@usefragments/core 1.5.2 → 1.7.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,
@@ -56,6 +58,7 @@ import type {
   ThemeDeclarationFact,
   TokenDefinitionFact,
   UsageComponentFact,
+  UsageChildContentFact,
   UsageImportFact,
   UsageInlineStyleFact,
   UsageNodeFact,
@@ -64,6 +67,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 +386,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 +394,7 @@ export function makeStyleRawColorForbiddenFact(input: {
     except: [...input.except],
     prefer: input.prefer,
     severity: input.severity,
+    ...policyExcludeField(input.exclude),
   };
 }
 
@@ -386,6 +402,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 +410,7 @@ export function makeStyleRawDimensionForbiddenFact(input: {
     appliesTo: [...input.appliesTo],
     prefer: input.prefer,
     severity: input.severity,
+    ...policyExcludeField(input.exclude),
   };
 }
 
@@ -400,6 +418,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 +426,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 +467,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 +498,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 +521,7 @@ export function makeJsxImportPathPreferredFact(input: {
           },
         }
       : {}),
+    ...policyExcludeField(input.exclude),
   };
 }
 
@@ -500,6 +530,7 @@ export function makeJsxComponentPreferredFact(input: {
   to: ComponentId;
   because?: string;
   severity: GovernanceSeverity;
+  exclude?: readonly PolicyExclude[];
 }): JsxComponentPreferredFact {
   return {
     id: factId("jsx_component_preferred", {
@@ -511,6 +542,7 @@ export function makeJsxComponentPreferredFact(input: {
     to: input.to,
     because: input.because,
     severity: input.severity,
+    ...policyExcludeField(input.exclude),
   };
 }
 
@@ -690,6 +722,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 +734,7 @@ export function makeUsageInlineStyleFact(input: {
     property: input.property,
     valueKind: input.valueKind,
     value: input.value,
+    ...(input.valueFrom ? { valueFrom: input.valueFrom } : {}),
   };
 }
 
@@ -718,6 +752,18 @@ export function makeUsageTextChildFact(input: {
   };
 }
 
+export function makeUsageChildContentFact(input: {
+  nodeId: FactId;
+  content: UsageChildContentFact["content"];
+}): UsageChildContentFact {
+  return {
+    id: factId("usage_child_content", { nodeId: input.nodeId }),
+    kind: "usage_child_content",
+    nodeId: input.nodeId,
+    content: input.content,
+  };
+}
+
 export function makeClassNameLiteralFact(input: {
   file: string;
   nodeId: FactId;
@@ -856,6 +902,7 @@ export function makeStyleDeclarationFact(input: {
   value: string;
   location: FactLocation;
   declaredTokenSource?: boolean;
+  valueFrom?: StyleValueProvenance;
 }): StyleDeclarationFact {
   return {
     id: factId("style_declaration", {
@@ -872,6 +919,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 [];
@@ -239,19 +353,19 @@ function compileRuleConfigFacts(govern: GovernanceConfig): PolicyFact[] {
     configs.set(ruleId, ruleConfigFromValue(value, govern.severity ?? "warn"));
   }
 
-  if (
-    govern.canonicalSources?.length &&
-    configs.get("components/prefer-library")?.enabled !== false
-  ) {
-    const existing = configs.get("components/prefer-library");
-    configs.set("components/prefer-library", {
-      enabled: true,
-      severity: existing?.severity ?? govern.severity ?? "warn",
-      options: {
-        ...existing?.options,
-        canonicalSources: existing?.options?.canonicalSources ?? govern.canonicalSources,
-      },
-    });
+  if (govern.canonicalSources?.length) {
+    for (const ruleId of ["components/prefer-library", "components/shadow-component"] as const) {
+      const existing = configs.get(ruleId);
+      if (existing?.enabled === false) continue;
+      configs.set(ruleId, {
+        enabled: true,
+        severity: existing?.severity ?? govern.severity ?? "warn",
+        options: {
+          ...existing?.options,
+          canonicalSources: existing?.options?.canonicalSources ?? govern.canonicalSources,
+        },
+      });
+    }
   }
 
   return [...configs.entries()].map(([ruleId, config]) =>

package/src/facts/fact-index.ts

@@ -45,9 +45,21 @@ 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) => void;
+  onConflict?: (message: string, conflict: FactConflict) => void;
 }
 
 interface FactWithComponent {
@@ -133,7 +145,8 @@ export class FactIndex {
         canonicalJson(logicalFactForComparison(fact))
       ) {
         this.options.onConflict?.(
-          `FactIndex: conflicting facts for id ${fact.id} — keeping ${describeFactForConflict(existing)}, skipping ${describeFactForConflict(fact)}`
+          `FactIndex: conflicting facts for id ${fact.id} — keeping ${describeFactForConflict(existing)}, skipping ${describeFactForConflict(fact)}`,
+          { kept: existing, skipped: fact }
         );
       }
       return;

package/src/facts/facts.test.ts

@@ -370,7 +370,7 @@ describe("FactIndex — query layer", () => {
     expect(unknownProps?.severity).toBe("error");
   });
 
-  it("activates prefer-library from top-level canonical sources", () => {
+  it("activates canonical-component rules from top-level canonical sources", () => {
     const ix = new FactIndex();
     ix.addMany(
       compileGlobalGovernanceFacts({
@@ -397,6 +397,43 @@ describe("FactIndex — query layer", () => {
         ],
       },
     });
+    expect(ix.policy.ruleConfig("components/shadow-component")).toMatchObject({
+      enabled: true,
+      severity: "warn",
+      options: {
+        canonicalSources: [
+          {
+            kind: "npm",
+            specifier: "@usefragments/ui",
+            include: ["Button"],
+          },
+        ],
+      },
+    });
+  });
+
+  it("preserves an explicit shadow-component disable when canonical sources are declared", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        canonicalSources: [
+          {
+            kind: "npm",
+            specifier: "@usefragments/ui",
+            include: ["Button"],
+          },
+        ],
+        rules: {
+          "components/shadow-component": false,
+        },
+      })
+    );
+
+    expect(ix.policy.ruleConfig("components/prefer-library")?.enabled).toBe(true);
+    expect(ix.policy.ruleConfig("components/shadow-component")).toMatchObject({
+      enabled: false,
+      ruleId: "components/shadow-component",
+    });
   });
 
   it("resolves preferred import and component policy facts", () => {
@@ -469,7 +506,10 @@ describe("FactIndex — query layer", () => {
     };
     ix.add(a);
     expect(() => ix.add(b)).not.toThrow();
-    expect(onConflict).toHaveBeenCalledWith(expect.stringContaining("conflicting facts"));
+    expect(onConflict).toHaveBeenCalledWith(expect.stringContaining("conflicting facts"), {
+      kept: a,
+      skipped: b,
+    });
     expect(ix.get(id)).toEqual(a);
   });
 
@@ -514,7 +554,8 @@ describe("FactIndex — query layer", () => {
     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);
   });

package/src/facts/index.ts

@@ -48,11 +48,13 @@ export type {
   GovernanceRuleConfigFact,
   UsageNodeFact,
   UsageComponentFact,
+  UsageChildContentFact,
   UsageImportFact,
   UsagePropResolvedFact,
   UsageInlineStyleFact,
   UsageTextChildFact,
   StyleDeclarationFact,
+  StyleValueProvenance,
   StyleUnsupportedFact,
   UnsupportedStyleReason,
   ClassNameLiteralFact,
@@ -60,11 +62,11 @@ export type {
   ClassNameFact,
   ClassNameOrigin,
   ClassNameDynamicReason,
-	  TailwindClassFact,
-	  TailwindModifier,
-	  TailwindModifierKind,
-	  SuppressionDirectiveFact,
-	  TailwindResolvedKind,
+  TailwindClassFact,
+  TailwindModifier,
+  TailwindModifierKind,
+  SuppressionDirectiveFact,
+  TailwindResolvedKind,
   TailwindResolutionSource,
   TailwindResolvedValue,
   TailwindTokenResolvedFact,
@@ -105,6 +107,7 @@ export {
   makeGovernanceRuleConfigFact,
   makeUsageNodeFact,
   makeUsageComponentFact,
+  makeUsageChildContentFact,
   makeUsageImportFact,
   makeUsagePropResolvedFact,
   makeUsageInlineStyleFact,
@@ -119,7 +122,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";