Module check_api_links 

cargo dev check-api-links — every link in the map resolves to a real page.

Why this is a separate command

The api-links generator is fail-closed about the code: it refuses to emit a page path for a symbol whose kind it cannot determine, and generate-all --mode check fails on drift. Neither of those can tell whether the paths it emits exist, because knowing that needs two build artefacts the fast per-push gate does not have — a rustdoc tree and a built site.

The generator’s module docs say its URL rules were “measured against cargo doc --workspace --all-features --no-deps”. That was true when it was written and is a claim in a comment thereafter. This command is the same measurement, run on every build of the docs job (docs/design/11-documentation-plan.md §11, §1.3.100).

The three checks

1. Forward, Rust. Every rust: value names a file in the rustdoc tree.
2. Reverse, Rust. Every item page in the facade’s subtree of that tree is claimed by some rust: value, except the entries of UNCLAIMABLE, each of which carries the reason it cannot be claimed. This is the direction that finds a symbol the guide can never link to.
3. Anchors, Python and CLI. Every python:/cli: target’s anchor appears as an id="…" on the page it names. mkdocs build --strict validates only the anchors a page actually names, so two dead ones sat in the map until this check found them (§1.3.106).

Fail-closed on a missing input

A missing rustdoc tree or a missing site/ is an error, never a skipped check. Four of this milestone’s defects were checks that passed because they had nothing to look at (§1.3.106 most recently), and a green check-api-links that ran none of its checks would be the fifth.

What this command does not check

It never reads docs/api_links.yml. It calls api_links::map and checks the values the generator would write — so a hand-edited map is invisible here, and a bite test that corrupts the file produces no failure at all (measured). That is deliberate, and it is sound only as a pair: generate-all --mode check is what proves the file equals map()’s output, and this command is what proves map()’s output resolves. Run one without the other and a hand-edited map slips through — which is why §11 puts both in the same job.

The alternative, parsing the YAML back, was rejected: it adds a parser to a tool that has deliberately avoided one, and it lets the checker and the generator drift apart in their reading of the same bytes, which is the failure the map exists to prevent one level up.

Structs

CargoMetadata 🔒

The one Cargo metadata field needed to find rustdoc output.

FsPageTree 🔒

Constants

CHECKER 🔒

This command’s name, for fail-closed error messages.

DOC_COMMAND 🔒

The command that writes the rustdoc tree, named in the message when it is absent.

FACADE_TREE 🔒

The crate whose rustdoc subtree the reverse check covers.

ITEM_PREFIXES 🔒

Rustdoc’s own file naming, by item kind. A file matching none of these is machinery — all.html, sidebar-items.js, static.files/ — and is not a symbol’s page.

SITE_COMMAND 🔒

The command that writes the site, likewise.

SITE_DIR 🔒

Where the built site is, relative to the repository root.

UNCLAIMABLE 🔒

Pages in the facade’s tree that no map key can claim, and why.

Traits

PageTree 🔒

Functions

cargo 🔒

The cargo that invoked this tool, so a non-default toolchain stays consistent.

cargo_metadata_failed 🔒

Reports a failed metadata command without discarding Cargo’s diagnostics.

check

Runs the three checks, reporting every failure rather than the first.

check_anchors 🔒

Every python:/cli: anchor appears as an id="…" on the page it names.

check_rust_forward 🔒

Every rust: value names a file that exists.

check_rust_reverse 🔒

Every item page in the facade’s subtree is claimed by some rust: value.

check_rust_reverse_with 🔒

collect_pages_with 🔒

find_bytes 🔒

find_markup_tag_end 🔒

find_raw_text_end 🔒

find_tag_close 🔒

html_identifiers 🔒

index_is_file 🔒

is_raw_text_element 🔒

looks_like_html_tag 🔒

page_tree_error 🔒

parse_cargo_metadata 🔒

Decodes the metadata shape this checker consumes.

parse_html_attribute_value 🔒

parse_html_tag 🔒

read_identifiers 🔒

The id="…" attributes of one built page.

require_dir 🔒

Fails when an input this command reads has not been built.

rustdoc_tree 🔒

The rustdoc output directory, read from cargo rather than assumed.

skip_html_space 🔒

unclassifiable 🔒

Wraps a message as this command’s fail-closed error.