@usefragments/core 1.5.0 → 1.5.2

package/src/facts/fact-index.ts

@@ -45,6 +45,11 @@ export interface FactEvidence {
   fact: Fact;
 }
 
+export interface FactIndexOptions {
+  /** Optional internal diagnostic route. Product output is quiet by default. */
+  onConflict?: (message: string) => void;
+}
+
 interface FactWithComponent {
   componentId: ComponentId;
 }
@@ -115,6 +120,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,7 +132,7 @@ export class FactIndex {
         canonicalJson(logicalFactForComparison(existing)) !==
         canonicalJson(logicalFactForComparison(fact))
       ) {
-        console.warn(
+        this.options.onConflict?.(
           `FactIndex: conflicting facts for id ${fact.id} — keeping ${describeFactForConflict(existing)}, skipping ${describeFactForConflict(fact)}`
         );
       }
@@ -360,6 +367,10 @@ export class FactIndex {
   // ---------------------------------------------------------------------
 
   private indexTokenSymbols(fact: TokenDefinitionFact): void {
+    // Upstream definitions are comparison evidence, not local replacement
+    // candidates. Keeping them out of the reverse symbol index also prevents a
+    // known-drift upstream value from making the local token look safe.
+    if (fact.role === "upstream") return;
     const legacyScssAlias =
       fact.referenceFormat === "scss-var" && fact.name.startsWith("--")
         ? `$${fact.name.slice(2)}`

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,13 @@ 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"));
     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 +490,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 +511,12 @@ 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/
       )
     );
     expect(ix.get(first.id)).toEqual(first);
-    warn.mockRestore();
   });
 
   it("treats old and current owned component spellings as the same indexed facts", () => {
@@ -527,17 +524,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/types.ts

@@ -184,6 +184,14 @@ export interface JsxImportPathPreferredFact extends BaseFact {
   imported?: string;
   because?: string;
   severity: GovernanceSeverity;
+  /** Present when the policy was compiled from a confirmed local-canonical bridge. */
+  bridge?: {
+    componentKey: string;
+    localExportName: string;
+    underlyingExportName: string;
+    implementationFiles: string[];
+    decisionSource: "authored" | "migration";
+  };
 }
 
 export interface JsxComponentPreferredFact extends BaseFact {
@@ -197,7 +205,9 @@ export interface JsxComponentPreferredFact extends BaseFact {
 /**
  * A design token from the system. Used by fixes (e.g., raw color → token
  * substitution) and rules that need to know the token vocabulary. Identity is
- * the token `name`; two scans of the same token registry produce the same ID.
+ * the token `name` for legacy/local facts. Authority-aware facts also include
+ * role and source identity so same-name local/upstream definitions cannot
+ * silently collapse in the fact index.
  */
 export interface TokenDefinitionFact extends BaseFact {
   kind: "token_definition";
@@ -212,14 +222,21 @@ export interface TokenDefinitionFact extends BaseFact {
    * How the token is referenced from authored styles, inferred from its source.
    * Governs whether a "use the token" fix can be *applied* automatically: a
    * `css-var`/`scss-var` reference resolves verbatim, but a `scss-map` member
-   * (`$colors-primary` minted from a Sass map) or a `dtcg` JSON token (no CSS
-   * custom property emitted) does not — those are surfaced as suggestions, not
-   * deterministic rewrites, so the fixer never writes non-compiling output.
-   * Absent on legacy/hand-built facts, which are treated as safe.
+   * (`$colors-primary` minted from a Sass map), a `dtcg` JSON token (no CSS
+   * custom property emitted), or a `js-member` path (`colors.primary`) does not
+   * — those are surfaced as suggestions, not deterministic rewrites, so the
+   * fixer never writes invented syntax. Absent on legacy/hand-built facts,
+   * which fail closed because an unknown authored form is not applicability
+   * proof.
    */
-  referenceFormat?: "css-var" | "scss-var" | "scss-map" | "dtcg";
+  referenceFormat?: "css-var" | "scss-var" | "scss-map" | "dtcg" | "js-member";
   /** Original authored spellings retained before parser normalization. */
   sourceNames?: string[];
+  role?: "local" | "upstream";
+  authority?: "authored" | "declared-package";
+  sourceIdentity?: string;
+  /** Authored upstream identity when the local and upstream names differ. */
+  upstreamName?: string;
 }
 
 export interface TailwindPaletteAllowFact extends BaseFact {
@@ -611,6 +628,8 @@ export interface ComponentDefinitionFact extends BaseFact {
   componentId: ComponentId;
   file: string;
   exportName: string;
+  /** Whether this definition is reachable through an authored ESM export. */
+  exported: boolean;
   componentKey: string;
   renderRoot: ComponentDefinitionRenderRoot;
   propSurface: string[];

package/src/governance-integrity.test.ts

@@ -2,12 +2,15 @@ import { describe, expect, it } from "vitest";
 
 import type { GovernanceConfig } from "./governance.js";
 import {
+  detectOrphanGovernanceScales,
+  detectUnconsumedConfigKeys,
   evaluateGovernanceIntegrity,
   hasEffectiveComponentVocabulary,
   isEffectiveCanonicalSource,
   type GovernanceIntegrityInput,
 } from "./governance-integrity.js";
 import { customerDefaultRuleStates } from "./rules/presets.js";
+import { fragmentsConfigSchema } from "./schema.js";
 
 function evaluate(
   overrides: Partial<GovernanceIntegrityInput>
@@ -66,6 +69,84 @@ 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/**"] },
+          "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.exclude" },
+      { 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("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([]);
+  });
+});
+
 describe("evaluateGovernanceIntegrity", () => {
   it("1. no policy at all → inert, not fatal, not blocking-capable", () => {
     const verdict = evaluate({ policy: undefined, policySource: "none", declared: false });
@@ -139,6 +220,28 @@ describe("evaluateGovernanceIntegrity", () => {
     expect(verdict.status).toBe("healthy");
   });
 
+  it("6b. a confirmed local bridge arms exact component governance", () => {
+    const policy: GovernanceConfig = {
+      canonicalBridges: [
+        {
+          underlying: { packageName: "@mui/material", exportName: "Button" },
+          local: {
+            componentKey: "src/components/Button.tsx#Button",
+            moduleSpecifier: "@/components/Button",
+            exportName: "Button",
+            implementationFiles: ["src/components/Button.tsx"],
+          },
+          decision: { state: "confirmed", source: "authored" },
+        },
+      ],
+    };
+    const verdict = evaluate({ policy, policySource: "config", declared: true });
+    const components = verdict.families.find((family) => family.id === "components");
+    expect(components).toMatchObject({ armed: true });
+    expect(components?.rules).toContain("imports/preferred-path");
+    expect(verdict.status).toBe("healthy");
+  });
+
   it("7. css-vars active + token vocabulary → tokens armed → healthy", () => {
     const policy: GovernanceConfig = {
       styles: [{ kind: "style.cssVars.mustBeDefined", severity: "warn" }],
@@ -185,4 +288,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);
+  });
 });