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§
- Compiled
Roots - A package’s library-kind and binary roots, in Cargo’s reported order, each once, and at least one — by
construction, since only
crate_rootsbuilds one, so an empty list cannot stand for either state that has none.
Enums§
- Crate
Roots - 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 1for the workspace atmanifest_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 elsebintarget). - crate_
roots - What ONE package’s metadata says about its compiled crate roots: every one — each library-kind target
and each
bintarget, in Cargo’s reported order, deduplicated. - find_
package - Find a workspace member package by name in parsed metadata.
- is_
directory - Whether
pathis a directory, or why this reader could not tell —is_regular_file’s sibling. - is_
regular_ file - Whether
pathis a regular file, or why this reader could not tell — the criterion isis_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
pathand record it invisited, 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.Erronly when the path itself cannot be resolved (seecanonicalize_or_fail); a cycle-specific reaction (as opposed to a plain dedup skip) is the caller’s own decision once it seesOk(false). - workspace_
root - The workspace root directory Cargo resolved for this metadata read — the directory holding the
workspace manifest, whichever member manifest
--manifest-pathhappened to name (Cargo resolves upward to the same root either way).