@usefragments/core 1.4.0 → 1.5.1

package/src/identity/classify.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+
+import { classifyIdentity, type ClassifyIdentityInput } from "./classify.js";
+
+const definition = {
+  componentKey: "src/MyButton.tsx#MyButton",
+  exportName: "MyButton",
+  canonical: false,
+};
+
+function classify(overrides: Partial<ClassifyIdentityInput>) {
+  return classifyIdentity({
+    definition,
+    renderRoot: { kind: "unresolved", reason: "test" },
+    ...overrides,
+  });
+}
+
+describe("classifyIdentity", () => {
+  it("gives canonical membership primary authority", () => {
+    expect(
+      classify({
+        definition: { ...definition, canonical: true },
+        renderRoot: { kind: "external", localName: "Primitive", source: "third-party" },
+      })
+    ).toEqual({ state: "canonical", confidence: "confirmed" });
+  });
+
+  it("keeps an undecided canonical-root wrapper at review confidence", () => {
+    expect(
+      classify({
+        renderRoot: {
+          kind: "canonical",
+          localName: "Button",
+          target: { componentKey: "packages/ui/Button.tsx#Button", role: "Button" },
+        },
+      })
+    ).toEqual({
+      state: "variant",
+      confidence: "review",
+      canonicalTarget: "packages/ui/Button.tsx#Button",
+    });
+  });
+
+  it("classifies an evidenced intrinsic only when the declared vocabulary has its role", () => {
+    expect(
+      classify({
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "button",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "exact-html",
+          canonicalTargets: [{ componentKey: "packages/ui/Button.tsx#Button", role: "Button" }],
+        },
+      })
+    ).toEqual({ state: "shadow", confidence: "confirmed", canonicalTarget: "Button" });
+
+    expect(
+      classify({
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "button",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "exact-html",
+          canonicalTargets: [],
+        },
+      })
+    ).toEqual({ state: "unresolved", confidence: "review" });
+  });
+
+  it("uses supporting evidence only to upgrade confidence", () => {
+    expect(
+      classify({
+        propSurfaceOverlap: 0.8,
+        stylingOwnership: "visual-role",
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "textarea",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "html-advisory",
+          canonicalTargets: [
+            { componentKey: "packages/ui/Textarea.tsx#Textarea", role: "Textarea" },
+          ],
+        },
+      })
+    ).toEqual({ state: "shadow", confidence: "confirmed", canonicalTarget: "Textarea" });
+
+    expect(
+      classify({
+        propSurfaceOverlap: 0.8,
+        stylingOwnership: "layout-only",
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "textarea",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "html-advisory",
+          canonicalTargets: [
+            { componentKey: "packages/ui/Textarea.tsx#Textarea", role: "Textarea" },
+          ],
+        },
+      })
+    ).toEqual({ state: "shadow", confidence: "likely", canonicalTarget: "Textarea" });
+  });
+
+  it("applies wrapper decisions as classification inputs", () => {
+    const renderRoot: ClassifyIdentityInput["renderRoot"] = {
+      kind: "canonical",
+      localName: "Button",
+      target: { componentKey: "packages/ui/Button.tsx#Button", role: "Button" },
+    };
+    expect(
+      classify({
+        renderRoot,
+        decisions: [{ componentKey: definition.componentKey, decision: "sanctioned-wrapper" }],
+      })
+    ).toEqual({
+      state: "variant",
+      confidence: "confirmed",
+      canonicalTarget: "packages/ui/Button.tsx#Button",
+    });
+    expect(
+      classify({
+        renderRoot,
+        decisions: [{ componentKey: definition.componentKey, decision: "rejected-wrapper" }],
+      })
+    ).toEqual({ state: "shadow", confidence: "confirmed", canonicalTarget: "Button" });
+  });
+
+  it("classifies canonical mixtures as composites", () => {
+    expect(
+      classify({
+        renderRoot: {
+          kind: "mixed",
+          canonicalTargets: [{ componentKey: "packages/ui/Card.tsx#Card", role: "Card" }],
+          localTargets: [
+            { componentKey: "src/UserAvatar.tsx#UserAvatar", exportName: "UserAvatar" },
+          ],
+          externalTargets: [],
+          intrinsics: [],
+          unresolvedNames: [],
+        },
+      })
+    ).toEqual({
+      state: "composite",
+      confidence: "confirmed",
+      canonicalTarget: "packages/ui/Card.tsx#Card",
+    });
+  });
+
+  it("distinguishes a canonical consumer from a pass-through wrapper", () => {
+    expect(
+      classify({
+        usageCounts: { staticTextChildren: 1 },
+        renderRoot: {
+          kind: "canonical",
+          localName: "Button",
+          target: { componentKey: "packages/ui/Button.tsx#Button", role: "Button" },
+        },
+      })
+    ).toEqual({
+      state: "composite",
+      confidence: "confirmed",
+      canonicalTarget: "packages/ui/Button.tsx#Button",
+    });
+  });
+
+  it("classifies third-party roots and keeps name similarity message-only", () => {
+    expect(
+      classify({
+        renderRoot: { kind: "external", localName: "Widget", source: "third-party" },
+      })
+    ).toEqual({ state: "external", confidence: "confirmed" });
+
+    expect(
+      classify({
+        nameSimilarityTargets: ["Card", "Button"],
+        renderRoot: { kind: "unresolved", reason: "dynamic factory" },
+      })
+    ).toEqual({ state: "unresolved", confidence: "review", canonicalTarget: "Button" });
+  });
+});

