guibiao 0.9.0

圭表 (Guibiao) — Tianheng's dependency-light static observation core (derived from modou). Declare crate, module, and dependency-source boundaries in Rust — dependencies by name, module imports, and each dependency's declared source kind (git/registry/path) for manifest hygiene — observed from cargo metadata and source use-scans, reacted in CI. No AST: the syn-free gnomon of the family.
Documentation
use std::path::Path;

/// The target workspace could not be read — a missing or malformed manifest, or a
/// `cargo metadata` failure. `err` is the underlying cause.
///
/// Deliberate **verbatim** twin of hunyi's `unreadable_workspace_error` (the price of the dimension
/// split; sharing a module would need a forbidden guibiao↔hunyi edge). The two copies MUST stay
/// byte-identical — an unreadable workspace reads the same in either dimension.
pub(crate) fn unreadable_workspace_error(manifest_path: &Path, err: &str) -> String {
    format!(
        "a boundary is observed against a real workspace, so an unreadable one cannot be judged \
         and its verdict would be a false pass: cannot read target workspace at {} ({err}); check \
         the manifest path and that `cargo metadata` succeeds",
        manifest_path.display()
    )
}

/// A boundary names a crate that is not a member of the target workspace.
///
/// Deliberate **verbatim** twin of hunyi's `crate_not_found_error` (dimension split; a shared module
/// would need a forbidden guibiao↔hunyi edge). The two copies MUST stay byte-identical.
pub(crate) fn crate_not_found_error(crate_package: &str) -> String {
    format!(
        "a boundary must govern a real crate or it silently never reacts: target crate \
         '{crate_package}' is not a member of the target workspace — check the name or --manifest-path"
    )
}

/// A workspace member's `src` directory could not be located from its manifest.
///
/// Deliberate **parallel** twin of hunyi's `missing_src_error`: same intent and structure, differing
/// only in the dimension noun ("module" here in 圭表, "semantic" in 渾儀) — not a verbatim twin,
/// because each dimension names its own boundary kind.
pub(crate) fn missing_src_error(crate_package: &str) -> String {
    format!(
        "a module boundary is observed from source, so with no src it could never react: cannot \
         locate the crate root source for '{crate_package}'"
    )
}

/// A package whose every target is an example, a test, a bench or a build script: no compiled root reads its
/// `src/`, so a module boundary there could never react.
///
/// Deliberate **parallel** twin of hunyi's `no_compiled_root_error`: same intent and structure, differing
/// only in the dimension noun ("module" here in 圭表, "semantic" in 渾儀) — not a verbatim twin,
/// because each dimension names its own boundary kind.
pub(crate) fn no_compiled_root_error(crate_package: &str) -> String {
    format!(
        "a module boundary is observed from a compiled crate root, and '{crate_package}' has none: no target \
         Cargo reports for it is a library or a binary, so nothing its src directory holds is compiled into a \
         root this boundary could govern"
    )
}

/// A module boundary targets an inline `mod name { … }`, which owns no source file
/// and so cannot be a governed target — distinct from an unknown-module typo.
pub(crate) fn inline_module_target_error(
    module: &str,
    crate_package: &str,
    leaf: &str,
    unit: Option<&str>,
    suggested_path: &str,
) -> String {
    let unit_qualifier = match unit {
        Some(u) => format!(" in compilation unit '{u}'"),
        None => String::new(),
    };
    format!(
        "module '{module}' in crate '{crate_package}'{unit_qualifier} is declared inline (`mod {leaf} {{ … }}`) and \
         owns no source file; module boundaries govern file-based modules — move it \
         into its own file (e.g. `{suggested_path}`), use `#[path = \"…\"]`, or target an enclosing file-based \
         module"
    )
}

/// A module boundary targets a path that is not a reachable module of the crate
/// (e.g. a typo), distinct from an inline target.
///
/// Deliberate **parallel** twin of hunyi's `unknown_module_error`: both carry the same principle
/// preamble and `— check the path` tail, differing only in the dimension-accurate detail (圭表's
/// module graph is **file-based reachability**; 渾儀 descends declared `mod`s incl. inline).
pub(crate) fn unknown_module_error(module: &str, crate_package: &str) -> String {
    format!(
        "a boundary must anchor to a real module or it silently never reacts: module '{module}' is \
         not found among the reachable modules of crate '{crate_package}' (declared via `mod`, \
         file-based) — check the path"
    )
}

