圭表 / guibiao
立表見影,依賴無遁。 — Set the gnomon and the shadow shows — no dependency escapes.
The static observation dimension of Tianheng — the gnomon.
圭表 (the gnomon, reading the cast shadow) is the dependency-light static core, derived
from modou. It reads the shadow the code casts —
its imports and dependencies — from cargo metadata and a source use scan, compares
against boundaries you declare in Rust, and reacts.
It is a pure functional core: no CLI, no filesystem shell. Its external dependencies are
serde_json and Unicode's identifier and normalization tables, unicode-ident and
unicode-normalization — no syn. Its internal dependencies are the workspace crates its
Cargo.toml names.
use ;
let constitution = new
.boundary
.boundary;
// `check` is the pure entry: observe a workspace, return an Outcome.
let outcome = check;
Beyond which crates a target may depend on (by name, or the external/internal split), a
crate boundary can also restrict the declared source kind of its dependencies — the
git-vs-registry-vs-path distinction cargo metadata records:
use ;
// A crate prepared for crates.io declares no git source: its manifest must name only
// registry and path dependencies (an *optional* git dependency blocks publishing too).
let boundary = crate_
.restrict_dependency_sources_to
.because;
Its stated bounds (deliberate, never silently overreached):
- It governs the declared source, not the resolved one. A registry dependency that
[patch]or[source] replace-withredirects to git reads asregistry+…and does not violate — correct for manifest hygiene, since[patch]is workspace-local and never blockscargo publish. Observing the resolved source is cargo-deny's[sources]lane, not a Tianheng capability. - It is source-kind hygiene, not a
cargo publishoracle. A{ git = "…", version = "…" }dependency declares a git source and is flagged even though it would publish successfully; the rule classifies by the declared source and does not parse theversionkey.
The crate-boundary rules (each declared in Rust, each carrying a .because(…) reason and an
optional .warn() severity): deny_external_dependencies (allow a named exception list),
forbid_dependency_on([…]), restrict_dependencies_to([…]) (a closed allowlist),
restrict_workspace_dependencies_to([…]) / forbid_all_workspace_dependencies (the
crate-to-crate layering surface), and restrict_dependency_sources_to([…]) (above). The
module-boundary rules: must_not_import, restrict_imports_to([…]), must_not_be_imported_by,
must_only_be_imported_by([…]) (the closed inbound allowlist), confine_external_crate (confine
an external crate's use imports to one module subtree — FFI / platform-vocabulary confinement), and
must_not_call_inline("…") (forbid an inline symbol path — e.g. std::time::…::now — within a declared
module subtree; the inline-symbol-path / clock-free confinement), and confine_inline_call("…") (its permitting
dual: permit an inline symbol path — e.g. std::process::Command — only within a declared module subtree).
By default a crate rule observes the normal [dependencies] table; .dependency_kind(DependencyKind::Dev)
(or Build) targets [dev-dependencies] / [build-dependencies] instead — a boundary governs
exactly one table, so govern two by declaring two. Dev/build findings carry a (dev) / (build)
suffix so the same dependency governed in two tables stays a distinct finding (a normal-table
finding keeps the bare name, so existing baselines do not churn).
Stated partial coverage (never silently passed): the hand-rolled use scanner does not
see bare path expressions or macro-generated imports — closing those would require an AST, an
amendment, not a silent trade.
The scanner anchors source discovery to Cargo's observed target src_path (the lib target,
else a bin target), so custom [lib] path = "lib.rs" and bin-only crates are scanned from
the compiled source root rather than the manifest_dir/src shortcut. A #[path]-remapped
module is followed under its declared logical module path, so a same-named conventional orphan
does not stand in for the target.
Adoption & status
Experimental — pre-1.0. The 0.3.0 release replaced presentation-derived identity
with RuleKey + StructuredFactIdentity. The adopter-written boundary DSL remains the guarded
surface; callers may inspect the returned structured Outcome directly through this crate.
Adopt 圭表 on its own — the footprint is guibiao and the normal dependencies cargo tree -p guibiao -e normal
lists, none of them syn — or graduate to
the composed constitution through the tianheng shell (which
re-exports this crate's surface): a single 儀 is an on-ramp, the suite is the destination. Onboard
without a red wall — declare at .warn(), Baseline::of(...) to grandfather an existing codebase,
then enforce. A runnable guibiao-standalone example lives under the workspace examples/.
License
Licensed under either of Apache-2.0 or MIT, at your option.