@usefragments/core 1.5.1 → 1.6.0

package/src/facts/types.ts

@@ -14,6 +14,7 @@
 
 import type { GovernanceSeverity } from "../governance.js";
 import type { IdentityConfidence, IdentityState } from "../identity/classify.js";
+import type { PolicyExclude } from "../policy-exclude.js";
 
 // ---------------------------------------------------------------------------
 // Branded IDs
@@ -121,34 +122,42 @@ export interface ScaleValueFact extends BaseFact {
   value: number;
 }
 
-export interface StyleRawColorForbiddenFact extends BaseFact {
+/**
+ * Path excludes carried by a compiled policy fact. Present only when the authoring
+ * record declared them, so fact shapes are byte-identical for configs without
+ * excludes. Never part of the fact's `factId` inputs: scoping a policy off a path
+ * must not move fact ids or the finding fingerprints Cloud and baselines dedupe on.
+ */
+type PolicyFactExcludes = { exclude?: PolicyExclude[] };
+
+export interface StyleRawColorForbiddenFact extends BaseFact, PolicyFactExcludes {
   kind: "style_raw_color_forbidden";
   except: string[];
   prefer: "token" | "css-variable";
   severity: GovernanceSeverity;
 }
 
-export interface StyleRawDimensionForbiddenFact extends BaseFact {
+export interface StyleRawDimensionForbiddenFact extends BaseFact, PolicyFactExcludes {
   kind: "style_raw_dimension_forbidden";
   appliesTo: string[];
   prefer: "token" | "css-variable";
   severity: GovernanceSeverity;
 }
 
-export interface StylePropertyScaleFact extends BaseFact {
+export interface StylePropertyScaleFact extends BaseFact, PolicyFactExcludes {
   kind: "style_property_scale";
   property: string;
   scale: string;
   severity: GovernanceSeverity;
 }
 
-export interface StyleFontSizeScaleFact extends BaseFact {
+export interface StyleFontSizeScaleFact extends BaseFact, PolicyFactExcludes {
   kind: "style_font_size_scale";
   scale: string;
   severity: GovernanceSeverity;
 }
 
-export interface StyleCssVarsMustBeDefinedFact extends BaseFact {
+export interface StyleCssVarsMustBeDefinedFact extends BaseFact, PolicyFactExcludes {
   kind: "style_css_vars_must_be_defined";
   severity: GovernanceSeverity;
 }
@@ -166,18 +175,18 @@ export interface ContractTokenFact extends BaseFact {
   name: string;
 }
 
-export interface JsxUnknownPropsForbiddenFact extends BaseFact {
+export interface JsxUnknownPropsForbiddenFact extends BaseFact, PolicyFactExcludes {
   kind: "jsx_unknown_props_forbidden";
   severity: GovernanceSeverity;
 }
 
-export interface JsxInlineStyleForbiddenRawFact extends BaseFact {
+export interface JsxInlineStyleForbiddenRawFact extends BaseFact, PolicyFactExcludes {
   kind: "jsx_inline_style_forbidden_raw";
   property: string;
   severity: GovernanceSeverity;
 }
 
-export interface JsxImportPathPreferredFact extends BaseFact {
+export interface JsxImportPathPreferredFact extends BaseFact, PolicyFactExcludes {
   kind: "jsx_import_path_preferred";
   from: string;
   to: string;
@@ -194,7 +203,7 @@ export interface JsxImportPathPreferredFact extends BaseFact {
   };
 }
 
-export interface JsxComponentPreferredFact extends BaseFact {
+export interface JsxComponentPreferredFact extends BaseFact, PolicyFactExcludes {
   kind: "jsx_component_preferred";
   from: ComponentId;
   to: ComponentId;
@@ -343,6 +352,9 @@ export interface UsageInlineStyleFact extends BaseFact {
    */
   valueKind: "static" | "number" | "css-variable" | "dynamic-raw";
   value: string;
+  /** Set when `value` was resolved through a hop rather than authored inline.
+   *  Additive — the fact's identity key is unchanged. */
+  valueFrom?: StyleValueProvenance;
 }
 
 export interface UsageTextChildFact extends BaseFact {
@@ -511,6 +523,27 @@ export interface TailwindTokenResolvedFact extends BaseFact {
  * selector chain. Identity is `{ file, selector, declarationPath, property }`
  * so the ID stays stable when other lines move.
  */
+/**
+ * How a style value reached the fact when the authored text at the use site was
+ * not the value itself. Present only for `const-binding` today: the extractor
+ * followed exactly one hop to a same-file, immutable, statically-initialized
+ * `const` (`const c = '#FFC107'; sx={{ color: c }}`).
+ *
+ * Two consequences for rules, both load-bearing:
+ * - The declaration line is the evidence a reader needs — the use site only
+ *   shows an identifier.
+ * - **No deterministic fix may be attached.** The authored text at the finding's
+ *   location is the identifier, so any value replacement would be an edit the
+ *   user never wrote.
+ */
+export interface StyleValueProvenance {
+  kind: "const-binding";
+  /** Identifier the use site referenced. */
+  name: string;
+  /** Where the binding was declared. */
+  location: FactLocation;
+}
+
 export interface StyleDeclarationFact extends BaseFact {
   kind: "style_declaration";
   file: string;
@@ -527,6 +560,9 @@ export interface StyleDeclarationFact extends BaseFact {
    * flagging ad hoc custom properties in product code.
    */
   declaredTokenSource?: boolean;
+  /** Set when `value` was resolved through a hop rather than authored inline.
+   *  Additive — the fact's identity key is unchanged. */
+  valueFrom?: StyleValueProvenance;
 }
 
 export type UnsupportedStyleReason =

package/src/governance-integrity.test.ts

@@ -1,13 +1,26 @@
 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,
   hasEffectiveComponentVocabulary,
   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";
 
 function evaluate(
   overrides: Partial<GovernanceIntegrityInput>
@@ -66,6 +79,245 @@ describe("hasEffectiveComponentVocabulary", () => {
   });
 });
 
+describe("inert config diagnostics", () => {
+  it("reports stripped, passthrough, unknown-rule, and rule-field keys in stable order", () => {
+    const authored = {
+      styles: { spacing: true },
+      screenshots: { threshold: 0.1, renderer: "chromium" },
+      tokens: { include: ["tokens.css"], mystery: true },
+      govern: {
+        scales: {
+          space: { kind: "scale", unit: "px", values: [0, 4, 8], source: "legacy" },
+        },
+        rules: {
+          "styles/no-raw-color": { enabled: true, exclude: ["vendor/**"], scope: "app" },
+          "styles/not-a-real-rule": { enabled: true },
+        },
+      },
+    };
+    const parsed = fragmentsConfigSchema.parse(authored);
+
+    expect(detectUnconsumedConfigKeys(authored, parsed)).toMatchObject([
+      { 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" },
+      { code: "FUI9004", path: "styles" },
+      { code: "FUI9004", path: "tokens.mystery" },
+    ]);
+  });
+
+  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: {
+        spacing: { kind: "scale", unit: "px", values: [0, 4, 8] },
+      },
+    };
+    const effective: GovernanceConfig = {
+      ...declared,
+      scales: {
+        ...declared.scales,
+        space: { kind: "scale", unit: "px", values: [0, 4, 8] },
+      },
+      styles: [
+        {
+          kind: "style.rawSpacing.mustMatchScale",
+          scale: "space",
+          appliesTo: ["margin", "padding"],
+          severity: "warn",
+        },
+      ],
+    };
+
+    expect(detectOrphanGovernanceScales(declared, effective)).toEqual([
+      expect.objectContaining({
+        code: "FUI9005",
+        path: "govern.scales.spacing",
+        message: expect.stringContaining('bound to the scale named "space"'),
+      }),
+    ]);
+  });
+
+  it("does not report a scale referenced by an effective property policy", () => {
+    const policy: GovernanceConfig = {
+      scales: {
+        space: { kind: "scale", unit: "px", values: [0, 4, 8] },
+      },
+      styles: [
+        {
+          kind: "style.rawSpacing.mustMatchScale",
+          scale: "space",
+          appliesTo: ["margin"],
+          severity: "warn",
+        },
+      ],
+    };
+
+    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", () => {
   it("1. no policy at all → inert, not fatal, not blocking-capable", () => {
     const verdict = evaluate({ policy: undefined, policySource: "none", declared: false });
@@ -207,4 +459,28 @@ describe("evaluateGovernanceIntegrity", () => {
     // degraded is enforceable, so not CI-fatal
     expect(verdict.fatalForCi).toBe(false);
   });
+
+  it("includes inert config diagnostics in the doctor roster without changing integrity status", () => {
+    const policy: GovernanceConfig = {
+      rules: { "styles/no-raw-color": { enabled: true, severity: "warn" } },
+    };
+    const baseline = evaluate({ policy, policySource: "config", declared: true });
+    const withDiagnostic = evaluate({
+      policy,
+      policySource: "config",
+      declared: true,
+      configDiagnostics: Array.from({ length: 2 }, () => ({
+        code: "FUI9005",
+        kind: "orphan-scale",
+        severity: "warn",
+        path: "govern.scales.spacing",
+        message: "orphan",
+      })),
+    });
+
+    expect(withDiagnostic.status).toBe(baseline.status);
+    expect(withDiagnostic.fatalForCi).toBe(baseline.fatalForCi);
+    expect(withDiagnostic.roster).toMatchObject({ active: 1, inert: 1 });
+    expect(withDiagnostic.configDiagnostics).toHaveLength(1);
+  });
 });