@usefragments/core 1.3.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

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  asComponentId,
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  makeComponentIdentityFact,
+  makeUsageComponentFact,
+  makeUsageImportFact,
+  makeUsageNodeFact,
+  ruleComponentsPreferLibrary,
+} from "../index.js";
+
+// #9e — import-path identity for a DIRECTORY canonical source. A directory
+// source (e.g. `src/components/ui`) declares its canonical component NAMES via an
+// include list. The rule must:
+//   (a) leave a genuine `<Button>` alone once the scan resolver proved its import
+//       resolves INSIDE the directory (a `usage_component` with a `<dir>#Name` id);
+//   (b) flag a local impostor `<Button>` imported from OUTSIDE the directory,
+//       redirecting the import at the canonical directory path (advisory / warn);
+//   (c) never flag a third-party or aliased same-name import (collision guard).
+describe("components/prefer-library — #9e directory import-path identity", () => {
+  const CANONICAL_DIR = "src/components/ui";
+
+  function directoryIndex() {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "warning",
+            options: {
+              canonicalSources: [
+                { kind: "directory", path: CANONICAL_DIR, include: ["Button", "Input"] },
+              ],
+            },
+          },
+        },
+      })
+    );
+    return ix;
+  }
+
+  function addButtonUsage(
+    ix: FactIndex,
+    input: { local?: string; imported?: string; source: string }
+  ) {
+    const node = makeUsageNodeFact({
+      file: "src/pages/Home.tsx",
+      nodePath: "0:0",
+      element: "Button",
+      location: { file: "src/pages/Home.tsx", line: 5, column: 4 },
+    });
+    ix.add(node);
+    ix.add(
+      makeUsageImportFact({
+        file: "src/pages/Home.tsx",
+        local: input.local ?? "Button",
+        imported: input.imported ?? "Button",
+        source: input.source,
+        location: { file: "src/pages/Home.tsx", line: 1, column: 0 },
+      })
+    );
+    return node;
+  }
+
+  it("does not flag a Button whose import the scan resolver proved resolves inside the canonical directory", () => {
+    const ix = directoryIndex();
+    // The genuine primitive, imported through a `@/` alias into the canonical dir.
+    const node = addButtonUsage(ix, { source: "@/components/ui/Button" });
+    // The extractor's resolveComponentId seam emitted this canonical id because
+    // the module resolved INSIDE `src/components/ui`.
+    ix.add(
+      makeUsageComponentFact({
+        nodeId: node.id,
+        componentId: asComponentId(`${CANONICAL_DIR}#Button`),
+      })
+    );
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
+  });
+
+  it("flags a local impostor Button imported from outside the canonical directory and redirects to the canonical path", () => {
+    const ix = directoryIndex();
+    // No usage_component fact: the impostor's import resolved OUTSIDE the dir.
+    addButtonUsage(ix, { source: "../features/FakeButton" });
+
+    const findings = ruleComponentsPreferLibrary(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "components/prefer-library",
+      code: "FUI1004",
+      fix: {
+        kind: "replaceImport",
+        from: "../features/FakeButton",
+        to: CANONICAL_DIR,
+        deterministic: false,
+      },
+      attributes: {
+        suggestedComponent: "Button",
+        suggestedImport: CANONICAL_DIR,
+        advisory: true,
+        contractProof: "missing",
+      },
+    });
+    // Advisory only — never a hard error/block.
+    expect(findings[0].level).toBe("warn");
+  });
+
+  it("does not flag a same-name Button imported from a third-party package (collision guard)", () => {
+    const ix = directoryIndex();
+    addButtonUsage(ix, { source: "@tanstack/react-router" });
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
+  });
+
+  it("does not flag an aliased same-name import whose bound export differs (collision guard)", () => {
+    const ix = directoryIndex();
+    // `import { Foo as Button } from "../x"` — the local JSX name collides, but
+    // the imported binding is not the canonical `Button`, so it is not a redirect
+    // candidate.
+    addButtonUsage(ix, { local: "Button", imported: "Foo", source: "../x" });
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
+  });
+
+  it("does not blanket-flag local imports for a directory source without an include list (#224 guard)", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "warning",
+            options: {
+              // No include list → no curated canonical NAME vocabulary, so there
+              // is no basis to redirect an arbitrary local component import.
+              canonicalSources: [{ kind: "directory", path: CANONICAL_DIR }],
+            },
+          },
+        },
+      })
+    );
+    addButtonUsage(ix, { source: "../features/FakeButton" });
+
+    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");
+  });
+});