@usefragments/core 1.5.1 → 1.6.0

package/src/facts/builders.ts

@@ -9,6 +9,7 @@
  */
 
 import type { GovernanceSeverity } from "../governance.js";
+import type { PolicyExclude } from "../policy-exclude.js";
 import { asComponentId, factId } from "./ids.js";
 import type {
   A11yNameRequiredFact,
@@ -42,6 +43,7 @@ import type {
   StyleFontSizeScaleFact,
   StylePropertyScaleFact,
   StyleRawColorForbiddenFact,
+  StyleValueProvenance,
   StyleRawDimensionForbiddenFact,
   StyleUnsupportedFact,
   UnsupportedStyleReason,
@@ -64,6 +66,17 @@ import type {
   FactId,
 } from "./types.js";
 
+/**
+ * Attach a policy record's path excludes without perturbing its fact identity — the
+ * field is omitted entirely when nothing was authored, so a config with no excludes
+ * produces byte-identical facts (and therefore identical finding fingerprints).
+ */
+function policyExcludeField(exclude: readonly PolicyExclude[] | undefined): {
+  exclude?: PolicyExclude[];
+} {
+  return exclude?.length ? { exclude: exclude.map((entry) => ({ ...entry })) } : {};
+}
+
 // ---------------------------------------------------------------------------
 // Component facts
 // ---------------------------------------------------------------------------
@@ -372,6 +385,7 @@ export function makeStyleRawColorForbiddenFact(input: {
   except: string[];
   prefer: "token" | "css-variable";
   severity: GovernanceSeverity;
+  exclude?: readonly PolicyExclude[];
 }): StyleRawColorForbiddenFact {
   return {
     id: factId("style_raw_color_forbidden", {}),
@@ -379,6 +393,7 @@ export function makeStyleRawColorForbiddenFact(input: {
     except: [...input.except],
     prefer: input.prefer,
     severity: input.severity,
+    ...policyExcludeField(input.exclude),
   };
 }
 
@@ -386,6 +401,7 @@ export function makeStyleRawDimensionForbiddenFact(input: {
   appliesTo: string[];
   prefer: "token" | "css-variable";
   severity: GovernanceSeverity;
+  exclude?: readonly PolicyExclude[];
 }): StyleRawDimensionForbiddenFact {
   return {
     id: factId("style_raw_dimension_forbidden", {}),
@@ -393,6 +409,7 @@ export function makeStyleRawDimensionForbiddenFact(input: {
     appliesTo: [...input.appliesTo],
     prefer: input.prefer,
     severity: input.severity,
+    ...policyExcludeField(input.exclude),
   };
 }
 
@@ -400,6 +417,7 @@ export function makeStylePropertyScaleFact(input: {
   property: string;
   scale: string;
   severity: GovernanceSeverity;
+  exclude?: readonly PolicyExclude[];
 }): StylePropertyScaleFact {
   return {
     id: factId("style_property_scale", { property: input.property }),
@@ -407,28 +425,33 @@ export function makeStylePropertyScaleFact(input: {
     property: input.property,
     scale: input.scale,
     severity: input.severity,
+    ...policyExcludeField(input.exclude),
   };
 }
 
 export function makeStyleFontSizeScaleFact(input: {
   scale: string;
   severity: GovernanceSeverity;
+  exclude?: readonly PolicyExclude[];
 }): StyleFontSizeScaleFact {
   return {
     id: factId("style_font_size_scale", {}),
     kind: "style_font_size_scale",
     scale: input.scale,
     severity: input.severity,
+    ...policyExcludeField(input.exclude),
   };
 }
 
 export function makeStyleCssVarsMustBeDefinedFact(input: {
   severity: GovernanceSeverity;
+  exclude?: readonly PolicyExclude[];
 }): StyleCssVarsMustBeDefinedFact {
   return {
     id: factId("style_css_vars_must_be_defined", {}),
     kind: "style_css_vars_must_be_defined",
     severity: input.severity,
+    ...policyExcludeField(input.exclude),
   };
 }
 
@@ -443,23 +466,27 @@ export function makeContractTokenFact(input: { name: string }): ContractTokenFac
 
 export function makeJsxUnknownPropsForbiddenFact(input: {
   severity: GovernanceSeverity;
+  exclude?: readonly PolicyExclude[];
 }): JsxUnknownPropsForbiddenFact {
   return {
     id: factId("jsx_unknown_props_forbidden", {}),
     kind: "jsx_unknown_props_forbidden",
     severity: input.severity,
+    ...policyExcludeField(input.exclude),
   };
 }
 
 export function makeJsxInlineStyleForbiddenRawFact(input: {
   property: string;
   severity: GovernanceSeverity;
+  exclude?: readonly PolicyExclude[];
 }): JsxInlineStyleForbiddenRawFact {
   return {
     id: factId("jsx_inline_style_forbidden_raw", { property: input.property }),
     kind: "jsx_inline_style_forbidden_raw",
     property: input.property,
     severity: input.severity,
+    ...policyExcludeField(input.exclude),
   };
 }
 
@@ -470,6 +497,7 @@ export function makeJsxImportPathPreferredFact(input: {
   because?: string;
   severity: GovernanceSeverity;
   bridge?: JsxImportPathPreferredFact["bridge"];
+  exclude?: readonly PolicyExclude[];
 }): JsxImportPathPreferredFact {
   return {
     id: factId("jsx_import_path_preferred", {
@@ -492,6 +520,7 @@ export function makeJsxImportPathPreferredFact(input: {
           },
         }
       : {}),
+    ...policyExcludeField(input.exclude),
   };
 }
 
@@ -500,6 +529,7 @@ export function makeJsxComponentPreferredFact(input: {
   to: ComponentId;
   because?: string;
   severity: GovernanceSeverity;
+  exclude?: readonly PolicyExclude[];
 }): JsxComponentPreferredFact {
   return {
     id: factId("jsx_component_preferred", {
@@ -511,6 +541,7 @@ export function makeJsxComponentPreferredFact(input: {
     to: input.to,
     because: input.because,
     severity: input.severity,
+    ...policyExcludeField(input.exclude),
   };
 }
 
@@ -690,6 +721,7 @@ export function makeUsageInlineStyleFact(input: {
   property: string;
   valueKind: "static" | "number" | "css-variable" | "dynamic-raw";
   value: string;
+  valueFrom?: StyleValueProvenance;
 }): UsageInlineStyleFact {
   return {
     id: factId("usage_inline_style", {
@@ -701,6 +733,7 @@ export function makeUsageInlineStyleFact(input: {
     property: input.property,
     valueKind: input.valueKind,
     value: input.value,
+    ...(input.valueFrom ? { valueFrom: input.valueFrom } : {}),
   };
 }
 
@@ -856,6 +889,7 @@ export function makeStyleDeclarationFact(input: {
   value: string;
   location: FactLocation;
   declaredTokenSource?: boolean;
+  valueFrom?: StyleValueProvenance;
 }): StyleDeclarationFact {
   return {
     id: factId("style_declaration", {
@@ -872,6 +906,7 @@ export function makeStyleDeclarationFact(input: {
     value: input.value,
     location: input.location,
     ...(input.declaredTokenSource ? { declaredTokenSource: true } : {}),
+    ...(input.valueFrom ? { valueFrom: input.valueFrom } : {}),
   };
 }
 

package/src/facts/compile.ts

@@ -19,6 +19,9 @@ import type {
   ResolvedGovernedFragmentDefinition,
 } from "../governance.js";
 import { resolveComponentGovernance } from "../governance.js";
+import { RULE_FAMILY_MEMBERS } from "../rules/families.js";
+import { normalizePolicyExcludes, type PolicyExclude } from "../policy-exclude.js";
+import { ownedImportMatchesRoot, ownedImportsEqual } from "../package-identity-match.js";
 import type { CompiledFragment, PropDefinition } from "../compiled-types/index.js";
 import { asComponentId } from "./ids.js";
 import {
@@ -50,6 +53,52 @@ import type { ComponentId, Fact, PolicyFact } from "./types.js";
 // Global governance → facts
 // ---------------------------------------------------------------------------
 
+/**
+ * A global record's authored path excludes, normalized for the fact it compiles into.
+ * Omitted when absent so no-exclude configs keep byte-identical policy facts.
+ */
+function recordExclude(record: { exclude?: unknown }): { exclude?: PolicyExclude[] } {
+  const exclude = normalizePolicyExcludes(record.exclude);
+  return exclude ? { exclude } : {};
+}
+
+/**
+ * Reconcile excludes across records that compile to the SAME policy fact.
+ *
+ * A resolved policy concatenates preset records with the user's, and the singleton
+ * style/jsx kinds are content-addressed on their kind alone — so a user record and the
+ * preset record it refines share one fact id, and only one survives indexing. Without
+ * this pass the survivor is usually the preset's, and the user's authored exemption
+ * disappears with no diagnostic: the facts-seam silence this train exists to kill.
+ *
+ * Scope is deliberately narrow. Excludes are unioned onto every instance of the id, so
+ * whichever copy the index keeps carries the whole set. Nothing else about the records
+ * is merged — general merge displacement for the other fields is a separate concern
+ * (`10-config-truth`), and widening it here would silently change severity/prefer
+ * resolution for existing repos.
+ */
+function unionExcludesBySharedFactId(facts: PolicyFact[]): PolicyFact[] {
+  const byId = new Map<string, PolicyExclude[]>();
+  for (const fact of facts) {
+    const exclude = (fact as { exclude?: PolicyExclude[] }).exclude;
+    if (!exclude?.length) continue;
+    const merged = byId.get(fact.id) ?? [];
+    for (const entry of exclude) {
+      if (!merged.some((seen) => seen.glob === entry.glob && seen.reason === entry.reason)) {
+        merged.push(entry);
+      }
+    }
+    byId.set(fact.id, merged);
+  }
+  if (byId.size === 0) return facts;
+
+  return facts.map((fact) => {
+    const merged = byId.get(fact.id);
+    if (!merged) return fact;
+    return { ...fact, exclude: merged.map((entry) => ({ ...entry })) } as PolicyFact;
+  });
+}
+
 export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefined): PolicyFact[] {
   if (!govern) return [];
   const out: PolicyFact[] = [];
@@ -79,6 +128,7 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
               except: style.except,
               prefer: style.prefer,
               severity: style.severity,
+              ...recordExclude(style),
             })
           );
           break;
@@ -88,6 +138,7 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
               appliesTo: style.appliesTo,
               prefer: style.prefer,
               severity: style.severity,
+              ...recordExclude(style),
             })
           );
           break;
@@ -98,15 +149,27 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
                 property,
                 scale: style.scale,
                 severity: style.severity,
+                ...recordExclude(style),
               })
             );
           }
           break;
         case "style.fontSize.mustMatchScale":
-          out.push(makeStyleFontSizeScaleFact({ scale: style.scale, severity: style.severity }));
+          out.push(
+            makeStyleFontSizeScaleFact({
+              scale: style.scale,
+              severity: style.severity,
+              ...recordExclude(style),
+            })
+          );
           break;
         case "style.cssVars.mustBeDefined":
-          out.push(makeStyleCssVarsMustBeDefinedFact({ severity: style.severity }));
+          out.push(
+            makeStyleCssVarsMustBeDefinedFact({
+              severity: style.severity,
+              ...recordExclude(style),
+            })
+          );
           break;
       }
     }
@@ -116,7 +179,12 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
     for (const jsx of govern.jsx) {
       switch (jsx.kind) {
         case "jsx.unknownProps.forbid":
-          out.push(makeJsxUnknownPropsForbiddenFact({ severity: jsx.severity }));
+          out.push(
+            makeJsxUnknownPropsForbiddenFact({
+              severity: jsx.severity,
+              ...recordExclude(jsx),
+            })
+          );
           break;
         case "jsx.inlineStyle.forbidRaw":
           for (const property of jsx.properties) {
@@ -124,6 +192,7 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
               makeJsxInlineStyleForbiddenRawFact({
                 property,
                 severity: jsx.severity,
+                ...recordExclude(jsx),
               })
             );
           }
@@ -136,6 +205,7 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
               imported: jsx.imported,
               because: jsx.because,
               severity: jsx.severity,
+              ...recordExclude(jsx),
             })
           );
           break;
@@ -146,6 +216,7 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
               to: asComponentId(jsx.to) as ComponentId,
               because: jsx.because,
               severity: jsx.severity,
+              ...recordExclude(jsx),
             })
           );
           break;
@@ -172,6 +243,67 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
     );
   }
 
+  compileTailwindAndRuleConfigFacts(govern, out);
+  return unionExcludesBySharedFactId(out);
+}
+
+export interface SupersededImportPathPreference {
+  from: string;
+  imported?: string;
+  to: string;
+  packageName: string;
+  underlyingExportName: string;
+  localExportName: string;
+}
+
+/**
+ * Name each non-bridge `jsx.importPath.prefer` record whose domain a confirmed
+ * bridge covers. The rule suppresses the duplicate finding at match time
+ * (report #2 B6); this projection is the compile-side voice of that
+ * supersession, so the record is never silenced without a word — the exact
+ * silence class the config-truth layer exists to kill.
+ */
+export function projectSupersededImportPathPreferences(
+  govern: GovernanceConfig | undefined
+): SupersededImportPathPreference[] {
+  const bridges = govern?.canonicalBridges ?? [];
+  if (bridges.length === 0 || !govern?.jsx) return [];
+  const out: SupersededImportPathPreference[] = [];
+  for (const record of govern.jsx) {
+    if (record.kind !== "jsx.importPath.prefer") continue;
+    const bridge = bridges.find((candidate) => importPathRecordOverlapsBridge(record, candidate));
+    if (!bridge) continue;
+    out.push({
+      from: record.from,
+      ...(record.imported !== undefined ? { imported: record.imported } : {}),
+      to: record.to,
+      packageName: bridge.underlying.packageName,
+      underlyingExportName: bridge.underlying.exportName,
+      localExportName: bridge.local.exportName,
+    });
+  }
+  return out;
+}
+
+function importPathRecordOverlapsBridge(
+  record: { from: string; imported?: string },
+  bridge: NonNullable<GovernanceConfig["canonicalBridges"]>[number]
+): boolean {
+  if (!ownedImportMatchesRoot(record.from, bridge.underlying.packageName)) return false;
+  if (ownedImportsEqual(record.from, bridge.underlying.packageName)) {
+    return record.imported === undefined || record.imported === bridge.underlying.exportName;
+  }
+  const subpath = record.from.slice(bridge.underlying.packageName.length + 1);
+  const leaf = subpath.split("/").at(-1);
+  return (
+    leaf === bridge.underlying.exportName &&
+    (record.imported === undefined ||
+      record.imported === "default" ||
+      record.imported === bridge.underlying.exportName)
+  );
+}
+
+function compileTailwindAndRuleConfigFacts(govern: GovernanceConfig, out: PolicyFact[]): void {
   const tailwindPalette = govern.tailwind?.palette;
   const forbiddenPaletteSeverity = ruleSeverity(
     govern.rules?.["tailwind/forbidden-palette"],
@@ -203,26 +335,8 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
   }
 
   out.push(...compileRuleConfigFacts(govern));
-
-  return out;
 }
 
-const RULE_FAMILY_MEMBERS: Record<string, readonly string[]> = {
-  "tokens/hardcoded-values": [
-    "styles/no-raw-color",
-    "styles/no-raw-spacing",
-    "tokens/require-dual-fallback",
-    "theme/no-theme-coupled-literal",
-  ],
-  "components/usage": [
-    "components/forbidden-prop-value",
-    "components/preferred-component",
-    "components/unknown-prop",
-    "props/invalid-value",
-  ],
-  "a11y/wcag": ["a11y/required-accessible-name"],
-};
-
 function compileRuleConfigFacts(govern: GovernanceConfig): PolicyFact[] {
   const rules = govern.rules;
   if (!rules && !govern.canonicalSources?.length) return [];

package/src/facts/fact-index.ts

@@ -45,6 +45,23 @@ export interface FactEvidence {
   fact: Fact;
 }
 
+/**
+ * The two facts involved in a first-wins drop: `kept` is already indexed, `skipped`
+ * carries different logical content and is discarded. Handed to `onConflict` alongside
+ * the rendered message so callers can classify the drop (a colliding *config record* is
+ * a named user-facing diagnostic; anything else stays an internal debug line) instead of
+ * re-parsing prose.
+ */
+export interface FactConflict {
+  kept: Fact;
+  skipped: Fact;
+}
+
+export interface FactIndexOptions {
+  /** Optional internal diagnostic route. Product output is quiet by default. */
+  onConflict?: (message: string, conflict: FactConflict) => void;
+}
+
 interface FactWithComponent {
   componentId: ComponentId;
 }
@@ -115,6 +132,8 @@ export class FactIndex {
   private readonly idsByComponent = new Map<ComponentId, Set<FactId>>();
   private readonly tokenBySymbol = new Map<string, TokenDefinitionFact>();
 
+  constructor(private readonly options: FactIndexOptions = {}) {}
+
   add(fact: Fact): void {
     if (fact.kind === "token_definition") {
       this.indexTokenSymbols(fact);
@@ -125,8 +144,9 @@ export class FactIndex {
         canonicalJson(logicalFactForComparison(existing)) !==
         canonicalJson(logicalFactForComparison(fact))
       ) {
-        console.warn(
-          `FactIndex: conflicting facts for id ${fact.id} — keeping ${describeFactForConflict(existing)}, skipping ${describeFactForConflict(fact)}`
+        this.options.onConflict?.(
+          `FactIndex: conflicting facts for id ${fact.id} — keeping ${describeFactForConflict(existing)}, skipping ${describeFactForConflict(fact)}`,
+          { kept: existing, skipped: fact }
         );
       }
       return;

package/src/facts/facts.test.ts

@@ -446,9 +446,9 @@ describe("FactIndex — query layer", () => {
     expect(() => ix.evidence([componentFact.id, ghost])).toThrow(/missing/i);
   });
 
-  it("warns and keeps the first fact when a conflicting fact reuses an id", () => {
-    const ix = new FactIndex();
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  it("reports through an opt-in callback and keeps the first fact when an id conflicts", () => {
+    const onConflict = vi.fn();
+    const ix = new FactIndex({ onConflict });
     const id = factId("prop_value_forbidden", {
       componentId: buttonId,
       prop: "variant",
@@ -469,14 +469,16 @@ describe("FactIndex — query layer", () => {
     };
     ix.add(a);
     expect(() => ix.add(b)).not.toThrow();
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining("conflicting facts"));
+    expect(onConflict).toHaveBeenCalledWith(expect.stringContaining("conflicting facts"), {
+      kept: a,
+      skipped: b,
+    });
     expect(ix.get(id)).toEqual(a);
-    warn.mockRestore();
   });
 
   it("does not treat token-definition provenance as a logical conflict", () => {
-    const ix = new FactIndex();
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const onConflict = vi.fn();
+    const ix = new FactIndex({ onConflict });
     const first = makeTokenDefinitionFact({
       name: "--fui-color-accent",
       value: "#2563eb",
@@ -491,14 +493,13 @@ describe("FactIndex — query layer", () => {
     ix.add(first);
     ix.add(second);
 
-    expect(warn).not.toHaveBeenCalled();
+    expect(onConflict).not.toHaveBeenCalled();
     expect(ix.get(first.id)).toEqual(first);
-    warn.mockRestore();
   });
 
-  it("includes token-definition provenance in logical conflict warnings", () => {
-    const ix = new FactIndex();
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  it("includes token-definition provenance in logical conflict reports", () => {
+    const onConflict = vi.fn();
+    const ix = new FactIndex({ onConflict });
     const first = makeTokenDefinitionFact({
       name: "--fui-color-accent",
       value: "#2563eb",
@@ -513,13 +514,13 @@ describe("FactIndex — query layer", () => {
     ix.add(first);
     ix.add(second);
 
-    expect(warn).toHaveBeenCalledWith(
+    expect(onConflict).toHaveBeenCalledWith(
       expect.stringMatching(
         /conflicting facts.*keeping kind=token_definition location=tokens\/base\.css:2:1, skipping kind=token_definition location=tokens\/theme\.css:4:1/
-      )
+      ),
+      { kept: first, skipped: second }
     );
     expect(ix.get(first.id)).toEqual(first);
-    warn.mockRestore();
   });
 
   it("treats old and current owned component spellings as the same indexed facts", () => {
@@ -527,17 +528,16 @@ describe("FactIndex — query layer", () => {
     const currentId = asComponentId("@usefragments/ui#Button");
     const legacy = compileComponentFacts(legacyId, buildSampleFragment());
     const current = compileComponentFacts(currentId, buildSampleFragment());
-    const ix = new FactIndex();
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const onConflict = vi.fn();
+    const ix = new FactIndex({ onConflict });
 
     ix.addMany(legacy);
     ix.addMany(current);
 
-    expect(warn).not.toHaveBeenCalled();
+    expect(onConflict).not.toHaveBeenCalled();
     expect(ix.size()).toBe(legacy.length);
     expect(ix.components.byId(legacyId)?.name).toBe("Button");
     expect(ix.components.byId(currentId)?.name).toBe("Button");
-    warn.mockRestore();
   });
 });
 

package/src/facts/index.ts

@@ -53,6 +53,7 @@ export type {
   UsageInlineStyleFact,
   UsageTextChildFact,
   StyleDeclarationFact,
+  StyleValueProvenance,
   StyleUnsupportedFact,
   UnsupportedStyleReason,
   ClassNameLiteralFact,
@@ -60,11 +61,11 @@ export type {
   ClassNameFact,
   ClassNameOrigin,
   ClassNameDynamicReason,
-	  TailwindClassFact,
-	  TailwindModifier,
-	  TailwindModifierKind,
-	  SuppressionDirectiveFact,
-	  TailwindResolvedKind,
+  TailwindClassFact,
+  TailwindModifier,
+  TailwindModifierKind,
+  SuppressionDirectiveFact,
+  TailwindResolvedKind,
   TailwindResolutionSource,
   TailwindResolvedValue,
   TailwindTokenResolvedFact,
@@ -119,7 +120,9 @@ export {
 } from "./builders.js";
 
 export { FactIndex, matchesGlob } from "./fact-index.js";
-export type { FactEvidence } from "./fact-index.js";
+export type { FactConflict, FactEvidence } from "./fact-index.js";
 
 export { compileGlobalGovernanceFacts, compileComponentFacts } from "./compile.js";
+export { projectSupersededImportPathPreferences } from "./compile.js";
+export type { SupersededImportPathPreference } from "./compile.js";
 export type { ComponentFactInput } from "./compile.js";