package/src/identity/classify.ts

@@ -0,0 +1,257 @@
+import type { RawHtmlPrecisionTier } from "../raw-html-canonical.js";
+
+export type IdentityState =
+  | "canonical"
+  | "variant"
+  | "shadow"
+  | "composite"
+  | "external"
+  | "unresolved";
+
+export type IdentityConfidence = "confirmed" | "likely" | "review";
+
+export interface CanonicalIdentityReference {
+  componentKey: string;
+  role: string;
+}
+
+export interface LocalIdentityReference {
+  componentKey: string;
+  exportName: string;
+}
+
+export interface ExternalIdentityReference {
+  localName: string;
+  source: string;
+}
+
+export interface ResolvedIntrinsicIdentityRoot {
+  kind: "intrinsic";
+  tag: string;
+  hasRole: boolean;
+  interactive: boolean;
+  role?: string;
+  inputType?: string;
+  precisionTier?: RawHtmlPrecisionTier;
+  canonicalTargets: readonly CanonicalIdentityReference[];
+}
+
+export type ResolvedIdentityRenderRoot =
+  | {
+      kind: "canonical";
+      localName: string;
+      target: CanonicalIdentityReference;
+    }
+  | ResolvedIntrinsicIdentityRoot
+  | {
+      kind: "external";
+      localName: string;
+      source: string;
+    }
+  | {
+      kind: "mixed";
+      canonicalTargets: readonly CanonicalIdentityReference[];
+      localTargets: readonly LocalIdentityReference[];
+      externalTargets: readonly ExternalIdentityReference[];
+      intrinsics: readonly ResolvedIntrinsicIdentityRoot[];
+      unresolvedNames: readonly string[];
+    }
+  | { kind: "unresolved"; reason: string };
+
+export interface IdentityDecision {
+  componentKey: string;
+  decision: "sanctioned-wrapper" | "rejected-wrapper";
+  canonicalTarget?: string;
+  decisionId?: string;
+}
+
+export interface ClassifyIdentityInput {
+  definition: {
+    componentKey: string;
+    exportName: string;
+    canonical: boolean;
+  };
+  renderRoot: ResolvedIdentityRenderRoot;
+  propSurfaceOverlap?: number;
+  stylingOwnership?: "visual-role" | "layout-only" | "none" | "unknown";
+  usageCounts?: {
+    importers?: number;
+    callSites?: number;
+    nestedElements?: number;
+    staticTextChildren?: number;
+  };
+  decisions?: readonly IdentityDecision[];
+  nameSimilarityTargets?: readonly string[];
+}
+
+export interface IdentityClassification {
+  state: IdentityState;
+  confidence: IdentityConfidence;
+  canonicalTarget?: string;
+}
+
+/**
+ * Classify already-resolved identity evidence. AST and filesystem concerns stay
+ * in the extractor; this function is deterministic and browser-safe.
+ */
+export function classifyIdentity(input: ClassifyIdentityInput): IdentityClassification {
+  const { definition, renderRoot } = input;
+  if (definition.canonical) return { state: "canonical", confidence: "confirmed" };
+
+  const decision = input.decisions?.find(
+    (candidate) => candidate.componentKey === definition.componentKey
+  );
+  if (decision?.decision === "sanctioned-wrapper") {
+    return withTarget("variant", "confirmed", decision.canonicalTarget ?? rootTarget(input));
+  }
+  if (decision?.decision === "rejected-wrapper") {
+    return withTarget("shadow", "confirmed", decision.canonicalTarget ?? shadowTarget(input));
+  }
+
+  if (renderRoot.kind === "canonical") {
+    if (
+      (input.usageCounts?.nestedElements ?? 0) > 0 ||
+      (input.usageCounts?.staticTextChildren ?? 0) > 0
+    ) {
+      return withTarget("composite", "confirmed", renderRoot.target.componentKey);
+    }
+    const confidence = strongOverlap(input.propSurfaceOverlap) ? "likely" : "review";
+    return withTarget("variant", confidence, renderRoot.target.componentKey);
+  }
+
+  if (renderRoot.kind === "intrinsic") {
+    return classifyIntrinsic(input, renderRoot);
+  }
+
+  if (renderRoot.kind === "mixed") {
+    if (renderRoot.canonicalTargets.length > 0) {
+      const target = bestCanonicalReference(
+        definition.exportName,
+        renderRoot.canonicalTargets
+      )?.componentKey;
+      const fullyResolved =
+        renderRoot.externalTargets.length === 0 && renderRoot.unresolvedNames.length === 0;
+      return withTarget("composite", fullyResolved ? "confirmed" : "likely", target);
+    }
+
+    if (
+      renderRoot.externalTargets.length > 0 &&
+      renderRoot.localTargets.length === 0 &&
+      renderRoot.unresolvedNames.length === 0
+    ) {
+      return { state: "external", confidence: "likely" };
+    }
+
+    return withTarget("unresolved", "review", rootTarget(input));
+  }
+
+  if (renderRoot.kind === "external") {
+    return { state: "external", confidence: "confirmed" };
+  }
+
+  return withTarget("unresolved", "review", rootTarget(input));
+}
+
+function classifyIntrinsic(
+  input: ClassifyIdentityInput,
+  root: ResolvedIntrinsicIdentityRoot
+): IdentityClassification {
+  const target = bestCanonicalReference(input.definition.exportName, root.canonicalTargets);
+  if (!target || (!root.interactive && !root.hasRole)) {
+    return withTarget("unresolved", "review", rootTarget(input));
+  }
+
+  let confidence: IdentityConfidence =
+    root.precisionTier === "exact-html" || root.precisionTier === "role-reimpl"
+      ? "confirmed"
+      : "likely";
+  if (
+    confidence === "likely" &&
+    input.stylingOwnership !== "layout-only" &&
+    (strongOverlap(input.propSurfaceOverlap) || input.stylingOwnership === "visual-role")
+  ) {
+    confidence = "confirmed";
+  }
+
+  return { state: "shadow", confidence, canonicalTarget: target.role };
+}
+
+function rootTarget(input: ClassifyIdentityInput): string | undefined {
+  const { renderRoot } = input;
+  if (renderRoot.kind === "canonical") return renderRoot.target.componentKey;
+  if (renderRoot.kind === "intrinsic") {
+    return bestCanonicalReference(input.definition.exportName, renderRoot.canonicalTargets)?.role;
+  }
+  if (renderRoot.kind === "mixed") {
+    return bestCanonicalReference(input.definition.exportName, renderRoot.canonicalTargets)
+      ?.componentKey;
+  }
+  return bestMessageTarget(input.definition.exportName, input.nameSimilarityTargets ?? []);
+}
+
+function shadowTarget(input: ClassifyIdentityInput): string | undefined {
+  const { renderRoot } = input;
+  if (renderRoot.kind === "canonical") return renderRoot.target.role;
+  if (renderRoot.kind === "intrinsic") {
+    return bestCanonicalReference(input.definition.exportName, renderRoot.canonicalTargets)?.role;
+  }
+  if (renderRoot.kind === "mixed") {
+    return bestCanonicalReference(input.definition.exportName, renderRoot.canonicalTargets)?.role;
+  }
+  return bestMessageTarget(input.definition.exportName, input.nameSimilarityTargets ?? []);
+}
+
+function bestCanonicalReference(
+  definitionName: string,
+  candidates: readonly CanonicalIdentityReference[]
+): CanonicalIdentityReference | undefined {
+  return [...candidates].sort(
+    (left, right) =>
+      nameSimilarityScore(definitionName, right.role) -
+        nameSimilarityScore(definitionName, left.role) ||
+      left.componentKey.localeCompare(right.componentKey)
+  )[0];
+}
+
+function bestMessageTarget(
+  definitionName: string,
+  candidates: readonly string[]
+): string | undefined {
+  return [...candidates].sort(
+    (left, right) =>
+      nameSimilarityScore(definitionName, right) - nameSimilarityScore(definitionName, left) ||
+      left.localeCompare(right)
+  )[0];
+}
+
+function nameSimilarityScore(definitionName: string, target: string): number {
+  const definition = normalizeName(definitionName);
+  const candidate = normalizeName(target);
+  if (!candidate) return 0;
+  if (definition === candidate) return 3;
+  if (definition.endsWith(candidate) || definition.startsWith(candidate)) return 2;
+  if (definition.includes(candidate) || candidate.includes(definition)) return 1;
+  return 0;
+}
+
+function normalizeName(value: string): string {
+  return (
+    value
+      .split(/[.#/]/)
+      .at(-1)
+      ?.replace(/[^a-z0-9]/gi, "")
+      .toLowerCase() ?? ""
+  );
+}
+
+function strongOverlap(overlap: number | undefined): boolean {
+  return overlap !== undefined && overlap >= 0.7;
+}
+
+function withTarget(
+  state: IdentityState,
+  confidence: IdentityConfidence,
+  canonicalTarget: string | undefined
+): IdentityClassification {
+  return canonicalTarget ? { state, confidence, canonicalTarget } : { state, confidence };
+}

package/src/identity/component-key.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+
+import { buildComponentKey } from "./component-key.js";
+
+describe("buildComponentKey", () => {
+  it("normalizes clone-independent repository paths", () => {
+    expect(
+      buildComponentKey({
+        repoRelativeFile: "./packages/ui/src/../src/Button.tsx",
+        exportName: " Button ",
+      })
+    ).toBe("packages/ui/src/Button.tsx#Button");
+  });
+
+  it("normalizes Windows separators to the same key", () => {
+    const posix = buildComponentKey({
+      repoRelativeFile: "packages/ui/src/Button.tsx",
+      exportName: "Button",
+    });
+    const windows = buildComponentKey({
+      repoRelativeFile: ".\\packages\\ui\\src\\Button.tsx",
+      exportName: "Button",
+    });
+
+    expect(windows).toBe(posix);
+  });
+
+  it("rejects empty identity parts", () => {
+    expect(() => buildComponentKey({ repoRelativeFile: "", exportName: "Button" })).toThrow();
+    expect(() => buildComponentKey({ repoRelativeFile: "Button.tsx", exportName: " " })).toThrow();
+  });
+});

package/src/identity/component-key.ts

@@ -0,0 +1,35 @@
+export interface ComponentKeyInput {
+  repoRelativeFile: string;
+  exportName: string;
+}
+
+/**
+ * Mint a clone- and platform-portable identity for one component definition.
+ */
+export function buildComponentKey({ repoRelativeFile, exportName }: ComponentKeyInput): string {
+  const file = normalizeRepoRelativeFile(repoRelativeFile);
+  const name = exportName.trim();
+  if (!file) throw new Error("repoRelativeFile must not be empty");
+  if (!name) throw new Error("exportName must not be empty");
+  return `${file}#${name}`;
+}
+
+function normalizeRepoRelativeFile(file: string): string {
+  const slashNormalized = file
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/^\.\/+/, "");
+  const absolute = slashNormalized.startsWith("/");
+  const parts: string[] = [];
+
+  for (const part of slashNormalized.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === ".." && parts.length > 0 && parts.at(-1) !== "..") {
+      parts.pop();
+      continue;
+    }
+    parts.push(part);
+  }
+
+  return `${absolute ? "/" : ""}${parts.join("/")}`;
+}

