@usefragments/core 1.5.2 → 1.7.0

package/src/canonical-bridge.ts

@@ -1,5 +1,5 @@
 import type { ContractCanonicalMappingInput } from "./contract/preimage.js";
-import type { CanonicalBridgeV1 } from "./governance.js";
+import type { CanonicalBridgeV1, CanonicalSource } from "./governance.js";
 import { ownedImportMatchesRoot } from "./package-identity-match.js";
 
 export function canonicalBridgeUnderlyingKey(input: {
@@ -28,6 +28,74 @@ export function canonicalBridgeContractMappings(
   }));
 }
 
+/**
+ * One authored bridge, projected into the two facts a consumer needs to honor
+ * it WITHOUT widening it: the npm canonical source its underlying export
+ * implies, and the local component the user actually sanctioned.
+ *
+ * The pairing is the point. A bridge says "`src/components/Button.tsx#Button`
+ * wraps `@mui/material#Button`" — a fact about ONE component. Reading only the
+ * source half turns it into "`@mui/material#Button` is canonical in this repo",
+ * which is a strictly wider claim: every component in the tree that happens to
+ * render that export inherits the sanction it was never given.
+ */
+export interface CanonicalBridgeIdentityBinding {
+  /** The npm canonical source this bridge's underlying export implies. */
+  source: Extract<CanonicalSource, { kind: "npm" }>;
+  /** The sanctioned local component — `<repo-relative-file>#<exportName>`. */
+  localComponentKey: string;
+}
+
+/**
+ * The per-component bindings an authored bridge set implies — one definition,
+ * because every consumer of "which components did the user sanction, against
+ * which package export" must see the same set.
+ *
+ * Consumed by `classify`'s RENDER_ROOT_CANONICAL context, which gates the
+ * signal on `localComponentKey`: only the component the bridge names may claim
+ * the bridge's canonical, so a sanction stays as narrow as the user authored it.
+ */
+export function canonicalBridgeIdentityBindings(
+  bridges: readonly CanonicalBridgeV1[] | undefined
+): CanonicalBridgeIdentityBinding[] {
+  return (bridges ?? []).map((bridge) => ({
+    source: {
+      kind: "npm",
+      specifier: bridge.underlying.packageName,
+      include: [bridge.underlying.exportName],
+    },
+    localComponentKey: bridge.local.componentKey,
+  }));
+}
+
+/**
+ * The npm canonical sources an authored bridge set implies — the source half of
+ * `canonicalBridgeIdentityBindings`, for consumers that resolve the whole tree
+ * at once and scope the result themselves.
+ *
+ * A bridge states that `underlying.packageName#exportName` IS the canonical
+ * thing a local component wraps, so identity resolution treats that export as
+ * declared, exactly as an explicit `govern.canonicalSources` npm entry would.
+ * Before this projection was shared, a repo whose decision lived only in
+ * `canonicalBridges` (hand-authored, or written by `identity sanction`)
+ * resolved render roots at `canonical` grade in the pipeline while the
+ * classifier saw no declaration at all — the authored fact reached one consumer
+ * and silently missed the other.
+ *
+ * Consumer: the scan pipeline's identity input
+ * (`buildCanonicalDirectionIdentityInput`), which resolves render roots for the
+ * whole definition set and reports the grade rather than acting on it.
+ * Anything that turns the grade into an AUTHORED decision must use
+ * `canonicalBridgeIdentityBindings` instead — this projection deliberately
+ * drops `local.componentKey`, so on its own it cannot tell a sanctioned wrapper
+ * from any other component that renders the same export.
+ */
+export function canonicalBridgeIdentitySources(
+  bridges: readonly CanonicalBridgeV1[] | undefined
+): Array<Extract<CanonicalSource, { kind: "npm" }>> {
+  return canonicalBridgeIdentityBindings(bridges).map((binding) => binding.source);
+}
+
 export function canonicalBridgeMatchesUnderlyingImport(
   bridge: CanonicalBridgeV1,
   source: string,

package/src/canonical-direction.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+
+import { FactIndex, makeComponentDefinitionFact } from "./facts/index.js";
+import type { ComponentDefinitionRenderRoot } from "./facts/index.js";
+import { projectCanonicalDirectionConflicts } from "./canonical-direction.js";
+
+const NPM_SOURCE = {
+  kind: "npm",
+  specifier: "@mui/material",
+  include: ["Button", "TextField"],
+} as const;
+
+function wrapperDefinition(input: {
+  file: string;
+  exportName: string;
+  renderRoot: ComponentDefinitionRenderRoot;
+  exported?: boolean;
+}) {
+  return makeComponentDefinitionFact({
+    file: input.file,
+    exportName: input.exportName,
+    exported: input.exported ?? true,
+    componentKey: `${input.file}#${input.exportName}`,
+    renderRoot: input.renderRoot,
+    propSurface: [],
+  });
+}
+
+describe("projectCanonicalDirectionConflicts", () => {
+  it("projects a conflict from a package-identity canonical key", () => {
+    const ix = new FactIndex();
+    ix.add(
+      wrapperDefinition({
+        file: "src/components/Button.tsx",
+        exportName: "Button",
+        renderRoot: {
+          resolution: "canonical",
+          canonical: "@mui/material#Button",
+          importSource: "@mui/material",
+        },
+      })
+    );
+
+    expect(projectCanonicalDirectionConflicts(ix, [NPM_SOURCE])).toMatchObject([
+      {
+        packageName: "@mui/material",
+        exportName: "Button",
+        wrapperComponentKey: "src/components/Button.tsx#Button",
+        state: "unresolved",
+      },
+    ]);
+  });
+
+  // A canonical package vendored inside the repo (a workspace package or the
+  // committed archetype fixture's fake-packages/) resolves the wrapper's render
+  // root to its local file identity. The original import specifier is still
+  // exact and source-backed — the conflict must not vanish when resolution
+  // goes local, or init detects an ambiguity the scan can never see.
+  it("projects a conflict through the import source when the canonical key resolved locally", () => {
+    const ix = new FactIndex();
+    ix.add(
+      wrapperDefinition({
+        file: "src/components/Button.tsx",
+        exportName: "Button",
+        renderRoot: {
+          resolution: "canonical",
+          canonical: "fake-packages/mui-material/index.js#Button",
+          importSource: "@mui/material",
+        },
+      })
+    );
+
+    expect(projectCanonicalDirectionConflicts(ix, [NPM_SOURCE])).toMatchObject([
+      {
+        packageName: "@mui/material",
+        exportName: "Button",
+        wrapperComponentKey: "src/components/Button.tsx#Button",
+        wrapperFile: "src/components/Button.tsx",
+        wrapperExportName: "Button",
+        state: "unresolved",
+      },
+    ]);
+  });
+
+  it("ignores locally-resolved roots whose import source is not a canonical package", () => {
+    const ix = new FactIndex();
+    ix.add(
+      wrapperDefinition({
+        file: "src/components/Button.tsx",
+        exportName: "Button",
+        renderRoot: {
+          resolution: "canonical",
+          canonical: "packages/other-kit/index.ts#Button",
+          importSource: "@acme/other-kit",
+        },
+      })
+    );
+
+    expect(projectCanonicalDirectionConflicts(ix, [NPM_SOURCE])).toEqual([]);
+  });
+
+  it("honors the include list on the import-source fallback", () => {
+    const ix = new FactIndex();
+    ix.add(
+      wrapperDefinition({
+        file: "src/components/Chip.tsx",
+        exportName: "Chip",
+        renderRoot: {
+          resolution: "canonical",
+          canonical: "fake-packages/mui-material/index.js#Chip",
+          importSource: "@mui/material",
+        },
+      })
+    );
+
+    expect(projectCanonicalDirectionConflicts(ix, [NPM_SOURCE])).toEqual([]);
+  });
+});

package/src/canonical-direction.ts

@@ -1,7 +1,9 @@
 import type { CanonicalSource } from "./governance.js";
-import type { FactIndex } from "./facts/index.js";
+import type { ComponentDefinitionRenderRoot, FactIndex } from "./facts/index.js";
 import { ownedImportMatchesRoot } from "./package-identity-match.js";
 
+type CanonicalRenderRoot = Extract<ComponentDefinitionRenderRoot, { resolution: "canonical" }>;
+
 export interface CanonicalDirectionConflict {
   packageName: string;
   exportName: string;
@@ -32,7 +34,7 @@ export function projectCanonicalDirectionConflicts(
 
   for (const definition of ix.byKind("component_definition")) {
     if (!definition.exported || definition.renderRoot.resolution !== "canonical") continue;
-    const target = npmTarget(definition.renderRoot.canonical, npmSources);
+    const target = npmTarget(definition.renderRoot, npmSources);
     if (!target) continue;
 
     const identity = identityByComponent.get(definition.componentKey);
@@ -83,6 +85,16 @@ export function canonicalDirectionConflictsTarget(
 }
 
 function npmTarget(
+  renderRoot: CanonicalRenderRoot,
+  sources: readonly Extract<CanonicalSource, { kind: "npm" }>[]
+): { packageName: string; exportName: string } | null {
+  return (
+    npmTargetFromCanonicalKey(renderRoot.canonical, sources) ??
+    npmTargetFromImportSource(renderRoot, sources)
+  );
+}
+
+function npmTargetFromCanonicalKey(
   canonicalTarget: string,
   sources: readonly Extract<CanonicalSource, { kind: "npm" }>[]
 ): { packageName: string; exportName: string } | null {
@@ -108,6 +120,35 @@ function npmTarget(
   return null;
 }
 
+/**
+ * A canonical package that also lives in the repo (a vendored fixture package
+ * or a workspace package whose package.json name matches the specifier)
+ * resolves to its local file identity, so the canonical key carries no package
+ * name. The original import specifier still does — and it is just as exact and
+ * source-backed, so the conflict must not vanish when resolution goes local
+ * (init's detector sees it; the scan must see the same set).
+ */
+function npmTargetFromImportSource(
+  renderRoot: CanonicalRenderRoot,
+  sources: readonly Extract<CanonicalSource, { kind: "npm" }>[]
+): { packageName: string; exportName: string } | null {
+  const separator = renderRoot.canonical.lastIndexOf("#");
+  if (separator <= 0 || separator === renderRoot.canonical.length - 1) return null;
+  const exportName = renderRoot.canonical
+    .slice(separator + 1)
+    .split(".")
+    .at(-1);
+  if (!exportName || exportName === "default") return null;
+
+  for (const source of sources) {
+    if (!ownedImportMatchesRoot(renderRoot.importSource, source.specifier)) continue;
+    if (source.exclude?.includes(exportName)) continue;
+    if (source.include && !source.include.includes(exportName)) continue;
+    return { packageName: source.specifier, exportName };
+  }
+  return null;
+}
+
 function packageSubpath(importPath: string, packageName: string): string {
   return importPath === packageName ? "" : importPath.slice(packageName.length + 1);
 }

package/src/codes/__tests__/codes.test.ts

@@ -11,7 +11,20 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const registryPath = path.resolve(__dirname, "../../../../../docs/codes/registry.json");
 
-const SUBSYSTEM_EMITTED_CODES = ["FUI9001", "FUI9002", "FUI9003", "FUI9004", "FUI9005"] as const;
+const SUBSYSTEM_EMITTED_CODES = [
+  "FUI9001",
+  "FUI9002",
+  "FUI9003",
+  "FUI9004",
+  "FUI9005",
+  "FUI9006",
+  "FUI9007",
+  "FUI9008",
+  // Emitted by the CLI scan layer, not the rule engine: the contract's token
+  // sources are read before any rule runs, and an unreadable one aborts the
+  // scan rather than producing a finding.
+  "FUI9009",
+] as const;
 
 const RESERVED_CODES = {
   FUI1001: "Reserved for canonical primitive findings; no core rule emits it.",
@@ -20,7 +33,6 @@ const RESERVED_CODES = {
   FUI2001: "Reserved for generic design-token requirements; no core rule emits it.",
   FUI2002: "Reserved for token-prefix policy; no core rule emits it.",
   FUI2013: "Reserved for brand-seed enforcement; no core rule emits it.",
-  FUI3002: "Reserved for general accessibility standards; no core rule emits it.",
   FUI5001: "Reserved for required-child composition; no core rule emits it.",
   FUI5002: "Deprecated canonical-composition alias; no active core rule emits it.",
   FUI6001: "Reserved for generic unknown props; no core rule emits it.",

package/src/codes/codes.ts

@@ -282,14 +282,13 @@ export const CODES = [
     lifecycle: "experimental",
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI3002",
     ruleId: "a11y/standard",
     category: "a11y",
     defaultSeverity: "serious",
     title: "Accessibility standard failed",
     lifecycle: "experimental",
-    fixAvailable: false,
     evidenceRequired: true,
   }),
   code({
@@ -488,6 +487,46 @@ export const CODES = [
     fixAvailable: false,
     evidenceRequired: false,
   }),
+  code({
+    code: "FUI9006",
+    ruleId: "config/unmatched-exclude",
+    category: "system",
+    defaultSeverity: "moderate",
+    title: "Rule exclude matched no scanned file",
+    lifecycle: "experimental",
+    fixAvailable: false,
+    evidenceRequired: false,
+  }),
+  code({
+    code: "FUI9007",
+    ruleId: "config/colliding-record",
+    category: "system",
+    defaultSeverity: "moderate",
+    title: "Governance record was dropped as a duplicate",
+    lifecycle: "experimental",
+    fixAvailable: false,
+    evidenceRequired: false,
+  }),
+  code({
+    code: "FUI9008",
+    ruleId: "config/overridden-record-severity",
+    category: "system",
+    defaultSeverity: "moderate",
+    title: "Rule override outranks a record's authored severity",
+    lifecycle: "experimental",
+    fixAvailable: false,
+    evidenceRequired: false,
+  }),
+  code({
+    code: "FUI9009",
+    ruleId: "contract/unreadable-token-source",
+    category: "system",
+    defaultSeverity: "critical",
+    title: "Contract token source cannot be read",
+    lifecycle: "experimental",
+    fixAvailable: false,
+    evidenceRequired: false,
+  }),
 ] as const satisfies readonly FuiCode[];
 
 export const byCode: ReadonlyMap<string, FuiCode> = new Map(

package/src/compiled-types/index.ts

@@ -267,6 +267,87 @@ export interface CompiledFragmentsFile {
   recipes?: Record<string, CompiledBlock>;
 }
 
+export class CompiledFragmentsFileValidationError extends Error {
+  constructor(
+    readonly source: string,
+    readonly issues: string[]
+  ) {
+    super(`Invalid compiled Fragments catalog at ${source}: ${issues.join("; ")}`);
+    this.name = "CompiledFragmentsFileValidationError";
+  }
+}
+
+export function parseCompiledFragmentsFile(
+  input: string | unknown,
+  source = "fragments.json"
+): CompiledFragmentsFile {
+  let value: unknown = input;
+  if (typeof input === "string") {
+    try {
+      value = JSON.parse(input);
+    } catch (error) {
+      throw new CompiledFragmentsFileValidationError(source, [
+        `invalid JSON (${error instanceof Error ? error.message : String(error)})`,
+      ]);
+    }
+  }
+
+  const issues: string[] = [];
+  if (!isRecord(value)) {
+    throw new CompiledFragmentsFileValidationError(source, ["root must be an object"]);
+  }
+  if (typeof value.version !== "string" || value.version.length === 0) {
+    issues.push("version must be a non-empty string");
+  }
+  if (typeof value.generatedAt !== "string" || value.generatedAt.length === 0) {
+    issues.push("generatedAt must be a non-empty string");
+  }
+  if (!isRecord(value.fragments)) {
+    issues.push("fragments must be an object");
+  } else {
+    for (const [key, fragment] of Object.entries(value.fragments)) {
+      validateCompiledFragment(key, fragment, issues);
+    }
+  }
+  if (value.graph !== undefined) {
+    if (
+      !isRecord(value.graph) ||
+      !Array.isArray(value.graph.nodes) ||
+      !Array.isArray(value.graph.edges) ||
+      !isRecord(value.graph.health)
+    ) {
+      issues.push("graph must contain nodes[], edges[], and health");
+    }
+  }
+  if (issues.length > 0) throw new CompiledFragmentsFileValidationError(source, issues);
+  return value as unknown as CompiledFragmentsFile;
+}
+
+function validateCompiledFragment(key: string, value: unknown, issues: string[]): void {
+  const path = `fragments.${key}`;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  if (typeof value.filePath !== "string") issues.push(`${path}.filePath must be a string`);
+  if (!isRecord(value.meta) || typeof value.meta.name !== "string") {
+    issues.push(`${path}.meta.name must be a string`);
+  }
+  if (!isRecord(value.props)) issues.push(`${path}.props must be an object`);
+  if (!Array.isArray(value.variants)) issues.push(`${path}.variants must be an array`);
+  if (
+    !isRecord(value.usage) ||
+    !Array.isArray(value.usage.when) ||
+    !Array.isArray(value.usage.whenNot)
+  ) {
+    issues.push(`${path}.usage must contain when[] and whenNot[]`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
 /**
  * Theme identifier
  */

package/src/compiled-types/parse.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  CompiledFragmentsFileValidationError,
+  parseCompiledFragmentsFile,
+} from "./index.js";
+
+const validCatalog = {
+  version: "1.0.0",
+  generatedAt: "2026-07-28T00:00:00.000Z",
+  fragments: {
+    Button: {
+      filePath: "src/Button.fragment.ts",
+      meta: { name: "Button", description: "Action", category: "Actions" },
+      usage: { when: ["Actions"], whenNot: [] },
+      props: {},
+      variants: [],
+    },
+  },
+};
+
+describe("parseCompiledFragmentsFile", () => {
+  it("accepts a compiled catalog with the command-critical shape", () => {
+    expect(parseCompiledFragmentsFile(JSON.stringify(validCatalog))).toMatchObject(validCatalog);
+  });
+
+  it("reports invalid fragment paths instead of allowing command-specific crashes", () => {
+    expect(() =>
+      parseCompiledFragmentsFile(
+        {
+          ...validCatalog,
+          fragments: { Button: { meta: {}, variants: "bad" } },
+        },
+        "/repo/fragments.json"
+      )
+    ).toThrow(CompiledFragmentsFileValidationError);
+    expect(() =>
+      parseCompiledFragmentsFile(
+        {
+          ...validCatalog,
+          fragments: { Button: { meta: {}, variants: "bad" } },
+        },
+        "/repo/fragments.json"
+      )
+    ).toThrow("fragments.Button.meta.name");
+  });
+});