@volter/world-runtime 2.0.0

package/src/project-inspect.ts

@@ -0,0 +1,770 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { parse as parseToml } from 'smol-toml';
+import { basename, relative, resolve } from 'node:path';
+import { normalizePypiName, overlayPypiTwins, overlaySdkTwins } from './pack-facts.ts';
+
+export type ProjectInspection = {
+  root: string;
+  runtimes: string[];
+  manifests: string[];
+  vendorSdks: Array<{ vendor: string; packages: string[]; twin: string }>;
+  registryDestinations: Array<ProjectNpmRegistry & {
+    classification: 'npm-registry' | 'unknown';
+    twin?: '@volter/twin-npm-registry';
+  }>;
+  envNames: string[];
+  entrypoints: string[];
+  coverage: string[];
+  decisions: string[];
+};
+
+/** npm package → vendor/twin mapping — the shared vendor↔SDK knowledge used by both
+ * `inspect-project` (adoption discovery) and `covers` (room-setup coverage proof).
+ * The canonical entry for each pack is the real client package that pack's own tests
+ * prove the twin against (see each `packages/twin/<pack>/package.json` devDependencies);
+ * the extra aliases are the vendor's other official/first-party clients of the same
+ * API surface. */
+export const SDK_TWINS: Record<string, { vendor: string; twin: string }> = {
+  // (empty — every entry has moved onto its pack descriptor. See the note below.)
+};
+// descriptor-first migration (adding-a-twin.md §3), COMPLETE for this table: every pack declares its own sdk names
+// (`adoption.sdks` on its descriptor, compiled into the committed pack-facts artifact), and the
+// literal above is now empty — the map is populated entirely by the overlay below. It is kept as
+// the overlay's target, not as a home: the exported object identity is what every use site already
+// reads, so nothing downstream changed. Do NOT re-add an entry here; a fact declared in both homes
+// throws at module init.
+overlaySdkTwins(SDK_TWINS);
+
+/** PyPI distribution name (PEP 503) → twin. Built ENTIRELY from descriptors' `adoption.pypi`
+ *  (no hand table): the Python half of the same map SDK_TWINS is for npm. A Python dependency
+ *  detected here surfaces under the vendor's key, so covers/inspect treat both halves alike. */
+export const PYPI_TWINS: Record<string, { vendor: string; twin: string }> = {};
+overlayPypiTwins(PYPI_TWINS);
+
+/** Python dependency names declared by a project — requirements*.txt (one requirement per line;
+ *  `-r` includes followed one level; comments, options and URLs skipped) and pyproject.toml
+ *  (`[project] dependencies`, every `[project.optional-dependencies.*]` list, and Poetry's
+ *  `[tool.poetry.dependencies]` / `[tool.poetry.group.*.dependencies]` tables) — across the
+ *  root and every manifest dir. Names are PEP 503 normalized; extras and version specs dropped. */
+export function projectPythonDependencies(input = process.cwd()): string[] {
+  const root = resolve(input);
+  const out = new Set<string>();
+  const reqName = (line: string): string | null => {
+    const s = line.replace(/\s+#.*$/, '').trim();
+    if (!s || s.startsWith('#') || s.startsWith('-') || s.includes('://') || s.startsWith('.') || s.startsWith('/')) return null;
+    const m = /^([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(s);
+    return m ? normalizePypiName(m[1]!) : null;
+  };
+  const readRequirements = (path: string, depth: number): void => {
+    if (depth > 1 || !existsSync(path)) return;
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+      const t = line.trim();
+      const inc = /^-r\s+(\S+)/.exec(t) ?? /^--requirement\s+(\S+)/.exec(t);
+      if (inc) { readRequirements(resolve(path, '..', inc[1]!), depth + 1); continue; }
+      const n = reqName(t);
+      if (n) out.add(n);
+    }
+  };
+  const readPyproject = (path: string): void => {
+    if (!existsSync(path)) return;
+    const text = readFileSync(path, 'utf8');
+    // TOML arrays of requirement strings under the known keys — a targeted read, not a parser.
+    // The KEY is checked, not just the section: under `[project]` only `dependencies` holds
+    // requirements, while `keywords` and `classifiers` are prose arrays that live in the same
+    // table. Accepting every key there read Airflow's `keywords = ["dag", "workflow", …]` as
+    // dependency names — harmless while PYPI_TWINS was empty, a FALSE VENDOR DETECTION the moment
+    // descriptors claim real distribution names (a repo whose keywords say "openai" does not
+    // thereby call OpenAI). Under `[project.optional-dependencies]` and `[dependency-groups]`
+    // every key IS a requirement list (the key is the extra/group name), so any key counts there.
+    for (const m of text.matchAll(/^[ \t]*([A-Za-z0-9_-]+)\s*=\s*\[([\s\S]*?)\]/gm)) {
+      const head = text.slice(0, m.index).split('\n').reverse().find((l) => /^\s*\[/.test(l)) ?? '';
+      const section = /^\s*\[(project|project\.optional-dependencies|dependency-groups)\]/.exec(head)?.[1];
+      if (section === undefined) continue;
+      if (section === 'project' && m[1] !== 'dependencies') continue;
+      for (const q of m[2]!.matchAll(/["']([^"']+)["']/g)) { const n = reqName(q[1]!); if (n) out.add(n); }
+    }
+    // Poetry tables: keys are the package names.
+    for (const m of text.matchAll(/^[ \t]*\[tool\.poetry(?:\.group\.[A-Za-z0-9_-]+)?\.dependencies\][ \t]*\r?\n([\s\S]*?)(?=^[ \t]*\[|$(?![\s\S]))/gm)) {
+      for (const line of m[1]!.split('\n')) {
+        const k = /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*=/.exec(line);
+        if (k && k[1]!.toLowerCase() !== 'python') out.add(normalizePypiName(k[1]!));
+      }
+    }
+  };
+  for (const dir of [root, ...projectManifestDirs(root).filter((d) => d !== root)]) {
+    for (const f of filesAt(dir)) if (/^requirements[^/]*\.txt$/.test(f)) readRequirements(resolve(dir, f), 0);
+    readPyproject(resolve(dir, 'pyproject.toml'));
+  }
+  return [...out].sort();
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Directories (any depth up to `depth`) below `dir`, skipping hidden dirs and node_modules. */
+function walkDirs(dir: string, depth: number): string[] {
+  if (depth <= 0 || !existsSync(dir)) return [];
+  const found: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+    const child = resolve(dir, entry.name);
+    found.push(child, ...walkDirs(child, depth - 1));
+  }
+  return found;
+}
+
+// Expand one workspace glob into the member dirs that actually hold a package.json.
+// Supports literal dirs, `*` in any segment (one level: "apps/*", two: "packages/*" + "/*"),
+// and a terminal `**` (all nested dirs). Line comment on purpose: glob examples contain
+// the block-comment terminator.
+function expandWorkspaceGlob(root: string, glob: string): string[] {
+  const segments = glob.replace(/\/+$/, '').split('/');
+  let current: string[] = [root];
+  for (const segment of segments) {
+    const next: string[] = [];
+    if (segment === '**') {
+      for (const dir of current) next.push(dir, ...walkDirs(dir, 4));
+      current = next;
+      break; // `**` is terminal: it already covers every nested dir
+    }
+    for (const dir of current) {
+      if (segment.includes('*')) {
+        if (!existsSync(dir)) continue;
+        const matcher = new RegExp(`^${segment.split('*').map(escapeRegExp).join('.*')}$`);
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules' && matcher.test(entry.name)) {
+            next.push(resolve(dir, entry.name));
+          }
+        }
+      } else if (existsSync(resolve(dir, segment))) {
+        next.push(resolve(dir, segment));
+      }
+    }
+    current = next;
+  }
+  return current.filter((dir) => dir !== root && existsSync(resolve(dir, 'package.json')));
+}
+
+/** Workspace member dirs of a JS monorepo: pnpm-workspace.yaml packages plus
+ * package.json "workspaces" (npm/yarn/bun form), glob patterns expanded via
+ * expandWorkspaceGlob above. A repo's vendor SDKs usually live in members, not
+ * the root manifest — the ponder blind-adoption test found inspect-project
+ * blind to exactly this. */
+export function workspaceDirs(root: string): string[] {
+  const globs: string[] = [];
+  const workspaceYaml = resolve(root, 'pnpm-workspace.yaml');
+  if (existsSync(workspaceYaml)) {
+    for (const line of readFileSync(workspaceYaml, 'utf8').split(/\r?\n/)) {
+      const match = line.match(/^\s*-\s*["']?([^"'#]+?)["']?\s*$/);
+      if (match) globs.push(match[1]!.trim());
+    }
+  }
+  const pkg = json(resolve(root, 'package.json'));
+  const declared = Array.isArray(pkg?.workspaces) ? pkg.workspaces : Array.isArray(pkg?.workspaces?.packages) ? pkg.workspaces.packages : [];
+  globs.push(...declared.filter((entry: unknown): entry is string => typeof entry === 'string'));
+  const dirs = new Set<string>();
+  for (const glob of globs) {
+    if (glob.includes('!')) continue;
+    for (const dir of expandWorkspaceGlob(root, glob)) dirs.add(dir);
+  }
+  return [...dirs].sort();
+}
+
+const NESTED_ROOT_SKIP = new Set(['node_modules', 'dist', 'build', 'out', 'vendor', 'target', 'coverage']);
+const NESTED_ROOT_CAP = 200;
+
+/** Nested JS project roots: subdirs (depth ≤ 2) holding a package.json or
+ * pnpm-workspace.yaml that the GIT root's own workspace declarations never reach.
+ * The 2026-08 battery scan (evals/battery) found the detector blind to exactly this
+ * shape — a Go/Rails/Python repo with its JS app in `web/` or `frontend/` (unkey's
+ * stripe lives in web/apps/dashboard, reachable only via web/'s OWN workspace file).
+ * Each nested root contributes itself plus ITS workspace members. Same class as the
+ * ponder workspace fix above, one level out. */
+export function nestedProjectRoots(root: string): string[] {
+  const found = new Set<string>();
+  const candidates: string[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.') || NESTED_ROOT_SKIP.has(entry.name)) continue;
+    const child = resolve(root, entry.name);
+    candidates.push(child);
+    try {
+      for (const nested of readdirSync(child, { withFileTypes: true })) {
+        if (!nested.isDirectory() || nested.name.startsWith('.') || NESTED_ROOT_SKIP.has(nested.name)) continue;
+        candidates.push(resolve(child, nested.name));
+      }
+    } catch { /* unreadable dir */ }
+  }
+  for (const dir of candidates) {
+    if (found.size >= NESTED_ROOT_CAP) break;
+    if (!existsSync(resolve(dir, 'package.json')) && !existsSync(resolve(dir, 'pnpm-workspace.yaml'))) continue;
+    found.add(dir);
+    for (const member of workspaceDirs(dir)) if (found.size < NESTED_ROOT_CAP) found.add(member);
+  }
+  return [...found].sort();
+}
+
+/** Every dir whose package.json should count toward the project's dependency /
+ * env-name census: the root, its declared workspace members, and nested project
+ * roots (plus THEIR members). Single source of truth for the walkers below. */
+export function projectManifestDirs(root: string): string[] {
+  return [...new Set([root, ...workspaceDirs(root), ...nestedProjectRoots(root)])].sort();
+}
+
+function json(path: string): Record<string, any> | undefined {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return undefined; }
+}
+
+function filesAt(root: string): string[] {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name);
+}
+
+/** Every dependency name declared anywhere in the repo — root manifest plus all
+ * workspace members, across dependencies/devDependencies/peerDependencies — plus
+ * the python manifest candidates. Exported raw for `covers`, which must also see
+ * the external-service-shaped deps that DON'T map to any twin. */
+export function projectDependencies(input = process.cwd()): string[] {
+  const root = resolve(input);
+  const dependencies = new Set<string>();
+  // A dep that IS one of the repo's own workspace members resolves LOCALLY (the workspace
+  // protocol wins under every package manager), so it is never an external-vendor signal —
+  // whatever scope it carries. Without this, one mapped package in a vendor's scope turns the
+  // vendor's OWN monorepo self-references into "unmapped siblings of a mapped scope": the
+  // 2026-08-31 census counted 110 of posthog's `@posthog/*` workspace packages as unknown
+  // external services the day `@posthog/api-client` entered a pack's adoption.
+  const memberNames = new Set<string>();
+  const pkg = json(resolve(root, 'package.json'));
+  for (const dir of projectManifestDirs(root)) {
+    const manifest = dir === root ? pkg : json(resolve(dir, 'package.json'));
+    if (typeof manifest?.name === 'string' && manifest.name.length > 0) memberNames.add(manifest.name);
+    for (const group of ['dependencies', 'devDependencies', 'peerDependencies']) {
+      for (const name of Object.keys(manifest?.[group] ?? {})) dependencies.add(name);
+    }
+  }
+  for (const name of memberNames) dependencies.delete(name);
+  // The Python half: every declared PyPI dependency that a descriptor maps (PYPI_TWINS)
+  // surfaces under the vendor's key — the same key the npm half yields — so a mixed repo
+  // counts a vendor once. Unmapped Python names are not external-service-shaped by
+  // themselves and stay out (the env-name and URL detectors still see a vendor either way).
+  for (const name of projectPythonDependencies(root)) {
+    const hit = PYPI_TWINS[name];
+    if (hit) dependencies.add(`pypi:${name}`);
+  }
+  return [...dependencies].sort();
+}
+
+/** Env var names assigned in committed .env* files (root + workspace members) —
+ * the secondary vendor signal: a repo may hold a vendor key without declaring
+ * the vendor's SDK (raw fetch / CLI use). */
+export function projectEnvNames(input = process.cwd()): string[] {
+  const root = resolve(input);
+  const envNames = new Set<string>();
+  for (const dir of projectManifestDirs(root)) {
+    for (const name of filesAt(dir).filter((candidate) => candidate === '.env' || candidate.startsWith('.env.'))) {
+      const text = readFileSync(resolve(dir, name), 'utf8');
+      for (const line of text.split(/\r?\n/)) {
+        const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/);
+        if (match) envNames.add(match[1]!);
+      }
+    }
+  }
+  return [...envNames].sort();
+}
+
+export type ProjectNpmRegistry = { url: string; source: string };
+
+const BUNFIG_MAX_BYTES = 256 * 1024;
+const BUNFIG_MAX_LINE_LENGTH = 4 * 1024;
+
+function publicRegistryUrl(configured: string): string {
+  const parsed = new URL(configured);
+  // inspect-project is a public diagnostic surface, not a credential transport. Registry host and
+  // path are sufficient for classification; userinfo, query tokens, and fragments must never be
+  // copied from config files into its structured report or formatted stdout.
+  parsed.username = '';
+  parsed.password = '';
+  parsed.search = '';
+  parsed.hash = '';
+  return parsed.toString();
+}
+
+type InspectedEnv = { values: Map<string, string>; sources: Map<string, string> };
+
+function inspectedEnv(dir: string, label: string, onlyFile?: string): InspectedEnv {
+  const values = new Map<string, string>();
+  const sources = new Map<string, string>();
+  for (const name of filesAt(dir).filter((candidate) => onlyFile ? candidate === onlyFile : candidate === '.env' || candidate.startsWith('.env.')).sort()) {
+    for (const [index, line] of readFileSync(resolve(dir, name), 'utf8').split(/\r?\n/).entries()) {
+      const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+      if (!match) continue;
+      let value = match[2]!;
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      } else {
+        value = value.replace(/\s+#.*$/, '').trim();
+      }
+      if (value.length > 2_048) continue;
+      values.set(match[1]!, value);
+      sources.set(match[1]!, `${label === '.' ? '' : `${label}/`}${name}:${index + 1}`);
+    }
+  }
+  return { values, sources };
+}
+
+/** Resolve only ordinary npm-style `${NAME}` references from inspected, committed env files.
+ * Eight rounds bound cycles/expansion; shell operators and unresolved variables stay unresolved
+ * instead of being guessed or evaluated. */
+function resolveInspectedEnv(value: string, env: Map<string, string>): string | null {
+  let resolved = value;
+  for (let depth = 0; depth < 8 && /\$\{[A-Za-z_][A-Za-z0-9_]*\}/.test(resolved); depth++) {
+    let missing = false;
+    resolved = resolved.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_whole, name: string) => {
+      const replacement = env.get(name);
+      if (replacement === undefined) { missing = true; return ''; }
+      return replacement;
+    });
+    if (missing || resolved.length > 4_096) return null;
+  }
+  return resolved.includes('${') ? null : resolved;
+}
+
+function resolveBunfigEnv(value: string, env: Map<string, string>): string | null {
+  let resolved = resolveInspectedEnv(value, env);
+  if (resolved === null) return null;
+  // Bun's documented bunfig syntax also accepts bare $NAME references. Keep interpolation
+  // deliberately narrower than a shell: no operators, commands, or process environment reads.
+  for (let depth = 0; depth < 8 && /\$[A-Za-z_][A-Za-z0-9_]*/.test(resolved); depth++) {
+    let missing = false;
+    resolved = resolved.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_whole, name: string) => {
+      const replacement = env.get(name);
+      if (replacement === undefined) { missing = true; return ''; }
+      return replacement;
+    });
+    if (missing || resolved.length > 4_096) return null;
+  }
+  return /\$[A-Za-z_][A-Za-z0-9_]*/.test(resolved) ? null : resolved;
+}
+
+function bunfigInstallRegistries(path: string, sourcePrefix: string, env: Map<string, string>): ProjectNpmRegistry[] {
+  if (!existsSync(path)) return [];
+  const stat = statSync(path);
+  if (!stat.isFile() || stat.size > BUNFIG_MAX_BYTES) return [];
+  const text = readFileSync(path, 'utf8');
+  const lines = text.split(/\r?\n/);
+  if (lines.some((line) => line.length > BUNFIG_MAX_LINE_LENGTH)) return [];
+  let parsed: unknown;
+  try { parsed = parseToml(text); } catch { return []; }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return [];
+  const install = (parsed as Record<string, unknown>).install;
+  if (!install || typeof install !== 'object' || Array.isArray(install)) return [];
+  const registry = (install as Record<string, unknown>).registry;
+  const scopes = (install as Record<string, unknown>).scopes;
+  const candidates: Array<{ raw: string; linePattern: RegExp }> = [];
+  const registryUrl = typeof registry === 'string'
+    ? registry
+    : registry && typeof registry === 'object' && !Array.isArray(registry)
+      ? (registry as Record<string, unknown>).url
+      : undefined;
+  if (typeof registryUrl === 'string') {
+    candidates.push({ raw: registryUrl, linePattern: /^\s*(?:install\.)?registry\s*=/ });
+  }
+  if (scopes && typeof scopes === 'object' && !Array.isArray(scopes)) {
+    for (const [scope, value] of Object.entries(scopes)) {
+      const url = typeof value === 'string'
+        ? value
+        : value && typeof value === 'object' && !Array.isArray(value)
+          ? (value as Record<string, unknown>).url
+          : undefined;
+      if (typeof url === 'string') {
+        const escapedScope = scope.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        candidates.push({ raw: url, linePattern: new RegExp(`^\\s*["']?${escapedScope}["']?\\s*=`) });
+      }
+    }
+  }
+  const found: ProjectNpmRegistry[] = [];
+  for (const candidate of candidates) {
+    const configured = resolveBunfigEnv(candidate.raw, env);
+    if (configured === null) continue;
+    const index = lines.findIndex((line) => candidate.linePattern.test(line));
+    try {
+      found.push({ url: publicRegistryUrl(configured), source: `${sourcePrefix}bunfig.toml:${index >= 0 ? index + 1 : 1}` });
+    } catch { /* Bun owns malformed registry diagnostics. */ }
+  }
+  return found;
+}
+
+/** Explicit npm registry destinations in root/workspace `.npmrc`, `bunfig.toml`, and publishConfig.
+ * npm/Bun are executables rather than SDK dependencies, so adoption must inspect their actual
+ * destination configuration: an NPM_TOKEN alone does not prove that traffic targets one of the
+ * two official hosts the npm-registry injector owns. */
+export function projectNpmRegistries(input = process.cwd()): ProjectNpmRegistry[] {
+  const root = resolve(input);
+  const found = new Map<string, ProjectNpmRegistry>();
+  const rootEnv = inspectedEnv(root, '.');
+  for (const dir of projectManifestDirs(root)) {
+    const label = relative(root, dir) || '.';
+    const localEnv = dir === root ? rootEnv : inspectedEnv(dir, label);
+    const env = new Map([...rootEnv.values, ...localEnv.values]);
+    for (const envName of ['NPM_CONFIG_REGISTRY', 'BUN_CONFIG_REGISTRY']) {
+      const configuredByEnv = env.get(envName);
+      if (configuredByEnv === undefined) continue;
+      const resolvedRegistry = resolveInspectedEnv(configuredByEnv, env);
+      if (resolvedRegistry !== null) {
+        try {
+          const url = publicRegistryUrl(resolvedRegistry);
+          const source = `${localEnv.sources.get(envName) ?? rootEnv.sources.get(envName) ?? '.env'} ${envName}`;
+          found.set(`${source}\0${url}`, { url, source });
+        } catch { /* npm/Bun own invalid registry diagnostics */ }
+      }
+    }
+    const npmrc = resolve(dir, '.npmrc');
+    if (existsSync(npmrc)) {
+      for (const [index, line] of readFileSync(npmrc, 'utf8').split(/\r?\n/).entries()) {
+        const match = line.match(/^\s*(?:@[^:]+:)?registry\s*=\s*([^#;\s]+)\s*$/i);
+        if (!match) continue;
+        const configured = resolveInspectedEnv(match[1]!, env);
+        if (configured === null) continue;
+        try {
+          const url = publicRegistryUrl(configured);
+          const source = `${label === '.' ? '' : `${label}/`}.npmrc:${index + 1}`;
+          found.set(`${source}\0${url}`, { url, source });
+        } catch { /* malformed config is npm's own startup error, not a vendor destination */ }
+      }
+    }
+    for (const bunfig of bunfigInstallRegistries(resolve(dir, 'bunfig.toml'), label === '.' ? '' : `${label}/`, env)) {
+      found.set(`${bunfig.source}\0${bunfig.url}`, bunfig);
+    }
+    const manifest = json(resolve(dir, 'package.json'));
+    const configured = manifest?.publishConfig?.registry;
+    if (typeof configured === 'string') {
+      const resolvedRegistry = resolveInspectedEnv(configured, env);
+      if (resolvedRegistry === null) continue;
+      try {
+        const url = publicRegistryUrl(resolvedRegistry);
+        const source = `${label === '.' ? '' : `${label}/`}package.json#publishConfig.registry`;
+        found.set(`${source}\0${url}`, { url, source });
+      } catch { /* npm owns invalid publishConfig diagnostics */ }
+    }
+  }
+  return [...found.values()].sort((a, b) => a.source.localeCompare(b.source) || a.url.localeCompare(b.url));
+}
+
+export type ProjectFetchUrl = {
+  /** Absolute URL passed directly as the first argument to fetch. */
+  url: string;
+  /** Repo-relative source location (`path:line`). */
+  source: string;
+};
+
+const SOURCE_EXTENSIONS = new Set([
+  '.astro', '.cjs', '.cts', '.js', '.jsx', '.mjs', '.mts', '.svelte', '.ts', '.tsx', '.vue',
+]);
+const SOURCE_DIR_IGNORE = new Set([
+  '.git', '.next', '.storybook', '.turbo', '.volter', '__fixtures__', '__mocks__', '__tests__',
+  'build', 'coverage', 'dist', 'fixtures', 'mocks', 'node_modules', 'storybook',
+  'storybook-static', 'target', 'test', 'tests', 'vendor',
+]);
+
+function sourceExtension(name: string): string {
+  const index = name.lastIndexOf('.');
+  return index < 0 ? '' : name.slice(index).toLowerCase();
+}
+
+/** Whether `index` is executable source rather than a comment or string. This deliberately small
+ * lexer only answers that one question; it is not a JavaScript parser. It keeps comment examples
+ * and strings containing `fetch("https://...")` from becoming false vendor evidence. */
+function isCodeAt(text: string, index: number): boolean {
+  let quote: "'" | '"' | '`' | null = null;
+  let lineComment = false;
+  let blockComment = false;
+  for (let cursor = 0; cursor < index; cursor += 1) {
+    const char = text[cursor]!;
+    const next = text[cursor + 1];
+    if (lineComment) {
+      if (char === '\n') lineComment = false;
+      continue;
+    }
+    if (blockComment) {
+      if (char === '*' && next === '/') { blockComment = false; cursor += 1; }
+      continue;
+    }
+    if (quote !== null) {
+      if (char === '\\') { cursor += 1; continue; }
+      // JavaScript single/double-quoted strings cannot cross an unescaped newline. Resetting here
+      // also keeps ordinary JSX prose (`We're ...`) from hiding every fetch later in a TSX file.
+      if (char === '\n' && quote !== '`') { quote = null; continue; }
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '/' && next === '/') { lineComment = true; cursor += 1; continue; }
+    if (char === '/' && next === '*') { blockComment = true; cursor += 1; continue; }
+    if (char === "'" || char === '"' || char === '`') quote = char;
+  }
+  return quote === null && !lineComment && !blockComment;
+}
+
+/** Production JS/TS source files, deterministically ordered. Shared by every source-level
+ * discovery signal so raw-fetch detection and env-read boot-risk detection exclude the same
+ * generated, test, fixture, mock, story, and dependency trees. */
+function projectSourceFiles(input: string, extensions = SOURCE_EXTENSIONS): string[] {
+  const root = resolve(input);
+  if (!existsSync(root)) return [];
+  const files: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (SOURCE_DIR_IGNORE.has(entry.name)) continue;
+      const path = resolve(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!entry.name.startsWith('.')) walk(path);
+        continue;
+      }
+      if (!entry.isFile() || !extensions.has(sourceExtension(entry.name))) continue;
+      if (/\.(?:spec|stories|test)\.[^.]+$/i.test(entry.name)) continue;
+      // Generated/minified bundles can be enormous and are already excluded by directory; keep a
+      // final size guard so one checked-in bundle cannot make discovery unbounded.
+      if (statSync(path).size > 1_000_000) continue;
+      files.push(path);
+    }
+  };
+  walk(root);
+  return files;
+}
+
+/** Connection facts contain names and source locations, never connection strings or credentials. */
+export type ProjectConnection = {
+  protocol: string | null;
+  env?: string;
+  sources: string[];
+};
+
+const DATABASE_ENV = /(?:^|_)(?:DATABASE|POSTGRES|POSTGRESQL|PG|MYSQL|MARIADB|MONGO|MONGODB|REDIS|VALKEY)[A-Z0-9_]*_(?:URL|URI|DSN|CONNECTION_STRING)$/;
+const CONNECTION_SCHEMES: Record<string, string> = {
+  mysql: 'mysql', mariadb: 'mysql', postgres: 'postgres', postgresql: 'postgres',
+  mongodb: 'mongodb', 'mongodb+srv': 'mongodb', redis: 'redis', rediss: 'redis', valkey: 'redis',
+};
+
+export function connectionProtocol(value: string): string | null {
+  const scheme = value.match(/^([a-z][a-z0-9+.-]*):\/\//i)?.[1]?.toLowerCase();
+  return scheme === undefined ? null : CONNECTION_SCHEMES[scheme] ?? null;
+}
+
+/** Native connections are independent of the vendor's HTTP SDK. Inspect ordinary URL schemes
+ * and Prisma datasource declarations; never infer a selected Prisma adapter from its presence
+ * in package.json. Dynamic/config-file-only datasources remain unknown, as do unbound drivers. */
+export function projectConnections(input = process.cwd(), attributedEnv = new Set<string>()): ProjectConnection[] {
+  const root = resolve(input);
+  const found: ProjectConnection[] = [];
+  const dependencies = projectDependencies(root);
+  for (const dir of projectManifestDirs(root)) {
+    const label = relative(root, dir) || '.';
+    // Inspect each example/config separately: conflicting schemes must not silently overwrite
+    // one another. inspectedEnv is only used for resolving ordinary references within a file.
+    for (const file of filesAt(dir).filter((name) => name === '.env' || name.startsWith('.env.')).sort()) {
+      const text = readFileSync(resolve(dir, file), 'utf8');
+      const env = inspectedEnv(dir, label, file);
+      for (const [index, line] of text.split(/\r?\n/).entries()) {
+        const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
+        if (!match || !DATABASE_ENV.test(match[1]!)) continue;
+        const value = match[2]!.replace(/^["']|["']$/g, '');
+        const resolved = resolveInspectedEnv(value, env.values) ?? '';
+        if (/^file:/i.test(resolved)) continue;
+        // Vendor-specific HTTP endpoints have existing descriptor attribution. A generic HTTP
+        // DATABASE_URL has none and must stay unknown, even beside an unrelated HTTP SDK.
+        if (connectionProtocol(resolved) === null && attributedEnv.has(match[1]!) &&
+          (/^https?:/i.test(resolved) || /_REST_URL$/.test(match[1]!))) continue;
+        found.push({ protocol: connectionProtocol(resolved), env: match[1]!, sources: [`env: ${relative(root, resolve(dir, file))}:${index + 1} ${match[1]}`] });
+      }
+    }
+  }
+
+  let datasourceCount = 0;
+  for (const path of projectSourceFiles(root, new Set(['.prisma']))) {
+    // Keep quoted strings intact while removing comments (URLs themselves can contain //).
+    const text = readFileSync(path, 'utf8').replace(/"(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (part) => part.startsWith('"') ? part : '');
+    for (const block of text.matchAll(/\bdatasource\s+\w+\s*\{([^}]+)\}/g)) {
+      datasourceCount += 1;
+      const provider = block[1]!.match(/\bprovider\s*=\s*"([^"]+)"/)?.[1];
+      if (provider === 'sqlite') continue; // local file, no external connection
+      const env = block[1]!.match(/\burl\s*=\s*env\(\s*"([A-Z][A-Z0-9_]*)"\s*\)/)?.[1];
+      const literal = block[1]!.match(/\burl\s*=\s*"([^"]+)"/)?.[1];
+      const protocol = provider === undefined ? null : CONNECTION_SCHEMES[provider] ?? null;
+      // A schema's provider identifies the database, not a dynamically selected HTTP adapter.
+      // With no native URL evidence, retain the uncertainty rather than claiming routing.
+      const nativeEnv = env !== undefined && found.some((entry) => entry.env === env && entry.protocol === protocol && protocol !== null);
+      found.push({
+        protocol: nativeEnv || (literal !== undefined && connectionProtocol(literal) === protocol) ? protocol : null,
+        ...(env ? { env } : {}),
+        sources: [`prisma: ${relative(root, path)} (${provider ?? 'unresolved provider'})`],
+      });
+    }
+  }
+  if (dependencies.includes('@prisma/client') && datasourceCount === 0) {
+    found.push({ protocol: null, sources: ['npm: @prisma/client (datasource not resolved)'] });
+  }
+  for (const [driver, protocol] of Object.entries({ mysql: 'mysql', mysql2: 'mysql', pg: 'postgres', postgres: 'postgres' })) {
+    if (dependencies.includes(driver) && !found.some((entry) => entry.protocol === protocol)) {
+      found.push({ protocol, sources: [`npm: ${driver} (endpoint variable not resolved)`] });
+    }
+  }
+  const merged = new Map<string, ProjectConnection>();
+  for (const entry of found) {
+    const key = `${entry.protocol ?? 'unknown'}:${entry.env ?? entry.sources[0]}`;
+    const previous = merged.get(key);
+    if (previous) previous.sources.push(...entry.sources);
+    else merged.set(key, { ...entry, sources: [...entry.sources] });
+  }
+  return [...merged.values()];
+}
+
+/** Literal HTTP(S) destinations passed directly to the platform fetch API in production source.
+ *
+ * This is the third vendor signal beside dependencies and env names: hand-written REST clients
+ * often declare no SDK, and an unconventional credential name can hide the same vendor from the
+ * env heuristic. Only direct `fetch("https://...")`, `window.fetch`, and `globalThis.fetch` calls
+ * count. Dynamic destinations remain intentionally unclaimed; guessing from arbitrary URL strings
+ * would turn docs, links, and webhook examples into false external-service dependencies. */
+export function projectFetchUrls(input = process.cwd()): ProjectFetchUrl[] {
+  const root = resolve(input);
+  const found: ProjectFetchUrl[] = [];
+  const seen = new Set<string>();
+  // A leading identifier/dot would make this a custom method (`client.fetch`), not platform fetch.
+  const literalFetch = /(?<![\w$.])(?:(?:globalThis|window)\.)?fetch\s*\(\s*(['"`])(https?:\/\/[^'"`\s]+)\1/g;
+  for (const path of projectSourceFiles(root)) {
+    const text = readFileSync(path, 'utf8');
+    for (const match of text.matchAll(literalFetch)) {
+      if (match.index === undefined || !isCodeAt(text, match.index)) continue;
+      const url = match[2]!;
+      try { new URL(url); } catch { continue; }
+      const line = text.slice(0, match.index).split(/\r?\n/).length;
+      const source = `${relative(root, path)}:${line}`;
+      const key = `${source}\0${url}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      found.push({ url, source });
+    }
+  }
+  return found;
+}
+
+/** Env names read directly by production JS/TS source, with repo-relative `path:line` evidence.
+ * This is intentionally evidence, not validator inference: seeing an empty example value read by
+ * the app is enough to rank it as a boot risk, but not enough to claim whether the app permits an
+ * empty string. Supports the standard runtime forms without guessing through arbitrary wrappers. */
+export function projectEnvReads(input = process.cwd()): Map<string, string[]> {
+  const root = resolve(input);
+  const reads = new Map<string, string[]>();
+  const patterns = [
+    /\b(?:process|Bun)\.env\.([A-Z][A-Z0-9_]*)\b/g,
+    /\b(?:process|Bun)\.env\[\s*['"]([A-Z][A-Z0-9_]*)['"]\s*\]/g,
+    /\bimport\.meta\.env\.([A-Z][A-Z0-9_]*)\b/g,
+    /\bDeno\.env\.get\(\s*['"]([A-Z][A-Z0-9_]*)['"]\s*\)/g,
+  ];
+  for (const path of projectSourceFiles(root)) {
+    const text = readFileSync(path, 'utf8');
+    const matches: Array<{ index: number; name: string }> = [];
+    for (const pattern of patterns) {
+      for (const match of text.matchAll(pattern)) {
+        if (match.index === undefined || !isCodeAt(text, match.index)) continue;
+        const after = text.slice(match.index + match[0].length);
+        const before = text.slice(0, match.index);
+        // Assignment/delete sites do not prove the app consumes the value. `??=`/`||=` remain
+        // evidence because they read before writing; only a plain assignment is write-only.
+        if (/^\s*=(?!=)/.test(after) || /\bdelete\s*$/.test(before)) continue;
+        matches.push({ index: match.index, name: match[1]! });
+      }
+    }
+    for (const match of matches.sort((a, b) => a.index - b.index || a.name.localeCompare(b.name))) {
+      const line = text.slice(0, match.index).split(/\r?\n/).length;
+      const source = `${relative(root, path)}:${line}`;
+      const current = reads.get(match.name) ?? [];
+      if (!current.includes(source)) reads.set(match.name, [...current, source]);
+    }
+  }
+  return reads;
+}
+
+export function inspectProject(input = process.cwd()): ProjectInspection {
+  const root = resolve(input);
+  if (!existsSync(root)) throw new Error(`inspect-project: path does not exist: ${root}`);
+  const files = filesAt(root);
+  const manifests = ['package.json', 'pyproject.toml', 'requirements.txt', 'uv.lock', 'bun.lock', 'package-lock.json', 'pnpm-lock.yaml']
+    .filter((name) => files.includes(name));
+  const runtimes = new Set<string>();
+  if (manifests.some((name) => ['package.json', 'bun.lock', 'package-lock.json', 'pnpm-lock.yaml'].includes(name))) runtimes.add('javascript/typescript');
+  if (manifests.some((name) => ['pyproject.toml', 'requirements.txt', 'uv.lock'].includes(name))) runtimes.add('python');
+
+  const pkg = json(resolve(root, 'package.json'));
+  const dependencies = new Set(projectDependencies(root));
+  const grouped = new Map<string, { vendor: string; packages: string[]; twin: string }>();
+  for (const dependency of dependencies) {
+    const match = SDK_TWINS[dependency];
+    if (!match) continue;
+    const current = grouped.get(match.vendor) ?? { ...match, packages: [] };
+    current.packages.push(dependency);
+    grouped.set(match.vendor, current);
+  }
+
+  const envNames = projectEnvNames(root);
+  const officialNpmHosts = new Set(['registry.npmjs.org', 'npm.pkg.github.com']);
+  const registryDestinations = projectNpmRegistries(root).map((registry) => {
+    const classification = officialNpmHosts.has(new URL(registry.url).hostname.toLowerCase())
+      ? 'npm-registry' as const
+      : 'unknown' as const;
+    return {
+      ...registry,
+      classification,
+      ...(classification === 'npm-registry' ? { twin: '@volter/twin-npm-registry' as const } : {}),
+    };
+  });
+  const entrypoints = ['src/index.ts', 'src/index.js', 'src/app.ts', 'src/app.js', 'app.ts', 'app.js', 'app.mjs', 'main.py']
+    .filter((name) => existsSync(resolve(root, name)));
+  const coverage: string[] = [];
+  if (dependencies.has('c8') || dependencies.has('nyc') || pkg?.scripts?.coverage?.includes('coverage')) coverage.push('istanbul/v8');
+  if (manifests.includes('pyproject.toml') || manifests.includes('requirements.txt')) {
+    const text = manifests.map((name) => readFileSync(resolve(root, name), 'utf8')).join('\n').toLowerCase();
+    if (text.includes('coverage') || text.includes('pytest-cov')) coverage.push('coverage.py');
+  }
+  const hasKnownVendor = grouped.size > 0 || registryDestinations.some((registry) => registry.classification === 'npm-registry');
+  const unknownRegistries = registryDestinations.filter((registry) => registry.classification === 'unknown');
+  const decisions = [
+    ...(hasKnownVendor ? [] : ['Identify vendor APIs that should be replaced by twins.']),
+    ...unknownRegistries.map((registry) => `Resolve uncovered npm registry destination ${new URL(registry.url).hostname} (${registry.source}).`),
+    ...(entrypoints.length ? [] : ['Choose the application command the world should run or test.']),
+    'Choose representative user behavior and assertions.',
+    ...(coverage.length ? [] : ['Choose the application native coverage command, if coverage acquisition is a goal.']),
+  ];
+  return {
+    root,
+    runtimes: [...runtimes].sort(),
+    manifests,
+    vendorSdks: [...grouped.values()].map((item) => ({ ...item, packages: item.packages.sort() })).sort((a, b) => a.vendor.localeCompare(b.vendor)),
+    registryDestinations,
+    envNames,
+    entrypoints,
+    coverage,
+    decisions,
+  };
+}
+
+export function formatProjectInspection(report: ProjectInspection): string {
+  const lines = [`Project: ${basename(report.root)} (${report.root})`];
+  lines.push(`Runtime: ${report.runtimes.join(', ') || 'not detected'}`);
+  lines.push(`Manifests: ${report.manifests.join(', ') || 'none detected'}`);
+  lines.push('Vendor SDKs:');
+  if (!report.vendorSdks.length) lines.push('  none detected');
+  for (const sdk of report.vendorSdks) lines.push(`  ${sdk.vendor}: ${sdk.packages.join(', ')} -> ${sdk.twin}`);
+  lines.push('Registry destinations:');
+  if (!report.registryDestinations.length) lines.push('  none detected');
+  for (const registry of report.registryDestinations) {
+    lines.push(`  ${registry.url} (${registry.source}) -> ${registry.twin ?? 'unknown/uncovered'}`);
+  }
+  lines.push(`Environment names: ${report.envNames.join(', ') || 'none detected'}`);
+  lines.push(`Likely entrypoints: ${report.entrypoints.join(', ') || 'none detected'}`);
+  lines.push(`Native coverage: ${report.coverage.join(', ') || 'not detected'}`);
+  lines.push('Decisions left to the adopter:');
+  for (const decision of report.decisions) lines.push(`  - ${decision}`);
+  return `${lines.join('\n')}\n`;
+}