@usefragments/core 1.10.2 → 2.0.0

package/src/evaluation/evaluate.test.ts

@@ -0,0 +1,522 @@
+/**
+ * Kernel unit spec — behaviors outside the parity corpus's reach. The
+ * scenario-level semantics (all 44 authored verdicts) are asserted by
+ * `@repo/parity`'s kernel suite; this file pins the mechanics: determinism
+ * under input reordering, facts-mode evidence, eligibility edges, waiver
+ * expiry boundaries, and explicit policy overrides.
+ */
+import { describe, expect, it } from "vitest";
+
+import { CONTRACT_PREIMAGE_SCHEMA } from "../contract/preimage.js";
+import {
+  FactIndex,
+  compileGlobalGovernanceFacts,
+  makeStyleDeclarationFact,
+} from "../facts/index.js";
+import { g } from "../governance.js";
+import { contractHash } from "../contract/hash.js";
+import type { ContractPreimage } from "../contract/preimage.js";
+import { evaluate } from "./evaluate.js";
+import type { EvaluationFindingInput, EvaluationInput } from "./types.js";
+
+const PREIMAGE: ContractPreimage = {
+  schema: CONTRACT_PREIMAGE_SCHEMA,
+  domains: {
+    components: "a".repeat(64),
+    tokens: "b".repeat(64),
+    canonicalMap: "c".repeat(64),
+    policy: "d".repeat(64),
+  },
+};
+const FCID = contractHash(PREIMAGE);
+const NOW = 1_756_400_000_000;
+
+function baseInput(overrides: Partial<EvaluationInput> = {}): EvaluationInput {
+  return {
+    contract: { state: "pinned", fcid: FCID, preimage: PREIMAGE },
+    scope: { kind: "full", coverage: { filesScanned: 3 } },
+    evidence: { kind: "findings", findings: [] },
+    policy: { failOnWarnings: false },
+    integrity: { governance: "healthy" },
+    evaluatedAt: NOW,
+    ...overrides,
+  };
+}
+
+function styleError(fingerprint = "f-1"): EvaluationFindingInput {
+  return { fingerprint, ruleId: "styles/no-raw-color", severity: "error" };
+}
+
+describe("evaluate — mechanics", () => {
+  it("verifies the FCID by recomputation and reports a mismatch as integrity", () => {
+    const ok = evaluate(baseInput());
+    expect(ok.integrity.fcidVerified).toBe(true);
+    expect(ok.verdict).toBe("pass");
+
+    const mismatch = evaluate(
+      baseInput({ contract: { state: "pinned", fcid: "0".repeat(64), preimage: PREIMAGE } })
+    );
+    expect(mismatch.integrity.fcidVerified).toBe(false);
+    expect(mismatch.reasons).toContain("contractIdentityMismatch");
+    expect(mismatch.verdict).toBe("indeterminate");
+  });
+
+  it("marks identity unavailable (never a mismatch) when no preimage is supplied", () => {
+    const result = evaluate(baseInput({ contract: { state: "pinned", fcid: FCID } }));
+    expect(result.integrity.fcidVerified).toBe("unavailable");
+    expect(result.reasons).not.toContain("contractIdentityMismatch");
+    expect(result.verdict).toBe("pass");
+  });
+
+  it("is invariant under evidence and waiver ordering", () => {
+    const findings = [styleError("b"), styleError("a")];
+    const waivers = [{ fingerprint: "b" }, { fingerprint: "a" }];
+    const forward = evaluate(baseInput({ evidence: { kind: "findings", findings }, waivers }));
+    const reversed = evaluate(
+      baseInput({
+        evidence: { kind: "findings", findings: [...findings].reverse() },
+        waivers: [...waivers].reverse(),
+      })
+    );
+    expect(forward.inputDigest).toBe(reversed.inputDigest);
+    expect(forward.resultDigest).toBe(reversed.resultDigest);
+    expect(forward.findings).toEqual(reversed.findings);
+  });
+
+  it("digests a missing evidence grade identically to an explicit source_backed", () => {
+    const explicit = evaluate(
+      baseInput({
+        evidence: {
+          kind: "findings",
+          findings: [{ ...styleError(), evidenceGrade: "source_backed" }],
+        },
+      })
+    );
+    const omitted = evaluate(
+      baseInput({ evidence: { kind: "findings", findings: [styleError()] } })
+    );
+    expect(explicit.inputDigest).toBe(omitted.inputDigest);
+    expect(explicit.resultDigest).toBe(omitted.resultDigest);
+  });
+
+  it("digests same-fingerprint waivers order-invariantly across expiries", () => {
+    const waivers = [
+      { fingerprint: "w", expiresAt: NOW + 100 },
+      { fingerprint: "w", expiresAt: NOW + 200 },
+    ];
+    const forward = evaluate(baseInput({ waivers }));
+    const reversed = evaluate(baseInput({ waivers: [...waivers].reverse() }));
+    expect(forward.inputDigest).toBe(reversed.inputDigest);
+    expect(forward.resultDigest).toBe(reversed.resultDigest);
+  });
+
+  it("digests absent, Infinity, and NaN waiver expiries identically (all never expire)", () => {
+    const absent = evaluate(baseInput({ waivers: [{ fingerprint: "w" }] }));
+    const infinite = evaluate(
+      baseInput({ waivers: [{ fingerprint: "w", expiresAt: Number.POSITIVE_INFINITY }] })
+    );
+    const nan = evaluate(baseInput({ waivers: [{ fingerprint: "w", expiresAt: Number.NaN }] }));
+    expect(infinite.inputDigest).toBe(absent.inputDigest);
+    expect(nan.inputDigest).toBe(absent.inputDigest);
+    expect(infinite.resultDigest).toBe(absent.resultDigest);
+    expect(nan.resultDigest).toBe(absent.resultDigest);
+
+    // The verdict agrees with the digest even at a non-finite evaluatedAt:
+    // an Infinity expiry never expires, so digest-equal inputs judge equal.
+    const atInfinity = evaluate(
+      baseInput({
+        evaluatedAt: Number.POSITIVE_INFINITY,
+        waivers: [{ fingerprint: "w", expiresAt: Number.POSITIVE_INFINITY }],
+      })
+    );
+    expect(atInfinity.reasons).not.toContain("expiredSuppression");
+    expect(atInfinity.verdict).toBe("pass");
+  });
+
+  it("digests unknown presets order-invariantly", () => {
+    const forward = evaluate(
+      baseInput({ integrity: { governance: "healthy", unknownPresets: ["b", "a"] } })
+    );
+    const reversed = evaluate(
+      baseInput({ integrity: { governance: "healthy", unknownPresets: ["a", "b"] } })
+    );
+    expect(forward.inputDigest).toBe(reversed.inputDigest);
+    expect(forward.resultDigest).toBe(reversed.resultDigest);
+  });
+
+  it("collapses duplicate fingerprints to one finding, keeping the harder state", () => {
+    const result = evaluate(
+      baseInput({
+        evidence: {
+          kind: "findings",
+          findings: [
+            { fingerprint: "dup", ruleId: "styles/no-raw-color", severity: "warn" },
+            { fingerprint: "dup", ruleId: "styles/no-raw-color", severity: "error" },
+          ],
+        },
+      })
+    );
+    // The warn row is advisory (not gated); the error row pends — it wins.
+    expect(result.findings).toHaveLength(1);
+    expect(result.findings[0]?.severity).toBe("error");
+    expect(result.findings[0]?.state).toBe("pending_cloud_trust");
+  });
+
+  it("never synthesizes a blocker from contradictory duplicates", () => {
+    // Each row is advisory on its own (advisory-tier error / non-gated warn).
+    // A field-wise merge would fabricate a non-advisory error that blocks
+    // under full trust — the hardest GENUINE state is advisory.
+    const result = evaluate(
+      baseInput({
+        evidence: {
+          kind: "findings",
+          findings: [
+            { ...styleError("dup"), advisory: true },
+            { fingerprint: "dup", ruleId: "styles/no-raw-color", severity: "warn" },
+          ],
+        },
+        baseline: { identityVerified: true, findingStates: { dup: "introduced" } },
+        trust: { source: "verified", mappings: {} },
+      })
+    );
+    expect(result.findings[0]?.state).toBe("advisory");
+    expect(result.verdict).toBe("pass");
+  });
+
+  it("preserves a duplicate's earned block across rule identities", () => {
+    // The style row blocks alone (evidence-class trust affirmative); the
+    // canonical row is advisory (definitive mapping negative). A merged row
+    // keyed to the lexically-smaller canonical rule would erase the block.
+    const result = evaluate(
+      baseInput({
+        evidence: {
+          kind: "findings",
+          findings: [
+            { fingerprint: "dup", ruleId: "components/prefer-library", severity: "error" },
+            styleError("dup"),
+          ],
+        },
+        baseline: { identityVerified: true, findingStates: { dup: "introduced" } },
+        trust: { source: "verified", mappings: { dup: "unconfirmed" } },
+      })
+    );
+    expect(result.findings[0]?.state).toBe("blocked");
+    expect(result.findings[0]?.ruleId).toBe("styles/no-raw-color");
+    expect(result.verdict).toBe("block");
+  });
+
+  it("never combines contradictory records' facts into an unsupported block", () => {
+    // Record A: verified source but existing debt with an unconfirmed
+    // mapping. Record B: introduced with a confirmed mapping but an unchecked
+    // source. Folding their facts together would block; neither record
+    // supports it alone — the hardest genuine state is B's pending hold.
+    const result = evaluate(
+      baseInput({
+        evidence: {
+          kind: "findings",
+          findings: [
+            {
+              fingerprint: "dup",
+              ruleId: "components/prefer-library",
+              severity: "error",
+              sourceTrust: "verified",
+              mappingTrust: "unconfirmed",
+              baselineState: "existing",
+            },
+            {
+              fingerprint: "dup",
+              ruleId: "components/prefer-library",
+              severity: "error",
+              sourceTrust: "unknown",
+              mappingTrust: "confirmed",
+              baselineState: "introduced",
+            },
+          ],
+        },
+        baseline: { identityVerified: true, findingStates: {} },
+      })
+    );
+    expect(result.findings[0]?.state).toBe("pending_cloud_trust");
+    expect(result.verdict).toBe("indeterminate");
+  });
+
+  it("never lets a waived record lend its facts or waiver to an unwaived duplicate", () => {
+    // A fully-trusted suppressed record plus an unjudged unsuppressed record:
+    // the waived record is advisory, the peer pends on its own unknowns —
+    // nothing blocks.
+    const result = evaluate(
+      baseInput({
+        evidence: {
+          kind: "findings",
+          findings: [
+            {
+              ...styleError("dup"),
+              sourceTrust: "verified",
+              baselineState: "introduced",
+              waived: true,
+            },
+            { ...styleError("dup"), sourceTrust: "unknown", baselineState: "unknown" },
+          ],
+        },
+        baseline: { identityVerified: true, findingStates: {} },
+      })
+    );
+    expect(result.findings[0]?.state).toBe("pending_cloud_trust");
+    expect(result.verdict).toBe("indeterminate");
+    expect(result.counts.blocked).toBe(0);
+  });
+
+  it("honors a definitive mapping negative on a contract-tier rule under a trust:evidence override", () => {
+    const result = evaluate(
+      baseInput({
+        evidence: {
+          kind: "findings",
+          findings: [
+            { fingerprint: "f-1", ruleId: "components/prefer-library", severity: "error" },
+          ],
+        },
+        policy: {
+          failOnWarnings: false,
+          rules: { "components/prefer-library": { trust: "evidence" } },
+        },
+        baseline: { identityVerified: true, findingStates: { "f-1": "introduced" } },
+        trust: { source: "verified", mappings: { "f-1": "unconfirmed" } },
+      })
+    );
+    // The override waives the mapping UNKNOWN, never a proven
+    // non-confirmation.
+    expect(result.findings[0]?.state).toBe("advisory");
+    expect(result.verdict).toBe("pass");
+  });
+
+  it("treats a waiver expiring exactly at evaluatedAt as expired", () => {
+    const active = evaluate(baseInput({ waivers: [{ fingerprint: "w", expiresAt: NOW + 1 }] }));
+    expect(active.reasons).not.toContain("expiredSuppression");
+    expect(active.verdict).toBe("pass");
+
+    const expired = evaluate(baseInput({ waivers: [{ fingerprint: "w", expiresAt: NOW }] }));
+    expect(expired.reasons).toContain("expiredSuppression");
+    expect(expired.verdict).toBe("block");
+  });
+
+  it("never lets advisory-tier or weak-evidence findings become candidates", () => {
+    const result = evaluate(
+      baseInput({
+        evidence: {
+          kind: "findings",
+          findings: [
+            { ...styleError("advisory"), advisory: true },
+            { ...styleError("heuristic"), evidenceGrade: "runtime_advisory" },
+            { ...styleError("unclassifiable"), evidenceGrade: "not-a-grade" },
+            { fingerprint: "info", ruleId: "styles/no-raw-color", severity: "info" },
+          ],
+        },
+      })
+    );
+    expect(result.findings.every((finding) => finding.state === "advisory")).toBe(true);
+    expect(result.verdict).toBe("pass");
+  });
+
+  it("honors an explicit trust:none policy override", () => {
+    const result = evaluate(
+      baseInput({
+        evidence: { kind: "findings", findings: [styleError()] },
+        policy: { failOnWarnings: false, rules: { "styles/no-raw-color": { trust: "none" } } },
+      })
+    );
+    expect(result.findings[0]?.state).toBe("blocked");
+    expect(result.verdict).toBe("block");
+  });
+
+  it("never enforces a proven non-reproduction, even under trust:none", () => {
+    const result = evaluate(
+      baseInput({
+        evidence: { kind: "findings", findings: [styleError()] },
+        policy: { failOnWarnings: false, rules: { "styles/no-raw-color": { trust: "none" } } },
+        trust: { source: "unverified", mappings: {} },
+      })
+    );
+    expect(result.findings[0]?.state).toBe("advisory");
+    expect(result.verdict).toBe("pass");
+  });
+
+  it("honors a definitive mapping negative on a contract-tier rule, even under trust:none", () => {
+    const result = evaluate(
+      baseInput({
+        evidence: {
+          kind: "findings",
+          findings: [
+            { fingerprint: "f-1", ruleId: "components/prefer-library", severity: "error" },
+          ],
+        },
+        policy: {
+          failOnWarnings: false,
+          rules: { "components/prefer-library": { trust: "none" } },
+        },
+        baseline: { identityVerified: true, findingStates: { "f-1": "introduced" } },
+        trust: { source: "verified", mappings: { "f-1": "unconfirmed" } },
+      })
+    );
+    // The override waives UNKNOWNS, never a proven non-confirmation — a
+    // contract-tier finding without a confirmed mapping has no named fix.
+    expect(result.findings[0]?.state).toBe("advisory");
+    expect(result.verdict).toBe("pass");
+  });
+
+  it("takes adoption facts independently of baseline identity verification", () => {
+    const regressed = evaluate(baseInput({ adoption: { regressed: true } }));
+    expect(regressed.reasons).toContain("adoptionRegression");
+    expect(regressed.verdict).toBe("block");
+
+    const unavailable = evaluate(baseInput({ adoption: "unavailable" }));
+    expect(unavailable.reasons).toContain("adoptionBaselineUnavailable");
+    expect(unavailable.verdict).toBe("indeterminate");
+  });
+
+  it("resolves per-finding source trust over the run default", () => {
+    const result = evaluate(
+      baseInput({
+        evidence: { kind: "findings", findings: [styleError("trusted"), styleError("unchecked")] },
+        baseline: {
+          identityVerified: true,
+          findingStates: { trusted: "introduced", unchecked: "introduced" },
+        },
+        trust: { source: "unknown", sources: { trusted: "verified" }, mappings: {} },
+      })
+    );
+    const byFingerprint = Object.fromEntries(
+      result.findings.map((finding) => [finding.fingerprint, finding.state])
+    );
+    // The verified blocker blocks; the unknown peer pends without diluting it.
+    expect(byFingerprint).toEqual({ trusted: "blocked", unchecked: "pending_cloud_trust" });
+    expect(result.verdict).toBe("block");
+  });
+
+  it("keeps the hardest genuinely-supported duplicate, order-invariantly", () => {
+    const advisoryRow: EvaluationFindingInput = { ...styleError("dup"), advisory: true };
+    const gatingRow = styleError("dup");
+    const forward = evaluate(
+      baseInput({ evidence: { kind: "findings", findings: [advisoryRow, gatingRow] } })
+    );
+    const reversed = evaluate(
+      baseInput({ evidence: { kind: "findings", findings: [gatingRow, advisoryRow] } })
+    );
+    expect(forward).toEqual(reversed);
+    // The non-advisory row's pending hold outranks the advisory downgrade.
+    expect(forward.findings[0]?.state).toBe("pending_cloud_trust");
+  });
+
+  it("holds default candidates with no trust facts at pending_cloud_trust", () => {
+    const result = evaluate(
+      baseInput({ evidence: { kind: "findings", findings: [styleError()] } })
+    );
+    expect(result.findings[0]?.state).toBe("pending_cloud_trust");
+    expect(result.verdict).toBe("indeterminate");
+    expect(result.derived.gatingFindingsPresent).toBe(false);
+  });
+
+  it("blocked findings win the verdict over pending ones when integrity is intact", () => {
+    const result = evaluate(
+      baseInput({
+        evidence: { kind: "findings", findings: [styleError("pending"), styleError("gated")] },
+        policy: { failOnWarnings: false, rules: {} },
+        baseline: { identityVerified: true, findingStates: { gated: "introduced" } },
+        trust: { source: "verified", mappings: {} },
+      })
+    );
+    // "pending" resolves the same facts — introduced (absent entry on a
+    // verified baseline) + verified source: both block.
+    expect(result.verdict).toBe("block");
+    expect(result.derived.gatingFindingsPresent).toBe(true);
+  });
+
+  it("derives warnPresent without ever emitting it as a reason", () => {
+    const result = evaluate(
+      baseInput({
+        evidence: {
+          kind: "findings",
+          findings: [{ fingerprint: "w", ruleId: "styles/no-raw-color", severity: "warn" }],
+        },
+      })
+    );
+    expect(result.derived.warnPresent).toBe(true);
+    expect(result.reasons).not.toContain("warnPresent" as never);
+    expect(result.verdict).toBe("pass");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Facts mode — rule config parity with the engine scan
+// ---------------------------------------------------------------------------
+
+/** One raw-hex `color` declaration under a raw-colour policy: `styles/no-raw-color` fires. */
+function rawColorIndex(rules?: Record<string, unknown>): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      styles: [
+        g.styles
+          .rawColors()
+          .forbid({ except: ["transparent"], prefer: "token", severity: "error" }),
+      ],
+      ...(rules ? { rules } : {}),
+    })
+  );
+  ix.add(
+    makeStyleDeclarationFact({
+      file: "src/icon.module.scss",
+      selector: ".icon",
+      declarationPath: "0:0",
+      property: "color",
+      value: "#00ff00",
+      location: { file: "src/icon.module.scss", line: 2, column: 2 },
+    })
+  );
+  return ix;
+}
+
+describe("evaluate — facts mode honours governance_rule_config", () => {
+  it("runs the rule and gates at its record severity when no rule config exists", () => {
+    const result = evaluate(baseInput({ evidence: { kind: "facts", facts: rawColorIndex() } }));
+    expect(result.findings).toHaveLength(1);
+    expect(result.findings[0]).toMatchObject({ ruleId: "styles/no-raw-color", severity: "error" });
+    expect(result.findings[0].stateReasons).not.toContain("ineligible:warn-not-gated");
+  });
+
+  it("never runs a rule the config disabled — a disabled rule cannot block --ci", () => {
+    // The engine scan prints nothing for a disabled rule; the kernel used to re-run
+    // it over the same facts and block on findings no surface showed.
+    const result = evaluate(
+      baseInput({
+        evidence: {
+          kind: "facts",
+          facts: rawColorIndex({ "styles/no-raw-color": { enabled: false } }),
+        },
+      })
+    );
+    expect(result.findings).toEqual([]);
+    expect(result.counts.blocked).toBe(0);
+    expect(result.derived.warnPresent).toBe(false);
+    expect(result.verdict).toBe("pass");
+  });
+
+  it("applies the configured severity exactly as the engine does", () => {
+    const result = evaluate(
+      baseInput({
+        evidence: {
+          kind: "facts",
+          facts: rawColorIndex({ "styles/no-raw-color": { enabled: true, severity: "warn" } }),
+        },
+        policy: { failOnWarnings: false },
+      })
+    );
+    expect(result.findings).toHaveLength(1);
+    expect(result.findings[0]).toMatchObject({
+      ruleId: "styles/no-raw-color",
+      severity: "warn",
+      state: "advisory",
+      stateReasons: ["ineligible:warn-not-gated"],
+    });
+    expect(result.counts.blocked).toBe(0);
+  });
+});