@usefragments/core 1.4.0 → 1.5.0

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

@@ -627,6 +627,7 @@ export {
   ruleComponentsUnknownProp,
   ruleComponentsForbiddenPropValue,
   ruleComponentsPreferLibrary,
+  ruleComponentsShadowComponent,
   rulePropsInvalidValue,
   ruleJsxPreferredImportPath,
   ruleJsxPreferredComponent,
@@ -644,6 +645,10 @@ export {
   ruleTokensRequireDualFallback,
   ruleA11yRequiredAccessibleName,
 } from "./rules/index.js";
+export {
+  indexComponentIdentityUsage,
+  type ComponentIdentityUsage,
+} from "./identity/usage.js";
 export { nearestSignedScaleValue } from "./rules/utils.js";
 export {
   buildSpacingTokenLookup,
@@ -726,6 +731,8 @@ export {
   matchesGlob,
   makeComponentMetadataFact,
   makeComponentCapabilityFact,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
   makeCanonicalCandidateFact,
   makeCanonicalMappingFact,
   makeCanonicalReplacementFact,
@@ -836,6 +843,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 +869,10 @@ export type {
   CanonicalMappingFact,
   CanonicalReplacementFact,
   ComponentLevelFact,
+  ComponentDefinitionFact,
+  ComponentDefinitionRenderRoot,
+  ComponentIdentityFact,
+  IdentityFact,
   PolicyFact,
   UsageFact,
   ComponentMetadataFact,

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

@@ -4,6 +4,7 @@ import {
   asComponentId,
   compileGlobalGovernanceFacts,
   FactIndex,
+  makeComponentIdentityFact,
   makeUsageComponentFact,
   makeUsageImportFact,
   makeUsageNodeFact,
@@ -145,4 +146,51 @@ describe("components/prefer-library — #9e directory import-path identity", ()
 
     expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
   });
+
+  it("keeps flagging raw render roots when component identity facts are absent", () => {
+    const ix = directoryIndex();
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/components/MyButton.tsx",
+        nodePath: "0:0",
+        element: "button",
+        interactive: true,
+        location: { file: "src/components/MyButton.tsx", line: 5, column: 2 },
+      })
+    );
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(1);
+  });
+
+  it("suppresses only the render-root node proven to belong to a shadow definition", () => {
+    const ix = directoryIndex();
+    const shadowRoot = makeUsageNodeFact({
+      file: "src/components/MyButton.tsx",
+      nodePath: "0:0",
+      element: "button",
+      interactive: true,
+      location: { file: "src/components/MyButton.tsx", line: 5, column: 2 },
+    });
+    const unrelated = makeUsageNodeFact({
+      file: "src/App.tsx",
+      nodePath: "0:0",
+      element: "button",
+      interactive: true,
+      location: { file: "src/App.tsx", line: 9, column: 4 },
+    });
+    ix.addMany([shadowRoot, unrelated]);
+    ix.add(
+      makeComponentIdentityFact({
+        componentKey: "src/components/MyButton.tsx#MyButton",
+        state: "shadow",
+        confidence: "confirmed",
+        canonicalTarget: "Button",
+        evidence: [shadowRoot.id],
+      })
+    );
+
+    const findings = ruleComponentsPreferLibrary(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.location.file).toBe("src/App.tsx");
+  });
 });

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

@@ -270,6 +270,7 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
   // 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 shadowRenderRootNodeIds = indexShadowRenderRootNodeIds(ix);
   const findings: Finding[] = [];
   const seenImportFixes = new Set<string>();
 
@@ -277,6 +278,7 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
     if (isCanonicalSourceImplementationFile(node.file, sources)) continue;
     if (node.element.includes(".")) continue;
     if (canonicalDirectoryResolvedNodes.has(node.id)) continue;
+    if (shadowRenderRootNodeIds.has(node.id)) continue;
     const props = propsByNode.get(node.id) ?? [];
     const textChildren = textByNode.get(node.id) ?? [];
     const importsForFile = importsByFileAndLocal.get(node.file);
@@ -603,6 +605,20 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
   return findings;
 }
 
