@usefragments/core 2.0.1 → 2.1.0

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

@@ -1,3 +1,10 @@
+import {
+  contractComponentSourceKey,
+  contractComponentExportAddresses as qualifiedMappingExports,
+  contractComponentReplacementImport as qualifiedMappingImport,
+  type ContractComponentSource,
+  type ContractComponentExport,
+} from "../contract/source-identity.js";
 import type { CanonicalSource, GovernanceSeverity } from "../governance.js";
 import type {
   FactId,
@@ -17,6 +24,7 @@ import {
   type RawHtmlPrecisionTier,
 } from "../raw-html-canonical.js";
 import { ownedImportMatchesRoot, ownedImportsEqual } from "../package-identity-match.js";
+import { canonicalizeOwnedImport } from "../package-identity.js";
 import { indexComponentIdentityUsage } from "../identity/usage.js";
 import { canonicalSourceContainsFile, canonicalSourceIncludesExport } from "../canonical-source.js";
 import {
@@ -33,6 +41,8 @@ export const RULE_ID = "components/prefer-library";
 export const RULE_VERSION = "1";
 
 interface CanonicalMappingOption {
+  source?: ContractComponentSource;
+  exportAddresses?: readonly ContractComponentExport[];
   name: string;
   /** Internal conform-boundary assertion; only the conform policy builder sets it. */
   conformStatus?: "confirmed";
@@ -183,13 +193,17 @@ const GENERIC_CLASSNAME_DENYLIST: ReadonlySet<string> = new Set([
 interface ReimplTarget {
   name: string;
   import?: string;
+  unresolved?: boolean;
+  alternatives?: string[];
 }
 
 /** lowercased class token → the canonical component it likely reimplements. */
 function canonicalReimplTargets(
   sources: readonly CanonicalSource[],
-  mappings: readonly CanonicalMappingOption[]
+  mappings: readonly CanonicalMappingOption[],
+  sourceQualified = false
 ): Map<string, ReimplTarget> {
+  if (sourceQualified) return qualifiedReimplTargets(sources, mappings);
   const out = new Map<string, ReimplTarget>();
   const add = (name: string | undefined, importPath: string | undefined) => {
     if (!name || !isIdentifier(name)) return;
@@ -205,6 +219,80 @@ function canonicalReimplTargets(
   return out;
 }
 
+function qualifiedReimplTargets(
+  sources: readonly CanonicalSource[],
+  mappings: readonly CanonicalMappingOption[]
+): Map<string, ReimplTarget> {
+  const choices = new Map<string, Map<string, ReimplTarget>>();
+  const exportOwners = new Map<string, Set<string>>();
+  const add = (name: string, identity: string, target: ReimplTarget) => {
+    const key = name.toLowerCase();
+    if (!isIdentifier(name) || GENERIC_CLASSNAME_DENYLIST.has(key)) return;
+    const matches = choices.get(key) ?? new Map<string, ReimplTarget>();
+    // Source identity and public export are separate choices. Two addresses of
+    // the same definition must not overwrite each other in authored order.
+    matches.set(JSON.stringify([identity, target.name, target.import ?? null]), target);
+    choices.set(key, matches);
+  };
+  for (const mapping of mappings) {
+    const identity = mapping.source
+      ? contractComponentSourceKey(mapping.source)
+      : JSON.stringify([mapping.importPath, mapping.name]);
+    const addresses = qualifiedMappingExports(mapping);
+    for (const address of addresses) {
+      const key = contractComponentSourceKey({ kind: "package", ...address });
+      const owners = exportOwners.get(key) ?? new Set<string>();
+      owners.add(identity);
+      exportOwners.set(key, owners);
+    }
+    const selected = qualifiedMappingImport(mapping);
+    const targets = selected ? [selected] : addresses;
+    if (targets.length === 0) add(mapping.name, identity, { name: mapping.name, unresolved: true });
+    for (const target of targets)
+      add(mapping.name, identity, {
+        name: target.exportName,
+        import: target.importPath,
+        ...(!isComponentBinding(target.exportName) ? { unresolved: true } : {}),
+      });
+  }
+  for (const source of sources) {
+    for (const name of source.include ?? []) {
+      if (source.exclude?.includes(name)) continue;
+      const identity = qualifiedSourceIdentity(source, name);
+      const owners = exportOwners.get(identity) ?? new Set([identity]);
+      for (const owner of owners)
+        add(name, owner, {
+          name,
+          ...(canonicalImportPath(source) && isComponentBinding(name)
+            ? { import: canonicalizeOwnedImport(canonicalImportPath(source)!) }
+            : { unresolved: true }),
+        });
+    }
+  }
+  return new Map(
+    [...choices].map(([key, matches]) => {
+      const identities = [...matches.keys()].sort();
+      const target = matches.get(identities[0]!)!;
+      return [
+        key,
+        identities.length === 1
+          ? target
+          : { name: key, unresolved: true, alternatives: identities },
+      ];
+    })
+  );
+}
+
+function qualifiedSourceIdentity(source: CanonicalSource, name: string): string {
+  return source.kind === "npm"
+    ? contractComponentSourceKey({
+        kind: "package",
+        importPath: source.specifier,
+        exportName: name,
+      })
+    : JSON.stringify([source.kind, sourceLabel(source), name]);
+}
+
 /** The CSS-module member of a `styles.card` / `styles["card"]` snippet, or null. */
 function classMemberFromSnippet(snippet: string): string | null {
   const bracket = /\[\s*["'`]([A-Za-z0-9_-]+)["'`]\s*\]\s*$/.exec(snippet);
@@ -238,6 +326,8 @@ interface ClassNameReimplMatch {
   canonical: string;
   matchedClass: string;
   import?: string;
+  unresolved?: boolean;
+  alternatives?: string[];
 }
 
 function findClassNameReimpl(
@@ -253,7 +343,9 @@ function findClassNameReimpl(
       return {
         canonical: target.name,
         matchedClass: token,
-        ...(target.import ? { import: target.import } : {}),
+        ...(target.import && !target.unresolved ? { import: target.import } : {}),
+        ...(target.unresolved ? { unresolved: true } : {}),
+        ...(target.alternatives ? { alternatives: target.alternatives } : {}),
       };
     }
   }
@@ -282,7 +374,8 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
   const propsByNode = indexPropsByNodeId(ix);
   const textByNode = indexTextChildrenByNodeId(ix);
   const classTokensByNode = indexClassTokensByNode(ix);
-  const reimplTargets = canonicalReimplTargets(sources, mappings);
+  const sourceQualified = policy.options?.sourceIdentitySchema === "component-source:v1";
+  const reimplTargets = canonicalReimplTargets(sources, mappings, sourceQualified);
   // #9e — nodes whose local import a Node-side module resolver already proved
   // resolves INSIDE a directory canonical source (the extractor emitted a
   // `usage_component` whose id points at that directory). These are the genuine
@@ -333,8 +426,8 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
     const imported = importsForFile?.get(node.element);
     const nodeInputType =
       node.element === "input" ? readStaticStringProp(props, "type") : undefined;
-    const mapped = findMapping(node, nodeInputType, mappings);
-    if (mapped && imported && isMappedCanonicalImport(imported, mapped)) continue;
+    const mapped = findMapping(node, nodeInputType, mappings, sourceQualified, imported);
+    if (mapped && imported && isMappedCanonicalImport(imported, mapped, sourceQualified)) continue;
     if (
       imported &&
       isCanonicalImport(
@@ -342,20 +435,92 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
         node.element,
         approvedLocalDefinitionKeys === undefined
           ? sources
-          : sources.filter((source) => source.kind !== "directory")
+          : sources.filter((source) => source.kind !== "directory"),
+        sourceQualified
       )
     )
       continue;
 
+    if (mapped === null) {
+      const preciseIntrinsic =
+        !imported &&
+        mappings.some(
+          (mapping) =>
+            sameHtmlTag(mapping.htmlEquivalent, node.element) &&
+            isEnforceableHtmlEquivalent({
+              tag: node.element,
+              canonical: mapping.name,
+              inputType: nodeInputType,
+              explicit: isExplicitTagDeclaration(mapping),
+            })
+        );
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: preciseIntrinsic
+            ? (policy.severity ?? "warn")
+            : capAdvisorySeverity(policy.severity),
+          message: `<${node.element}> has multiple approved component sources. Choose the intended source before applying a replacement.`,
+          location: node.location,
+          evidence: ix.evidence(
+            imported ? [node.id, imported.id, policy.id] : [node.id, policy.id]
+          ),
+          fingerprintIdentity: {
+            file: node.file,
+            nodePath: node.nodePath,
+            element: node.element,
+            ambiguity: "approved-component-sources",
+          },
+          attributes: {
+            ...(!preciseIntrinsic ? { advisory: true } : {}),
+            ambiguousCanonicalTarget: true,
+            contractProof: "missing",
+          },
+        })
+      );
+      continue;
+    }
+
     if (mapped) {
       if (!shouldSuggestMapped(node, nodeInputType, imported, mapped)) continue;
-      const importPath = mapped.importPath;
-      const suggestedComponent = mapped.name;
+      const target = sourceQualified ? qualifiedMappingImport(mapped) : undefined;
+      const roleMatch = isRoleMatch(node, mapped);
+      const precisionTier: RawHtmlPrecisionTier = roleMatch ? "role-reimpl" : "exact-html";
+      if (sourceQualified && !target) {
+        findings.push(
+          makeFinding({
+            ruleId: RULE_ID,
+            ruleVersion: RULE_VERSION,
+            severity: imported
+              ? capAdvisorySeverity(policy.severity)
+              : severityForTier(policy.severity, precisionTier),
+            message: `Choose a verified export of ${mapped.name} before replacing <${node.element}>.`,
+            location: node.location,
+            evidence: ix.evidence(
+              imported ? [node.id, imported.id, policy.id] : [node.id, policy.id]
+            ),
+            fingerprintIdentity: {
+              file: node.file,
+              nodePath: node.nodePath,
+              element: node.element,
+              ambiguity: "approved-component-export",
+            },
+            attributes: {
+              ...(imported || isRawHtmlAdvisoryTier(precisionTier) ? { advisory: true } : {}),
+              precisionTier,
+              unresolvedCanonicalExport: true,
+              contractProof: "missing",
+            },
+          })
+        );
+        continue;
+      }
+      const importPath = sourceQualified ? target?.importPath : mapped.importPath;
+      const suggestedComponent = target?.exportName ?? mapped.name;
       const suggestedImport = importPath ?? "the canonical library";
       const propMapping = mapped.propMapping ?? [];
       const propCompatibility = assessMappedPropCompatibility(props, propMapping);
-      const roleMatch = isRoleMatch(node, mapped);
-      const precisionTier: RawHtmlPrecisionTier = roleMatch ? "role-reimpl" : "exact-html";
 
       if (
         imported &&
@@ -494,20 +659,29 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
             ruleId: RULE_ID,
             ruleVersion: RULE_VERSION,
             severity: capAdvisorySeverity(policy.severity),
-            message: `<${node.element} class="${reimpl.matchedClass}"> looks like a hand-rolled <${reimpl.canonical}>. Use <${reimpl.canonical}> from ${suggestedImport} instead of restyling a <${node.element}>.`,
+            message: reimpl.unresolved
+              ? `<${node.element} class="${reimpl.matchedClass}"> resembles an approved component. Choose an exact implementation and public export before replacing it.`
+              : `<${node.element} class="${reimpl.matchedClass}"> looks like a hand-rolled <${reimpl.canonical}>. Use <${reimpl.canonical}> from ${suggestedImport} instead of restyling a <${node.element}>.`,
             location: node.location,
             evidence: ix.evidence([node.id, policy.id]),
             fingerprintIdentity: {
               file: node.file,
               nodePath: node.nodePath,
               element: node.element,
-              suggestedComponent: reimpl.canonical,
+              ...(reimpl.unresolved ? {} : { suggestedComponent: reimpl.canonical }),
               matchedClass: reimpl.matchedClass,
             },
             attributes: {
               rawValue: node.element,
-              suggestedComponent: reimpl.canonical,
+              ...(reimpl.unresolved ? {} : { suggestedComponent: reimpl.canonical }),
               ...(reimpl.import ? { suggestedImport: reimpl.import } : {}),
+              ...(reimpl.unresolved ? { unresolvedCanonicalExport: true } : {}),
+              ...(reimpl.alternatives
+                ? {
+                    ambiguousCanonicalTarget: true,
+                    canonicalAlternatives: reimpl.alternatives,
+                  }
+                : {}),
               precisionTier: "classname-reimpl",
               matchedClass: reimpl.matchedClass,
               advisory: true,
@@ -521,9 +695,38 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
     const builtIn = findBuiltInRawHtmlMatch(node, props, textChildren, nodeInputType);
     const suggestedComponent =
       builtIn?.canonical ?? (node.element === "button" ? "Button" : node.element);
-    const suggestion = findSuggestionSource(suggestedComponent, sources);
-    if (!suggestion) continue;
     if (!builtIn && !shouldSuggest(node, imported)) continue;
+    const suggestion = findSuggestionSource(suggestedComponent, sources, sourceQualified);
+    if (suggestion === null) {
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: capAdvisorySeverity(policy.severity),
+          message: `<${node.element}> has multiple approved component sources. Choose the intended source before applying a replacement.`,
+          location: node.location,
+          evidence: ix.evidence(
+            imported ? [node.id, imported.id, policy.id] : [node.id, policy.id]
+          ),
+          fingerprintIdentity: {
+            file: node.file,
+            nodePath: node.nodePath,
+            element: node.element,
+            ambiguity: "approved-component-sources",
+          },
+          attributes: {
+            advisory: true,
+            ambiguousCanonicalTarget: true,
+            contractProof: "missing",
+            canonicalAlternatives: suggestionSources(suggestedComponent, sources)
+              .map((source) => qualifiedSourceIdentity(source, suggestedComponent))
+              .sort(),
+          },
+        })
+      );
+      continue;
+    }
+    if (!suggestion) continue;
 
     // An exact component-name match is either already canonical (handled near
     // the top of the loop), a safely redirectable local component import, or an
@@ -1063,54 +1266,78 @@ function hasValidComponentList(value: unknown): boolean {
 function findMapping(
   node: UsageNodeFact,
   nodeInputType: string | undefined,
-  mappings: readonly CanonicalMappingOption[]
-): CanonicalMappingOption | undefined {
+  mappings: readonly CanonicalMappingOption[],
+  sourceQualified = false,
+  imported?: UsageImportFact
+): CanonicalMappingOption | null | undefined {
+  const choose = (matches: CanonicalMappingOption[]) => {
+    if (!sourceQualified) return matches[0];
+    const exact = imported
+      ? matches.filter((mapping) => isMappedCanonicalImport(imported, mapping, true))
+      : [];
+    const candidates = exact.length > 0 ? exact : matches;
+    const identities = new Map(
+      candidates.map((mapping) => [
+        mapping.source
+          ? contractComponentSourceKey(mapping.source)
+          : JSON.stringify([mapping.importPath, mapping.name]),
+        mapping,
+      ])
+    );
+    return identities.size > 1 ? null : candidates[0];
+  };
   // A type-specific input mapping wins over a generic tag-level one, so a
   // library mapping `<input type="checkbox">` → Checkbox is never shadowed by a
   // catch-all `<input>` → TextField entry. Normalized to lower-case to mirror
   // the resolved `type` prop value the extractor records.
   if (node.element === "input" && nodeInputType) {
-    const typed = mappings.find(
-      (mapping) =>
-        sameHtmlTag(mapping.htmlEquivalent, "input") &&
-        mapping.htmlType !== undefined &&
-        mapping.htmlType.toLowerCase() === nodeInputType.toLowerCase()
+    const typed = choose(
+      mappings.filter(
+        (mapping) =>
+          sameHtmlTag(mapping.htmlEquivalent, "input") &&
+          mapping.htmlType !== undefined &&
+          mapping.htmlType.toLowerCase() === nodeInputType.toLowerCase()
+      )
     );
-    if (typed) return typed;
+    if (typed !== undefined) return typed;
   }
 
-  return mappings.find((mapping) => {
-    if (
-      sameHtmlTag(mapping.htmlEquivalent, node.element) &&
-      // Match enforceability against the EMITTED `mapping.name` (see
-      // shouldSuggestMapped): for ambiguous tags this requires the suggested
-      // component to BE the tag's curated canonical, so a disagreeing
-      // `<button>` → Chip mapping never matches in the first place.
-      isEnforceableHtmlEquivalent({
-        tag: node.element,
-        canonical: mapping.name,
-        inputType: nodeInputType,
-        explicit: isExplicitTagDeclaration(mapping),
-      })
-    ) {
-      // A type-constrained mapping only matches the matching input type; an
-      // unconstrained one matches any element with that tag (back-compat).
-      // Gated so an inferred `div`/`span` primitive (or a `button` → specialized
-      // component) never blanket-flags every container — see
-      // isEnforceableHtmlEquivalent.
-      return mapping.htmlType === undefined || matchesInputType(mapping, nodeInputType);
-    }
-    if (mapping.name === node.element) return true;
-    // Deliberately NOT matching on `mapping.canonical` (the vocabulary id): see
-    // shouldSuggestMapped. Selecting a mapping purely because the element name
-    // equals a canonical vocab id (Dialog/Tooltip/Card…) produced divergent swaps
-    // and cross-mapping hijacking (audit #1/#2). A real name match (above), an
-    // enforceable htmlEquivalent (above), or an ARIA-role match (below) remain.
-    // Semantic match: a bespoke element whose declared ARIA role equals the
-    // canonical primitive's role (e.g. `<div role="status">` → Toast). Keyed on
-    // normalized `usage_node.role`, so it is framework-agnostic.
-    return node.role !== undefined && mapping.ariaRole === node.role;
-  });
+  return choose(
+    mappings.filter((mapping) => {
+      if (sourceQualified && imported && isMappedCanonicalImport(imported, mapping, true))
+        return true;
+      if (
+        sameHtmlTag(mapping.htmlEquivalent, node.element) &&
+        // Match enforceability against the EMITTED `mapping.name` (see
+        // shouldSuggestMapped): for ambiguous tags this requires the suggested
+        // component to BE the tag's curated canonical, so a disagreeing
+        // `<button>` → Chip mapping never matches in the first place.
+        isEnforceableHtmlEquivalent({
+          tag: node.element,
+          canonical: mapping.name,
+          inputType: nodeInputType,
+          explicit: isExplicitTagDeclaration(mapping),
+        })
+      ) {
+        // A type-constrained mapping only matches the matching input type; an
+        // unconstrained one matches any element with that tag (back-compat).
+        // Gated so an inferred `div`/`span` primitive (or a `button` → specialized
+        // component) never blanket-flags every container — see
+        // isEnforceableHtmlEquivalent.
+        return mapping.htmlType === undefined || matchesInputType(mapping, nodeInputType);
+      }
+      if (mapping.name === node.element) return true;
+      // Deliberately NOT matching on `mapping.canonical` (the vocabulary id): see
+      // shouldSuggestMapped. Selecting a mapping purely because the element name
+      // equals a canonical vocab id (Dialog/Tooltip/Card…) produced divergent swaps
+      // and cross-mapping hijacking (audit #1/#2). A real name match (above), an
+      // enforceable htmlEquivalent (above), or an ARIA-role match (below) remain.
+      // Semantic match: a bespoke element whose declared ARIA role equals the
+      // canonical primitive's role (e.g. `<div role="status">` → Toast). Keyed on
+      // normalized `usage_node.role`, so it is framework-agnostic.
+      return node.role !== undefined && mapping.ariaRole === node.role;
+    })
+  );
 }
 
 function matchesInputType(
@@ -1133,15 +1360,50 @@ function isRoleMatch(node: UsageNodeFact, mapping: CanonicalMappingOption): bool
   );
 }
 
-function isMappedCanonicalImport(usage: UsageImportFact, mapping: CanonicalMappingOption): boolean {
-  return Boolean(mapping.importPath && ownedImportsEqual(usage.source, mapping.importPath));
+function isMappedCanonicalImport(
+  usage: UsageImportFact,
+  mapping: CanonicalMappingOption,
+  sourceQualified = false
+): boolean {
+  if (!sourceQualified)
+    return Boolean(mapping.importPath && ownedImportsEqual(usage.source, mapping.importPath));
+  // A public barrel alias has its own export name; the implementation symbol
+  // does not authorize arbitrary names at the package's root.
+  if (
+    mapping.exportAddresses?.some(
+      (address) =>
+        address.kind === "package" &&
+        ownedImportsEqual(usage.source, address.importPath) &&
+        usage.imported === address.exportName
+    )
+  )
+    return true;
+  return Boolean(
+    mapping.source?.kind === "package" &&
+    ownedImportsEqual(usage.source, mapping.source.importPath) &&
+    usage.imported === mapping.source.exportName
+  );
+}
+
+/** Current replacement fixes need a component binding, not default-import syntax. */
+function isComponentBinding(name: string): boolean {
+  return isIdentifier(name) && !/^[a-z]/.test(name);
 }
 
 function isCanonicalImport(
   usage: UsageImportFact,
   componentName: string,
-  sources: readonly CanonicalSource[]
+  sources: readonly CanonicalSource[],
+  sourceQualified = false
 ): boolean {
+  if (sourceQualified)
+    return sources.some(
+      (source) =>
+        canonicalImportPath(source) !== undefined &&
+        source.include?.includes(usage.imported) &&
+        !source.exclude?.includes(usage.imported) &&
+        ownedImportsEqual(usage.source, canonicalImportPath(source)!)
+    );
   return sources.some((source) => {
     if (!sourceIncludesComponent(source, componentName)) return false;
     if (source.exclude?.includes(componentName)) return false;
@@ -1158,9 +1420,26 @@ function isCanonicalImport(
 
 function findSuggestionSource(
   componentName: string,
-  sources: readonly CanonicalSource[]
-): CanonicalSource | undefined {
-  return sources.find(
+  sources: readonly CanonicalSource[],
+  sourceQualified = false
+): CanonicalSource | null | undefined {
+  const matches = suggestionSources(componentName, sources);
+  if (!sourceQualified) return matches[0];
+  const identities = new Set(
+    matches.map((source) => qualifiedSourceIdentity(source, componentName))
+  );
+  if (identities.size > 1) return null;
+  const source = matches[0];
+  if (source?.kind === "npm")
+    return { ...source, specifier: canonicalizeOwnedImport(source.specifier) };
+  if (source?.kind === "registry" && source.importPath) {
+    return { ...source, importPath: canonicalizeOwnedImport(source.importPath) };
+  }
+  return source;
+}
+
+function suggestionSources(componentName: string, sources: readonly CanonicalSource[]) {
+  return sources.filter(
     (source) =>
       sourceIncludesComponent(source, componentName) && !source.exclude?.includes(componentName)
   );