@usefragments/core 1.5.0 → 1.5.1

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,73 @@ 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: {

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[];

package/src/index.ts

@@ -227,6 +227,12 @@ export type {
 // Token types
 export type {
   TokenCategory,
+  TokenCatalog,
+  TokenCatalogDefinition,
+  TokenCatalogDiagnostic,
+  TokenCatalogLocation,
+  TokenCatalogReference,
+  TokenCatalogSourceState,
   DesignToken,
   TokenRegistry,
   TokenRegistryMeta,
@@ -435,6 +441,7 @@ export type { InferProps } from "./defineFragment.js";
 export {
   componentGovernanceRecordSchema,
   componentGovernanceRecordsSchema,
+  canonicalBridgeV1Schema,
   g,
   globalGovernanceRecordSchema,
   globalJsxGovernanceRecordSchema,
@@ -446,6 +453,7 @@ export {
 } from "./governance.js";
 export type {
   AccessibilityGovernanceBuilder,
+  CanonicalBridgeV1,
   CanonicalSource,
   ComponentGovernanceBuilder,
   ComponentGovernanceRecord,
@@ -645,10 +653,7 @@ export {
   ruleTokensRequireDualFallback,
   ruleA11yRequiredAccessibleName,
 } from "./rules/index.js";
-export {
-  indexComponentIdentityUsage,
-  type ComponentIdentityUsage,
-} from "./identity/usage.js";
+export { indexComponentIdentityUsage, type ComponentIdentityUsage } from "./identity/usage.js";
 export { nearestSignedScaleValue } from "./rules/utils.js";
 export {
   buildSpacingTokenLookup,
@@ -720,6 +725,24 @@ export type {
   GovernanceIntegrityVerdict,
 } from "./governance-integrity.js";
 
+export {
+  canonicalDirectionConflictsTarget,
+  projectCanonicalDirectionConflicts,
+} from "./canonical-direction.js";
+export type { CanonicalDirectionConflict } from "./canonical-direction.js";
+
+export { canonicalBridgeContractMappings } from "./canonical-bridge.js";
+
+export {
+  compileEffectiveGovernanceInputs,
+  EFFECTIVE_GOVERNANCE_INPUTS_SCHEMA,
+} from "./effective-governance-inputs.js";
+export type {
+  CompileEffectiveGovernanceInputsOptions,
+  EffectiveGovernanceInputs,
+  EffectiveGovernanceInputsSourceState,
+} from "./effective-governance-inputs.js";
+
 // Fact IR + index (Phase 3 of the governance compiler refactor)
 export {
   componentId,

package/src/rules/__tests__/fix-emission-invariant.test.ts

@@ -65,6 +65,34 @@ describe("proof-carrying fix invariant", () => {
       "token reference is not directly applicable"
     );
   });
+
+  it("keeps JavaScript member tokens advisory without inventing a CSS variable", () => {
+    const ix = buildFixtureCorpus("js-member", "radii.md");
+    const dimension = RULES.find((rule) => rule.id === "styles/no-raw-dimensions")
+      ?.run(ix)
+      .find((finding) => finding.fix);
+
+    expect(dimension?.fix).toMatchObject({
+      value: "radii.md",
+      deterministic: false,
+    });
+    expect(JSON.stringify(dimension?.fix)).not.toContain("var(--radii-md)");
+    expect(dimension?.attributes?.downgradeReason).toContain(
+      "token reference is not directly applicable"
+    );
+  });
+
+  it("fails closed when a legacy token fact has no authored reference format", () => {
+    const ix = buildFixtureCorpus("unknown");
+    const dimension = RULES.find((rule) => rule.id === "styles/no-raw-dimensions")
+      ?.run(ix)
+      .find((finding) => finding.fix);
+
+    expect(dimension?.fix?.deterministic).toBe(false);
+    expect(dimension?.attributes?.downgradeReason).toContain(
+      "token reference is not directly applicable"
+    );
+  });
 });
 
 function runEveryRule(ix: FactIndex): Finding[] {
@@ -98,7 +126,10 @@ function withoutDeterminism(fix: FindingFix): Omit<FindingFix, "deterministic">
   return rest;
 }
 
-function buildFixtureCorpus(radiusReferenceFormat: "css-var" | "dtcg" = "css-var"): FactIndex {
+function buildFixtureCorpus(
+  radiusReferenceFormat: "css-var" | "dtcg" | "js-member" | "unknown" = "css-var",
+  radiusName = "--proof-radius"
+): FactIndex {
   const ix = new FactIndex();
   ix.addMany([
     makeTokenDefinitionFact({
@@ -116,11 +147,11 @@ function buildFixtureCorpus(radiusReferenceFormat: "css-var" | "dtcg" = "css-var
       sourceNames: ["--proof-space"],
     }),
     makeTokenDefinitionFact({
-      name: "--proof-radius",
+      name: radiusName,
       value: "4px",
       category: "radius",
-      referenceFormat: radiusReferenceFormat,
-      sourceNames: ["--proof-radius"],
+      referenceFormat: radiusReferenceFormat === "unknown" ? undefined : radiusReferenceFormat,
+      sourceNames: [radiusName],
     }),
     makeTokenDefinitionFact({
       name: "--proof-font",

package/src/rules/components-prefer-library.test.ts

@@ -4,6 +4,7 @@ import {
   asComponentId,
   compileGlobalGovernanceFacts,
   FactIndex,
+  makeComponentDefinitionFact,
   makeComponentIdentityFact,
   makeUsageComponentFact,
   makeUsageImportFact,
@@ -11,6 +12,108 @@ import {
   ruleComponentsPreferLibrary,
 } from "../index.js";
 
+describe("components/prefer-library — canonical direction containment", () => {
+  const componentKey = "src/components/Button.tsx#Button";
+
+  function indexFor(decision?: "sanction" | "reject", exported = true) {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "warning",
+            options: {
+              canonicalSources: [
+                { kind: "npm", specifier: "@mui/material", include: ["Button", "Stepper"] },
+              ],
+            },
+          },
+        },
+      })
+    );
+    const definition = makeComponentDefinitionFact({
+      file: "src/components/Button.tsx",
+      exportName: "Button",
+      exported,
+      componentKey,
+      renderRoot: {
+        resolution: "canonical",
+        canonical: "@mui/material#Button",
+        importSource: "@mui/material",
+      },
+      propSurface: [],
+    });
+    ix.add(definition);
+    ix.add(
+      makeComponentIdentityFact({
+        componentKey,
+        state: decision === "reject" ? "shadow" : "variant",
+        confidence: decision ? "confirmed" : "review",
+        canonicalTarget: "Button",
+        ...(decision ? { decisionId: `local:${decision}:${componentKey}` } : {}),
+        evidence: [definition.id],
+      })
+    );
+    return ix;
+  }
+
+  function addLocalUsage(ix: FactIndex, name: "Button" | "Stepper") {
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/App.tsx",
+        nodePath: `0:${name}`,
+        element: name,
+        location: { file: "src/App.tsx", line: 3, column: 2 },
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/App.tsx",
+        local: name,
+        imported: name,
+        source: `./components/${name}`,
+        location: { file: "src/App.tsx", line: 1, column: 0 },
+      })
+    );
+  }
+
+  it("suppresses only the exact conflicted npm export when direction is unresolved", () => {
+    const ix = indexFor();
+    addLocalUsage(ix, "Button");
+    addLocalUsage(ix, "Stepper");
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/App.tsx",
+        nodePath: "0:raw-button",
+        element: "button",
+        interactive: true,
+        location: { file: "src/App.tsx", line: 4, column: 2 },
+      })
+    );
+
+    const findings = ruleComponentsPreferLibrary(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.attributes?.suggestedComponent).toBe("Stepper");
+  });
+
+  it("keeps a sanctioned wrapper exempt and restores npm guidance after explicit rejection", () => {
+    const sanctioned = indexFor("sanction");
+    addLocalUsage(sanctioned, "Button");
+    expect(ruleComponentsPreferLibrary(sanctioned)).toHaveLength(0);
+
+    const rejected = indexFor("reject");
+    addLocalUsage(rejected, "Button");
+    expect(ruleComponentsPreferLibrary(rejected)).toHaveLength(1);
+  });
+
+  it("does not let a private helper deactivate canonical policy", () => {
+    const ix = indexFor(undefined, false);
+    addLocalUsage(ix, "Button");
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(1);
+  });
+});
+
 // #9e — import-path identity for a DIRECTORY canonical source. A directory
 // source (e.g. `src/components/ui`) declares its canonical component NAMES via an
 // include list. The rule must:

package/src/rules/components-prefer-library.ts

@@ -15,6 +15,11 @@ import {
   type RawHtmlPrecisionTier,
 } from "../raw-html-canonical.js";
 import { ownedImportMatchesRoot, ownedImportsEqual } from "../package-identity-match.js";
+import {
+  canonicalDirectionConflictsTarget,
+  projectCanonicalDirectionConflicts,
+  type CanonicalDirectionConflict,
+} from "../canonical-direction.js";
 
 import { makeFinding } from "./finding.js";
 import type { Finding } from "./types.js";
@@ -254,8 +259,12 @@ function findClassNameReimpl(
 export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
   const policy = ix.policy.ruleConfig(RULE_ID);
   if (!policy?.enabled) return [];
-  const sources = canonicalSourcesFromPolicy(policy.options?.canonicalSources);
-  const mappings = canonicalMappingsFromPolicy(policy.options?.canonicalMappings);
+  const configuredSources = canonicalSourcesFromPolicy(policy.options?.canonicalSources);
+  const conflicts = projectCanonicalDirectionConflicts(ix, configuredSources);
+  const sources = configuredSources.map((source) => suppressConflictedExports(source, conflicts));
+  const mappings = canonicalMappingsFromPolicy(policy.options?.canonicalMappings).filter(
+    (mapping) => !canonicalDirectionConflictsTarget(conflicts, mapping.importPath, mapping.name)
+  );
   if (sources.length === 0 && mappings.length === 0) return [];
 
   const importsByFileAndLocal = indexImportsByFileAndLocal(ix);
@@ -605,6 +614,22 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
   return findings;
 }
 
+function suppressConflictedExports(
+  source: CanonicalSource,
+  conflicts: readonly CanonicalDirectionConflict[]
+): CanonicalSource {
+  if (source.kind !== "npm") return source;
+  const names = conflicts
+    .filter((conflict) => ownedImportMatchesRoot(source.specifier, conflict.packageName))
+    .map((conflict) => conflict.exportName);
+  if (names.length === 0) return source;
+  const blocked = new Set(names);
+  if (source.include) {
+    return { ...source, include: source.include.filter((name) => !blocked.has(name)) };
+  }
+  return { ...source, exclude: [...new Set([...(source.exclude ?? []), ...names])].sort() };
+}
+
 function indexShadowRenderRootNodeIds(ix: FactIndex): Set<FactId> {
   const identities = ix.byKind("component_identity");
   if (identities.length === 0) return new Set();
@@ -1113,8 +1138,9 @@ function indexCanonicalDirectoryResolvedNodes(
 ): Set<FactId> {
   const out = new Set<FactId>();
   const directoryPaths = sources
-    .filter((source): source is Extract<CanonicalSource, { kind: "directory" }> =>
-      source.kind === "directory"
+    .filter(
+      (source): source is Extract<CanonicalSource, { kind: "directory" }> =>
+        source.kind === "directory"
     )
     .map((source) => normalizePath(source.path));
   if (directoryPaths.length === 0) return out;

package/src/rules/fix-availability.ts

@@ -25,6 +25,7 @@ export const RULE_FIX_AVAILABLE = {
   "tailwind/unknown-class": false,
   "tokens/require-dual-fallback": true,
   "tokens/css-vars-must-be-defined": false,
+  "tokens/upstream-drift": false,
   "theme/no-theme-coupled-literal": false,
   "a11y/required-accessible-name": false,
   "composition/cardinality": false,

package/src/rules/index.ts

@@ -31,6 +31,7 @@ import { ruleTailwindRawColorViaToken } from "./tailwind-raw-color-via-token.js"
 import { ruleTailwindUnknownClass } from "./tailwind-unknown-class.js";
 import { ruleTokensRequireDualFallback } from "./tokens-require-dual-fallback.js";
 import { ruleTokensCssVarsMustBeDefined } from "./tokens-css-vars-must-be-defined.js";
+import { ruleTokensUpstreamDrift } from "./tokens-upstream-drift.js";
 import type { Finding } from "./types.js";
 
 export type RuleFn = (ix: FactIndex) => Finding[];
@@ -137,6 +138,11 @@ export const RULES: readonly Rule[] = [
     version: "1",
     run: ruleTokensCssVarsMustBeDefined,
   },
+  {
+    id: "tokens/upstream-drift",
+    version: "1",
+    run: ruleTokensUpstreamDrift,
+  },
   {
     id: "theme/no-theme-coupled-literal",
     version: "1",
@@ -211,6 +217,7 @@ export { ruleTailwindRawColorViaToken } from "./tailwind-raw-color-via-token.js"
 export { ruleTailwindUnknownClass } from "./tailwind-unknown-class.js";
 export { ruleTokensRequireDualFallback } from "./tokens-require-dual-fallback.js";
 export { ruleTokensCssVarsMustBeDefined } from "./tokens-css-vars-must-be-defined.js";
+export { ruleTokensUpstreamDrift } from "./tokens-upstream-drift.js";
 export { ruleThemeNoThemeCoupledLiteral } from "./theme-no-theme-coupled-literal.js";
 export { ruleA11yRequiredAccessibleName } from "./a11y-required-accessible-name.js";
 export { ruleCompositionCardinality, ruleCompositionCoOccurrence } from "./composition-pattern.js";

package/src/rules/jsx-preferred-import-path.ts

@@ -1,5 +1,5 @@
 import type { FactIndex } from "../facts/index.js";
-import { ownedImportsEqual } from "../package-identity-match.js";
+import { ownedImportMatchesRoot, ownedImportsEqual } from "../package-identity-match.js";
 
 import { makeFinding } from "./finding.js";
 import type { Finding } from "./types.js";
@@ -16,6 +16,21 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
 
   for (const usage of ix.byKind("usage_import")) {
     const matches = policies.filter((policy) => {
+      if (policy.bridge) {
+        if (policy.bridge.implementationFiles.some((file) => sameRepoPath(file, usage.file))) {
+          return false;
+        }
+        if (!ownedImportMatchesRoot(usage.source, policy.from)) return false;
+        if (ownedImportsEqual(usage.source, policy.from)) {
+          return usage.imported === policy.bridge.underlyingExportName;
+        }
+        const subpath = usage.source.slice(policy.from.length + 1);
+        const leaf = subpath.split("/").at(-1);
+        return (
+          leaf === policy.bridge.underlyingExportName &&
+          (usage.imported === "default" || usage.imported === policy.bridge.underlyingExportName)
+        );
+      }
       if (!ownedImportsEqual(policy.from, usage.source)) return false;
       if (policy.imported !== undefined && policy.imported !== usage.imported) return false;
       return true;
@@ -33,7 +48,9 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
           ruleId: RULE_ID,
           ruleVersion: RULE_VERSION,
           severity: policy.severity,
-          message: `Import from "${usage.source}" should use "${policy.to}".`,
+          message: policy.bridge
+            ? `Import ${policy.bridge.underlyingExportName} through the confirmed local ${policy.bridge.localExportName} wrapper from "${policy.to}".`
+            : `Import from "${usage.source}" should use "${policy.to}".`,
           location: usage.location,
           evidence: ix.evidence([usage.id, policy.id]),
           fingerprintIdentity: {
@@ -44,19 +61,30 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
             line: usage.location.line,
             column: usage.location.column,
           },
-          fix: {
-            kind: "replaceImport",
-            title: policy.because ?? `Replace import path with "${policy.to}"`,
-            from: usage.source,
-            to: policy.to,
-            deterministic: true,
-          },
+          fix: policy.bridge
+            ? undefined
+            : {
+                kind: "replaceImport",
+                title: policy.because ?? `Replace import path with "${policy.to}"`,
+                from: usage.source,
+                to: policy.to,
+                deterministic: true,
+              },
           attributes: {
             importPath: usage.source,
             suggestedImport: policy.to,
             imported: usage.imported,
             local: usage.local,
             rawValue: usage.source,
+            ...(policy.bridge
+              ? {
+                  canonicalBridge: true,
+                  canonicalTarget: policy.bridge.componentKey,
+                  suggestedComponent: policy.bridge.localExportName,
+                  implementationFiles: policy.bridge.implementationFiles,
+                  decisionSource: policy.bridge.decisionSource,
+                }
+              : {}),
           },
         })
       );
@@ -65,3 +93,11 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
 
   return findings;
 }
+
+function sameRepoPath(left: string, right: string): boolean {
+  return normalizeRepoPath(left) === normalizeRepoPath(right);
+}
+
+function normalizeRepoPath(path: string): string {
+  return path.replace(/\\/gu, "/").replace(/^\.\//u, "");
+}