@usefragments/core 1.4.0 → 1.5.1

package/src/facts/builders.ts

@@ -9,7 +9,7 @@
  */
 
 import type { GovernanceSeverity } from "../governance.js";
-import { factId } from "./ids.js";
+import { asComponentId, factId } from "./ids.js";
 import type {
   A11yNameRequiredFact,
   CanonicalCandidateFact,
@@ -20,7 +20,9 @@ import type {
   ClassNameLiteralFact,
   ClassNameOrigin,
   ComponentCapabilityFact,
+  ComponentDefinitionFact,
   ComponentId,
+  ComponentIdentityFact,
   ComponentMetadataFact,
   FactLocation,
   GovernanceRuleConfigFact,
@@ -99,6 +101,50 @@ export function makeComponentCapabilityFact(input: {
   };
 }
 
+export function makeComponentDefinitionFact(input: {
+  file: string;
+  exportName: string;
+  exported?: boolean;
+  componentKey: string;
+  renderRoot: ComponentDefinitionFact["renderRoot"];
+  propSurface: string[];
+  stylingChannel?: ComponentDefinitionFact["stylingChannel"];
+}): ComponentDefinitionFact {
+  return {
+    id: factId("component_definition", { componentKey: input.componentKey }),
+    kind: "component_definition",
+    componentId: asComponentId(input.componentKey),
+    file: input.file,
+    exportName: input.exportName,
+    exported: input.exported ?? false,
+    componentKey: input.componentKey,
+    renderRoot: input.renderRoot,
+    propSurface: [...input.propSurface],
+    ...(input.stylingChannel ? { stylingChannel: { ...input.stylingChannel } } : {}),
+  };
+}
+
+export function makeComponentIdentityFact(input: {
+  componentKey: string;
+  state: ComponentIdentityFact["state"];
+  confidence: ComponentIdentityFact["confidence"];
+  canonicalTarget?: string;
+  decisionId?: string;
+  evidence: FactId[];
+}): ComponentIdentityFact {
+  return {
+    id: factId("component_identity", { componentKey: input.componentKey }),
+    kind: "component_identity",
+    componentId: asComponentId(input.componentKey),
+    componentKey: input.componentKey,
+    state: input.state,
+    confidence: input.confidence,
+    ...(input.canonicalTarget ? { canonicalTarget: input.canonicalTarget } : {}),
+    ...(input.decisionId ? { decisionId: input.decisionId } : {}),
+    evidence: [...input.evidence],
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Classifier facts
 // ---------------------------------------------------------------------------
@@ -423,12 +469,14 @@ export function makeJsxImportPathPreferredFact(input: {
   imported?: string;
   because?: string;
   severity: GovernanceSeverity;
+  bridge?: JsxImportPathPreferredFact["bridge"];
 }): JsxImportPathPreferredFact {
   return {
     id: factId("jsx_import_path_preferred", {
       from: input.from,
       to: input.to,
       imported: input.imported,
+      bridge: input.bridge,
     }),
     kind: "jsx_import_path_preferred",
     from: input.from,
@@ -436,6 +484,14 @@ export function makeJsxImportPathPreferredFact(input: {
     imported: input.imported,
     because: input.because,
     severity: input.severity,
+    ...(input.bridge
+      ? {
+          bridge: {
+            ...input.bridge,
+            implementationFiles: [...input.bridge.implementationFiles],
+          },
+        }
+      : {}),
   };
 }
 
@@ -465,9 +521,17 @@ export function makeTokenDefinitionFact(input: {
   category?: TokenDefinitionFact["category"];
   referenceFormat?: TokenDefinitionFact["referenceFormat"];
   sourceNames?: TokenDefinitionFact["sourceNames"];
+  role?: TokenDefinitionFact["role"];
+  authority?: TokenDefinitionFact["authority"];
+  sourceIdentity?: TokenDefinitionFact["sourceIdentity"];
+  upstreamName?: TokenDefinitionFact["upstreamName"];
 }): TokenDefinitionFact {
+  const authorityIdentity =
+    input.role || input.sourceIdentity
+      ? { role: input.role ?? "local", sourceIdentity: input.sourceIdentity ?? "" }
+      : {};
   return {
-    id: factId("token_definition", { name: input.name }),
+    id: factId("token_definition", { name: input.name, ...authorityIdentity }),
     kind: "token_definition",
     name: input.name,
     value: input.value,
@@ -475,6 +539,10 @@ export function makeTokenDefinitionFact(input: {
     category: input.category,
     referenceFormat: input.referenceFormat,
     ...(input.sourceNames?.length ? { sourceNames: [...input.sourceNames] } : {}),
+    ...(input.role ? { role: input.role } : {}),
+    ...(input.authority ? { authority: input.authority } : {}),
+    ...(input.sourceIdentity ? { sourceIdentity: input.sourceIdentity } : {}),
+    ...(input.upstreamName ? { upstreamName: input.upstreamName } : {}),
   };
 }
 

package/src/facts/compile.ts

@@ -153,6 +153,25 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
     }
   }
 
+  for (const bridge of govern.canonicalBridges ?? []) {
+    out.push(
+      makeJsxImportPathPreferredFact({
+        from: bridge.underlying.packageName,
+        to: bridge.local.moduleSpecifier,
+        imported: bridge.underlying.exportName,
+        because: `Use the confirmed local ${bridge.local.exportName} wrapper`,
+        severity: ruleSeverity(govern.rules?.["imports/preferred-path"], govern.severity ?? "warn"),
+        bridge: {
+          componentKey: bridge.local.componentKey,
+          localExportName: bridge.local.exportName,
+          underlyingExportName: bridge.underlying.exportName,
+          implementationFiles: [...bridge.local.implementationFiles],
+          decisionSource: bridge.decision.source,
+        },
+      })
+    );
+  }
+
   const tailwindPalette = govern.tailwind?.palette;
   const forbiddenPaletteSeverity = ruleSeverity(
     govern.rules?.["tailwind/forbidden-palette"],
@@ -230,8 +249,7 @@ function compileRuleConfigFacts(govern: GovernanceConfig): PolicyFact[] {
       severity: existing?.severity ?? govern.severity ?? "warn",
       options: {
         ...existing?.options,
-        canonicalSources:
-          existing?.options?.canonicalSources ?? govern.canonicalSources,
+        canonicalSources: existing?.options?.canonicalSources ?? govern.canonicalSources,
       },
     });
   }

package/src/facts/fact-index.ts

@@ -360,6 +360,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

@@ -10,6 +10,8 @@ import {
   compileGlobalGovernanceFacts,
   g,
   makeTokenDefinitionFact,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
   makeUsageNodeFact,
 } from "../index.js";
 import type { ComponentId, FactId, PropValueForbiddenFact } from "../index.js";
@@ -151,6 +153,34 @@ describe("fact IR — content-addressed IDs", () => {
     expect(a).toBe(b);
   });
 
+  it("keys definition and identity facts by the portable componentKey", () => {
+    const first = makeComponentDefinitionFact({
+      file: "src/a/Button.tsx",
+      exportName: "Button",
+      componentKey: "src/a/Button.tsx#Button",
+      renderRoot: { resolution: "intrinsic", tag: "button", interactive: true },
+      propSurface: ["disabled"],
+    });
+    const second = makeComponentDefinitionFact({
+      file: "src/b/Button.tsx",
+      exportName: "Button",
+      componentKey: "src/b/Button.tsx#Button",
+      renderRoot: { resolution: "intrinsic", tag: "button", interactive: true },
+      propSurface: ["disabled"],
+    });
+    const identity = makeComponentIdentityFact({
+      componentKey: first.componentKey,
+      state: "shadow",
+      confidence: "confirmed",
+      canonicalTarget: "Button",
+      evidence: [first.id],
+    });
+
+    expect(first.id).not.toBe(second.id);
+    expect(String(identity.componentId)).toBe(first.componentKey);
+    expect(identity.evidence).toEqual([first.id]);
+  });
+
   it("keeps v1 IDs stable across owned package spellings only in typed identity fields", () => {
     const legacyComponentId = asComponentId("@fragments-sdk/ui#Button");
     const currentComponentId = asComponentId("@usefragments/ui#Button");

package/src/facts/index.ts

@@ -18,6 +18,10 @@ export type {
   CanonicalMappingFact,
   CanonicalReplacementFact,
   ComponentLevelFact,
+  ComponentDefinitionFact,
+  ComponentDefinitionRenderRoot,
+  ComponentIdentityFact,
+  IdentityFact,
   PolicyFact,
   UsageFact,
   ComponentMetadataFact,
@@ -73,6 +77,8 @@ export { componentId, asComponentId, factId, hash64Hex, canonicalJson } from "./
 export {
   makeComponentMetadataFact,
   makeComponentCapabilityFact,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
   makePropMetadataFact,
   makePropValueAvoidedFact,
   makePropValueForbiddenFact,

package/src/facts/types.ts

@@ -13,6 +13,7 @@
  */
 
 import type { GovernanceSeverity } from "../governance.js";
+import type { IdentityConfidence, IdentityState } from "../identity/classify.js";
 
 // ---------------------------------------------------------------------------
 // Branded IDs
@@ -183,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 {
@@ -196,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";
@@ -211,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 {
@@ -574,6 +592,65 @@ export interface CanonicalReplacementFact extends BaseFact {
   location?: FactLocation;
 }
 
+// ---------------------------------------------------------------------------
+// Component identity facts
+// ---------------------------------------------------------------------------
+
+export type ComponentDefinitionRenderRoot =
+  | {
+      resolution: "canonical";
+      canonical: string;
+      importSource: string;
+    }
+  | {
+      resolution: "intrinsic";
+      tag: string;
+      role?: string;
+      interactive?: boolean;
+    }
+  | {
+      resolution: "mixed";
+      canonicals: string[];
+      intrinsics: string[];
+    }
+  | {
+      resolution: "external";
+      importSource: string;
+    }
+  | {
+      resolution: "unresolved";
+      reason: string;
+    };
+
+export interface ComponentDefinitionFact extends BaseFact {
+  kind: "component_definition";
+  /** Index-compatible projection of `componentKey`. */
+  componentId: ComponentId;
+  file: string;
+  exportName: string;
+  /** Whether this definition is reachable through an authored ESM export. */
+  exported: boolean;
+  componentKey: string;
+  renderRoot: ComponentDefinitionRenderRoot;
+  propSurface: string[];
+  stylingChannel?: {
+    module: string;
+    ownsVisualRole: boolean;
+  };
+}
+
+export interface ComponentIdentityFact extends BaseFact {
+  kind: "component_identity";
+  /** Index-compatible projection of `componentKey`. */
+  componentId: ComponentId;
+  componentKey: string;
+  state: IdentityState;
+  confidence: IdentityConfidence;
+  canonicalTarget?: string;
+  decisionId?: string;
+  evidence: FactId[];
+}
+
 // ---------------------------------------------------------------------------
 // Discriminated unions
 // ---------------------------------------------------------------------------
@@ -622,7 +699,9 @@ export type UsageFact =
   | StructuralConfidenceFact
   | CanonicalReplacementFact;
 
-export type Fact = ComponentLevelFact | PolicyFact | UsageFact;
+export type IdentityFact = ComponentDefinitionFact | ComponentIdentityFact;
+
+export type Fact = ComponentLevelFact | PolicyFact | UsageFact | IdentityFact;
 
 export type FactKind = Fact["kind"];
 

package/src/governance-integrity.test.ts

@@ -139,6 +139,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" }],

package/src/governance-integrity.ts

@@ -166,23 +166,29 @@ export function evaluateGovernanceIntegrity(
 
   // --- components family ----------------------------------------------------
   const componentsConfig = configs.get("components/prefer-library");
+  const confirmedBridges = input.policy?.canonicalBridges ?? [];
   const componentsArmed =
-    componentsConfig?.enabled === true && hasEffectiveComponentVocabulary(componentsConfig.options);
+    confirmedBridges.length > 0 ||
+    (componentsConfig?.enabled === true &&
+      hasEffectiveComponentVocabulary(componentsConfig.options));
   const componentsFamily: GovernanceIntegrityFamily = {
     id: "components",
     armed: componentsArmed,
-    rules: ["components/prefer-library"],
+    rules: [
+      ...(confirmedBridges.length > 0 ? ["imports/preferred-path"] : []),
+      ...(componentsConfig?.enabled === true ? ["components/prefer-library"] : []),
+    ],
   };
   if (!componentsArmed) {
     if (componentsConfig?.enabled === true) {
       componentsFamily.reason =
         "components/prefer-library enabled but no effective canonical source";
       componentsFamily.remediation =
-        "add govern.canonicalSources (a directory source, or npm/registry with a non-empty include) or designSystem.path/packageName";
+        "add govern.canonicalBridges for local wrappers, govern.canonicalSources, or designSystem.path/packageName";
     } else {
       componentsFamily.reason = "components/prefer-library not enabled";
       componentsFamily.remediation =
-        "add govern.canonicalSources (a directory source, or npm/registry with a non-empty include) or designSystem.path/packageName";
+        "add govern.canonicalBridges for local wrappers, govern.canonicalSources, or designSystem.path/packageName";
     }
   }
 

package/src/governance.test.ts

@@ -139,6 +139,99 @@ describe("governance DSL", () => {
     });
   });
 
+  it("accepts one confirmed package-to-local canonical bridge", () => {
+    const config = defineConfig({
+      govern: {
+        canonicalBridges: [
+          {
+            underlying: { packageName: "@mui/material", exportName: "Button" },
+            local: {
+              componentKey: "src/components/Button.tsx#Button",
+              moduleSpecifier: "@/components",
+              exportName: "Button",
+              implementationFiles: ["src/components/Button.tsx"],
+            },
+            decision: { state: "confirmed", source: "authored" },
+          },
+        ],
+      },
+    });
+
+    expect(config.govern?.canonicalBridges?.[0]).toMatchObject({
+      underlying: { packageName: "@mui/material", exportName: "Button" },
+      local: { moduleSpecifier: "@/components", exportName: "Button" },
+      decision: { state: "confirmed", source: "authored" },
+    });
+  });
+
+  it("rejects ambiguous or unsafe canonical bridge declarations", () => {
+    const bridge = {
+      underlying: { packageName: "@mui/material", exportName: "Button" },
+      local: {
+        componentKey: "src/components/Button.tsx#Button",
+        moduleSpecifier: "@/components",
+        exportName: "Button",
+        implementationFiles: ["src/components/Button.tsx"],
+      },
+      decision: { state: "confirmed" as const, source: "authored" as const },
+    };
+
+    expect(() => defineConfig({ govern: { canonicalBridges: [bridge, bridge] } })).toThrow(
+      "Invalid fragments config"
+    );
+    expect(() =>
+      defineConfig({
+        govern: {
+          canonicalBridges: [
+            bridge,
+            {
+              ...bridge,
+              underlying: { packageName: "@radix-ui/react-slot", exportName: "Slot" },
+            },
+          ],
+        },
+      })
+    ).toThrow("Invalid fragments config");
+    expect(() =>
+      defineConfig({
+        govern: {
+          canonicalBridges: [
+            {
+              ...bridge,
+              local: { ...bridge.local, moduleSpecifier: "../components" },
+            },
+          ],
+        },
+      })
+    ).toThrow("Invalid fragments config");
+  });
+
+  it("preserves top-level component identity decisions", () => {
+    const config = defineConfig({
+      identity: {
+        decisions: [
+          {
+            component: "src/components/AppDialog.tsx#AppDialog",
+            kind: "sanction",
+            canonicalTarget: "Dialog",
+            reason: "Owns the application modal defaults.",
+            decisionId: "local:app-dialog",
+          },
+        ],
+      },
+    });
+
+    expect(config.identity?.decisions).toEqual([
+      {
+        component: "src/components/AppDialog.tsx#AppDialog",
+        kind: "sanction",
+        canonicalTarget: "Dialog",
+        reason: "Owns the application modal defaults.",
+        decisionId: "local:app-dialog",
+      },
+    ]);
+  });
+
   it("rejects unsafe registry canonical source paths", () => {
     expect(() =>
       defineConfig({

package/src/governance.ts

@@ -192,6 +192,79 @@ const canonicalSourcePathSchema = z
 
 const canonicalSourceRegistryHashSchema = z.string().regex(/^[0-9a-f]{64}$/);
 
+const canonicalBridgeModuleSpecifierSchema = z
+  .string()
+  .min(1)
+  .superRefine((value, ctx) => {
+    const normalized = value.replace(/\\/gu, "/");
+    if (normalized.startsWith("/") || /^[A-Za-z]:\//u.test(normalized)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Canonical bridge moduleSpecifier must be a portable import specifier",
+      });
+    }
+    if (normalized.split("/").includes("..")) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Canonical bridge moduleSpecifier must not traverse outside the project",
+      });
+    }
+  });
+
+export const canonicalBridgeV1Schema = z
+  .object({
+    underlying: z
+      .object({
+        packageName: z.string().min(1),
+        exportName: z.string().min(1),
+      })
+      .strict(),
+    local: z
+      .object({
+        componentKey: z.string().min(1),
+        moduleSpecifier: canonicalBridgeModuleSpecifierSchema,
+        exportName: z.string().min(1),
+        implementationFiles: z.array(canonicalSourcePathSchema).min(1),
+      })
+      .strict(),
+    decision: z
+      .object({
+        state: z.literal("confirmed"),
+        source: z.enum(["authored", "migration"]),
+      })
+      .strict(),
+  })
+  .strict();
+
+const canonicalBridgesV1Schema = z.array(canonicalBridgeV1Schema).superRefine((bridges, ctx) => {
+  const underlying = new Map<string, number>();
+  const componentKeys = new Map<string, number>();
+  for (const [index, bridge] of bridges.entries()) {
+    const underlyingKey = `${bridge.underlying.packageName}\u0000${bridge.underlying.exportName}`;
+    const previousUnderlying = underlying.get(underlyingKey);
+    if (previousUnderlying !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Duplicate confirmed bridge target for ${bridge.underlying.packageName}#${bridge.underlying.exportName} (also at canonicalBridges.${previousUnderlying})`,
+        path: [index, "underlying"],
+      });
+    } else {
+      underlying.set(underlyingKey, index);
+    }
+
+    const previousComponent = componentKeys.get(bridge.local.componentKey);
+    if (previousComponent !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Local component key overlaps canonicalBridges.${previousComponent}`,
+        path: [index, "local", "componentKey"],
+      });
+    } else {
+      componentKeys.set(bridge.local.componentKey, index);
+    }
+  }
+});
+
 const canonicalSourceSchema = z.discriminatedUnion("kind", [
   z.object({
     kind: z.literal("npm"),
@@ -237,6 +310,7 @@ export const governanceConfigSchema = z
     audit: z.object({}).passthrough().optional(),
     runners: z.record(z.string(), z.object({}).passthrough()).optional(),
     canonicalSources: z.array(canonicalSourceSchema).optional(),
+    canonicalBridges: canonicalBridgesV1Schema.optional(),
     presets: z.array(z.string()).optional(),
     scales: z.record(z.string(), scaleGovernanceRecordSchema).optional(),
     styles: z.array(globalStyleGovernanceRecordSchema).optional(),
@@ -278,6 +352,7 @@ export type ComponentPolicyMatch = z.infer<typeof componentPolicyMatchSchema>;
 export type ComponentPolicyRecord = z.infer<typeof componentPolicyRecordSchema>;
 export type ComponentPolicyOverride = z.infer<typeof componentPolicyOverrideSchema>;
 export type CanonicalSource = z.infer<typeof canonicalSourceSchema>;
+export type CanonicalBridgeV1 = z.infer<typeof canonicalBridgeV1Schema>;
 
 export interface GovernanceConfig {
   extends?: string[];
@@ -287,6 +362,7 @@ export interface GovernanceConfig {
   audit?: Record<string, unknown>;
   runners?: Record<string, Record<string, unknown>>;
   canonicalSources?: CanonicalSource[];
+  canonicalBridges?: CanonicalBridgeV1[];
   presets?: string[];
   scales?: Record<string, ScaleGovernanceRecord>;
   styles?: GlobalStyleGovernanceRecord[];