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
//! The projections: the text and JSON renderings of an [`Outcome`] and a
//! [`Constitution`]. A projection is a faithful, self-describing view of the model
//! for humans (text) and machines (JSON) — it adds no policy and makes no decision
//! (PROJECT.md). The *per-type* serialization (a [`Violation`] → JSON, the
//! infallible `pretty_json`) lives in the dimension-agnostic `xuanji` crate; this
//! module assembles the *document* — folding in the static [`Coverage`] and stale
//! baseline entries — which is why it stays here in the engine, not in the model.

use super::*;
use serde_json::Value;
use xuanji::pretty_json;

/// 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.
pub fn report_json_with_stale_policy(
    outcome: &Outcome,
    stale: &[BaselineEntry],
    coverage: Option<&Coverage>,
    disallow_stale: bool,
) -> String {
    let policy = stale_policy(outcome, stale, disallow_stale);
    let has_disallowed_stale = policy.stale_disallowed;
    let (label, violations, error, subject) = match outcome {
        Outcome::Clean(subject) => (
            if has_disallowed_stale {
                "violations"
            } else {
                "clean"
            },
            Vec::new(),
            Value::Null,
            Some(*subject),
        ),
        Outcome::Violations(report) => (
            "violations",
            report.violations.iter().map(Violation::to_json).collect(),
            Value::Null,
            None,
        ),
        Outcome::ConstitutionError(message) => (
            "constitution_error",
            Vec::new(),
            Value::String(message.clone()),
            None,
        ),
        _ => ("unknown", Vec::new(), Value::Null, None),
    };
    let stale_baseline: Vec<Value> = stale
        .iter()
        .map(|entry| {
            let mut object = entry.id.to_json();
            object["rule"] = serde_json::json!(entry.rule);
            object["finding"] = serde_json::json!(entry.finding);
            object["owner"] = serde_json::json!(entry.owner);
            object["tracker"] = serde_json::json!(entry.tracker);
            object
        })
        .collect();
    let mut document = serde_json::json!({
        "format": "tianheng.reaction/structured-facts",
        "outcome": label,
        "exit_code": policy.exit_code,
        "violations": violations,
        "stale_baseline": stale_baseline,
        "stale_disallowed": has_disallowed_stale,
        "error": error,
    });
    if let Some(subject) = subject {
        document["subject"] = serde_json::json!({
            "declared": subject.declared(),
            "reached": subject.reached(),
        });
    }
    if let Some(coverage) = coverage {
        document["coverage"] = serde_json::json!({
            "workspace_crates": coverage.total,
            "uncovered": coverage.uncovered,
        });
    }
    pretty_json(&document)
}

/// Pure result of applying the optional stale-baseline gate policy to an [`Outcome`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StalePolicy {
    /// Whether stale entries exist and the caller requested that they fail the gate.
    pub stale_disallowed: bool,
    /// Final process exit code after applying the policy.
    pub exit_code: u8,
}

/// Apply the stale-baseline gate policy once for every projection and runner consumer.
///
/// Disallowed stale entries turn an otherwise successful reaction into exit `1`; an existing
/// violation or constitution error retains its own exit code.
pub fn stale_policy(
    outcome: &Outcome,
    stale: &[BaselineEntry],
    disallow_stale: bool,
) -> StalePolicy {
    let stale_disallowed = disallow_stale && !stale.is_empty();
    let exit_code = if stale_disallowed && outcome.exit_code() == 0 {
        1
    } else {
        outcome.exit_code()
    };
    StalePolicy {
        stale_disallowed,
        exit_code,
    }
}

/// Render the outcome as a JSON document for machine consumption.
/// Delegates to [`report_json_with_stale_policy`] with default `disallow_stale = false`.
pub fn report_json(
    outcome: &Outcome,
    stale: &[BaselineEntry],
    coverage: Option<&Coverage>,
) -> String {
    report_json_with_stale_policy(outcome, stale, coverage, false)
}

/// 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)`.
pub fn constitution_text(constitution: &Constitution) -> String {
    let boundaries = constitution.boundaries();
    let noun = if boundaries.len() == 1 {
        "boundary"
    } else {
        "boundaries"
    };
    let mut out = format!(
        "Constitution: {}  ({} {noun})\n",
        constitution.name(),
        boundaries.len()
    );
    for boundary in boundaries {
        let (severity, target, rule, reason) = match boundary {
            Boundary::Crate(b) => {
                let rule = match dependency_kind_label(b.dependency_kind()) {
                    Some(kind) => format!("{} ({kind} dependencies)", b.rule().text()),
                    None => b.rule().text(),
                };
                (
                    b.severity(),
                    format!("crate {}", b.target().package),
                    rule,
                    b.reason(),
                )
            }
            Boundary::Module(b) => (
                b.severity(),
                format!("module {} in {}", b.module(), b.crate_package()),
                b.rule().text(),
                b.reason(),
            ),
        };
        out.push_str(&format!(
            "\n[{}] {target}\n  rule:   {rule}\n  reason: {reason}\n",
            severity.as_str()
        ));
    }
    out
}

/// 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.
pub fn constitution_json(constitution: &Constitution) -> String {
    let boundaries: Vec<Value> = constitution
        .boundaries()
        .iter()
        .map(boundary_json)
        .collect();
    let document = serde_json::json!({
        "format": "tianheng.constitution/declared-boundaries",
        "constitution": constitution.name(),
        "boundaries": boundaries,
    });
    pretty_json(&document)
}

/// Projects a single boundary to JSON. Anchors and non-default dependency kinds are only emitted
/// when set, preserving byte-identical output when unset.
fn boundary_json(boundary: &Boundary) -> Value {
    match boundary {
        Boundary::Crate(b) => {
            let mut object = serde_json::json!({
                "kind": "crate",
                "target": b.target().package,
                "rule": b.rule().label(),
                "severity": b.severity().as_str(),
                "reason": b.reason(),
            });
            for (key, value) in b.rule().json_params() {
                object[key] = value;
            }
            if let Some(kind) = dependency_kind_label(b.dependency_kind()) {
                object["dependency_kind"] = serde_json::json!(kind);
            }
            if let Some(anchor) = b.anchor() {
                object["anchor"] = serde_json::json!(anchor);
            }
            object
        }
        Boundary::Module(b) => {
            let mut object = serde_json::json!({
                "kind": "module",
                "target": b.module(),
                "crate": b.crate_package(),
                "rule": b.rule().label(),
                "severity": b.severity().as_str(),
                "reason": b.reason(),
            });
            for (key, value) in b.rule().json_params() {
                object[key] = value;
            }
            if let Some(anchor) = b.anchor() {
                object["anchor"] = serde_json::json!(anchor);
            }
            if b.scan_depth().is_shallow() {
                object["scan_depth"] = serde_json::json!(b.scan_depth().as_str());
            }
            object
        }
    }
}

/// The projection label for a non-default dependency kind, or `None` for `Normal` so
/// the common projection is unchanged.
fn dependency_kind_label(kind: DependencyKind) -> Option<&'static str> {
    match kind {
        DependencyKind::Normal => None,
        DependencyKind::Dev => Some("dev"),
        DependencyKind::Build => Some("build"),
    }
}