Skip to main content

Crate xingbiao

Crate xingbiao 

Source
Expand description

星表 (xīngbiǎo) — the single reader of truth for what the workspace tree IS.

Reads cargo metadata --no-deps and looks up packages and their crate-root source files: the tabulated catalog every observation dimension references before it observes. Spawns cargo and parses its JSON (serde_json + std only, no syn).

The criterion, because this charter widens, and an enumeration of what it holds goes stale. A fact belongs here when every dimension must agree on it before observing, and it is a fact about the tree rather than a reading of what the tree contains. Which packages exist and where their roots are; whether two paths are one file; whether a path is there at all, and whether being unable to tell is the same answer as its absence. Each of those is asked by 圭表, 渾儀 and 漏刻 alike, and a dimension answering it privately is how three readers came to disagree about one tree.

What the criterion refuses is as load-bearing as what it admits: an interpretation of source is a dimension’s own observation, not a fact about the tree. cargo metadata says which file is a crate root; what the tokens in that file mean is 圭表’s or 渾儀’s answer and belongs to whichever is asking. The line is between what is there and what it says.

The widenings are named rather than left to be inferred: the path-identity primitives (canonicalize_or_fail, try_visit) arrived for a module-graph cycle guard, and the filesystem-answer policy (is_regular_file, is_directory and the crate-private criterion behind them) arrived after all three dimensions were measured collapsing absent into unreadable — each is one notch finer than the last, on the same question of what the tree holds.

Fixture infrastructure. This widening is test-only: the hidden scratch-root helpers ([claim_scratch], [scratch_base], [scratch_root]) and Unreadable. All of these are #[doc(hidden)] items that exist because integration and unit test trees across member crates cannot share a cfg(test) helper, yet must enforce identical policies (atomic temporary root reservation without adopting pre-existing symlinks, and permission-removal verification that restores on drop and asserts under TIANHENG_WORKSPACE_TESTS). They ship hidden in the published crate so all test suites agree on fixture safety and refusal semantics without hand-rolled copies.

Sits beneath all three observation dimensions — static (圭表), semantic (渾儀) and runtime (漏刻, through its CI-only audit face) — preventing twin-drift in what they take the tree to be.

Structs§

CompiledRoots
A package’s library-kind and binary roots, in Cargo’s reported order, each once, and at least one — by construction, since only crate_roots builds one, so an empty list cannot stand for either state that has none.

Enums§

CrateRoots
Which of a package’s crate roots are compiled, told apart from the two ways there can be none.

Functions§

audit_corpus_and_anchor
The runtime audit’s corpus and label anchor for the workspace at manifest_path, in one read.
canonicalize_or_fail
Canonicalize path (resolving symlinks) for a cycle/dedup identity. Fails loud — never a silent skip — so an unresolvable path surfaces as a scan error instead of quietly admitting a weakened guard (the single decision this crate makes on a dimension’s behalf; a dimension that wants a different failure posture composes its own handling around this, but must not reimplement the canonicalize call itself).
cargo_metadata
Run cargo metadata --no-deps --format-version 1 for the workspace at manifest_path.
compilation_unit_label
A compilation unit’s stable identity label: its root source path relative to the package’s own manifest directory (src/lib.rs, src/main.rs, tools/x.rs).
crate_root_file
Resolve a crate’s root source file from cargo metadata (library target else bin target).
crate_roots
What ONE package’s metadata says about its compiled crate roots: every one — each library-kind target and each bin target, in Cargo’s reported order, deduplicated.
find_package
Find a workspace member package by name in parsed metadata.
is_directory
Whether path is a directory, or why this reader could not tell — is_regular_file’s sibling.
is_regular_file
Whether path is a regular file, or why this reader could not tell — the criterion is is_absence, crate-private beside these two, which are its only callers.
member_root_files
Every workspace member library, proc-macro, and binary crate-root source file reported by Cargo.
member_src_dirs
Workspace member source-root directories (deduplicated and sorted).
path_label
A path as a canonical identity label: / as its only component separator, and every byte the path carried preserved.
try_visit
Canonicalize path and record it in visited, reporting whether this is its first visit (Ok(true)) or a repeat (Ok(false)) — the shape behind every plain “have I already walked this file” dedup guard. Err only when the path itself cannot be resolved (see canonicalize_or_fail); a cycle-specific reaction (as opposed to a plain dedup skip) is the caller’s own decision once it sees Ok(false).
workspace_root
The workspace root directory Cargo resolved for this metadata read — the directory holding the workspace manifest, whichever member manifest --manifest-path happened to name (Cargo resolves upward to the same root either way).