Skip to main content

Crate guibiao

Crate guibiao 

Source
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.
BaselineEntry
One recorded baseline entry.
BoundDecl
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.
CrateBoundary
A boundary attached to one crate target, with a human-readable reason.
CrateBoundaryBuilder
Fluent builder: CrateBoundary::crate_("x").deny_external_dependencies().because("…") or CrateBoundary::crate_("x").forbid_dependency_on(["y"]).because("…").
CrateBoundaryDraft
A crate boundary awaiting its severity and reason.
CrateTarget
A crate identified by its package name.
DenyExternalDraft
A deny-external boundary awaiting an optional allowlist, severity, and reason.
Finding
Pair human-readable finding text with stable structured identity.
InlineConfinementDraft
A dedicated draft for an inline-symbol-path confinement (from must_not_call_inline). Distinct from ModuleBoundaryDraft so its narrowing / escalation modifiers cannot be applied to the other module rules (no modifier pollution). Chain ending_with or strict_prefix_only (they are mutually exclusive), and warn, before because.
ModuleBoundary
A boundary over the intra-crate module import graph — the layering Cargo cannot see. Observed from the target crate’s source use declarations (PROJECT.md).
ModuleBoundaryBuilder
Fluent builder for a ModuleBoundary.
ModuleBoundaryDraft
A module boundary awaiting its severity and reason.
ModuleTargetDraft
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.
StalePolicy
Pure result of applying the optional stale-baseline gate policy to an Outcome.
StaticObserver
The static dimension as an Observer.
StructuredFactIdentity
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.
ViolationId
A violation’s stable semantic identity.

Enums§

Boundary
One boundary, of either kind. Named Boundary (umbrella) with the crate kind as CrateBoundary, since a module reaction is also a boundary (drift law D2).
BoundaryKind
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.
DependencyKind
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] — unlike Rule, this enum will not grow.
Extent
Where a reaction’s measure stops for one declared shape.
FactGranularity
Which part of an observed fact a granularity bound limits.
ModuleRule
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.
ScanDepth
The depth or granularity level of a boundary observation.
Severity
How strongly a boundary reacts.
SourceKind
A dependency’s declared source kind, classified from cargo metadata’s source field. The vocabulary of the Rule::RestrictDependencySourcesTo allowlist. Like DependencyKind, 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 Some whenever the membership was read — including when the outcome is a constitution error from a later boundary; the caller decides whether to surface it. It is None for either of the two facts that make a membership unavailable: the cargo metadata read 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, so None never travels alone. One cargo metadata spawn feeds both, where check plus a separate coverage pass would have spawned twice.
constitution_json
Render the declared constitution as a JSON projection: a constitution name and a boundaries array. Each entry carries kind, target (the crate name, or the module path for a module boundary), severity, reason, and the rule with its parameters. The module-boundary target is the governed module path, which equals a violation’s target for every module rule except confine_external_crate, whose violation target is 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_policy with default disallow_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 Outcome with each violation’s kind, the boundary reason as the repair hint, and exit_code mirroring the process exit. stale lists baseline entries matching no current violation. When disallow_stale is true and stale is not empty, stale_disallowed is set to true, exit_code is 1, and outcome reflects "violations" if any violation or disallowed stale entry fails the gate. The subject is emitted beside outcome to 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 read cargo metadata itself. Each root is the parent of the member’s lib (else proc-macro, else bin) target src_path — this preserves custom target layouts that a manifest_dir/src shortcut would silently miss. An unreadable workspace is a constitution error, never a silent empty set.