Repository navigation
fix(docs): convert a config-example link whose text holds a bracketed span - #3731
Conversation
worktrunk-bot
left a comment
There was a problem hiding this comment.
Two follow-ons, both about the class rather than this instance.
The widened class still misses the double-bracket shape. (?:[^\[\]]|\[[^\[\]]*\])+ requires the inner span to be a single bracket pair, so a link whose text names an array-of-tables — e.g. [`[[projects."…".post-start]]` hooks](@/config.md#hooks), and that block is already in this config surface (dev/config.example.toml, the post-start example) — falls back to exactly the unconverted-markdown outcome this PR fixes. ZOLA_LINK_PATTERN earlier in this file solves the same problem the other way, alternating a backticked code span with any non-]-non-backtick char; that's why skills/worktrunk/reference/config.md already renders this very sentence with a resolved URL while the TOML example didn't. Swapping in that class keeps all six new cases behaving identically (including the bare `[forge]` non-link), covers [[…]], and leaves this file with one rule for "how link text may contain ]" instead of two. Inline suggestion below.
A shape the regex declines still fails silently. The PR body's own point — the sync test compares the example against this same transform, so an unconverted link is "in sync" by construction — is unchanged by the new unit test, which pins the shapes we already know about. finalize_skill_content handles the identical risk with a guardrail: after the rewrite it scans for a stray ](@/…md (UNTRANSFORMED_ZOLA_LINK_PATTERN) and panics with the offending line, precisely because "the regex failed to match on an unexpected character in the link text" is the expected failure mode. transform_config_source_to_toml has no equivalent, which is why this one reached dev/wt.example.toml and the --help output. The same check at the end of that function would cover both generated example files and turn the next unsupported shape into a loud test failure rather than a raw @/config.md target in the user's config file.
Happy to push both (regex + docstring, and the guardrail) if you'd rather have them here than in a follow-up.
Adopt ZOLA_LINK_PATTERN's link-text class in convert_markdown_links_for_config, so this file carries one rule for how link text may contain `]` instead of two. The class alternates a backticked code span with any non-`]`-non-backtick char, which also covers the `[[…]]` array-of-tables shape the one-level-of-nesting class declined — these sections already document `[[projects."…".post-start]]` pipelines, so a link naming one is the next form to arrive. Add the guardrail finalize_skill_content already had: after the rewrite, assert no `](@/…md` survives. A regex that declines to match fails silently, and neither sync test can see it — each compares the generated file against the same transform that produced it. Extract the existing check into assert_no_untransformed_zola_links and call it from both surfaces, so an unsupported shape becomes a test failure naming the line rather than a raw `@/config.md` target in the user's config file.
|
Pushed both in d5441cd. The guardrail. Agreed that the new unit test only pins the shapes we already know about, and that the silent-decline failure mode is what let this reach
Locally green on the final state: |
…innable (#3736) Daily `review-runs` sweep of the 2026-08-03/04 window. One maintainer correction in the window is generalizable repo knowledge, so it gets codified here. ## What happened Triaging [#3696](#3696) ("Allow selecting the `wt list` JSON schema on the command line"), the bot read [`resolve_json_schema`](https://github.com/max-sixty/worktrunk/blob/286004f1ebe5f6563c772be24987394144a29215/src/commands/list/mod.rs#L220), saw it reads `repo.config().list.json_schema`, and [posted](#3696 (comment)) that "there's no way to pin it per-invocation independent of that config" — then went further and said the usual alias deflection "can't substitute, since there's no composable way to select the schema without this flag existing first". max-sixty [corrected it](#3696 (comment)): "the need is real, but it's already met, so I'm not going to add the flag" — `wt --config-set 'list.json-schema = 2' list --format=json` pins it per invocation, and `WORKTRUNK_LIST__JSON_SCHEMA` does the same a layer down. The proposed `--schema` flag was declined as "a third spelling of the same thing on a surface I deliberately keep small". The issue was closed on that basis. `--config-set` has been documented since [#3138](#3138) (2026-06-19), in `after_long_help` in [`src/cli/mod.rs`](https://github.com/max-sixty/worktrunk/blob/286004f1ebe5f6563c772be24987394144a29215/src/cli/mod.rs#L2558) and its rendered mirror. It was available to read; the triage just never looked above the resolver. ## Why codify it rather than log it The specific miss is what the gates would call a single occurrence, but the shape isn't a behavioural nudge that risks noise elsewhere — it's a factual property of worktrunk's config layering, and the failure mode it prevents is a **publicly posted false capability claim**, which is the class `running-in-ci` treats as the most corrosive output failure. It's also invisible: nothing fails, the reply just reads as authoritative and wrong until a maintainer happens to catch it. It sits directly above **Suggesting Aliases for Niche Feature Requests** because it serves the same flag-growth limit that section already encodes, and is the cheaper answer when the ask is "select an existing config value per invocation" — the alias deflection is the fallback when it isn't. <details><summary>Window summary</summary> 46 token-bearing runs, **0 failed**, 0 near-timeout (longest job 68 min against the 360-min cap). 3 bot PRs opened ([#3731](#3731), [#3732](#3732), [#3734](#3734)), 2 merged ([#3722](#3722), [#3726](#3726)), 0 closed without merge. [#3721](#3721) — the PR stranded by the 08-03 outage — was reviewed and approved, confirming yesterday's recovery worked. Full evidence in the tracking issue [#3691](#3691). </details> --------- Co-authored-by: worktrunk-bot <254187624+worktrunk-bot@users.noreply.github.com>
worktrunk 0.72.0 Created-by: HarmonybrewBot Commit-by: HarmonybrewBot Merged-by: HarmonybrewBot Description: Created by `brew bump` --- Created with `brew bump-formula-pr`.<details> <summary>release notes</summary> <pre>## Release Notes ### Improved - **A host carrying a forge's name anywhere resolves to that forge again**: 0.71.0 required `github`, `gitlab`, or `gitea` as a whole dot-separated label, which read as an ownership check but wasn't one — an attacker controls their own DNS — while shutting out self-hosters with hyphenated names. `github-enterprise.acme.com`, `myhub.lumenfield.work`, and the `github-personal` SSH alias classify again, so CI status, `wt switch --prs`, and `repo.provider` work with no config. ([#3673](max-sixty/worktrunk#3673)) - **One `[projects."…"]` entry can cover every repository on a host, and can set the forge**: A key containing `*` matches any run of characters, `/` included, so `[projects."git.company.example/*"]` covers a whole host; every matching entry applies, least- to most-specific. The table also gained `forge.platform` and `forge.hostname`, so a self-hosted host needs one entry here rather than a block in every repo. [Docs](https://worktrunk.dev/config/#user-project-specific-settings) ([#3701](max-sixty/worktrunk#3701), thanks @chrishas35 for the request and @witt-bit for the workspace-scoped case it partly serves) - **`wt merge` and `wt step push` leave the target worktree's uncommitted changes in place**: The autostash that held a dirty target's changes restored them as unstaged; both now advance the target with a compare-and-swap `update-ref` and `read-tree -m -u`, which leaves uncommitted work untouched. (Breaking: the fast-forward path no longer runs `git push`, so `pre-push` and the receive-side hooks no longer fire, and a failed sync errors with the ref rolled back.) ([#3703](max-sixty/worktrunk#3703), [#3684](max-sixty/worktrunk#3684), [#3693](max-sixty/worktrunk#3693), thanks @gubasso for reporting) - **Approval state and branch-removal outcomes are machine-readable**: `wt config approvals list --format=json` reports whether a non-interactive run would stop for approval. `wt remove` and `wt step prune` replace `branch_deleted` with `branch_outcome`: `deleted`, `deferred`, `not_attempted`, `retained_unmerged`, `retained_checked_out`, `retained_raced`, `retained_failed`. (Breaking.) ([#3710](max-sixty/worktrunk#3710), thanks @NathanaelRea for the requests) - **Every commit hash worktrunk prints follows `core.abbrev`**: The `wt list` table, `wt switch --prs`'s `log` tab, and `wt config state`'s CI cache table sliced to 8 characters while `--format=json` carried git's `%h`. All now ask git how wide it abbreviates in this repo. ([#3676](max-sixty/worktrunk#3676), [#3677](max-sixty/worktrunk#3677)) - **`wt list --format=json` schema 2 has a published JSON Schema**: [worktrunk.dev/schema/list-v2.json](https://worktrunk.dev/schema/list-v2.json) holds the contract, and `wt list --print-schema` prints the same document. Four fields that were bare strings are now enumerated vocabularies; the emitted JSON is unchanged. ([#3747](max-sixty/worktrunk#3747)) - **A detached worktree is named by its commit, not `-`**: The Branch cell hardcoded `-`, which reads as missing data rather than a state; it now carries the row's abbreviated HEAD, and the picker and statusline name the worktree the same way. ([#3675](max-sixty/worktrunk#3675)) ### Fixed - **Piped output is plain and no longer panics**: `wt list | head -3` exited 101 with `failed printing to stdout: Broken pipe`, and `wt list` wrote ANSI to a pipe unconditionally. Every stdout surface now exits cleanly, and the human-read ones are plain when piped unless `CLICOLOR_FORCE=1`. ([#3746](max-sixty/worktrunk#3746), [#3766](max-sixty/worktrunk#3766)) - **A CI check that hasn't finished no longer reads as passed**: Each forge's status parser missed documented values, so a GitHub PR parked on an approval gate showed green, and GitLab's `canceling` and Azure DevOps's `postponed` read as no CI at all. ([#3741](max-sixty/worktrunk#3741), [#3740](max-sixty/worktrunk#3740)) - **The shell wrappers survive an `rm` alias and a failing `--execute`**: Aliases bake into the wrapper at parse time, so `alias rm='rm -v'` reached its cleanup — noise on zsh and bash, and on nushell an abort that leaked three temp files, as a failing `--execute` body also did. ([#3714](max-sixty/worktrunk#3714), thanks @Ar4l), ([#3732](max-sixty/worktrunk#3732), [#3734](max-sixty/worktrunk#3734)) - **An alias or hook wrapping `wt switch` or `wt remove` keeps your subdirectory**: The user's position came from the `wt` process's cwd, which inside an alias body is the worktree root, so an aliased `wt remove` from `feature/apps/gateway` landed at the primary worktree's root. Fixes [#3723](max-sixty/worktrunk#3723). ([#3724](max-sixty/worktrunk#3724), thanks @vivienm for reporting) - **`wt merge` and `wt step push` refuse a target worktree parked mid-operation**: The two-tree sync refuses an unmerged index but not a stopped cherry-pick or rebase whose conflict was already staged, so the push range could land in a paused target and be committed by `--continue`. ([#3759](max-sixty/worktrunk#3759)) - **The Claude plugin's worktree-remove hook resolves against the worktree path**: The hook anchored at `CLAUDE_PROJECT_DIR`, which the `claude agents` view routinely leaves outside any repository, so `wt remove` died with `not a git repository` and the session became undeletable. Its guard now also requires a `.git` entry. ([#3754](max-sixty/worktrunk#3754), [#3767](max-sixty/worktrunk#3767), thanks @judewang for the fix and the report) - **A Gitea API error is reported as one, not as a parse failure**: `tea api` exits 0 whatever the HTTP status, so both call sites guessed from the body's shape and blamed an API change for an API error. `--include` surfaces the status instead. ([#3713](max-sixty/worktrunk#3713), [#3600](max-sixty/worktrunk#3600)) - **`--print-schema` and the doc-generation help flags name the right command**: All three found the subcommand by scanning `argv` for a `/wt` suffix, which never matches `wt.exe` under a backslash path, so on Windows they read the binary's own path as the command. ([#3762](max-sixty/worktrunk#3762)) - **A multibyte shell name no longer panics**: `extract_filename_from_path` sliced at `len() - 4` to test for `.exe` with no char-boundary check: `SHELL=/bin/日本語 wt config show` panicked, and on macOS every process name goes through it during shell detection. ([#3727](max-sixty/worktrunk#3727)) - **`wt` installed under a dotted name generates shell integration for that name**: `binary_name` used `file_stem`, which cuts at the last dot, so `wt config shell init bash` under `wt.old` emitted a wrapper for `wt`. It now strips only the executable suffix. ([#3719](max-sixty/worktrunk#3719)) - **Concurrent `wt step prune` removals no longer race the worktree registry**: `git worktree remove` reads every sibling under `.git/worktrees/`, so two overlapping removals could have one read a sibling mid-teardown. Registry-mutating removals now serialize behind a second lock. ([#3692](max-sixty/worktrunk#3692)) - **The `wt switch` first-run offer previews the legacy files it removes**: Accepting "Install shell integration?" could delete a deprecated worktrunk-managed wrapper the prompt never named. What gets removed is unchanged. ([#3656](max-sixty/worktrunk#3656)) - **`wt config create --project` writes a resolvable link**: The comment it writes into `.config/wt.toml` carried a raw Zola target, because the link-conversion regex stopped at the first `]` — here the one closing a nested code span. ([#3731](max-sixty/worktrunk#3731)) - **`wt list --branches` counts a local branch containing `/` as local**: The summary tally classified branch-only rows by `branch.contains('/')`, so a local `feature/login` counted under "N remote branches". ([#3687](max-sixty/worktrunk#3687)) - **`wt step relocate`'s human summary counts template-error branches as skipped**: `--format=json` already folded them into `skipped`; the human tally undercounted by the number of branches whose `worktree-path` template failed to expand. ([#3688](max-sixty/worktrunk#3688)) ### Documentation - **SignPath attribution appears with the artifacts it describes**: The code-signing notice and a route to the policy now sit in the install section's Windows block on the README and the docs landing page, as SignPath Foundation's OSS program requires. ([#3709](max-sixty/worktrunk#3709)) - **`wt step copy-ignored`'s `--require-include` example renders as a terminal block**: It was the only `console` block in the command's long help missing the `$ ` prefix. ([#3706](max-sixty/worktrunk#3706)) ### Internal - **Library API rework** (Breaking library API): `cargo-semver-checks` fails five lints — `LegacyForgeAlias` and `Repository::legacy_forge_alias` removed with the forge-classification revert, `Repository::forge_platform_override` removed for one shared resolver, `stage_worktree_removal` gained two parameters, `UserProjectOverrides` gained a `forge` field, and the `real-repo-benches` feature was removed. ([#3673](max-sixty/worktrunk#3673), [#3694](htt See merge request: Harmonybrew/homebrew-core!16275
wt config create --projectwrites a comment into the user's.config/wt.toml— andwt config create --helpprints the same text — carrying a raw, unresolvable Zola link:Every other cross-reference in that file is a plain URL (
… see \wt hook` (https://worktrunk.dev/hook/) …), becausetransform_config_source_to_tomlconverts theafter_long_helpmarkdown to plain text on the way intodev/wt.example.toml. This one link isn't converted:convert_markdown_links_for_configmatched link text with[^]]+, which stops at the first]— here the one closing the nested ``[projects]` `` span — so the regex failed to match and the markdown survived verbatim. The line arrived with #3701; it's the only link in either generated example file with a bracketed span in its text.The fix
One rule for
]in link text.ZOLA_LINK_PATTERN, earlier in the same file, already solves this problem for the skill mirrors — it alternates a backticked code span with any non-]-non-backtick char, which is whyskills/worktrunk/reference/config.mdrenders this very sentence with a resolved URL while the TOML example didn't.convert_markdown_links_for_confignow uses that same class rather than a second, weaker one. Brackets in these link texts always sit inside a code span, so the class fits the shape exactly, and it covers[[…]]array-of-tables names as well — these sections already document[[projects."…".post-start]]pipelines, so a link naming one is the next form to arrive. Regenerating produces the intended form:A shape the regex declines now fails loudly. Widening the class fixes the shapes we know about; it can't fix the next one.
finalize_skill_contentalready handled that risk with a guardrail — after the rewrite it scans for a stray](@/…mdand panics with the offending line, precisely because "the regex declined on an unexpected character in the link text" is the expected failure mode.transform_config_source_to_tomlhad no equivalent, which is why this one reacheddev/wt.example.tomland the--helpoutput. That check is now extracted intoassert_no_untransformed_zola_linksand called from both surfaces, so the next unsupported shape is a test failure naming the line rather than a raw@/config.mdtarget in a user's config file.Why nothing caught it
test_project_config_source_generates_example_tomlcomparesdev/wt.example.tomlagainst the output of this same transform, so an unconverted link is "in sync" by construction — the sync test can't see the difference between a link that converted and one the regex declined to match. Two tests close that gap:test_config_markdown_links_convert_to_plain_textasserts the transform's output directly. It fails onmain's regex with exactly the reported symptom, and pins the forms already working (Zola page, Zola page + anchor, absolute URL, two links on one line, the[[…]]array-of-tables name) plus the case that must not convert — a bare`[forge]`span is not a link and has to survive verbatim.test_untransformed_zola_link_fails_the_config_transformcovers the backstop itself: an unbalanced backtick in link text makes the rewrite decline, and the assertion turns that into a panic naming the line.Files
tests/integration_tests/readme_sync.rs— the shared link-text class, the guardrail extraction and its second call site, and both tests.dev/wt.example.toml— regenerated by the sync test (one line).tests/snapshots/…help_config_create.snap— the same line, aswt config create --helprenders it.Ran locally on the final state:
readme_sync::(15),test_help(47),cargo clippy --tests --all-features, andcargo fmt --check. All green; the generated files are byte-identical under the new class, so the sync tests pass without regenerating. The full gate runs in CI.