@starklab/stark-mcp 0.1.0 → 0.2.0

package/src/adopt/installedPackagePropSchemaResolver.js

@@ -0,0 +1,279 @@
+import ts from 'typescript';
+
+import {
+  resolveInstalledLocation,
+  findTypesEntry,
+  fetchFromCdn,
+} from './installedPackageDiscoveryResolver.js';
+
+// A style-props system that unions in every pseudo-selector/breakpoint key
+// (e.g. Chakra UI v3's `Omit<HTMLAttributes, ...>` props) can render past a
+// megabyte of text per component with NoTruncation — harmless on its own,
+// but multiplied across hundreds of sampled components it blows well past
+// V8's max string length once the CLI's JSON.stringify(value, null, 2)
+// tries to serialize the result (confirmed live against a real installed
+// @chakra-ui/react: ~765 components, ~900KB typeName each, ~530MB compact
+// JSON). Cap the rendered text rather than dropping NoTruncation — TS's own
+// truncation elides from the middle of the type in arbitrary, unhelpful
+// places, whereas an end-anchored cap keeps the (usually most informative)
+// start of the type intact.
+const MAX_TYPE_STRING_LENGTH = 2000;
+
+/**
+ * Renders a ts.Type back to a compact string via the checker itself —
+ * TypeScript's own type-to-string formatting handles unions, generics, and
+ * aliases correctly (e.g. resolves `ComponentProps<'div'>['onClick']` down
+ * to its real function signature), which is exactly the class of shape
+ * foreignPropSchemaResolver.js's hand-rolled typeAnnotationToString() can't
+ * reach — the real motivation for using the compiler API here instead of
+ * porting that Babel-AST approach to a second, installed-package case.
+ */
+function typeToString(checker, type) {
+  let rendered;
+  try {
+    rendered = checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseFullyQualifiedType);
+  } catch {
+    return '<unresolvable type>';
+  }
+  if (rendered.length <= MAX_TYPE_STRING_LENGTH) return rendered;
+  return `${rendered.slice(0, MAX_TYPE_STRING_LENGTH)}… (truncated, ${rendered.length} chars total)`;
+}
+
+/**
+ * Finds the props parameter's type for a component symbol: for a function/
+ * arrow component, the first parameter's type; for a class component, the
+ * type argument to React.Component<Props, ...>. Returns null (a real
+ * "unreachable" case, not empty props) when neither shape is found —
+ * mirrors findPropsDeclaration()'s "never guess among ambiguous
+ * candidates" discipline in the shadcn resolver.
+ */
+function findPropsType(checker, symbol) {
+  const decls = symbol.getDeclarations() || [];
+  for (const decl of decls) {
+    if (ts.isClassDeclaration(decl) && decl.heritageClauses) {
+      for (const clause of decl.heritageClauses) {
+        for (const t of clause.types) {
+          if (t.typeArguments?.length) {
+            try {
+              return checker.getTypeFromTypeNode(t.typeArguments[0]);
+            } catch {
+              // fall through to the call-signature fallback below
+            }
+          }
+        }
+      }
+    }
+  }
+
+  try {
+    const type = checker.getTypeOfSymbolAtLocation(symbol, decls[0] ?? symbol.valueDeclaration);
+    const callSigs = type.getCallSignatures();
+    if (callSigs.length > 0) {
+      const params = callSigs[0].getParameters();
+      if (params.length > 0) {
+        return checker.getTypeOfSymbolAtLocation(params[0], params[0].valueDeclaration ?? decls[0]);
+      }
+    }
+  } catch {
+    // fall through to null below
+  }
+  return null;
+}
+
+// A style-props system (e.g. Chakra UI v3's `SystemProperties`) spreads
+// every pseudo-selector (`_hover`, `_focus`, ...) and responsive breakpoint
+// (`sm`, `md`, `smToLg`, ...) across CSS properties into hundreds of
+// individually-named properties on the props type — confirmed live against
+// @chakra-ui/react: up to 1268 "properties" for a single component, ~880 on
+// average across all 765. That's a fundamentally different shape than a
+// normal component API and isn't useful to enumerate exhaustively for a
+// coverage/prop-schema report; cap it the same way typeToString() caps a
+// single runaway type string, so one component's combinatorial style-prop
+// surface can't blow the sampled-output size up the way it did before.
+const MAX_PROPS_PER_COMPONENT = 150;
+
+/**
+ * Extracts { name, type, optional } for every real (non-inherited-from-
+ * Object) property on a resolved props type, via
+ * checker.getPropertiesOfType — the real fix for the exact limitation
+ * Phase 1's live-verification run documented for shadcn's own resolver
+ * (generic aliases like `ComponentProps<'div'>` returning "unreachable"):
+ * a real type checker resolves the generic instantiation properly, a
+ * string-pattern AST walk never can.
+ */
+function membersFromPropsType(checker, propsType) {
+  let properties;
+  try {
+    properties = checker.getPropertiesOfType(propsType);
+  } catch (err) {
+    return { props: [], totalPropCount: 0, unresolvedReason: err.message };
+  }
+  const named = properties.filter((p) => !/^(toString|valueOf|hasOwnProperty|constructor)$/.test(p.getName()));
+  const props = named.slice(0, MAX_PROPS_PER_COMPONENT).map((p) => {
+    const decl = p.valueDeclaration ?? p.declarations?.[0];
+    let memberType;
+    try {
+      memberType = decl ? checker.getTypeOfSymbolAtLocation(p, decl) : checker.getAnyType();
+    } catch {
+      return {
+        name: p.getName(),
+        type: '<unresolvable type>',
+        optional: Boolean(p.flags & ts.SymbolFlags.Optional) || (p.getDeclarations() || []).some((d) => d.questionToken),
+      };
+    }
+    return {
+      name: p.getName(),
+      type: typeToString(checker, memberType),
+      optional: Boolean(p.flags & ts.SymbolFlags.Optional) || (p.getDeclarations() || []).some((d) => d.questionToken),
+    };
+  });
+  return { props, totalPropCount: named.length };
+}
+
+/**
+ * Per-component isolation: everything below asks the TypeScript checker to
+ * resolve arbitrary types from a third-party .d.ts, and the checker can
+ * throw on a circular or unusually deep/mapped generic rather than return a
+ * clean "can't resolve." Without the try/catch here, one such component
+ * would abort the whole sampled-output batch — losing every other component
+ * that resolved fine — instead of being reported as its own "unreachable"
+ * entry, the same discipline the rest of this file already applies to
+ * missing exports and unresolved props parameters.
+ */
+function sampleFromProgram(checker, moduleSymbol, components) {
+  const exports = new Map(checker.getExportsOfModule(moduleSymbol).map((s) => [s.getName(), s]));
+  return components.map(({ name }) => {
+    try {
+      const symbol = exports.get(name);
+      if (!symbol) {
+        return { component: name, reachable: false, reason: `"${name}" not found among the resolved module's exports` };
+      }
+      const propsType = findPropsType(checker, symbol);
+      if (!propsType) {
+        return { component: name, reachable: false, reason: 'no props parameter / class type argument could be resolved' };
+      }
+      const { props, totalPropCount, unresolvedReason } = membersFromPropsType(checker, propsType);
+      if (unresolvedReason) {
+        return { component: name, reachable: false, reason: unresolvedReason };
+      }
+      const result = { component: name, reachable: true, typeName: typeToString(checker, propsType), props };
+      if (totalPropCount > props.length) {
+        result.propsTruncated = true;
+        result.totalPropCount = totalPropCount;
+      }
+      return result;
+    } catch (err) {
+      return { component: name, reachable: false, reason: err.message };
+    }
+  });
+}
+
+/**
+ * Layer 2 of Phase 2 ("Version B" installed-package adapter) — reads prop
+ * shapes from the package's own .d.ts via the TypeScript compiler API
+ * (checker.getTypeOfSymbol/getPropertiesOfType), the installed-package twin
+ * of foreignPropSchemaResolver.js's shadcn-only Babel-AST walk. There is no
+ * local .tsx source to walk for an installed package — real prop types live
+ * in node_modules/<packageName>'s declarations, or (allowNetwork) a CDN
+ * fallback's fetched .d.ts text, so both branches build a real ts.Program /
+ * standalone SourceFile and resolve through the checker rather than pattern
+ * matching.
+ */
+export async function resolvePropSchema(root, packageName, components, { allowNetwork = false } = {}) {
+  const located = resolveInstalledLocation(root, packageName);
+
+  if (located) {
+    const typesEntryFile = findTypesEntry(located.installDir, located.pkg);
+    if (!typesEntryFile) {
+      return {
+        system: packageName,
+        root,
+        reachableFromRepoAlone: false,
+        source: 'node_modules',
+        sampled: components.map(({ name }) => ({ component: name, reachable: false, reason: 'no .d.ts types entry found for the package' })),
+      };
+    }
+    const program = ts.createProgram([typesEntryFile], {
+      allowJs: true,
+      jsx: ts.JsxEmit.React,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      noEmit: true,
+    });
+    const checker = program.getTypeChecker();
+    const sourceFile = program.getSourceFile(typesEntryFile);
+    const moduleSymbol = sourceFile ? checker.getSymbolAtLocation(sourceFile) : null;
+    if (!moduleSymbol) {
+      return {
+        system: packageName,
+        root,
+        reachableFromRepoAlone: false,
+        source: 'node_modules',
+        sampled: components.map(({ name }) => ({ component: name, reachable: false, reason: 'types entry file could not be resolved as a module' })),
+      };
+    }
+    return {
+      system: packageName,
+      root,
+      reachableFromRepoAlone: true,
+      source: 'node_modules',
+      sampled: sampleFromProgram(checker, moduleSymbol, components),
+    };
+  }
+
+  if (!allowNetwork) {
+    return {
+      system: packageName,
+      root,
+      reachableFromRepoAlone: false,
+      source: null,
+      sampled: components.map(({ name }) => ({ component: name, reachable: false, reason: `"${packageName}" is not installed and --allow-network was not passed` })),
+    };
+  }
+
+  const cdn = await fetchFromCdn(packageName);
+  if (!cdn || !cdn.typesText) {
+    return {
+      system: packageName,
+      root,
+      reachableFromRepoAlone: false,
+      source: 'cdn',
+      sampled: components.map(({ name }) => ({ component: name, reachable: false, reason: 'CDN fallback could not fetch a usable .d.ts' })),
+    };
+  }
+
+  // Compiling a standalone SourceFile (no real filesystem module graph) is
+  // enough to resolve locally-declared shapes but can't follow imports the
+  // .d.ts itself makes to other files (e.g. a shared "CommonProps" type in
+  // a sibling declaration file) — a known, narrower-than-node_modules
+  // limitation of the CDN path, reported per-component via "reachable" the
+  // same way an unresolved shadcn generic is, never silently guessed.
+  const virtualHost = ts.createCompilerHost({ allowJs: true, skipLibCheck: true, noEmit: true });
+  const originalGetSourceFile = virtualHost.getSourceFile.bind(virtualHost);
+  const VIRTUAL_NAME = 'cdn-types.d.ts';
+  virtualHost.getSourceFile = (fileName, languageVersion) => {
+    if (fileName === VIRTUAL_NAME) return ts.createSourceFile(fileName, cdn.typesText, languageVersion, true);
+    return originalGetSourceFile(fileName, languageVersion);
+  };
+  const program = ts.createProgram([VIRTUAL_NAME], { allowJs: true, skipLibCheck: true, noEmit: true }, virtualHost);
+  const checker = program.getTypeChecker();
+  const sourceFile = program.getSourceFile(VIRTUAL_NAME);
+  const moduleSymbol = sourceFile ? checker.getSymbolAtLocation(sourceFile) : null;
+  if (!moduleSymbol) {
+    return {
+      system: packageName,
+      root,
+      reachableFromRepoAlone: false,
+      source: 'cdn',
+      sampled: components.map(({ name }) => ({ component: name, reachable: false, reason: 'fetched .d.ts could not be resolved as a module' })),
+    };
+  }
+
+  return {
+    system: packageName,
+    root,
+    reachableFromRepoAlone: false,
+    source: 'cdn',
+    sampled: sampleFromProgram(checker, moduleSymbol, components),
+  };
+}

