From 0df1ab878f2023bf59ece1c2a27c42247917b7d9 Mon Sep 17 00:00:00 2001 From: Teemu Kuusisto Date: Tue, 8 Sep 2026 16:59:40 +0000 Subject: [PATCH 01/11] docs(dash): drop doc-comment pointers to documents that do not exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Module docs cited 18 `../wiki/…` markdown paths across 14 files. No `wiki/` directory has ever existed in the tree or anywhere in git history, and the project has no GitHub wiki. The paths were also mutually inconsistent about depth (`../`, `../../`, `../../../`), and every one sat inside backticks, so none of them ever rendered as a link even where a target might have existed. None of the 14 cited documents exists anywhere, so each pointer is either removed or replaced with a short explanation inline in the file it was meant to send the reader away from. One further citation of the same class, a bare `rocm-cli-unification-working-agreements.md`, was equally unresolvable and is fixed here too. Signed-off-by: Teemu Kuusisto --- crates/rocm-dash-collectors/src/amd_smi.rs | 2 +- crates/rocm-dash-collectors/src/docker.rs | 1 - crates/rocm-dash-collectors/src/vllm_log.rs | 1 - crates/rocm-dash-collectors/src/vllm_prom.rs | 2 +- crates/rocm-dash-core/src/bench_rollup.rs | 7 +++---- crates/rocm-dash-core/src/bench_schema.rs | 1 - crates/rocm-dash-core/src/efficiency.rs | 2 +- crates/rocm-dash-core/src/lib.rs | 4 +++- crates/rocm-dash-core/src/metrics.rs | 1 - crates/rocm-dash-core/src/partition.rs | 2 +- crates/rocm-dash-core/src/protocol.rs | 1 - crates/rocm-dash-core/src/state.rs | 1 - crates/rocm-dash-core/src/vram.rs | 2 +- crates/rocm-dash-tui/src/ui/approval.rs | 3 +-- crates/rocm-dash-tui/src/ui/theme.rs | 2 +- 15 files changed, 13 insertions(+), 19 deletions(-) diff --git a/crates/rocm-dash-collectors/src/amd_smi.rs b/crates/rocm-dash-collectors/src/amd_smi.rs index f19e20b82d..b8d2aaf794 100644 --- a/crates/rocm-dash-collectors/src/amd_smi.rs +++ b/crates/rocm-dash-collectors/src/amd_smi.rs @@ -5,7 +5,7 @@ //! amd-smi subprocess + JSON parse. //! //! Field paths and the KFD pre-flight check are vendored from the TypeScript -//! `AmdSmiProvider` in instinct-dash. See `../wiki/entities/amd-smi.md`. +//! `AmdSmiProvider` in instinct-dash. use std::ffi::OsString; use std::io; diff --git a/crates/rocm-dash-collectors/src/docker.rs b/crates/rocm-dash-collectors/src/docker.rs index b034d7c8cd..34df674cb1 100644 --- a/crates/rocm-dash-collectors/src/docker.rs +++ b/crates/rocm-dash-collectors/src/docker.rs @@ -6,7 +6,6 @@ //! //! Field-extraction logic is vendored from instinct-dash `DockerService.ts` //! (HIP_VISIBLE_DEVICES → gpu_ids, `--tensor-parallel-size`/`-tp`, etc.). -//! See `../../wiki/entities/dockerode.md`. //! //! The async inherent methods are the public API. The `ServiceDiscovery` trait //! impl is sync-only and returns `Unsupported`: bollard requires a tokio diff --git a/crates/rocm-dash-collectors/src/vllm_log.rs b/crates/rocm-dash-collectors/src/vllm_log.rs index a501d72fb0..7494b88627 100644 --- a/crates/rocm-dash-collectors/src/vllm_log.rs +++ b/crates/rocm-dash-collectors/src/vllm_log.rs @@ -3,7 +3,6 @@ // SPDX-License-Identifier: MIT //! vLLM log slicer — verbatim port of `inspect_bench/log_slicer.py`. -//! See `../wiki/entities/log-slicer.md` and `../wiki/concepts/log-derived-metrics.md`. use regex::Regex; diff --git a/crates/rocm-dash-collectors/src/vllm_prom.rs b/crates/rocm-dash-collectors/src/vllm_prom.rs index 70f559db5a..a6eaf7bf67 100644 --- a/crates/rocm-dash-collectors/src/vllm_prom.rs +++ b/crates/rocm-dash-collectors/src/vllm_prom.rs @@ -5,7 +5,7 @@ //! vLLM Prometheus `/metrics` scraper. //! //! Field paths and the kv-cache 0..1 → 0..100 scaling are vendored from -//! instinct-dash `VllmMetricsService.ts`. See `../../wiki/entities/vllm.md`. +//! instinct-dash `VllmMetricsService.ts`. //! //! Sync `InstanceMetrics::fetch` returns `Unsupported` (the underlying client //! is async); call `fetch_async` from the runner. diff --git a/crates/rocm-dash-core/src/bench_rollup.rs b/crates/rocm-dash-core/src/bench_rollup.rs index f134cfac43..1c635a82df 100644 --- a/crates/rocm-dash-core/src/bench_rollup.rs +++ b/crates/rocm-dash-core/src/bench_rollup.rs @@ -8,10 +8,9 @@ //! it whenever the row set changes rather than relying on the upstream //! `pass_n_of_n` / `pass_at_n` CSV columns. //! -//! See `../wiki/concepts/benchmark-result-schema.md` and -//! `../wiki/entities/normalize-results.md`: rows are grouped by -//! `(cell, model, backend, concurrency)` and each group of N trials yields -//! two verdicts — strict (all N passed) and lenient (at least one passed). +//! Rows are grouped by `(cell, model, backend, concurrency)`; each group of N +//! trials yields two verdicts — strict (all N passed) and lenient (at least +//! one passed). use std::collections::BTreeMap; diff --git a/crates/rocm-dash-core/src/bench_schema.rs b/crates/rocm-dash-core/src/bench_schema.rs index 4090b6a4de..ce5aa70359 100644 --- a/crates/rocm-dash-core/src/bench_schema.rs +++ b/crates/rocm-dash-core/src/bench_schema.rs @@ -3,7 +3,6 @@ // SPDX-License-Identifier: MIT //! Benchmark row schema, vendored from instinct-agent-bench. -//! See `../wiki/concepts/benchmark-result-schema.md` and `../wiki/entities/csv-emitter.md`. use serde::{Deserialize, Serialize}; diff --git a/crates/rocm-dash-core/src/efficiency.rs b/crates/rocm-dash-core/src/efficiency.rs index 072b022639..c45854b6b1 100644 --- a/crates/rocm-dash-core/src/efficiency.rs +++ b/crates/rocm-dash-core/src/efficiency.rs @@ -5,7 +5,7 @@ //! Pure efficiency derivations (tokens-per-watt). No I/O, no rendering. //! //! This is the join that turns vLLM throughput + amd-smi power into a -//! per-instance capacity number. See `../wiki/concepts/metric-registry.md`. +//! per-instance capacity number. use crate::metrics::GpuMetrics; diff --git a/crates/rocm-dash-core/src/lib.rs b/crates/rocm-dash-core/src/lib.rs index 3af02af7df..ac73930ade 100644 --- a/crates/rocm-dash-core/src/lib.rs +++ b/crates/rocm-dash-core/src/lib.rs @@ -7,7 +7,9 @@ //! Pure types, traits, schemas, and the reducer for rocm-dash. //! No rendering deps. No async deps at the type boundary. //! -//! See `../wiki/concepts/tea-reducer-pattern.md` for the architectural pattern. +//! The reducer is Elm-style: `state::State::apply` folds a `StateEvent` into +//! `State` and returns the `SideEffect`s the async layer performs, so every +//! state transition stays pure and testable. pub mod bench_rollup; pub mod bench_schema; diff --git a/crates/rocm-dash-core/src/metrics.rs b/crates/rocm-dash-core/src/metrics.rs index 6e2282afa8..00cffee957 100644 --- a/crates/rocm-dash-core/src/metrics.rs +++ b/crates/rocm-dash-core/src/metrics.rs @@ -3,7 +3,6 @@ // SPDX-License-Identifier: MIT //! Live metric types. snake_case + units encoded in field names. -//! See `../wiki/concepts/metric-registry.md` and `../wiki/data/metric-field-index.md`. use chrono::{DateTime, Utc}; use serde::{Deserialize, Serialize}; diff --git a/crates/rocm-dash-core/src/partition.rs b/crates/rocm-dash-core/src/partition.rs index 6f7706623a..3aa94bb6e7 100644 --- a/crates/rocm-dash-core/src/partition.rs +++ b/crates/rocm-dash-core/src/partition.rs @@ -2,7 +2,7 @@ // // SPDX-License-Identifier: MIT -//! GPU partition mode enums. See `../wiki/concepts/gpu-partition-modes.md`. +//! GPU partition mode enums. use serde::{Deserialize, Serialize}; diff --git a/crates/rocm-dash-core/src/protocol.rs b/crates/rocm-dash-core/src/protocol.rs index 01e9888b3c..6dd2a5cbc6 100644 --- a/crates/rocm-dash-core/src/protocol.rs +++ b/crates/rocm-dash-core/src/protocol.rs @@ -3,7 +3,6 @@ // SPDX-License-Identifier: MIT //! NDJSON command/event protocol between rocmdashd and rocmdash. -//! See `../wiki/comparisons/ctux-vs-rocm-dash.md` (resolved decisions). use serde::{Deserialize, Serialize}; diff --git a/crates/rocm-dash-core/src/state.rs b/crates/rocm-dash-core/src/state.rs index b2d53cffaf..eff7f1ab71 100644 --- a/crates/rocm-dash-core/src/state.rs +++ b/crates/rocm-dash-core/src/state.rs @@ -3,7 +3,6 @@ // SPDX-License-Identifier: MIT //! Pure reducer. `State::apply(StateEvent) -> Vec`. -//! See `../wiki/concepts/tea-reducer-pattern.md`. use std::collections::{HashMap, VecDeque}; use std::sync::Arc; diff --git a/crates/rocm-dash-core/src/vram.rs b/crates/rocm-dash-core/src/vram.rs index 5752b45901..98fd294809 100644 --- a/crates/rocm-dash-core/src/vram.rs +++ b/crates/rocm-dash-core/src/vram.rs @@ -17,7 +17,7 @@ //! //! Graceful degradation: an instance that matches nothing (empty `gpu_ids`, //! no container entry — e.g. Lemonade) resolves to `(0, 0)`, never a panic and -//! never a confidently-wrong number. See `../wiki/concepts/metric-registry.md`. +//! never a confidently-wrong number. use std::collections::HashMap; diff --git a/crates/rocm-dash-tui/src/ui/approval.rs b/crates/rocm-dash-tui/src/ui/approval.rs index e2cc124023..a7abf9543b 100644 --- a/crates/rocm-dash-tui/src/ui/approval.rs +++ b/crates/rocm-dash-tui/src/ui/approval.rs @@ -6,8 +6,7 @@ //! //! This is a **render + event seam ONLY**. The decision *logic* — what an //! approval actually does (run a CLI command, enable full access, approve a -//! proposal) — stays CLI-side per the working agreement -//! (`rocm-cli-unification-working-agreements.md` §1). This module renders an +//! proposal) — stays CLI-side by design. This module renders an //! [`ApprovalRequest`] and reports the user's [`ApprovalVerdict`]; the caller //! maps the verdict onto a CLI-side action. //! diff --git a/crates/rocm-dash-tui/src/ui/theme.rs b/crates/rocm-dash-tui/src/ui/theme.rs index 98b5a79d07..e7106c5681 100644 --- a/crates/rocm-dash-tui/src/ui/theme.rs +++ b/crates/rocm-dash-tui/src/ui/theme.rs @@ -11,7 +11,7 @@ //! sourced from each project's published palette. Theme catalogue //! inspired by [ansicolor.com](https://ansicolor.com/). //! -//! Pattern borrowed from ctux (see `../../../wiki/sources/ctux.md`). +//! Pattern borrowed from ctux. use ratatui::style::{Color, Modifier, Style}; From d3c1d2538c960fdd0c6c2bc1ca7d5b3c8d449031 Mon Sep 17 00:00:00 2001 From: Teemu Kuusisto Date: Tue, 8 Sep 2026 16:59:50 +0000 Subject: [PATCH 02/11] ci(xtask): fail the build when a doc comment cites a missing file `cargo xtask verify-doc-paths` scans `//!` and `///` lines in tracked `.rs` files for citations of `.md` files and resolves each one against the citing file's own directory or the workspace root, both of which this tree uses. Every violation is reported at once rather than only the first. The check runs in the existing `clippy` CI job. `**/*.md` joins the `rust` path filter so that deleting or renaming a cited markdown file also triggers it, even when the change touches no `.rs` file. URLs and lines outside doc comments are deliberately ignored: ordinary code names `.md` files legitimately in string literals, and flagging those would make the check unusable. Signed-off-by: Teemu Kuusisto --- .github/workflows/ci.yml | 8 ++ xtask/src/doc_paths.rs | 298 +++++++++++++++++++++++++++++++++++++++ xtask/src/main.rs | 7 + 3 files changed, 313 insertions(+) create mode 100644 xtask/src/doc_paths.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 15e3bdc290..12330ff0d4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -100,6 +100,10 @@ jobs: - 'rust-toolchain*' # clippy runs `cargo xtask manifest --check` against this file. - 'MANIFEST.md' + # clippy also runs `cargo xtask verify-doc-paths`, so deleting or + # renaming a doc file can break a doc-comment citation with no + # *.rs file in the change. + - '**/*.md' # rocm-deps compiles the pins into constants, so a pin change is a # source change even though no *.rs file moved. - 'runtime-deps.toml' @@ -738,6 +742,10 @@ jobs: if: needs.changes.outputs.rust == 'true' run: cargo xtask manifest --check + - name: Doc-comment paths resolve + if: needs.changes.outputs.rust == 'true' + run: cargo xtask verify-doc-paths + # Surface the cache hit rate for the clippy compile so the effect is visible # in the logs, on the local-only path too — see build-and-test for why this # is gated on sccache being present rather than on the remote backend being diff --git a/xtask/src/doc_paths.rs b/xtask/src/doc_paths.rs new file mode 100644 index 0000000000..b9112f7555 --- /dev/null +++ b/xtask/src/doc_paths.rs @@ -0,0 +1,298 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Assert every relative documentation path cited in a Rust doc comment +//! resolves to a file in the tree. +//! +//! Doc comments accumulated citations of markdown files that had never existed +//! (a whole `../wiki/…` tree of them). Nothing pointed the reader anywhere: +//! `rustdoc` does not resolve a bare path in prose, so a dangling citation is +//! invisible to the compiler, to clippy, and to review. This check makes the +//! next one fail CI instead. +//! +//! Design notes: +//! +//! - **Doc lines only.** Only lines whose trimmed text starts with `//!` or +//! `///` are scanned. Ordinary code mentions `.md` files legitimately — a +//! `format!("{dist}/README.md")` naming an artifact that exists only after a +//! build, a shell command embedded in a workflow-contract test — and those are +//! not citations to resolve. +//! - **No backtick requirement.** Citations in this tree appear both quoted and +//! bare (`docs/ux-guidelines.md` in `app/summary.rs` is bare), so requiring +//! backticks would miss the majority of them. +//! - **Two resolution roots.** A candidate passes if it resolves next to the +//! citing file (the `./` and `../` forms) *or* against the workspace root (the +//! `docs/…` and bare `README.md`/`AGENTS.md` forms). Both are how the tree +//! actually cites files, and accepting either keeps the check free of +//! false positives without weakening it: a name that resolves under neither +//! root points at nothing. +//! - **Every violation, once.** Failures are collected and reported together. +//! Reporting only the first would cost one CI round trip per dangling path. +//! +//! Matching is hand-rolled rather than regex-based to keep xtask's dependency +//! set as-is; the pure helpers take their inputs as parameters so they are +//! unit-testable without touching process-global state. + +use std::path::{Path, PathBuf}; +use std::process::Command; + +use anyhow::{Context, Result, bail}; + +/// Characters that may appear in a cited path. +/// +/// Deliberately excludes the placeholder delimiters (`{`, `<`) and quoting +/// characters (backtick, parenthesis, comma), so those terminate a candidate +/// rather than becoming part of it. +const fn is_path_char(c: char) -> bool { + c.is_ascii_alphanumeric() || matches!(c, '_' | '.' | '@' | '/' | '-') +} + +/// Characters that mark a candidate as a placeholder rather than a real path, +/// when they sit immediately either side of it (`.md`, `{dist}/x.md`). +const fn is_placeholder_delimiter(c: char) -> bool { + matches!(c, '{' | '}' | '<' | '>') +} + +/// Drop whitespace-separated tokens that contain a URL scheme separator, so an +/// external link ending in `.md` is never mistaken for a path in the tree. +fn strip_urls(text: &str) -> String { + text.split_whitespace() + .filter(|token| !token.contains("://")) + .collect::>() + .join(" ") +} + +/// Candidate `.md` paths in one doc-comment line's text. +fn candidates_in_line(text: &str) -> Vec { + let text = strip_urls(text); + let chars: Vec = text.chars().collect(); + let mut found = Vec::new(); + let mut start = 0; + while start < chars.len() { + if !is_path_char(chars[start]) { + start += 1; + continue; + } + let mut end = start; + while end < chars.len() && is_path_char(chars[end]) { + end += 1; + } + let run: String = chars[start..end].iter().collect(); + // Trailing sentence punctuation is a path character, so `docs/x.md.` + // would otherwise not look like a citation. + let candidate = run.trim_end_matches('.'); + let before = start.checked_sub(1).map(|i| chars[i]); + let after = chars.get(end).copied(); + let placeholder = before.is_some_and(is_placeholder_delimiter) + || after.is_some_and(is_placeholder_delimiter); + // A bare `.md` is the tail of a split placeholder like `{name}.md` + // rather than a path, so the stem must be non-empty; an absolute path is + // not a repo-relative citation. The suffix match is deliberately + // case-sensitive — every markdown file in this tree is `.md`. + let named = candidate + .strip_suffix(".md") + .is_some_and(|stem| !stem.is_empty()); + if named && !candidate.starts_with('/') && !placeholder { + found.push(candidate.to_owned()); + } + start = end; + } + found +} + +/// Every `.md` path cited in a doc comment in `source`, as `(line number, path)` +/// with 1-based line numbers. Non-doc lines are ignored, and a path cited twice +/// on one line is reported once. +pub fn extract_citations(source: &str) -> Vec<(usize, String)> { + let mut citations: Vec<(usize, String)> = Vec::new(); + for (index, line) in source.lines().enumerate() { + let trimmed = line.trim_start(); + let Some(text) = trimmed + .strip_prefix("//!") + .or_else(|| trimmed.strip_prefix("///")) + else { + continue; + }; + let line_number = index + 1; + for candidate in candidates_in_line(text) { + if !citations.iter().any(|(existing_line, existing)| { + *existing_line == line_number && *existing == candidate + }) { + citations.push((line_number, candidate)); + } + } + } + citations +} + +/// Whether `candidate` names a file, resolved either next to the citing file or +/// against the workspace root. +pub fn resolve(candidate: &str, file_dir: &Path, root: &Path) -> bool { + file_dir.join(candidate).is_file() || root.join(candidate).is_file() +} + +/// All tracked `*.rs` files, excluding `third_party/`, as paths relative to `root`. +fn discover_rust_files(root: &Path) -> Result> { + let output = Command::new("git") + .current_dir(root) + .args(["ls-files", "*.rs"]) + .output() + .context("failed to run `git ls-files`")?; + if !output.status.success() { + bail!( + "`git ls-files` failed: {}", + String::from_utf8_lossy(&output.stderr).trim() + ); + } + Ok(String::from_utf8_lossy(&output.stdout) + .lines() + .map(str::trim) + .filter(|line| !line.is_empty() && !line.starts_with("third_party/")) + .map(PathBuf::from) + .collect()) +} + +/// Verify every documentation path cited in a Rust doc comment resolves. +pub fn run() -> Result<()> { + let root = crate::paths::workspace_root()?; + let files = discover_rust_files(&root)?; + + let mut violations = Vec::new(); + let mut checked = 0usize; + for file in &files { + let path = root.join(file); + let source = std::fs::read_to_string(&path) + .with_context(|| format!("failed to read {}", file.display()))?; + let file_dir = path + .parent() + .map_or_else(|| root.clone(), Path::to_path_buf); + for (line, candidate) in extract_citations(&source) { + checked += 1; + if !resolve(&candidate, &file_dir, &root) { + violations.push(format!( + "{}:{line}: doc comment cites `{candidate}`, which does not resolve to a \ + file in the tree", + file.display() + )); + } + } + } + + if !violations.is_empty() { + bail!( + "{} dangling documentation path(s) cited in doc comments:\n{}", + violations.len(), + violations.join("\n") + ); + } + println!( + "doc paths: {checked} citation(s) across {} file(s) resolve.", + files.len() + ); + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn extracts_from_doc_lines_only() { + let source = "//! Module doc, see docs/a.md for details.\n\ + /// Item doc, see `docs/b.md`.\n\ + // Ordinary comment about docs/c.md.\n\ + let path = docs_d_md;\n"; + assert_eq!( + extract_citations(source), + vec![(1, "docs/a.md".to_owned()), (2, "docs/b.md".to_owned())] + ); + } + + #[test] + fn ignores_md_in_a_string_literal_on_a_code_line() { + // The shape that made a naive whole-file scan unusable: real code names + // build artifacts and shell commands that are not citations. + let source = "let readme = format!(\"{dist}/README.md\");\n\ + assert!(jobs.contains(\"base64 -w0 regenerated/MANIFEST.md > manifest.b64\"));\n\ + let inputs = [\"docs/guide.md\".to_string()];\n"; + assert!(extract_citations(source).is_empty()); + } + + #[test] + fn ignores_urls_ending_in_md() { + let source = "//! See https://example.com/docs/remote.md for the upstream note.\n\ + /// Mirrored at .\n"; + assert!(extract_citations(source).is_empty()); + } + + #[test] + fn ignores_placeholder_and_absolute_paths() { + let source = "//! Writes `.md` under the bundle, or /etc/motd.md on request.\n"; + assert!(extract_citations(source).is_empty()); + } + + #[test] + fn strips_trailing_sentence_punctuation() { + let source = "//! Refer to docs/ux-guidelines.md.\n"; + assert_eq!( + extract_citations(source), + vec![(1, "docs/ux-guidelines.md".to_owned())] + ); + } + + #[test] + fn reports_a_repeated_citation_on_one_line_once() { + let source = "//! docs/a.md and again docs/a.md, plus docs/b.md.\n"; + assert_eq!( + extract_citations(source), + vec![(1, "docs/a.md".to_owned()), (1, "docs/b.md".to_owned())] + ); + } + + #[test] + fn resolves_relative_to_the_citing_file_and_to_the_root() { + let temp = tempfile::tempdir().expect("tempdir"); + let root = temp.path(); + std::fs::create_dir_all(root.join("docs")).expect("docs dir"); + std::fs::create_dir_all(root.join("crates/thing/src")).expect("src dir"); + std::fs::write(root.join("README.md"), "readme").expect("readme"); + std::fs::write(root.join("docs/x.md"), "x").expect("docs file"); + std::fs::write(root.join("crates/thing/sibling.md"), "sibling").expect("sibling"); + let file_dir = root.join("crates/thing/src"); + + assert!(resolve("../sibling.md", &file_dir, root)); + assert!(resolve("docs/x.md", &file_dir, root)); + assert!(resolve("README.md", &file_dir, root)); + // A directory is not a file, and neither form of a missing path resolves. + assert!(!resolve("docs", &file_dir, root)); + assert!(!resolve("../wiki/foo.md", &file_dir, root)); + assert!(!resolve("foo.md", &file_dir, root)); + } + + #[test] + fn flags_every_unresolvable_citation_not_just_the_first() { + // The regression this check exists for: a `../wiki/…` tree that never + // existed, plus a bare filename that resolves against neither root. + let temp = tempfile::tempdir().expect("tempdir"); + let root = temp.path(); + std::fs::create_dir_all(root.join("crates/thing/src")).expect("src dir"); + std::fs::write(root.join("README.md"), "readme").expect("readme"); + let file_dir = root.join("crates/thing/src"); + + let source = "//! See `../wiki/concepts/metric-registry.md`.\n\ + //! And `rocm-cli-unification-working-agreements.md`.\n\ + //! And README.md, which is fine.\n"; + let unresolved: Vec<_> = extract_citations(source) + .into_iter() + .filter(|(_, candidate)| !resolve(candidate, &file_dir, root)) + .collect(); + assert_eq!( + unresolved, + vec![ + (1, "../wiki/concepts/metric-registry.md".to_owned()), + (2, "rocm-cli-unification-working-agreements.md".to_owned()), + ] + ); + } +} diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 291d0de0a0..0a58f18488 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -12,6 +12,7 @@ mod affected; mod demos; +mod doc_paths; mod e2e; mod e2e_prewarm; mod e2e_report; @@ -79,6 +80,11 @@ enum Command { /// `docs/keys/`, and that any configured CI signing key matches the pinned /// current release key. A no-op while no canonical keys are published. VerifyPinnedKeys, + /// Assert every relative documentation path cited in a Rust doc comment + /// (`//!` or `///`) resolves to a file, either next to the citing file or + /// against the workspace root. `rustdoc` does not resolve such paths, so a + /// citation of a file that never existed is otherwise invisible. + VerifyDocPaths, /// Print the workspace crates affected by a git range (changed crates plus /// their transitive dependents) as `cargo` package-selection flags, so CI /// can build/test only what a change can reach instead of `--workspace`. @@ -240,6 +246,7 @@ fn run() -> Result<()> { signature, } => signing::verify(public_key.as_deref(), &input, &signature)?, Command::VerifyPinnedKeys => verify_pinned_keys::run()?, + Command::VerifyDocPaths => doc_paths::run()?, Command::Affected { base } => affected::run(base)?, Command::Manifest { check } => manifest::run(check)?, Command::Tpn { From a83764894d6c0c725d4c9546c71c3bbf01da405e Mon Sep 17 00:00:00 2001 From: Teemu Kuusisto Date: Tue, 8 Sep 2026 17:57:58 +0000 Subject: [PATCH 03/11] fix(xtask): stop the doc-path check flagging its own test fixtures MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `cargo xtask verify-doc-paths` failed on the file that implements it. The scan is line-based, and the test fixtures were multi-line string literals joined with a trailing backslash, so each continuation line began with `//!` or `///` once its indentation was trimmed. Two lines of fixture data — paths chosen precisely because they resolve to nothing — were read as real citations on `doc_paths.rs` itself. Building the fixtures with `concat!` keeps the prefix off the start of a line and leaves what each test asserts untouched. The paths they carry are now neutral placeholders: the check's acceptance criterion is that no `.rs` file in the tree names the directory that motivated it, and a test fixture is no exception. Both unresolvable shapes are still covered, the `../`-prefixed form and the bare filename. A design note records the limitation, since the same shape can bite a doc comment that quotes source or holds a fenced code block. Signed-off-by: Teemu Kuusisto --- xtask/src/doc_paths.rs | 58 +++++++++++++++++++++++++++--------------- 1 file changed, 38 insertions(+), 20 deletions(-) diff --git a/xtask/src/doc_paths.rs b/xtask/src/doc_paths.rs index b9112f7555..b41f406fff 100644 --- a/xtask/src/doc_paths.rs +++ b/xtask/src/doc_paths.rs @@ -6,10 +6,10 @@ //! resolves to a file in the tree. //! //! Doc comments accumulated citations of markdown files that had never existed -//! (a whole `../wiki/…` tree of them). Nothing pointed the reader anywhere: -//! `rustdoc` does not resolve a bare path in prose, so a dangling citation is -//! invisible to the compiler, to clippy, and to review. This check makes the -//! next one fail CI instead. +//! — a whole tree of them, under a directory this repository never had. Nothing +//! pointed the reader anywhere: `rustdoc` does not resolve a bare path in prose, +//! so a dangling citation is invisible to the compiler, to clippy, and to +//! review. This check makes the next one fail CI instead. //! //! Design notes: //! @@ -27,6 +27,11 @@ //! actually cites files, and accepting either keeps the check free of //! false positives without weakening it: a name that resolves under neither //! root points at nothing. +//! - **Lines, not tokens.** The scan is line-based, so a multi-line string +//! literal whose continuation lines start with `//!` or `///` reads as a doc +//! comment. The fixtures below use `concat!` to keep that prefix off the start +//! of a line; a doc comment inside a fenced code block is scanned for the same +//! reason, and none in this tree names a `.md` file. //! - **Every violation, once.** Failures are collected and reported together. //! Reporting only the first would cost one CI round trip per dangling path. //! @@ -199,10 +204,12 @@ mod tests { #[test] fn extracts_from_doc_lines_only() { - let source = "//! Module doc, see docs/a.md for details.\n\ - /// Item doc, see `docs/b.md`.\n\ - // Ordinary comment about docs/c.md.\n\ - let path = docs_d_md;\n"; + let source = concat!( + "//! Module doc, see docs/a.md for details.\n", + "/// Item doc, see `docs/b.md`.\n", + "// Ordinary comment about docs/c.md.\n", + "let path = docs_d_md;\n", + ); assert_eq!( extract_citations(source), vec![(1, "docs/a.md".to_owned()), (2, "docs/b.md".to_owned())] @@ -213,16 +220,20 @@ mod tests { fn ignores_md_in_a_string_literal_on_a_code_line() { // The shape that made a naive whole-file scan unusable: real code names // build artifacts and shell commands that are not citations. - let source = "let readme = format!(\"{dist}/README.md\");\n\ - assert!(jobs.contains(\"base64 -w0 regenerated/MANIFEST.md > manifest.b64\"));\n\ - let inputs = [\"docs/guide.md\".to_string()];\n"; + let source = concat!( + "let readme = format!(\"{dist}/README.md\");\n", + "assert!(jobs.contains(\"base64 -w0 regenerated/MANIFEST.md > manifest.b64\"));\n", + "let inputs = [\"docs/guide.md\".to_string()];\n", + ); assert!(extract_citations(source).is_empty()); } #[test] fn ignores_urls_ending_in_md() { - let source = "//! See https://example.com/docs/remote.md for the upstream note.\n\ - /// Mirrored at .\n"; + let source = concat!( + "//! See https://example.com/docs/remote.md for the upstream note.\n", + "/// Mirrored at .\n", + ); assert!(extract_citations(source).is_empty()); } @@ -230,6 +241,11 @@ mod tests { fn ignores_placeholder_and_absolute_paths() { let source = "//! Writes `.md` under the bundle, or /etc/motd.md on request.\n"; assert!(extract_citations(source).is_empty()); + // A placeholder butting straight up against a filename, with no path + // separator to end the run: adjacency is the only thing that rules this + // out, so the case fails if that check is ever dropped. + let source = "//! Writes `{version}CHANGELOG.md` beside the archive.\n"; + assert!(extract_citations(source).is_empty()); } #[test] @@ -266,13 +282,13 @@ mod tests { assert!(resolve("README.md", &file_dir, root)); // A directory is not a file, and neither form of a missing path resolves. assert!(!resolve("docs", &file_dir, root)); - assert!(!resolve("../wiki/foo.md", &file_dir, root)); + assert!(!resolve("../elsewhere/foo.md", &file_dir, root)); assert!(!resolve("foo.md", &file_dir, root)); } #[test] fn flags_every_unresolvable_citation_not_just_the_first() { - // The regression this check exists for: a `../wiki/…` tree that never + // The regression this check exists for: a relative tree that never // existed, plus a bare filename that resolves against neither root. let temp = tempfile::tempdir().expect("tempdir"); let root = temp.path(); @@ -280,9 +296,11 @@ mod tests { std::fs::write(root.join("README.md"), "readme").expect("readme"); let file_dir = root.join("crates/thing/src"); - let source = "//! See `../wiki/concepts/metric-registry.md`.\n\ - //! And `rocm-cli-unification-working-agreements.md`.\n\ - //! And README.md, which is fine.\n"; + let source = concat!( + "//! See `../elsewhere/concepts/registry.md`.\n", + "//! And `never-written-agreement.md`.\n", + "//! And README.md, which is fine.\n", + ); let unresolved: Vec<_> = extract_citations(source) .into_iter() .filter(|(_, candidate)| !resolve(candidate, &file_dir, root)) @@ -290,8 +308,8 @@ mod tests { assert_eq!( unresolved, vec![ - (1, "../wiki/concepts/metric-registry.md".to_owned()), - (2, "rocm-cli-unification-working-agreements.md".to_owned()), + (1, "../elsewhere/concepts/registry.md".to_owned()), + (2, "never-written-agreement.md".to_owned()), ] ); } From c72f7f81f3d94e6efc34c0417c393f18daa875e5 Mon Sep 17 00:00:00 2001 From: Teemu Kuusisto Date: Tue, 8 Sep 2026 17:58:12 +0000 Subject: [PATCH 04/11] fix(xtask): refuse a doc citation that resolves outside the workspace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `resolve` joined the candidate onto both the citing file's directory and the workspace root and asked the filesystem, so a `../`-prefixed citation could climb out of the checkout and match a file in a sibling directory. Whether such a directory exists is a property of one machine, not of the tree: the same citation would resolve on the author's disk and dangle in CI, and the shape that motivated this check is exactly the one that escapes. Both candidates are now normalized lexically — `canonicalize` is no use on paths that do not exist — and rejected unless they land inside the workspace root. Signed-off-by: Teemu Kuusisto --- xtask/src/doc_paths.rs | 52 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 49 insertions(+), 3 deletions(-) diff --git a/xtask/src/doc_paths.rs b/xtask/src/doc_paths.rs index b41f406fff..68d7678634 100644 --- a/xtask/src/doc_paths.rs +++ b/xtask/src/doc_paths.rs @@ -26,7 +26,8 @@ //! `docs/…` and bare `README.md`/`AGENTS.md` forms). Both are how the tree //! actually cites files, and accepting either keeps the check free of //! false positives without weakening it: a name that resolves under neither -//! root points at nothing. +//! root points at nothing. Neither root accepts a path that climbs out of the +//! workspace, so what sits next to the checkout cannot decide the result. //! - **Lines, not tokens.** The scan is line-based, so a multi-line string //! literal whose continuation lines start with `//!` or `///` reads as a doc //! comment. The fixtures below use `concat!` to keep that prefix off the start @@ -39,7 +40,7 @@ //! set as-is; the pure helpers take their inputs as parameters so they are //! unit-testable without touching process-global state. -use std::path::{Path, PathBuf}; +use std::path::{Component, Path, PathBuf}; use std::process::Command; use anyhow::{Context, Result, bail}; @@ -131,10 +132,38 @@ pub fn extract_citations(source: &str) -> Vec<(usize, String)> { citations } +/// Lexically resolve `.` and `..` in `path` without touching the filesystem. +/// +/// `canonicalize` is unusable here: it fails on the paths this check cares about +/// most, the ones that do not exist. +fn normalize(path: &Path) -> PathBuf { + let mut normalized = PathBuf::new(); + for component in path.components() { + match component { + Component::CurDir => {} + Component::ParentDir => { + if !normalized.pop() { + normalized.push(component.as_os_str()); + } + } + other => normalized.push(other.as_os_str()), + } + } + normalized +} + /// Whether `candidate` names a file, resolved either next to the citing file or /// against the workspace root. +/// +/// A candidate that climbs out of the workspace never resolves, even if a file +/// happens to sit there. Whether a directory exists beside the checkout is a +/// property of one machine, not of the tree, and a citation that resolved only +/// on the author's disk would pass review and fail CI. pub fn resolve(candidate: &str, file_dir: &Path, root: &Path) -> bool { - file_dir.join(candidate).is_file() || root.join(candidate).is_file() + [file_dir.join(candidate), root.join(candidate)] + .iter() + .map(|path| normalize(path)) + .any(|path| path.starts_with(root) && path.is_file()) } /// All tracked `*.rs` files, excluding `third_party/`, as paths relative to `root`. @@ -286,6 +315,23 @@ mod tests { assert!(!resolve("foo.md", &file_dir, root)); } + #[test] + fn refuses_to_resolve_a_path_that_climbs_out_of_the_workspace() { + let temp = tempfile::tempdir().expect("tempdir"); + let outside = temp.path(); + let root = outside.join("workspace"); + std::fs::create_dir_all(root.join("crates/thing/src")).expect("src dir"); + std::fs::create_dir_all(outside.join("beside")).expect("neighbour dir"); + std::fs::write(outside.join("beside/note.md"), "note").expect("neighbour file"); + let file_dir = root.join("crates/thing/src"); + + // The file really is there, but it is outside the checkout: resolving it + // would make the check pass on this machine and fail on any other. + assert!(outside.join("beside/note.md").is_file()); + assert!(!resolve("../beside/note.md", &root, &root)); + assert!(!resolve("../../../../beside/note.md", &file_dir, &root)); + } + #[test] fn flags_every_unresolvable_citation_not_just_the_first() { // The regression this check exists for: a relative tree that never From d9c7d942ee7def8a6360e7db743bd74612d92b32 Mon Sep 17 00:00:00 2001 From: Teemu Kuusisto Date: Tue, 8 Sep 2026 17:58:18 +0000 Subject: [PATCH 05/11] docs(dash): name the fields the pass-rate rollup actually groups by MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The module doc said rows are grouped by `(cell, model, backend, concurrency)`. `RollupKey` also holds `tp` and `dtype`, and the field is `engine`, not `backend` — a difference the reader would only find by disbelieving the doc, and one that misstates what Pass^N and Pass@N are computed over. `row_verdict`'s summary is also split into a real first sentence. The paragraph break existed only to satisfy `too_long_first_doc_paragraph`, which left rustdoc showing half a sentence as the item's summary. Signed-off-by: Teemu Kuusisto --- crates/rocm-dash-core/src/bench_rollup.rs | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/crates/rocm-dash-core/src/bench_rollup.rs b/crates/rocm-dash-core/src/bench_rollup.rs index 1c635a82df..9f78a37d20 100644 --- a/crates/rocm-dash-core/src/bench_rollup.rs +++ b/crates/rocm-dash-core/src/bench_rollup.rs @@ -8,18 +8,20 @@ //! it whenever the row set changes rather than relying on the upstream //! `pass_n_of_n` / `pass_at_n` CSV columns. //! -//! Rows are grouped by `(cell, model, backend, concurrency)`; each group of N -//! trials yields two verdicts — strict (all N passed) and lenient (at least -//! one passed). +//! Rows are grouped by `(cell, model, engine, tp, dtype, concurrency)` — every +//! field that defines the run except the trial itself; each group of N trials +//! yields two verdicts — strict (all N passed) and lenient (at least one +//! passed). use std::collections::BTreeMap; use crate::bench_schema::{BenchmarkRow, PassFail}; -/// Effective verdict for one row: prefer the rolled-up `pass_fail`, fall back +/// Effective verdict for one row. /// -/// to the judge verdict when the rollup is `Unknown`. A row that is `Unknown` -/// under both returns `Unknown` and never counts as a pass. +/// Prefers the rolled-up `pass_fail`, falling back to the judge verdict when the +/// rollup is `Unknown`. A row that is `Unknown` under both returns `Unknown` and +/// never counts as a pass. #[must_use] pub const fn row_verdict(row: &BenchmarkRow) -> PassFail { match row.pass_fail { From 4d139612a3ba0f4f958903f55f937e017ecbc0ed Mon Sep 17 00:00:00 2001 From: Teemu Kuusisto Date: Tue, 8 Sep 2026 18:16:17 +0000 Subject: [PATCH 06/11] docs(dash): stop claiming the rollup key covers every run field MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The module doc said the trial-group key is "every field that defines the run except the trial itself". It is not: `BenchmarkRow` also carries `task`, `prompt_class`, `pp`, `max_num_seqs`, `attention_backend`, `kv_dtype`, `spec`, `input_len`, `output_len` and `cache_mode`, none of which `RollupKey` holds. Two rows that differ only in `input_len` are folded into one trial set, so the sentence promised a guarantee the code does not make. `RollupKey`'s own doc carried the same overreach from further back — "everything that defines the backend config is held fixed" — while `endpoint`, `pp`, `max_num_seqs`, `attention_backend`, `kv_dtype` and `spec` sit in the schema's backend-config block and outside the key. Both now state the key and say plainly what it does not separate. Signed-off-by: Teemu Kuusisto --- crates/rocm-dash-core/src/bench_rollup.rs | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/crates/rocm-dash-core/src/bench_rollup.rs b/crates/rocm-dash-core/src/bench_rollup.rs index 9f78a37d20..dbd04f019f 100644 --- a/crates/rocm-dash-core/src/bench_rollup.rs +++ b/crates/rocm-dash-core/src/bench_rollup.rs @@ -8,10 +8,9 @@ //! it whenever the row set changes rather than relying on the upstream //! `pass_n_of_n` / `pass_at_n` CSV columns. //! -//! Rows are grouped by `(cell, model, engine, tp, dtype, concurrency)` — every -//! field that defines the run except the trial itself; each group of N trials -//! yields two verdicts — strict (all N passed) and lenient (at least one -//! passed). +//! Rows are grouped by `(cell, model, engine, tp, dtype, concurrency)`, and +//! each group of N trials yields two verdicts — strict (all N passed) and +//! lenient (at least one passed). use std::collections::BTreeMap; @@ -30,9 +29,11 @@ pub const fn row_verdict(row: &BenchmarkRow) -> PassFail { } } -/// Grouping key for a trial set. Trials within a group differ only by `run` -/// (and `trial_index`); everything that defines the backend config is held -/// fixed so Pass^N / Pass@N compare like-for-like. +/// Grouping key for a trial set: the fields Pass^N / Pass@N compare over. +/// +/// Rows differing only in `run` and `trial_index` fall into the same group. +/// Columns outside the key do not split one either: rows that differ in, say, +/// `input_len` or `attention_backend` are folded into the same trial set. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] struct RollupKey { cell: String, From af8cd151d6c1c8f6c583bf2db1aa5d2f90ef545a Mon Sep 17 00:00:00 2001 From: Teemu Kuusisto Date: Tue, 8 Sep 2026 18:17:12 +0000 Subject: [PATCH 07/11] docs(dash): drop line numbers from doc pointers into other files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two doc comments pointed at a line range in another file. Both had already rotted: `agent.rs:59-62` lands on `InferenceParams`' sampling knobs rather than the read-only chat seam it names, and `runner.rs:446-460` on nothing in particular — the `known_services.difference(&disc.seen)` it cites now sits near line 519. A line range is a citation that decays on the next edit above it, which is the same failure this branch is removing elsewhere, so both now name the file and the symbol and leave the reader to grep. Signed-off-by: Teemu Kuusisto --- crates/rocm-dash-daemon/tests/telemetry_contract.rs | 4 ++-- crates/rocm-dash-tui/src/ui/approval.rs | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/rocm-dash-daemon/tests/telemetry_contract.rs b/crates/rocm-dash-daemon/tests/telemetry_contract.rs index 577ab6f8b5..376a181319 100644 --- a/crates/rocm-dash-daemon/tests/telemetry_contract.rs +++ b/crates/rocm-dash-daemon/tests/telemetry_contract.rs @@ -513,8 +513,8 @@ async fn counter_reset_invalidates_baseline_immediately() { /// event on the next discovery tick and the instance is absent from subsequent /// Snapshots. /// -/// GREEN: runner.rs:446-460 computes `known_services.difference(&disc.seen)` -/// and fires `InstanceGone` for each absent id. +/// GREEN: `runner.rs` computes `known_services.difference(&disc.seen)` and +/// fires `InstanceGone` for each absent id. #[tokio::test] async fn service_removal_fires_instance_gone() { let tmp = tempfile::TempDir::new().unwrap(); diff --git a/crates/rocm-dash-tui/src/ui/approval.rs b/crates/rocm-dash-tui/src/ui/approval.rs index a7abf9543b..ce7e045ee6 100644 --- a/crates/rocm-dash-tui/src/ui/approval.rs +++ b/crates/rocm-dash-tui/src/ui/approval.rs @@ -11,7 +11,7 @@ //! maps the verdict onto a CLI-side action. //! //! It must never gain a mutating capability and never touches the read-only -//! chat seam (`agent.rs:59-62`). +//! chat seam in `agent.rs`. //! //! Keymap mirrors the frozen rocm-cli `pending_approval` screen: Up/Down/Tab //! move the cursor; `y` approves; `n` denies; Esc cancels; Enter performs the From 4add02c0d47bddebd8d23788a949bbdf46bf739d Mon Sep 17 00:00:00 2001 From: Teemu Kuusisto Date: Tue, 8 Sep 2026 18:17:21 +0000 Subject: [PATCH 08/11] ci: fold the MANIFEST.md path filter into the markdown glob `**/*.md` joined the `rust` filter so a deleted or renamed doc file reaches `cargo xtask verify-doc-paths`. dorny/paths-filter matches patterns with picomatch, where a leading `**/` also matches zero directories, so the glob already covers the root-level `MANIFEST.md` entry sitting above it. Keeping both left a rule that can never decide anything, and two comments where one states why markdown is a Rust input at all. Signed-off-by: Teemu Kuusisto --- .github/workflows/ci.yml | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 12330ff0d4..43e72efdab 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -98,11 +98,10 @@ jobs: - '**/Cargo.toml' - 'Cargo.lock' - 'rust-toolchain*' - # clippy runs `cargo xtask manifest --check` against this file. - - 'MANIFEST.md' - # clippy also runs `cargo xtask verify-doc-paths`, so deleting or - # renaming a doc file can break a doc-comment citation with no - # *.rs file in the change. + # clippy runs `cargo xtask manifest --check` against MANIFEST.md + # and `cargo xtask verify-doc-paths` over every doc-comment + # citation, so deleting or renaming any markdown file can break a + # Rust check with no *.rs file in the change. - '**/*.md' # rocm-deps compiles the pins into constants, so a pin change is a # source change even though no *.rs file moved. From 059b86d6bbe2b25982b31a89c0cb6303bced327f Mon Sep 17 00:00:00 2001 From: Teemu Kuusisto Date: Tue, 8 Sep 2026 18:21:26 +0000 Subject: [PATCH 09/11] fix(xtask): stop the doc-path check reading `////` as a doc comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `"////foo".strip_prefix("///")` succeeds, so a four-slash separator banner was scanned like a doc line. rustc treats `////` as an ordinary comment and rustdoc renders nothing from it, so a file name inside one is not a citation the reader can follow, and flagging it would fail CI over text no document ever pointed at. None exists in the tree today, which is why the gate stayed green. The design note also records that the block forms `/*! … */` and `/** … */` are not scanned at all. Signed-off-by: Teemu Kuusisto --- xtask/src/doc_paths.rs | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/xtask/src/doc_paths.rs b/xtask/src/doc_paths.rs index 68d7678634..c368e8d657 100644 --- a/xtask/src/doc_paths.rs +++ b/xtask/src/doc_paths.rs @@ -17,7 +17,9 @@ //! `///` are scanned. Ordinary code mentions `.md` files legitimately — a //! `format!("{dist}/README.md")` naming an artifact that exists only after a //! build, a shell command embedded in a workflow-contract test — and those are -//! not citations to resolve. +//! not citations to resolve. `////` is skipped because rustc does not treat it +//! as a doc comment either; the block forms `/*! … */` and `/** … */` are not +//! scanned at all, and none in this tree cites a file. //! - **No backtick requirement.** Citations in this tree appear both quoted and //! bare (`docs/ux-guidelines.md` in `app/summary.rs` is bare), so requiring //! backticks would miss the majority of them. @@ -114,6 +116,9 @@ pub fn extract_citations(source: &str) -> Vec<(usize, String)> { let mut citations: Vec<(usize, String)> = Vec::new(); for (index, line) in source.lines().enumerate() { let trimmed = line.trim_start(); + if trimmed.starts_with("////") { + continue; + } let Some(text) = trimmed .strip_prefix("//!") .or_else(|| trimmed.strip_prefix("///")) @@ -266,6 +271,14 @@ mod tests { assert!(extract_citations(source).is_empty()); } + #[test] + fn ignores_a_four_slash_banner_comment() { + // rustc does not treat `////` as a doc comment, so rustdoc never renders + // a separator banner and a name inside one is not a citation. + let source = "//// section break, see docs/never-written.md\n"; + assert!(extract_citations(source).is_empty()); + } + #[test] fn ignores_placeholder_and_absolute_paths() { let source = "//! Writes `.md` under the bundle, or /etc/motd.md on request.\n"; From 5909e8c8b5fb18bf7c8ace6aff4d65bc21e364ac Mon Sep 17 00:00:00 2001 From: Teemu Kuusisto Date: Tue, 8 Sep 2026 18:21:49 +0000 Subject: [PATCH 10/11] test(xtask): make the doc-path guards fail their tests when removed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two tests passed for the wrong reason. `ignores_urls_ending_in_md` used only `scheme://host` links, where the scheme's `//` leads the character run and the absolute-path guard rejects the candidate on its own — the URL filter could be deleted and the test would still be green. It now also carries an anchored link, whose fragment puts a bare relative path inside the token, so dropping the whole token is what keeps the line quiet. `flags_every_unresolvable_citation_not_just_the_first` re-implemented the collection loop with an iterator instead of calling the code that does it, so `run()` could have returned at the first miss and the test would not have noticed. The loop moves into `check_source`, which returns the citations checked and a violation line for each miss; the test now covers both the count and the rendered messages, and `run()` keeps its totals. Verified by mutation: neutering the URL filter or capping the collection at one now fails the matching test. A design note records what the URL filter does not cover — a link written without a scheme, and a citation glued to a URL with no space. Signed-off-by: Teemu Kuusisto --- xtask/src/doc_paths.rs | 63 ++++++++++++++++++++++++++++++------------ 1 file changed, 46 insertions(+), 17 deletions(-) diff --git a/xtask/src/doc_paths.rs b/xtask/src/doc_paths.rs index c368e8d657..688efbc5c2 100644 --- a/xtask/src/doc_paths.rs +++ b/xtask/src/doc_paths.rs @@ -20,6 +20,12 @@ //! not citations to resolve. `////` is skipped because rustc does not treat it //! as a doc comment either; the block forms `/*! … */` and `/** … */` are not //! scanned at all, and none in this tree cites a file. +//! - **URLs, by whole token.** A whitespace-separated token containing `://` is +//! dropped, so an external link ending in `.md` is never read as a path in the +//! tree. Two shapes fall outside that rule: a link written without a scheme, +//! as a bare host and path, is still read as a path and reported, and a real +//! citation glued to a URL with no space between them is dropped along with +//! it. Neither occurs here — write the scheme, and a space after the comma. //! - **No backtick requirement.** Citations in this tree appear both quoted and //! bare (`docs/ux-guidelines.md` in `app/summary.rs` is bare), so requiring //! backticks would miss the majority of them. @@ -171,6 +177,27 @@ pub fn resolve(candidate: &str, file_dir: &Path, root: &Path) -> bool { .any(|path| path.starts_with(root) && path.is_file()) } +/// Citations checked in `source`, and a violation line for each that does not +/// resolve. +/// +/// Every miss is collected rather than returned at the first, so one CI run is +/// enough to fix a whole file. +fn check_source(file: &Path, source: &str, file_dir: &Path, root: &Path) -> (usize, Vec) { + let citations = extract_citations(source); + let violations = citations + .iter() + .filter(|(_, candidate)| !resolve(candidate, file_dir, root)) + .map(|(line, candidate)| { + format!( + "{}:{line}: doc comment cites `{candidate}`, which does not resolve to a file in \ + the tree", + file.display() + ) + }) + .collect(); + (citations.len(), violations) +} + /// All tracked `*.rs` files, excluding `third_party/`, as paths relative to `root`. fn discover_rust_files(root: &Path) -> Result> { let output = Command::new("git") @@ -206,16 +233,9 @@ pub fn run() -> Result<()> { let file_dir = path .parent() .map_or_else(|| root.clone(), Path::to_path_buf); - for (line, candidate) in extract_citations(&source) { - checked += 1; - if !resolve(&candidate, &file_dir, &root) { - violations.push(format!( - "{}:{line}: doc comment cites `{candidate}`, which does not resolve to a \ - file in the tree", - file.display() - )); - } - } + let (count, found) = check_source(file, &source, &file_dir, &root); + checked += count; + violations.extend(found); } if !violations.is_empty() { @@ -267,6 +287,11 @@ mod tests { let source = concat!( "//! See https://example.com/docs/remote.md for the upstream note.\n", "/// Mirrored at .\n", + // The scheme's `//` leads the run in the two forms above, so the + // absolute-path guard would reject them even without the URL + // filter. An anchor puts a bare relative path inside the token, so + // only dropping the whole token keeps this line quiet. + "//! Anchored at https://example.com/page#docs/section.md as well.\n", ); assert!(extract_citations(source).is_empty()); } @@ -360,15 +385,19 @@ mod tests { "//! And `never-written-agreement.md`.\n", "//! And README.md, which is fine.\n", ); - let unresolved: Vec<_> = extract_citations(source) - .into_iter() - .filter(|(_, candidate)| !resolve(candidate, &file_dir, root)) - .collect(); + let file = Path::new("crates/thing/src/lib.rs"); + let (checked, violations) = check_source(file, source, &file_dir, root); + + assert_eq!(checked, 3); assert_eq!( - unresolved, + violations, vec![ - (1, "../elsewhere/concepts/registry.md".to_owned()), - (2, "never-written-agreement.md".to_owned()), + "crates/thing/src/lib.rs:1: doc comment cites \ + `../elsewhere/concepts/registry.md`, which does not resolve to a file in the tree" + .to_owned(), + "crates/thing/src/lib.rs:2: doc comment cites `never-written-agreement.md`, which \ + does not resolve to a file in the tree" + .to_owned(), ] ); } From a7ad92676b59c2dd2b6415789bfe77bb338916b1 Mon Sep 17 00:00:00 2001 From: Teemu Kuusisto Date: Tue, 8 Sep 2026 18:44:40 +0000 Subject: [PATCH 11/11] test(xtask): pin the two doc-path guards no test was holding Mutating each guard in `candidates_in_line` and deleting it showed two that no test noticed. Removing the angle brackets from the placeholder delimiter set left every test green, because the only bracketed fixture (`.md`) has an empty stem and is rejected by the stem check first. Removing the stem check left every test green in turn, because that same fixture is rejected by the delimiter check. Each guard was standing in for the other, so either could have been deleted unnoticed. Add a bracketed name with a real stem, and a bare extension with nothing next to it, so each guard is now the only thing rejecting one case. Signed-off-by: Teemu Kuusisto --- xtask/src/doc_paths.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/xtask/src/doc_paths.rs b/xtask/src/doc_paths.rs index 688efbc5c2..67dfe2e138 100644 --- a/xtask/src/doc_paths.rs +++ b/xtask/src/doc_paths.rs @@ -313,6 +313,15 @@ mod tests { // out, so the case fails if that check is ever dropped. let source = "//! Writes `{version}CHANGELOG.md` beside the archive.\n"; assert!(extract_citations(source).is_empty()); + // The same, for the angle-bracket pair. The first case above has an + // empty stem and so is ruled out twice over; this one has a stem, so + // adjacency is all that stands between it and a false positive. + let source = "//! Writes `-notes.md` next to the log.\n"; + assert!(extract_citations(source).is_empty()); + // A bare extension is the tail of a split placeholder, not a path, and + // nothing sits next to it: only the empty-stem check rejects this one. + let source = "//! The extension is .md by convention.\n"; + assert!(extract_citations(source).is_empty()); } #[test]