Skip to content

chore(tests): factor write_tracked helper; mark generated files#2409

Merged
max-sixty merged 2 commits intomainfrom
llm-docs
Apr 24, 2026
Merged

chore(tests): factor write_tracked helper; mark generated files#2409
max-sixty merged 2 commits intomainfrom
llm-docs

Conversation

@max-sixty
Copy link
Copy Markdown
Owner

@max-sixty max-sixty commented Apr 24, 2026

Summary

Three small cleanups to the docs/skills sync pipeline (flagged by /simplify review on #2404 but deferred at the time):

  • readme_sync.rs — extract a write_tracked(path, expected, rel_path, updated) helper that handles fs::create_dir_all + fs::write + push-to-updated_files. Applied at five call sites: sync_command_pages, convert_console_blocks_in_docs, sync_skill_files, sync_well_known_skills, sync_llms_txt. Callers keep control of the "is it different?" check so each site can apply its own normalization (e.g., trim_lines) before comparing.

  • sync_llms_txt — merge the two parse/group loops. Use let-else to pull out extra.group when the frontmatter is first parsed, then push directly into the BTreeMap. Drops both the intermediate Vec<(String, Frontmatter)> and an unreachable .expect("non-home pages must declare [extra] group") that only existed because the group was looked up twice.

  • .gitattributes — new file. Marks the 14 auto-generated outputs as linguist-generated=true so GitHub collapses them in PR diffs. Targets skills/worktrunk/reference/*.md, docs/static/*.md (the .md symlinks), docs/static/llms.txt, and docs/static/.well-known/agent-skills/index.json. Primary sources (docs/content/*.md, src/cli/mod.rs) stay fully visible — git check-attr confirms.

No behavior change; all 13 readme_sync tests pass, cargo clippy --all-targets --all-features -- -D warnings clean, cargo fmt clean.

Test plan

  • cargo test --test integration readme_sync — 13 passed
  • cargo clippy --all-targets --all-features -- -D warnings — clean
  • cargo fmt --check — clean
  • git check-attr linguist-generated on a sample of generated + primary-source files — generated flip to true, primary sources stay unspecified

This was written by Claude Code on behalf of @max-sixty

@max-sixty @claude
chore(tests): factor write_tracked helper; mark generated files
9196551 
Three cleanups to the docs/skills sync pipeline (flagged by /simplify):

- readme_sync.rs: extract `write_tracked` helper, applied at 5 sites
  that were repeating the `fs::create_dir_all` + `fs::write` + push-to-
  `updated_files` pattern.
- sync_llms_txt: merge the parse and group loops so pages land directly
  in the `BTreeMap`. Drops the intermediate `Vec<(String, Frontmatter)>`
  and its unreachable `.expect("non-home pages must declare [extra]
  group")`.
- .gitattributes: mark the 14 auto-generated files
  (skills/worktrunk/reference/*.md, docs/static/*.md symlinks,
  docs/static/llms.txt, agent-skills index.json) as linguist-generated
  so GitHub collapses the mirrored diffs in PR reviews.

Co-Authored-By: Claude <noreply@anthropic.com>
worktrunk-bot
worktrunk-bot reviewed Apr 24, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator

@worktrunk-bot worktrunk-bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One concern on the .gitattributes rule — flagged inline.

Comment thread .gitattributes
# `test_command_pages_and_skill_files_are_in_sync` in
# tests/integration_tests/readme_sync.rs — edits belong in the primary source
# (src/cli/mod.rs for command pages, docs/content/*.md for everything else).
skills/worktrunk/reference/*.md linguist-generated=true
Copy link
Copy Markdown
Collaborator

@worktrunk-bot worktrunk-bot Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

skills/worktrunk/reference/*.md also matches three primary-source files that are edited directly: shell-integration.md, troubleshooting.md, and the README.md symlink (per the three-category split in CLAUDE.md — skill-only files have no docs/content/ equivalent). Marking them linguist-generated=true will collapse their diffs on GitHub, which hides real edits (e.g. #2194 adding the wt list fsmonitor hang section to troubleshooting.md).

Suggested change
skills/worktrunk/reference/*.md linguist-generated=true
skills/worktrunk/reference/*.md linguist-generated=true
skills/worktrunk/reference/README.md linguist-generated=false
skills/worktrunk/reference/shell-integration.md linguist-generated=false
skills/worktrunk/reference/troubleshooting.md linguist-generated=false

Copy link
Copy Markdown
Collaborator

@worktrunk-bot worktrunk-bot Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch — fixed in 88aec25. Added three linguist-generated=false overrides for README.md, shell-integration.md, and troubleshooting.md (matches CLAUDE.md's three-category split). git check-attr confirms the three primary-source files now return false while config.md/faq.md/etc. stay true.

@worktrunk-bot @claude
fix(gitattributes): exempt primary-source skill files from linguist-g…
88aec25 
…enerated

Why: the `skills/worktrunk/reference/*.md` glob over-matches. README.md is a
symlink to the top-level README and shell-integration.md / troubleshooting.md
are skill-only files edited directly (per CLAUDE.md's three-category split).
Marking them generated would collapse real edits in PR diffs.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@max-sixty max-sixty merged commit 8b4e53f into main Apr 24, 2026
26 checks passed
@max-sixty max-sixty deleted the llm-docs branch April 24, 2026 15:27
@max-sixty max-sixty mentioned this pull request Apr 24, 2026
Merged
5 tasks
max-sixty added a commit that referenced this pull request Apr 24, 2026
@worktrunk-bot @claude @max-sixty
docs(pages): add static command output to sections dominated by GIFs (#…
5f126d2 
…2405)

## Summary

Adds static command-output blocks to the docs pages dominated by GIFs
(addresses #2403). The blocks are **driven from insta snapshots** so
they stay in lockstep with what `wt` actually prints — one source flows
to all three surfaces:

- terminal `wt <cmd> --help` (plain text, gutter-formatted)
- `docs/content/*.md` (colorized `{% terminal(cmd="...") %}` shortcode)
- `skills/worktrunk/reference/*.md` (plain `$ cmd\noutput\n` block)

## What changed

- **Six scripted snapshot tests** produce realistic output (`cargo
nextest run`, `flyctl scale count 0`, LLM-generated commit messages):
  - `test_docs_merge_pre_merge_hook` — `wt merge` with pre-merge hook
  - `test_docs_step_commit_llm` — `wt step commit` with LLM
  - `test_docs_step_squash_llm` — three-commit squash with LLM
- `test_docs_merge_squash_llm` — `wt merge` (squash + LLM + merge) for
`llm-commits.md`
- `test_docs_remove_pre_remove_hook` — `wt remove` with pre-remove hook
  - `test_docs_hook_pre_merge` — `wt hook pre-merge` direct invocation

- **Sync pipeline extension** in
`tests/integration_tests/readme_sync.rs`:
- New write-back pass `sync_cli_mod_example_bodies` fills the
```console``` body in each `<!-- wt <cmd> (docs-example) -->`
placeholder in `src/cli/mod.rs` from the registered snapshot. Runs
before `--help-page` reads the file.
- `COMMAND_PLACEHOLDER_PATTERN` extended to match three forms
(```bash```, `{{ terminal() }}` self-closing, `{% terminal %} body {%
end %}`). This **fixes a pre-existing bug** in `docs/content/list.md`
where the HTML-mode expansion was silently broken.
- Stripped trailing `|||` corruption that arises when blank lines in
snapshot bodies are interpreted as empty commands by
`convert_dollar_console_to_terminal`.

- **Docs page migration**:
- `src/cli/mod.rs` — replaced four hand-written ```console``` blocks
(merge, step, remove, hook) with `<!-- wt <cmd> (docs-example) -->`
markers.
- `docs/content/llm-commits.md` — replaced three hand-crafted HTML
blocks with `<!-- ⚠️ AUTO-GENERATED-HTML from X.snap -->` markers.

- **Refactor follow-up** in a separate commit:
- `BADGE_EXPERIMENTAL_HTML`, `SUBDOC_MARKER_PREFIX`,
`DEMO_MARKER_PREFIX` hoisted to `worktrunk::docs` so producer and
consumer stay in lockstep.
- `normalize_clap_help_fences()` consolidates the `text→` +
`console→bash` replacement pair shared by `--help-md` and
`help_reference_inner`.

- **CLAUDE.md note** documenting the `.gitattributes`
`linguist-generated=false` exemption requirement when adding skill-only
files (carryover from #2409).

## Test plan

- [x] `cargo test --test integration readme_sync` — all 13 tests pass,
idempotent
- [x] `cargo test --test integration test_help` — help snapshots updated
- [x] `cargo run -- {merge,remove,step,hook} --help` — clean gutter
formatting, no visible HTML comments
- [x] `cargo run -- hook pre-merge --yes` — full project gate green
(3355 tests)
- [ ] Visual check on dev site (maintainer — terminal shortcodes now
render with colors via ANSI→HTML; dark/light variants both expected to
look like the GIFs they replace)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: worktrunk-bot <254187624+worktrunk-bot@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Maximilian Roos <m@maxroos.com>
@worktrunk-bot worktrunk-bot mentioned this pull request Apr 25, 2026
Open
@BrewTestBot BrewTestBot mentioned this pull request Apr 27, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@worktrunk-bot worktrunk-bot worktrunk-bot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@max-sixty @worktrunk-bot