Expand description
圭表 (Guībiǎo) — the gnomon: Tianheng’s static observation core. It reads the cast shadow — a crate’s imports and dependencies.
The dependency-light functional core, derived from modou: declare a
Constitution in Rust, observe the real shape from cargo metadata and source
use scans, and check for drift, returning an Outcome. This crate is pure
observation + comparison — it carries no command-line, filesystem, or
stdout/stderr shell. The imperative shell lives in the sibling tianheng crate,
which must depend on this core and never the reverse — a crate-level invariant
Tianheng enforces on itself (crates/shengmo/src/law.rs).
Two reaction kinds, each with its own observation source: CrateBoundary over
cargo metadata, and ModuleBoundary over the crate’s own source use
declarations. Each carries a Severity; violations gate against a Baseline.
Govern by reaction, not instruction.
Modules§
- constitution
- Constitution model.
- crate_
rule - Crate boundary rules.
- module_
rule - Module boundary rules.
Structs§
- Baseline
- Recorded set of accepted violations.
- Baseline
Entry - One recorded baseline entry.
- Bound
Decl - One declared observation bound: its identity, the shape it stops at, and where the measure stops.
- BoundId
- A declared bound’s identity:
<capability>/<bound-slug>, matched to the bound item in a capability intent file. - Constitution
- The governed shape, declared in Rust (the single source of truth).
- Coverage
- Workspace coverage: how many workspace members exist and which are governed by no boundary. A projection (an observation), not a reaction — it never changes the exit code. Part of the projection surface (the 天衡 runner folds it into its report), not the reaction/law API.
- Crate
Boundary - A boundary attached to one crate target, with a human-readable reason.
- Crate
Boundary Builder - Fluent builder:
CrateBoundary::crate_("x").deny_external_dependencies().because("…")orCrateBoundary::crate_("x").forbid_dependency_on(["y"]).because("…"). - Crate
Boundary Draft - A crate boundary awaiting its severity and reason.
- Crate
Target - A crate identified by its package name.
- Deny
External Draft - A deny-external boundary awaiting an optional allowlist, severity, and reason.
- Finding
- Pair human-readable finding text with stable structured identity.
- Inline
Confinement Draft - A dedicated draft for an inline-symbol-path confinement (from
must_not_call_inline). Distinct fromModuleBoundaryDraftso its narrowing / escalation modifiers cannot be applied to the other module rules (no modifier pollution). Chainending_withorstrict_prefix_only(they are mutually exclusive), andwarn, beforebecause. - Module
Boundary - A boundary over the intra-crate module import graph — the layering Cargo cannot
see. Observed from the target crate’s source
usedeclarations (PROJECT.md). - Module
Boundary Builder - Fluent builder for a
ModuleBoundary. - Module
Boundary Draft - A module boundary awaiting its severity and reason.
- Module
Target Draft - A module boundary awaiting its module rule.
- Report
- All violations from one evaluation.
- RuleKey
- A validated semantic key for one rule family and its identity-bearing parameters.
- Stale
Policy - Pure result of applying the optional stale-baseline gate policy to an
Outcome. - Static
Observer - The static dimension as an
Observer. - Structured
Fact Identity - A validated, dimension-agnostic identity for one observed fact.
- Subject
- What an observation was asked to enforce, and how much of the workspace it reached.
- Violation
- One violated boundary.
- Violation
Id - A violation’s stable semantic identity.
Enums§
- Boundary
- One boundary, of either kind. Named
Boundary(umbrella) with the crate kind asCrateBoundary, since a module reaction is also a boundary (drift law D2). - Boundary
Kind - Which kind of boundary produced a violation.
- Defence
- The evidence state of a declared observation bound.
- Demonstrates
- What a bound’s pinning test must demonstrate, derived from its
Extent. - Dependency
Kind - Which dependency table a crate rule observes. Defaults to
Normal. Mirrors cargo’s fixed set (normal / dev / build), so it is intentionally not#[non_exhaustive]— unlikeRule, this enum will not grow. - Extent
- Where a reaction’s measure stops for one declared shape.
- Fact
Granularity - Which part of an observed fact a granularity bound limits.
- Module
Rule - What a module boundary forbids.
- Outcome
- The reaction’s outcome.
- Owner
- Who must act if a declared false negative is ever to close.
- Polarity
- The repair direction a boundary-drift violation points to.
- Reached
- What a reaction does with a shape it did see.
- Rule
- What a crate boundary forbids. Each variant is a reaction with an observation
source in
cargo metadata; no variant is named for a reaction that does not exist. - Scan
Depth - The depth or granularity level of a boundary observation.
- Severity
- How strongly a boundary reacts.
- Source
Kind - A dependency’s declared source kind, classified from
cargo metadata’ssourcefield. The vocabulary of theRule::RestrictDependencySourcesToallowlist. LikeDependencyKind, it mirrors a fixed cargo distinction (a declared source is a registry, a git, or a path), so it is intentionally not#[non_exhaustive]: it will not grow.
Traits§
- Observer
- A participant in one governance run: it observes a workspace, and declares what it does not observe.
Functions§
- apply_
baseline - Mark each violation recorded in baseline as baselined.
- check
- Run the constitution’s boundaries against the Cargo workspace at
manifest_path. - check_
and_ cover - Read the target workspace once and return both the reaction outcome and workspace
coverage. Coverage is
Somewhenever the membership was read — including when the outcome is a constitution error from a later boundary; the caller decides whether to surface it. It isNonefor either of the two facts that make a membership unavailable: thecargo metadataread itself failed, or the metadata was read and its workspace membership could not be decoded from it. Both are reported as a constitution error in the outcome, soNonenever travels alone. Onecargo metadataspawn feeds both, wherecheckplus a separate coverage pass would have spawned twice. - constitution_
json - Render the declared constitution as a JSON projection: a
constitutionname and aboundariesarray. Each entry carrieskind,target(the crate name, or the module path for a module boundary),severity,reason, and the rule with its parameters. The module-boundarytargetis the governed module path, which equals a violation’stargetfor every module rule exceptconfine_external_crate, whose violationtargetis the confined crate name (the declaration names the module it is confined to, the reaction names the crate confined). No field is invented for data the constitution does not hold. - constitution_
text - Render the declared constitution as a human-readable projection — the law as
code declares it, for a steward reviewing an amendment or an operator reading a
CI log. A projection of the Rust source of truth, never a second source and never
a reaction. An empty constitution renders its name and
(0 boundaries). - observation_
bounds - Every observation bound 圭表 declares. The order is free — every projection of the register sorts by id.
- report_
json - Render the outcome as a JSON document for machine consumption.
Delegates to
report_json_with_stale_policywith defaultdisallow_stale = false. - report_
json_ with_ stale_ policy - Render the outcome as a JSON document for machine consumption, with optional stale-disallow policy:
a faithful projection of
Outcomewith each violation’skind, the boundaryreasonas the repair hint, andexit_codemirroring the process exit.stalelists baseline entries matching no current violation. Whendisallow_staleis true andstaleis not empty,stale_disallowedis set totrue,exit_codeis1, andoutcomereflects"violations"if any violation or disallowed stale entry fails the gate. Thesubjectis emitted besideoutcometo distinguish observed-clean workspaces from unreached ones. - stale_
policy - Apply the stale-baseline gate policy once for every projection and runner consumer.
- workspace_
member_ src_ dirs - Resolve every workspace member’s source-root directory from the target workspace at
manifest_path, so a caller (the 天衡 shell, composing the 漏刻 runtime CI audit) can hand resolved&Paths to a dimension that must stay std-only and never readcargo metadataitself. Each root is the parent of the member’slib(elseproc-macro, elsebin) targetsrc_path— this preserves custom target layouts that amanifest_dir/srcshortcut would silently miss. An unreadable workspace is a constitution error, never a silent empty set.