package/src/adopt/installedPackageScoringResolver.js

@@ -0,0 +1,153 @@
+import path from 'node:path';
+
+import { buildModuleGraph, resolveOrigin } from './moduleGraph.js';
+import { nameFromPackageSpecifier } from './installedPackageDiscoveryResolver.js';
+import { resolveOpportunities } from './opportunityResolver.js';
+
+/**
+ * Coverage — which of the discovered components are actually imported
+ * anywhere in the target repo. Simpler than foreignScoringResolver.js's
+ * shadcn case (no tsconfig-alias resolution needed): an installed package's
+ * components are reached via resolveOrigin()'s
+ * `!source.startsWith('.') && !source.startsWith('/')` terminal, which
+ * returns `{ pkg, name }` — the same pattern referenceResolver.js uses for
+ * Stark's own catalog package, applied here with `packageName` in place of
+ * packageNameForPlatform()'s hardcoded Stark package name.
+ *
+ * Two import shapes both count as usage, confirmed by live-verifying
+ * against a real installed @mui/material (ADOPTION_APP_PLAN.md §10 decision
+ * #25): a bare specifier (`import { Button } from '@mui/material'`, where
+ * `pkg === packageName` and `name` is the component directly) and MUI's own
+ * common per-component subpath import (`import Button from
+ * '@mui/material/Button'`, where `pkg === '@mui/material/Button'` and a
+ * default import's `name` is always the literal `'default'`, never the real
+ * component name). The first live run against a real MUI consumer fixture
+ * reported 0/149 coverage for a file that plainly imported Button and
+ * TextField — this subpath case is why, and componentNameFromOrigin()
+ * below is the fix: for a `${packageName}/X` subpath it prefers a real
+ * named import (`name !== 'default'`) and otherwise falls back to the
+ * subpath's last segment, which is the component name for this import
+ * style by convention.
+ *
+ * A third shape hits the exact same `name === 'default'` problem on the
+ * bare-specifier branch itself: a single-component package whose whole
+ * default export IS the component (`import Button from '@atlaskit/button'`,
+ * where `pkg === packageName` and `name` is again the literal `'default'`).
+ * Confirmed live: this reported 0/3 coverage for a fixture that plainly
+ * imported and used Button. nameFromPackageSpecifier() — the same fallback
+ * installedPackageDiscoveryResolver.js's enumerateComponents() applies when
+ * it meets a "default"-named export — resolves both sides to the same name.
+ */
+function componentNameFromOrigin(packageName, origin) {
+  if (!origin) return null;
+  if (origin.pkg === packageName) {
+    return origin.name === 'default' ? nameFromPackageSpecifier(packageName) : origin.name;
+  }
+  if (origin.pkg.startsWith(`${packageName}/`)) {
+    if (origin.name && origin.name !== 'default') return origin.name;
+    const subpath = origin.pkg.slice(packageName.length + 1);
+    return subpath.split('/').pop() || null;
+  }
+  return null;
+}
+
+function scoreCoverage(origins, packageName, components) {
+  const known = new Set(components.map((c) => c.name));
+  const usageCounts = new Map(components.map((c) => [c.name, 0]));
+
+  for (const origin of origins) {
+    const componentName = componentNameFromOrigin(packageName, origin);
+    if (componentName && known.has(componentName)) {
+      usageCounts.set(componentName, usageCounts.get(componentName) + 1);
+    }
+  }
+
+  const perComponent = components.map((c) => ({
+    component: c.name,
+    usageCount: usageCounts.get(c.name) ?? 0,
+  }));
+  const used = perComponent.filter((c) => c.usageCount > 0).length;
+  const available = perComponent.length;
+
+  return {
+    used,
+    available,
+    pct: available > 0 ? Math.round((used / available) * 1000) / 10 : null,
+    perComponent,
+  };
+}
+
+/**
+ * Duplication — reuses resolveOpportunities() for both platforms rather
+ * than hand-rolling a second matcher, the same "reuse, don't reimplement"
+ * discipline foreignScoringResolver.js's findDuplicates() already
+ * established for shadcn. Unlike shadcn (whose own components live inside
+ * a known local componentDir that findings must be excluded from), an
+ * installed package's components live in node_modules — already outside
+ * DEFAULT_IGNORE-scanned repo source — so there's no local-directory
+ * exclusion filter needed here.
+ */
+function findDuplicates(root, ignore, platform) {
+  const { opportunities } = resolveOpportunities(root, { platform, ignore });
+  return opportunities;
+}
+
+/**
+ * Everything a score needs that does *not* depend on which package is being
+ * scored: every import origin the repo resolves to a package, and the repo's
+ * hand-rolled duplicates. Both are whole-repo sweeps whose cost is unrelated
+ * to the package name, so a multi-package system (installedSystemScan.js)
+ * builds this once and scores each of its packages against it rather than
+ * re-walking the module graph forty times and reporting the same duplicate
+ * set forty times over.
+ *
+ * A context is only valid for the `platform`/`ignore` it was built with —
+ * origins resolve differently per platform (moduleGraph.js's .native/.ios
+ * preference), so reusing one across platforms would silently score against
+ * the wrong resolution.
+ */
+export function buildInstalledScanContext(root, { platform = 'web', ignore = [] } = {}) {
+  const moduleGraph = buildModuleGraph(root, { ignore });
+  const origins = [];
+
+  for (const file of moduleGraph.files) {
+    const entry = moduleGraph.graph.get(file);
+    if (!entry || entry.parseError) continue;
+    for (const localName of entry.imports.keys()) {
+      const origin = resolveOrigin(moduleGraph, file, localName, { platform });
+      // resolveOrigin returns `{ cycle: [...] }` — no `pkg` — when the import
+      // chain is circular, which componentNameFromOrigin()'s
+      // `origin.pkg.startsWith(...)` would throw on. Filtering to real
+      // package origins here is what keeps one circular import in the
+      // scanned repo from taking down the whole scan.
+      if (origin && typeof origin.pkg === 'string') origins.push(origin);
+    }
+  }
+
+  return { platform, origins, duplicates: findDuplicates(root, ignore, platform) };
+}
+
+/**
+ * Layer 3 of Phase 2 ("Version B" installed-package adapter,
+ * ADOPTION_APP_PLAN.md §10 decision #25) — same structural-only, no-
+ * opinionated-rules discipline as foreignScoringResolver.js: catalog
+ * coverage and hand-rolled duplication, no CI-gate severity (Stark has no
+ * house opinion about a design system it doesn't own).
+ *
+ * Pass a `context` from buildInstalledScanContext() to score several
+ * packages of one system without repeating the repo-wide work; omit it and
+ * one is built for this call alone (the single-package path, unchanged).
+ */
+export function scoreInstalledPackageAdoption(root, packageName, discovery, { platform = 'web', ignore = [], context = null } = {}) {
+  const scanContext = context ?? buildInstalledScanContext(root, { platform, ignore });
+  const coverage = scoreCoverage(scanContext.origins, packageName, discovery.components);
+
+  return {
+    system: packageName,
+    root,
+    platform,
+    coverage: { used: coverage.used, available: coverage.available, pct: coverage.pct },
+    coverageDetail: coverage.perComponent,
+    duplicates: scanContext.duplicates,
+  };
+}

