@usefragments/core 2.0.0 → 2.0.1

package/dist/schemas/index.js

@@ -24,7 +24,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "../chunk-BMPYIUZE.js";
+} from "../chunk-QPOKQ5H6.js";
 import "../chunk-EIYNNS77.js";
 import "../chunk-PWIJMOI4.js";
 import "../chunk-JNBFJ34I.js";

package/package.json

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

package/src/canonical-source.ts

@@ -0,0 +1,41 @@
+import type { CanonicalSource } from "./governance.js";
+
+/** Export filters narrow source ownership; an empty include approves nothing. */
+export function canonicalSourceIncludesExport(source: CanonicalSource, name: string): boolean {
+  const role = name.split(".").at(-1) ?? name;
+  const matches = (names: readonly string[]) => names.includes(name) || names.includes(role);
+  return (
+    !matches(source.exclude ?? []) && (source.include === undefined || matches(source.include))
+  );
+}
+
+/** Filesystem ownership only. Package import specifiers are not local paths. */
+export function canonicalSourceContainsFile(source: CanonicalSource, file: string): boolean {
+  const root =
+    source.kind === "directory"
+      ? source.path
+      : source.kind === "registry"
+        ? source.installPath
+        : source.implementationPath;
+  if (!root) return false;
+  const normalize = (value: string) =>
+    value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+  const normalizedRoot = normalize(root);
+  const normalizedFile = normalize(file);
+  return (
+    normalizedRoot === "." ||
+    normalizedFile === normalizedRoot ||
+    normalizedFile.startsWith(`${normalizedRoot}/`)
+  );
+}
+
+export function isCanonicalSourceDefinition(
+  file: string,
+  exportName: string,
+  sources: readonly CanonicalSource[]
+): boolean {
+  return sources.some(
+    (source) =>
+      canonicalSourceContainsFile(source, file) && canonicalSourceIncludesExport(source, exportName)
+  );
+}

package/src/facts/builders.ts

