@avi770/testteam 3.0.0 → 3.2.0

package/dist/agents/87-connection-mapper.js

@@ -0,0 +1,658 @@
+/**
+ * Connection Mapper Agent — static analysis of the project under test.
+ *
+ * Walks the target project (config.projectRoot, defaults to cwd) and builds a
+ * connection graph describing how the codebase is wired together:
+ *
+ *   - file → file imports (which symbols)
+ *   - HTTP route registrations (Express, Next pages/app, NestJS, Fastify)
+ *   - React hook usage (built-in and custom)
+ *   - event emitter / listener handlers
+ *
+ * The graph is persisted to `evidence/connection-map.json` so Agent #88
+ * (Localhost Walkthrough) can drive a deterministic walk against the
+ * discovered routes and modules.
+ *
+ * As a side effect, surfaces structural findings:
+ *   - orphans  (exports that nothing imports)
+ *   - cycles   (A → B → A)
+ *   - untested (source files with no corresponding *.test.* or *.spec.*)
+ *
+ * Static-only: never spawns subprocesses, never makes network calls.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { BaseAgent } from './base-agent.js';
+import { isTestPath } from './lib/source-scan.js';
+const SRC_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', '.next', '.nuxt', '.run', 'coverage', 'reports', 'baselines',
+]);
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS', 'HEAD', 'ALL'];
+function walk(dir, results = [], rootMarker = dir) {
+    if (!fs.existsSync(dir))
+        return results;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            walk(full, results, rootMarker);
+        }
+        else if (entry.isFile() && SRC_EXTENSIONS.has(path.extname(entry.name))) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function isTestFile(file, root) {
+    // Filename conventions (.test./.spec./-spec/NestJS e2e-spec) plus test
+    // directories (tests/, test/, __tests__/, type-tests/, e2e/, …). Pass root
+    // so an absolute path is judged relative to the project — see isTestPath.
+    return isTestPath(file, root);
+}
+function extractExports(content) {
+    const names = new Set();
+    const decl = /export\s+(?:async\s+)?(?:function|class|const|let|var|type|interface|enum)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
+    let m;
+    while ((m = decl.exec(content)) !== null)
+        names.add(m[1]);
+    const named = /export\s*\{([^}]+)\}/g;
+    while ((m = named.exec(content)) !== null) {
+        for (const piece of m[1].split(',')) {
+            const sym = piece.trim().split(/\s+as\s+/)[0].trim();
+            if (sym)
+                names.add(sym);
+        }
+    }
+    if (/export\s+default\b/.test(content))
+        names.add('default');
+    return [...names];
+}
+/**
+ * Names exported as a `type` or `interface` (plus `export type { … }`
+ * re-exports) — these are erased at runtime, so importing only these names
+ * (even without the `import type` keyword) can't form a runtime cycle.
+ */
+function extractTypeOnlyExports(content) {
+    const names = new Set();
+    const decl = /export\s+(type|interface)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
+    let m;
+    while ((m = decl.exec(content)) !== null)
+        names.add(m[2]);
+    // `export type { A, B }` re-exports
+    const named = /export\s+type\s*\{([^}]+)\}/g;
+    while ((m = named.exec(content)) !== null) {
+        for (const piece of m[1].split(',')) {
+            const sym = piece.trim().split(/\s+as\s+/).pop().trim();
+            if (sym)
+                names.add(sym);
+        }
+    }
+    return names;
+}
+function extractImports(content) {
+    const out = [];
+    // import { a, b as c } from 'spec'  (also `import type { … }` / `import { type a }`)
+    const named = /import\s+(type\s+)?\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/g;
+    let m;
+    while ((m = named.exec(content)) !== null) {
+        const wholeType = !!m[1];
+        const raw = m[2].split(',').map((s) => s.trim()).filter(Boolean);
+        const symbols = raw.map((s) => s.replace(/^type\s+/, '').split(/\s+as\s+/)[0].trim());
+        // Type-only when the whole import is `import type {` or every specifier is `type X`.
+        const typeOnly = wholeType || (raw.length > 0 && raw.every((s) => /^type\s+/.test(s)));
+        out.push({ spec: m[3], symbols, typeOnly });
+    }
+    // import X from 'spec' (default)
+    const def = /import\s+([A-Za-z_$][A-Za-z0-9_$]*)\s+from\s+['"]([^'"]+)['"]/g;
+    while ((m = def.exec(content)) !== null) {
+        out.push({ spec: m[2], symbols: ['default'], typeOnly: false });
+    }
+    // import * as X from 'spec'
+    const star = /import\s+\*\s+as\s+[A-Za-z_$][A-Za-z0-9_$]*\s+from\s+['"]([^'"]+)['"]/g;
+    while ((m = star.exec(content)) !== null) {
+        out.push({ spec: m[1], symbols: ['*'], typeOnly: false });
+    }
+    // CommonJS: const x = require('spec') / const { a } = require('spec') / bare require('spec').
+    // Without this, a CommonJS project has an empty import graph and every file
+    // looks orphaned. require() is always a runtime edge (never type-only).
+    const req = /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    while ((m = req.exec(content)) !== null) {
+        out.push({ spec: m[1], symbols: ['*'], typeOnly: false });
+    }
+    // Dynamic import('spec') / await import('spec') (lazy / code-split — runtime edge).
+    const dyn = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    while ((m = dyn.exec(content)) !== null) {
+        out.push({ spec: m[1], symbols: ['*'], typeOnly: false });
+    }
+    // Re-exports: export * from 'spec' / export * as ns from 'spec' / export { a, b } from 'spec'.
+    // A barrel that re-exports a module makes it reachable, so without these edges
+    // barrel-only modules (the common index.ts pattern) look orphaned. `export type`
+    // re-exports are runtime-erased and stay type-only (no false cycle).
+    const reexport = /export\s+(type\s+)?(?:\*(?:\s+as\s+[A-Za-z_$][\w$]*)?|\{([^}]*)\})\s+from\s+['"]([^'"]+)['"]/g;
+    while ((m = reexport.exec(content)) !== null) {
+        const inner = m[2];
+        const typeOnly = !!m[1] || (inner != null && inner.trim().length > 0 && inner.split(',').every((s) => /^\s*type\s/.test(s)));
+        out.push({ spec: m[3], symbols: ['*'], typeOnly });
+    }
+    return out;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Remove // and /* *\/ comments without touching comment-like sequences inside strings. */
+function stripJsonComments(input) {
+    let out = '';
+    let inString = false;
+    let quote = '';
+    let inLine = false;
+    let inBlock = false;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        const next = input[i + 1];
+        if (inLine) {
+            if (ch === '\n') {
+                inLine = false;
+                out += ch;
+            }
+            continue;
+        }
+        if (inBlock) {
+            if (ch === '*' && next === '/') {
+                inBlock = false;
+                i++;
+            }
+            continue;
+        }
+        if (inString) {
+            out += ch;
+            if (ch === '\\') {
+                out += next ?? '';
+                i++;
+            }
+            else if (ch === quote) {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inString = true;
+            quote = ch;
+            out += ch;
+        }
+        else if (ch === '/' && next === '/') {
+            inLine = true;
+            i++;
+        }
+        else if (ch === '/' && next === '*') {
+            inBlock = true;
+            i++;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}
+/**
+ * Read `compilerOptions.baseUrl` + `paths` from the project's tsconfig so that
+ * path-alias imports (`@/lib/x`, `~/utils`) resolve to real files. Without this,
+ * every alias import looks like an external package and its target looks orphaned —
+ * a massive false-positive source on any aliased project (Next.js `@/*` is the default).
+ */
+function loadAliasConfig(projectRoot) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(projectRoot, 'tsconfig.json'), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let json;
+    try {
+        // Most tsconfigs are plain JSON. Try that first — it never corrupts glob
+        // strings like "**/*.ts" (whose `/*` would fool a naive comment stripper).
+        json = JSON.parse(raw);
+    }
+    catch {
+        try {
+            // Fall back to JSONC: tsconfig also allows // and /* */ comments and
+            // trailing commas. Strip them string-aware so globs/URLs survive.
+            json = JSON.parse(stripJsonComments(raw).replace(/,(\s*[}\]])/g, '$1'));
+        }
+        catch {
+            return null;
+        }
+    }
+    const co = json.compilerOptions ?? {};
+    const baseUrl = typeof co.baseUrl === 'string' ? co.baseUrl : '.';
+    const baseDir = path.resolve(projectRoot, baseUrl);
+    const paths = [];
+    if (co.paths && typeof co.paths === 'object') {
+        for (const [pattern, targets] of Object.entries(co.paths)) {
+            if (!Array.isArray(targets))
+                continue;
+            const re = new RegExp('^' + pattern.split('*').map(escapeRegExp).join('(.*)') + '$');
+            paths.push({ re, targets: targets.filter((t) => typeof t === 'string') });
+        }
+    }
+    return { baseDir, paths };
+}
+function tryCandidates(base, allFiles) {
+    // TS ESM (NodeNext) imports the compiled `.js`/.mjs path but the source is
+    // `.ts`/.tsx — strip the JS extension so `import './x.js'` resolves to x.ts.
+    const stripped = base.replace(/\.(js|jsx|mjs|cjs)$/, '');
+    for (const candidateBase of stripped === base ? [base] : [base, stripped]) {
+        for (const ext of ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']) {
+            if (allFiles.has(candidateBase + ext))
+                return candidateBase + ext;
+            const indexFile = path.join(candidateBase, `index${ext}`);
+            if (allFiles.has(indexFile))
+                return indexFile;
+        }
+        if (allFiles.has(candidateBase))
+            return candidateBase;
+    }
+    return null;
+}
+function resolveImport(fromFile, spec, allFiles, alias) {
+    if (spec.startsWith('.') || spec.startsWith('/')) {
+        return tryCandidates(path.resolve(path.dirname(fromFile), spec), allFiles);
+    }
+    // Non-relative: try tsconfig path aliases before giving up as an external package.
+    if (alias) {
+        for (const { re, targets } of alias.paths) {
+            const m = spec.match(re);
+            if (!m)
+                continue;
+            const wildcard = m[1] ?? '';
+            for (const target of targets) {
+                const hit = tryCandidates(path.resolve(alias.baseDir, target.replaceAll('*', wildcard)), allFiles);
+                if (hit)
+                    return hit;
+            }
+        }
+    }
+    return null; // external package
+}
+function extractRoutes(content, file) {
+    const out = [];
+    const lines = content.split('\n');
+    // Express / Fastify: app.get('/path', ...) or router.post('/path', ...)
+    const express = /\b([a-z_$][\w$]*)\s*\.\s*(get|post|put|delete|patch|options|head|all)\s*\(\s*['"]([^'"]+)['"]/gi;
+    let m;
+    while ((m = express.exec(content)) !== null) {
+        const lineNum = content.slice(0, m.index).split('\n').length;
+        const framework = /fastify/i.test(lines[lineNum - 1] ?? '') ? 'fastify' : 'express';
+        out.push({
+            method: m[2].toUpperCase(),
+            path: m[3],
+            file,
+            line: lineNum,
+            framework,
+        });
+    }
+    // NestJS decorators: @Get('/path'), @Post(), @Controller('/base')
+    const nest = /@(Get|Post|Put|Delete|Patch|Options|Head|All)\s*\(\s*(?:['"]([^'"]*)['"])?\s*\)/g;
+    while ((m = nest.exec(content)) !== null) {
+        const lineNum = content.slice(0, m.index).split('\n').length;
+        out.push({
+            method: m[1].toUpperCase(),
+            path: m[2] ?? '',
+            file,
+            line: lineNum,
+            framework: 'nest',
+        });
+    }
+    // Next.js app router: any /app/**/route.{ts,tsx,js} that exports GET/POST/...
+    if (/[\\/]app[\\/].*[\\/]route\.[tj]sx?$/.test(file)) {
+        for (const method of HTTP_METHODS) {
+            const exp = new RegExp(`export\\s+(?:async\\s+)?function\\s+${method}\\b`);
+            const match = exp.exec(content);
+            if (match) {
+                const lineNum = content.slice(0, match.index).split('\n').length;
+                const pathFromFile = file
+                    .replace(/.*[\\/]app[\\/]/, '/')
+                    .replace(/[\\/]route\.[tj]sx?$/, '')
+                    .replace(/[\\/]\(.*?\)/g, '');
+                out.push({ method, path: pathFromFile || '/', file, line: lineNum, framework: 'next-app' });
+            }
+        }
+    }
+    // Next.js pages router: pages/api/**/*.{ts,js}
+    if (/[\\/]pages[\\/]api[\\/].*\.[tj]sx?$/.test(file)) {
+        if (/export\s+default\b/.test(content)) {
+            const pathFromFile = file
+                .replace(/.*[\\/]pages[\\/]api[\\/]/, '/api/')
+                .replace(/\.[tj]sx?$/, '')
+                .replace(/[\\/]index$/, '');
+            out.push({ method: 'ALL', path: pathFromFile, file, line: 1, framework: 'next-pages' });
+        }
+    }
+    return out;
+}
+function extractHooks(content, file) {
+    if (!/\.tsx?$/.test(file) && !/\.jsx?$/.test(file))
+        return [];
+    const out = [];
+    const hookCall = /\b(use[A-Z][A-Za-z0-9_]*)\s*\(/g;
+    let m;
+    while ((m = hookCall.exec(content)) !== null) {
+        const lineNum = content.slice(0, m.index).split('\n').length;
+        out.push({ name: m[1], file, line: lineNum });
+    }
+    return out;
+}
+function extractEventHandlers(content, file) {
+    const out = [];
+    // .emit('event', ...) and .on('event', ...)
+    const emitOn = /\.(emit|on)\s*\(\s*['"]([^'"]+)['"]/g;
+    let m;
+    while ((m = emitOn.exec(content)) !== null) {
+        const lineNum = content.slice(0, m.index).split('\n').length;
+        out.push({ event: m[2], kind: m[1], file, line: lineNum });
+    }
+    // addEventListener('event', ...)
+    const ael = /\.addEventListener\s*\(\s*['"]([^'"]+)['"]/g;
+    while ((m = ael.exec(content)) !== null) {
+        const lineNum = content.slice(0, m.index).split('\n').length;
+        out.push({ event: m[1], kind: 'addEventListener', file, line: lineNum });
+    }
+    return out;
+}
+/**
+ * Collapse cycles that belong to the same tangled cluster. A DFS over a densely
+ * circular module group (e.g. a zod-schema layer) emits many overlapping cycle
+ * paths through one strongly-connected component; reporting all of them is noise.
+ * Cycles sharing any file are unioned into one cluster and represented by their
+ * shortest path. Independent cycles (no shared file) are kept separately.
+ */
+export function dedupeCyclesBySCC(cycles) {
+    if (cycles.length <= 1)
+        return cycles;
+    const parent = cycles.map((_, i) => i);
+    const find = (x) => {
+        while (parent[x] !== x) {
+            parent[x] = parent[parent[x]];
+            x = parent[x];
+        }
+        return x;
+    };
+    const nodeToCycle = new Map();
+    cycles.forEach((cyc, i) => {
+        for (const node of cyc) {
+            const prev = nodeToCycle.get(node);
+            if (prev !== undefined)
+                parent[find(i)] = find(prev);
+            else
+                nodeToCycle.set(node, i);
+        }
+    });
+    const repByGroup = new Map();
+    cycles.forEach((cyc, i) => {
+        const g = find(i);
+        const cur = repByGroup.get(g);
+        if (!cur || cyc.length < cur.length)
+            repByGroup.set(g, cyc);
+    });
+    return [...repByGroup.values()];
+}
+function detectCycles(edges) {
+    const adj = new Map();
+    for (const e of edges) {
+        // `import type` edges are erased at runtime and cannot form a runtime cycle.
+        if (e.typeOnly)
+            continue;
+        if (!adj.has(e.from))
+            adj.set(e.from, new Set());
+        adj.get(e.from).add(e.to);
+    }
+    const cycles = [];
+    const seen = new Set();
+    function dfs(node, stack, onPath) {
+        if (onPath.has(node)) {
+            const idx = stack.indexOf(node);
+            cycles.push(stack.slice(idx).concat(node));
+            return;
+        }
+        if (seen.has(node))
+            return;
+        seen.add(node);
+        onPath.add(node);
+        stack.push(node);
+        for (const next of adj.get(node) ?? [])
+            dfs(next, stack, onPath);
+        stack.pop();
+        onPath.delete(node);
+    }
+    for (const start of adj.keys()) {
+        if (!seen.has(start))
+            dfs(start, [], new Set());
+    }
+    return dedupeCyclesBySCC(cycles);
+}
+function relativise(absPath, root) {
+    return path.relative(root, absPath).split(path.sep).join('/');
+}
+/** Next.js App Router reserved filenames (invoked by file-system routing, never imported). */
+const NEXT_APP_RESERVED = /(^|\/)app\/(?:[^/]+\/)*(?:page|layout|route|loading|error|not-found|template|default|global-error|head|sitemap|robots|manifest|opengraph-image|twitter-image|icon|apple-icon)\.[tj]sx?$/;
+/**
+ * True for files a framework/tool loads by convention rather than via an `import`,
+ * so they must not be reported as orphans.
+ */
+function isEntryPoint(relPath) {
+    return (/\.d\.[cm]?ts$/.test(relPath) || // ambient type declarations (next-env.d.ts, *-env.d.ts) — loaded via tsconfig, never imported
+        /(^|\/)(index|main|server|app|cli)\.[tj]sx?$/.test(relPath) ||
+        /^bin\//.test(relPath) ||
+        /^scripts\//.test(relPath) ||
+        /\.config\.[^/]+$/.test(relPath) ||
+        /(^|\/)\.[\w.-]*rc\.[cm]?[jt]s$/.test(relPath) || // dot-config: .eslintrc.js, .prettierrc.cjs, …
+        NEXT_APP_RESERVED.test(relPath) || // Next.js App Router
+        /(^|\/)pages\/.*\.[tj]sx?$/.test(relPath) || // Next.js Pages Router (every file is an entry)
+        /(^|\/)(middleware|instrumentation)\.[tj]sx?$/.test(relPath) || // Next.js middleware/instrumentation
+        /(^|\/)prisma\/seed\.[tj]sx?$/.test(relPath) || // Prisma seed (run via `prisma db seed`)
+        // Documentation sites, example/sample apps, playgrounds, benchmarks — illustrative
+        // or standalone code, not application source that other modules import.
+        /(^|\/)(docs?|site|website|examples?|samples?|demos?|playgrounds?|benchmarks?)\//.test(relPath) ||
+        /(^|\/)(generated|__generated__|\.generated)\//.test(relPath) || // codegen output (GraphQL/protobuf/…)
+        /(^|\/)playground\.[tj]sx?$/.test(relPath));
+}
+export class ConnectionMapperAgent extends BaseAgent {
+    agentId = 87;
+    agentName = 'Connection Mapper';
+    async preFlight() {
+        const root = this.config.projectRoot ?? process.cwd();
+        if (!fs.existsSync(root)) {
+            throw new Error(`projectRoot does not exist: ${root}`);
+        }
+    }
+    async execute() {
+        const findings = [];
+        const projectRoot = this.config.projectRoot ?? process.cwd();
+        const allFilePaths = walk(projectRoot);
+        const allFiles = new Set(allFilePaths);
+        const aliasConfig = loadAliasConfig(projectRoot);
+        const files = [];
+        const importEdges = [];
+        const routes = [];
+        const hooks = [];
+        const handlers = [];
+        const sourceFilesByName = new Set();
+        // Pass 1: read + cache each file, record its type-only exports so we can
+        // tell whether a plain `import { Foo }` actually pulls in a runtime value.
+        const contentByFile = new Map();
+        const typeOnlyExportsByPath = new Map();
+        for (const file of allFilePaths) {
+            let content;
+            try {
+                content = fs.readFileSync(file, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            contentByFile.set(file, content);
+            const isTest = isTestFile(file, projectRoot);
+            files.push({
+                path: relativise(file, projectRoot),
+                exports: extractExports(content),
+                isTest,
+                loc: content.split('\n').length,
+            });
+            if (!isTest)
+                sourceFilesByName.add(file);
+            typeOnlyExportsByPath.set(relativise(file, projectRoot), extractTypeOnlyExports(content));
+        }
+        // Pass 2: build edges (with runtime-accurate type-only detection), routes, etc.
+        for (const [file, content] of contentByFile) {
+            for (const imp of extractImports(content)) {
+                const resolved = resolveImport(file, imp.spec, allFiles, aliasConfig);
+                if (!resolved)
+                    continue;
+                const to = relativise(resolved, projectRoot);
+                // An edge is type-only when written as `import type`, or when every
+                // named symbol it imports is a type-only export of the target (a plain
+                // `import { SomeType }` that TS erases at runtime — common pre-
+                // verbatimModuleSyntax, and a frequent false cycle otherwise).
+                let typeOnly = imp.typeOnly;
+                if (!typeOnly && imp.symbols.length > 0 && !imp.symbols.includes('*') && !imp.symbols.includes('default')) {
+                    const targetTypes = typeOnlyExportsByPath.get(to);
+                    if (targetTypes && targetTypes.size > 0 && imp.symbols.every((s) => targetTypes.has(s))) {
+                        typeOnly = true;
+                    }
+                }
+                importEdges.push({ from: relativise(file, projectRoot), to, symbols: imp.symbols, typeOnly });
+            }
+            routes.push(...extractRoutes(content, file).map((r) => ({ ...r, file: relativise(r.file, projectRoot) })));
+            hooks.push(...extractHooks(content, file).map((h) => ({ ...h, file: relativise(h.file, projectRoot) })));
+            handlers.push(...extractEventHandlers(content, file).map((e) => ({ ...e, file: relativise(e.file, projectRoot) })));
+        }
+        // Orphans: source files that nothing imports. Excludes entry points that are
+        // loaded by a tool/runtime rather than imported by code: index/main/server/app/cli,
+        // bin/, scripts/, *.config.*, and framework-routed files (Next.js App/Pages
+        // Router reserved files, middleware) which the framework invokes by convention.
+        const importedTargets = new Set(importEdges.map((e) => e.to));
+        const orphans = files
+            .filter((f) => !f.isTest && !importedTargets.has(f.path) && !isEntryPoint(f.path))
+            .map((f) => f.path);
+        // Untested: source files without a sibling test file or matching __tests__/<file>.test.*
+        const testTargets = new Set();
+        for (const f of files) {
+            if (!f.isTest)
+                continue;
+            // foo.test.ts → assume tests foo.ts in either same dir or sibling source dir
+            const base = path.basename(f.path).replace(/\.(test|spec)\.[tj]sx?$/, '');
+            testTargets.add(base);
+        }
+        const untested = files
+            .filter((f) => !f.isTest)
+            .filter((f) => {
+            const base = path.basename(f.path).replace(/\.[tj]sx?$/, '');
+            return !testTargets.has(base);
+        })
+            .map((f) => f.path);
+        // Cycles among test files (e.g. ORM entity fixtures with bidirectional
+        // relations) aren't production bugs. Detect cycles over non-test files only;
+        // a real runtime cycle is source→source, so dropping edges that touch a test
+        // file can't hide one.
+        const testPaths = new Set(files.filter((f) => f.isTest).map((f) => f.path));
+        const cycles = detectCycles(importEdges.filter((e) => !testPaths.has(e.from) && !testPaths.has(e.to)));
+        const map = {
+            version: 1,
+            generatedAt: new Date().toISOString(),
+            projectRoot,
+            files,
+            imports: importEdges,
+            routes,
+            hooks,
+            handlers,
+            orphans,
+            cycles,
+            untested,
+            stats: {
+                totalFiles: files.length,
+                totalImports: importEdges.length,
+                totalRoutes: routes.length,
+                totalHooks: hooks.length,
+                totalHandlers: handlers.length,
+            },
+        };
+        // Persist the map for #88 (Localhost Walkthrough) to consume.
+        try {
+            const evidenceDir = path.join(this.runDir, 'evidence');
+            fs.mkdirSync(evidenceDir, { recursive: true });
+            const outPath = path.join(evidenceDir, 'connection-map.json');
+            fs.writeFileSync(outPath, JSON.stringify(map, null, 2), 'utf-8');
+            this.addEvidence({
+                type: 'report',
+                path: 'evidence/connection-map.json',
+                description: `Connection map: ${map.stats.totalFiles} files, ${map.stats.totalRoutes} routes, ${map.stats.totalHooks} hook calls`,
+            });
+        }
+        catch (err) {
+            findings.push({
+                id: `${this.agentId}-write-failed`,
+                type: 'infra-issue',
+                severity: 'high',
+                agentId: this.agentId,
+                module: 'connection-mapper',
+                description: `Failed to persist connection-map.json: ${err instanceof Error ? err.message : String(err)}`,
+            });
+            return findings;
+        }
+        // Cycles are blocking for alpha.
+        for (const cycle of cycles.slice(0, 20)) {
+            findings.push({
+                id: `${this.agentId}-cycle-${cycle.join('->')}`,
+                type: 'code-bug-logic',
+                severity: 'high',
+                agentId: this.agentId,
+                module: 'connection-mapper',
+                description: `Import cycle: ${cycle.join(' → ')}`,
+            });
+        }
+        // Orphans are advisory — could be entry points the heuristic missed.
+        for (const orphan of orphans.slice(0, 50)) {
+            findings.push({
+                id: `${this.agentId}-orphan-${orphan.replace(/[^\w]/g, '_')}`,
+                type: 'code-bug-cosmetic',
+                severity: 'low',
+                agentId: this.agentId,
+                module: 'connection-mapper',
+                description: `Orphaned file (no imports point at it): ${orphan}`,
+                file: orphan,
+            });
+        }
+        // Untested ratio — only surface if more than half of source files have no test.
+        const sourceCount = files.filter((f) => !f.isTest).length;
+        if (sourceCount > 0 && untested.length / sourceCount > 0.5) {
+            findings.push({
+                id: `${this.agentId}-low-test-coverage-ratio`,
+                type: 'test-bug',
+                severity: 'medium',
+                agentId: this.agentId,
+                module: 'connection-mapper',
+                description: `${untested.length}/${sourceCount} source files (${Math.round((untested.length / sourceCount) * 100)}%) have no associated test file`,
+            });
+        }
+        if (map.stats.totalRoutes === 0 && map.stats.totalHooks === 0) {
+            findings.push({
+                id: `${this.agentId}-empty-surface`,
+                type: 'infra-issue',
+                severity: 'low',
+                agentId: this.agentId,
+                module: 'connection-mapper',
+                description: 'No HTTP routes or React hooks discovered — Localhost Walkthrough (#88) will have nothing to exercise',
+            });
+        }
+        return findings;
+    }
+}
+//# sourceMappingURL=87-connection-mapper.js.map