package/src/adopt/installedSystemAutoDetector.js

@@ -0,0 +1,51 @@
+import { detectPackage } from './foreignDiscoveryResolver.js';
+import { FOREIGN_SYSTEMS, systemPackages } from './foreignSystemConfig.js';
+
+function exactDepPattern(npmPackage) {
+  return new RegExp(`^${npmPackage.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`);
+}
+
+/**
+ * Answers "which registered foreign system does this repo already depend
+ * on" so `scan-foreign auto` can skip asking — reuses
+ * foreignDiscoveryResolver.js's detectPackage() (the same monorepo-aware
+ * package.json sweep shadcn's depFallback signal already relies on) for
+ * every FOREIGN_SYSTEMS entry, not just shadcn's own. For an
+ * 'installed-package' system there's no configFiles signal (that's a
+ * copy-paste-only concept), just an exact-name dependency match — a
+ * prefix/regex match here would misfire on scoped near-neighbors (e.g.
+ * "@mantine/core" matching "@mantine/hooks").
+ *
+ * A multi-package system matches on *any* one of its packages, since a repo
+ * adopting Atlaskit installs the handful of `@atlaskit/*` siblings it
+ * actually uses rather than all twenty-five the entry lists — requiring all
+ * of them would make the common case undetectable. The reported `npmPackages` is
+ * still the system's full declared set, not the subset that matched; what
+ * the repo actually has is in `evidence.depEvidence`.
+ *
+ * A match here only decides which system id to hand to the real discovery
+ * resolver afterward — it is not itself a component count or a "this will
+ * work" guarantee.
+ */
+export function detectForeignSystems(root, { ignore = [] } = {}) {
+  const matches = [];
+  for (const system of Object.values(FOREIGN_SYSTEMS)) {
+    const packages = systemPackages(system);
+    const detectSpec =
+      system.distribution === 'copy-paste'
+        ? system.packageDetect
+        : { configFiles: [], depFallback: packages.map(exactDepPattern) };
+    const result = detectPackage(root, ignore, { packageDetect: detectSpec });
+    if (result.detected) {
+      matches.push({
+        id: system.id,
+        label: system.label,
+        distribution: system.distribution,
+        npmPackage: packages[0] ?? null,
+        npmPackages: packages,
+        evidence: result,
+      });
+    }
+  }
+  return matches;
+}

