From bdb025deaee1f0c3b37f949e7581cc9b97806025 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Tue, 6 Oct 2026 05:52:31 +0000 Subject: [PATCH 1/7] fix(xtask): harden arch-doc checker's possessive-owner narrowing extract_path_citations's possessive-owner narrowing only recognized exactly 's/slash/and as literal connector text between two Code spans, and fully reset all chain state on any intervening non-path backtick span (a type name). Real prose describing a multi-file split embeds exactly those things -- explanatory asides and free phrases like "was split into" -- so every citation after the first lost its narrowing, as happened when #456 merged into main while #432 was in review, breaking CI on both the architecture-doc gate and the Windows run_passes_against_the_real_doc test. Make the clause continue through any intervening text within the same sentence instead of requiring a literal connector before every citation; a sentence-ending period still hard-stops it unconditionally -- the guard against a later, unrelated sentence silently inheriting an earlier owner, which is the one masking risk this scoping feature exists to prevent. A naive "any period" check would misfire on a de-backticked filename's own extension dot (the de-backticked agent.rs sits inside the very clause it must not break), so sentence-ending is specifically a period followed by whitespace or end-of-text, not one glued to surrounding characters. Part of #492; the docs/architecture.md revert that proves this against the real doc is a separate commit later in this branch. Signed-off-by: Jussi Elo --- xtask/src/architecture_doc.rs | 161 ++++++++++++++++++++++++++++++++-- 1 file changed, 153 insertions(+), 8 deletions(-) diff --git a/xtask/src/architecture_doc.rs b/xtask/src/architecture_doc.rs index 75e7d51244..aa41c4f376 100644 --- a/xtask/src/architecture_doc.rs +++ b/xtask/src/architecture_doc.rs @@ -252,6 +252,54 @@ fn is_directory_shaped(span: &str) -> bool { is_directory_path || is_hyphenated_bare_word(span) } +/// Whether `inter_text` — the raw prose accumulated since a possessive +/// clause's owner was last confirmed — continues that clause rather than +/// ending it, for the continuation step (the initial `'s` owner-establishing +/// step is a separate, exact-match check and unaffected by this). +/// +/// A real split's prose connects its files with free English — "was split +/// into", "a mechanical relocation, since ..." — not just `/`/`and`/`,`, +/// and interleaves explanatory asides (type names, identifiers) between +/// them. Requiring a literal connector token directly before every citation +/// (the original, stricter design) rejects exactly this ordinary writing: a +/// doc edit this mundane should not need unusual phrasing just to keep CI +/// green. So the clause continues through *any* text, with one +/// unconditional exception: a sentence-ending `.` always ends it, no matter +/// what else is in `inter_text`. That's the safety net against the masking +/// risk the module doc warns about — without it, a later sentence naming an +/// unrelated file from a *different* crate in the same heading, with no new +/// possessive clause of its own, would silently inherit an earlier owner +/// instead of falling back to the heading's full (and correctly checked) +/// crate list. A single sentence is a safe enough unit to trust: shifting to +/// a different crate's file without starting a new clause or sentence would +/// be confusing prose on its own merits, not just a gap in this checker. +/// +/// A sentence-ending `.` means one followed by whitespace (or nothing, at +/// the end of `inter_text`) — not a bare `.` glued to surrounding +/// characters. This doc itself now de-backticks the removed `agent.rs` +/// filename right inside a clause this function must keep alive ("old +/// agent.rs was split into ..."); a naive "any `.`" check would wrongly +/// treat that file extension's dot as a sentence end. +fn continues_possessive_clause(inter_text: &str) -> bool { + !ends_with_a_sentence_boundary(inter_text) +} + +/// Whether `text` contains a period that ends a sentence, as opposed to one +/// embedded in ordinary prose (a filename like `agent.rs`, a version like +/// `v1.0`) — see [`continues_possessive_clause`] for why that distinction +/// matters here. A period counts as sentence-ending only when followed by +/// whitespace or nothing (the end of `text`); one directly glued to the next +/// character on both sides never does. +fn ends_with_a_sentence_boundary(text: &str) -> bool { + let bytes = text.as_bytes(); + bytes.iter().enumerate().any(|(i, &b)| { + b == b'.' + && bytes + .get(i + 1) + .is_none_or(|&next| next.is_ascii_whitespace()) + }) +} + /// Extract every backtick-quoted path citation from the doc's markdown /// source, paired with its section context. Powered by `pulldown-cmark`, /// which handles fenced code blocks (backtick and tilde), indented code @@ -266,9 +314,9 @@ fn is_directory_shaped(span: &str) -> bool { /// each independently make the same claim. A citation that instead names one /// specific crate from a multi-crate heading (`` `rocm-dash-tui`\'s /// `agent.rs` ``) is narrowed to just that crate via the possessive-connector -/// check: `'s` starts a possessive clause, `/` and `and` continue one. -/// Only `.rs` citations are narrowed this way; the logic lives inline in -/// the `Event::Code` arm below. +/// check: `'s` starts a possessive clause; [`continues_possessive_clause`] +/// decides what continues one. Only `.rs` citations are narrowed this way; +/// the logic lives inline in the `Event::Code` arm below. fn extract_path_citations(markdown: &str) -> BTreeSet { use pulldown_cmark::{Event, Options, Parser, Tag, TagEnd}; @@ -382,7 +430,16 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { } if !is_path_candidate(span) { - reset_inline!(); + // Unlike a block/heading/paragraph boundary, a stray + // non-path span (a type name, an identifier) inside a + // possessive clause's explanatory aside is transparent to + // the chain, not a hard break: only the immediately + // preceding prose is cleared (so it can't be misread as a + // connector by the next citation), but the active owner + // and last code span survive — see + // `continues_possessive_clause`'s doc comment for why + // this is still safe. + inter_text.clear(); continue; } @@ -394,9 +451,11 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { continue; } - // Resolve the possessive owner for this span — the three - // connectors the doc uses: 's starts a clause, / and `and` - // continue one. Only scoped (.rs) citations are narrowed. + // Resolve the possessive owner for this span — the clause + // starts with 's, and continues via / or `and`, optionally + // wrapped in ordinary list punctuation (see + // `continues_possessive_clause`). Only scoped (.rs) citations + // are narrowed. let trimmed = inter_text.trim(); let new_owner: Option = if is_scoped_extension(span) { if trimmed == "'s" { @@ -404,7 +463,7 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { .as_deref() .filter(|s| is_directory_shaped(s)) .map(str::to_string) - } else if matches!(trimmed, "/" | "and") { + } else if continues_possessive_clause(trimmed) { possessive_owner.clone() } else { None @@ -1216,6 +1275,92 @@ Every listed crate's `mod.rs` is a placeholder example, not real doc prose. ); } + #[test] + fn extract_path_citations_keeps_an_owner_through_an_unrelated_aside() { + // Regression: the real doc's `rocm-dash-tui` paragraph interleaves + // type names (`AgentClient`, `rig`) between the files a possessive + // clause names — each one a non-path Code span that used to fully + // reset the chain (`reset_inline!()`), losing the owner for every + // citation after the first. The aside must be transparent instead. + let markdown = "\ +### `crates/rocm-dash-core`, `rocm-dash-collectors`, `rocm-dash-daemon`, `rocm-dash-tui` — dashboard/telemetry + +`rocm-dash-tui`'s `agent.rs` was split into `agent/mod.rs` (the `AgentClient` seam) and `agent/snapshot.rs` (no `rig` dependency). +"; + let citations = extract_path_citations(markdown); + for text in ["agent/mod.rs", "agent/snapshot.rs"] { + let citation = citations + .iter() + .find(|c| c.text == text) + .unwrap_or_else(|| panic!("expected a {text} citation")); + assert_eq!( + citation.section_dirs, + vec!["rocm-dash-tui".to_string()], + "{text} should stay narrowed to rocm-dash-tui through the aside" + ); + } + } + + #[test] + fn extract_path_citations_narrows_a_natural_comma_and_list() { + // Regression: a contributor listing split files the way ordinary + // English lists things ("X, Y, Z, and W") rather than joining them + // with literal slashes must not lose narrowing on the middle items — + // only the last pair uses the word `and`; the rest are plain commas. + let markdown = "\ +### `crates/rocm-dash-core`, `rocm-dash-collectors`, `rocm-dash-daemon`, `rocm-dash-tui` — dashboard/telemetry + +`rocm-dash-tui`'s `agent.rs` was split into `agent/mod.rs`, `agent/snapshot.rs`, `agent/tools.rs`, and `agent/clients.rs`. +"; + let citations = extract_path_citations(markdown); + for text in [ + "agent/mod.rs", + "agent/snapshot.rs", + "agent/tools.rs", + "agent/clients.rs", + ] { + let citation = citations + .iter() + .find(|c| c.text == text) + .unwrap_or_else(|| panic!("expected a {text} citation")); + assert_eq!( + citation.section_dirs, + vec!["rocm-dash-tui".to_string()], + "{text} should be narrowed to rocm-dash-tui via the comma list" + ); + } + } + + #[test] + fn extract_path_citations_does_not_leak_an_owner_across_a_sentence_boundary() { + // The relaxations above must not regress into the rejected "sticky + // for the rest of the heading" design: a new sentence naming a file + // that belongs to a *different* crate the heading also lists, with + // no possessive clause of its own, must NOT inherit the previous + // sentence's owner — it should fall back to the heading's full + // (and correctly checked) crate list instead. + let markdown = "\ +### `crates/rocm-dash-core`, `rocm-dash-collectors`, `rocm-dash-daemon`, `rocm-dash-tui` — dashboard/telemetry + +`rocm-dash-tui`'s `agent.rs` was split into `agent/mod.rs` and `agent/snapshot.rs`. Elsewhere, `metrics.rs` tracks collector throughput. +"; + let citations = extract_path_citations(markdown); + let metrics_citation = citations + .iter() + .find(|c| c.text == "metrics.rs") + .expect("expected a metrics.rs citation"); + assert_eq!( + metrics_citation.section_dirs, + vec![ + "crates/rocm-dash-core".to_string(), + "rocm-dash-collectors".to_string(), + "rocm-dash-daemon".to_string(), + "rocm-dash-tui".to_string(), + ], + "metrics.rs must not inherit rocm-dash-tui from the earlier sentence" + ); + } + #[test] fn extract_path_citations_narrows_every_citation_in_a_slash_chained_possessive() { // The real doc's module-map prose reads `` `crates/rocm-core`'s From 6caf9d23a0b0392708cc5cc7815cfc812b0735ea Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 2 Oct 2026 07:48:06 +0000 Subject: [PATCH 2/7] fix(xtask): harden path-candidate and clause-continuation checks is_path_candidate accepted any slash-containing span unconditionally, so a future doc edit using a common shorthand pair (`read/write`, `and/or`, `GPU/CPU`) would false-fail CI. Reject a slash-path whose every segment is a known prose word, while still accepting a real path with only one ordinary-word segment (`apps/rocm`). Also fix continues_possessive_clause: it inferred a sentence boundary from inter_text, but a non-candidate aside span (a type name) or a pending hyphenated span clears inter_text first, discarding an already-seen sentence-ending period before the check ever ran. A period right before such an aside was silently lost, letting a possessive owner wrongly narrow a later, unrelated citation past its sentence boundary. Track the boundary with a persistent flag instead, reset only where a clause's owner is actually (re)confirmed. Fixes #440. Signed-off-by: Jussi Elo --- xtask/src/architecture_doc.rs | 181 ++++++++++++++++++++++++++-------- 1 file changed, 138 insertions(+), 43 deletions(-) diff --git a/xtask/src/architecture_doc.rs b/xtask/src/architecture_doc.rs index aa41c4f376..c0417a39c7 100644 --- a/xtask/src/architecture_doc.rs +++ b/xtask/src/architecture_doc.rs @@ -176,24 +176,22 @@ fn tracked_files(root: &Path) -> Result> { /// word (`rocm-dash-collectors`) — the doc's convention for citing a /// crate directory by its Cargo package name. /// -/// Two deliberate blind spots, same "safer to miss than false-flag" tradeoff: -/// - A bare, non-hyphenated word (`xtask`) is not treated as a candidate: -/// nothing at the lexical level distinguishes a real bare directory from -/// a plain English word or shell command (e.g. `grep`). -/// - A slash-path whose every component is a common English word (`read/write`, -/// `and/or`) is accepted unconditionally; nothing at the lexical level -/// distinguishes `apps/rocm` from `and/or`, and the doc's own prose has -/// never contained such a pattern — spaces, which is_path_safe already -/// rejects, have always separated prose from punctuation in practice. -/// A future `` `and/or` `` in the doc would false-fail CI; if that ever -/// happens, the citation should use a hyphenated form or a qualifying -/// directory prefix. +/// One deliberate blind spot remains, same "safer to miss than false-flag" +/// tradeoff: a bare, non-hyphenated word (`xtask`) is not treated as a +/// candidate — nothing at the lexical level distinguishes a real bare +/// directory from a plain English word or shell command (e.g. `grep`). +/// +/// A slash-path whose every component is a known [`PROSE_SLASH_WORDS`] entry +/// (`read/write`, `and/or`, `GPU/CPU`) is rejected rather than accepted +/// unconditionally — see that constant's doc comment for why this guard is +/// narrow (a curated list, not a dictionary check) rather than a complete +/// fix. fn is_path_candidate(span: &str) -> bool { if span.is_empty() || !is_path_safe(span) { return false; } if span.contains('/') { - return true; + return !is_prose_slash_phrase(span); } if BARE_FILE_EXTENSIONS .iter() @@ -204,6 +202,30 @@ fn is_path_candidate(span: &str) -> bool { is_hyphenated_bare_word(span) } +/// Bare words known to appear as `/`-joined shorthand pairs in ordinary +/// prose (`` `and/or` ``, `` `read/write` ``, `` `GPU/CPU` ``) rather than as +/// real path segments. Matched case-insensitively so `GPU`/`CPU` are caught +/// by the same list as `and`/`or`. +/// +/// Not exhaustive, by design — the same bounded, curated-list tradeoff +/// [`BARE_FILE_EXTENSIONS`] already makes for extensions rather than +/// guessing. A slash-joined prose pair not in this list (or a path where +/// only *one* side happens to be an ordinary word, e.g. `apps/rocm`) still +/// passes [`is_path_candidate`] unchanged — this closes the three concrete +/// patterns #440 reported, not every possible false positive. +const PROSE_SLASH_WORDS: [&str; 6] = ["and", "or", "read", "write", "gpu", "cpu"]; + +/// Whether every `/`-separated segment of `span` is a [`PROSE_SLASH_WORDS`] +/// entry — i.e. the whole span reads as a prose shorthand pair rather than a +/// path, so even a real path with one ordinary-word segment (`apps/rocm`) +/// is unaffected: only a span where *every* segment matches is rejected. +fn is_prose_slash_phrase(span: &str) -> bool { + span.split('/').all(|segment| { + let lower = segment.to_ascii_lowercase(); + PROSE_SLASH_WORDS.contains(&lower.as_str()) + }) +} + /// Whether every character in `span` is safe to appear in a path, as /// opposed to prose punctuation: alphanumeric (any Unicode letter or digit, /// not just ASCII — a tracked file can have a non-ASCII name, e.g. @@ -252,10 +274,11 @@ fn is_directory_shaped(span: &str) -> bool { is_directory_path || is_hyphenated_bare_word(span) } -/// Whether `inter_text` — the raw prose accumulated since a possessive -/// clause's owner was last confirmed — continues that clause rather than -/// ending it, for the continuation step (the initial `'s` owner-establishing -/// step is a separate, exact-match check and unaffected by this). +/// Whether a possessive clause continues through to the next citation, +/// given `sentence_boundary_seen` — whether a sentence-ending `.` has +/// occurred anywhere since the clause's owner was last confirmed — for the +/// continuation step (the initial `'s` owner-establishing step is a +/// separate, exact-match check and unaffected by this). /// /// A real split's prose connects its files with free English — "was split /// into", "a mechanical relocation, since ..." — not just `/`/`and`/`,`, @@ -264,24 +287,28 @@ fn is_directory_shaped(span: &str) -> bool { /// (the original, stricter design) rejects exactly this ordinary writing: a /// doc edit this mundane should not need unusual phrasing just to keep CI /// green. So the clause continues through *any* text, with one -/// unconditional exception: a sentence-ending `.` always ends it, no matter -/// what else is in `inter_text`. That's the safety net against the masking -/// risk the module doc warns about — without it, a later sentence naming an -/// unrelated file from a *different* crate in the same heading, with no new -/// possessive clause of its own, would silently inherit an earlier owner -/// instead of falling back to the heading's full (and correctly checked) -/// crate list. A single sentence is a safe enough unit to trust: shifting to -/// a different crate's file without starting a new clause or sentence would -/// be confusing prose on its own merits, not just a gap in this checker. +/// unconditional exception: a sentence-ending `.` always ends it. That's +/// the safety net against the masking risk the module doc warns about — +/// without it, a later sentence naming an unrelated file from a *different* +/// crate in the same heading, with no new possessive clause of its own, +/// would silently inherit an earlier owner instead of falling back to the +/// heading's full (and correctly checked) crate list. A single sentence is +/// a safe enough unit to trust: shifting to a different crate's file +/// without starting a new clause or sentence would be confusing prose on +/// its own merits, not just a gap in this checker. /// -/// A sentence-ending `.` means one followed by whitespace (or nothing, at -/// the end of `inter_text`) — not a bare `.` glued to surrounding -/// characters. This doc itself now de-backticks the removed `agent.rs` -/// filename right inside a clause this function must keep alive ("old -/// agent.rs was split into ..."); a naive "any `.`" check would wrongly -/// treat that file extension's dot as a sentence end. -fn continues_possessive_clause(inter_text: &str) -> bool { - !ends_with_a_sentence_boundary(inter_text) +/// `sentence_boundary_seen` is threaded through [`extract_path_citations`]'s +/// loop rather than recomputed from the `inter_text` buffer at the call +/// site, because that buffer isn't a reliable record of "every sentence +/// since the owner was confirmed": a non-candidate aside span (a type name +/// like `` `AgentClient` ``) or a pending hyphenated span clears it so it +/// can't be misread as a connector, which used to silently discard an +/// already-seen sentence-ending period along with it. The flag survives +/// those clears and is only reset where a clause's owner is actually +/// (re)confirmed, so a period is never lost just because an aside happened +/// to follow it. +const fn continues_possessive_clause(sentence_boundary_seen: bool) -> bool { + !sentence_boundary_seen } /// Whether `text` contains a period that ends a sentence, as opposed to one @@ -338,6 +365,12 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { let mut last_code_span: Option = None; // The active possessive owner within the current clause. let mut possessive_owner: Option = None; + // Whether a sentence-ending `.` has occurred since `possessive_owner` + // was last (re)confirmed — tracked separately from `inter_text` because + // that buffer gets cleared by asides and pending hyphenated spans + // (see [`continues_possessive_clause`]), which must not also erase the + // memory of an already-seen sentence boundary. + let mut sentence_boundary_seen = false; // Accumulate heading directories until End(Heading) commits them. let mut heading_dirs: Vec = Vec::new(); @@ -361,6 +394,7 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { last_code_span = None; possessive_owner = None; pending_hyphenated = None; + sentence_boundary_seen = false; }; } @@ -410,9 +444,13 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { section_dirs: effective_dirs.clone(), }); possessive_owner = Some(hyph.clone()); + sentence_boundary_seen = false; } last_code_span = Some(hyph); } + if ends_with_a_sentence_boundary(&text) { + sentence_boundary_seen = true; + } inter_text.push_str(&text); } Event::Code(span) if !in_code_block => { @@ -435,16 +473,19 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { // possessive clause's explanatory aside is transparent to // the chain, not a hard break: only the immediately // preceding prose is cleared (so it can't be misread as a - // connector by the next citation), but the active owner - // and last code span survive — see - // `continues_possessive_clause`'s doc comment for why - // this is still safe. + // connector by the next citation), but the active owner, + // last code span, and `sentence_boundary_seen` survive — + // see `continues_possessive_clause`'s doc comment for why + // this is still safe (and why `sentence_boundary_seen` + // specifically must NOT be cleared here). inter_text.clear(); continue; } // Hyphenated bare word: defer emission until we see whether - // the next text is 's (possessive) or not (prose). + // the next text is 's (possessive) or not (prose). Same + // transparency as the aside branch above: + // `sentence_boundary_seen` must survive this clear too. if is_hyphenated_bare_word(span) { pending_hyphenated = Some(span.to_string()); inter_text.clear(); @@ -453,9 +494,10 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { // Resolve the possessive owner for this span — the clause // starts with 's, and continues via / or `and`, optionally - // wrapped in ordinary list punctuation (see - // `continues_possessive_clause`). Only scoped (.rs) citations - // are narrowed. + // wrapped in ordinary list punctuation, unless a sentence + // boundary has been seen since the owner was last confirmed + // (see `continues_possessive_clause`). Only scoped (.rs) + // citations are narrowed. let trimmed = inter_text.trim(); let new_owner: Option = if is_scoped_extension(span) { if trimmed == "'s" { @@ -463,7 +505,7 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { .as_deref() .filter(|s| is_directory_shaped(s)) .map(str::to_string) - } else if continues_possessive_clause(trimmed) { + } else if continues_possessive_clause(sentence_boundary_seen) { possessive_owner.clone() } else { None @@ -499,6 +541,7 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { possessive_owner = new_owner; last_code_span = Some(span.to_string()); inter_text.clear(); + sentence_boundary_seen = false; } _ => {} } @@ -785,6 +828,28 @@ mod tests { } } + #[test] + fn slash_joined_prose_pairs_are_not_candidates() { + // #440 regression: `is_path_candidate` used to accept any + // slash-containing span unconditionally, so a future doc edit using + // one of these common shorthand pairs would false-fail CI (none + // exist in the tracked tree, so none would resolve to a real path). + for span in ["read/write", "and/or", "GPU/CPU"] { + assert!( + !is_path_candidate(span), + "did not expect {span} to be a candidate" + ); + } + } + + #[test] + fn slash_path_with_only_one_prose_side_is_still_a_candidate() { + // The guard only rejects a span where *every* segment is a known + // prose word — a real path like `apps/rocm` has one ordinary-word + // segment (`rocm`) but must still be checked. + assert!(is_path_candidate("apps/rocm")); + } + #[test] fn bare_non_hyphenated_word_is_not_a_candidate() { // The documented blind spot: `xtask` is a real directory cited bare @@ -1361,6 +1426,36 @@ Every listed crate's `mod.rs` is a placeholder example, not real doc prose. ); } + #[test] + fn extract_path_citations_does_not_leak_an_owner_past_a_sentence_boundary_hidden_by_an_aside() { + // Regression: `inter_text.clear()` in the non-candidate aside branch + // used to discard a sentence-ending `.` before `continues_possessive_ + // clause` ever saw it, so a period immediately followed by an aside + // Code span (a type name) went unnoticed — the clause wrongly kept + // "continuing" past the sentence boundary into the next citation. + let markdown = "\ +### `crates/rocm-dash-core`, `rocm-dash-collectors`, `rocm-dash-daemon`, `rocm-dash-tui` — dashboard/telemetry + +`rocm-dash-tui`'s `agent.rs` is done. `AgentClient` tracks `metrics.rs`. +"; + let citations = extract_path_citations(markdown); + let metrics_citation = citations + .iter() + .find(|c| c.text == "metrics.rs") + .expect("expected a metrics.rs citation"); + assert_eq!( + metrics_citation.section_dirs, + vec![ + "crates/rocm-dash-core".to_string(), + "rocm-dash-collectors".to_string(), + "rocm-dash-daemon".to_string(), + "rocm-dash-tui".to_string(), + ], + "metrics.rs must not inherit rocm-dash-tui through the aside, \ + since a sentence already ended before it" + ); + } + #[test] fn extract_path_citations_narrows_every_citation_in_a_slash_chained_possessive() { // The real doc's module-map prose reads `` `crates/rocm-core`'s From bddb8409caa2a6923ae6d061313183473570a670 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 2 Oct 2026 08:44:41 +0000 Subject: [PATCH 3/7] fix(xtask): abbreviation-aware sentence boundaries, directory/candidate parity contains_a_sentence_boundary (renamed from ends_with_a_sentence_boundary, which checked anywhere in the text, not just the end) treated any "period followed by whitespace" as a sentence end, so "e.g. "/"i.e. "/ "etc. " wrongly ended a possessive clause early. The real doc already uses "e.g." near the checker's own module doc, so a future doc edit using it inside a possessive clause would fall back to the heading's full crate list instead of narrowing - a false CI failure on an accurate edit, the exact class of bug this scoping feature exists to prevent. Guard against a small, curated list of abbreviations (e.g, i.e, etc), matched against the alphanumerics-and-periods token the candidate period ends, so surrounding punctuation like a leading `(` doesn't need separate stripping. Also closes a gap the #440 fix left open: is_path_candidate rejects a slash-joined prose pair (read/write, and/or, GPU/CPU), but is_directory_shaped didn't get the same guard, so a heading citing such a span would still be collected as a directory. Both now share the is_prose_slash_phrase check. Signed-off-by: Jussi Elo --- xtask/src/architecture_doc.rs | 122 +++++++++++++++++++++++++++++----- 1 file changed, 107 insertions(+), 15 deletions(-) diff --git a/xtask/src/architecture_doc.rs b/xtask/src/architecture_doc.rs index c0417a39c7..2347861835 100644 --- a/xtask/src/architecture_doc.rs +++ b/xtask/src/architecture_doc.rs @@ -258,19 +258,25 @@ fn is_hyphenated_bare_word(span: &str) -> bool { /// [`is_path_safe`]) — otherwise a stray bit of prose punctuation next to a /// `/` (`` `foo/bar!`'s `main.rs` ``) would be accepted as a directory, /// producing an unmatchable `section_dirs` entry that fails an accurate -/// citation — and its last component must have no extension (a `.`), +/// citation — its last component must have no extension (a `.`), /// otherwise a full file path (`` `crates/rocm-core/src/diagnose.rs` ``, /// or one ending in an extension outside [`BARE_FILE_EXTENSIONS`] like /// `` `.github/workflows/ci.yml` ``) would be accepted as if it were the /// directory containing it, which is equally unmatchable — checked /// generally rather than against just [`BARE_FILE_EXTENSIONS`], since a /// full path can end in any extension, not only the ones the doc cites -/// bare. [`is_hyphenated_bare_word`] already excludes extensions and -/// guarantees path-safety on its own, so only the slash branch needs the -/// extra checks. +/// bare — and it must not be a [`PROSE_SLASH_WORDS`] pair, same as +/// [`is_path_candidate`]'s slash branch: a heading literally citing +/// `` `read/write` `` must not be collected as a directory any more than it +/// would be accepted as a citation elsewhere. [`is_hyphenated_bare_word`] +/// already excludes extensions and guarantees path-safety on its own, so +/// only the slash branch needs the extra checks. fn is_directory_shaped(span: &str) -> bool { let last_segment = span.rsplit('/').next().unwrap_or(span); - let is_directory_path = span.contains('/') && is_path_safe(span) && !last_segment.contains('.'); + let is_directory_path = span.contains('/') + && is_path_safe(span) + && !last_segment.contains('.') + && !is_prose_slash_phrase(span); is_directory_path || is_hyphenated_bare_word(span) } @@ -311,19 +317,62 @@ const fn continues_possessive_clause(sentence_boundary_seen: bool) -> bool { !sentence_boundary_seen } -/// Whether `text` contains a period that ends a sentence, as opposed to one -/// embedded in ordinary prose (a filename like `agent.rs`, a version like -/// `v1.0`) — see [`continues_possessive_clause`] for why that distinction -/// matters here. A period counts as sentence-ending only when followed by -/// whitespace or nothing (the end of `text`); one directly glued to the next -/// character on both sides never does. -fn ends_with_a_sentence_boundary(text: &str) -> bool { +/// Abbreviations whose trailing period isn't a sentence boundary, matched +/// against the token of alphanumerics-and-periods containing the candidate +/// period — case-insensitively, and with that token's own trailing periods +/// stripped first, so `` e.g. ``'s embedded period doesn't need separate +/// handling from its trailing one (`` e.g. `` trims to `e.g`, matching the +/// `"e.g"` entry below). Surrounding punctuation (a leading `(`, say) isn't +/// part of the token, only alphanumerics/periods are — otherwise a leading +/// character swept in by a plain whitespace boundary (`` (e.g. ``) would +/// never match. Not exhaustive, same bounded, curated-list tradeoff as +/// [`PROSE_SLASH_WORDS`]: an abbreviation not in this list still incorrectly +/// ends a clause early — a doc edit hitting that gap should spell the +/// abbreviation out, or this list extended deliberately. +const SENTENCE_BOUNDARY_ABBREVIATIONS: [&str; 3] = ["e.g", "i.e", "etc"]; + +/// Whether `text` contains a period that ends a sentence *anywhere* within +/// it — not just at its end, despite scanning one word at a time; the name +/// says "contains", not "ends with", because callers scan one accumulated +/// chunk of prose for any sentence boundary, not just a trailing one (see +/// [`continues_possessive_clause`] for why that distinction matters here). +/// +/// A period counts as sentence-ending only when followed by whitespace or +/// nothing (the end of `text`) — one directly glued to the next character +/// on both sides never does, which already excludes a version number like +/// `v1.0` or a filename like `agent.rs` *unless* it sits at the very end of +/// `text` (a file name right before a sentence-ending period, as in this +/// module's own doc comments, correctly still counts). The remaining case a +/// trailing-whitespace check alone can't tell apart from a real sentence end +/// is an abbreviation like `` e.g. ``/`` i.e. ``/`` etc. `` — checked +/// against [`SENTENCE_BOUNDARY_ABBREVIATIONS`]. +fn contains_a_sentence_boundary(text: &str) -> bool { let bytes = text.as_bytes(); bytes.iter().enumerate().any(|(i, &b)| { - b == b'.' - && bytes + if b != b'.' + || !bytes .get(i + 1) .is_none_or(|&next| next.is_ascii_whitespace()) + { + return false; + } + // Walk back over the token this period ends — alphanumerics and + // embedded periods only (`e.g.`'s own internal `.`), so surrounding + // punctuation like a leading `(` isn't swept into the comparison + // below and doesn't need stripping on top of the trailing trim. + let mut word_start = i; + while word_start > 0 { + let prev = bytes[word_start - 1]; + if prev.is_ascii_alphanumeric() || prev == b'.' { + word_start -= 1; + } else { + break; + } + } + let word = &text[word_start..=i]; + !SENTENCE_BOUNDARY_ABBREVIATIONS + .iter() + .any(|abbr| word.trim_end_matches('.').eq_ignore_ascii_case(abbr)) }) } @@ -448,7 +497,7 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { } last_code_span = Some(hyph); } - if ends_with_a_sentence_boundary(&text) { + if contains_a_sentence_boundary(&text) { sentence_boundary_seen = true; } inter_text.push_str(&text); @@ -850,6 +899,24 @@ mod tests { assert!(is_path_candidate("apps/rocm")); } + #[test] + fn slash_joined_prose_pairs_are_not_directory_shaped() { + // Regression: `is_directory_shaped` wasn't updated alongside + // `is_path_candidate`'s #440 fix, so a heading backtick-citing a + // prose slash-phrase would still be collected into `heading_dirs` + // even though the same span is rejected as a citation elsewhere — + // an undocumented inconsistency between the two checks. + for span in ["read/write", "and/or", "GPU/CPU"] { + assert!( + !is_directory_shaped(span), + "did not expect {span} to be directory-shaped" + ); + } + // A real path with only one ordinary-word segment must stay + // directory-shaped, same carve-out as `is_path_candidate`. + assert!(is_directory_shaped("apps/rocm")); + } + #[test] fn bare_non_hyphenated_word_is_not_a_candidate() { // The documented blind spot: `xtask` is a real directory cited bare @@ -1456,6 +1523,31 @@ Every listed crate's `mod.rs` is a placeholder example, not real doc prose. ); } + #[test] + fn an_abbreviation_does_not_end_a_possessive_clause() { + // Regression: `e.g.`/`i.e.`/`etc.` each end in a period followed by + // whitespace, matching the plain "sentence boundary" pattern even + // though they don't end a sentence — and the real doc already uses + // `e.g.` nearby (the module's own intro paragraph). Without the + // abbreviation guard, this would wrongly fall back `agent/mod.rs` + // to the heading's full crate list instead of narrowing it. + let markdown = "\ +### `crates/rocm-dash-core`, `rocm-dash-collectors`, `rocm-dash-daemon`, `rocm-dash-tui` — dashboard/telemetry + +`rocm-dash-tui`'s `agent.rs` was split (e.g. via mechanical relocation) into `agent/mod.rs`. +"; + let citations = extract_path_citations(markdown); + let citation = citations + .iter() + .find(|c| c.text == "agent/mod.rs") + .expect("expected an agent/mod.rs citation"); + assert_eq!( + citation.section_dirs, + vec!["rocm-dash-tui".to_string()], + "agent/mod.rs should stay narrowed to rocm-dash-tui through the e.g. abbreviation" + ); + } + #[test] fn extract_path_citations_narrows_every_citation_in_a_slash_chained_possessive() { // The real doc's module-map prose reads `` `crates/rocm-core`'s From 5f3ebca0d7cc232653c69e287583ef9eadca26f5 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 2 Oct 2026 13:55:59 +0000 Subject: [PATCH 4/7] fix(xtask): clear last_code_span through a non-path aside A type-name aside (e.g. an identifier) right before a possessive `'s` used to leave `last_code_span` pointing at whatever directory-shaped span preceded it, so `'s` could pick up that stale, unrelated owner instead of correctly finding none. Clear `last_code_span` in the aside branch alongside `inter_text`. Also pins two gaps the review found in the existing test suite: a `is_prose_slash_phrase` regression test whose input couldn't actually distinguish `all` from `any`, and missing coverage for the hyphenated-owner `sentence_boundary_seen` reset when a new clause starts right after an earlier sentence in the same paragraph. Signed-off-by: Jussi Elo --- xtask/src/architecture_doc.rs | 146 ++++++++++++++++++++++++++++++---- 1 file changed, 131 insertions(+), 15 deletions(-) diff --git a/xtask/src/architecture_doc.rs b/xtask/src/architecture_doc.rs index 2347861835..ede58163d7 100644 --- a/xtask/src/architecture_doc.rs +++ b/xtask/src/architecture_doc.rs @@ -303,6 +303,15 @@ fn is_directory_shaped(span: &str) -> bool { /// without starting a new clause or sentence would be confusing prose on /// its own merits, not just a gap in this checker. /// +/// Known limitation: an owner can still leak to an unrelated file *within* +/// one sentence, because only a backtick-quoted `` `'s` `` starts a new +/// clause — `` `rocm-dash-tui`'s `agent.rs` talks to the daemon's +/// `server.rs` `` narrows `server.rs` to `rocm-dash-tui` too, even though +/// its own `'s` is ordinary (un-backticked) prose, not a new possessive +/// citation. This is natural wording, not a contrived edge case, so it is a +/// real gap rather than "confusing prose on its own merits" — accepted for +/// now as the same bounded tradeoff the module doc already makes elsewhere. +/// /// `sentence_boundary_seen` is threaded through [`extract_path_citations`]'s /// loop rather than recomputed from the `inter_text` buffer at the call /// site, because that buffer isn't a reliable record of "every sentence @@ -406,8 +415,10 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { let mut narrowed_owners: std::collections::BTreeMap = std::collections::BTreeMap::new(); - // Inline context: what sits between one Code event and the next. - // Used to detect possessive connectors (\'s, /, and) for narrowing. + // Inline context: what sits between one Code event and the next. Only + // checked for an exact `'s` (the clause's owner-establishing step); any + // other content continues the clause via [`continues_possessive_clause`] + // regardless of what it is. let mut inter_text = String::new(); // The last Code span that was a directory-shaped or scoped candidate — // may become a possessive owner for the next Code span. @@ -520,14 +531,19 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { // Unlike a block/heading/paragraph boundary, a stray // non-path span (a type name, an identifier) inside a // possessive clause's explanatory aside is transparent to - // the chain, not a hard break: only the immediately - // preceding prose is cleared (so it can't be misread as a - // connector by the next citation), but the active owner, - // last code span, and `sentence_boundary_seen` survive — - // see `continues_possessive_clause`'s doc comment for why + // the chain, not a hard break: the active owner and + // `sentence_boundary_seen` survive — see + // `continues_possessive_clause`'s doc comment for why // this is still safe (and why `sentence_boundary_seen` - // specifically must NOT be cleared here). + // specifically must NOT be cleared here). But the + // preceding prose AND `last_code_span` are both cleared: + // the aside's own span (a type name, an identifier) must + // not be mistaken for the possessive's owner by the next + // citation's exact-`'s` check — `'s` takes its owner from + // the span immediately before it, and that span is this + // aside, not whatever code span preceded it. inter_text.clear(); + last_code_span = None; continue; } @@ -542,10 +558,9 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { } // Resolve the possessive owner for this span — the clause - // starts with 's, and continues via / or `and`, optionally - // wrapped in ordinary list punctuation, unless a sentence - // boundary has been seen since the owner was last confirmed - // (see `continues_possessive_clause`). Only scoped (.rs) + // starts with 's, and continues through any text until a + // sentence boundary ends it (see + // `continues_possessive_clause`). Only scoped (.rs) // citations are narrowed. let trimmed = inter_text.trim(); let new_owner: Option = if is_scoped_extension(span) { @@ -894,9 +909,13 @@ mod tests { #[test] fn slash_path_with_only_one_prose_side_is_still_a_candidate() { // The guard only rejects a span where *every* segment is a known - // prose word — a real path like `apps/rocm` has one ordinary-word - // segment (`rocm`) but must still be checked. - assert!(is_path_candidate("apps/rocm")); + // prose word — a real path like `docs/and` has one + // `PROSE_SLASH_WORDS` segment (`and`) but its other segment + // (`docs`) is not, so it must still be checked. (`apps/rocm` + // doesn't actually exercise this: neither `apps` nor `rocm` is a + // `PROSE_SLASH_WORDS` entry, so the check can't tell `all` from + // `any` on that input — it passes either way.) + assert!(is_path_candidate("docs/and")); } #[test] @@ -928,6 +947,17 @@ mod tests { assert!(!is_path_candidate("grep")); } + #[test] + fn contains_a_sentence_boundary_detects_a_period_at_the_very_end_of_text() { + // The doc comment explicitly claims this case ("a file name right + // before a sentence-ending period ... correctly still counts"), but + // nothing exercised it directly: every other sentence-boundary test + // runs through `extract_path_citations`, where a trailing period is + // always followed by more markdown text, never the end of the + // scanned chunk itself. + assert!(contains_a_sentence_boundary("done.")); + } + #[test] fn extract_path_citations_recognizes_a_double_backtick_directory_citation() { let markdown = "See ``apps/rocm`` for the CLI entry point.\n"; @@ -1523,6 +1553,92 @@ Every listed crate's `mod.rs` is a placeholder example, not real doc prose. ); } + #[test] + fn extract_path_citations_takes_the_owner_from_the_span_right_before_s_not_a_stale_one() { + // Regression: the aside branch used to clear only `inter_text`, + // leaving `last_code_span` pointing at whatever directory-shaped + // span preceded the aside. When `'s` directly follows a non-path + // aside (a type name), the checker's own rule — `'s` takes its + // owner from the span right before it — means the possessive + // belongs to the aside itself (not a path), so there is no valid + // owner; it must fall back to the heading's full crate list, not + // silently narrow to that stale, unrelated directory. + let markdown = "\ +### `crates/rocm-dash-core`, `rocm-dash-tui` — dashboard/telemetry + +`rocm-dash-tui` wraps `AgentClient`'s `lib.rs`. +"; + let citations = extract_path_citations(markdown); + let citation = citations + .iter() + .find(|c| c.text == "lib.rs") + .expect("expected a lib.rs citation"); + assert_eq!( + citation.section_dirs, + vec![ + "crates/rocm-dash-core".to_string(), + "rocm-dash-tui".to_string(), + ], + "lib.rs must not narrow to rocm-dash-tui — the possessive belongs \ + to AgentClient, not the stale last code span" + ); + } + + #[test] + fn extract_path_citations_does_not_narrow_through_a_slash_qualified_owner_hidden_by_an_aside() { + // Second reproduction of the same regression, with a slash-qualified + // directory one `and` away from the aside instead of a bare + // hyphenated name — the stale `last_code_span` must not survive + // either shape of owner. + let markdown = "\ +### `crates/rocm-dash-core`, `rocm-dash-tui` — dashboard/telemetry + +`crates/rocm-dash-core` and `Foo`'s `x.rs`. +"; + let citations = extract_path_citations(markdown); + let citation = citations + .iter() + .find(|c| c.text == "x.rs") + .expect("expected an x.rs citation"); + assert_eq!( + citation.section_dirs, + vec![ + "crates/rocm-dash-core".to_string(), + "rocm-dash-tui".to_string(), + ], + "x.rs must not narrow to crates/rocm-dash-core — the possessive \ + belongs to Foo, not the stale last code span" + ); + } + + #[test] + fn extract_path_citations_narrows_a_hyphenated_owner_that_starts_after_an_earlier_sentence() { + // Regression: resolving a pending hyphenated span into a confirmed + // possessive owner has its own `sentence_boundary_seen = false` + // reset, separate from `reset_inline!()` — it must fire every time + // an owner is (re)confirmed, including when that owner's clause + // starts right after an earlier sentence in the same paragraph. + // Without it, the earlier sentence's boundary would still be + // asserted against the brand new clause, failing its very first + // continuation check and falling back to the heading's full list. + let markdown = "\ +### `crates/rocm-dash-core`, `rocm-dash-tui` — dashboard/telemetry + +Intro. `rocm-dash-tui`'s old thing was split into `agent/mod.rs`. +"; + let citations = extract_path_citations(markdown); + let citation = citations + .iter() + .find(|c| c.text == "agent/mod.rs") + .expect("expected an agent/mod.rs citation"); + assert_eq!( + citation.section_dirs, + vec!["rocm-dash-tui".to_string()], + "agent/mod.rs should narrow to rocm-dash-tui even though an \ + earlier sentence in the same paragraph already ended" + ); + } + #[test] fn an_abbreviation_does_not_end_a_possessive_clause() { // Regression: `e.g.`/`i.e.`/`etc.` each end in a period followed by From 5e66c6c96d9b008a7a9ba46f850da1a0546e61bb Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 5 Oct 2026 07:38:56 +0000 Subject: [PATCH 5/7] test(xtask): cover sentence boundary across a discarded hyphenated span Mirrors the existing aside-branch regression test for the pending- hyphenated-span discard path: sentence_boundary_seen must survive that inter_text.clear() too, or a later citation narrows to a stale owner instead of falling back to the heading's full list. Signed-off-by: Jussi Elo --- xtask/src/architecture_doc.rs | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/xtask/src/architecture_doc.rs b/xtask/src/architecture_doc.rs index ede58163d7..33c818d285 100644 --- a/xtask/src/architecture_doc.rs +++ b/xtask/src/architecture_doc.rs @@ -1639,6 +1639,40 @@ Intro. `rocm-dash-tui`'s old thing was split into `agent/mod.rs`. ); } + #[test] + fn extract_path_citations_does_not_leak_an_owner_past_a_sentence_boundary_hidden_by_a_discarded_hyphenated_span() + { + // Regression: a bare hyphenated word that turns out not to be a + // possessive owner (no `'s` follows it) is discarded as prose, and + // that discard clears `inter_text` the same way the type-name aside + // does — but, like the aside, must NOT reset `sentence_boundary_seen` + // (see the comment on that clear). If it did, a sentence boundary + // seen just before the discarded hyphenated word would be forgotten, + // and the next scoped citation would wrongly keep narrowing to the + // earlier sentence's owner instead of falling back to the heading's + // full list. + let markdown = "\ +### `crates/rocm-dash-core`, `rocm-dash-daemon`, `rocm-dash-tui` — dashboard/telemetry + +`rocm-dash-tui`'s `a.rs` is done. See `rocm-dash-daemon` docs and `b.rs`. +"; + let citations = extract_path_citations(markdown); + let citation = citations + .iter() + .find(|c| c.text == "b.rs") + .expect("expected a b.rs citation"); + assert_eq!( + citation.section_dirs, + vec![ + "crates/rocm-dash-core".to_string(), + "rocm-dash-daemon".to_string(), + "rocm-dash-tui".to_string(), + ], + "b.rs must not inherit rocm-dash-tui through the discarded \ + rocm-dash-daemon span, since a sentence already ended before it" + ); + } + #[test] fn an_abbreviation_does_not_end_a_possessive_clause() { // Regression: `e.g.`/`i.e.`/`etc.` each end in a period followed by From c4660c49c0479d251ad229537a7dd08a05f98f04 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 5 Oct 2026 08:53:53 +0000 Subject: [PATCH 6/7] fix(xtask): recognize ?/! sentence boundaries, close a narrowing test gap Non-blocking findings from the last automated review: - contains_a_sentence_boundary only checked '.', so a clause ending in '?' or '!' kept carrying its owner into the next sentence. - The sentence_boundary_seen reset at the end of the main citation Code arm had no dedicated unit test, only indirect coverage via run_passes_against_the_real_doc. - is_path_candidate's doc comment claimed one blind spot remained, undercounting the PROSE_SLASH_WORDS gap described two lines below. Signed-off-by: Jussi Elo --- xtask/src/architecture_doc.rs | 129 ++++++++++++++++++++++++++-------- 1 file changed, 101 insertions(+), 28 deletions(-) diff --git a/xtask/src/architecture_doc.rs b/xtask/src/architecture_doc.rs index 33c818d285..8e29bc4256 100644 --- a/xtask/src/architecture_doc.rs +++ b/xtask/src/architecture_doc.rs @@ -176,16 +176,18 @@ fn tracked_files(root: &Path) -> Result> { /// word (`rocm-dash-collectors`) — the doc's convention for citing a /// crate directory by its Cargo package name. /// -/// One deliberate blind spot remains, same "safer to miss than false-flag" -/// tradeoff: a bare, non-hyphenated word (`xtask`) is not treated as a -/// candidate — nothing at the lexical level distinguishes a real bare -/// directory from a plain English word or shell command (e.g. `grep`). +/// Deliberate blind spots remain here, same "safer to miss than +/// false-flag" tradeoff as elsewhere in this module: a bare, non-hyphenated +/// word (`xtask`) is not treated as a candidate — nothing at the lexical +/// level distinguishes a real bare directory from a plain English word or +/// shell command (e.g. `grep`). /// /// A slash-path whose every component is a known [`PROSE_SLASH_WORDS`] entry /// (`read/write`, `and/or`, `GPU/CPU`) is rejected rather than accepted /// unconditionally — see that constant's doc comment for why this guard is /// narrow (a curated list, not a dictionary check) rather than a complete -/// fix. +/// fix, which leaves a second blind spot: a prose slash-pair not in that +/// list is still wrongly accepted as a path candidate. fn is_path_candidate(span: &str) -> bool { if span.is_empty() || !is_path_safe(span) { return false; @@ -281,7 +283,7 @@ fn is_directory_shaped(span: &str) -> bool { } /// Whether a possessive clause continues through to the next citation, -/// given `sentence_boundary_seen` — whether a sentence-ending `.` has +/// given `sentence_boundary_seen` — whether a sentence-ending `.`/`?`/`!` has /// occurred anywhere since the clause's owner was last confirmed — for the /// continuation step (the initial `'s` owner-establishing step is a /// separate, exact-match check and unaffected by this). @@ -293,8 +295,8 @@ fn is_directory_shaped(span: &str) -> bool { /// (the original, stricter design) rejects exactly this ordinary writing: a /// doc edit this mundane should not need unusual phrasing just to keep CI /// green. So the clause continues through *any* text, with one -/// unconditional exception: a sentence-ending `.` always ends it. That's -/// the safety net against the masking risk the module doc warns about — +/// unconditional exception: a sentence-ending `.`/`?`/`!` always ends it. +/// That's the safety net against the masking risk the module doc warns about — /// without it, a later sentence naming an unrelated file from a *different* /// crate in the same heading, with no new possessive clause of its own, /// would silently inherit an earlier owner instead of falling back to the @@ -340,31 +342,37 @@ const fn continues_possessive_clause(sentence_boundary_seen: bool) -> bool { /// abbreviation out, or this list extended deliberately. const SENTENCE_BOUNDARY_ABBREVIATIONS: [&str; 3] = ["e.g", "i.e", "etc"]; -/// Whether `text` contains a period that ends a sentence *anywhere* within -/// it — not just at its end, despite scanning one word at a time; the name -/// says "contains", not "ends with", because callers scan one accumulated -/// chunk of prose for any sentence boundary, not just a trailing one (see -/// [`continues_possessive_clause`] for why that distinction matters here). +/// Whether `text` contains a `.`/`?`/`!` that ends a sentence *anywhere* +/// within it — not just at its end, despite scanning one word at a time; the +/// name says "contains", not "ends with", because callers scan one +/// accumulated chunk of prose for any sentence boundary, not just a trailing +/// one (see [`continues_possessive_clause`] for why that distinction matters +/// here). /// -/// A period counts as sentence-ending only when followed by whitespace or -/// nothing (the end of `text`) — one directly glued to the next character -/// on both sides never does, which already excludes a version number like -/// `v1.0` or a filename like `agent.rs` *unless* it sits at the very end of -/// `text` (a file name right before a sentence-ending period, as in this -/// module's own doc comments, correctly still counts). The remaining case a -/// trailing-whitespace check alone can't tell apart from a real sentence end -/// is an abbreviation like `` e.g. ``/`` i.e. ``/`` etc. `` — checked -/// against [`SENTENCE_BOUNDARY_ABBREVIATIONS`]. +/// Any of the three counts as sentence-ending only when followed by +/// whitespace or nothing (the end of `text`) — one directly glued to the +/// next character on both sides never does, which already excludes a +/// version number like `v1.0` or a filename like `agent.rs` *unless* it sits +/// at the very end of `text` (a file name right before a sentence-ending +/// period, as in this module's own doc comments, correctly still counts). +/// The remaining case a trailing-whitespace check alone can't tell apart +/// from a real sentence end is a period-only abbreviation like `` e.g. ``/`` +/// i.e. ``/`` etc. `` — checked against +/// [`SENTENCE_BOUNDARY_ABBREVIATIONS`]; `?` and `!` have no such exceptions, +/// so either always ends the sentence it closes. fn contains_a_sentence_boundary(text: &str) -> bool { let bytes = text.as_bytes(); bytes.iter().enumerate().any(|(i, &b)| { - if b != b'.' + if !matches!(b, b'.' | b'?' | b'!') || !bytes .get(i + 1) .is_none_or(|&next| next.is_ascii_whitespace()) { return false; } + if b != b'.' { + return true; + } // Walk back over the token this period ends — alphanumerics and // embedded periods only (`e.g.`'s own internal `.`), so surrounding // punctuation like a leading `(` isn't swept into the comparison @@ -425,11 +433,11 @@ fn extract_path_citations(markdown: &str) -> BTreeSet { let mut last_code_span: Option = None; // The active possessive owner within the current clause. let mut possessive_owner: Option = None; - // Whether a sentence-ending `.` has occurred since `possessive_owner` - // was last (re)confirmed — tracked separately from `inter_text` because - // that buffer gets cleared by asides and pending hyphenated spans - // (see [`continues_possessive_clause`]), which must not also erase the - // memory of an already-seen sentence boundary. + // Whether a sentence-ending `.`/`?`/`!` has occurred since + // `possessive_owner` was last (re)confirmed — tracked separately from + // `inter_text` because that buffer gets cleared by asides and pending + // hyphenated spans (see [`continues_possessive_clause`]), which must not + // also erase the memory of an already-seen sentence boundary. let mut sentence_boundary_seen = false; // Accumulate heading directories until End(Heading) commits them. @@ -958,6 +966,40 @@ mod tests { assert!(contains_a_sentence_boundary("done.")); } + #[test] + fn contains_a_sentence_boundary_detects_a_question_mark_and_an_exclamation_point() { + // Regression: only `.` was ever checked, so a clause ending in `?` + // or `!` instead of `.` didn't count as a sentence boundary — the + // owner would wrongly keep "continuing" into a different sentence. + assert!(contains_a_sentence_boundary("done? ")); + assert!(contains_a_sentence_boundary("done! ")); + } + + #[test] + fn extract_path_citations_does_not_leak_an_owner_across_a_sentence_boundary_ended_by_an_exclamation_point() + { + // End-to-end regression for the same gap: `runtime.rs` narrows to + // `engines/vllm`, but the clause must not continue past the `!` that + // ends its sentence — `state.rs` belongs to no possessive clause of + // its own and must fall back to the heading's full list, not inherit + // `engines/vllm`. + let markdown = "\ +### `engines/lemonade`, `engines/vllm` — inference engines + +`engines/vllm`'s `runtime.rs` is done! `state.rs` other. +"; + let citations = extract_path_citations(markdown); + let citation = citations + .iter() + .find(|c| c.text == "state.rs") + .expect("expected a state.rs citation"); + assert_eq!( + citation.section_dirs, + vec!["engines/lemonade".to_string(), "engines/vllm".to_string()], + "state.rs must not inherit engines/vllm across the `!` sentence boundary" + ); + } + #[test] fn extract_path_citations_recognizes_a_double_backtick_directory_citation() { let markdown = "See ``apps/rocm`` for the CLI entry point.\n"; @@ -1639,6 +1681,37 @@ Intro. `rocm-dash-tui`'s old thing was split into `agent/mod.rs`. ); } + #[test] + fn extract_path_citations_narrows_through_a_slash_qualified_owner_confirmed_after_an_earlier_sentence() + { + // Regression: the `sentence_boundary_seen = false` reset at the end + // of the main citation `Code` arm — the one that fires for every + // path-candidate span, not just the pending-hyphenated or aside + // cases above — is only exercised indirectly via + // `run_passes_against_the_real_doc`. Without it, an owner confirmed + // via the slash-qualified `'s` exact-match branch (`` `crates/ + // rocm-dash-tui`'s `` here) would still carry the earlier "Intro." + // sentence's boundary forward, failing the very next file's + // continuation check and falling back to the heading's full list + // instead of narrowing to `crates/rocm-dash-tui`. + let markdown = "\ +### `crates/rocm-dash-core`, `crates/rocm-dash-tui` — dashboard/telemetry + +Intro. `crates/rocm-dash-tui`'s `agent.rs` was split into `agent/mod.rs`. +"; + let citations = extract_path_citations(markdown); + let citation = citations + .iter() + .find(|c| c.text == "agent/mod.rs") + .expect("expected an agent/mod.rs citation"); + assert_eq!( + citation.section_dirs, + vec!["crates/rocm-dash-tui".to_string()], + "agent/mod.rs should narrow to crates/rocm-dash-tui even though \ + an earlier sentence in the same paragraph already ended" + ); + } + #[test] fn extract_path_citations_does_not_leak_an_owner_past_a_sentence_boundary_hidden_by_a_discarded_hyphenated_span() { From 14be823bb1f46005fd56a0d919348d0a71ebc889 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Tue, 6 Oct 2026 05:53:34 +0000 Subject: [PATCH 7/7] docs(architecture): revert rocm-dash-tui paragraph to natural prose #432 shipped a lead-in sentence chaining every rocm-dash-tui filename with literal 's/slash/and connectors, to unblock its own CI the moment #456's natural-prose version of this paragraph broke the then-stricter possessive-owner narrowing. With that narrowing now hardened to continue through ordinary prose, the workaround is no longer needed -- and leaving it in place meant the real doc never exercised the new continuation logic at all, since every citation still resolved through the old literal-connector chain. Revert to natural prose: each sentence that needs narrowing opens with its own explicit `rocm-dash-tui's` anchor directly before its first citation (the exact-match possessive step), and later citations in the same sentence rely on the new continue-through-any-text behavior, including through explanatory asides like `` `AgentClient` `` and `` `MouseEvent` `` -- exactly the shape #456's original prose had, and exactly what broke CI under the old narrower checker. This is the end-to-end proof #492 asked for: `cargo xtask check-architecture-doc` now passes this paragraph via the new continuation logic against the real doc, not just the unit tests. Fixes #492. Signed-off-by: Jussi Elo --- docs/architecture.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index 55f00694a5..bdc493ebc6 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -39,7 +39,7 @@ Already-extracted subsystem modules include `diagnose.rs`, `examine.rs`, `model_ ### `crates/rocm-dash-core`, `rocm-dash-collectors`, `rocm-dash-daemon`, `rocm-dash-tui` — dashboard/telemetry -`rocm-dash-tui`'s `agent/mod.rs`/`agent/snapshot.rs`/`agent/tools.rs`/`agent/clients.rs` and `app/mod.rs`/`app/types.rs`/`app/event_loop.rs`/`app/scrollbar.rs`/`app/actions.rs`/`app/chat.rs`/`app/slash.rs`/`app/summary.rs` are every file this phase's dashboard-TUI split touches. The old agent.rs was split into `agent/mod.rs` (the `AgentClient` seam, `AgentError`, `StateSnapshot`, `InferenceParams`, `REQUEST_TIMEOUT`), `agent/snapshot.rs` (pure JSON telemetry helpers with no `rig` dependency), `agent/tools.rs` (the `rig::tool::Tool` "Skill" wrappers and ROCm read/mutating tool dispatch), and `agent/clients.rs` (the `RigAgentClient`/`ChatGptAgentClient`/`AnthropicAgentClient`/`MockAgentClient` backends) — a mechanical relocation, since the shared seam types stay in `agent/mod.rs` and are reached from the split-out files via `super::`. `app/mod.rs` is modularized (ROCMAI-84, Phase 4 of EAI-7768's sequencing) into an app/ directory following full domain extraction: `app/types.rs` (shared type/enum defs — `Focus`, `ResolvedArgs`, connection/tab/chat/replay state, `Modal`, `UpdateStatus`, and the slash/plan/approval payload types; no `AppState` access), `app/event_loop.rs` (terminal lifecycle, signal handling, and the tick loop — `run`, `event_loop`, the termination-signal watcher, and the startup-focus / Updates-tile tick helpers), `app/scrollbar.rs` (mouse/scroll hit-testing: resolving a raw `MouseEvent` against recorded scrollbar tracks, the tab bar, and footer-legend chips into a `KeyAction`), `app/actions.rs` (`KeyAction` dispatch: translating a key press or resolved mouse hit into a `KeyAction` and applying it to reducer state). `app/mod.rs` keeps only `AppState`, its `apply_event`/`apply_action`-adjacent reducer impl, and the handful of items that stay with it (`ProviderSwitch`, `HISTORY_CAP`, `BENCH_CAP`) — the modularization effort's "reducer's reason to exist." `crate::app::*` paths for the public surface moved out are unchanged via re-exports from `app/mod.rs` (see the re-export block's comment for what counts as "public surface"). `app/chat.rs`, `app/slash.rs`, and `app/summary.rs` were previously extracted from `app/mod.rs` following the same mechanical-relocation convention this phase's agent.rs split mirrors. `crates/rocm-dash-tui/src/ui/approval.rs` is the shared component for approval-state prompts — reuse it rather than hand-rolling new approval UI. +`rocm-dash-tui`'s `agent/mod.rs` keeps the `AgentClient` seam (`AgentError`, `StateSnapshot`, `InferenceParams`, `REQUEST_TIMEOUT`) that the old agent.rs was split into, alongside `agent/snapshot.rs` (pure JSON telemetry helpers with no `rig` dependency), `agent/tools.rs` (the `rig::tool::Tool` "Skill" wrappers and ROCm read/mutating tool dispatch), and `agent/clients.rs` (the `RigAgentClient`/`ChatGptAgentClient`/`AnthropicAgentClient`/`MockAgentClient` backends) — a mechanical relocation, since the shared seam types stay in `agent/mod.rs` and are reached from the split-out files via `super::`. `rocm-dash-tui`'s `app/mod.rs` is modularized (ROCMAI-84, Phase 4 of EAI-7768's sequencing) into an app/ directory following full domain extraction into `app/types.rs` (shared type/enum defs — `Focus`, `ResolvedArgs`, connection/tab/chat/replay state, `Modal`, `UpdateStatus`, and the slash/plan/approval payload types; no `AppState` access), `app/event_loop.rs` (terminal lifecycle, signal handling, and the tick loop — `run`, `event_loop`, the termination-signal watcher, and the startup-focus / Updates-tile tick helpers), `app/scrollbar.rs` (mouse/scroll hit-testing: resolving a raw `MouseEvent` against recorded scrollbar tracks, the tab bar, and footer-legend chips into a `KeyAction`), and `app/actions.rs` (`KeyAction` dispatch: translating a key press or resolved mouse hit into a `KeyAction` and applying it to reducer state). `app/mod.rs` keeps only `AppState`, its `apply_event`/`apply_action`-adjacent reducer impl, and the handful of items that stay with it (`ProviderSwitch`, `HISTORY_CAP`, `BENCH_CAP`) — the modularization effort's "reducer's reason to exist." `crate::app::*` paths for the public surface moved out are unchanged via re-exports from `app/mod.rs` (see the re-export block's comment for what counts as "public surface"). `rocm-dash-tui`'s `app/chat.rs`, `app/slash.rs`, and `app/summary.rs` were previously extracted from `app/mod.rs` following the same mechanical-relocation convention this phase's agent.rs split mirrors. `crates/rocm-dash-tui/src/ui/approval.rs` is the shared component for approval-state prompts — reuse it rather than hand-rolling new approval UI. ### `crates/rocm-engine-protocol` — engine IPC protocol