+function indexShadowRenderRootNodeIds(ix: FactIndex): Set<FactId> {
+  const identities = ix.byKind("component_identity");
+  if (identities.length === 0) return new Set();
+
+  const nodeIds = new Set<FactId>();
+  for (const identity of identities) {
+    if (identity.state !== "shadow") continue;
+    for (const evidenceId of identity.evidence) {
+      if (ix.get(evidenceId)?.kind === "usage_node") nodeIds.add(evidenceId);
+    }
+  }
+  return nodeIds;
+}
+
 interface BuiltInRawHtmlMatch {
   canonical: string;
   tier: RawHtmlPrecisionTier;

package/src/rules/components-shadow-component.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  BLOCKING_RULE_ALLOWLIST,
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  isDenyEligible,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
+  makeUsageComponentFact,
+  makeUsageNodeFact,
+  ruleComponentsShadowComponent,
+} from "../index.js";
+
+describe("components/shadow-component", () => {
+  it("emits one definition finding with usage count, blast radius, and a stable fingerprint", () => {
+    const first = shadowIndex({ definitionLine: 8 });
+    const moved = shadowIndex({ definitionLine: 80 });
+
+    const finding = ruleComponentsShadowComponent(first)[0];
+    const movedFinding = ruleComponentsShadowComponent(moved)[0];
+
+    expect(finding).toMatchObject({
+      ruleId: "components/shadow-component",
+      level: "warn",
+      location: { file: "src/components/MyButton.tsx", line: 8, column: 2 },
+      attributes: {
+        canonicalTarget: "Button",
+        usageCount: 3,
+        blastRadius: 2,
+        confidence: "confirmed",
+        state: "shadow",
+      },
+    });
+    expect(finding?.attributes).not.toHaveProperty("advisory");
+    expect(finding?.fingerprint).toBe(movedFinding?.fingerprint);
+  });
+
+  it("keeps review-tier variants permanently advisory at info severity", () => {
+    const ix = shadowIndex({ state: "variant", confidence: "review", severity: "error" });
+
+    const finding = ruleComponentsShadowComponent(ix)[0];
+
+    expect(finding).toMatchObject({
+      severity: "minor",
+      level: "warn",
+      attributes: {
+        canonicalTarget: "Button",
+        confidence: "review",
+        state: "variant",
+        advisory: true,
+      },
+    });
+    expect(isDenyEligible(finding!, true)).toBe(false);
+  });
+
+  it("honors an error severity for a confirmed shadow but never enters the write deny-set", () => {
+    const finding = ruleComponentsShadowComponent(shadowIndex({ severity: "error" }))[0];
+
+    expect(finding?.level).toBe("error");
+    expect(finding?.attributes).not.toHaveProperty("advisory");
+    expect(BLOCKING_RULE_ALLOWLIST.has("components/shadow-component")).toBe(false);
+    expect(isDenyEligible(finding!, false)).toBe(false);
+  });
+
+  it("throws rather than emitting an evidence-free finding", () => {
+    const ix = shadowIndex();
+    const identity = ix.byKind("component_identity")[0]!;
+    const empty = new FactIndex();
+    empty.addMany(
+      ix
+        .all()
+        .filter((fact) => fact.id !== identity.id)
+    );
+    empty.add(makeComponentIdentityFact({ ...identity, evidence: [] }));
+
+    expect(() => ruleComponentsShadowComponent(empty)).toThrow(
+      "findings must carry at least one evidence fact"
+    );
+  });
+});
+
+function shadowIndex(
+  options: {
+    state?: "shadow" | "variant";
+    confidence?: "confirmed" | "review";
+    severity?: "warn" | "error";
+    definitionLine?: number;
+  } = {}
+): FactIndex {
+  const componentKey = "src/components/MyButton.tsx#MyButton";
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      rules: {
+        "components/shadow-component": {
+          enabled: true,
+          severity: options.severity ?? "warn",
+        },
+      },
+    })
+  );
+  const definition = makeComponentDefinitionFact({
+    file: "src/components/MyButton.tsx",
+    exportName: "MyButton",
+    componentKey,
+    renderRoot: { resolution: "intrinsic", tag: "button", interactive: true },
+    propSurface: ["children", "disabled"],
+  });
+  const renderRoot = makeUsageNodeFact({
+    file: definition.file,
+    nodePath: "0:0",
+    element: "button",
+    interactive: true,
+    location: {
+      file: definition.file,
+      line: options.definitionLine ?? 8,
+      column: 2,
+    },
+  });
+  ix.addMany([definition, renderRoot]);
+  ix.add(
+    makeComponentIdentityFact({
+      componentKey,
+      state: options.state ?? "shadow",
+      confidence: options.confidence ?? "confirmed",
+      canonicalTarget: "Button",
+      evidence: [definition.id, renderRoot.id],
+    })
+  );
+
+  for (const [index, file] of ["src/App.tsx", "src/App.tsx", "src/Checkout.tsx"].entries()) {
+    const node = makeUsageNodeFact({
+      file,
+      nodePath: `0:${index}`,
+      element: "MyButton",
+      location: { file, line: index + 1, column: 0 },
+    });
+    ix.addMany([
+      node,
+      makeUsageComponentFact({ nodeId: node.id, componentId: definition.componentId }),
+    ]);
+  }
+  return ix;
+}