@usefragments/core 1.5.2 → 1.7.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 {
@@ -352,6 +364,20 @@ export interface UsageTextChildFact extends BaseFact {
   index: number;
 }
 
+/**
+ * Framework-neutral summary of the rendered child content for one usage node.
+ *
+ * An adapter that supports semantic child analysis preserves its existing prop
+ * facts and additionally emits exactly one summary per usage node, so rules do
+ * not have to interpret React's `children`, Vue slots, or Svelte snippets
+ * themselves. Adapters may add support independently.
+ */
+export interface UsageChildContentFact extends BaseFact {
+  kind: "usage_child_content";
+  nodeId: FactId;
+  content: "static-text" | "runtime" | "structural" | "empty";
+}
+
 // ---------------------------------------------------------------------------
 // Tailwind className facts.
 //
@@ -511,6 +537,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 +574,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 =
@@ -686,6 +736,7 @@ export type UsageFact =
   | UsagePropResolvedFact
   | UsageInlineStyleFact
   | UsageTextChildFact
+  | UsageChildContentFact
   | StyleDeclarationFact
   | StyleUnsupportedFact
   | ClassNameLiteralFact

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", () => {
@@ -172,7 +343,10 @@ describe("evaluateGovernanceIntegrity", () => {
       canonicalSources: [{ kind: "directory", path: "ui" }],
     };
     const verdict = evaluate({ policy, policySource: "config", declared: true });
-    expect(verdict.families.find((f) => f.id === "components")?.armed).toBe(true);
+    expect(verdict.families.find((f) => f.id === "components")).toMatchObject({
+      armed: true,
+      rules: ["components/prefer-library", "components/shadow-component"],
+    });
     expect(verdict.status).toBe("healthy");
     expect(verdict.blockingCapable).toBe(false);
     expect(verdict.armed).toContain("components");
@@ -201,6 +375,83 @@ describe("evaluateGovernanceIntegrity", () => {
     expect(verdict.blockingCapable).toBe(true);
   });
 
+  it("4c. prefer-library disabled + canonical source leaves shadow governance armed", () => {
+    const policy: GovernanceConfig = {
+      severity: "error",
+      canonicalSources: [{ kind: "directory", path: "ui" }],
+      rules: { "components/prefer-library": false },
+    };
+    const verdict = evaluate({ policy, policySource: "config", declared: true });
+    expect(verdict.families.find((f) => f.id === "components")).toMatchObject({
+      armed: true,
+      rules: ["components/shadow-component"],
+    });
+    expect(verdict.families.find((f) => f.id === "blocking-deny")?.rules).toEqual([
+      "components/shadow-component",
+    ]);
+    expect(verdict.status).toBe("healthy");
+    expect(verdict.blockingCapable).toBe(true);
+  });
+
+  it("4d. shadow-component disabled + canonical source leaves prefer-library armed", () => {
+    const policy: GovernanceConfig = {
+      severity: "error",
+      canonicalSources: [{ kind: "directory", path: "ui" }],
+      rules: { "components/shadow-component": false },
+    };
+    const verdict = evaluate({ policy, policySource: "config", declared: true });
+    expect(verdict.families.find((f) => f.id === "components")).toMatchObject({
+      armed: true,
+      rules: ["components/prefer-library"],
+    });
+    expect(verdict.families.find((f) => f.id === "blocking-deny")?.rules).toEqual([
+      "components/prefer-library",
+    ]);
+  });
+
+  it("4e. explicitly disabling both canonical-component rules leaves the policy inert", () => {
+    const policy: GovernanceConfig = {
+      severity: "error",
+      canonicalSources: [{ kind: "directory", path: "ui" }],
+      rules: {
+        "components/prefer-library": false,
+        "components/shadow-component": false,
+      },
+    };
+    const verdict = evaluate({ policy, policySource: "config", declared: true });
+    expect(verdict.families.find((f) => f.id === "components")).toMatchObject({
+      armed: false,
+      rules: [],
+      reason: "canonical-component rules not enabled",
+    });
+    expect(verdict.status).toBe("inert");
+    expect(verdict.blockingCapable).toBe(false);
+  });
+
+  it("4f. vocabulary on a disabled sibling rule cannot arm shadow governance", () => {
+    const policy: GovernanceConfig = {
+      rules: {
+        "components/prefer-library": {
+          enabled: false,
+          options: {
+            canonicalMappings: [
+              { name: "Button", htmlEquivalent: "button", importPath: "@acme/ui" },
+            ],
+          },
+        },
+        "components/shadow-component": { enabled: true, severity: "error" },
+      },
+    };
+    const verdict = evaluate({ policy, policySource: "config", declared: true });
+    expect(verdict.families.find((f) => f.id === "components")).toMatchObject({
+      armed: false,
+      rules: ["components/shadow-component"],
+      reason: "component governance enabled but no effective canonical source",
+    });
+    expect(verdict.status).toBe("inert");
+    expect(verdict.blockingCapable).toBe(false);
+  });
+
   it("5. npm source with NO include → components NOT armed → inert (blocker-#2 lock)", () => {
     const policy: GovernanceConfig = {
       canonicalSources: [{ kind: "npm", specifier: "@acme/ui" }],
@@ -274,6 +525,23 @@ describe("evaluateGovernanceIntegrity", () => {
     expect(tokens?.reason).toBe("no token vocabulary");
   });
 
+  it("7c. error-level token drift with a vocabulary is blocking-capable", () => {
+    const policy: GovernanceConfig = {
+      styles: [{ kind: "style.cssVars.mustBeDefined", severity: "error" }],
+    };
+    const verdict = evaluate({
+      policy,
+      policySource: "config",
+      declared: true,
+      cssVarsActive: true,
+      tokenVocabularySize: 5,
+    });
+    expect(verdict.families.find((family) => family.id === "blocking-deny")?.rules).toContain(
+      "tokens/css-vars-must-be-defined"
+    );
+    expect(verdict.blockingCapable).toBe(true);
+  });
+
   it("8. hygiene-only policy (raw-style rule enabled, no contract) → degraded", () => {
     const policy: GovernanceConfig = {
       rules: { "styles/no-raw-color": { enabled: true, severity: "warn" } },