@@ -122,6 +122,7 @@ export function makeComponentDefinitionFact(input: {
   componentKey: string;
   renderRoot: ComponentDefinitionFact["renderRoot"];
   propSurface: string[];
+  location?: FactLocation;
   stylingChannel?: ComponentDefinitionFact["stylingChannel"];
 }): ComponentDefinitionFact {
   return {
@@ -134,6 +135,7 @@ export function makeComponentDefinitionFact(input: {
     componentKey: input.componentKey,
     renderRoot: input.renderRoot,
     propSurface: [...input.propSurface],
+    ...(input.location ? { location: { ...input.location } } : {}),
     ...(input.stylingChannel ? { stylingChannel: { ...input.stylingChannel } } : {}),
   };
 }
@@ -664,6 +666,7 @@ export function makeUsageNodeFact(input: {
 export function makeUsageComponentFact(input: {
   nodeId: FactId;
   componentId: ComponentId;
+  definitionKey?: string;
 }): UsageComponentFact {
   return {
     id: factId("usage_component", {
@@ -673,6 +676,7 @@ export function makeUsageComponentFact(input: {
     kind: "usage_component",
     nodeId: input.nodeId,
     componentId: input.componentId,
+    ...(input.definitionKey ? { definitionKey: input.definitionKey } : {}),
   };
 }
 

package/src/facts/fact-index.ts

@@ -87,6 +87,10 @@ function logicalFactForComparison(fact: Fact): Record<string, unknown> {
     const { location: _location, sourceNames: _sourceNames, ...logicalFact } = fact;
     return logicalFact;
   }
+  if (fact.kind === "component_definition") {
+    const { location: _location, ...logicalFact } = fact;
+    return { ...logicalFact, componentId: logicalComponentId(fact.componentId) };
+  }
   if (fact.kind === "jsx_import_path_preferred") {
     return {
       ...fact,

package/src/facts/facts.test.ts

@@ -549,6 +549,76 @@ describe("FactIndex — query layer", () => {
     expect(ix.get(first.id)).toEqual(first);
   });
 
+  it.each(["missing-first", "missing-second", "moved"] as const)(
+    "coalesces component definitions when only their evidence region differs (%s)",
+    (mode) => {
+      const onConflict = vi.fn();
+      const onDuplicate = vi.fn();
+      const ix = new FactIndex({ onConflict, onDuplicate });
+      const definition = {
+        file: "src/Button.tsx",
+        exportName: "Button",
+        exported: true,
+        componentKey: "src/Button.tsx#Button",
+        renderRoot: { resolution: "intrinsic", tag: "button" } as const,
+        propSurface: ["disabled"],
+      };
+      const first = makeComponentDefinitionFact({
+        ...definition,
+        ...(mode !== "missing-first"
+          ? { location: { file: definition.file, line: 2, column: 0, endLine: 4, endColumn: 1 } }
+          : {}),
+      });
+      const second = makeComponentDefinitionFact({
+        ...definition,
+        ...(mode !== "missing-second"
+          ? { location: { file: definition.file, line: 6, column: 0, endLine: 8, endColumn: 1 } }
+          : {}),
+      });
+
+      ix.addMany([first, second]);
+
+      expect(onConflict).not.toHaveBeenCalled();
+      expect(onDuplicate).toHaveBeenCalledTimes(1);
+      expect(onDuplicate).toHaveBeenCalledWith({ kept: first, duplicate: second });
+      expect(ix.byKind("component_definition")).toEqual([first]);
+    }
+  );
+
+  it.each([
+    { renderRoot: { resolution: "intrinsic", tag: "a" } as const },
+    { propSurface: ["disabled", "href"] },
+    { exported: false },
+  ])("retains component-definition conflicts for material changes: %j", (change) => {
+    const onConflict = vi.fn();
+    const onDuplicate = vi.fn();
+    const ix = new FactIndex({ onConflict, onDuplicate });
+    const definition = {
+      file: "src/Button.tsx",
+      exportName: "Button",
+      exported: true,
+      componentKey: "src/Button.tsx#Button",
+      renderRoot: { resolution: "intrinsic", tag: "button" } as const,
+      propSurface: ["disabled"],
+    };
+    const first = makeComponentDefinitionFact(definition);
+    const second = makeComponentDefinitionFact({
+      ...definition,
+      ...change,
+      location: { file: definition.file, line: 2, column: 0, endLine: 4, endColumn: 1 },
+    });
+
+    ix.addMany([first, second]);
+
+    expect(onConflict).toHaveBeenCalledTimes(1);
+    expect(onConflict).toHaveBeenCalledWith(expect.stringContaining("conflicting facts"), {
+      kept: first,
+      skipped: second,
+    });
+    expect(onDuplicate).not.toHaveBeenCalled();
+    expect(ix.byKind("component_definition")).toEqual([first]);
+  });
+
   it("includes token-definition provenance in logical conflict reports", () => {
     const onConflict = vi.fn();
     const ix = new FactIndex({ onConflict });

package/src/facts/types.ts

@@ -317,6 +317,8 @@ export interface UsageComponentFact extends BaseFact {
   kind: "usage_component";
   nodeId: FactId;
   componentId: ComponentId;
+  /** Exact local definition resolved from source, separate from catalog/policy identity. */
+  definitionKey?: string;
 }
 
 export interface UsageImportFact extends BaseFact {
@@ -688,6 +690,8 @@ export interface ComponentDefinitionFact extends BaseFact {
   componentKey: string;
   renderRoot: ComponentDefinitionRenderRoot;
   propSurface: string[];
+  /** Implementation region, used to scope exemptions; never part of fact identity. */
+  location?: FactLocation;
   stylingChannel?: {
     module: string;
     ownsVisualRole: boolean;

package/src/identity/usage.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import {
+  FactIndex,
+  asComponentId,
+  makeComponentDefinitionFact,
+  makeUsageComponentFact,
+  makeUsageNodeFact,
+} from "../index.js";
+import { indexComponentIdentityUsage } from "./usage.js";
+
+describe("component identity usage joins", () => {
+  const key = "src/Button.tsx#Button";
+  const catalogId = asComponentId("cloud:source#source::src/Button.tsx::Button");
+
+  it("preserves fact identity and counts a node once with exact definition evidence", () => {
+    const ix = new FactIndex();
+    const node = makeUsageNodeFact({
+      file: "src/App.tsx",
+      nodePath: "0:0",
+      element: "Button",
+      location: { file: "src/App.tsx", line: 1, column: 0 },
+    });
+    const original = makeUsageComponentFact({ nodeId: node.id, componentId: catalogId });
+    const resolved = makeUsageComponentFact({
+      nodeId: node.id,
+      componentId: catalogId,
+      definitionKey: key,
+    });
+    expect(resolved.id).toBe(original.id);
+    ix.addMany([
+      node,
+      resolved,
+      makeUsageComponentFact({ nodeId: node.id, componentId: asComponentId(key) }),
+      makeComponentDefinitionFact({
+        file: "src/Button.tsx",
+        exportName: "Button",
+        componentKey: key,
+        propSurface: [],
+        renderRoot: { resolution: "intrinsic", tag: "button" },
+      }),
+    ]);
+    expect(indexComponentIdentityUsage(ix).get(key)).toMatchObject({
+      usageCount: 1,
+      blastRadius: 1,
+    });
+    expect(indexComponentIdentityUsage(ix).has(catalogId)).toBe(false);
+  });
+
+  it("does not synthesize a definition from catalog evidence", () => {
+    const ix = new FactIndex();
+    const node = makeUsageNodeFact({
+      file: "src/App.tsx",
+      nodePath: "0:0",
+      element: "Button",
+      location: { file: "src/App.tsx", line: 1, column: 0 },
+    });
+    ix.addMany([
+      node,
+      makeUsageComponentFact({ nodeId: node.id, componentId: catalogId, definitionKey: key }),
+    ]);
+    expect(indexComponentIdentityUsage(ix).has(key)).toBe(false);
+    expect(indexComponentIdentityUsage(ix).get(catalogId)?.usageCount).toBe(1);
+  });
+});

package/src/identity/usage.ts

@@ -12,12 +12,18 @@ export function indexComponentIdentityUsage(
   ix: FactIndex
 ): ReadonlyMap<string, ComponentIdentityUsage> {
   const nodesById = new Map(ix.byKind("usage_node").map((node) => [node.id, node]));
+  const definitions = new Set(
+    ix.byKind("component_definition").map((definition) => definition.componentKey)
+  );
   const nodesByComponent = new Map<string, Map<string, UsageNodeFact>>();
 
   for (const usage of ix.byKind("usage_component")) {
     const node = nodesById.get(usage.nodeId);
     if (!node) continue;
-    const componentKey = String(usage.componentId);
+    const componentKey =
+      usage.definitionKey && definitions.has(usage.definitionKey)
+        ? usage.definitionKey
+        : String(usage.componentId);
     const nodes = nodesByComponent.get(componentKey) ?? new Map<string, UsageNodeFact>();
     nodes.set(node.id, node);
     nodesByComponent.set(componentKey, nodes);

package/src/index.ts

@@ -684,6 +684,11 @@ export {
   type RuleConfigView,
 } from "./rules/rule-config.js";
 export { indexComponentIdentityUsage, type ComponentIdentityUsage } from "./identity/usage.js";
+export {
+  isCanonicalSourceDefinition,
+  canonicalSourceContainsFile,
+  canonicalSourceIncludesExport,
+} from "./canonical-source.js";
 export { nearestSignedScaleValue } from "./rules/utils.js";
 export {
   buildSpacingTokenLookup,

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

@@ -2,6 +2,8 @@ import type { CanonicalSource, GovernanceSeverity } from "../governance.js";
 import type {
   FactId,
   FactIndex,
+  ComponentDefinitionFact,
+  FactLocation,
   UsageImportFact,
   UsageNodeFact,
   UsagePropResolvedFact,
@@ -15,6 +17,8 @@ import {
   type RawHtmlPrecisionTier,
 } from "../raw-html-canonical.js";
 import { ownedImportMatchesRoot, ownedImportsEqual } from "../package-identity-match.js";
+import { indexComponentIdentityUsage } from "../identity/usage.js";
+import { canonicalSourceContainsFile, canonicalSourceIncludesExport } from "../canonical-source.js";
 import {
   canonicalDirectionConflictsTarget,
   projectCanonicalDirectionConflicts,
@@ -262,6 +266,13 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
   const configuredSources = canonicalSourcesFromPolicy(policy.options?.canonicalSources);
   const conflicts = projectCanonicalDirectionConflicts(ix, configuredSources);
   const sources = configuredSources.map((source) => suppressConflictedExports(source, conflicts));
+  const approvedLocalDefinitionKeys = Array.isArray(policy.options?.approvedLocalDefinitionKeys)
+    ? new Set(
+        policy.options.approvedLocalDefinitionKeys.filter(
+          (key): key is string => typeof key === "string"
+        )
+      )
+    : undefined;
   const mappings = canonicalMappingsFromPolicy(policy.options?.canonicalMappings).filter(
     (mapping) => !canonicalDirectionConflictsTarget(conflicts, mapping.importPath, mapping.name)
   );
@@ -278,16 +289,41 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
   // canonical primitives imported by a relative/`@/` path; a browser-safe string
   // comparison of the raw specifier could never recognize them, so the resolved
   // fact is the identity of record. Never flag them as import impostors.
-  const canonicalDirectoryResolvedNodes = indexCanonicalDirectoryResolvedNodes(ix, sources);
+  const canonicalDirectoryResolvedNodes = indexCanonicalDirectoryResolvedNodes(
+    ix,
+    sources,
+    approvedLocalDefinitionKeys
+  );
   const shadowRenderRootNodeIds =
     ix.policy.ruleConfig("components/shadow-component")?.enabled === true
       ? indexShadowRenderRootNodeIds(ix)
       : new Set<FactId>();
   const findings: Finding[] = [];
   const seenImportFixes = new Set<string>();
+  const canonicalIdentities = new Map(
+    ix
+      .byKind("component_identity")
+      .map((identity) => [identity.componentKey, identity.state === "canonical"])
+  );
+  const definitionsByFile = new Map<string, ComponentDefinitionFact[]>();
+  for (const definition of ix.byKind("component_definition")) {
+    const file = normalizePath(definition.file);
+    const definitions = definitionsByFile.get(file) ?? [];
+    definitions.push(definition);
+    definitionsByFile.set(file, definitions);
+  }
 
   for (const node of ix.byKind("usage_node")) {
-    if (isCanonicalSourceImplementationFile(node.file, sources)) continue;
+    if (
+      isCanonicalSourceImplementation(
+        node,
+        sources,
+        definitionsByFile,
+        canonicalIdentities,
+        approvedLocalDefinitionKeys
+      )
+    )
+      continue;
     if (node.element.includes(".")) continue;
     if (canonicalDirectoryResolvedNodes.has(node.id)) continue;
     if (shadowRenderRootNodeIds.has(node.id)) continue;
@@ -299,7 +335,17 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
       node.element === "input" ? readStaticStringProp(props, "type") : undefined;
     const mapped = findMapping(node, nodeInputType, mappings);
     if (mapped && imported && isMappedCanonicalImport(imported, mapped)) continue;
-    if (imported && isCanonicalImport(imported, node.element, sources)) continue;
+    if (
+      imported &&
+      isCanonicalImport(
+        imported,
+        node.element,
+        approvedLocalDefinitionKeys === undefined
+          ? sources
+          : sources.filter((source) => source.kind !== "directory")
+      )
+    )
+      continue;
 
     if (mapped) {
       if (!shouldSuggestMapped(node, nodeInputType, imported, mapped)) continue;
@@ -1154,22 +1200,34 @@ function canonicalImportPath(source: CanonicalSource): string | undefined {
  */
 function indexCanonicalDirectoryResolvedNodes(
   ix: FactIndex,
-  sources: readonly CanonicalSource[]
+  sources: readonly CanonicalSource[],
+  approvedLocalDefinitionKeys?: ReadonlySet<string>
 ): Set<FactId> {
   const out = new Set<FactId>();
-  const directoryPaths = sources
-    .filter(
-      (source): source is Extract<CanonicalSource, { kind: "directory" }> =>
-        source.kind === "directory"
-    )
-    .map((source) => normalizePath(source.path));
-  if (directoryPaths.length === 0) return out;
-  for (const fact of ix.byKind("usage_component")) {
-    const module = componentIdModule(fact.componentId);
+  const directorySources = sources.filter(
+    (source): source is Extract<CanonicalSource, { kind: "directory" }> =>
+      source.kind === "directory"
+  );
+  if (directorySources.length === 0) return out;
+  const identities = new Map(
+    ix.byKind("component_identity").map((identity) => [identity.componentKey, identity])
+  );
+  for (const [componentKey, usage] of indexComponentIdentityUsage(ix)) {
+    if (approvedLocalDefinitionKeys !== undefined && !approvedLocalDefinitionKeys.has(componentKey))
+      continue;
+    const identity = identities.get(componentKey);
+    if (identity && identity.state !== "canonical") continue;
+    const module = componentIdModule(componentKey);
     if (module === undefined) continue;
-    const normalizedModule = normalizePath(module);
-    if (directoryPaths.some((path) => isPathInSource(normalizedModule, path))) {
-      out.add(fact.nodeId);
+    const exportName = componentKey.slice(componentKey.indexOf("#") + 1);
+    if (
+      directorySources.some(
+        (source) =>
+          canonicalSourceContainsFile(source, module) &&
+          canonicalSourceIncludesExport(source, exportName)
+      )
+    ) {
+      for (const node of usage.nodes) out.add(node.id);
     }
   }
   return out;
@@ -1181,28 +1239,47 @@ function componentIdModule(componentId: string): string | undefined {
   return hash > 0 ? componentId.slice(0, hash) : undefined;
 }
 
-function isCanonicalSourceImplementationFile(
-  file: string,
-  sources: readonly CanonicalSource[]
+function isCanonicalSourceImplementation(
+  node: UsageNodeFact,
+  sources: readonly CanonicalSource[],
+  definitionsByFile: ReadonlyMap<string, readonly ComponentDefinitionFact[]>,
+  canonicalIdentities: ReadonlyMap<string, boolean>,
+  approvedLocalDefinitionKeys?: ReadonlySet<string>
 ): boolean {
-  const normalizedFile = normalizePath(file);
+  const definitions = definitionsByFile.get(normalizePath(node.file)) ?? [];
   return sources.some((source) => {
-    if (source.kind === "npm" && source.implementationPath) {
-      return isPathInSource(normalizedFile, source.implementationPath);
-    }
-    if (source.kind === "directory") {
-      return isPathInSource(normalizedFile, source.path);
-    }
-    if (source.kind === "registry") {
-      return isPathInSource(normalizedFile, source.installPath);
-    }
-    return false;
+    if (!canonicalSourceContainsFile(source, node.file)) return false;
+    // Legacy package/registry implementation roots declare file ownership;
+    // their export filters describe the public API. A frozen local inventory
+    // always narrows that ownership to exact approved definition regions.
+    if (
+      approvedLocalDefinitionKeys === undefined &&
+      (source.kind !== "directory" || (source.include === undefined && !source.exclude?.length))
+    )
+      return true;
+    const owners = definitions.filter(
+      (definition) => definition.location && locationContains(definition.location, node.location)
+    );
+    // Unlocated/ambiguous source cannot exempt arbitrary application code.
+    return (
+      owners.length > 0 &&
+      owners.every(
+        (definition) =>
+          (approvedLocalDefinitionKeys === undefined ||
+            approvedLocalDefinitionKeys.has(definition.componentKey)) &&
+          canonicalIdentities.get(definition.componentKey) !== false &&
+          canonicalSourceIncludesExport(source, definition.exportName)
+      )
+    );
   });
 }
 
-function isPathInSource(file: string, sourcePath: string): boolean {
-  const normalizedSource = normalizePath(sourcePath).replace(/\/$/, "");
-  return file === normalizedSource || file.startsWith(`${normalizedSource}/`);
+function locationContains(region: FactLocation, node: FactLocation): boolean {
+  if (region.endLine === undefined || region.endColumn === undefined) return false;
+  return (
+    (node.line > region.line || (node.line === region.line && node.column >= region.column)) &&
+    (node.line < region.endLine || (node.line === region.endLine && node.column < region.endColumn))
+  );
 }
 
 function normalizePath(path: string): string {