/// A module path — a governed module, or a module a rule names — written in a spelling other than
/// the canonical one. `suggestion` is the canonical spelling the written one most plausibly meant,
/// when there is one.
///
/// Deliberate **verbatim** twin of hunyi's `non_canonical_module_anchor_error` (dimension split; a
/// shared module would need a forbidden guibiao↔hunyi edge). The two copies MUST stay
/// byte-identical — one spelling rule reads the same in either dimension.
pub(crate) fn non_canonical_module_path_error(
    written: &str,
    crate_package: &str,
    suggestion: Option<&str>,
) -> String {
    let repair = match suggestion {
        Some("crate") => "write `crate` for the crate root".to_string(),
        Some(spelling) => format!("write `{spelling}`"),
        None => "write the module's path from the crate root, starting `crate::`".to_string(),
    };
    format!(
        "a module is named by one spelling or it becomes two identities: '{written}' in crate \
         '{crate_package}' is not `crate` or `crate::` followed by `::`-separated identifiers — \
         {repair}"
    )
}

/// A `must_not_import` or `must_not_be_imported_by` boundary naming a module that no compiled root
/// of the crate declares: the edge it forbids can never be observed.
pub(crate) fn unknown_forbidden_module_error(
    module: &str,
    crate_package: &str,
    rule_method: &str,
) -> String {
    format!(
        "a forbidden module must be a real module or the rule silently never reacts: `{rule_method}` \
         names '{module}', which is not found among the reachable modules of crate \
         '{crate_package}' (declared via `mod`) — check the path"
    )
}

/// A `restrict_imports_to` or `must_only_be_imported_by` allowlist entry naming a module that no
/// compiled root of the crate declares: the entry can never match, so every edge it was meant to
/// permit is reported.
pub(crate) fn unknown_allowed_module_error(
    module: &str,
    crate_package: &str,
    rule_method: &str,
) -> String {
    format!(
        "an allowed module must be a real module or it can never match: `{rule_method}` names \
         '{module}', which is not found among the reachable modules of crate '{crate_package}' \
         (declared via `mod`) — check the path"
    )
}

/// A `restrict_imports_to` boundary targets the crate root `crate`, which has no
/// outward internal edge.
pub(crate) fn restrict_imports_to_on_crate_error(crate_package: &str) -> String {
    format!(
        "the `restrict_imports_to` rule cannot govern `crate` (the crate root) of crate \
         '{crate_package}': the root has no outward internal edge — every internal import is \
         within its own subtree, so the rule could never react; declare it on a submodule \
         (e.g. `crate::kernel`) instead"
    )
}

/// A `must_not_be_imported_by` boundary protects the crate root `crate`, against which
/// every internal import (`crate::…`) is "the protected module or beneath".
pub(crate) fn must_not_be_imported_by_on_crate_error(crate_package: &str) -> String {
    format!(
        "the `must_not_be_imported_by` rule cannot protect `crate` (the crate root) of crate \
         '{crate_package}': every internal import is within the crate root, so the rule could \
         never react as an inbound rule; declare it on a submodule (e.g. `crate::internal`) \
         instead"
    )
}

/// A `must_only_be_imported_by` boundary protecting the crate root `crate` degenerates the same
/// way as `must_not_be_imported_by`.
pub(crate) fn must_only_be_imported_by_on_crate_error(crate_package: &str) -> String {
    format!(
        "the `must_only_be_imported_by` rule cannot protect `crate` (the crate root) of crate \
         '{crate_package}': every module is within the crate root, so none is an inbound importer \
         and the allowlist could never react; declare it on a submodule (e.g. `crate::internal`) \
         instead"
    )
}