package/src/adopt/installedSystemScan.js

@@ -0,0 +1,101 @@
+import { resolveInstalledPackageDiscovery } from './installedPackageDiscoveryResolver.js';
+import { resolvePropSchema } from './installedPackagePropSchemaResolver.js';
+import { buildInstalledScanContext, scoreInstalledPackageAdoption } from './installedPackageScoringResolver.js';
+
+/**
+ * Runs the installed-package pipeline (discovery → prop schema → scoring)
+ * over the one-or-many npm packages that make up a foreign design system,
+ * and is the only place that knows a system can be more than one package.
+ *
+ * Why it exists: until 2026-08-27 `scan-foreign` took exactly one package
+ * name, which made a system with no umbrella barrel unregisterable rather
+ * than merely untested. That was not hypothetical — the registry already
+ * held such a system, mis-registered: Atlaskit ships ~100 sibling
+ * `@atlaskit/*` packages with no barrel over them, and its entry named
+ * `@atlaskit/button` alone, so it reported a four-component catalog as the
+ * whole of Atlassian's design system. Live-verified against a real
+ * four-package install: 1/4 (25%) under the old form, 3/13 (23.1%) under
+ * this one. The three resolvers stay single-package by design (a package's
+ * `.d.ts` entry is the unit of discovery); the fan-out belongs here.
+ *
+ * Two output shapes, deliberately:
+ *
+ *  - **one package** → `{ discovery, propSchema, scoring }`, byte-identical
+ *    to what this command has always printed. Nineteen of the twenty
+ *    registered systems and every raw package name take this path, so it is
+ *    not worth breaking to make the rare shape uniform.
+ *  - **many packages** → an aggregate carrying `multiPackage: true`, a
+ *    `packages[]` entry per package, and `totals`. `root`, `platform` and
+ *    `duplicates` are hoisted out of the per-package scores because they are
+ *    properties of the *repo*, not of any one package — repeating a
+ *    duplicate finding once per package would inflate the same handful of
+ *    findings forty-fold.
+ *
+ * `totals.coverage.pct` is recomputed from the summed used/available, never
+ * averaged across packages: averaging percentages over catalogs of wildly
+ * different sizes (a 2-component package and a 90-component one) weights
+ * them equally and reports a number no package actually has.
+ */
+export async function scanInstalledSystem(root, packages, {
+  platform = 'web',
+  ignore = [],
+  allowNetwork = false,
+  system = null,
+  label = null,
+} = {}) {
+  const unique = [...new Set(packages)];
+  if (unique.length === 0) {
+    throw new Error('scanInstalledSystem needs at least one npm package name.');
+  }
+
+  // Built once and threaded through every package's score — the module graph
+  // walk and the duplicate sweep are whole-repo work that does not vary by
+  // package name. For a single package this is exactly the work
+  // scoreInstalledPackageAdoption would have done internally.
+  const context = buildInstalledScanContext(root, { platform, ignore });
+
+  const scanned = [];
+  for (const packageName of unique) {
+    const discovery = await resolveInstalledPackageDiscovery(root, packageName, { platform, allowNetwork });
+    const propSchema = await resolvePropSchema(root, packageName, discovery.components, { allowNetwork });
+    const scoring = scoreInstalledPackageAdoption(root, packageName, discovery, { platform, ignore, context });
+    scanned.push({ packageName, discovery, propSchema, scoring });
+  }
+
+  if (scanned.length === 1) {
+    const { discovery, propSchema, scoring } = scanned[0];
+    return { discovery, propSchema, scoring };
+  }
+
+  const used = scanned.reduce((sum, s) => sum + s.scoring.coverage.used, 0);
+  const available = scanned.reduce((sum, s) => sum + s.scoring.coverage.available, 0);
+
+  return {
+    system: system ?? unique.join(','),
+    label,
+    root,
+    platform,
+    multiPackage: true,
+    packages: scanned.map(({ packageName, discovery, propSchema, scoring }) => ({
+      package: packageName,
+      discovery,
+      propSchema,
+      coverage: scoring.coverage,
+      coverageDetail: scoring.coverageDetail,
+    })),
+    totals: {
+      packages: scanned.length,
+      installed: scanned.filter((s) => s.discovery.installed).length,
+      components: scanned.reduce((sum, s) => sum + s.discovery.components.length, 0),
+      unreachableComponents: scanned.reduce((sum, s) => sum + s.discovery.unreachableComponents.length, 0),
+      coverage: { used, available, pct: available > 0 ? Math.round((used / available) * 1000) / 10 : null },
+    },
+    // Surfaced at the top level too, not just buried per package: for a
+    // forty-package system the one thing a reader needs up front is which
+    // packages the repo does not actually have installed.
+    unresolved: scanned
+      .filter((s) => s.discovery.unresolvedReason)
+      .map((s) => ({ package: s.packageName, reason: s.discovery.unresolvedReason })),
+    duplicates: context.duplicates,
+  };
+}

