Skip to content

Harden check-architecture-doc's possessive-owner narrowing against ordinary prose #492

Closed

Description

@jussielo-amd

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions