@starklab/stark-mcp 0.2.0 → 0.3.0

package/src/adopt/findingSnippet.js

@@ -0,0 +1,386 @@
+import path from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { stkRoot } from '../data.js';
+import { loadTokenInventory } from './tokenAliasResolver.js';
+
+/**
+ * Captures the source a finding is actually about — the "wrong" side — and,
+ * where the fix is *derivable rather than guessed*, the "right" side next to
+ * it. This is what turns a finding from a coordinate ("drift-behind-alias at
+ * PromoBanner.tsx:24") into something a developer can act on without leaving
+ * the tracker.
+ *
+ * Three constraints shape everything below.
+ *
+ * 1. **Source code leaving the customer's machine is a new data flow.** Every
+ *    other field a scan reports is a name, a count, or a coordinate; this is
+ *    the first one that carries the customer's own code. So it is bounded on
+ *    three axes — `CONTEXT_LINES` around the finding, `MAX_LINE_LENGTH` per
+ *    line, `MAX_SNIPPETS` per scan — and it is opt-out at the CLI
+ *    (`stark-cli adopt --no-snippets`), which skips this module entirely and
+ *    leaves the rest of the report byte-identical.
+ *
+ * 2. **The "right" side is never invented.** A wrong snippet is an observation;
+ *    a right one is a claim about what the code should say, and a plausible
+ *    wrong answer there is worse than no answer. So `after` is produced only
+ *    by a literal substitution the token build itself proves — a value that
+ *    resolves to exactly one semantic token — and is `null` for every rule and
+ *    every value where it doesn't. Two of the nine rules that carry a location
+ *    can ever produce one (see DERIVABLE_RULES); the other seven get a wrong
+ *    side and an honest empty right side.
+ *
+ * 3. **It must never break a scan.** An unreadable file, a missing token
+ *    build, a line number past the end of the file: each drops that one
+ *    snippet and nothing else. Nothing here throws.
+ */
+
+// Lines of context on each side of the offending line. Two is enough to see
+// the declaration's block without shipping a whole function body.
+const CONTEXT_LINES = 2;
+// Long minified or generated lines are truncated rather than dropped — the
+// finding is still worth showing, the tail of a 4000-column bundle line is not.
+const MAX_LINE_LENGTH = 200;
+// Whole-scan budget. A repo with thousands of findings would otherwise turn a
+// small JSON report into a partial copy of its own source tree.
+const MAX_SNIPPETS = 200;
+
+// What the inline `// annotation` on the highlighted line says. Keyed by rule,
+// because the annotation is the one-line explanation of *why* that line is
+// highlighted, and that differs per rule even when the capture doesn't.
+const RULE_ANNOTATIONS = {
+  'drift-behind-alias': { before: 'hardcoded value', after: 'design system token' },
+  'layer-violation': { before: 'primitive token — skips the semantic layer', after: 'semantic token' },
+  'broken-alias': { before: 'alias chain never resolves' },
+  'unresolved-alias': { before: 'alias target not found in the scanned files' },
+  'raw-fallback': { before: 'raw fallback value' },
+  'style-escape-hatch': { before: 'inline style bypasses the component API' },
+  'deprecated-prop-passed': { before: 'deprecated prop' },
+  'invalid-enum-value': { before: 'value outside the prop enum' },
+  'required-prop-missing': { before: 'required prop missing' },
+};
+
+// The only two rules whose fix is a substitution rather than a judgement.
+// `drift-behind-alias` says a declaration bottoms out in a raw value, and
+// `layer-violation` says it bottoms out in a primitive — in both cases the
+// correct replacement is a semantic token with the same resolved value, which
+// the token build can be asked for. Every other rule needs a decision
+// (which prop, which enum member, which component) that this module has no
+// basis to make.
+const DERIVABLE_RULES = new Set(['drift-behind-alias', 'layer-violation']);
+
+// ---------------------------------------------------------------------------
+// Token values
+// ---------------------------------------------------------------------------
+
+function normalizeValue(value) {
+  const v = String(value).trim().toLowerCase().replace(/\s+/g, ' ');
+  // #abc and #aabbcc are the same colour and the build emits both forms.
+  const short = v.match(/^#([0-9a-f])([0-9a-f])([0-9a-f])$/);
+  return short ? `#${short[1]}${short[1]}${short[2]}${short[2]}${short[3]}${short[3]}` : v;
+}
+
+/**
+ * literal value -> the tokens a consumer should be writing instead, from the
+ * built `tokens.css`.
+ *
+ * Two layers are indexed, and the split is not arbitrary. Colour has a real
+ * semantic layer (`surface/*`, `text/*`, `border/*`, `icon/*`, `state/*`), so
+ * a colour suggestion is a semantic token and a primitive shade is exactly the
+ * thing `layer-violation` reports — never a suggestion. Dimensions have no
+ * semantic layer at all: `radius/md`, `spacing/xs` and the type scale live in
+ * `tokens/base/` and *are* the published vocabulary (CLAUDE.md's own
+ * "semantic tokens quick reference" lists them), so for a length the primitive
+ * is the honest answer. Hence: every semantic token, plus every primitive
+ * whose value is not a colour.
+ *
+ * Component tokens are excluded from both — suggesting `--stk-button-bg` for a
+ * consumer's own property would bind their code to another component's slot.
+ *
+ * Returns an empty index rather than throwing when the consumer has no token
+ * build — then nothing is derivable and every snippet is wrong-side only.
+ */
+function isColorValue(value) {
+  return /^(#|rgb|hsl|color\()/i.test(String(value).trim());
+}
+
+export function loadTokenValueIndex(stkPkgRoot) {
+  const empty = { byValue: new Map(), declared: new Map(), resolve: () => null };
+  const cssPath = path.join(stkPkgRoot, 'build', 'css', 'tokens.css');
+  if (!existsSync(cssPath)) return empty;
+
+  let src;
+  let layers;
+  try {
+    src = readFileSync(cssPath, 'utf-8');
+    ({ layers } = loadTokenInventory(stkPkgRoot));
+  } catch {
+    return empty;
+  }
+
+  const declared = new Map();
+  for (const m of src.matchAll(/(--stk-[\w-]+)\s*:\s*([^;]+);/g)) declared.set(m[1], m[2].trim());
+
+  // The build's own var() chains have to be followed to a literal, or a
+  // semantic token that aliases a primitive would index under the string
+  // "var(--stk-…)" and match nothing a consumer ever writes.
+  const resolve = (name, seen) => {
+    if (seen.has(name)) return null;
+    seen.add(name);
+    const value = declared.get(name);
+    if (!value) return null;
+    const ref = value.match(/^var\(\s*(--stk-[\w-]+)\s*\)$/);
+    return ref ? resolve(ref[1], seen) : value;
+  };
+
+  const byValue = new Map();
+  for (const name of declared.keys()) {
+    const layer = layers.get(name);
+    if (layer !== 'semantic' && layer !== 'primitive') continue;
+    const literal = resolve(name, new Set());
+    if (!literal) continue;
+    if (layer === 'primitive' && isColorValue(literal)) continue;
+    const key = normalizeValue(literal);
+    if (!byValue.has(key)) byValue.set(key, []);
+    byValue.get(key).push(name);
+  }
+  return { byValue, declared, resolve: (name) => resolve(name, new Set()) };
+}
+
+// The token family a declaration is asking for, read off the words its author
+// already wrote. This is the only tie-breaker between equal-valued tokens, and
+// it exists because a bare value is genuinely ambiguous: `8px` is a radius, a
+// spacing step *and* a border width in this scale, and `#aaaaaa` is a surface,
+// a border and a press state.
+//
+// Ordered, and the order is the whole content of the table: `borderRadius` is
+// a radius before it is a border, and `backgroundColor` is a surface before it
+// is a colour. First match wins; a hint that matches nothing gets no
+// suggestion rather than an arbitrary one.
+const FAMILY_RULES = [
+  [/background|(^|[^a-z])bg([^a-z]|$)|surface/, 'surface'],
+  [/radius|rounded/, 'radius'],
+  [/border-?width|outline-?width|stroke-?width/, 'border-width'],
+  [/border|outline|stroke|divider/, 'border'],
+  [/gap|padding|margin|inset|spacing|space/, 'spacing'],
+  [/font-?size|text-?size|type-?size/, 'typography-size'],
+  [/icon/, 'icon'],
+  [/shadow|elevation/, 'shadow'],
+  [/duration|delay|easing|motion|transition/, 'motion'],
+  [/opacity/, 'opacity'],
+  [/colou?r|text|label|title|copy|foreground/, 'text'],
+];
+
+export function tokenFamilyFor(...hints) {
+  const text = hints
+    .filter(Boolean)
+    .join(' ')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase();
+  for (const [pattern, family] of FAMILY_RULES) {
+    if (pattern.test(text)) return family;
+  }
+  return null;
+}
+
+/**
+ * The replacement token for `value`, or null when there isn't exactly one
+ * honest answer.
+ *
+ * Two gates, both of which must pass. The value has to resolve to a token that
+ * exists — no rounding to the nearest step, since a `12px` in a scale that
+ * publishes 8 and 16 is a decision only the author can make — and the family
+ * that value belongs to has to be identifiable from the declaration and has to
+ * leave exactly one candidate. Anything else returns null, and the finding is
+ * reported with a wrong side and no right side.
+ */
+export function suggestReplacementToken(value, hints, tokenValues) {
+  if (!tokenValues || !tokenValues.byValue) return null;
+
+  // A token reference resolves through the build first (layer-violation), a
+  // literal is looked up as written (drift-behind-alias).
+  const ref = String(value).trim().match(/^var\(\s*(--stk-[\w-]+)\s*\)$/);
+  const literal = ref ? tokenValues.resolve(ref[1]) : value;
+  if (!literal) return null;
+
+  const candidates = (tokenValues.byValue.get(normalizeValue(literal)) ?? [])
+    // Replacing a token with itself is not a fix.
+    .filter((c) => !ref || c !== ref[1]);
+  if (candidates.length === 0) return null;
+
+  // The family filter runs even when only one candidate survived the value
+  // lookup, and that is deliberate: `12px` happens to be exactly
+  // `--stk-spacing-sm` and is not a radius in this scale at all, so a lone
+  // match from the wrong family is a confident wrong answer, not a lucky one.
+  const family = tokenFamilyFor(...hints);
+  if (family) {
+    const narrowed = candidates.filter((c) => c.startsWith(`--stk-${family}-`));
+    return narrowed.length === 1 ? narrowed[0] : null;
+  }
+  return candidates.length === 1 ? candidates[0] : null;
+}
+
+// ---------------------------------------------------------------------------
+// Source capture
+// ---------------------------------------------------------------------------
+
+/**
+ * The name and value a declaration assigns, in either of the two languages a
+ * finding can point at: a CSS declaration (`--promo-radius: 12px;`) and a
+ * JS/JSX style-object entry (`borderRadius: '12px' }}>`). Both halves are
+ * returned: the value is what gets substituted, the name is what disambiguates
+ * which token to substitute it with.
+ */
+export function extractDeclaredValue(line) {
+  const text = String(line);
+  const idx = text.indexOf(':');
+  if (idx < 0) return null;
+
+  const name = text.slice(0, idx).replace(/[^\w-]+/g, ' ').trim();
+  const rest = text.slice(idx + 1).trim();
+  if (!rest) return null;
+
+  // A quoted value ends at its own closing quote, so whatever follows it —
+  // `}}>`, a comma, a JSX tail — is not part of the value and needs no
+  // balancing pass.
+  const quoted = rest.match(/^(['"`])(.*?)\1/);
+  if (quoted) return { name, value: quoted[2], quote: quoted[1] };
+
+  // Otherwise strip the statement terminator, then peel closers that belong to
+  // an expression opened outside this value — but only while they are actually
+  // unbalanced, or `rgb(0, 0, 0)` would lose its own parenthesis.
+  const openerFor = { '}': '{', ')': '(', ']': '[' };
+  let value = rest.replace(/[;,]\s*$/, '').trim();
+  for (;;) {
+    const last = value[value.length - 1];
+    if (last === '>') { value = value.slice(0, -1).trim(); continue; }
+    const opener = openerFor[last];
+    if (opener && value.split(last).length > value.split(opener).length) {
+      value = value.slice(0, -1).replace(/[;,]\s*$/, '').trim();
+      continue;
+    }
+    break;
+  }
+  return value ? { name, value, quote: '' } : null;
+}
+
+function truncate(line) {
+  return line.length > MAX_LINE_LENGTH ? `${line.slice(0, MAX_LINE_LENGTH)}…` : line;
+}
+
+// Strips the shared leading indentation so a snippet from a deeply nested
+// block doesn't spend half its width on whitespace. Blank lines are ignored
+// when measuring, or a single empty line would pin the indent at zero.
+function dedent(lines) {
+  const indents = lines.filter((l) => l.trim()).map((l) => l.match(/^[ \t]*/)[0].length);
+  const common = indents.length ? Math.min(...indents) : 0;
+  return common ? lines.map((l) => l.slice(common)) : lines;
+}
+
+function readLines(absPath, cache) {
+  if (cache.has(absPath)) return cache.get(absPath);
+  let lines = null;
+  try {
+    lines = readFileSync(absPath, 'utf-8').split(/\r?\n/);
+  } catch {
+    lines = null;
+  }
+  cache.set(absPath, lines);
+  return lines;
+}
+
+function relativeFile(absPath, root) {
+  const rel = path.relative(root, absPath).split(path.sep).join('/');
+  // A finding outside the scan root has no meaningful project-relative path,
+  // and the absolute one is exactly what must not be shipped.
+  return !rel || rel.startsWith('..') ? path.basename(absPath) : rel;
+}
+
+/**
+ * The snippet for one finding, or null when there is nothing honest to show:
+ * no location, an unreadable file, or a line number the file doesn't have.
+ */
+export function captureFindingSnippet(finding, { root, tokenValues = null, cache = new Map() } = {}) {
+  const { file, line } = finding ?? {};
+  if (typeof file !== 'string' || !file || typeof line !== 'number' || line < 1) return null;
+
+  const absPath = path.isAbsolute(file) ? file : path.join(root, file);
+  const lines = readLines(absPath, cache);
+  if (!lines || line > lines.length) return null;
+
+  const index = line - 1;
+  const start = Math.max(0, index - CONTEXT_LINES);
+  const end = Math.min(lines.length - 1, index + CONTEXT_LINES);
+  const before = dedent(lines.slice(start, end + 1)).map(truncate);
+  const highlightIndex = index - start;
+
+  const annotations = RULE_ANNOTATIONS[finding.rule] ?? {};
+  let after = null;
+  let afterAnnotation = null;
+
+  if (DERIVABLE_RULES.has(finding.rule)) {
+    const declared = extractDeclaredValue(before[highlightIndex]);
+    const token = declared
+      ? suggestReplacementToken(declared.value, [finding.property, finding.prop, declared.name], tokenValues)
+      : null;
+    if (token && declared) {
+      const replacement = `var(${token})`;
+      after = before.map((l, i) => (i === highlightIndex ? l.replace(declared.value, replacement) : l));
+      // A no-op replacement means the value wasn't where it was parsed from —
+      // better to show no right side than an identical one labelled as a fix.
+      if (after[highlightIndex] === before[highlightIndex]) after = null;
+      else afterAnnotation = annotations.after ?? 'design system token';
+    }
+  }
+
+  return {
+    file: relativeFile(absPath, root),
+    before,
+    after,
+    highlightIndex,
+    beforeAnnotation: annotations.before ?? finding.rule,
+    afterAnnotation,
+  };
+}
+
+/**
+ * Walks a `runAdopt` result and attaches a `snippet` to every finding that can
+ * have one. Returns a new object; the input is not mutated.
+ *
+ * Keyed on the shape rather than on a list of resolvers: every resolver that
+ * reports defects does so under a `findings` array, and a new one gets this for
+ * free rather than by remembering to register itself here.
+ */
+export function attachFindingSnippets(result, { root, stkPkgRoot = null, maxSnippets = MAX_SNIPPETS } = {}) {
+  let tokenValues = null;
+  try {
+    tokenValues = loadTokenValueIndex(stkPkgRoot ?? stkRoot());
+  } catch {
+    tokenValues = null;
+  }
+
+  const cache = new Map();
+  let remaining = maxSnippets;
+
+  const walk = (value) => {
+    if (Array.isArray(value)) return value.map(walk);
+    if (!value || typeof value !== 'object') return value;
+
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (key === 'findings' && Array.isArray(child)) {
+        out[key] = child.map((finding) => {
+          if (remaining <= 0 || !finding || typeof finding !== 'object') return finding;
+          const snippet = captureFindingSnippet(finding, { root, tokenValues, cache });
+          if (!snippet) return finding;
+          remaining -= 1;
+          return { ...finding, snippet };
+        });
+      } else {
+        out[key] = walk(child);
+      }
+    }
+    return out;
+  };
+
+  return walk(result);
+}

package/src/adopt/foreignDiscoveryResolver.js

@@ -154,7 +154,7 @@ function hasComponentExport(ast) {
 
 /**
  * Component enumeration — walks for componentDir matches (e.g.
- * components/ui), then parses each .tsx/.jsx directly inside and keeps
+ * components/ui), then parses every .tsx/.jsx beneath one and keeps
  * only files with a real component export. This is literally reading a
  * conventional folder shadcn always writes to, not import-usage detection
  * — a consumer who renamed or restructured that folder produces zero
@@ -174,7 +174,20 @@ function enumerateComponents(root, ignore, system) {
   const unresolvedFiles = [];
 
   for (const dir of dirs) {
-    const files = fg.sync(['*.tsx', '*.jsx'], { cwd: dir, absolute: true });
+    // Recursive, not flat. shadcn's own CLI writes flat into components/ui,
+    // but consumers group related files into a subfolder and those are
+    // still the catalog: openstatusHQ/openstatus's apps/dashboard keeps 8
+    // of its 10 components/ui files under a data-table/ subdir, and a flat
+    // read reported "2 available, 2 used, 100% coverage" for it — a number
+    // that reads as complete adoption while missing 80% of the folder.
+    // hasComponentExport() below is what keeps the wider net honest; test
+    // and story files are dropped by name since a story does export a
+    // component-shaped value.
+    const files = fg.sync(['**/*.tsx', '**/*.jsx'], {
+      cwd: dir,
+      absolute: true,
+      ignore: [...DEFAULT_IGNORE, '**/*.test.*', '**/*.spec.*', '**/*.stories.*'],
+    });
     for (const file of files) {
       let code;
       try {
@@ -190,8 +203,12 @@ function enumerateComponents(root, ignore, system) {
         continue;
       }
       if (!hasComponentExport(ast)) continue;
+      // A file directly in the dir keeps its bare basename; one in a
+      // subfolder carries the subfolder so two "data-table" rows can't
+      // appear side by side with nothing to tell them apart.
+      const withinDir = path.relative(dir, file);
       components.push({
-        name: path.basename(file, path.extname(file)),
+        name: withinDir.replace(/\.(tsx|jsx)$/, '').split(path.sep).join('/'),
         file: path.relative(root, file),
       });
     }

package/src/adopt/foreignScoringResolver.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { getForeignSystem } from './foreignSystemConfig.js';
 import { buildModuleGraph, resolveCandidateFile, resolveRelative } from './moduleGraph.js';
 import { resolveOpportunities } from './opportunityResolver.js';
+import { discoverTargets, workspacePackageMap } from './targetDiscovery.js';
 
 // Strips // and block comments from JSONC source, string-literal-aware — a
 // naive regex stripper is NOT safe here: a first attempt matched the block-
@@ -49,8 +50,16 @@ function stripJsonComments(src) {
   return out;
 }
 
+function readJson(file) {
+  try {
+    return JSON.parse(stripJsonComments(readFileSync(file, 'utf-8')).replace(/,(\s*[}\]])/g, '$1'));
+  } catch {
+    return null;
+  }
+}
+
 /**
- * Reads compilerOptions.paths/baseUrl from the target's own tsconfig.json
+ * Reads compilerOptions.paths/baseUrl from one directory's own tsconfig.json
  * (falling back to jsconfig.json). A live run against shadcn-ui/taxonomy
  * caught the reason this exists: every real Next.js + shadcn consumer
  * imports its own components via the `@/*` alias (`create-next-app`'s and
@@ -60,27 +69,58 @@ function stripJsonComments(src) {
  * JSON; a config that still fails to parse just yields no aliases, same as
  * a repo with no path aliases at all.
  */
-function loadPathAliases(root) {
+function loadPathAliases(dir) {
   for (const name of ['tsconfig.json', 'jsconfig.json']) {
-    const file = path.join(root, name);
+    const file = path.join(dir, name);
     if (!existsSync(file)) continue;
-    try {
-      const raw = stripJsonComments(readFileSync(file, 'utf-8')).replace(/,(\s*[}\]])/g, '$1');
-      const json = JSON.parse(raw);
-      const paths = json.compilerOptions?.paths;
-      if (!paths) continue;
-      return { baseUrl: json.compilerOptions?.baseUrl || '.', paths };
-    } catch {
-      continue;
+    const json = readJson(file);
+    const paths = json?.compilerOptions?.paths;
+    if (!paths) continue;
+    return { dir, baseUrl: json.compilerOptions?.baseUrl || '.', paths };
+  }
+  return null;
+}
+
+/**
+ * The tsconfig that actually governs one file: the nearest one at or above
+ * it, not the one at the scan root. Reading the root's alone is correct for
+ * a single-package repo and wrong for every monorepo — measured live against
+ * openstatusHQ/openstatus, which has *no* tsconfig.json at its root at all
+ * and declares `@/*` separately in each of apps/dashboard, apps/web and
+ * apps/status-page. Scanning it from the root therefore resolved zero `@/*`
+ * imports, and components with 29 and 10 real usages (checkbox-tree,
+ * sortable) scored 0 — the same components scored correctly when the scan
+ * was pointed at apps/dashboard directly. Results are memoised per
+ * directory, including the negative one, so the walk runs once per dir
+ * rather than once per file.
+ */
+function nearestPathAliases(root, file, cache) {
+  const chain = [];
+  let dir = path.dirname(file);
+  for (;;) {
+    if (cache.has(dir)) {
+      const hit = cache.get(dir);
+      for (const d of chain) cache.set(d, hit);
+      return hit;
     }
+    chain.push(dir);
+    const found = loadPathAliases(dir);
+    if (found) {
+      for (const d of chain) cache.set(d, found);
+      return found;
+    }
+    const parent = path.dirname(dir);
+    if (dir === root || parent === dir || !dir.startsWith(root)) break;
+    dir = parent;
   }
+  for (const d of chain) cache.set(d, null);
   return null;
 }
 
 /** Resolves a bare specifier (e.g. "@/components/ui/button") against tsconfig paths, if any match. */
-function resolveAliasedImport(root, aliases, specifier) {
+function resolveAliasedImport(aliases, specifier) {
   if (!aliases) return null;
-  const base = path.resolve(root, aliases.baseUrl);
+  const base = path.resolve(aliases.dir, aliases.baseUrl);
   for (const [pattern, targets] of Object.entries(aliases.paths)) {
     if (pattern.endsWith('/*')) {
       const prefix = pattern.slice(0, -2);
@@ -100,21 +140,103 @@ function resolveAliasedImport(root, aliases, specifier) {
   return null;
 }
 
+/** Splits "@scope/pkg/a/b" into { name: "@scope/pkg", subpath: "a/b" }. */
+function splitPackageSpecifier(specifier) {
+  const parts = specifier.split('/');
+  if (specifier.startsWith('@')) {
+    if (parts.length < 2) return null;
+    return { name: parts.slice(0, 2).join('/'), subpath: parts.slice(2).join('/') };
+  }
+  return { name: parts[0], subpath: parts.slice(1).join('/') };
+}
+
+/** Picks a file path out of one "exports" value, string or conditions object. */
+function pickExportTarget(value) {
+  if (typeof value === 'string') return value;
+  if (!value || typeof value !== 'object') return null;
+  for (const key of ['default', 'import', 'require', 'types']) {
+    if (typeof value[key] === 'string') return value[key];
+  }
+  return null;
+}
+
+/**
+ * Resolves one subpath through a package.json "exports" map, including
+ * wildcard patterns ("./components/ui/*": "./src/components/ui/*.tsx"),
+ * longest-prefix-first the way Node's own resolver orders them. Deep
+ * subpaths are the shape that matters here, not the "." entry:
+ * openstatusHQ/openstatus's @openstatus/ui declares *no* "." export at all,
+ * and all 1082 of its consumers import a deep path.
+ */
+function resolveExportsSubpath(pkgDir, pkg, subpath) {
+  const exp = pkg?.exports;
+  if (!exp || typeof exp !== 'object') return null;
+  const key = subpath ? `./${subpath}` : '.';
+
+  const exact = pickExportTarget(exp[key]);
+  if (exact) return resolveCandidateFile(path.resolve(pkgDir, exact));
+
+  let best = null;
+  for (const [pattern, value] of Object.entries(exp)) {
+    const star = pattern.indexOf('*');
+    if (star === -1) continue;
+    const prefix = pattern.slice(0, star);
+    const suffix = pattern.slice(star + 1);
+    if (!key.startsWith(prefix) || !key.endsWith(suffix)) continue;
+    if (key.length < prefix.length + suffix.length) continue;
+    if (!best || prefix.length > best.prefix.length) {
+      best = { prefix, value, match: key.slice(prefix.length, key.length - suffix.length) };
+    }
+  }
+  if (!best) return null;
+  const target = pickExportTarget(best.value);
+  if (!target) return null;
+  return resolveCandidateFile(path.resolve(pkgDir, target.replace('*', best.match)));
+}
+
+/**
+ * Resolves an import of a *sibling workspace package* into that sibling's
+ * own source file — the same crossing resolveWrappers() already makes via
+ * its `workspacePackages` option (ADOPTION_APP_PLAN.md §3e), applied here
+ * so a shared internal UI package's components are not scored as unused.
+ * Measured live: openstatusHQ/openstatus keeps 41 of its 61 shadcn
+ * components in packages/ui and imports every one of them as
+ * "@openstatus/ui/components/ui/<name>", so without this all 41 scored 0
+ * usages and the repo's coverage read 13.1% instead of its real value.
+ */
+function resolveWorkspaceImport(workspacePackages, specifier) {
+  if (!workspacePackages || workspacePackages.size === 0) return null;
+  const split = splitPackageSpecifier(specifier);
+  if (!split) return null;
+  const pkgDir = workspacePackages.get(split.name);
+  if (!pkgDir) return null;
+
+  const viaExports = resolveExportsSubpath(pkgDir, readJson(path.join(pkgDir, 'package.json')), split.subpath);
+  if (viaExports) return viaExports;
+  if (!split.subpath) return null;
+
+  return (
+    resolveCandidateFile(path.resolve(pkgDir, split.subpath)) ||
+    resolveCandidateFile(path.resolve(pkgDir, 'src', split.subpath))
+  );
+}
+
 /**
  * Coverage — which of the components resolveForeignDiscovery found are
  * actually imported anywhere else in the repo, vs. the full inventory the
  * componentDir holds. shadcn components are local files, never bare
  * package specifiers, so the origin?.pkg === pkgName filter every other
  * resolver uses (usageRulesResolver.js, propApiResolver.js) doesn't apply
- * here — instead this walks every file's relative imports through
- * moduleGraph.js's own resolveRelative() and checks whether the resolved
- * absolute path lands on a discovered component file. A local-file import
- * edge stands in for "used" — no JSX-usage confirmation beyond that, which
- * is exactly the "structural, not opinionated" scope Layer 3 commits to.
+ * here — instead this walks every file's imports through moduleGraph.js's
+ * own resolveRelative(), the nearest tsconfig's path aliases, and the
+ * workspace package map, and checks whether the resolved absolute path
+ * lands on a discovered component file. An import edge stands in for
+ * "used" — no JSX-usage confirmation beyond that, which is exactly the
+ * "structural, not opinionated" scope Layer 3 commits to.
  */
-function scoreCoverage(root, ignore, components) {
+function scoreCoverage(root, ignore, components, workspacePackages) {
   const moduleGraph = buildModuleGraph(root, { ignore });
-  const aliases = loadPathAliases(root);
+  const aliasCache = new Map();
   const absComponentFiles = components.map((c) => path.resolve(root, c.file));
   const absSet = new Set(absComponentFiles);
   const usageCounts = new Map(absComponentFiles.map((f) => [f, 0]));
@@ -126,7 +248,8 @@ function scoreCoverage(root, ignore, components) {
       const resolved =
         source.startsWith('.') || source.startsWith('/')
           ? resolveRelative(file, source)
-          : resolveAliasedImport(root, aliases, source);
+          : resolveAliasedImport(nearestPathAliases(root, file, aliasCache), source) ||
+            resolveWorkspaceImport(workspacePackages, source);
       if (resolved && resolved !== file && absSet.has(resolved)) {
         usageCounts.set(resolved, usageCounts.get(resolved) + 1);
       }
@@ -169,6 +292,24 @@ function findDuplicates(root, ignore, system) {
     .filter((o) => !o.file.includes(uiDirFragment));
 }
 
+/**
+ * The `Map<packageName, absoluteDir>` resolveWorkspaceImport() needs. Built
+ * here rather than threaded in from cli.js — unlike `adopt --all-targets`,
+ * which already had a discovery result in hand, scan-foreign has one entry
+ * point and every caller of it needs the map, so a caller that forgets to
+ * pass it would silently undercount. Discovery failing (an unreadable or
+ * malformed workspace manifest) degrades to the no-workspace behaviour
+ * instead of failing the scan: coverage is a fact this command reports, not
+ * a gate it enforces.
+ */
+function discoverWorkspacePackages(root) {
+  try {
+    return workspacePackageMap(discoverTargets(root));
+  } catch {
+    return new Map();
+  }
+}
+
 /**
  * Layer 3 of "Version B" (ADOPTION_APP_PLAN.md §10 decision #25) —
  * deliberately structural-only: catalog coverage and hand-rolled
@@ -179,7 +320,7 @@ function findDuplicates(root, ignore, system) {
  */
 export function scoreForeignAdoption(root, systemId, discovery, { ignore = [] } = {}) {
   const system = getForeignSystem(systemId);
-  const coverage = scoreCoverage(root, ignore, discovery.components);
+  const coverage = scoreCoverage(root, ignore, discovery.components, discoverWorkspacePackages(root));
   const duplicates = findDuplicates(root, ignore, system);
 
   return {