Skip to content

fix(docs): convert a config-example link whose text holds a bracketed span - #3731

Merged
max-sixty merged 2 commits into
mainfrom
nightly/clean-30886678884
Aug 5, 2026
Merged

max-sixty merged 2 commits into
mainfrom
nightly/clean-30886678884

Conversation

@worktrunk-bot

@worktrunk-bot worktrunk-bot commented Aug 4, 2026 •

Copy link
Copy Markdown
Collaborator

wt config create --project writes a comment into the user's .config/wt.toml — and wt config create --help prints the same text — carrying a raw, unresolvable Zola link:

# When many repositories share one self-hosted host, name it once in user config with a [pattern-keyed `[projects]` entry](@/config.md#user-project-specific-settings) instead of repeating this block in each repo.

Every other cross-reference in that file is a plain URL (… see \wt hook` (https://worktrunk.dev/hook/) …), because transform_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 why skills/worktrunk/reference/config.md renders this very sentence with a resolved URL while the TOML example didn't. convert_markdown_links_for_config now 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:

# When many repositories share one self-hosted host, name it once in user config with a pattern-keyed `[projects]` entry (https://worktrunk.dev/config/#user-project-specific-settings) instead of repeating this block in each repo.

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_content already handled that risk with a guardrail — after the rewrite it scans for a stray ](@/…md and 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_toml had no equivalent, which is why this one reached dev/wt.example.toml and the --help output. That check is now extracted into assert_no_untransformed_zola_links and called from both surfaces, so the next unsupported shape is a test failure naming the line rather than a raw @/config.md target in a user's config file.

Why nothing caught it

test_project_config_source_generates_example_toml compares dev/wt.example.toml against 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_text asserts the transform's output directly. It fails on main'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_transform covers 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, as wt config create --help renders it.

Ran locally on the final state: readme_sync:: (15), test_help (47), cargo clippy --tests --all-features, and cargo 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.

@worktrunk-bot worktrunk-bot added the nightly-cleanup Issues found by nightly code quality sweep label Aug 4, 2026

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.

Comment thread tests/integration_tests/readme_sync.rs Resolved
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.
@worktrunk-bot

Copy link
Copy Markdown
Collaborator Author

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 dev/wt.example.toml in the first place. Rather than a second copy of the check, I extracted finalize_skill_content's into assert_no_untransformed_zola_links(content, surface) and called it from both — transform_config_source_to_toml now asserts on its joined output, so both generated example files are covered, and the panic names the surface along with the offending line.

test_untransformed_zola_link_fails_the_config_transform exercises the backstop directly: an unbalanced backtick in link text makes the rewrite decline, which is exactly the class of input neither the widened regex nor the case table can anticipate.

Locally green on the final state: readme_sync:: (15), test_help (47), cargo clippy --tests --all-features, cargo fmt --check. PR description updated to match the approach.

max-sixty pushed a commit that referenced this pull request Aug 5, 2026
…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>
@max-sixty
max-sixty merged commit 2203c41 into main Aug 5, 2026
40 checks passed
@max-sixty
max-sixty deleted the nightly/clean-30886678884 branch August 5, 2026 17:15
social4hyq pushed a commit to social4hyq/homebrew-core that referenced this pull request Sep 20, 2026
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

This branch was previously deployed

1 inactive deployment
tend — d5441cdc Deployed Aug 4, 2026 by worktrunk-bot via review #3698
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

nightly-cleanup Issues found by nightly code quality sweep

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants