@starklab/stark-mcp 0.1.0 → 0.2.1

package/src/adopt/installedPackageDiscoveryResolver.js

@@ -0,0 +1,602 @@
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import ts from 'typescript';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * KNOWN_DISTRIBUTION_PATTERNS — the empirically-derived taxonomy of
+ * React/React Native design-system distribution/export shapes this adapter
+ * has hit in practice, one entry per real fix landed in this file or its
+ * siblings (ADOPTION_APP_PLAN.md §10 decision #25). When a new system's
+ * scan comes back wrong, check it against this list before assuming the
+ * failure is novel — most new systems land in an already-known category.
+ *
+ * 1. Direct named exports (the default/majority case — Carbon, Ant Design,
+ *    Fluent UI, Tamagui, React Native Elements, React Native Paper, MUI).
+ *    No special handling needed: isDirectlyComponentShaped() alone covers it.
+ * 2. Namespace re-export (Radix: every top-level export is itself a module
+ *    re-export, e.g. `export { reactAccordion as Accordion }`). Fixed by
+ *    isCompoundComponentNamespace() below, via checker.getAliasedSymbol().
+ * 3. Strict `exports` map with no `./package.json` subpath (Mantine).
+ *    Fixed by resolveInstalledLocation()'s walk-up-from-entry-point fallback.
+ * 4. Broken/incomplete `types` field needing an independent `typings`
+ *    fallback (native-base declares both; only `typings` resolves). Fixed
+ *    by findTypesEntry() trying both fields independently, never `||`.
+ * 5. Oversized prop surface from a style-props system spreading every
+ *    pseudo-selector/breakpoint into named properties (Chakra UI v3: up to
+ *    1268 properties on one component). Fixed by MAX_PROPS_PER_COMPONENT /
+ *    MAX_TYPE_STRING_LENGTH caps in installedPackagePropSchemaResolver.js.
+ * 6. Cross-file re-export losing its type annotation at the export site
+ *    (@atlaskit/button: `export { default } from './old-button/button'`).
+ *    Fixed by isDirectlyComponentShaped()'s getAliasedSymbol() resolution
+ *    through the re-export chain to the terminal declaration.
+ * 7. Runtime factory-synthesized components (Shopify Restyle:
+ *    createBox()/createText() build the real UI primitives at runtime: they
+ *    never exist as named package exports at all). Root-caused as a genuine
+ *    architectural non-goal, not a bug — fixing it for real would mean
+ *    tracing factory call sites and the local identifiers they're bound to
+ *    across the consuming repo, a materially different mechanism than
+ *    reading a package's own .d.ts. Not built; Restyle stays registered
+ *    with this documented as its known limitation.
+ * 8. Root entry declared but not published (primereact 11: package.json's
+ *    "main"/"types" and its own "exports" "." condition all point at
+ *    "./index.mjs"/"./index.d.ts", but neither file exists in the published
+ *    tarball — every real component lives only under subpaths like
+ *    "primereact/button". Both of resolveInstalledLocation()'s
+ *    require.resolve attempts throw MODULE_NOT_FOUND (not the
+ *    ERR_PACKAGE_PATH_NOT_EXPORTED case #3 already handles), which previously
+ *    fell through to a false "not installed" report even though the package
+ *    plainly exists on disk. Fixed by resolveInstalledLocation()'s third,
+ *    filesystem-only fallback tier below.
+ * 9. Compound component declared as an intersection with a `typeof`
+ *    reference to an internal module (@ant-design/react-native 5:
+ *    `declare const Checkbox: typeof InternalCheckbox & { CheckboxItem:
+ *    typeof CheckboxItem; AgreeItem: typeof AgreeItem };`). The component
+ *    shape lives behind the `typeof` operand, in a different module, so
+ *    isDirectlyComponentShaped() — which recognises `React.FC<Props>` and
+ *    `class X extends React.Component` at the declaration site — sees only
+ *    an intersection type and drops the export. Distinct from #2, where the
+ *    export is an alias the checker resolves in one hop, and from #6, where
+ *    the terminal declaration is itself component-shaped. Four of that
+ *    package's exports (Checkbox, Collapse, Input, List) are lost this way;
+ *    they are real components a consumer imports and uses, so the coverage
+ *    denominator under-reports. Not fixed: resolving it means following
+ *    `typeof` operands into their declaring modules and re-running the
+ *    component test there, which needs care not to walk the whole type
+ *    graph. Ant Design Mobile RN stays registered with this documented as
+ *    its known limitation, same treatment as #7 and #8.
+ */
+export const KNOWN_DISTRIBUTION_PATTERNS = [
+  'direct-named-exports',
+  'namespace-re-export',
+  'strict-exports-map',
+  'broken-types-field',
+  'oversized-prop-surface',
+  'cross-file-re-export',
+  'runtime-factory-synthesized',
+  'root-entry-declared-but-not-published',
+  'typeof-intersection-compound-component',
+];
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Best-effort component name for a symbol whose exported name is the
+ * literal string "default" — a single-component package re-exporting its
+ * whole default export with no named binding anywhere in its own .d.ts
+ * (confirmed live against @atlaskit/button: `export { default } from
+ * './old-button/button'`, no re-exported "Button" identifier at all). The
+ * bare symbol name "default" is neither PascalCase (so it silently failed
+ * the component-convention filter below, dropping the package's one real
+ * component from the catalog entirely) nor a name coverage scoring could
+ * ever match against a real import. Falls back to the package's own last
+ * path segment, cased the way an npm package name (always lowercase/kebab)
+ * would be written as the JS identifier a consumer binds it to on default
+ * import — "@atlaskit/button" -> "Button", "my-cool-button" ->
+ * "MyCoolButton". installedPackageScoringResolver.js's componentNameFromOrigin()
+ * applies this exact same fallback so a bare-specifier default import
+ * resolves to the same name discovery reports here.
+ */
+export function nameFromPackageSpecifier(packageName) {
+  const last = packageName.split('/').pop() || '';
+  return last.replace(/(^|-)([a-z])/g, (_, boundary, c) => c.toUpperCase());
+}
+
+function depNames(pkg) {
+  return new Set([
+    ...Object.keys(pkg?.dependencies || {}),
+    ...Object.keys(pkg?.devDependencies || {}),
+    ...Object.keys(pkg?.peerDependencies || {}),
+  ]);
+}
+
+/**
+ * Package detection — a straight exact/scoped-name lookup against the
+ * target's own root package.json, unlike foreignDiscoveryResolver.js's
+ * detectPackage() which needs a two-signal (config file + dep regex)
+ * fallback because shadcn is never itself an npm dependency. An
+ * installed-package system IS the dependency, so one signal is sufficient
+ * and unambiguous.
+ */
+function detectPackage(root, packageName) {
+  const pkgFile = path.join(root, 'package.json');
+  const pkg = readJson(pkgFile);
+  if (!pkg) return { detected: false, evidence: [] };
+  const names = depNames(pkg);
+  const detected = names.has(packageName);
+  return {
+    detected,
+    evidence: detected ? [{ file: 'package.json', dep: packageName }] : [],
+  };
+}
+
+/**
+ * Resolves the installed package's own root dir and package.json via
+ * require.resolve against the target repo's node_modules — this correctly
+ * handles hoisted/pnpm/yarn-workspace layouts a manual node_modules walk
+ * would get wrong, the same reason moduleGraph.js/foreignScoringResolver.js
+ * never hand-roll their own resolution when a Node builtin already does it
+ * right.
+ *
+ * Falls back to resolving the package's main entry point and walking up to
+ * the nearest package.json when the direct "<pkg>/package.json" resolve
+ * throws — confirmed live against @mantine/core: its package.json declares
+ * a strict "exports" map with no "./package.json" entry, so Node's own
+ * resolver rejects the subpath with ERR_PACKAGE_PATH_NOT_EXPORTED even
+ * though the file plainly exists on disk (this only gates module
+ * resolution, not a raw fs read). Resolving the package's real entry point
+ * (which "exports" does allow, via its "." condition) and walking up
+ * directories to the first package.json whose own "name" matches sidesteps
+ * the restriction entirely without special-casing Mantine.
+ *
+ * Falls back a second time to a plain node_modules directory walk (still no
+ * special-casing) when even the entry-point resolve throws — confirmed live
+ * against primereact 11: its package.json's "main"/"types" AND its own
+ * "exports" "." condition all point at "./index.mjs"/"./index.d.ts", but
+ * neither file exists in the published package at all (every real
+ * component lives only under subpaths like "primereact/button"). That's not
+ * an exports-map access restriction like Mantine's (the "." condition does
+ * resolve, to a target that then 404s), so the walk-up-from-entry-point
+ * fallback above never gets an entry path to start from — both attempts
+ * throw MODULE_NOT_FOUND. Without this third tier, a package in exactly
+ * this shape was reported as "not installed" (wrong — it plainly is, see
+ * KNOWN_DISTRIBUTION_PATTERNS #8) instead of "installed, no root types
+ * entry." This walks up from `root` looking for
+ * node_modules/<packageName>/package.json directly via fs, bypassing
+ * Node's module resolution (and its exports-map enforcement) entirely — the
+ * same "raw fs read" insight the Mantine fallback already relies on, just
+ * without needing any resolvable file to anchor the walk.
+ */
+export function resolveInstalledLocation(root, packageName) {
+  try {
+    const pkgJsonPath = require.resolve(`${packageName}/package.json`, { paths: [root] });
+    const pkg = readJson(pkgJsonPath);
+    return { installDir: path.dirname(pkgJsonPath), pkgJsonPath, pkg };
+  } catch {
+    // fall through to the walk-up strategy below
+  }
+
+  try {
+    const entryPath = require.resolve(packageName, { paths: [root] });
+    let dir = path.dirname(entryPath);
+    while (true) {
+      const candidate = path.join(dir, 'package.json');
+      if (existsSync(candidate)) {
+        const pkg = readJson(candidate);
+        if (pkg?.name === packageName) {
+          return { installDir: dir, pkgJsonPath: candidate, pkg };
+        }
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    // fall through to the plain fs walk below
+  }
+
+  let dir = root;
+  while (true) {
+    const candidate = path.join(dir, 'node_modules', packageName, 'package.json');
+    if (existsSync(candidate)) {
+      const pkg = readJson(candidate);
+      if (pkg?.name === packageName) {
+        return { installDir: path.dirname(candidate), pkgJsonPath: candidate, pkg };
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Finds the package's own .d.ts types entry point from its package.json —
+ * "types" then "typings" (the direct, unambiguous signals, tried
+ * independently), then a same-named .d.ts sibling of "main"/"module" (the
+ * common convention when a package omits "types" but ships declarations
+ * alongside its JS), then a root-level index.d.ts as a last resort. Returns
+ * null, never a guess, when none of these exist — that's a real "not
+ * reachable" case for the caller to report, not a silently-empty catalog.
+ *
+ * "types" and "typings" are tried as two independent candidates, not
+ * `pkg.types || pkg.typings` — confirmed live against native-base: its
+ * package.json declares both fields, but "types" points at a path that
+ * doesn't exist in the published package (a real upstream bug) while
+ * "typings" points at a real, valid one. `||` picks whichever is merely
+ * truthy first and never tries the second string once the first fails its
+ * existsSync check, so the valid "typings" path was silently never reached.
+ */
+export function findTypesEntry(installDir, pkg) {
+  for (const field of ['types', 'typings']) {
+    const declared = pkg?.[field];
+    if (!declared) continue;
+    const resolved = path.resolve(installDir, declared);
+    if (existsSync(resolved)) return resolved;
+  }
+
+  for (const field of ['main', 'module']) {
+    const entry = pkg?.[field];
+    if (!entry) continue;
+    const dtsSibling = path.resolve(installDir, entry.replace(/\.jsx?$/, '.d.ts'));
+    if (existsSync(dtsSibling)) return dtsSibling;
+  }
+
+  const rootIndex = path.join(installDir, 'index.d.ts');
+  if (existsSync(rootIndex)) return rootIndex;
+
+  return null;
+}
+
+/**
+ * The decls-based + call-signature checks only, no namespace fallback —
+ * factored out of isComponentShapedSymbol() so isCompoundComponentNamespace()
+ * below can apply the same "is this thing itself component-shaped" test to a
+ * namespace's members without recursing back into the namespace check (which
+ * would only matter for a namespace nested inside a namespace — not a shape
+ * any real design system's compound-component convention produces).
+ */
+function isDirectlyComponentShaped(checker, symbol) {
+  let decls = symbol.getDeclarations() || [];
+  // A cross-file re-export (`export { default } from './internal/button'`,
+  // confirmed live against @atlaskit/button) makes the exported symbol's own
+  // declaration an ExportSpecifier, not the original `declare const X: ...`
+  // — the text-pattern check below would never see the real type annotation.
+  // getAliasedSymbol() resolves through the whole re-export chain (verified:
+  // one hop or many) to the terminal declaration, letting the syntactic
+  // check fire without needing the checker to resolve React.FC's own module,
+  // which the callSigs fallback below requires and a target repo may lack.
+  if (symbol.flags & ts.SymbolFlags.Alias) {
+    try {
+      const aliased = checker.getAliasedSymbol(symbol);
+      if (aliased && aliased !== symbol) decls = decls.concat(aliased.getDeclarations() || []);
+    } catch {
+      // fall through with whatever decls we already have
+    }
+  }
+  for (const decl of decls) {
+    if (ts.isClassDeclaration(decl)) return true;
+    if (ts.isFunctionDeclaration(decl)) return true;
+    if (ts.isVariableDeclaration(decl) && decl.type) {
+      const typeText = decl.type.getText();
+      if (/^(React\.)?(FC|FunctionComponent|ForwardRefExoticComponent|MemoExoticComponent|ComponentType)\b/.test(typeText)) {
+        return true;
+      }
+    }
+  }
+  // Fallback: a symbol whose resolved type has call signatures returning
+  // something JSX-shaped is treated as component-shaped too — covers the
+  // common `export const Button: (props: ButtonProps) => JSX.Element` and
+  // arrow-const-without-an-explicit-FC-annotation shapes real libraries use.
+  // No declaration to resolve at all is a legitimate "not a component";
+  // deliberately no try/catch beyond that guard — a symbol with a real
+  // location never makes the checker throw for an ordinary non-component
+  // reason (it just returns zero call signatures), so an actual exception
+  // here is a genuine checker failure and must propagate to
+  // enumerateComponents()'s per-symbol guard so it's reported as
+  // unreachable, not silently mislabeled as "not a component."
+  const location = decls[0] ?? symbol.valueDeclaration;
+  if (!location) return false;
+  const type = checker.getTypeOfSymbolAtLocation(symbol, location);
+  const callSigs = type.getCallSignatures();
+  return callSigs.length > 0;
+}
+
+/**
+ * True for a "compound component namespace" export — a top-level export
+ * that is itself just a module re-export (`import * as reactAccordion from
+ * '@radix-ui/react-accordion'; export { reactAccordion as Accordion }`),
+ * confirmed live as radix-ui's whole package shape: every one of its ~30
+ * top-level exports (Accordion, Dialog, Select, ...) is this pattern, not a
+ * component/class/callable itself, so isDirectlyComponentShaped() always
+ * returned false and the entire catalog reported 0 components. The
+ * TypeScript checker resolves the re-export alias to the real module symbol
+ * (checker.getAliasedSymbol) whose own .exports contains the actual
+ * components (Root, Trigger, Content, ...) — this reports the namespace
+ * itself as one catalog entry (e.g. "Accordion") when at least one of its
+ * members is component-shaped, matching how a consumer actually imports and
+ * uses it (`import { Accordion } from 'radix-ui'` then `<Accordion.Root>`)
+ * rather than expanding into "Accordion.Root"/"Accordion.Trigger" entries,
+ * which would multiply out into redundant long-form/short-form aliases
+ * radix itself re-exports side by side (e.g. both "AccordionContent" and
+ * "Content" resolve to the same underlying component).
+ */
+function isCompoundComponentNamespace(checker, symbol) {
+  if (!(symbol.flags & ts.SymbolFlags.Alias)) return false;
+  let resolved;
+  try {
+    resolved = checker.getAliasedSymbol(symbol);
+  } catch {
+    return false;
+  }
+  if (!resolved?.exports) return false;
+  let hasComponentMember = false;
+  resolved.exports.forEach((memberSymbol, memberName) => {
+    if (hasComponentMember) return;
+    if (!/^[A-Z]/.test(memberName)) return;
+    if (isDirectlyComponentShaped(checker, memberSymbol)) hasComponentMember = true;
+  });
+  return hasComponentMember;
+}
+
+/**
+ * True when a TypeScript type is component-shaped for enumeration purposes:
+ * callable (a function/const arrow component), a class extending
+ * React.Component/PureComponent, or a compound-component namespace object
+ * (see isCompoundComponentNamespace() above). Deliberately loose — the real
+ * "is this usable as JSX" narrowing happens in
+ * installedPackagePropSchemaResolver.js via getPropertiesOfType on the
+ * actual props parameter; this pass only needs to build the catalog, not
+ * validate it.
+ */
+function isComponentShapedSymbol(checker, symbol) {
+  return isDirectlyComponentShaped(checker, symbol) || isCompoundComponentNamespace(checker, symbol);
+}
+
+/**
+ * Component enumeration via the TypeScript compiler API — the real fix for
+ * the Phase-1 spike's documented gap (ADOPTION_APP_PLAN.md §10 decision #25):
+ * a regex/import-usage scan only ever finds components the TARGET repo
+ * happens to already use, never the library's full catalog. Building a real
+ * ts.Program over the resolved types entry and walking
+ * checker.getExportsOfModule gives every exported symbol regardless of
+ * whether the target repo imports it — the same "every catalog component
+ * reported, including zero-usage ones" discipline runAdopt() already
+ * applies to Stark's own catalog.json, now available for a foreign one too.
+ *
+ * Known limitation, confirmed via live verification against react-native-paper
+ * (ADOPTION_APP_PLAN.md §10 decision #25): isComponentShapedSymbol()'s
+ * call-signature fallback needs the checker to actually resolve types like
+ * ForwardRefExoticComponent/ComponentType, which live in @types/react (and
+ * @types/react-native for RN-specific aliases) — not bundled with `react`
+ * itself. Without those type packages resolvable from the target repo
+ * (hoisted or local), any component whose declared type is an unresolvable
+ * alias silently reports 0 call signatures and is dropped from the catalog
+ * with no error — confirmed live: Button/Card vanished from a 29-component
+ * react-native-paper catalog until @types/react + @types/react-native were
+ * installed in the target repo, after which the same package reported 38
+ * components including both. A pure-JS target repo with no TypeScript
+ * tooling at all will see the same under-count for any forwardRef/generic
+ * component in the scanned package, even though the package itself is fully
+ * typed — this is an inherent limit of reading .d.ts via the checker, not a
+ * bug to fix here.
+ *
+ * Per-symbol isolation: isComponentShapedSymbol() ultimately asks the
+ * TypeScript checker to resolve arbitrary types from a third-party .d.ts —
+ * a circular or unusually deep generic can make the checker throw rather
+ * than return false. Without a guard here, one such symbol would abort the
+ * whole export loop and silently drop every component after it, not just
+ * the offending one. The try/catch below skips only that symbol and
+ * records it in unreachableComponents, the same "report honestly, don't
+ * silently drop data" discipline propsTruncated/totalPropCount already
+ * applies to Chakra's oversized prop surface (see the sibling
+ * installedPackagePropSchemaResolver.js).
+ */
+function enumerateComponents(typesEntryFile, packageName) {
+  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);
+  if (!sourceFile) return { components: [], unreachableComponents: [], moduleSymbol: null, checker: null, program: null };
+
+  const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+  if (!moduleSymbol) return { components: [], unreachableComponents: [], moduleSymbol: null, checker, program };
+
+  const exports = checker.getExportsOfModule(moduleSymbol);
+  const components = [];
+  const unreachableComponents = [];
+  const seen = new Set();
+  for (const symbol of exports) {
+    const rawName = symbol.getName();
+    const name = rawName === 'default' ? nameFromPackageSpecifier(packageName) : rawName;
+    if (!/^[A-Z]/.test(name)) continue; // component convention: PascalCase export
+    if (seen.has(name)) continue;
+    try {
+      if (!isComponentShapedSymbol(checker, symbol)) continue;
+    } catch (err) {
+      seen.add(name);
+      unreachableComponents.push({ name, reason: err.message });
+      continue;
+    }
+    seen.add(name);
+    components.push({ name });
+  }
+
+  return { components, unreachableComponents, moduleSymbol, checker, program };
+}
+
+/**
+ * Read-only CDN fallback for the no-node_modules case — jsdelivr's data API
+ * serves raw published package files as static GETs, never executed. This
+ * is explicitly opt-in (allowNetwork) and off by default: the whole point
+ * is that scanning a repo never triggers `npm install <arbitrary-package>`
+ * (real code execution via install-time lifecycle scripts), and a silent
+ * network fallback would be a surprising side effect of a "static analysis"
+ * tool. jsdelivr resolves "latest" when no version pin is known locally.
+ */
+export async function fetchFromCdn(packageName) {
+  const pkgUrl = `https://cdn.jsdelivr.net/npm/${packageName}/package.json`;
+  const pkgRes = await fetch(pkgUrl);
+  if (!pkgRes.ok) return null;
+  const pkg = await pkgRes.json();
+
+  const declared = pkg.types || pkg.typings;
+  if (!declared) return { pkg, typesText: null };
+  const typesUrl = `https://cdn.jsdelivr.net/npm/${packageName}/${declared.replace(/^\.?\//, '')}`;
+  const typesRes = await fetch(typesUrl);
+  if (!typesRes.ok) return { pkg, typesText: null };
+  return { pkg, typesText: await typesRes.text() };
+}
+
+/**
+ * Layer 1 of Phase 2 ("Version B", ADOPTION_APP_PLAN.md §10 decision #25) —
+ * discovery for the 'installed-package' distribution mode (any npm-
+ * published React/React Native design system: MUI, Chakra, Carbon, or an
+ * unregistered package passed directly by name — see cli.js's scan-foreign
+ * handler for how "whatever design system" becomes real rather than a
+ * curated list). Unlike foreignDiscoveryResolver.js's shadcn-only path,
+ * there's no local .tsx source to glob — real component/prop types live in
+ * node_modules/<packageName>'s .d.ts, so this reads that instead, via the
+ * TypeScript compiler API rather than Babel-AST walking.
+ *
+ * RN platform-file handling: when platform is 'native', component/prop
+ * resolution in the sibling resolvers additionally considers .native.tsx/
+ * .ios.tsx/.android.tsx sources when the caller's own repo (not the
+ * package) uses platform-split files — see moduleGraph.js's EXTENSIONS.
+ * This resolver itself only reads the package's own .d.ts, which is
+ * platform-agnostic by construction (a single Button.d.ts covers whatever
+ * platform the JS implementation targets).
+ */
+export async function resolveInstalledPackageDiscovery(root, packageName, { platform = 'web', allowNetwork = false } = {}) {
+  const packageDetection = detectPackage(root, packageName);
+  const located = resolveInstalledLocation(root, packageName);
+
+  if (located) {
+    const typesEntryFile = findTypesEntry(located.installDir, located.pkg);
+    if (!typesEntryFile) {
+      return {
+        system: packageName,
+        root,
+        platform,
+        distribution: 'installed-package',
+        packageDetected: packageDetection.detected,
+        evidence: packageDetection.evidence,
+        installed: true,
+        source: 'node_modules',
+        typesEntryFile: null,
+        components: [],
+        unreachableComponents: [],
+        unresolvedReason: `No .d.ts types entry found for "${packageName}" — checked package.json "types"/"typings", a same-named sibling of "main"/"module", and a root index.d.ts.`,
+      };
+    }
+
+    const { components, unreachableComponents } = enumerateComponents(typesEntryFile, packageName);
+    return {
+      system: packageName,
+      root,
+      platform,
+      distribution: 'installed-package',
+      packageDetected: packageDetection.detected,
+      evidence: packageDetection.evidence,
+      installed: true,
+      source: 'node_modules',
+      typesEntryFile: path.relative(root, typesEntryFile).startsWith('..')
+        ? typesEntryFile
+        : path.relative(root, typesEntryFile),
+      components,
+      unreachableComponents,
+      unresolvedReason: null,
+    };
+  }
+
+  if (!allowNetwork) {
+    return {
+      system: packageName,
+      root,
+      platform,
+      distribution: 'installed-package',
+      packageDetected: packageDetection.detected,
+      evidence: packageDetection.evidence,
+      installed: false,
+      source: null,
+      typesEntryFile: null,
+      components: [],
+      unreachableComponents: [],
+      unresolvedReason: `"${packageName}" is not installed in ${root}'s node_modules. Install it first, or pass --allow-network to fetch its published types read-only from a CDN (never installed, never executed).`,
+    };
+  }
+
+  const cdn = await fetchFromCdn(packageName);
+  if (!cdn || !cdn.typesText) {
+    return {
+      system: packageName,
+      root,
+      platform,
+      distribution: 'installed-package',
+      packageDetected: packageDetection.detected,
+      evidence: packageDetection.evidence,
+      installed: false,
+      source: 'cdn',
+      typesEntryFile: null,
+      components: [],
+      unreachableComponents: [],
+      unresolvedReason: `Could not fetch a usable .d.ts for "${packageName}" from the CDN fallback (package.json missing/no "types" field/fetch failed).`,
+    };
+  }
+
+  // The CDN fallback has no real filesystem location to hand ts.createProgram
+  // a resolvable module path, so it's parsed as a standalone source file
+  // instead — sufficient to enumerate top-level exports, which is this
+  // layer's job; installedPackagePropSchemaResolver.js's own CDN branch
+  // does the equivalent for prop extraction.
+  const sourceFile = ts.createSourceFile('cdn-types.d.ts', cdn.typesText, ts.ScriptTarget.Latest, true);
+  const components = [];
+  ts.forEachChild(sourceFile, (node) => {
+    const names = [];
+    if (ts.isClassDeclaration(node) && node.name && hasExportModifier(node)) names.push(node.name.text);
+    if (ts.isFunctionDeclaration(node) && node.name && hasExportModifier(node)) names.push(node.name.text);
+    if (ts.isVariableStatement(node) && hasExportModifier(node)) {
+      for (const decl of node.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name)) names.push(decl.name.text);
+      }
+    }
+    for (const name of names) {
+      if (/^[A-Z]/.test(name)) components.push({ name });
+    }
+  });
+
+  return {
+    system: packageName,
+    root,
+    platform,
+    distribution: 'installed-package',
+    packageDetected: packageDetection.detected,
+    evidence: packageDetection.evidence,
+    installed: false,
+    source: 'cdn',
+    typesEntryFile: null,
+    components,
+    unreachableComponents: [],
+    unresolvedReason: null,
+  };
+}
+
+function hasExportModifier(node) {
+  return (node.modifiers || []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+}