Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

refactor(docs): drop mirrored help-page close; align convert_console_blocks_in_docs error channel (#2422)

Maximilian Roos4cbc8ca5fd73
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 33c459755..83962ec08 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -105,10 +105,10 @@ group = "Commands"
[generated content here]
-<!-- END AUTO-GENERATED from `wt list --help-page` -->
+<!-- END AUTO-GENERATED -->
```
-The END tag mirrors the source ID, enabling precise matching even with nested snapshot markers inside.
+The bare close marker is paired with the open via non-greedy regex matching. `test_no_nested_auto_generated_markers` enforces that no `AUTO-GENERATED` open ever appears inside a region in `docs/content/*.md`, which is the precondition for non-greedy pairing to be safe.
The frontmatter (title, weight, group) is preserved in each file. Everything between the START and END markers is generated by:
@@ -311,12 +311,12 @@ All AUTO-GENERATED markers use a consistent format with START and END tags:
<!-- END AUTO-GENERATED -->
```
-For regions that may contain nested markers (like command pages with embedded snapshots), the END tag mirrors the source ID:
-```html
-<!-- END AUTO-GENERATED from `wt list --help-page` -->
-```
-
-This enables precise matching of the outer region.
+All `AUTO-GENERATED` regions use the bare close — sync test
+`test_no_nested_auto_generated_markers` enforces that no region ever nests
+inside another in `docs/content/*.md`, which is the precondition for the
+outer-region regex to safely pair the open with the close via non-greedy
+matching. If you ever need nested regions, restore a disambiguating close
+form on the outer marker rather than relying on the regex.
## Template examples in documentation
diff --git a/docs/content/config.md b/docs/content/config.md
index 04b93f4df..e171ecfe4 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -1100,4 +1100,4 @@ Usage: <b><span class=c>wt config state vars</span></b> <span class=c>[OPTIONS]<
Skip approval prompts
{% end %}
-<!-- END AUTO-GENERATED from `wt config --help-page` -->
+<!-- END AUTO-GENERATED -->
diff --git a/docs/content/hook.md b/docs/content/hook.md
index f5a040747..9f15be1c0 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -336,4 +336,4 @@ Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span
Skip approval prompts
{% end %}
-<!-- END AUTO-GENERATED from `wt hook --help-page` -->
+<!-- END AUTO-GENERATED -->
diff --git a/docs/content/list.md b/docs/content/list.md
index 5fd8f0fcc..c218d3775 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -311,4 +311,4 @@ Usage: <b><span class=c>wt list</span></b> <span class=c>[OPTIONS]</span>
Skip approval prompts
{% end %}
-<!-- END AUTO-GENERATED from `wt list --help-page` -->
+<!-- END AUTO-GENERATED -->
diff --git a/docs/content/merge.md b/docs/content/merge.md
index cab80e297..39a98f694 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -165,4 +165,4 @@ Usage: <b><span class=c>wt merge</span></b> <span class=c>[OPTIONS]</span> <span
Skip approval prompts
{% end %}
-<!-- END AUTO-GENERATED from `wt merge --help-page` -->
+<!-- END AUTO-GENERATED -->
diff --git a/docs/content/remove.md b/docs/content/remove.md
index f8727e8dc..83e50010b 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -146,4 +146,4 @@ Usage: <b><span class=c>wt remove</span></b> <span class=c>[OPTIONS]</span> <spa
Skip approval prompts
{% end %}
-<!-- END AUTO-GENERATED from `wt remove --help-page` -->
+<!-- END AUTO-GENERATED -->
diff --git a/docs/content/step.md b/docs/content/step.md
index 216045b44..7100ba7fc 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -847,4 +847,4 @@ Usage: <b><span class=c>wt step relocate</span></b> <span class=c>[OPTIONS]</spa
Skip approval prompts
{% end %}
-<!-- END AUTO-GENERATED from `wt step --help-page` -->
+<!-- END AUTO-GENERATED -->
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 54b5a37c2..26acd468b 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -224,4 +224,4 @@ Usage: <b><span class=c>wt switch</span></b> <span class=c>[OPTIONS]</span> <spa
Skip approval prompts
{% end %}
-<!-- END AUTO-GENERATED from `wt switch --help-page` -->
+<!-- END AUTO-GENERATED -->
diff --git a/src/docs.rs b/src/docs.rs
index 7bb470452..927e6adb3 100644
--- a/src/docs.rs
+++ b/src/docs.rs
@@ -31,10 +31,10 @@ pub const DEMO_MARKER_PREFIX: &str = "<!-- demo: ";
/// can't drift between sides.
pub const MARKER_OPEN_PREFIX: &str = "<!-- ⚠️ AUTO-GENERATED from ";
-/// Standard close marker for an auto-generated region. The help-page emitter
-/// uses a mirrored variant (`<!-- END AUTO-GENERATED from <id> -->`) so two
-/// adjacent regions can be parsed without ambiguity; everything else uses
-/// this bare form.
+/// Close marker for an auto-generated region. Paired with `MARKER_OPEN_PREFIX`
+/// via non-greedy regex matching; the sync test
+/// `test_no_nested_auto_generated_markers` enforces the no-nesting precondition
+/// that makes that pairing safe.
pub const MARKER_CLOSE: &str = "<!-- END AUTO-GENERATED -->";
/// Convert `$ `‐prefixed console blocks into `{% terminal() %}` shortcodes.
diff --git a/src/help.rs b/src/help.rs
index 578a85131..2a3388788 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -51,8 +51,8 @@ use ansi_str::AnsiStr;
use clap::ColorChoice;
use clap::error::ErrorKind;
use worktrunk::docs::{
- BADGE_EXPERIMENTAL_HTML, DEMO_MARKER_PREFIX, MARKER_OPEN_PREFIX, SUBDOC_MARKER_PREFIX,
- convert_dollar_console_to_terminal,
+ BADGE_EXPERIMENTAL_HTML, DEMO_MARKER_PREFIX, MARKER_CLOSE, MARKER_OPEN_PREFIX,
+ SUBDOC_MARKER_PREFIX, convert_dollar_console_to_terminal,
};
use worktrunk::styling::{eprintln, println};
@@ -129,13 +129,11 @@ impl PageMode {
std::println!();
}
- /// Emit the closing END marker (web only). Mirrors the open id so the sync
- /// test can disambiguate from inner snapshot-marker closes nested inside
- /// the help-page region.
- fn emit_footer(self, subcommand: &str) {
+ /// Emit the closing END marker (web only).
+ fn emit_footer(self) {
if matches!(self, Self::Web) {
std::println!();
- std::println!("<!-- END AUTO-GENERATED from `wt {subcommand} --help-page` -->");
+ std::println!("{MARKER_CLOSE}");
}
}
}
@@ -524,7 +522,7 @@ Commands with pages: merge, switch, remove, list"
std::println!("{}", subdocs_expanded.trim());
}
- mode.emit_footer(subcommand);
+ mode.emit_footer();
}
/// Post-process CLI help content for web docs rendering.
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 8c0ba184a..0b40dece9 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -1814,15 +1814,16 @@ fn sync_command_pages(project_root: &Path) -> (Vec<String>, Vec<String>) {
current.clone()
};
- // Find the help-page marker region. The mirrored close
- // (`<!-- END AUTO-GENERATED from <id> -->`) is required because the
- // help-page body can contain inner snapshot markers (which use the
- // bare `MARKER_CLOSE`); a bare close on the outer region would let
- // the regex stop at the first inner close.
+ // Find the help-page marker region. Non-greedy `.*?` pairs the open
+ // with the nearest `MARKER_CLOSE`. Inner `AUTO-GENERATED` markers are
+ // not emitted by any sync step (verified via test that ensures no
+ // nesting in command pages); if that ever changes, a tempered match
+ // would be needed instead of bare non-greedy.
let id_re = regex::escape(&format!("`wt {cmd} --help-page`"));
let marker_pattern = Regex::new(&format!(
- r"(?s){open}{id_re}[^>]*-->.*?<!-- END AUTO-GENERATED from {id_re} -->",
+ r"(?s){open}{id_re}[^>]*-->.*?{close}",
open = regex::escape(MARKER_OPEN_PREFIX),
+ close = regex::escape(MARKER_CLOSE),
))
.unwrap();
@@ -1881,10 +1882,14 @@ static ZOLA_EXPERIMENTAL_SHORTCODE: LazyLock<Regex> =
LazyLock::new(|| Regex::new(r"\{\{\s*experimental\(\)\s*\}\}").unwrap());
/// Regex to strip AUTO-GENERATED marker comments (just the comments, not content).
-/// Matches both the open prefixes (with ⚠️) and the close form (with or without
-/// the help-page mirrored suffix).
+/// Matches the open prefix (with ⚠️) and the bare close form.
static AUTO_GENERATED_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
- Regex::new(r"<!-- ⚠️ AUTO-GENERATED[^>]*-->\n*|<!-- END AUTO-GENERATED[^>]*-->\n*").unwrap()
+ Regex::new(&format!(
+ r"{open}[^>]*-->\n*|{close}\n*",
+ open = regex::escape(MARKER_OPEN_PREFIX),
+ close = regex::escape(MARKER_CLOSE),
+ ))
+ .unwrap()
});
/// Regex to strip HTML figure/picture elements (demo GIFs)
@@ -2042,29 +2047,50 @@ fn remove_section(content: &str, heading: &str) -> String {
/// Command pages already have this conversion via --help-page, but hand-written
/// docs (faq.md, llm-commits.md, claude-code.md) can also use ```console with $
/// and get the same treatment.
-fn convert_console_blocks_in_docs(project_root: &Path) -> Vec<String> {
- let docs_dir = project_root.join("docs/content");
+fn convert_console_blocks_in_docs(project_root: &Path) -> (Vec<String>, Vec<String>) {
+ let mut errors = Vec::new();
let mut updated_files = Vec::new();
+ let docs_dir = project_root.join("docs/content");
- for entry in fs::read_dir(&docs_dir).unwrap() {
- let entry = entry.unwrap();
- let path = entry.path();
- if path.extension().is_some_and(|e| e == "md") {
- let content = fs::read_to_string(&path).unwrap();
- let converted = worktrunk::docs::convert_dollar_console_to_terminal(&content);
- if converted != content {
- let rel = path.strip_prefix(project_root).unwrap_or(&path);
- write_tracked(
- &path,
- &converted,
- rel.display().to_string(),
- &mut updated_files,
- );
+ let entries = match fs::read_dir(&docs_dir) {
+ Ok(e) => e,
+ Err(e) => {
+ errors.push(format!("read_dir {}: {e}", docs_dir.display()));
+ return (errors, updated_files);
+ }
+ };
+
+ for entry in entries {
+ let path = match entry {
+ Ok(e) => e.path(),
+ Err(e) => {
+ errors.push(format!("dir entry in {}: {e}", docs_dir.display()));
+ continue;
}
+ };
+ if path.extension().is_none_or(|e| e != "md") {
+ continue;
+ }
+ let content = match fs::read_to_string(&path) {
+ Ok(c) => c,
+ Err(e) => {
+ errors.push(format!("read {}: {e}", path.display()));
+ continue;
+ }
+ };
+ let converted = worktrunk::docs::convert_dollar_console_to_terminal(&content);
+ if converted != content {
+ let rel = path.strip_prefix(project_root).unwrap_or(&path);
+ write_tracked(
+ &path,
+ &converted,
+ rel.display().to_string(),
+ &mut updated_files,
+ );
}
}
- updated_files
+ (errors, updated_files)
}
/// Sorted `.md` page filenames in `docs/content/` (excluding `_index.md`
@@ -2572,8 +2598,8 @@ fn test_docs_are_in_sync() {
// Step 1b: Convert $ console blocks to terminal shortcodes in ALL docs
// (command pages already converted via --help-page; this catches hand-written docs)
- let console_files = convert_console_blocks_in_docs(project_root);
- tag("console→terminal", Vec::new(), console_files);
+ let (console_errors, console_files) = convert_console_blocks_in_docs(project_root);
+ tag("console→terminal", console_errors, console_files);
// Step 2: Sync standalone docs files (snapshots → docs/content/*.md).
// README extraction in step 5 reads these, so they must be current first.
@@ -2642,6 +2668,45 @@ fn test_docs_are_in_sync() {
}
}
+/// `AUTO-GENERATED` markers must not nest. The help-page region's close uses
+/// the bare `MARKER_CLOSE`, paired with the open via non-greedy `.*?` — a
+/// nested inner close would cause the regex to chop the region short, leaving
+/// stale content beyond the inner close. This test catches re-introduction of
+/// nesting before that subtle failure mode lands.
+#[test]
+fn test_no_nested_auto_generated_markers() {
+ let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
+ let mut violations = Vec::new();
+ for entry in fs::read_dir(project_root.join("docs/content")).unwrap() {
+ let path = entry.unwrap().path();
+ if path.extension().is_some_and(|e| e == "md") {
+ let content = fs::read_to_string(&path).unwrap();
+ let mut depth = 0;
+ for (i, line) in content.lines().enumerate() {
+ if line.contains(MARKER_OPEN_PREFIX) {
+ depth += 1;
+ if depth > 1 {
+ violations.push(format!(
+ "{}:{}: nested AUTO-GENERATED open (depth {depth})",
+ path.display(),
+ i + 1
+ ));
+ }
+ } else if line.contains(MARKER_CLOSE) && depth > 0 {
+ depth -= 1;
+ }
+ }
+ }
+ }
+ assert!(
+ violations.is_empty(),
+ "Nested AUTO-GENERATED markers found — outer help-page regex would chop \
+ the region at the inner close. Either flatten the nesting or restore a \
+ disambiguating close marker.\n\n{}",
+ violations.join("\n")
+ );
+}
+
/// The hand-authored `## Template variables` table in `src/cli/mod.rs` must
/// match the variable constants in `src/config/expansion.rs`. Drift means the
/// help docs lie about which vars hooks and aliases can reference.