diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 15e3bdc290..43e72efdab 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -98,8 +98,11 @@ jobs: - '**/Cargo.toml' - 'Cargo.lock' - 'rust-toolchain*' - # clippy runs `cargo xtask manifest --check` against this file. - - 'MANIFEST.md' + # 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. - 'runtime-deps.toml' @@ -738,6 +741,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/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..dbd04f019f 100644 --- a/crates/rocm-dash-core/src/bench_rollup.rs +++ b/crates/rocm-dash-core/src/bench_rollup.rs @@ -8,19 +8,19 @@ //! 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, 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; 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 { @@ -29,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, 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-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 e2cc124023..ce7e045ee6 100644 --- a/crates/rocm-dash-tui/src/ui/approval.rs +++ b/crates/rocm-dash-tui/src/ui/approval.rs @@ -6,13 +6,12 @@ //! //! 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. //! //! 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 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}; diff --git a/xtask/src/doc_paths.rs b/xtask/src/doc_paths.rs new file mode 100644 index 0000000000..67dfe2e138 --- /dev/null +++ b/xtask/src/doc_paths.rs @@ -0,0 +1,413 @@ +// 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 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: +//! +//! - **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. `////` 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. +//! - **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. 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 +//! 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. +//! +//! 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::{Component, 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(); + if trimmed.starts_with("////") { + continue; + } + 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 +} + +/// 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), root.join(candidate)] + .iter() + .map(|path| normalize(path)) + .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") + .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); + let (count, found) = check_source(file, &source, &file_dir, &root); + checked += count; + violations.extend(found); + } + + 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 = 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())] + ); + } + + #[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 = 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 = 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()); + } + + #[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"; + 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()); + // 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] + 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("../elsewhere/foo.md", &file_dir, root)); + 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 + // 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 = concat!( + "//! See `../elsewhere/concepts/registry.md`.\n", + "//! And `never-written-agreement.md`.\n", + "//! And README.md, which is fine.\n", + ); + 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!( + violations, + vec![ + "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(), + ] + ); + } +} 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 {