@starklab/stark-mcp 0.1.0

package/src/adopt/wrapperResolver.js

@@ -0,0 +1,874 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import traverseModule from '@babel/traverse';
+
+import { loadCatalog, packageNameForPlatform } from './catalog.js';
+import { buildModuleGraph, resolveOriginDeep, EXTENSIONS } from './moduleGraph.js';
+import { classifyReference, KIND_CONFIDENCE } from './referenceResolver.js';
+
+const traverse = traverseModule.default ?? traverseModule;
+
+const WARN_DEPTH = 5; // ADOPTION_APP_PLAN.md §4 "5 is governance, 20 is safety"
+const MAX_DEPTH = 20;
+
+// ───────────────────────────── component declaration registry ─────────────────────────────
+
+function isFunctionNode(node) {
+  return (
+    node.type === 'FunctionDeclaration' ||
+    node.type === 'FunctionExpression' ||
+    node.type === 'ArrowFunctionExpression'
+  );
+}
+
+function isForwardRefCall(node) {
+  if (node.type !== 'CallExpression') return null;
+  const callee = node.callee;
+  const isBareForwardRef = callee.type === 'Identifier' && callee.name === 'forwardRef';
+  const isNamespacedForwardRef =
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === 'forwardRef';
+  if (!isBareForwardRef && !isNamespacedForwardRef) return null;
+  const fn = node.arguments[0];
+  return fn && isFunctionNode(fn) ? fn : null;
+}
+
+/**
+ * Collects every top-level, component-shaped local declaration in a file
+ * (function/arrow/forwardRef, capitalized name — the same rule JSX itself
+ * uses to tell a component tag from an intrinsic one) and annotates which
+ * ones are exported, and under what name. This is the registry
+ * resolveWrapperChain walks to find "does this JSX tag point at a wrapper
+ * this repo defines, rather than an import" (ADOPTION_APP_PLAN.md §4 blind
+ * spot 3).
+ */
+function extractComponentDecls(ast) {
+  const decls = new Map();
+
+  function registerNamed(name, fnNode, isForwardRef) {
+    if (!name || !/^[A-Z]/.test(name)) return;
+    decls.set(name, { fnNode, isForwardRef, exportedAs: null });
+  }
+
+  for (const node of ast.program.body) {
+    if (node.type === 'FunctionDeclaration' && node.id) {
+      registerNamed(node.id.name, node, false);
+    } else if (node.type === 'VariableDeclaration') {
+      for (const d of node.declarations) {
+        if (d.id.type !== 'Identifier' || !d.init) continue;
+        if (isFunctionNode(d.init)) {
+          registerNamed(d.id.name, d.init, false);
+        } else {
+          const fr = isForwardRefCall(d.init);
+          if (fr) registerNamed(d.id.name, fr, true);
+        }
+      }
+    } else if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+      const decl = node.declaration;
+      if (decl.type === 'FunctionDeclaration' && decl.id) {
+        registerNamed(decl.id.name, decl, false);
+        if (decls.has(decl.id.name)) decls.get(decl.id.name).exportedAs = decl.id.name;
+      } else if (decl.type === 'VariableDeclaration') {
+        for (const d of decl.declarations) {
+          if (d.id.type !== 'Identifier' || !d.init) continue;
+          if (isFunctionNode(d.init)) {
+            registerNamed(d.id.name, d.init, false);
+            if (decls.has(d.id.name)) decls.get(d.id.name).exportedAs = d.id.name;
+          } else {
+            const fr = isForwardRefCall(d.init);
+            if (fr) {
+              registerNamed(d.id.name, fr, true);
+              if (decls.has(d.id.name)) decls.get(d.id.name).exportedAs = d.id.name;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Second pass: `export { Foo, Bar as Baz }` and `export default Foo` only
+  // annotate exportedAs on declarations already collected above.
+  for (const node of ast.program.body) {
+    if (node.type === 'ExportNamedDeclaration' && !node.declaration && !node.source && node.specifiers?.length) {
+      for (const spec of node.specifiers) {
+        const localName = spec.local.name;
+        const exportedName = spec.exported.type === 'Identifier' ? spec.exported.name : spec.exported.value;
+        if (decls.has(localName)) decls.get(localName).exportedAs = exportedName;
+      }
+    } else if (node.type === 'ExportDefaultDeclaration') {
+      const decl = node.declaration;
+      if (decl.type === 'Identifier' && decls.has(decl.name)) {
+        decls.get(decl.name).exportedAs = 'default';
+      } else if (decl.type === 'FunctionDeclaration' && decl.id) {
+        registerNamed(decl.id.name, decl, false);
+        if (decls.has(decl.id.name)) decls.get(decl.id.name).exportedAs = 'default';
+        else decls.set(decl.id.name, { fnNode: decl, isForwardRef: false, exportedAs: 'default' });
+      } else if (isFunctionNode(decl)) {
+        decls.set('default', { fnNode: decl, isForwardRef: false, exportedAs: 'default' });
+      } else {
+        const fr = isForwardRefCall(decl);
+        if (fr) decls.set('default', { fnNode: fr, isForwardRef: true, exportedAs: 'default' });
+      }
+    }
+  }
+
+  return decls;
+}
+
+function getFileDecls(file, moduleGraph, declsCache) {
+  if (declsCache.has(file)) return declsCache.get(file);
+  const entry = moduleGraph.graph.get(file);
+  const decls = entry && entry.ast ? extractComponentDecls(entry.ast) : new Map();
+  declsCache.set(file, decls);
+  return decls;
+}
+
+// ───────────────────────────── JSX return-shape analysis ─────────────────────────────
+
+function significantChildren(children) {
+  return children.filter((c) => {
+    if (c.type === 'JSXText') return c.value.trim().length > 0;
+    if (c.type === 'JSXExpressionContainer' && c.expression.type === 'JSXEmptyExpression') return false;
+    return true;
+  });
+}
+
+function unwrapFragment(node) {
+  if (node.type !== 'JSXFragment') return node;
+  const kids = significantChildren(node.children);
+  if (kids.length === 1 && kids[0].type === 'JSXElement') return unwrapFragment(kids[0]);
+  return node; // ambiguous: 0 or 2+ significant children — no single root tag
+}
+
+function getOpeningName(node) {
+  if (node.type !== 'JSXElement') return null;
+  const nameNode = node.openingElement.name;
+  if (nameNode.type === 'JSXIdentifier') return { kind: 'identifier', name: nameNode.name };
+  if (nameNode.type === 'JSXMemberExpression' && nameNode.object.type === 'JSXIdentifier') {
+    return { kind: 'member', name: nameNode.object.name, member: nameNode.property.name };
+  }
+  return null; // JSXNamespacedName, or a member expression on a non-identifier object
+}
+
+function tagKeyOf(t) {
+  return t.kind === 'member' ? `member:${t.name}.${t.member}` : `identifier:${t.name}`;
+}
+
+function unwrapJsx(expr, out) {
+  if (!expr) return;
+  if (expr.type === 'JSXElement' || expr.type === 'JSXFragment') {
+    out.candidates.push(expr);
+    return;
+  }
+  if (expr.type === 'ConditionalExpression') {
+    unwrapJsx(expr.consequent, out);
+    unwrapJsx(expr.alternate, out);
+    return;
+  }
+  if (expr.type === 'LogicalExpression') {
+    unwrapJsx(expr.left, out);
+    unwrapJsx(expr.right, out);
+    return;
+  }
+  if (expr.type === 'ParenthesizedExpression') {
+    unwrapJsx(expr.expression, out);
+    return;
+  }
+  if (expr.type === 'NullLiteral' || (expr.type === 'BooleanLiteral' && expr.value === false)) return;
+  // Anything else (call expression, identifier, member access, template
+  // literal...) is a render path we can't classify without executing it.
+  out.dynamic = true;
+}
+
+function collectReturns(stmt, out) {
+  if (!stmt) return;
+  if (stmt.type === 'BlockStatement') {
+    for (const s of stmt.body) collectReturns(s, out);
+    return;
+  }
+  if (stmt.type === 'ReturnStatement') {
+    unwrapJsx(stmt.argument, out);
+    return;
+  }
+  if (stmt.type === 'IfStatement') {
+    collectReturns(stmt.consequent, out);
+    if (stmt.alternate) collectReturns(stmt.alternate, out);
+    return;
+  }
+  // Other statement kinds (loops, switch, try/catch, variable decls...) are
+  // deliberately not walked — this is a best-effort scan of the common
+  // early-return shapes, not a full control-flow analysis.
+}
+
+function analyzeFunctionReturns(fnNode) {
+  const out = { candidates: [], dynamic: false };
+  if (fnNode.body?.type === 'BlockStatement') {
+    collectReturns(fnNode.body, out);
+  } else if (fnNode.body) {
+    unwrapJsx(fnNode.body, out); // arrow function with an expression body
+  }
+  return out;
+}
+
+function singleSignificantJsxChild(node) {
+  const children = node.type === 'JSXElement' || node.type === 'JSXFragment' ? node.children : [];
+  const sig = significantChildren(children);
+  if (sig.length !== 1) return null;
+  return sig[0].type === 'JSXElement' || sig[0].type === 'JSXFragment' ? sig[0] : null;
+}
+
+/**
+ * Resolves a component function down to the single tag its JSX actually
+ * returns. Refuses to guess: multiple distinct return paths, a dynamic
+ * (non-JSX, non-null/false) return branch, or an ambiguous fragment all come
+ * back `ok:false` with a reason rather than picking one arbitrarily.
+ *
+ * When the outer root is a plain native/intrinsic element (a <div> etc.), it
+ * looks exactly one level inside for a single DS-bearing child before giving
+ * up — the "augmenting" pattern from ADOPTION_APP_PLAN.md §4 (a form-field
+ * wrapper: <div className="field"><Label/><Button/></div>). Multiple or zero
+ * significant children at that inner level means there's no single thing to
+ * attribute the wrap to, so it terminates as 'native' instead of guessing.
+ */
+function analyzeComponentBody(fnNode) {
+  const out = analyzeFunctionReturns(fnNode);
+  if (out.dynamic) return { ok: false, reason: 'dynamic-return' };
+  if (out.candidates.length === 0) return { ok: false, reason: 'no-jsx-return' };
+
+  const resolved = out.candidates.map(unwrapFragment);
+  const tagInfos = resolved.map(getOpeningName);
+  if (tagInfos.some((t) => !t)) return { ok: false, reason: 'ambiguous-root' };
+
+  const tagKeys = new Set(tagInfos.map(tagKeyOf));
+  if (tagKeys.size > 1) return { ok: false, reason: 'multiple-return-paths' };
+
+  const tag = tagInfos[0];
+  const node = resolved[0];
+
+  if (tag.kind === 'identifier' && /^[a-z]/.test(tag.name)) {
+    const inner = singleSignificantJsxChild(node);
+    if (inner) {
+      const innerUnwrapped = unwrapFragment(inner);
+      const innerTag = getOpeningName(innerUnwrapped);
+      if (innerTag) {
+        return { ok: true, tag: innerTag, node: innerUnwrapped, augmenting: true };
+      }
+    }
+    return { ok: false, reason: 'native-root', tag: tag.name };
+  }
+
+  return { ok: true, tag, node, augmenting: false };
+}
+
+// ───────────────────────────── faithfulness classification ─────────────────────────────
+
+const STYLE_ATTR_NAMES = new Set(['className', 'style', 'dangerouslySetInnerHTML']);
+
+function functionParamNames(fnNode) {
+  const params = fnNode.params || [];
+  return {
+    propsParamName: params[0]?.type === 'Identifier' ? params[0].name : null,
+    refParamName: params[1]?.type === 'Identifier' ? params[1].name : null,
+  };
+}
+
+function analyzeFaithfulness(rootJsxElement, fnNode, isForwardRef) {
+  const opening = rootJsxElement.openingElement;
+  const { refParamName } = functionParamNames(fnNode);
+
+  let hasSpread = false;
+  let refForwarded = false;
+  const hardcodedProps = [];
+  const divergentProps = [];
+
+  for (const attr of opening.attributes) {
+    if (attr.type === 'JSXSpreadAttribute') {
+      hasSpread = true; // spreading anything still forwards unknown props through
+      continue;
+    }
+    if (attr.type !== 'JSXAttribute') continue;
+    const name = attr.name.type === 'JSXIdentifier' ? attr.name.name : null;
+    if (!name) continue;
+
+    if (name === 'ref') {
+      if (
+        refParamName &&
+        attr.value?.type === 'JSXExpressionContainer' &&
+        attr.value.expression.type === 'Identifier' &&
+        attr.value.expression.name === refParamName
+      ) {
+        refForwarded = true;
+      }
+      continue;
+    }
+    if (name === 'children') continue;
+
+    if (STYLE_ATTR_NAMES.has(name)) {
+      divergentProps.push(name);
+      continue;
+    }
+
+    if (attr.value === null) {
+      hardcodedProps.push(name); // boolean shorthand — hardcoded `true`
+    } else if (attr.value.type === 'StringLiteral') {
+      hardcodedProps.push(name);
+    } else if (attr.value.type === 'JSXExpressionContainer') {
+      const expr = attr.value.expression;
+      const isPassthrough = expr.type === 'Identifier' || expr.type === 'MemberExpression' || expr.type === 'OptionalMemberExpression';
+      if (!isPassthrough) hardcodedProps.push(name);
+    }
+  }
+
+  return { hasSpread, refForwarded: isForwardRef ? refForwarded : true, hardcodedProps, divergentProps };
+}
+
+/**
+ * Priority order per ADOPTION_APP_PLAN.md §4: divergent (styling override) >
+ * augmenting (reached via the nested-native-wrapper path) > constraining (any
+ * hardcoded prop) > transparent.
+ */
+function classifyFaithfulness({ augmenting, divergentProps, hardcodedProps, hasSpread, refForwarded }) {
+  if (divergentProps.length > 0) return 'divergent';
+  if (augmenting) return 'augmenting';
+  if (hardcodedProps.length > 0) return 'constraining';
+  if (hasSpread && refForwarded) return 'transparent';
+  return 'transparent'; // no attributes to hardcode or forward — trivially faithful
+}
+
+// ───────────────────────────── root-terminal chain resolution ─────────────────────────────
+
+function resolveWrapperChain(
+  file,
+  localName,
+  moduleGraph,
+  declsCache,
+  catalogByName,
+  pkgName,
+  workspace,
+  visited = new Set(),
+  depth = 0
+) {
+  const key = `${file}#${localName}`;
+  if (visited.has(key)) {
+    return { terminal: 'cycle', cycle: [...visited, key], chain: [], depth };
+  }
+  if (depth > MAX_DEPTH) {
+    return { terminal: 'unresolved', reason: 'depth-limit', chain: [], depth };
+  }
+
+  const fileDecls = getFileDecls(file, moduleGraph, declsCache);
+  const declInfo = fileDecls.get(localName);
+  if (!declInfo) {
+    return { terminal: 'unresolved', reason: 'not-found', chain: [], depth };
+  }
+
+  const analysis = analyzeComponentBody(declInfo.fnNode);
+  if (!analysis.ok) {
+    if (analysis.reason === 'native-root') {
+      return { terminal: 'native', tag: analysis.tag, chain: [], depth };
+    }
+    return { terminal: 'unresolved', reason: analysis.reason, chain: [], depth };
+  }
+
+  const nextVisited = new Set(visited).add(key);
+  const sub = resolveTagTerminal(
+    file,
+    analysis.tag,
+    moduleGraph,
+    declsCache,
+    catalogByName,
+    pkgName,
+    workspace,
+    nextVisited,
+    depth + 1
+  );
+
+  const faithfulness = classifyFaithfulness({
+    augmenting: analysis.augmenting,
+    ...analyzeFaithfulness(analysis.node, declInfo.fnNode, declInfo.isForwardRef),
+  });
+
+  const hop = { file, localName, exportedAs: declInfo.exportedAs, faithfulness };
+  const chain = [hop, ...(sub.chain || [])];
+
+  return { ...sub, chain, depth: chain.length, warnDepth: chain.length > WARN_DEPTH };
+}
+
+function resolveTagTerminal(file, tagInfo, moduleGraph, declsCache, catalogByName, pkgName, workspace, visited, depth) {
+  const lookupName = tagInfo.name;
+
+  if (/^[a-z]/.test(lookupName)) {
+    return { terminal: 'native', tag: lookupName };
+  }
+
+  const fileDecls = getFileDecls(file, moduleGraph, declsCache);
+  if (fileDecls.has(lookupName)) {
+    return resolveWrapperChain(file, lookupName, moduleGraph, declsCache, catalogByName, pkgName, workspace, visited, depth);
+  }
+
+  const entry = moduleGraph.graph.get(file);
+  const binding = entry?.imports.get(lookupName);
+  if (!binding) {
+    return { terminal: 'unresolved', reason: 'not-found' };
+  }
+
+  const { source, imported } = binding;
+  if (!source.startsWith('.') && !source.startsWith('/')) {
+    if (source === pkgName && catalogByName.has(imported)) {
+      return { terminal: 'ds-component', component: imported };
+    }
+    const crossed = resolveWorkspacePackage(source, imported, workspace, catalogByName, pkgName, visited, depth);
+    if (crossed) return crossed;
+    return { terminal: 'third-party', pkg: source };
+  }
+  if (imported === '*') {
+    return { terminal: 'unresolved', reason: 'namespace-import' };
+  }
+
+  const resolvedFile = resolveRelativeFile(file, source);
+  if (!resolvedFile || !moduleGraph.graph.has(resolvedFile)) {
+    return { terminal: 'unresolved', reason: 'file-not-found' };
+  }
+
+  return resolveImportedSymbol(resolvedFile, imported, moduleGraph, declsCache, catalogByName, pkgName, workspace, visited, depth);
+}
+
+/**
+ * Shared tail for resolving a named export at a known file — used both for
+ * a same-repo relative import and, once a workspace-crossing import lands
+ * on a sibling package's entry file, for that sibling's own exports too.
+ * Not a local component export at `resolvedFile` could mean a pure
+ * re-export barrel hop (`export { Button } from '../wherever'`).
+ */
+function resolveImportedSymbol(resolvedFile, imported, moduleGraph, declsCache, catalogByName, pkgName, workspace, visited, depth) {
+  const targetDecls = getFileDecls(resolvedFile, moduleGraph, declsCache);
+  for (const [targetLocalName, info] of targetDecls) {
+    if (info.exportedAs === imported) {
+      return resolveWrapperChain(resolvedFile, targetLocalName, moduleGraph, declsCache, catalogByName, pkgName, workspace, visited, depth);
+    }
+  }
+
+  const deep = resolveOriginDeep(moduleGraph, resolvedFile, imported, { viaExport: true });
+  if (deep?.type === 'package') {
+    if (deep.pkg === pkgName && catalogByName.has(deep.name)) {
+      return { terminal: 'ds-component', component: deep.name };
+    }
+    const crossed = resolveWorkspacePackage(deep.pkg, deep.name, workspace, catalogByName, pkgName, visited, depth);
+    if (crossed) return crossed;
+    return { terminal: 'third-party', pkg: deep.pkg };
+  }
+  if (deep?.type === 'local') {
+    const deepDecls = getFileDecls(deep.file, moduleGraph, declsCache);
+    if (deepDecls.has(deep.name)) {
+      return resolveWrapperChain(deep.file, deep.name, moduleGraph, declsCache, catalogByName, pkgName, workspace, visited, depth);
+    }
+  }
+  if (deep?.cycle) return { terminal: 'cycle', cycle: deep.cycle };
+  return { terminal: 'unresolved', reason: 'unresolved-export' };
+}
+
+/**
+ * ADOPTION_APP_PLAN.md §3e: "the wrapper resolver must cross workspace
+ * boundaries inside a repo, resolving @acme/ui to its sibling source rather
+ * than treating it as an opaque third-party import." When an import's
+ * package name matches another discovered workspace target, builds (and
+ * caches) that sibling's own module graph and resolves the imported symbol
+ * inside it, so a chain can continue through a shared internal UI package
+ * instead of dead-ending at the workspace boundary. Returns null (not a
+ * workspace package, or entry file/graph unavailable) to fall through to
+ * the ordinary third-party terminal.
+ */
+function resolveWorkspacePackage(source, imported, workspace, catalogByName, pkgName, visited, depth) {
+  if (!workspace?.packages?.has(source)) return null;
+  const siblingDir = workspace.packages.get(source);
+  if (siblingDir === workspace.currentDir) return null; // a package importing its own name — not a crossing
+
+  const siblingPkgPath = path.join(siblingDir, 'package.json');
+  let siblingPkg = null;
+  try {
+    siblingPkg = existsSync(siblingPkgPath) ? JSON.parse(readFileSync(siblingPkgPath, 'utf-8')) : null;
+  } catch {
+    siblingPkg = null;
+  }
+  const entryFile = resolveEntryFile(siblingDir, siblingPkg);
+  if (!entryFile) return null;
+
+  const { moduleGraph: sibGraph, declsCache: sibDecls } = getWorkspaceGraph(workspace, siblingDir);
+  if (!sibGraph.graph.has(entryFile)) return null;
+
+  return resolveImportedSymbol(entryFile, imported, sibGraph, sibDecls, catalogByName, pkgName, workspace, visited, depth);
+}
+
+/**
+ * Resolves a package directory's public entry file from package.json's
+ * main/module/exports fields, falling back to the src/index.* convention
+ * this workspace's own packages use.
+ */
+function resolveEntryFile(dir, pkg) {
+  const candidates = [];
+  if (typeof pkg?.main === 'string') candidates.push(path.resolve(dir, pkg.main));
+  if (typeof pkg?.module === 'string') candidates.push(path.resolve(dir, pkg.module));
+  const exp = pkg?.exports;
+  if (typeof exp === 'string') candidates.push(path.resolve(dir, exp));
+  else if (exp && typeof exp === 'object') {
+    const dot = exp['.'];
+    if (typeof dot === 'string') candidates.push(path.resolve(dir, dot));
+    else if (dot && typeof dot === 'object') {
+      const val = dot.import || dot.require || dot.default;
+      if (typeof val === 'string') candidates.push(path.resolve(dir, val));
+    }
+  }
+  candidates.push(path.join(dir, 'src', 'index'), path.join(dir, 'index'));
+
+  for (const base of candidates) {
+    const tries = [base, ...EXTENSIONS.map((ext) => base + ext), ...EXTENSIONS.map((ext) => path.join(base, 'index' + ext))];
+    for (const candidate of tries) {
+      if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+    }
+  }
+  return null;
+}
+
+/** Lazily builds and caches a sibling workspace package's own module graph. */
+function getWorkspaceGraph(workspace, dir) {
+  if (workspace.graphs.has(dir)) return workspace.graphs.get(dir);
+  const entry = { moduleGraph: buildModuleGraph(dir, {}), declsCache: new Map() };
+  workspace.graphs.set(dir, entry);
+  return entry;
+}
+
+function resolveRelativeFile(fromFile, specifier) {
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  const candidates = [base, ...EXTENSIONS.map((ext) => base + ext), ...EXTENSIONS.map((ext) => path.join(base, 'index' + ext))];
+  for (const candidate of candidates) {
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  }
+  return null;
+}
+
+// ───────────────────────────── fanout counting ─────────────────────────────
+
+/**
+ * Counts, for each tracked wrapper (file+exportedAs key), how many places in
+ * the repo reference it — reusing referenceResolver.js's exact reference-kind
+ * classification so a wrapper's fanout and a catalog component's direct
+ * fanout are always counted the same way.
+ *
+ * `internalConsumers` excludes the wiring reference a parent wrapper makes to
+ * its own child wrapper (e.g. A's file rendering <B/> as A's implementation)
+ * from B's fanout — that reference is the chain edge itself, not an external
+ * usage, and is already reflected in A's own separately-tracked chain. A
+ * wrapper file that happens to *also* have an unrelated second reference to
+ * the same target is excluded too — a known v1 simplification.
+ */
+function computeFanouts(root, moduleGraph, trackedKeys, internalConsumers) {
+  const results = new Map(
+    [...trackedKeys].map((k) => [k, { counts: { jsx: 0, createElement: 0, hoc: 0, indirect: 0, reexport: 0 }, sites: [] }])
+  );
+
+  for (const file of moduleGraph.files) {
+    const entry = moduleGraph.graph.get(file);
+    if (!entry || entry.parseError) continue;
+
+    const localToKey = new Map();
+    for (const localName of entry.imports.keys()) {
+      const origin = resolveOriginDeep(moduleGraph, file, localName);
+      if (origin?.type !== 'local') continue;
+      const key = `${origin.file}#${origin.name}`;
+      if (!trackedKeys.has(key)) continue;
+      const excluded = internalConsumers.get(key);
+      if (excluded && excluded.has(file)) continue;
+      localToKey.set(localName, key);
+    }
+    if (localToKey.size === 0) continue;
+
+    traverse(entry.ast, {
+      Program(programPath) {
+        for (const [localName, key] of localToKey) {
+          const binding = programPath.scope.getBinding(localName);
+          if (!binding) continue;
+          const result = results.get(key);
+          for (const refPath of binding.referencePaths) {
+            const kind = classifyReference(refPath);
+            if (!kind) continue;
+            result.counts[kind] += 1;
+            result.sites.push({
+              file: path.relative(root, file),
+              line: refPath.node.loc?.start.line ?? null,
+              kind,
+              confidence: KIND_CONFIDENCE[kind],
+            });
+          }
+        }
+      },
+    });
+  }
+
+  return results;
+}
+
+// ───────────────────────────── dominion.config.json declared wrappers ─────────────────────────────
+
+function loadDominionConfig(root) {
+  const configPath = path.join(root, 'dominion.config.json');
+  if (!existsSync(configPath)) return { wrappers: {} };
+  try {
+    const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+    return { wrappers: raw.wrappers && typeof raw.wrappers === 'object' ? raw.wrappers : {} };
+  } catch {
+    return { wrappers: {} };
+  }
+}
+
+function resolveConfigFile(root, relPath) {
+  const base = path.resolve(root, relPath);
+  const candidates = [base, ...EXTENSIONS.map((ext) => base + ext), ...EXTENSIONS.map((ext) => path.join(base, 'index' + ext))];
+  for (const candidate of candidates) {
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  }
+  return null;
+}
+
+/**
+ * A declared file may export more than one component-shaped symbol, so pick
+ * "the" one deterministically: default export, else an export matching the
+ * file's own basename, else the first component export found.
+ */
+function pickWrapperExport(fileDecls, filePath) {
+  const base = path.basename(filePath).replace(/\.(jsx|tsx|js|ts|mjs|cjs)$/, '');
+  let fallback = null;
+  for (const [localName, info] of fileDecls) {
+    if (!info.exportedAs) continue;
+    if (info.exportedAs === 'default') return { localName, info };
+    if (localName === base || info.exportedAs === base) return { localName, info };
+    if (!fallback) fallback = { localName, info };
+  }
+  return fallback;
+}
+
+// ───────────────────────────── assembly ─────────────────────────────
+
+/**
+ * Resolves every exported wrapper component in a consumer repo down to its
+ * root terminal (a DS component, a native/intrinsic element, a third-party
+ * component, or unresolved/cycle), classifies how faithfully each wrapper
+ * passes through the DS component it wraps, counts how many places each
+ * wrapper is itself used, and left-joins the DS-terminal wrappers onto the
+ * catalog — same shape convention as resolveReferences (ADOPTION_APP_PLAN.md
+ * §4 blind spot 3: "adoption hidden behind indirection").
+ *
+ * `workspacePackages` (optional `Map<packageName, absoluteDir>`) enables
+ * cross-workspace resolution (ADOPTION_APP_PLAN.md §3e): a third-party
+ * import whose source matches another discovered workspace target's own
+ * package name is resolved into that sibling's source instead of
+ * terminating at the workspace boundary. Omit it for single-repo scans.
+ */
+export function resolveWrappers(root, { platform = 'web', ignore = [], workspacePackages = null } = {}) {
+  const pkgName = packageNameForPlatform(platform);
+  const catalog = loadCatalog(platform);
+  const catalogByName = new Map(catalog.components.map((c) => [c.name, c]));
+
+  const moduleGraph = buildModuleGraph(root, { ignore });
+  const declsCache = new Map();
+  const workspace = {
+    packages: workspacePackages || new Map(),
+    currentDir: root,
+    graphs: new Map([[root, { moduleGraph, declsCache }]]),
+  };
+
+  // Pass 1 — resolve a chain for every exported component decl in the repo.
+  const exportedDecls = [];
+  for (const file of moduleGraph.files) {
+    const entry = moduleGraph.graph.get(file);
+    if (!entry || entry.parseError) continue;
+    const decls = getFileDecls(file, moduleGraph, declsCache);
+    for (const [localName, info] of decls) {
+      if (!info.exportedAs) continue;
+      exportedDecls.push({ file, localName, exportedAs: info.exportedAs });
+    }
+  }
+
+  const autoResults = new Map();
+  for (const { file, localName, exportedAs } of exportedDecls) {
+    autoResults.set(
+      `${file}#${exportedAs}`,
+      resolveWrapperChain(file, localName, moduleGraph, declsCache, catalogByName, pkgName, workspace)
+    );
+  }
+
+  // Internal-consumer edges: for every chain, each hop's file "internally
+  // consumes" the next hop's export — exclude those sites from that next
+  // wrapper's own fanout count (see computeFanouts's docstring).
+  const internalConsumers = new Map();
+  for (const result of autoResults.values()) {
+    const chain = result.chain || [];
+    for (let i = 0; i < chain.length - 1; i++) {
+      const consumerFile = chain[i].file;
+      const target = chain[i + 1];
+      if (!target.exportedAs) continue;
+      const targetKey = `${target.file}#${target.exportedAs}`;
+      if (!internalConsumers.has(targetKey)) internalConsumers.set(targetKey, new Set());
+      internalConsumers.get(targetKey).add(consumerFile);
+    }
+  }
+
+  // dominion.config.json — declared wrappers fill gaps, never override a
+  // contradicting auto-detected terminal.
+  const dominionConfig = loadDominionConfig(root);
+  const declaredEntries = [];
+  const contradictions = [];
+  const unresolvedDeclarations = [];
+
+  for (const [relPath, componentName] of Object.entries(dominionConfig.wrappers)) {
+    const resolvedFile = resolveConfigFile(root, relPath);
+    if (!resolvedFile || !moduleGraph.graph.has(resolvedFile)) {
+      unresolvedDeclarations.push({ configPath: relPath, componentName, reason: 'file-not-found' });
+      continue;
+    }
+    const fileDecls = getFileDecls(resolvedFile, moduleGraph, declsCache);
+    const picked = pickWrapperExport(fileDecls, resolvedFile);
+    if (!picked) {
+      unresolvedDeclarations.push({ configPath: relPath, componentName, reason: 'no-component-export-found' });
+      continue;
+    }
+
+    const key = `${resolvedFile}#${picked.info.exportedAs}`;
+    const auto = autoResults.get(key);
+
+    if (auto?.terminal === 'ds-component') {
+      if (auto.component !== componentName) {
+        contradictions.push({
+          file: resolvedFile,
+          exportedAs: picked.info.exportedAs,
+          declaredAs: componentName,
+          autoDetected: auto.component,
+        });
+      }
+      continue; // already auto-verified either way — nothing to add
+    }
+    if (auto?.terminal === 'native' || auto?.terminal === 'third-party') {
+      contradictions.push({
+        file: resolvedFile,
+        exportedAs: picked.info.exportedAs,
+        declaredAs: componentName,
+        autoDetected: auto.terminal,
+      });
+      continue;
+    }
+    if (!catalogByName.has(componentName)) {
+      unresolvedDeclarations.push({ configPath: relPath, componentName, reason: 'unknown-catalog-component' });
+      continue;
+    }
+
+    // auto-detection came back unresolved/cycle/missing — the declaration fills the gap.
+    declaredEntries.push({
+      file: resolvedFile,
+      exportedAs: picked.info.exportedAs,
+      localName: picked.localName,
+      terminal: 'ds-component',
+      component: componentName,
+      chain: [{ file: resolvedFile, localName: picked.localName, exportedAs: picked.info.exportedAs, faithfulness: 'unknown' }],
+      depth: 1,
+      warnDepth: false,
+      provenance: 'declared',
+    });
+  }
+
+  // Auto-verified wrappers — only entries that actually resolve to a DS component.
+  const wrapperKeys = new Set();
+  const autoWrappers = [];
+  for (const { file, localName, exportedAs } of exportedDecls) {
+    const key = `${file}#${exportedAs}`;
+    const result = autoResults.get(key);
+    if (result?.terminal === 'ds-component') {
+      wrapperKeys.add(key);
+      autoWrappers.push({
+        file,
+        exportedAs,
+        localName,
+        terminal: 'ds-component',
+        component: result.component,
+        chain: result.chain,
+        depth: result.depth,
+        warnDepth: result.warnDepth,
+        provenance: 'auto-verified',
+      });
+    }
+  }
+  for (const declared of declaredEntries) wrapperKeys.add(`${declared.file}#${declared.exportedAs}`);
+
+  const unresolvedKeys = [];
+  for (const { file, exportedAs } of exportedDecls) {
+    const key = `${file}#${exportedAs}`;
+    const result = autoResults.get(key);
+    if (result?.terminal === 'unresolved' || result?.terminal === 'cycle') unresolvedKeys.push(key);
+  }
+
+  const trackedKeys = new Set([...wrapperKeys, ...unresolvedKeys]);
+  const fanoutResults = computeFanouts(root, moduleGraph, trackedKeys, internalConsumers);
+
+  const emptyFanout = { counts: { jsx: 0, createElement: 0, hoc: 0, indirect: 0, reexport: 0 }, sites: [] };
+  const allWrappers = [...autoWrappers, ...declaredEntries].map((w) => {
+    const key = `${w.file}#${w.exportedAs}`;
+    const fanout = fanoutResults.get(key) || emptyFanout;
+    return { ...w, file: path.relative(root, w.file), fanout };
+  });
+
+  // Rollup per catalog component — left-joined, so zero-adoption-via-wrapper
+  // components still appear.
+  const byComponent = new Map(
+    catalog.components.map((c) => [
+      c.name,
+      { name: c.name, slug: c.slug, viaWrappers: [], totalFanout: { jsx: 0, createElement: 0, hoc: 0, indirect: 0 } },
+    ])
+  );
+  for (const w of allWrappers) {
+    const bucket = byComponent.get(w.component);
+    if (!bucket) continue;
+    bucket.viaWrappers.push({
+      file: w.file,
+      exportedAs: w.exportedAs,
+      faithfulness: w.chain[0]?.faithfulness ?? 'unknown',
+      depth: w.depth,
+      warnDepth: w.warnDepth,
+      provenance: w.provenance,
+      fanout: w.fanout.counts,
+    });
+    bucket.totalFanout.jsx += w.fanout.counts.jsx;
+    bucket.totalFanout.createElement += w.fanout.counts.createElement;
+    bucket.totalFanout.hoc += w.fanout.counts.hoc;
+    bucket.totalFanout.indirect += w.fanout.counts.indirect;
+  }
+
+  // Provenance triple (ADOPTION_APP_PLAN.md's dominion.config.json section) —
+  // approximated at the wrapper level: sum each wrapper's counted (jsx +
+  // createElement + hoc) fanout, grouped by how its own terminal was found.
+  let autoVerifiedSites = 0;
+  let declaredSites = 0;
+  for (const w of allWrappers) {
+    const counted = w.fanout.counts.jsx + w.fanout.counts.createElement + w.fanout.counts.hoc;
+    if (w.provenance === 'auto-verified') autoVerifiedSites += counted;
+    else declaredSites += counted;
+  }
+  let unresolvedSites = 0;
+  for (const key of unresolvedKeys) {
+    const f = fanoutResults.get(key);
+    if (f) unresolvedSites += f.counts.jsx + f.counts.createElement + f.counts.hoc;
+  }
+
+  return {
+    platform,
+    package: pkgName,
+    root,
+    scannedFiles: moduleGraph.files.length,
+    wrappers: allWrappers,
+    byComponent: [...byComponent.values()].sort((a, b) => a.name.localeCompare(b.name)),
+    contradictions,
+    unresolvedDeclarations,
+    provenanceTriple: { autoVerified: autoVerifiedSites, declared: declaredSites, unresolved: unresolvedSites },
+    dominionConfigFound: Object.keys(dominionConfig.wrappers).length > 0,
+  };
+}