@massu/core 1.10.7 → 1.12.0

package/src/detect/adapters/discover.ts

@@ -1,469 +0,0 @@
-/**
- * Adapter discovery — Plan 3c Phase 5 5H deliverable.
- *
- * Scans three source classes per the three-class trust model
- * (CORE-BUNDLED + REGISTRY-VERIFIED + LOCAL-EXPLICIT, see security/
- * adapter-origin.ts), classifies each candidate, and returns the
- * deduplicated AdapterDescriptor[] the CLI + loader consume.
- *
- * Three sources scanned:
- * 1. CORE-BUNDLED: caller-provided id set (typically built from a static
- *    list of bundled adapter filenames in @massu/core itself). The
- *    discovery module does NOT enumerate the filesystem for these — that
- *    enumeration is done at @massu/core build time and shipped as a
- *    constant. Discovery just classifies the ids.
- * 2. REGISTRY-VERIFIED: walk node_modules/@massu/adapter-* directories
- *    + any node_modules/<pkg>/ where package.json declares
- *    "massu-adapter": true. Cross-reference each candidate against the
- *    cached registry manifest's adapters[] list — only entries that
- *    appear in the manifest are accepted (CR-46 Rule 0 single-source-of-
- *    truth: the registry manifest IS the authoritative allowlist).
- * 3. LOCAL-EXPLICIT: read getConfig().adapters?.local entries. Each entry
- *    is a POSIX-normalized relative path (already validated +
- *    normalized at config-parse time per AdapterLocalPathSchema in
- *    config.ts). Discovery resolves the path relative to the project
- *    root and confirms the file exists.
- *
- * The discovery surface returns warnings (not errors) for candidate-
- * classification refusals — a malformed package.json or a missing local
- * file does NOT abort the whole scan; those candidates are simply not
- * loaded, and the warning is surfaced to the CLI for operator awareness.
- *
- * What this module does NOT do (deferred to follow-up commits, all
- * in-flight Phase 5 deliverables):
- * - Install-time + load-time sha256 of installed adapter package
- *   contents (gap-37 install-tracking + tarball verification). This
- *   requires sha256 of the package's dist/ directory recursively + the
- *   ~/.massu/adapter-manifest-installed.json sidecar file.
- * - adapters.local fingerprint check (gap-32 postinstall-poisoning).
- *   This requires a sha256 of the canonical adapters.local entry list
- *   stored in ~/.massu/adapters-local-fingerprint.json.
- * - User-installed adapter scan at ~/.massu/adapters/ (CLI install
- *   path). Populated by `massu adapters install`, also Phase 5
- *   follow-up.
- *
- * Loading the actual adapter code (importing the JS module + invoking
- * detect/extract) is the loader's job (Plan 3b runner.ts). Discovery
- * just enumerates + classifies.
- */
-import { existsSync, readdirSync, readFileSync, lstatSync } from 'node:fs';
-import { resolve, isAbsolute } from 'node:path';
-import { z } from 'zod';
-import {
-  getAdapterOrigin,
-  type AdapterDescriptor,
-  type AdapterOriginInput,
-} from '../../security/adapter-origin.js';
-import { PrintableAsciiStringSchema, type Envelope, type AdapterEntry } from '../../security/manifest-schema.js';
-import { checkFingerprintDrift, FINGERPRINT_PATH } from '../../security/local-fingerprint.js';
-import {
-  verifyInstalledIntegrity,
-  containsHiddenDirs,
-  INSTALLED_MANIFEST_PATH,
-} from '../../security/install-tracking.js';
-
-/**
- * Minimal shape of a node_modules package.json that we care about for
- * adapter discovery. Strict enough to reject malformed packages at parse
- * time, loose enough (passthrough) to ignore unrelated keys.
- */
-const AdapterPackageJsonSchema = z.object({
-  // CR-9 iter-4 audit LOW-NEW4-2 fix: name/version are rendered in stderr
-  // warnings via `${pkg.name}@${pkg.version}` strings; without the
-  // printable-ASCII regex, a malicious local node_modules/<pkg>/package.json
-  // could embed ANSI escapes to log-inject. Postinstall scripts have the
-  // write access needed to mount this attack.
-  name: PrintableAsciiStringSchema,
-  version: PrintableAsciiStringSchema,
-  // Plan 3c gap-31 + gap-50: `"massu-adapter": true` is the explicit opt-in
-  // marker. @massu/adapter-* packages also declare this.
-  'massu-adapter': z.union([z.boolean(), z.literal(undefined)]).optional(),
-  // Plan 3c gap-31: api version. Loader refuses incompatible major (caller-side).
-  'massu-adapter-api-version': z.union([z.string(), z.number(), z.literal(undefined)]).optional(),
-}).passthrough();
-
-export interface DiscoverOptions {
-  /**
-   * Absolute path to the project root where node_modules/ lives. Caller
-   * passes from getProjectRoot() or equivalent.
-   */
-  projectRoot: string;
-  /**
-   * Set of adapter ids that are CORE-BUNDLED in @massu/core itself.
-   * Built from a static const at @massu/core build time. Pass an empty
-   * set in tests when not exercising CORE-BUNDLED classification.
-   */
-  coreBundledIds: ReadonlySet<string>;
-  /**
-   * The verified registry manifest envelope (from manifest-cache.getManifest).
-   * Discovery uses envelope.manifest.adapters[] as the REGISTRY-VERIFIED
-   * allowlist. Pass undefined if running offline + cache absent — discovery
-   * will then refuse all REGISTRY-VERIFIED candidates with a clear warning.
-   */
-  manifestEnvelope: Envelope | undefined;
-  /**
-   * POSIX-normalized relative paths from getConfig().adapters?.local.
-   * Each entry must already pass AdapterLocalPathSchema (config.ts). Pass
-   * empty array if no local adapters configured.
-   */
-  configLocalPaths: ReadonlyArray<string>;
-  /**
-   * Plan 3c gap-1 kill switch (CR-9 audit C1 fix). When false, ONLY
-   * CORE-BUNDLED adapters are emitted; REGISTRY-VERIFIED + LOCAL-EXPLICIT
-   * scans short-circuit immediately. Source-of-truth is
-   * `getConfig().adapters?.enabled === true`. Defaults to false at the
-   * config schema layer so operators MUST opt-in to third-party adapter
-   * loading — security-critical. Pass the flag through from
-   * commands/adapters.ts:runAdaptersList; a missing argument here would
-   * silently default to enabled, defeating the kill switch.
-   */
-  adaptersEnabled: boolean;
-  /**
-   * Override the on-disk fingerprint sentinel path for testing
-   * (gap-32 postinstall-poisoning check). Production callsite uses
-   * the default `~/.massu/adapters-local-fingerprint.json`.
-   */
-  fingerprintSentinelPath?: string;
-  /**
-   * Override the on-disk install-tracking sidecar path for testing
-   * (gap-37 install-time + load-time sha256 check). Production callsite
-   * uses the default `~/.massu/adapter-manifest-installed.json`.
-   */
-  installedManifestPath?: string;
-  /**
-   * Skip the gap-37 load-time sha256 integrity check. Default: false
-   * (always check). Setting this to `true` is a test seam ONLY — it
-   * exists so unit tests that don't materialize real package directories
-   * can still exercise the classification logic. Production callsites
-   * MUST NOT pass `true`; per CR-46 this is the most-robust posture.
-   */
-  skipInstalledIntegrityCheck?: boolean;
-}
-
-export interface DiscoveryResult {
-  adapters: AdapterDescriptor[];
-  warnings: string[];
-}
-
-/**
- * Walk node_modules for @massu/adapter-* directories AND any other package
- * declaring "massu-adapter": true. Returns the parsed package.json and
- * absolute package directory for each candidate. Skips malformed packages
- * with a warning.
- *
- * Walks ONLY one level of node_modules — does NOT descend into nested
- * node_modules (transitive deps' adapter packages). Adapters are operator-
- * installed top-level dependencies, not transitive.
- */
-function walkNodeModules(projectRoot: string, warnings: string[]): Array<{
-  packageDir: string;
-  pkg: z.infer<typeof AdapterPackageJsonSchema>;
-}> {
-  const nodeModulesDir = resolve(projectRoot, 'node_modules');
-  if (!existsSync(nodeModulesDir)) {
-    return [];
-  }
-  const candidates: Array<{ packageDir: string; pkg: z.infer<typeof AdapterPackageJsonSchema> }> = [];
-  let topLevelEntries: string[];
-  try {
-    topLevelEntries = readdirSync(nodeModulesDir);
-  } catch (err) {
-    warnings.push(`failed to read node_modules: ${err instanceof Error ? err.message : String(err)}`);
-    return [];
-  }
-
-  for (const entry of topLevelEntries) {
-    if (entry.startsWith('.')) continue;
-    const entryPath = resolve(nodeModulesDir, entry);
-    let entryStat;
-    try {
-      // CR-9 audit HIGH-NEW-1 fix: lstatSync (not statSync). statSync
-      // followed symlinks, so a malicious package shipping
-      // `node_modules/evil-link -> /elsewhere` would walk into /elsewhere.
-      // The same fix was applied in install-tracking.ts (audit H1) but
-      // discover's node_modules walk was missed at the time.
-      entryStat = lstatSync(entryPath);
-    } catch {
-      continue;
-    }
-    if (entryStat.isSymbolicLink()) {
-      warnings.push(
-        `skipping ${entryPath}: top-level node_modules entry is a symlink. ` +
-        `Adapter packages must be real directories (npm-installed); refusing to walk symlinks ` +
-        `as a defense against postinstall scripts that link to attacker-controlled paths.`,
-      );
-      continue;
-    }
-    if (!entryStat.isDirectory()) continue;
-
-    if (entry.startsWith('@')) {
-      // Scoped namespace — e.g., node_modules/@massu/. Walk one more level.
-      let scopedEntries: string[];
-      try {
-        scopedEntries = readdirSync(entryPath);
-      } catch {
-        continue;
-      }
-      for (const sub of scopedEntries) {
-        const subPath = resolve(entryPath, sub);
-        // Same lstatSync discipline at the inner level — a malicious
-        // postinstall could plant `node_modules/@massu/evil-link -> ...`.
-        let subStat;
-        try {
-          subStat = lstatSync(subPath);
-        } catch {
-          continue;
-        }
-        if (subStat.isSymbolicLink() || !subStat.isDirectory()) continue;
-        const result = tryReadAdapterPackage(subPath, warnings);
-        if (result) candidates.push(result);
-      }
-    } else {
-      const result = tryReadAdapterPackage(entryPath, warnings);
-      if (result) candidates.push(result);
-    }
-  }
-  return candidates;
-}
-
-function tryReadAdapterPackage(packageDir: string, warnings: string[]): {
-  packageDir: string;
-  pkg: z.infer<typeof AdapterPackageJsonSchema>;
-} | null {
-  const pkgJsonPath = resolve(packageDir, 'package.json');
-  if (!existsSync(pkgJsonPath)) return null;
-  let raw: unknown;
-  try {
-    raw = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
-  } catch (err) {
-    warnings.push(
-      `skipping ${packageDir}: package.json parse failed (${err instanceof Error ? err.message : String(err)})`,
-    );
-    return null;
-  }
-  const parsed = AdapterPackageJsonSchema.safeParse(raw);
-  if (!parsed.success) {
-    warnings.push(`skipping ${packageDir}: package.json shape invalid`);
-    return null;
-  }
-  const pkg = parsed.data;
-
-  // Filter: only consider candidates that EITHER match @massu/adapter-*
-  // glob OR declare "massu-adapter": true. Other npm packages are ignored
-  // (vast majority of node_modules entries).
-  const isMassuAdapterGlob = /^@massu\/adapter-[a-z][a-z0-9-]*$/.test(pkg.name);
-  const declaresMassuAdapter = pkg['massu-adapter'] === true;
-  if (!isMassuAdapterGlob && !declaresMassuAdapter) {
-    return null;
-  }
-  return { packageDir, pkg };
-}
-
-/**
- * Run discovery across all three trust classes. Returns the combined
- * descriptor list + a list of human-readable warnings the CLI prints.
- */
-export function discoverAdapters(opts: DiscoverOptions): DiscoveryResult {
-  const warnings: string[] = [];
-  const adapters: AdapterDescriptor[] = [];
-  const seenIds = new Set<string>();
-
-  // 1. CORE-BUNDLED — pass-through. Each id in coreBundledIds becomes a
-  // descriptor with origin='core-bundled'. No verification needed (trust
-  // derives from @massu/core itself).
-  for (const id of opts.coreBundledIds) {
-    const origin = getAdapterOrigin({ id, coreBundledIds: opts.coreBundledIds });
-    if (origin !== 'core-bundled') {
-      // This shouldn't happen — coreBundledIds + getAdapterOrigin is a
-      // closed loop. If it does, it's a programmer bug worth surfacing.
-      warnings.push(`expected core-bundled classification for id=${id}, got ${origin ?? 'null'}`);
-      continue;
-    }
-    adapters.push({ id, origin: 'core-bundled' });
-    seenIds.add(id);
-  }
-
-  // Plan 3c gap-1 kill switch (CR-9 audit C1): when adapters.enabled=false,
-  // ONLY CORE-BUNDLED adapters load. Skip REGISTRY-VERIFIED + LOCAL-EXPLICIT
-  // entirely. Operators rely on this kill switch documented in SECURITY.md;
-  // bypassing it would silently load third-party code in violation of the
-  // documented contract.
-  if (!opts.adaptersEnabled) {
-    if (opts.configLocalPaths.length > 0) {
-      warnings.push(
-        `adapters.enabled=false — refusing all REGISTRY-VERIFIED + LOCAL-EXPLICIT adapters. ` +
-        `Set massu.config.yaml > adapters.enabled: true to opt in.`,
-      );
-    }
-    return { adapters, warnings };
-  }
-
-  // 2. REGISTRY-VERIFIED — walk node_modules. For each candidate, look
-  // up the manifest entry; refuse if not in the allowlist.
-  const manifestEntries = opts.manifestEnvelope?.manifest.adapters ?? [];
-  const manifestByName = new Map<string, AdapterEntry>(
-    manifestEntries.map((e) => [e.package, e]),
-  );
-  const npmCandidates = walkNodeModules(opts.projectRoot, warnings);
-  for (const { packageDir, pkg } of npmCandidates) {
-    if (seenIds.has(pkg.name)) continue;
-    const manifestEntry = manifestByName.get(pkg.name);
-    if (!manifestEntry) {
-      if (!opts.manifestEnvelope) {
-        warnings.push(
-          `cannot verify ${pkg.name}@${pkg.version}: registry manifest unavailable. ` +
-          `Refusing to load. Run \`massu adapters refresh\` when online.`,
-        );
-      } else {
-        warnings.push(
-          `refusing ${pkg.name}@${pkg.version}: not in the signed registry manifest. ` +
-          `If you authored this adapter, submit a PR to the registry per AUTHORING-ADAPTERS.md.`,
-        );
-      }
-      continue;
-    }
-    if (manifestEntry.unpublished === true) {
-      warnings.push(
-        `refusing ${pkg.name}@${pkg.version}: registry marks this package as unpublished. ` +
-        `Remove via: npm uninstall ${pkg.name}`,
-      );
-      continue;
-    }
-    if (manifestEntry.deprecated) {
-      warnings.push(
-        `${pkg.name}@${pkg.version} is deprecated since ${manifestEntry.deprecated.since}: ` +
-        `${manifestEntry.deprecated.reason}. Replacement: ${manifestEntry.deprecated.replacement ?? '(none listed)'}.`,
-      );
-      // Adapter still loads despite deprecation — gap-57.
-    }
-    if (manifestEntry.version !== pkg.version) {
-      warnings.push(
-        `${pkg.name}@${pkg.version} version mismatch with manifest entry ${manifestEntry.version}. ` +
-        `Loading the installed version; the gap-37 sha256 integrity check below will catch tampering.`,
-      );
-    }
-
-    // gap-37 LOAD-time integrity check: re-compute sha256OfDir on the
-    // installed package and compare to the install-time hash recorded in
-    // ~/.massu/adapter-manifest-installed.json. Missing sidecar entry →
-    // refuse (operator must run `massu adapters install <pkg>`); drift →
-    // refuse (post-install tampering). Caller can suppress for tests via
-    // skipInstalledIntegrityCheck=true.
-    // iter-2 MED-NEW-2 fix: load-time hidden-dir refusal. A postinstall
-    // script that adds `.git/payload.js` to a registered package does NOT
-    // change the load-time hash (sha256OfDir excludes hidden dirs), so
-    // the integrity check passes — but the legitimate adapter could
-    // require() the smuggled payload at runtime. Refusing at load time
-    // closes the gap.
-    if (!opts.skipInstalledIntegrityCheck) {
-      const hiddenDir = containsHiddenDirs(packageDir);
-      if (hiddenDir !== null) {
-        warnings.push(
-          `refusing ${pkg.name}@${pkg.version}: contains '${hiddenDir}' subdirectory. ` +
-          `Published adapter packages must not ship hidden directories. ` +
-          `Recover via \`npm uninstall ${pkg.name} && npm install ${pkg.name} && ` +
-          `massu adapters install ${pkg.name}\`.`,
-        );
-        continue;
-      }
-      const integrity = verifyInstalledIntegrity(
-        pkg.name,
-        packageDir,
-        opts.installedManifestPath ?? INSTALLED_MANIFEST_PATH,
-      );
-      if (integrity.kind !== 'ok') {
-        warnings.push(`refusing ${pkg.name}@${pkg.version}: ${integrity.reason}`);
-        continue;
-      }
-      // CR-9 audit M4 fix: the sidecar can be tampered post-write (mode
-      // 0o600 stops other users but NOT same-user processes running
-      // as the operator). Cross-check the install-time hash recorded in
-      // the sidecar against the SIGNATURE-VERIFIED manifest entry's
-      // sha256. If they diverge, the sidecar was modified after install
-      // — refuse to load. This closes the "attacker writes both the
-      // package AND the sidecar" gap.
-      if (integrity.entry.installed_sha256 !== manifestEntry.sha256) {
-        warnings.push(
-          `refusing ${pkg.name}@${pkg.version}: install-tracking sidecar's installed_sha256 ` +
-          `(${integrity.entry.installed_sha256.slice(0, 16)}...) does not match the signed ` +
-          `manifest entry's sha256 (${manifestEntry.sha256.slice(0, 16)}...). The sidecar ` +
-          `appears tampered post-install. Recover via \`npm uninstall ${pkg.name} && ` +
-          `npm install ${pkg.name} && massu adapters install ${pkg.name}\`.`,
-        );
-        continue;
-      }
-    }
-
-    const origin = getAdapterOrigin({
-      id: pkg.name,
-      coreBundledIds: opts.coreBundledIds,
-      npmPackage: { name: pkg.name, version: pkg.version, massuAdapter: pkg['massu-adapter'] === true },
-    });
-    if (origin !== 'registry-verified') {
-      warnings.push(`expected registry-verified classification for ${pkg.name}, got ${origin ?? 'null'}`);
-      continue;
-    }
-    adapters.push({
-      id: pkg.name,
-      origin: 'registry-verified',
-      version: pkg.version,
-      packageDir,
-    });
-    seenIds.add(pkg.name);
-  }
-
-  // 3. LOCAL-EXPLICIT — read configLocalPaths. Each entry is already POSIX-
-  // normalized + path-validated by AdapterLocalPathSchema (config.ts).
-  //
-  // Plan 3c gap-32 postinstall-poisoning defense: BEFORE classifying any
-  // local adapter, check the fingerprint sentinel. If the current
-  // adapters.local content's fingerprint does NOT match the last
-  // operator-acknowledged sentinel, REFUSE to load any local adapter and
-  // surface the drift in warnings. The operator must run
-  // `massu adapters resync-local-fingerprint` (or add-local/remove-local)
-  // to re-acknowledge before discovery accepts local adapters again.
-  const fingerprintCheck = opts.configLocalPaths.length === 0
-    ? { kind: 'match' as const }
-    : checkFingerprintDrift(
-        opts.configLocalPaths,
-        opts.projectRoot,
-        opts.fingerprintSentinelPath ?? FINGERPRINT_PATH,
-      );
-  if (fingerprintCheck.kind !== 'match') {
-    if (opts.configLocalPaths.length > 0) {
-      warnings.push(
-        `refusing all LOCAL-EXPLICIT adapters: ${fingerprintCheck.reason}`,
-      );
-    }
-    // Skip the LOCAL-EXPLICIT loop entirely.
-    return { adapters, warnings };
-  }
-  const localSet = new Set(opts.configLocalPaths);
-  for (const localPath of opts.configLocalPaths) {
-    if (seenIds.has(localPath)) continue;
-    const absPath = isAbsolute(localPath) ? localPath : resolve(opts.projectRoot, localPath);
-    if (!existsSync(absPath)) {
-      warnings.push(
-        `local adapter file not found: ${localPath} (resolved to ${absPath}). ` +
-        `Remove via: massu adapters remove-local ${localPath}`,
-      );
-      continue;
-    }
-    const origin = getAdapterOrigin({
-      id: localPath,
-      coreBundledIds: opts.coreBundledIds,
-      configLocalPaths: localSet,
-    });
-    if (origin !== 'local-explicit') {
-      warnings.push(`expected local-explicit classification for ${localPath}, got ${origin ?? 'null'}`);
-      continue;
-    }
-    adapters.push({
-      id: localPath,
-      origin: 'local-explicit',
-    });
-    seenIds.add(localPath);
-  }
-
-  return { adapters, warnings };
-}