package/src/identity/usage.ts

@@ -0,0 +1,39 @@
+import type { FactIndex, UsageNodeFact } from "../facts/index.js";
+
+export interface ComponentIdentityUsage {
+  usageCount: number;
+  /** Number of distinct source files containing a usage. */
+  blastRadius: number;
+  nodes: UsageNodeFact[];
+}
+
+/** Join resolved component usages to their usage nodes once for rules and DX surfaces. */
+export function indexComponentIdentityUsage(
+  ix: FactIndex
+): ReadonlyMap<string, ComponentIdentityUsage> {
+  const nodesById = new Map(ix.byKind("usage_node").map((node) => [node.id, node]));
+  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 nodes = nodesByComponent.get(componentKey) ?? new Map<string, UsageNodeFact>();
+    nodes.set(node.id, node);
+    nodesByComponent.set(componentKey, nodes);
+  }
+
+  return new Map(
+    [...nodesByComponent].map(([componentKey, nodesByIdForComponent]) => {
+      const nodes = [...nodesByIdForComponent.values()];
+      return [
+        componentKey,
+        {
+          usageCount: nodes.length,
+          blastRadius: new Set(nodes.map((node) => node.file)).size,
+          nodes,
+        },
+      ];
+    })
+  );
+}

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,
@@ -627,6 +635,7 @@ export {
   ruleComponentsUnknownProp,
   ruleComponentsForbiddenPropValue,
   ruleComponentsPreferLibrary,
+  ruleComponentsShadowComponent,
   rulePropsInvalidValue,
   ruleJsxPreferredImportPath,
   ruleJsxPreferredComponent,
@@ -644,6 +653,7 @@ export {
   ruleTokensRequireDualFallback,
   ruleA11yRequiredAccessibleName,
 } from "./rules/index.js";
+export { indexComponentIdentityUsage, type ComponentIdentityUsage } from "./identity/usage.js";
 export { nearestSignedScaleValue } from "./rules/utils.js";
 export {
   buildSpacingTokenLookup,
@@ -715,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,
@@ -726,6 +754,8 @@ export {
   matchesGlob,
   makeComponentMetadataFact,
   makeComponentCapabilityFact,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
   makeCanonicalCandidateFact,
   makeCanonicalMappingFact,
   makeCanonicalReplacementFact,
@@ -836,6 +866,20 @@ export {
   type RawHtmlCanonicalMatch,
   type RawHtmlPrecisionTier,
 } from "./raw-html-canonical.js";
+export { buildComponentKey, type ComponentKeyInput } from "./identity/component-key.js";
+export {
+  classifyIdentity,
+  type CanonicalIdentityReference,
+  type ClassifyIdentityInput,
+  type ExternalIdentityReference,
+  type IdentityClassification,
+  type IdentityConfidence,
+  type IdentityDecision,
+  type IdentityState,
+  type LocalIdentityReference,
+  type ResolvedIdentityRenderRoot,
+  type ResolvedIntrinsicIdentityRoot,
+} from "./identity/classify.js";
 export type {
   ComponentId,
   FactId,
@@ -848,6 +892,10 @@ export type {
   CanonicalMappingFact,
   CanonicalReplacementFact,
   ComponentLevelFact,
+  ComponentDefinitionFact,
+  ComponentDefinitionRenderRoot,
+  ComponentIdentityFact,
+  IdentityFact,
   PolicyFact,
   UsageFact,
   ComponentMetadataFact,