@usefragments/core 1.5.2 → 1.6.0

package/src/governance-integrity.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, it } from "vitest";
 
-import type { GovernanceConfig } from "./governance.js";
+import type { GovernanceConfig, GovernanceSeverity } from "./governance.js";
 import {
+  collidingRecordDiagnostic,
+  collidingRecordDiagnostics,
+  configRecordShape,
+  overriddenRecordSeverityDiagnostic,
   detectOrphanGovernanceScales,
   detectUnconsumedConfigKeys,
   evaluateGovernanceIntegrity,
@@ -9,6 +13,12 @@ import {
   isEffectiveCanonicalSource,
   type GovernanceIntegrityInput,
 } from "./governance-integrity.js";
+import {
+  makeStyleFontSizeScaleFact,
+  makeStylePropertyScaleFact,
+  makeStyleRawColorForbiddenFact,
+  makeTokenDefinitionFact,
+} from "./facts/index.js";
 import { customerDefaultRuleStates } from "./rules/presets.js";
 import { fragmentsConfigSchema } from "./schema.js";
 
@@ -80,7 +90,7 @@ describe("inert config diagnostics", () => {
           space: { kind: "scale", unit: "px", values: [0, 4, 8], source: "legacy" },
         },
         rules: {
-          "styles/no-raw-color": { enabled: true, exclude: ["vendor/**"] },
+          "styles/no-raw-color": { enabled: true, exclude: ["vendor/**"], scope: "app" },
           "styles/not-a-real-rule": { enabled: true },
         },
       },
@@ -88,7 +98,7 @@ describe("inert config diagnostics", () => {
     const parsed = fragmentsConfigSchema.parse(authored);
 
     expect(detectUnconsumedConfigKeys(authored, parsed)).toMatchObject([
-      { code: "FUI9004", path: "govern.rules.styles/no-raw-color.exclude" },
+      { code: "FUI9004", path: "govern.rules.styles/no-raw-color.scope" },
       { code: "FUI9004", path: "govern.rules.styles/not-a-real-rule" },
       { code: "FUI9004", path: "govern.scales.space.source" },
       { code: "FUI9004", path: "screenshots.renderer" },
@@ -97,6 +107,17 @@ describe("inert config diagnostics", () => {
     ]);
   });
 
+  it("does not diagnose a rule-keyed exclude, which the scan consumes", () => {
+    const authored = {
+      govern: {
+        rules: { "styles/no-raw-color": { exclude: ["src/legacy/vendor/**"] } },
+      },
+    };
+    const parsed = fragmentsConfigSchema.parse(authored);
+
+    expect(detectUnconsumedConfigKeys(authored, parsed)).toEqual([]);
+  });
+
   it("reports an authored spacing scale that no effective property policy references", () => {
     const declared: GovernanceConfig = {
       scales: {
@@ -145,6 +166,156 @@ describe("inert config diagnostics", () => {
 
     expect(detectOrphanGovernanceScales(policy, policy)).toEqual([]);
   });
+
+  it("accepts govern.ci.failOnInert as a consumed key", () => {
+    const authored = { govern: { ci: { failOnInert: true } } };
+
+    expect(detectUnconsumedConfigKeys(authored, fragmentsConfigSchema.parse(authored))).toEqual([]);
+  });
+});
+
+describe("collidingRecordDiagnostic", () => {
+  const scaleFact = (property: string, scale: string, severity: GovernanceSeverity) =>
+    makeStylePropertyScaleFact({ property, scale, severity });
+
+  it("names the enforced and dropped settings of a colliding config record", () => {
+    const kept = scaleFact("padding", "space", "warn");
+    const skipped = scaleFact("padding", "myScale", "error");
+
+    expect(collidingRecordDiagnostic({ kept, skipped })).toEqual({
+      code: "FUI9007",
+      kind: "colliding-record",
+      severity: "warn",
+      path: "govern.styles[style.rawSpacing.mustMatchScale property=padding]",
+      message: expect.stringContaining("scale=space") as unknown as string,
+    });
+    expect(collidingRecordDiagnostic({ kept, skipped })?.message).toContain("scale=myScale");
+  });
+
+  it("names the colliding record kind for singleton records", () => {
+    expect(
+      collidingRecordDiagnostic({
+        kept: makeStyleRawColorForbiddenFact({ except: [], prefer: "token", severity: "warn" }),
+        skipped: makeStyleRawColorForbiddenFact({
+          except: [],
+          prefer: "css-variable",
+          severity: "error",
+        }),
+      })?.path
+    ).toBe("govern.styles[style.rawColors.forbid]");
+  });
+
+  // Two singleton-keyed kinds live in one section. If their diagnostics share a path,
+  // the (code, path) dedupe every consumer runs discards one collision entirely — the
+  // silent drop this code exists to end, reintroduced one layer up.
+  it("gives two different singleton kinds in one section distinct identities", () => {
+    const rawColor = collidingRecordDiagnostic({
+      kept: makeStyleRawColorForbiddenFact({ except: [], prefer: "token", severity: "warn" }),
+      skipped: makeStyleRawColorForbiddenFact({
+        except: [],
+        prefer: "css-variable",
+        severity: "error",
+      }),
+    });
+    const fontSize = collidingRecordDiagnostic({
+      kept: makeStyleFontSizeScaleFact({ scale: "type", severity: "warn" }),
+      skipped: makeStyleFontSizeScaleFact({ scale: "legacyType", severity: "error" }),
+    });
+
+    expect(rawColor?.path).not.toBe(fontSize?.path);
+    expect(fontSize?.path).toBe("govern.styles[style.fontSize.mustMatchScale]");
+    expect(fontSize?.message).toContain("style.fontSize.mustMatchScale");
+  });
+
+  it("leaves token-channel collisions to the token diagnostics, not config truth", () => {
+    const token = (value: string) =>
+      makeTokenDefinitionFact({
+        name: "--fui-color-accent",
+        value,
+        location: { file: "tokens/base.css", line: 1, column: 1 },
+      });
+
+    expect(collidingRecordDiagnostic({ kept: token("#000"), skipped: token("#fff") })).toBeNull();
+  });
+
+  it("ignores collisions between different fact kinds", () => {
+    expect(
+      collidingRecordDiagnostic({
+        kept: scaleFact("padding", "space", "warn"),
+        skipped: makeStyleFontSizeScaleFact({ scale: "type", severity: "warn" }),
+      })
+    ).toBeNull();
+  });
+
+  // Three records on one fact id produce TWO conflicts that render the same path. Emitted
+  // separately, the (code, path) dedupe every consumer runs kept only the last pair and
+  // the intermediate record vanished — the silence this code exists to end, one layer up.
+  it("aggregates a three-way collision into one diagnostic that names every drop", () => {
+    const diagnostics = collidingRecordDiagnostics([
+      {
+        kept: scaleFact("padding", "space", "warn"),
+        skipped: scaleFact("padding", "myScale", "error"),
+      },
+      {
+        kept: scaleFact("padding", "space", "warn"),
+        skipped: scaleFact("padding", "legacy", "info"),
+      },
+    ]);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.path).toBe(
+      "govern.styles[style.rawSpacing.mustMatchScale property=padding]"
+    );
+    expect(diagnostics[0]?.message).toContain("has 3 `style.rawSpacing.mustMatchScale` records");
+    expect(diagnostics[0]?.message).toContain("scale=myScale");
+    expect(diagnostics[0]?.message).toContain("scale=legacy");
+  });
+
+  it("keeps distinct fact ids in distinct diagnostics", () => {
+    expect(
+      collidingRecordDiagnostics([
+        {
+          kept: scaleFact("padding", "space", "warn"),
+          skipped: scaleFact("padding", "myScale", "error"),
+        },
+        { kept: scaleFact("gap", "space", "warn"), skipped: scaleFact("gap", "myScale", "error") },
+      ]).map((diagnostic) => diagnostic.path)
+    ).toEqual([
+      "govern.styles[style.rawSpacing.mustMatchScale property=padding]",
+      "govern.styles[style.rawSpacing.mustMatchScale property=gap]",
+    ]);
+  });
+});
+
+describe("overriddenRecordSeverityDiagnostic", () => {
+  it("names the record, the override that outranked it, and both severities", () => {
+    expect(
+      overriddenRecordSeverityDiagnostic({
+        ruleId: "styles/no-raw-color",
+        source: "govern.rules[tokens/hardcoded-values]",
+        section: "govern.styles",
+        record: "style.rawColors.forbid",
+        authored: "serious",
+        enforced: "moderate",
+      })
+    ).toEqual({
+      code: "FUI9008",
+      kind: "overridden-record-severity",
+      severity: "warn",
+      path: "govern.styles[style.rawColors.forbid]",
+      message: expect.stringContaining(
+        "govern.rules[tokens/hardcoded-values]"
+      ) as unknown as string,
+    });
+  });
+
+  it("reads the authoring record off the one config-record table", () => {
+    expect(configRecordShape("style_raw_color_forbidden")).toEqual({
+      section: "govern.styles",
+      record: "style.rawColors.forbid",
+    });
+    expect(configRecordShape("token_definition")).toBeNull();
+  });
 });
 
 describe("evaluateGovernanceIntegrity", () => {

package/src/governance-integrity.ts

@@ -18,14 +18,26 @@
  */
 
 import type { CanonicalSource, GovernanceConfig, GovernanceSeverity } from "./governance.js";
+import {
+  normalizePolicyExcludes,
+  policyExcludeMatchesPath,
+  type PolicyExclude,
+} from "./policy-exclude.js";
 import { compileGlobalGovernanceFacts } from "./facts/index.js";
+import type { FactConflict } from "./facts/index.js";
+import { RULE_FAMILY_IDS } from "./rules/families.js";
 import { FRAGMENTS_INTERNAL_RULE_IDS, RULE_TIER } from "./rules/tiers.js";
 import { BLOCKING_RULE_ALLOWLIST } from "./rules/emit-gate.js";
 
 export type GovernanceIntegrityStatus = "healthy" | "degraded" | "inert";
 
-export type InertConfigDiagnosticKind = "orphan-scale" | "unconsumed-key";
-export type InertConfigDiagnosticCode = "FUI9004" | "FUI9005";
+export type InertConfigDiagnosticKind =
+  | "orphan-scale"
+  | "unconsumed-key"
+  | "unmatched-exclude"
+  | "colliding-record"
+  | "overridden-record-severity";
+export type InertConfigDiagnosticCode = "FUI9004" | "FUI9005" | "FUI9006" | "FUI9007" | "FUI9008";
 
 export interface InertConfigDiagnostic {
   code: InertConfigDiagnosticCode;
@@ -152,10 +164,13 @@ function dedupe(values: string[]): string[] {
   return [...new Set(values)];
 }
 
-const RULE_FAMILY_IDS = new Set(["tokens/hardcoded-values", "components/usage", "a11y/wcag"]);
 const CONSUMED_RULE_IDS = new Set(Object.keys(RULE_TIER));
 const RECOGNIZED_RULE_IDS = new Set([...CONSUMED_RULE_IDS, ...RULE_FAMILY_IDS]);
-const RULE_CONFIG_KEYS = new Set(["enabled", "severity", "options"]);
+// `exclude` is consumed by the scan's finding-override pass (it scopes the rule off
+// the matching paths and reports each drop in the ignored accounting). It was absent
+// from this allow-set, so a working key was diagnosed as inert — the diagnostic was
+// wrong, not the config.
+const RULE_CONFIG_KEYS = new Set(["enabled", "severity", "options", "exclude"]);
 
 const PASSTHROUGH_KEYS = [
   {
@@ -195,7 +210,7 @@ const PASSTHROUGH_KEYS = [
   },
   {
     path: ["govern", "ci"],
-    keys: ["failOnWarnings"],
+    keys: ["failOnWarnings", "failOnInert"],
   },
 ] as const;
 
@@ -237,6 +252,232 @@ function unconsumedKeyDiagnostic(path: readonly (string | number)[]): InertConfi
   };
 }
 
+/**
+ * Config-record fact kinds: the policy facts that a `govern.*` record compiles into,
+ * paired with the config section that authored them, the authored record that produced
+ * them, and the identity keys their fact id is built from.
+ *
+ * `record` is load-bearing, not decoration. Several kinds in one section key on nothing
+ * (`style.rawColors.forbid`, `style.cssVars.mustBeDefined`, …) or on the same fields
+ * (`jsx.importPath.prefer` and `jsx.component.prefer` both on from/to), so a
+ * section-only diagnostic path makes two DIFFERENT collisions look like one — and the
+ * (code, path) dedupe every consumer runs then discards all but the last, which is the
+ * silence this diagnostic exists to end.
+ *
+ * Deliberately NOT the whole `PolicyFact` union — `token_definition` and
+ * `contract_token` are compiled from token *files*, not authored config records, and
+ * their collisions belong to the token-catalog diagnostics channel. Naming a duplicate
+ * token as a config defect would misattribute it and drown the real signal.
+ */
+const CONFIG_RECORD_FACT_KINDS: Readonly<
+  Record<string, { section: string; record: string; keys: string[] }>
+> = {
+  scale: { section: "govern.scales", record: "scale", keys: ["name"] },
+  scale_value: { section: "govern.scales", record: "scale.values", keys: ["scale", "value"] },
+  style_raw_color_forbidden: {
+    section: "govern.styles",
+    record: "style.rawColors.forbid",
+    keys: [],
+  },
+  style_raw_dimension_forbidden: {
+    section: "govern.styles",
+    record: "style.rawDimensions.forbid",
+    keys: [],
+  },
+  style_property_scale: {
+    section: "govern.styles",
+    record: "style.rawSpacing.mustMatchScale",
+    keys: ["property"],
+  },
+  style_font_size_scale: {
+    section: "govern.styles",
+    record: "style.fontSize.mustMatchScale",
+    keys: [],
+  },
+  style_css_vars_must_be_defined: {
+    section: "govern.styles",
+    record: "style.cssVars.mustBeDefined",
+    keys: [],
+  },
+  jsx_unknown_props_forbidden: {
+    section: "govern.jsx",
+    record: "jsx.unknownProps.forbid",
+    keys: [],
+  },
+  jsx_inline_style_forbidden_raw: {
+    section: "govern.jsx",
+    record: "jsx.inlineStyle.forbidRaw",
+    keys: ["property"],
+  },
+  jsx_import_path_preferred: {
+    section: "govern.jsx",
+    record: "jsx.importPath.prefer",
+    keys: ["from", "to", "imported"],
+  },
+  jsx_component_preferred: {
+    section: "govern.jsx",
+    record: "jsx.component.prefer",
+    keys: ["from", "to"],
+  },
+  prop_value_avoided: {
+    section: "govern.components",
+    record: "prop.value.avoid",
+    keys: ["componentId", "prop", "value"],
+  },
+  prop_value_forbidden: {
+    section: "govern.components",
+    record: "prop.value.forbid",
+    keys: ["componentId", "prop", "value", "pathPattern"],
+  },
+  a11y_name_required: {
+    section: "govern.components",
+    record: "a11y.requireName",
+    keys: ["componentId"],
+  },
+  tailwind_palette_allow: {
+    section: "govern.tailwind",
+    record: "palette.allow",
+    keys: [],
+  },
+  tailwind_palette_deny: { section: "govern.tailwind", record: "palette.deny", keys: [] },
+  tailwind_unknown_class_enabled: {
+    section: "govern.tailwind",
+    record: "unknownClass",
+    keys: [],
+  },
+  governance_rule_config: { section: "govern.rules", record: "rule", keys: ["ruleId"] },
+};
+
+/** The authored settings a reader needs to see to tell two colliding records apart. */
+const COLLISION_DETAIL_KEYS = [
+  "severity",
+  "scale",
+  "prefer",
+  "enabled",
+  "appliesTo",
+  "except",
+  "properties",
+  "because",
+] as const;
+
+function renderFactFields(fact: Record<string, unknown>, keys: readonly string[]): string {
+  return keys
+    .filter((key) => fact[key] !== undefined)
+    .map((key) => `${key}=${Array.isArray(fact[key]) ? JSON.stringify(fact[key]) : fact[key]}`)
+    .join(" ");
+}
+
+/**
+ * Name a config record that the fact index dropped as a first-wins duplicate.
+ *
+ * This is the Layer-6 backstop, not the primary mechanism: merge-time displacement
+ * (`mergeGovernanceConfigs`) already makes the later record win for every shape it can
+ * key. What reaches here is a collision displacement could NOT resolve — two records
+ * that compile to one fact id from different channels (config vs bridge vs Cloud
+ * policy). The invariant it defends: a dropped policy fact is never silent.
+ *
+ * Returns `null` for non-config facts, so usage/token collisions stay on the internal
+ * debug channel.
+ */
+export function collidingRecordDiagnostic(conflict: FactConflict): InertConfigDiagnostic | null {
+  return collidingRecordDiagnostics([conflict])[0] ?? null;
+}
+
+/**
+ * Aggregate every observed collision into one diagnostic per colliding fact id.
+ *
+ * Three same-kind records on one fact id produce TWO conflicts (first-wins keeps the
+ * first and skips both others), and both render the same path. Emitting them separately
+ * meant the `(code, path)` dedupe every consumer runs kept only the last pair, so the
+ * intermediate record was dropped in silence — the same failure the per-kind path fixed
+ * one layer down. Aggregating names the count and lists every dropped setting, and one
+ * user edit still resolves the whole group.
+ */
+export function collidingRecordDiagnostics(
+  conflicts: readonly FactConflict[]
+): InertConfigDiagnostic[] {
+  const groups = new Map<
+    string,
+    { record: string; kept: string; dropped: string[]; keptFallback: string }
+  >();
+
+  for (const conflict of conflicts) {
+    const shape = CONFIG_RECORD_FACT_KINDS[conflict.kept.kind];
+    if (!shape || conflict.kept.kind !== conflict.skipped.kind) continue;
+
+    const keptFact = conflict.kept as unknown as Record<string, unknown>;
+    const skippedFact = conflict.skipped as unknown as Record<string, unknown>;
+    const identity = renderFactFields(keptFact, shape.keys);
+    // The record kind is part of the identity, not just the prose: two singleton-keyed
+    // kinds in one section would otherwise share a path and collapse under the (code,
+    // path) dedupe, dropping one collision silently.
+    const path = `${shape.section}[${identity ? `${shape.record} ${identity}` : shape.record}]`;
+    const group = groups.get(path) ?? {
+      record: shape.record,
+      kept: renderFactFields(keptFact, COLLISION_DETAIL_KEYS),
+      dropped: [],
+      keptFallback: "the first record",
+    };
+    const dropped = renderFactFields(skippedFact, COLLISION_DETAIL_KEYS);
+    group.dropped.push(dropped || `record ${group.dropped.length + 2}`);
+    groups.set(path, group);
+  }
+
+  return [...groups].map(([path, group]) => ({
+    code: "FUI9007" as const,
+    kind: "colliding-record" as const,
+    severity: "warn" as const,
+    path,
+    message:
+      `${path} has ${group.dropped.length + 1} \`${group.record}\` records that compile to the same policy fact — ` +
+      `enforcing ${group.kept || group.keptFallback} and dropping ${group.dropped.join("; ")}. ` +
+      "Author one record for this policy, or scope them apart, so the enforced setting is the one you can read.",
+  }));
+}
+
+/**
+ * The authored config record a policy fact was compiled from, or `null` when the fact
+ * did not come from a `govern.*` record (token facts, usage facts). One table, read by
+ * both the collision diagnostic and the override backstop below.
+ */
+export function configRecordShape(kind: string): { section: string; record: string } | null {
+  const shape = CONFIG_RECORD_FACT_KINDS[kind];
+  return shape ? { section: shape.section, record: shape.record } : null;
+}
+
+/**
+ * Name a `govern.rules` override that outranks the severity a policy record authored.
+ *
+ * The backstop for the path provenance cannot reach. Locally, presets are merged here,
+ * so a preset's broad rule entry is tagged and treated as a default — a user record's
+ * `severity: "error"` wins (report #2 B4). A Cloud-served policy arrives whole: no merge
+ * ran, nothing is tagged, and a broad `tokens/hardcoded-values` entry in it still
+ * displaces the severity a record next to it authored. That cannot be fixed at this
+ * boundary, so it is named instead. Silence is the defect; an unfixable case must at
+ * least speak.
+ */
+export function overriddenRecordSeverityDiagnostic(input: {
+  ruleId: string;
+  /** Config path of the override that won — `govern.rules[...]` or `govern.severity`. */
+  source: string;
+  section: string;
+  record: string;
+  authored: string;
+  enforced: string;
+}): InertConfigDiagnostic {
+  const path = `${input.section}[${input.record}]`;
+  return {
+    code: "FUI9008",
+    kind: "overridden-record-severity",
+    severity: "warn",
+    path,
+    message:
+      `${path} authored severity=${input.authored}, but ${input.source} enforces ` +
+      `severity=${input.enforced} on \`${input.ruleId}\`. The record's severity is not what ` +
+      "gates CI — drop the rule override, or author the record at the severity you want enforced.",
+  };
+}
+
 function collectStrippedKeys(
   authored: unknown,
   parsed: unknown,
@@ -369,6 +610,65 @@ export function detectUnconsumedConfigKeys(
   return stableConfigDiagnostics(diagnostics);
 }
 
+/** Every authored exclude in a policy, paired with the config path that declared it. */
+function authoredPolicyExcludes(
+  policy: GovernanceConfig | undefined
+): Array<{ path: string; scope: string; exclude: PolicyExclude }> {
+  const out: Array<{ path: string; scope: string; exclude: PolicyExclude }> = [];
+  const collect = (path: string, scope: string, raw: unknown) => {
+    for (const exclude of normalizePolicyExcludes(raw) ?? []) {
+      out.push({ path, scope, exclude });
+    }
+  };
+
+  (policy?.styles ?? []).forEach((record, index) => {
+    collect(`govern.styles[${index}].exclude`, record.kind, record.exclude);
+  });
+  (policy?.jsx ?? []).forEach((record, index) => {
+    collect(`govern.jsx[${index}].exclude`, record.kind, record.exclude);
+  });
+  for (const ruleId of Object.keys(policy?.rules ?? {}).sort()) {
+    const record = objectRecord(policy?.rules?.[ruleId]);
+    if (!record) continue;
+    collect(`govern.rules.${ruleId}.exclude`, ruleId, record.exclude);
+  }
+
+  return out;
+}
+
+/**
+ * Diagnose excludes that scope nothing: the key is consumed and the glob is valid, but
+ * it matched no scanned file, so it silently exempts nothing while reading as active
+ * policy. That is the same "declared ≠ armed" failure this module exists to name — a
+ * stale path after a refactor is the common cause.
+ *
+ * `scannedFiles` are repo-relative paths supplied by the caller; core never reads the
+ * filesystem. An empty scan (nothing to compare against) yields no diagnostics rather
+ * than flagging every exclude.
+ */
+export function detectUnmatchedPolicyExcludes(
+  policy: GovernanceConfig | undefined,
+  scannedFiles: readonly string[]
+): InertConfigDiagnostic[] {
+  if (scannedFiles.length === 0) return [];
+  const diagnostics: InertConfigDiagnostic[] = [];
+
+  for (const { path, scope, exclude } of authoredPolicyExcludes(policy)) {
+    if (scannedFiles.some((file) => policyExcludeMatchesPath(exclude, file))) continue;
+    diagnostics.push({
+      code: "FUI9006",
+      kind: "unmatched-exclude",
+      severity: "warn",
+      path,
+      message:
+        `${path} pattern "${exclude.glob}" matched no scanned file, so ${scope} is not ` +
+        "actually scoped by it. Correct the glob to a path this scan covers, or remove it.",
+    });
+  }
+
+  return stableConfigDiagnostics(diagnostics);
+}
+
 interface ScaleBinding {
   label: string;
   mechanism: string;