Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions rs/justfile
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,89 @@ 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
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/<name>`, 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).
#
# 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

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
echo "$collisions" >&2
echo "set doc = false on whichever has no published API." >&2
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"

# 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":[
{"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 }}
Expand Down
5 changes: 5 additions & 0 deletions rs/moq-token-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand Down
31 changes: 31 additions & 0 deletions rs/scripts/doc-names.jq
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Find workspace targets that would render to the same `target/doc/<dir>`.
#
# `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 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 | 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"))
Comment on lines +23 to +24

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include doc-enabled examples, tests, and benches

When an [[example]], [[test]], or [[bench]] target explicitly sets doc = true, the ordinary cargo doc --workspace --no-deps invocation schedules rustdoc for it. In scratch workspaces on Cargo 1.89, Cargo reported that the library had “the same output filename as the example target,” with integration-test and bench targets behaving identically. This filter discards all three kinds, so _doc-names passes even though the immediately following CI doc step can hit the exact collision and cleanup race this gate is intended to prevent. Include every doc-enabled target kind that Cargo schedules, not only libraries and binaries. (Written by GPT-5.6 Sol)

AGENTS.md reference: AGENTS.md:L35-L35

Useful? React with 👍 / 👎.

Comment on lines +22 to +24

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Skip targets whose required features are disabled

When a documented binary declares required-features that are not enabled, Cargo skips that target, but this filter includes it solely because .doc is true. With Cargo 1.95, a default-feature cargo doc --workspace --no-deps documented only the colliding library while this gate rejected the same scratch workspace, so adding a feature-gated binary can make every CI check fail for a collision that cannot occur. Account for Cargo's required-features target selection, or derive the candidates from the actual doc build's enabled targets. (Written by GPT-5.6 Sol)

AGENTS.md reference: AGENTS.md:L35-L35

Useful? React with 👍 / 👎.

| select((([.kind[]] | any(. == "bin")) and ((.name | gsub("-"; "_")) | 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 "))
Loading