/// A `confine_external_crate` boundary confines a crate to the crate root `crate`, whose
/// subtree is the whole crate — the confined crate would be permitted everywhere and the
/// rule could never react.
pub(crate) fn confine_external_crate_on_crate_error(crate_package: &str) -> String {
    format!(
        "the `confine_external_crate` rule cannot confine a crate to `crate` (the crate root) of \
         crate '{crate_package}': the root's subtree is the whole crate, so the confined crate \
         would be permitted everywhere and the rule could never react; confine it to a submodule \
         (e.g. `crate::ffi`) instead"
    )
}

/// A `confine_inline_call` boundary permits its prefix within `crate` (the crate root), whose subtree is the whole
/// crate — the prefix would be permitted everywhere and the rule could never react.
pub(crate) fn confine_inline_call_on_crate_error(crate_package: &str) -> String {
    format!(
        "the `confine_inline_call` rule cannot permit a prefix only within `crate` (the crate root) of crate \
         '{crate_package}': the root's subtree is the whole crate, so the prefix would be permitted everywhere and \
         the rule could never react; confine it to a submodule (e.g. `crate::exec`) instead"
    )
}

/// A `confine_inline_call` boundary is declared at `ScanDepth::Shallow`. The permitted region is judged at file-module
/// grain, and a shallow region is the anchored module alone, so the permitted file's inline child modules — outside
/// that region — could not be told apart from it; refusing is what keeps that from being a silent pass.
pub(crate) fn confine_inline_call_shallow_error(crate_package: &str) -> String {
    format!(
        "the `confine_inline_call` rule of crate '{crate_package}' cannot be judged at `ScanDepth::Shallow`: the \
         permitted region is compared at the grain of a file's module, and a shallow region is the anchored module \
         alone, so a call in an inline child module of the permitted file would be read as permitted; declare it at \
         the default subtree depth instead"
    )
}

/// An inline confinement (`must_not_call_inline` or `confine_inline_call`, named by `rule`) declares an empty
/// confined prefix, which would match everything or nothing — a misdeclaration, never a silent no-op.
pub(crate) fn inline_empty_prefix_error(crate_package: &str, rule: &str) -> String {
    format!(
        "the `{rule}` rule needs a non-empty module-path prefix (e.g. `std::time`) \
         to confine, in crate '{crate_package}': an empty prefix cannot name a surface, so the \
         rule could never react meaningfully"
    )
}

/// An inline confinement (`must_not_call_inline` or `confine_inline_call`, named by `rule`) declares a
/// prefix in a spelling other than `::`-separated identifiers. `suggestion` is the spelling it most
/// plausibly meant, when there is one.
pub(crate) fn non_canonical_inline_prefix_error(
    written: &str,
    crate_package: &str,
    rule: &str,
    suggestion: Option<&str>,
) -> String {
    let repair = match suggestion {
        Some(spelling) => format!("write `{spelling}`"),
        None => "write the path from `crate`, `std`, `core`, `alloc` or a dependency".to_string(),
    };
    format!(
        "a prefix is compared segment by segment, so it has one spelling: `{rule}` in crate \
         '{crate_package}' names '{written}', which is not `::`-separated identifiers rooted at a crate — {repair}"
    )
}

/// An inline confinement (`must_not_call_inline` or `confine_inline_call`, named by `rule`) declares a
/// prefix whose first segment no sysroot crate, dependency or library of the package confirms, while the
/// same path rooted at `crate` — `rooted` — names something the crate declares.
pub(crate) fn unknown_inline_prefix_head_error(
    written: &str,
    crate_package: &str,
    rule: &str,
    rooted: &str,
) -> String {
    format!(
        "a prefix of the crate's own path starts at `crate`, or the rule silently never reacts: `{rule}` \
         in crate '{crate_package}' names '{written}', whose first segment is not a sysroot crate, a \
         dependency or the package's library, while `{rooted}` names something the crate declares — \
         write `{rooted}`, or `::{written}` for an external crate"
    )
}

/// An inline confinement (`must_not_call_inline` or `confine_inline_call`, named by `rule`) declares a
/// `crate::` prefix naming neither a module some compiled root declares nor an item one defines.
pub(crate) fn unknown_inline_prefix_error(
    written: &str,
    crate_package: &str,
    rule: &str,
) -> String {
    format!(
        "a prefix must name something or the rule silently never reacts: `{rule}` names \
         '{written}', which is neither a reachable module of crate '{crate_package}' (declared via \
         `mod`) nor an item one defines — check the path"
    )
}