package/src/detect/adapters/file-sampler.ts

@@ -1,225 +0,0 @@
-// Copyright (c) 2026 Massu. All rights reserved.
-// Licensed under BSL 1.1 - see LICENSE file for details.
-
-/**
- * Per-adapter file sampler — Plan 1.5.4 §3 deliverable.
- *
- * Replaces the `sampleFiles: async () => []` placeholder at
- * `codebase-introspector.ts:160` that prevented AST adapter introspect
- * output from reaching the user-facing config emission. The adapters
- * themselves have always worked (verified by `adapter-grammar-strict.test.ts`
- * with 10/10 fixtures returning 'high' confidence); the gap was that
- * production `introspectAsync()` handed each adapter `SourceFile[] = []`
- * so adapters never saw any actual code.
- *
- * Per Plan 1.5.4 §0 self-attest #3: REUSES `EXTENSIONS` and
- * `TEST_FILE_PATTERNS` from `source-dir-detector.ts:84-104` rather than
- * duplicating them. Adding a new language to those maps automatically
- * enables sampling for any adapter declaring that language.
- *
- * Algorithm:
- *   1. For each language in `adapter.languages`, collect candidate
- *      source dirs from `detection.sourceDirs[<lang>].dirs` (already
- *      computed by Tier 0 detection per `source-dir-detector.ts`).
- *      Fall back to walking common roots (`<projectRoot>` + first-level
- *      subdirs) if detection didn't find any.
- *   2. Walk each source dir up to `MAX_DEPTH` (default 3) levels deep,
- *      filtering by `EXTENSIONS[<lang>]` and excluding files matching
- *      any pattern in `TEST_FILE_PATTERNS[<lang>]`.
- *   3. Skip `IGNORED_DIRS` (node_modules, .git, dist, etc.) at every
- *      depth (already enumerated in `source-dir-detector.ts`).
- *   4. Cap per-adapter sample count to `MAX_FILES_PER_ADAPTER` (default
- *      50) — sufficient for AST queries to find canonical patterns
- *      without blowing the introspect time budget.
- *   5. Per-file size cap inherited from `parse-guard.ts:MAX_AST_FILE_BYTES`
- *      (256 KB) — files above this limit are dropped here so they don't
- *      reach the adapter's parse path.
- *   6. Return `SourceFile[]` typed per `detect/adapters/types.ts`.
- *
- * Errors during the walk (permission-denied, broken symlinks, etc.) are
- * non-fatal: the sampler logs a single stderr warning and proceeds with
- * whatever files it has already collected.
- */
-
-import { readdirSync, readFileSync, statSync, lstatSync } from 'node:fs';
-import { join, extname } from 'node:path';
-import type { CodebaseAdapter, SourceFile, TreeSitterLanguage } from './types.ts';
-import type { DetectionResult } from '../index.ts';
-import { MAX_AST_FILE_BYTES } from './parse-guard.ts';
-
-/**
- * Language → file extensions. Sourced from `source-dir-detector.ts`'s
- * `EXTENSIONS` map. Re-exported here as the canonical type for AST
- * adapter sampling. Keys are `TreeSitterLanguage` so any adapter that
- * targets a language not in this map fails the drift test (see
- * `sample-files-coverage.test.ts`).
- */
-export const SAMPLE_EXTENSIONS: Record<TreeSitterLanguage, readonly string[]> = {
-  python: ['py'],
-  typescript: ['ts', 'tsx'],
-  javascript: ['js', 'jsx', 'mjs', 'cjs'],
-  swift: ['swift'],
-  rust: ['rs'],
-  go: ['go'],
-  ruby: ['rb'],
-  php: ['php'],
-  java: ['java', 'kt'],
-  kotlin: ['kt', 'kts'],
-  elixir: ['ex', 'exs'],
-  erlang: ['erl', 'hrl'],
-  csharp: ['cs'],
-  cpp: ['cpp', 'cc', 'cxx', 'h', 'hpp'],
-  haskell: ['hs', 'lhs'],
-  ocaml: ['ml', 'mli'],
-};
-
-/**
- * Test-file patterns to exclude per language. Mirrors
- * `source-dir-detector.ts:TEST_FILE_PATTERNS`. Adapters extracting
- * "production" routing/auth/etc. conventions don't want to be misled by
- * test fixtures.
- */
-export const SAMPLE_TEST_FILE_PATTERNS: Record<TreeSitterLanguage, readonly RegExp[]> = {
-  python: [/_test\.py$/, /test_[^/]*\.py$/, /\/tests?\//],
-  typescript: [/\.test\.tsx?$/, /\.spec\.tsx?$/, /\/__tests__\//],
-  javascript: [/\.test\.[mc]?jsx?$/, /\.spec\.[mc]?jsx?$/, /\/__tests__\//],
-  swift: [/Tests\//],
-  rust: [/tests\/.*\.rs$/],
-  go: [/_test\.go$/],
-  ruby: [/_spec\.rb$/, /_test\.rb$/, /\/spec\//],
-  php: [/Test\.php$/, /\/tests?\//i],
-  java: [/Test[^/]*\.(java|kt)$/, /[^/]*Test\.(java|kt)$/, /\/test\//],
-  kotlin: [/Test[^/]*\.kt$/, /[^/]*Test\.kt$/],
-  elixir: [/_test\.exs$/, /\/test\//],
-  erlang: [/_SUITE\.erl$/],
-  csharp: [/Tests?\.cs$/, /\.Tests?\//],
-  cpp: [/_test\.(cpp|cc)$/i, /\/tests?\//i],
-  haskell: [/Spec\.hs$/, /\/test\//],
-  ocaml: [/_test\.ml$/, /\/test\//],
-};
-
-const IGNORED_DIRS = new Set([
-  'node_modules', '.venv', 'venv', '__pycache__', 'dist', 'build', '.build',
-  'target', '.next', '.nuxt', 'coverage', '.git', '.massu', '.turbo',
-  '.cache', '.pytest_cache', '.mypy_cache', 'DerivedData', 'Pods',
-  '_build', 'deps', 'priv', 'cover', '.elixir_ls', // Elixir/Phoenix
-  'bin', 'obj', '.vs', 'packages', 'publish', 'TestResults', // .NET
-]);
-
-export interface SampleFilesOptions {
-  /** Maximum directory depth to walk from each source dir. Default 3. */
-  maxDepth?: number;
-  /** Maximum total files to return per adapter. Default 50. */
-  maxFilesPerAdapter?: number;
-}
-
-const DEFAULT_MAX_DEPTH = 3;
-const DEFAULT_MAX_FILES = 50;
-
-/**
- * Sample source files for an AST adapter.
- *
- * @param adapter - the adapter declaring `languages: TreeSitterLanguage[]`
- * @param projectRoot - absolute project root
- * @param detection - existing detection result (provides per-language
- *   source dirs from `source-dir-detector`)
- * @param options - depth and count caps
- */
-export function sampleFilesForAdapter(
-  adapter: CodebaseAdapter,
-  projectRoot: string,
-  detection: DetectionResult,
-  options: SampleFilesOptions = {},
-): SourceFile[] {
-  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
-  const maxFiles = options.maxFilesPerAdapter ?? DEFAULT_MAX_FILES;
-
-  const out: SourceFile[] = [];
-  const seen = new Set<string>(); // dedup by absolute path
-
-  for (const lang of adapter.languages) {
-    if (out.length >= maxFiles) break;
-    const exts = SAMPLE_EXTENSIONS[lang];
-    if (!exts || exts.length === 0) continue;
-    const testPatterns = SAMPLE_TEST_FILE_PATTERNS[lang] ?? [];
-
-    // Determine candidate dirs. Prefer detection.sourceDirs[lang] when
-    // present; otherwise walk projectRoot itself.
-    // (lang here is `TreeSitterLanguage`; sourceDirs is keyed by
-    // `SupportedLanguage`. The intersection is structural — every
-    // SupportedLanguage is a TreeSitterLanguage. We coerce via
-    // `Record<string, …>` lookup which is type-safe in a Record<string>.)
-    const langKey = lang as unknown as keyof typeof detection.sourceDirs;
-    const langDetection = detection.sourceDirs[langKey];
-    const candidateDirs: string[] = [];
-    if (langDetection?.source_dirs && langDetection.source_dirs.length > 0) {
-      candidateDirs.push(...langDetection.source_dirs.map((d: string) => join(projectRoot, d)));
-    } else {
-      candidateDirs.push(projectRoot);
-    }
-
-    for (const dir of candidateDirs) {
-      if (out.length >= maxFiles) break;
-      walkDir(dir, exts, testPatterns, lang, maxDepth, 0, out, seen, maxFiles);
-    }
-  }
-
-  return out;
-}
-
-function walkDir(
-  dir: string,
-  exts: readonly string[],
-  testPatterns: readonly RegExp[],
-  lang: TreeSitterLanguage,
-  maxDepth: number,
-  curDepth: number,
-  out: SourceFile[],
-  seen: Set<string>,
-  maxFiles: number,
-): void {
-  if (curDepth > maxDepth) return;
-  if (out.length >= maxFiles) return;
-  let entries: string[];
-  try {
-    entries = readdirSync(dir);
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (out.length >= maxFiles) return;
-    if (entry.startsWith('.')) continue; // hidden
-    if (IGNORED_DIRS.has(entry)) continue;
-    const fullPath = join(dir, entry);
-    let st;
-    try {
-      st = lstatSync(fullPath);
-    } catch {
-      continue;
-    }
-    if (st.isSymbolicLink()) continue; // refuse symlinks (security)
-    if (st.isDirectory()) {
-      walkDir(fullPath, exts, testPatterns, lang, maxDepth, curDepth + 1, out, seen, maxFiles);
-      continue;
-    }
-    if (!st.isFile()) continue;
-    if (st.size > MAX_AST_FILE_BYTES) continue; // size cap (parse-guard)
-    const ext = extname(entry).slice(1);
-    if (!exts.includes(ext)) continue;
-    if (testPatterns.some((p) => p.test(fullPath))) continue;
-    if (seen.has(fullPath)) continue;
-    seen.add(fullPath);
-    let content: string;
-    try {
-      content = readFileSync(fullPath, 'utf-8');
-    } catch {
-      continue;
-    }
-    out.push({
-      path: fullPath,
-      content,
-      language: lang,
-      size: st.size,
-    });
-  }
-}