@massu/core 1.2.1 → 1.4.0-soak.0

package/src/detect/codebase-introspector.ts

@@ -0,0 +1,190 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Codebase Introspector — 2-tier dispatcher (Plan 3b Phase 1)
+ * ============================================================
+ *
+ * Public signature: `introspect(detection, projectRoot): DetectedConventions`.
+ * Byte-for-byte unchanged from Plan #2 — `detect/index.ts` calls this
+ * function as before.
+ *
+ * Internal change (Plan 3b Phase 1): the function is now a 2-tier dispatcher.
+ *
+ *   Tier 1 — AST adapters (preferred). Run via `runner.ts` against the four
+ *   first-party adapters: python-fastapi, python-django, nextjs-trpc,
+ *   swift-swiftui. Each writes to its own `detected.<adapter.id>` block
+ *   alongside the regex blocks. AST adapters use Tree-sitter S-expression
+ *   queries — never regex. Confidence is per-field.
+ *
+ *   Tier 2 — Regex fallback. For fields the AST adapters returned 'none'
+ *   confidence on, the regex helpers in `regex-fallback.ts` (verbatim moved
+ *   from this file's previous incarnation) take over. AST-wins rule: when
+ *   both tiers produce a value for the same `detected.<lang>.<field>` slot,
+ *   AST wins; the runner records both in provenance.
+ *
+ *   Tier 3 — null. The template engine's `| default("...")` then takes over.
+ *
+ * The AST tier may degrade silently to regex-only when:
+ *   - The Tree-sitter grammar is unavailable offline AND uncached
+ *   - The adapter throws (per-adapter try/catch in `runner.ts`)
+ *   - The grammar SHA-256 doesn't match the manifest (refused by loader)
+ *
+ * Exception: if a Tree-sitter query is malformed (developer bug), the loader
+ * propagates `InvalidQueryError` so we don't silently mask it.
+ */
+
+import type { DetectionResult } from './index.ts';
+import {
+  introspectPython,
+  introspectSwift,
+  introspectTypeScript,
+  type DetectedPython,
+  type DetectedSwift,
+  type DetectedTypeScript,
+} from './regex-fallback.ts';
+import { runAdapters, buildDetectionSignals } from './adapters/runner.ts';
+import { pythonFastApiAdapter } from './adapters/python-fastapi.ts';
+import { pythonDjangoAdapter } from './adapters/python-django.ts';
+import { nextjsTrpcAdapter } from './adapters/nextjs-trpc.ts';
+import { swiftSwiftUiAdapter } from './adapters/swift-swiftui.ts';
+import type { CodebaseAdapter, AdapterResolved } from './adapters/types.ts';
+
+// ============================================================
+// Public types — unchanged from Plan #2 to preserve consumers
+// ============================================================
+
+export type { DetectedPython, DetectedSwift, DetectedTypeScript };
+
+export interface DetectedConventions {
+  python?: DetectedPython;
+  swift?: DetectedSwift;
+  typescript?: DetectedTypeScript;
+  /**
+   * AST adapter blocks live here (Plan 3b). Keys are adapter ids
+   * (`python-fastapi`, etc.). Values include both extracted conventions and
+   * a `_provenance` map.
+   */
+  [adapterId: string]: unknown;
+}
+
+// ============================================================
+// Static adapter list (v1 — first-party only, per spec §6)
+// ============================================================
+
+const FIRST_PARTY_ADAPTERS: CodebaseAdapter[] = [
+  pythonFastApiAdapter,
+  pythonDjangoAdapter,
+  nextjsTrpcAdapter,
+  swiftSwiftUiAdapter,
+];
+
+// ============================================================
+// Public entry point
+// ============================================================
+
+/**
+ * Introspect the project's source files. Returns per-language conventions or
+ * an empty object if nothing was extracted.
+ *
+ * Synchronous signature is preserved — AST adapter execution is intentionally
+ * fire-and-forget at this layer. Phase 1 wires the adapter pipeline behind
+ * the existing sync function so `detect/index.ts` is byte-for-byte unchanged
+ * (plan line 137-142). The async adapter orchestration lives entirely inside
+ * `runIntrospect()`, which `introspect()` does NOT await — adapters either
+ * have their grammars cached (fast path, no async needed at the JS level by
+ * Phase 4 wiring) or degrade to regex.
+ *
+ * For Phase 1 Tier 1 to actually contribute values, callers must use the
+ * async variant `introspectAsync()`. The sync `introspect()` runs the regex
+ * tier ONLY for Phase 1; Phase 4 callers (LSP enrichment + adapter wiring)
+ * will switch to async.
+ */
+export function introspect(
+  detection: DetectionResult,
+  projectRoot: string,
+): DetectedConventions {
+  const out: DetectedConventions = {};
+  const languages = Array.from(
+    new Set(detection.manifests.map(m => m.language)),
+  );
+
+  // Tier 2 — regex fallback. Always runs. AST adapters in the async variant
+  // (`introspectAsync`) populate `detected.<adapter-id>` alongside; for the
+  // sync entry point, only the regex tier participates so Plan #2 callers
+  // see no behavior change.
+  if (languages.includes('python')) {
+    const python = introspectPython(detection, projectRoot);
+    if (python !== null) out.python = python;
+  }
+
+  if (languages.includes('swift')) {
+    const swift = introspectSwift(detection, projectRoot);
+    if (swift !== null) out.swift = swift;
+  }
+
+  if (languages.includes('typescript') || languages.includes('javascript')) {
+    const ts = introspectTypeScript(detection, projectRoot);
+    if (ts !== null) out.typescript = ts;
+  }
+
+  return out;
+}
+
+// ============================================================
+// Async variant — used by callers who want AST tier participation
+// ============================================================
+
+/**
+ * Async introspect: runs AST adapters first (Tier 1), then regex fallback
+ * (Tier 2) for fields the adapters returned 'none' on.
+ *
+ * Returns the same `DetectedConventions` shape as the sync `introspect()`,
+ * plus per-adapter blocks under their ids.
+ *
+ * Callers who can `await` (CLI commands, tests, etc.) should prefer this
+ * variant. The session-start hook keeps using sync `introspect()` for its
+ * 5s budget reason (P4-006).
+ */
+export async function introspectAsync(
+  detection: DetectionResult,
+  projectRoot: string,
+): Promise<DetectedConventions> {
+  const out: DetectedConventions = introspect(detection, projectRoot);
+
+  // Build signals + run AST adapters
+  const signals = buildDetectionSignals(projectRoot);
+  let merged;
+  try {
+    merged = await runAdapters(FIRST_PARTY_ADAPTERS, projectRoot, signals, {
+      sampleFiles: async (_adapter, _root) => {
+        // Phase 1 placeholder: file sampling for adapters is wired in
+        // dedicated harnesses (per-adapter tests inject SourceFile[] directly).
+        // The introspector tier doesn't yet sample for AST adapters — that
+        // wiring lands together with Phase 4 LSP enrichment so the same path
+        // serves both. For now, returning [] keeps adapters at 'none' which
+        // means `out` is regex-only — consistent with the sync path and the
+        // pre-Phase-1 baseline test suite.
+        return [];
+      },
+    });
+  } catch {
+    return out;
+  }
+
+  for (const [adapterId, resolved] of Object.entries(merged.byAdapter)) {
+    if (resolved.confidence === 'none') continue;
+    out[adapterId] = serializeAdapterBlock(resolved);
+  }
+
+  return out;
+}
+
+function serializeAdapterBlock(r: AdapterResolved): Record<string, unknown> {
+  const block: Record<string, unknown> = { ...r.conventions };
+  if (Object.keys(r._provenance).length > 0) {
+    block._provenance = r._provenance;
+  }
+  block._confidence = r.confidence;
+  return block;
+}

package/src/detect/index.ts

@@ -54,6 +54,10 @@ import {
   type UserVerificationEntry,
 } from './vr-command-map.ts';
 import { inferDomains } from './domain-inferrer.ts';
+import {
+  introspect,
+  type DetectedConventions,
+} from './codebase-introspector.ts';
 
 export type {
   PackageManifest,
@@ -97,6 +101,18 @@ export interface DetectionResult {
   verificationCommands: Partial<Record<SupportedLanguage, VRCommandSet>>;
   /** Non-fatal warnings collected across all detectors. */
   warnings: DetectionWarning[];
+  /** Plan #2 P3-001: per-language conventions sampled from existing source. */
+  detected?: DetectedConventions;
+}
+
+/** Plan #2 P3-002: opt-out of the codebase introspector. */
+export interface RunDetectionOptions {
+  /**
+   * When true, skip the codebase introspector pass. Used by the session-start
+   * hook (P4-006) to keep its 5-second budget intact — the drift banner only
+   * needs the fingerprint, not introspection detail.
+   */
+  skipIntrospect?: boolean;
 }
 
 function dominantDir(
@@ -122,7 +138,8 @@ function dominantDir(
  */
 export async function runDetection(
   projectRoot: string,
-  overrides?: DetectionConfigOverrides
+  overrides?: DetectionConfigOverrides,
+  options?: RunDetectionOptions,
 ): Promise<DetectionResult> {
   // 1. packages
   const pkg = detectPackageManifests(projectRoot);
@@ -170,7 +187,7 @@ export async function runDetection(
     verificationCommands[lang] = getVRCommands(lang, fw, dir, userOverride);
   }
 
-  return {
+  const result: DetectionResult = {
     projectRoot,
     manifests: pkg.manifests,
     frameworks,
@@ -180,4 +197,13 @@ export async function runDetection(
     verificationCommands,
     warnings: pkg.warnings,
   };
+
+  // P3-002: codebase introspector pass. Skipped when the caller opts out
+  // (the session-start hook at hooks/session-start.ts:272 passes
+  // `{ skipIntrospect: true }` to keep its 5s budget intact — see P4-006).
+  if (!options?.skipIntrospect) {
+    result.detected = introspect(result, projectRoot);
+  }
+
+  return result;
 }

package/src/detect/regex-fallback.ts

@@ -0,0 +1,449 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 1: Regex Fallback Introspector.
+ *
+ * Verbatim move of the per-language regex helpers that were previously in
+ * `codebase-introspector.ts` (Plan #2 P3-001). NO regex logic changes — only
+ * the import path. This preserves Plan #2's 13 vitest cases as-is (re-imports
+ * are updated in `codebase-introspector.test.ts` only if needed; the moved
+ * functions retain their original signatures).
+ *
+ * The new 2-tier introspector (`codebase-introspector.ts`) calls these
+ * functions ONLY for fields where AST adapters returned 'none' confidence.
+ * AST adapters produce values into separate `detected.<adapter.id>` blocks;
+ * regex output continues to go into `detected.python` / `.swift` /
+ * `.typescript` blocks.
+ *
+ * Design rules carried over from Plan #2:
+ *   - File size cap: 256KB per file (skip silently if larger).
+ *   - Sample cap: at most 3 files per adapter (sorted, deterministic order).
+ *   - Total wall-clock budget: <2s on a 10K-file repo.
+ *   - Filesystem-only. No network, no child processes, no DB.
+ *   - Returns `null` for any field it can't confidently extract.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { resolve, join, basename } from 'path';
+import type { DetectionResult } from './index.ts';
+
+export const MAX_FILE_BYTES = 256 * 1024;
+export const MAX_SAMPLES_PER_ADAPTER = 3;
+export const MAX_DIR_DEPTH = 6;
+
+// ============================================================
+// Public types (re-exported from codebase-introspector for compat)
+// ============================================================
+
+export interface DetectedPython {
+  auth_dep?: string;
+  api_prefix_base?: string;
+  test_async_pattern?: string;
+  _provenance?: Record<string, string>;
+}
+
+export interface DetectedSwift {
+  api_client_class?: string;
+  biometric_policy?: string;
+  _provenance?: Record<string, string>;
+}
+
+export interface DetectedTypeScript {
+  trpc_router_builder?: string;
+  procedure_pattern?: string;
+  _provenance?: Record<string, string>;
+}
+
+// ============================================================
+// Python adapter (FastAPI + Django)
+// ============================================================
+
+/**
+ * Introspect Python sources. Probes both FastAPI router files (`routers/*.py`,
+ * `api/*.py`) and Django views (`views.py`). Returns the most-extracted shape.
+ */
+export function introspectPython(
+  detection: DetectionResult,
+  projectRoot: string,
+): DetectedPython | null {
+  const sourceDir = resolveSourceDir(detection, 'python', projectRoot);
+  if (!sourceDir) return null;
+
+  // Sample router-shaped files first (FastAPI / Flask), then views.py (Django),
+  // then any .py file as a last resort. Match on PATH, not just filename:
+  // FastAPI projects typically name routers by resource (`options.py`, `tax.py`)
+  // and place them under a `routers/` directory, so basename-only matching
+  // misses them. Also accept files where the basename itself is router-shaped
+  // (e.g., `endpoints.py`, `api.py`).
+  const routerFiles = sampleFiles(sourceDir, /\.py$/, (absPath, name) =>
+    /\/(routers?|api|endpoints?|views)\//.test(absPath) ||
+    /^(routers?|api|endpoints?)\.py$/.test(name),
+  );
+  const viewFiles = sampleFiles(sourceDir, /^views\.py$/);
+  const fallbackFiles = routerFiles.length === 0 && viewFiles.length === 0
+    ? sampleFiles(sourceDir, /\.py$/)
+    : [];
+  const candidates = [...routerFiles, ...viewFiles, ...fallbackFiles].slice(
+    0,
+    MAX_SAMPLES_PER_ADAPTER,
+  );
+
+  if (candidates.length === 0) return null;
+
+  const authDeps = new Map<string, string>(); // value → first source path
+  const prefixBases = new Map<string, string>();
+  const testAsyncPatterns = new Map<string, string>();
+
+  for (const path of candidates) {
+    const body = readSafe(path);
+    if (body === null) continue;
+
+    // Auth dependency: `Depends(<name>)` — capture the call's argument.
+    // ReDoS-safe: anchored, short window, no nested quantifiers.
+    const authRegex = /\bDepends\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)/gu;
+    forEachMatch(authRegex, body, m => {
+      const name = m[1];
+      if (!authDeps.has(name)) authDeps.set(name, path);
+    });
+
+    // Django: `@login_required` or `@permission_required` decorators.
+    const djangoAuthRegex = /^@\s*([a-z_][a-z0-9_]*(?:_required|_login))\b/gmu;
+    forEachMatch(djangoAuthRegex, body, m => {
+      const name = m[1];
+      if (!authDeps.has(name)) authDeps.set(name, path);
+    });
+
+    // API prefix base: `APIRouter(prefix="/api/...")` — capture just the BASE
+    // (everything up to the second `/` from the start).
+    const prefixRegex = /\bAPIRouter\s*\(\s*[^)]*?prefix\s*=\s*["']([^"']+)["']/gu;
+    forEachMatch(prefixRegex, body, m => {
+      const fullPrefix = m[1];
+      const base = extractPrefixBase(fullPrefix);
+      if (base && !prefixBases.has(base)) prefixBases.set(base, path);
+    });
+
+    // Test async pattern: `@pytest.mark.asyncio` (with possible parens).
+    const asyncRegex = /^(@pytest\.mark\.asyncio(?:\s*\([^)]*\))?)/gmu;
+    forEachMatch(asyncRegex, body, m => {
+      const pat = m[1].trim();
+      if (!testAsyncPatterns.has(pat)) testAsyncPatterns.set(pat, path);
+    });
+  }
+
+  const authDep = pickBestSingleton(authDeps);
+  const apiPrefixBase = pickBestSingleton(prefixBases);
+  const testAsyncPattern = pickBestSingleton(testAsyncPatterns);
+
+  const result: DetectedPython = {};
+  const provenance: Record<string, string> = {};
+
+  if (authDep) {
+    result.auth_dep = authDep.value;
+    provenance.auth_dep_source = relativeTo(projectRoot, authDep.source);
+  }
+  if (apiPrefixBase) {
+    result.api_prefix_base = apiPrefixBase.value;
+    provenance.api_prefix_base_source = relativeTo(projectRoot, apiPrefixBase.source);
+  }
+  if (testAsyncPattern) {
+    result.test_async_pattern = testAsyncPattern.value;
+    provenance.test_async_pattern_source = relativeTo(projectRoot, testAsyncPattern.source);
+  }
+
+  // Only emit a language block when at least one real field was extracted.
+  // An empty result (provenance-only) clutters the YAML for no value.
+  if (Object.keys(result).length === 0) return null;
+  if (Object.keys(provenance).length > 0) result._provenance = provenance;
+  return result;
+}
+
+/**
+ * Reduce `/api/foo/bar` to `/api`. Returns null if the path doesn't have at
+ * least one slash-segment.
+ */
+function extractPrefixBase(prefix: string): string | null {
+  if (!prefix.startsWith('/')) return null;
+  const stripped = prefix.replace(/^\/+/, '');
+  const firstSeg = stripped.split('/')[0];
+  if (!firstSeg) return null;
+  return '/' + firstSeg;
+}
+
+// ============================================================
+// Swift adapter
+// ============================================================
+
+export function introspectSwift(
+  detection: DetectionResult,
+  projectRoot: string,
+): DetectedSwift | null {
+  const sourceDir = resolveSourceDir(detection, 'swift', projectRoot);
+  if (!sourceDir) return null;
+
+  // Prefer View files first, then any .swift. Path-aware: also match files
+  // under a `Views/` directory, since SwiftUI projects often name files by
+  // feature (e.g., `OrdersList.swift` inside `Features/Orders/Views/`).
+  const viewFiles = sampleFiles(sourceDir, /\.swift$/, (absPath, name) =>
+    /View\.swift$/.test(name) || /\/Views\//.test(absPath),
+  );
+  const fallbackFiles = viewFiles.length === 0
+    ? sampleFiles(sourceDir, /\.swift$/)
+    : [];
+  const candidates = [...viewFiles, ...fallbackFiles].slice(
+    0,
+    MAX_SAMPLES_PER_ADAPTER,
+  );
+
+  if (candidates.length === 0) return null;
+
+  const apiClasses = new Map<string, string>();
+  const biometricPolicies = new Map<string, string>();
+
+  for (const path of candidates) {
+    const body = readSafe(path);
+    if (body === null) continue;
+
+    // API client class: looks like `let api = SomeAPI()` or
+    // `@StateObject var api: SomeAPI = .shared` etc.
+    // Extract `SomeAPI` from `SomeAPI(`/`SomeAPI.shared`/`: SomeAPI`.
+    const apiRegex = /\b([A-Z][A-Za-z0-9_]*API)\s*(?:\(|\.shared|\b)/gu;
+    forEachMatch(apiRegex, body, m => {
+      const name = m[1];
+      if (!apiClasses.has(name)) apiClasses.set(name, path);
+    });
+
+    // LocalAuthentication policy: `LAPolicy.<name>` or `.<name>` after
+    // `evaluatePolicy(`. Whitelist known good values to avoid false positives.
+    const policyRegex = /\.(deviceOwnerAuthentication(?:WithBiometrics)?)\b/gu;
+    forEachMatch(policyRegex, body, m => {
+      const name = m[1];
+      if (!biometricPolicies.has(name)) biometricPolicies.set(name, path);
+    });
+  }
+
+  const apiClass = pickBestSingleton(apiClasses);
+  const biometricPolicy = pickBestSingleton(biometricPolicies);
+
+  const result: DetectedSwift = {};
+  const provenance: Record<string, string> = {};
+
+  if (apiClass) {
+    result.api_client_class = apiClass.value;
+    provenance.api_client_class_source = relativeTo(projectRoot, apiClass.source);
+  }
+  if (biometricPolicy) {
+    result.biometric_policy = biometricPolicy.value;
+    provenance.biometric_policy_source = relativeTo(projectRoot, biometricPolicy.source);
+  }
+
+  if (Object.keys(result).length === 0) return null;
+  if (Object.keys(provenance).length > 0) result._provenance = provenance;
+  return result;
+}
+
+// ============================================================
+// TypeScript / Next.js + tRPC adapter
+// ============================================================
+
+export function introspectTypeScript(
+  detection: DetectionResult,
+  projectRoot: string,
+): DetectedTypeScript | null {
+  const sourceDir = resolveSourceDir(detection, 'typescript', projectRoot)
+    ?? resolveSourceDir(detection, 'javascript', projectRoot);
+  if (!sourceDir) return null;
+
+  // Look for tRPC router files first. Match on PATH or filename: tRPC
+  // projects typically place routers under `server/api/routers/<name>.ts`
+  // where filenames are resource-named (e.g., `accounts.ts`).
+  const routerFiles = sampleFiles(sourceDir, /\.tsx?$/, (absPath, name) =>
+    /(router|trpc)/i.test(name) ||
+    /\/(routers|trpc|server\/api)\//.test(absPath),
+  );
+  const candidates = routerFiles.slice(0, MAX_SAMPLES_PER_ADAPTER);
+
+  if (candidates.length === 0) return null;
+
+  const builders = new Map<string, string>();
+  const procedurePatterns = new Map<string, string>();
+
+  for (const path of candidates) {
+    const body = readSafe(path);
+    if (body === null) continue;
+
+    // tRPC router builder: `createTRPCRouter({ ... })`. Whitelist known names
+    // (createTRPCRouter, router, t.router) — never grep for arbitrary identifiers.
+    const builderRegex = /\b(createTRPCRouter|router|t\.router)\s*\(/gu;
+    forEachMatch(builderRegex, body, m => {
+      const name = m[1];
+      if (!builders.has(name)) builders.set(name, path);
+    });
+
+    // Procedure pattern: `publicProcedure.input(...).query(...)` →
+    // capture just the procedure name (`publicProcedure`/`protectedProcedure`).
+    const procRegex = /\b([a-z]+Procedure)\b/gu;
+    forEachMatch(procRegex, body, m => {
+      const name = m[1];
+      if (!procedurePatterns.has(name)) procedurePatterns.set(name, path);
+    });
+  }
+
+  const builder = pickBestSingleton(builders);
+  const proc = pickBestSingleton(procedurePatterns);
+
+  const result: DetectedTypeScript = {};
+  const provenance: Record<string, string> = {};
+
+  if (builder) {
+    result.trpc_router_builder = builder.value;
+    provenance.trpc_router_builder_source = relativeTo(projectRoot, builder.source);
+  }
+  if (proc) {
+    result.procedure_pattern = proc.value;
+    provenance.procedure_pattern_source = relativeTo(projectRoot, proc.source);
+  }
+
+  if (Object.keys(result).length === 0) return null;
+  if (Object.keys(provenance).length > 0) result._provenance = provenance;
+  return result;
+}
+
+// ============================================================
+// Helpers
+// ============================================================
+
+/**
+ * Resolve the dominant source directory for a language, falling back to the
+ * project root if detection didn't surface anything specific.
+ */
+function resolveSourceDir(
+  detection: DetectionResult,
+  lang: string,
+  projectRoot: string,
+): string | null {
+  const dirs = (detection.sourceDirs as unknown as Record<string, { source_dirs?: string[] }>);
+  const info = dirs[lang];
+  const list = info?.source_dirs ?? [];
+  if (list.length > 0) {
+    const first = list[0];
+    const abs = resolve(projectRoot, first);
+    return existsSync(abs) ? abs : null;
+  }
+  return existsSync(projectRoot) ? projectRoot : null;
+}
+
+/**
+ * Walk `dir` and return up to MAX_SAMPLES_PER_ADAPTER files matching `nameRegex`,
+ * filtered further by `pathFilter` (called with absolute path AND basename, so
+ * filters can match either the filename (e.g., `views.py`) or a path
+ * component (e.g., a `routers/` parent directory). Skips dot-dirs,
+ * node_modules, .venv, etc. Bounded depth.
+ */
+export function sampleFiles(
+  dir: string,
+  nameRegex: RegExp,
+  pathFilter?: (absPath: string, basename: string) => boolean,
+): string[] {
+  const out: string[] = [];
+  const stack: { path: string; depth: number }[] = [{ path: dir, depth: 0 }];
+
+  while (stack.length > 0 && out.length < MAX_SAMPLES_PER_ADAPTER * 4) {
+    const { path, depth } = stack.pop()!;
+    if (depth > MAX_DIR_DEPTH) continue;
+
+    let entries: string[];
+    try {
+      entries = readdirSync(path);
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (entry.startsWith('.')) continue;
+      if (entry === 'node_modules') continue;
+      if (entry === '__pycache__') continue;
+      if (entry === 'venv' || entry === '.venv') continue;
+      if (entry === 'dist' || entry === 'build') continue;
+
+      const child = join(path, entry);
+      let st;
+      try {
+        st = statSync(child);
+      } catch {
+        continue;
+      }
+
+      if (st.isDirectory()) {
+        stack.push({ path: child, depth: depth + 1 });
+        continue;
+      }
+
+      if (!nameRegex.test(entry)) continue;
+      if (pathFilter && !pathFilter(child, entry)) continue;
+      if (st.size > MAX_FILE_BYTES) continue;
+      out.push(child);
+      if (out.length >= MAX_SAMPLES_PER_ADAPTER * 4) break;
+    }
+  }
+
+  // Stable ordering — deterministic test fixtures.
+  out.sort();
+  return out.slice(0, MAX_SAMPLES_PER_ADAPTER * 2);
+}
+
+/** Read a file as UTF-8. Returns null on any error or if too large. */
+export function readSafe(path: string): string | null {
+  try {
+    const st = statSync(path);
+    if (st.size > MAX_FILE_BYTES) return null;
+    return readFileSync(path, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run a global regex over `body` and call `cb` for each match. Caps iteration
+ * at 1000 matches per regex to defend against pathological inputs.
+ */
+export function forEachMatch(
+  re: RegExp,
+  body: string,
+  cb: (m: RegExpExecArray) => void,
+): void {
+  if (!re.global) return;
+  re.lastIndex = 0;
+  let count = 0;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(body)) !== null) {
+    cb(m);
+    count++;
+    if (count > 1000) break;
+    // Defensive: zero-width match → bump lastIndex to avoid infinite loop.
+    if (m.index === re.lastIndex) re.lastIndex++;
+  }
+}
+
+/**
+ * If `samples` has exactly one distinct value, return it.
+ * If it has 2 values, return the first-seen (stable, deterministic order from
+ * file walk).
+ * If it has 3+ distinct values, return null — Risk #6 (auth-dep ambiguity).
+ */
+export function pickBestSingleton(
+  samples: Map<string, string>,
+): { value: string; source: string } | null {
+  if (samples.size === 0) return null;
+  if (samples.size >= 3) return null;
+  const [firstKey, firstSource] = samples.entries().next().value as [string, string];
+  return { value: firstKey, source: firstSource };
+}
+
+/** Make a file path relative to the project root. */
+export function relativeTo(projectRoot: string, absPath: string): string {
+  if (absPath.startsWith(projectRoot + '/')) {
+    return absPath.slice(projectRoot.length + 1);
+  }
+  return basename(absPath);
+}