From fe9b8eee6d2b4a824b901aba59e109119c67e1db Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 14:37:28 -0700 Subject: [PATCH 1/3] fix(rs): gate doc output-name collisions instead of hitting them in CI #3113 fixed one pair of targets rendering to the same `target/doc/` (libmoq's staticlib and moq-cli's binary, both `moq`). A workspace-wide doc build shows there was a second: `moq-token`'s library and `moq-token-cli`'s binary both render to `target/doc/moq_token`. Both are the same failure. Two rustdoc processes in one `cargo doc` race to clean the shared directory, so the deterministic collision warning escalates to `error: failed to remove directory` depending on which gets there first, and `RUSTDOCFLAGS="-D warnings"` does not catch it because cargo emits the collision rather than rustdoc. The doc pass is diff-scoped, so it lands on whichever unrelated PR happens to select both crates and reads as a flake. Fixing them one at a time as they surface is the wrong shape, so add `just rs _doc-names` to `check`. It groups every documented lib/bin target by the directory it renders to and fails on any group above one, naming both sides and the fix. It reads `.doc` from `cargo metadata`, so a resolved pair stays resolved, and it needs no compilation at all, which is why it can sit in the PR gate rather than nightly. It would have caught the original pair before #3091 and #3066 ever failed. Resolve the new pair the same way as the first: `moq-token` is the published library whose docs.rs page is linked from `doc/lib/rs/`, while nothing links the binary's and a bin target has no public API to render. Verified by reverting each `doc = false` in turn: the gate reports that pair and exits 1. Co-Authored-By: Claude Opus 5 --- rs/justfile | 36 ++++++++++++++++++++++++++++++++++++ rs/moq-token-cli/Cargo.toml | 5 +++++ 2 files changed, 41 insertions(+) diff --git a/rs/justfile b/rs/justfile index 489474a1a48..3feddb3db60 100644 --- a/rs/justfile +++ b/rs/justfile @@ -32,10 +32,46 @@ check *args: just rs _publish-test cargo clippy --locked --all-targets {{ args }} -- -D warnings cargo fmt --all --check + just rs _doc-names RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps {{ args }} cargo shear cargo sort --workspace --check --no-format +# Two targets whose names differ only by `-` vs `_` render to the same +# `target/doc/`, and a `cargo doc` that selects both races to clean it: the +# collision warning escalates to `error: failed to remove directory` depending on +# which rustdoc process gets there first. That reads as a flake, and because the doc +# pass above is diff-scoped it surfaces on whichever unrelated PR happens to select +# both crates. Resolve a pair by setting `doc = false` on whichever target has no +# published API to render (usually the binary), which is what `.doc` reads here. +# +# Metadata only, so this costs no compilation and can sit in the PR gate. +_doc-names: + #!/usr/bin/env bash + set -euo pipefail + + collisions=$(cargo metadata --locked --no-deps --format-version 1 | jq -r ' + [ .packages[] + | .name as $package + | .targets[] + | select(.doc) + | select([.kind[]] | any(. == "lib" or . == "rlib" or . == "dylib" + or . == "cdylib" or . == "staticlib" or . == "proc-macro" or . == "bin")) + | { dir: (.name | gsub("-"; "_")), package: $package, target: .name, kind: .kind[0] } + ] + | group_by(.dir) + | map(select(length > 1)) + | .[] + | " target/doc/\(.[0].dir) <- " + (map("\(.package) [\(.kind)] \(.target)") | join(" and ")) + ') + + if [[ -n "$collisions" ]]; then + echo "rs: these targets render to the same doc directory:" >&2 + echo "$collisions" >&2 + echo "set doc = false on whichever has no published API." >&2 + exit 1 + fi + # Auto-fix clippy/format/shear/sort. fix *args: cargo clippy --locked --fix --allow-staged --allow-dirty --all-targets {{ args }} diff --git a/rs/moq-token-cli/Cargo.toml b/rs/moq-token-cli/Cargo.toml index fc559550bd3..986cbd639a8 100644 --- a/rs/moq-token-cli/Cargo.toml +++ b/rs/moq-token-cli/Cargo.toml @@ -20,6 +20,11 @@ path = "src/lib.rs" [[bin]] name = "moq-token" path = "src/main.rs" +# The `moq-token` library renders to the same `target/doc/moq_token`, and the two +# rustdoc processes race to clean it. The library is the published API consumers +# read; this binary has none, so it is the page to give up. `just rs _doc-names` +# fails if a new pair ever collides. +doc = false [dependencies] anyhow = { workspace = true } From 33585c5435cfbb5db534859c470913e0c7ccea83 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 15:11:14 -0700 Subject: [PATCH 2/3] fix(rs): don't flag a bin cargo already suppresses for its own lib The collision query grouped every doc-enabled lib and bin target, but cargo does not document all of them. A binary whose name matches a library in its own package is skipped, and only the library is documented, so the pair never races for the directory. Both targets still report `doc: true` in metadata, so the query rejected the conventional `src/lib.rs` + `src/main.rs` layout. Verified against cargo rather than assumed: a scratch package with both files reports two `doc: true` targets and `cargo doc` emits no collision. Skip a bin whose name matches a lib in the same package. Names are compared as spelled, not folded, because cargo's suppression is name equality: a `foo_bar` lib beside a `foo-bar` bin is not suppressed and does collide, so it has to stay reportable. The query moves to `rs/scripts/doc-names.jq` and `_doc-names` takes an optional metadata file, so `_doc-names-test` can drive it with synthetic workspaces and cover the direction that matters: the same-package pair must pass, a cross-package pair must fail, and `doc = false` must resolve it. It runs in `check` beside `_select-test` and `_publish-test`. Found by Codex review (medium). Co-Authored-By: Claude Opus 5 --- rs/justfile | 66 ++++++++++++++++++++++++++++++----------- rs/scripts/doc-names.jq | 31 +++++++++++++++++++ 2 files changed, 80 insertions(+), 17 deletions(-) create mode 100644 rs/scripts/doc-names.jq diff --git a/rs/justfile b/rs/justfile index 3feddb3db60..cac40c820ff 100644 --- a/rs/justfile +++ b/rs/justfile @@ -30,6 +30,7 @@ default: check *args: just rs _select-test just rs _publish-test + just rs _doc-names-test cargo clippy --locked --all-targets {{ args }} -- -D warnings cargo fmt --all --check just rs _doc-names @@ -43,27 +44,19 @@ check *args: # which rustdoc process gets there first. That reads as a flake, and because the doc # pass above is diff-scoped it surfaces on whichever unrelated PR happens to select # both crates. Resolve a pair by setting `doc = false` on whichever target has no -# published API to render (usually the binary), which is what `.doc` reads here. +# published API to render (usually the binary). # -# Metadata only, so this costs no compilation and can sit in the PR gate. -_doc-names: +# Metadata only, so this costs no compilation and can sit in the PR gate. Takes an +# optional metadata file so `_doc-names-test` can feed it synthetic workspaces. +_doc-names metadata="": #!/usr/bin/env bash set -euo pipefail - collisions=$(cargo metadata --locked --no-deps --format-version 1 | jq -r ' - [ .packages[] - | .name as $package - | .targets[] - | select(.doc) - | select([.kind[]] | any(. == "lib" or . == "rlib" or . == "dylib" - or . == "cdylib" or . == "staticlib" or . == "proc-macro" or . == "bin")) - | { dir: (.name | gsub("-"; "_")), package: $package, target: .name, kind: .kind[0] } - ] - | group_by(.dir) - | map(select(length > 1)) - | .[] - | " target/doc/\(.[0].dir) <- " + (map("\(.package) [\(.kind)] \(.target)") | join(" and ")) - ') + if [[ -n "{{ metadata }}" ]]; then + collisions=$(jq -r -f rs/scripts/doc-names.jq < "{{ metadata }}") + else + collisions=$(cargo metadata --locked --no-deps --format-version 1 | jq -r -f rs/scripts/doc-names.jq) + fi if [[ -n "$collisions" ]]; then echo "rs: these targets render to the same doc directory:" >&2 @@ -72,6 +65,45 @@ _doc-names: exit 1 fi +# Both directions of `_doc-names`, since the interesting half is what it must NOT +# report: cargo documents only the library when a binary shares its own package's +# name, so flagging that would reject the conventional src/lib.rs + src/main.rs layout. +_doc-names-test: + #!/usr/bin/env bash + set -euo pipefail + + scratch=$(mktemp -d) + trap 'rm -rf "$scratch"' EXIT + + # Same package, same name: cargo suppresses the bin, so this must pass. + cat > "$scratch/ok.json" <<'JSON' + {"packages":[{"name":"solo","targets":[ + {"name":"solo","kind":["lib"],"doc":true}, + {"name":"solo","kind":["bin"],"doc":true}]}]} + JSON + just rs _doc-names "$scratch/ok.json" + + # Different packages: a real collision, must be reported. + cat > "$scratch/bad.json" <<'JSON' + {"packages":[ + {"name":"a-lib","targets":[{"name":"shared_name","kind":["lib"],"doc":true}]}, + {"name":"b-cli","targets":[{"name":"shared-name","kind":["bin"],"doc":true}]}]} + JSON + if just rs _doc-names "$scratch/bad.json" 2>/dev/null; then + echo "rs: _doc-names missed a cross-package collision" >&2 + exit 1 + fi + + # `doc = false` is how a pair gets resolved, so it must stop being reported. + cat > "$scratch/fixed.json" <<'JSON' + {"packages":[ + {"name":"a-lib","targets":[{"name":"shared_name","kind":["lib"],"doc":true}]}, + {"name":"b-cli","targets":[{"name":"shared-name","kind":["bin"],"doc":false}]}]} + JSON + just rs _doc-names "$scratch/fixed.json" + + echo "rs: _doc-names ok" + # Auto-fix clippy/format/shear/sort. fix *args: cargo clippy --locked --fix --allow-staged --allow-dirty --all-targets {{ args }} diff --git a/rs/scripts/doc-names.jq b/rs/scripts/doc-names.jq new file mode 100644 index 00000000000..cf7b944d434 --- /dev/null +++ b/rs/scripts/doc-names.jq @@ -0,0 +1,31 @@ +# Find workspace targets that would render to the same `target/doc/`. +# +# `cargo doc` writes each documented target to a directory named after the target with +# dashes folded to underscores, so two targets that differ only there collide: both +# rustdoc processes race to clean it, and the warning escalates to a hard error +# depending on which wins. +# +# Reads `cargo metadata --no-deps` and prints one line per colliding group. +[ .packages[] + | . as $pkg + # Cargo skips a binary whose name matches a library in its own package, documenting + # only the library, so such a pair never actually collides. Names are compared as + # spelled: a `foo_bar` lib beside a `foo-bar` bin is not suppressed by cargo and does + # collide, so it has to stay reportable. + | [ $pkg.targets[] + | select([.kind[]] | any(. == "lib" or . == "rlib" or . == "dylib" + or . == "cdylib" or . == "staticlib" or . == "proc-macro")) + | .name + ] as $libs + | $pkg.targets[] + # `doc = false` in the manifest, which is how a reported pair gets resolved. + | select(.doc) + | select([.kind[]] | any(. == "lib" or . == "rlib" or . == "dylib" + or . == "cdylib" or . == "staticlib" or . == "proc-macro" or . == "bin")) + | select((([.kind[]] | any(. == "bin")) and (.name | IN($libs[]))) | not) + | { dir: (.name | gsub("-"; "_")), package: $pkg.name, target: .name, kind: .kind[0] } +] +| group_by(.dir) +| map(select(length > 1)) +| .[] +| " target/doc/\(.[0].dir) <- " + (map("\(.package) [\(.kind)] \(.target)") | join(" and ")) From e7ec155e03fa6ca209c7251b876ba4e75538ad18 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 15:22:46 -0700 Subject: [PATCH 3/3] fix(rs): fold names when suppressing a package's own binary The same-package suppression compared target names as spelled, on the assumption that cargo only skips a binary whose name matches its library exactly. It does not: cargo folds dashes to underscores first, so a `foo_bar` library beside a `foo-bar` binary is suppressed as well, and only the library is documented. Checked against cargo 1.95.0 with a scratch package rather than reasoned about: it emits no collision and generates a single `foo_bar` page. The previous comment asserted the opposite, so the query reported a pair cargo never documents together, which is a false positive on the exact layout the suppression exists for. Fold before comparing, and cover it: a same-package `foo_bar`/`foo-bar` pair must pass. Reverting to the as-spelled comparison now fails that fixture, which the existing ones did not catch. Co-Authored-By: Claude Opus 5 --- rs/justfile | 9 +++++++++ rs/scripts/doc-names.jq | 12 ++++++------ 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/rs/justfile b/rs/justfile index cac40c820ff..2c90cc37aed 100644 --- a/rs/justfile +++ b/rs/justfile @@ -83,6 +83,15 @@ _doc-names-test: JSON just rs _doc-names "$scratch/ok.json" + # Same package, differing only by `-` vs `_`: cargo folds before suppressing, so + # this must pass too. Comparing the names as spelled would report it. + cat > "$scratch/folded.json" <<'JSON' + {"packages":[{"name":"folded","targets":[ + {"name":"foo_bar","kind":["lib"],"doc":true}, + {"name":"foo-bar","kind":["bin"],"doc":true}]}]} + JSON + just rs _doc-names "$scratch/folded.json" + # Different packages: a real collision, must be reported. cat > "$scratch/bad.json" <<'JSON' {"packages":[ diff --git a/rs/scripts/doc-names.jq b/rs/scripts/doc-names.jq index cf7b944d434..5dfad17c57c 100644 --- a/rs/scripts/doc-names.jq +++ b/rs/scripts/doc-names.jq @@ -8,21 +8,21 @@ # Reads `cargo metadata --no-deps` and prints one line per colliding group. [ .packages[] | . as $pkg - # Cargo skips a binary whose name matches a library in its own package, documenting - # only the library, so such a pair never actually collides. Names are compared as - # spelled: a `foo_bar` lib beside a `foo-bar` bin is not suppressed by cargo and does - # collide, so it has to stay reportable. + # Cargo skips a binary that would land on the same directory as a library in its own + # package, documenting only the library, so such a pair never actually collides. + # Compared after folding, matching cargo: a `foo_bar` lib beside a `foo-bar` bin is + # suppressed too (verified against cargo 1.95). Only cross-package pairs collide. | [ $pkg.targets[] | select([.kind[]] | any(. == "lib" or . == "rlib" or . == "dylib" or . == "cdylib" or . == "staticlib" or . == "proc-macro")) - | .name + | (.name | gsub("-"; "_")) ] as $libs | $pkg.targets[] # `doc = false` in the manifest, which is how a reported pair gets resolved. | select(.doc) | select([.kind[]] | any(. == "lib" or . == "rlib" or . == "dylib" or . == "cdylib" or . == "staticlib" or . == "proc-macro" or . == "bin")) - | select((([.kind[]] | any(. == "bin")) and (.name | IN($libs[]))) | not) + | select((([.kind[]] | any(. == "bin")) and ((.name | gsub("-"; "_")) | IN($libs[]))) | not) | { dir: (.name | gsub("-"; "_")), package: $pkg.name, target: .name, kind: .kind[0] } ] | group_by(.dir)