/// An inline confinement (`must_not_call_inline` or `confine_inline_call`, named by `rule`) declares
/// `.ending_with([])` with an empty verb set, which would narrow the reaction to nothing — a silent no-op, resolved
/// loudly (exit 2).
pub(crate) fn inline_empty_verbs_error(crate_package: &str, rule: &str) -> String {
    format!(
        "a `{rule}` boundary in crate '{crate_package}' declares `.ending_with([])` \
         with an empty verb set, which would react on nothing (a silent no-op); pass at least one \
         read verb (e.g. `[\"now\"]`) or drop the narrowing"
    )
}

/// An inline confinement (`must_not_call_inline` or `confine_inline_call`, named by `rule`) declares both
/// `.ending_with(…)` (narrow to read verbs) and `.strict_prefix_only()` (widen to all mentions) — a contradiction,
/// resolved loudly (exit 2) rather than by a silent precedence choice.
pub(crate) fn inline_narrow_and_strict_error(crate_package: &str, rule: &str) -> String {
    format!(
        "a `{rule}` boundary in crate '{crate_package}' declares both `.ending_with(…)` \
         and `.strict_prefix_only()`, which contradict (narrow to read verbs vs. widen to all \
         mentions); choose one"
    )
}

/// A governed source file could not be read. Failing loud rather than skipping it,
/// which could hide a real violation.
pub(crate) fn unreadable_governed_file_error(file: &Path, err: &str) -> String {
    format!(
        "a governed file that cannot be read is 'cannot judge', not 'nothing to judge' — skipping \
         it could hide a real violation: cannot read governed source file '{}' ({err})",
        file.display()
    )
}

/// A source file the scan read but could not judge — a nesting cap, a chain past its cap — named with the refusal, so
/// a crate of many files says which one to repair. It is a governed file, or for the inline scan any file of the
/// compilation unit, since every file's scope table is read in resolving a governed one.
pub(crate) fn scan_refusal_in_file(file: &Path, refusal: &str) -> String {
    format!("cannot judge source file '{}': {refusal}", file.display())
}

/// A refusal the module walk of one compilation unit returned, named with the crate and the unit it walked, so a
/// package of several roots says which one declares the module to repair.
pub(crate) fn walk_refusal_in_unit(
    crate_package: &str,
    unit: Option<&str>,
    refusal: &str,
) -> String {
    let unit_qualifier = match unit {
        Some(u) => format!(" in compilation unit '{u}'"),
        None => String::new(),
    };
    format!("cannot walk crate '{crate_package}'{unit_qualifier}: {refusal}")
}

/// Targets sharing one root in different editions are two compilations of one file, and a scan reads it once.
pub(crate) fn root_in_several_editions_error(
    crate_package: &str,
    root: &std::path::Path,
    editions: &[&str],
) -> String {
    format!(
        "a crate root is read in the edition its target is compiled in, and targets sharing one root in \
         different editions compile it once in each, which one reading cannot judge: crate \
         '{crate_package}' roots targets in editions {} at '{}'; give each edition its own root file, or \
         one edition to every target rooted there",
        editions.join(", "),
        root.display()
    )
}

/// A package target whose root source file lies outside the package's own manifest directory cannot be
/// given a checkout-independent identity label, so it is "cannot judge" rather than a silent pass or a
/// checkout-dependent label — the same ordering 漏刻 applies when refusing a relative or empty anchor.
pub(crate) fn out_of_package_root_error(crate_package: &str, root: &std::path::Path) -> String {
    format!(
        "a violation's identity is labeled by the compilation unit it came from, relative to the \
         package's own directory, so a crate root outside that directory cannot be judged without a \
         checkout-dependent identity: crate '{crate_package}' declares a target rooted at '{}', which \
         is not under the package's manifest directory; move the target's source under the package \
         directory, or declare the boundary against the package that owns it",
        root.display()
    )
}