Repository navigation
Description
Context
#432 added cargo xtask check-architecture-doc, which guards docs/architecture.md's backtick-quoted path citations against drift. Its extract_path_citations narrows a bare/slash citation to one specific crate (instead of every crate a multi-crate heading names) only when it's directly chained to a possessive owner via one of exactly three literal connectors: 's, /, or and. Any other backtick span between two citations that isn't itself a path candidate (a type name like AgentClient) fully resets that chain state, and the connector check itself only recognizes those three exact tokens - not ordinary English list punctuation (commas, parentheses).
While #432 was in review, #456 (ROCMAI-51, the rocm-dash-tui agent.rs modularization) merged into main and rewrote the rocm-dash-tui doc section to narrate the split: agent.rs was split into agent/mod.rs (the AgentClient seam, ...), agent/snapshot.rs (...), ..., and agent/clients.rs (...). Real prose like this embeds explanatory type-name asides and comma-separated lists between citations - exactly what the connector heuristic can't parse - so every citation after the first lost its narrowing and fell back to the full four-crate heading scope, which none of them satisfy (they only exist under rocm-dash-tui). That broke CI on #432 itself (the architecture-doc gate, and the run_passes_against_the_real_doc unit test caught on the Windows job) the moment the two PRs' content combined.
#432 shipped an immediate, narrow fix for its own CI: a lead-in sentence chaining every filename with literal //and connectors, plus de-backticking the three mentions of the now fully-removed agent.rs (that part is correct regardless of narrowing robustness - the file doesn't exist, full stop). The slash-chain reads awkwardly, though, and the underlying gap will keep recurring: any future modularization PR that documents a multi-file split in ordinary English will hit the same false failure.
Proposal
Harden extract_path_citations's possessive-owner narrowing in xtask/src/architecture_doc.rs:
- An intervening non-candidate backtick span (a type name, an identifier) should no longer wipe the active owner - it should be transparent to the chain rather than a hard reset.
- The connector check should tolerate ordinary list punctuation (commas, parentheses) around 's/
//and, matching how a contributor naturally writes "X, Y, and Z" or "X (...), Y (...)". - A sentence-ending period in the accumulated text between two citations must still hard-stop the clause unconditionally - this is the safety net against a later, unrelated sentence silently inheriting an earlier owner (the masking failure mode this scoping feature exists to prevent).
Once this lands, revert #432's slash-chain workaround in docs/architecture.md back to natural prose, as the end-to-end proof.
Non-goals
- Not a "narrow once, trust for the rest of the heading" rewrite - that was considered and rejected because it reintroduces the exact masking risk this checker exists to prevent.
- No behavior change to citation existence checking, root-level extensions, or heading-directory collection - scoped entirely to the inline connector/owner-tracking state machine.
Activity
fix(xtask): harden arch-doc checker's possessive-owner narrowing
fix(xtask): harden arch-doc checker's possessive-owner narrowing
docs(architecture): revert rocm-dash-tui paragraph to natural prose
docs(architecture): rewrite citations as links, delete arch-doc checker
docs(architecture): rewrite citations as links, delete arch-doc checker
docs(architecture): rewrite citations as links, delete arch-doc checker
docs(architecture): rewrite citations as links, delete arch-doc checker
docs(architecture): rewrite citations as links, delete arch-doc checker
docs(architecture): rewrite citations as links, delete arch-doc check…