@usefragments/core 1.5.2 → 1.6.0

package/dist/react-types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType, ReactNode, JSX } from 'react';
-export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-pKrfh517.js';
+export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-DxFipN5V.js';
 import 'zod';
 import './topology/index.js';
 import './types-xJ2xyp_G.js';

package/dist/test-utils.d.ts

@@ -1,4 +1,4 @@
-import { C as CompiledBlock, b as CompiledFragment } from './governance-pKrfh517.js';
+import { C as CompiledBlock, b as CompiledFragment } from './governance-DxFipN5V.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/core",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "license": "MIT",
   "description": "Core types, schemas, and runtime API for Fragments component definitions",
   "author": "Conan McNicholl",

package/src/__tests__/policy-exclude.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  describePolicyExclude,
+  detectUnmatchedPolicyExcludes,
+  governanceConfigSchema,
+  matchPolicyExclude,
+  normalizePolicyExcludes,
+  type GovernanceConfig,
+} from "../index.js";
+
+describe("policy exclude normalization", () => {
+  it("accepts bare globs and { glob, reason } records alike", () => {
+    expect(
+      normalizePolicyExcludes([
+        "src/legacy/**",
+        { glob: "vendor/**", reason: "vendor drop, tracked in DS-611" },
+      ])
+    ).toEqual([
+      { glob: "src/legacy/**" },
+      { glob: "vendor/**", reason: "vendor drop, tracked in DS-611" },
+    ]);
+  });
+
+  it("returns undefined when nothing usable is authored", () => {
+    expect(normalizePolicyExcludes(undefined)).toBeUndefined();
+    expect(normalizePolicyExcludes([])).toBeUndefined();
+    expect(normalizePolicyExcludes(["", { reason: "no glob" }, 7])).toBeUndefined();
+  });
+
+  it("matches `**` across segments and `*` within one", () => {
+    const excludes = normalizePolicyExcludes(["src/legacy/vendor/**", "src/*.tsx"]);
+
+    expect(matchPolicyExclude(excludes, "src/legacy/vendor/deep/Widget.tsx")).toEqual({
+      glob: "src/legacy/vendor/**",
+    });
+    expect(matchPolicyExclude(excludes, "./src/App.tsx")).toEqual({ glob: "src/*.tsx" });
+    expect(matchPolicyExclude(excludes, "src\\App.tsx")).toEqual({ glob: "src/*.tsx" });
+    expect(matchPolicyExclude(excludes, "src/nested/App.tsx")).toBeUndefined();
+    expect(matchPolicyExclude(undefined, "src/App.tsx")).toBeUndefined();
+  });
+
+  it("describes an exclusion with its scope, glob, and reason", () => {
+    expect(
+      describePolicyExclude("style.rawColors.forbid", {
+        glob: "vendor/**",
+        reason: "vendor drop",
+      })
+    ).toBe("style.rawColors.forbid exclude matched vendor/** — vendor drop");
+    expect(describePolicyExclude("styles/no-raw-color", { glob: "vendor/**" })).toBe(
+      "styles/no-raw-color exclude matched vendor/**"
+    );
+  });
+});
+
+describe("global record excludes compile onto policy facts", () => {
+  const policy: GovernanceConfig = {
+    styles: [
+      {
+        kind: "style.rawColors.forbid",
+        except: [],
+        prefer: "token",
+        severity: "warn",
+        exclude: [{ glob: "src/legacy/vendor/**", reason: "vendor drop" }],
+      },
+    ],
+    jsx: [
+      {
+        kind: "jsx.importPath.prefer",
+        from: "@mui/material",
+        to: "@/components",
+        severity: "warn",
+        exclude: ["src/legacy/vendor/**"],
+      },
+    ],
+  };
+
+  it("is accepted by the shipped schema", () => {
+    expect(() => governanceConfigSchema.parse(policy)).not.toThrow();
+  });
+
+  it("threads the normalized excludes onto the compiled facts", () => {
+    const facts = compileGlobalGovernanceFacts(policy);
+    const color = facts.find((fact) => fact.kind === "style_raw_color_forbidden");
+    const importPath = facts.find((fact) => fact.kind === "jsx_import_path_preferred");
+
+    expect(color).toMatchObject({
+      exclude: [{ glob: "src/legacy/vendor/**", reason: "vendor drop" }],
+    });
+    expect(importPath).toMatchObject({ exclude: [{ glob: "src/legacy/vendor/**" }] });
+  });
+
+  it("keeps a user exclude alive when a preset record shares the same fact id", () => {
+    // A resolved policy is `[...presetRecords, ...userRecords]`, and the singleton style
+    // kinds are content-addressed on kind alone — so only one of the two survives
+    // indexing. The user's exemption must not be the casualty.
+    const facts = compileGlobalGovernanceFacts({
+      styles: [
+        { kind: "style.rawColors.forbid", except: [], prefer: "token", severity: "warn" },
+        {
+          kind: "style.rawColors.forbid",
+          except: [],
+          prefer: "token",
+          severity: "warn",
+          exclude: ["src/legacy/vendor/**"],
+        },
+      ],
+    });
+
+    const colorFacts = facts.filter((fact) => fact.kind === "style_raw_color_forbidden");
+    expect(colorFacts).toHaveLength(2);
+    // Both copies carry the union, so whichever the index keeps is the armed one.
+    for (const fact of colorFacts) {
+      expect(fact).toMatchObject({ exclude: [{ glob: "src/legacy/vendor/**" }] });
+    }
+  });
+
+  it("leaves fact identity untouched so fingerprints do not move", () => {
+    const withExclude = compileGlobalGovernanceFacts(policy);
+    const withoutExclude = compileGlobalGovernanceFacts({
+      styles: [{ kind: "style.rawColors.forbid", except: [], prefer: "token", severity: "warn" }],
+      jsx: [
+        {
+          kind: "jsx.importPath.prefer",
+          from: "@mui/material",
+          to: "@/components",
+          severity: "warn",
+        },
+      ],
+    });
+
+    expect(withExclude.map((fact) => fact.id)).toEqual(withoutExclude.map((fact) => fact.id));
+    // …and a policy with no excludes stays byte-identical to the pre-1.6.0 shape.
+    expect(withoutExclude.every((fact) => !("exclude" in fact))).toBe(true);
+  });
+});
+
+describe("detectUnmatchedPolicyExcludes", () => {
+  const policy: GovernanceConfig = {
+    styles: [
+      {
+        kind: "style.rawColors.forbid",
+        except: [],
+        prefer: "token",
+        severity: "warn",
+        exclude: ["src/legacy/vendor/**"],
+      },
+    ],
+    rules: { "styles/no-raw-spacing": { exclude: ["src/deleted-area/**"] } },
+  };
+
+  it("stays silent when every glob covers a scanned file", () => {
+    expect(
+      detectUnmatchedPolicyExcludes(policy, [
+        "src/legacy/vendor/Widget.tsx",
+        "src/deleted-area/Old.tsx",
+      ])
+    ).toEqual([]);
+  });
+
+  it("names each glob that scoped nothing, on both authoring routes", () => {
+    const diagnostics = detectUnmatchedPolicyExcludes(policy, ["src/App.tsx"]);
+
+    expect(diagnostics).toMatchObject([
+      {
+        code: "FUI9006",
+        kind: "unmatched-exclude",
+        path: "govern.rules.styles/no-raw-spacing.exclude",
+      },
+      { code: "FUI9006", kind: "unmatched-exclude", path: "govern.styles[0].exclude" },
+    ]);
+    expect(diagnostics[0]?.message).toContain("src/deleted-area/**");
+    expect(diagnostics[1]?.message).toContain("style.rawColors.forbid");
+  });
+
+  it("does not flag excludes when nothing was scanned at all", () => {
+    expect(detectUnmatchedPolicyExcludes(policy, [])).toEqual([]);
+  });
+});

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.",

package/src/codes/codes.ts

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