package/src/adopt/jsxOpportunityHelpers.js

@@ -0,0 +1,99 @@
+import { resolveJsxLiteral } from './usageRulesResolver.js';
+
+/**
+ * Shared low-level JSX node helpers for opportunityResolver.js's web
+ * signatures and opportunitySignaturesNative.js's RN signatures. Split out
+ * to avoid a circular import between the two signature-table modules (the
+ * web table lives in opportunityResolver.js alongside resolveOpportunities()
+ * itself; the native table is a sibling file per ADOPTION_APP_PLAN.md §10
+ * decision #25's Phase 2 plan) — both import from here instead of from each
+ * other.
+ */
+
+export function getAttr(openingElement, name) {
+  return openingElement.attributes.find((a) => a.type === 'JSXAttribute' && a.name.name === name);
+}
+
+/** True for a lowercase DOM tag (`<button>`), never a component (`<Pressable>`). */
+export function domTagName(nameNode) {
+  return nameNode.type === 'JSXIdentifier' && /^[a-z]/.test(nameNode.name) ? nameNode.name : null;
+}
+
+/** True for a PascalCase component reference (`<Pressable>`, `<TouchableOpacity>`), the RN counterpart of domTagName. */
+export function componentTagName(nameNode) {
+  return nameNode.type === 'JSXIdentifier' && /^[A-Z]/.test(nameNode.name) ? nameNode.name : null;
+}
+
+export function classNameMatches(openingElement, regex) {
+  const attr = getAttr(openingElement, 'className');
+  if (!attr) return false;
+  const r = resolveJsxLiteral(attr.value);
+  return r.resolved && typeof r.value === 'string' && regex.test(r.value);
+}
+
+/**
+ * True when the element was given *some* real, static class name — see
+ * opportunityResolver.js's matchButton for why a keyword regex
+ * (/btn|button/) is the wrong bar: real codebases name their button classes
+ * anything.
+ */
+export function hasStaticClassNameContent(openingElement) {
+  const attr = getAttr(openingElement, 'className');
+  if (!attr) return false;
+  const literal = resolveJsxLiteral(attr.value);
+  if (literal.resolved && typeof literal.value === 'string' && literal.value.trim().length > 0) return true;
+  if (attr.value?.type === 'JSXExpressionContainer' && attr.value.expression.type === 'TemplateLiteral') {
+    return attr.value.expression.quasis.some((q) => q.value.raw.trim().length > 0);
+  }
+  return false;
+}
+
+/**
+ * Reads the *keys* of a `style={{...}}` object literal, never the values —
+ * a dynamic value is still a real signal the element carries
+ * background/border/padding styling even when resolveJsxLiteral can't
+ * resolve the object as a whole.
+ */
+export function styleTouchesKeys(openingElement, keyRegex) {
+  const attr = getAttr(openingElement, 'style');
+  if (!attr || attr.value?.type !== 'JSXExpressionContainer') return false;
+  const expr = attr.value.expression;
+  if (expr.type !== 'ObjectExpression') return false;
+  return expr.properties.some((p) => {
+    if (p.type !== 'ObjectProperty' || p.computed) return false;
+    const key = p.key.type === 'Identifier' ? p.key.name : p.key.type === 'StringLiteral' ? p.key.value : null;
+    return key !== null && keyRegex.test(key);
+  });
+}
+
+/**
+ * True when a `style={...}` attribute references a StyleSheet-created
+ * styles object — `styles.button` (MemberExpression) or
+ * `[styles.button, active && styles.active]` (ArrayExpression of the same)
+ * — RN's equivalent of a static className, since RN has no CSS classes at
+ * all. Doesn't attempt to resolve the styles object's own declaration back
+ * to a StyleSheet.create() call (that's a cross-scope lookup this
+ * per-element matcher doesn't have); referencing *some* `styles.*` member is
+ * itself the signal, the same "don't guess further" discipline
+ * hasStaticClassNameContent applies to a template literal's static quasis.
+ */
+export function styleReferencesStylesheetMember(openingElement) {
+  const attr = getAttr(openingElement, 'style');
+  if (!attr || attr.value?.type !== 'JSXExpressionContainer') return false;
+  const expr = attr.value.expression;
+  const isStylesMember = (n) =>
+    n.type === 'MemberExpression' && n.object.type === 'Identifier' && /styles?$/i.test(n.object.name);
+  if (isStylesMember(expr)) return true;
+  if (expr.type === 'ArrayExpression') {
+    return expr.elements.some((el) => el && (isStylesMember(el) || (el.type === 'LogicalExpression' && isStylesMember(el.right))));
+  }
+  return false;
+}
+
+export function significantJsxChildren(children) {
+  return (children || []).filter((c) => {
+    if (c.type === 'JSXText') return c.value.trim().length > 0;
+    if (c.type === 'JSXExpressionContainer') return c.expression.type !== 'JSXEmptyExpression';
+    return c.type === 'JSXElement' || c.type === 'JSXFragment';
+  });
+}