headlesscode 1.0.2

package/src/codemap/extract.ts

@@ -0,0 +1,339 @@
+/**
+ * Edge extraction for the codemap — one mechanical extractor per language:
+ *
+ *   - TypeScript/JS: reuse `getImportGraph()` from src/codeintel/import-graph.ts
+ *     DIRECTLY (built on the TS Language Service, resolves tsconfig `paths`
+ *     aliases exactly as the compiler would) — issue #17 explicitly says to
+ *     wire it in, not reimplement it — plus `getCallGraph()` from
+ *     src/codeintel/call-graph.ts for Phase 2's cross-module call edges
+ *     (issue #18: real checker symbol resolution, never text matching).
+ *     Modules the TS program doesn't cover (e.g. standalone .mjs scripts
+ *     outside tsconfig's include) simply carry no import/call edges.
+ *   - Python: shell out to scripts/codemap-python-extract.py (stdlib `ast`
+ *     via a small Python subprocess — the project's established pattern for
+ *     Python tooling; the script is deterministic, no LLM). Call edges stay
+ *     Phase 2 for Python (per-framework pattern lists — FastAPI routes,
+ *     Celery tasks — are project-specific by design, see docs/codemap.md).
+ *   - C/C++: regex over `#include` directives (mechanical, good enough for
+ *     structure; symbol-level resolution is explicitly Phase 2 and likely
+ *     stays includes-only — a real call graph needs a compiler frontend).
+ *
+ * Edges whose target resolves OUTSIDE the workspace (node_modules, builtins,
+ * absolute paths) are NOT emitted as graph edges — they are summarized per
+ * module in `externalDeps` so the map stays a map of THIS project.
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { spawn } from "node:child_process"
+
+import { getCallGraph } from "../codeintel/call-graph.js"
+import { getImportGraph } from "../codeintel/import-graph.js"
+import { getCodeIntelCache } from "../codeintel/program.js"
+import type { CodemapEdge, ModuleEntry } from "./types.js"
+
+/** Absolute path of the Python AST extractor script (env-overridable for tests). */
+export function pythonExtractorScript(): string {
+	const override = process.env.HEADLESSCODE_CODEMAP_PYTHON_SCRIPT?.trim()
+	if (override) {
+		return override
+	}
+	return path.resolve(new URL("../../scripts/codemap-python-extract.py", import.meta.url).pathname)
+}
+
+/** C/C++ `#include` directive: `#include <foo.h>` or `#include "foo.h"`. */
+const INCLUDE_RE = /^\s*#\s*include\s*[<"]([^>"]+)[>"]/gm
+
+/** True when `rel` (workspace-relative posix) stays inside the workspace. */
+function isInsideWorkspace(rel: string): boolean {
+	return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel)
+}
+
+/** abs path -> workspace-relative posix path (undefined when outside). */
+function toWorkspaceRel(root: string, abs: string): string | undefined {
+	const rel = path.relative(root, abs).split(path.sep).join("/")
+	return isInsideWorkspace(rel) ? rel : undefined
+}
+
+/** Collect TS/JS import edges from the shared codeintel import graph. */
+function extractTypeScriptEdges(root: string, modules: ModuleEntry[]): { edges: CodemapEdge[]; externalDeps: Record<string, string[]> } {
+	const moduleSet = new Set(modules.map((m) => m.path))
+	const edges: CodemapEdge[] = []
+	const externalDeps: Record<string, string[]> = {}
+
+	// Skip program loading entirely on non-TS projects (a Python-only repo
+	// must not pay for an empty TS program).
+	if (!modules.some((m) => m.language === "typescript" || m.language === "javascript")) {
+		return { edges, externalDeps }
+	}
+
+	let intel
+	try {
+		intel = getCodeIntelCache(root).get()
+	} catch {
+		// A broken/absent tsconfig must not kill the whole codemap: the module
+		// inventory + other languages still work.
+		return { edges, externalDeps }
+	}
+	const graph = getImportGraph(intel)
+	const callGraph = getCallGraph(intel)
+
+	for (const module of modules) {
+		if (module.language !== "typescript" && module.language !== "javascript") {
+			continue
+		}
+		const abs = path.join(root, module.path)
+		const importEdges = graph.imports.get(abs)
+		if (importEdges === undefined || importEdges.length === 0) {
+			continue
+		}
+		const externals = new Set<string>()
+		for (const edge of importEdges) {
+			if (edge.resolved === undefined) {
+				externals.add(edge.specifier)
+				continue
+			}
+			const rel = toWorkspaceRel(root, edge.resolved)
+			if (rel === undefined || !moduleSet.has(rel)) {
+				externals.add(edge.specifier)
+				continue
+			}
+			edges.push({
+				from: module.path,
+				to: rel,
+				kind: "import",
+				specifier: edge.specifier,
+				isTypeOnly: edge.isTypeOnly === true,
+			})
+		}
+		if (externals.size > 0) {
+			externalDeps[module.path] = [...externals].sort()
+		}
+	}
+
+	// Phase 2 call edges (issue #18): cross-module function/method/constructor
+	// calls, resolved by the TS checker to the callee's defining file. One
+	// edge per from/to pair — callee names are joined into `specifier` so the
+	// module graph stays clean (no parallel lines in the visualizer).
+	const CALL_NAMES_CAP = 8
+	for (const module of modules) {
+		if (module.language !== "typescript" && module.language !== "javascript") {
+			continue
+		}
+		const abs = path.join(root, module.path)
+		const calls = callGraph.get(abs)
+		if (calls === undefined || calls.length === 0) {
+			continue
+		}
+		const byTarget = new Map<string, string[]>()
+		for (const call of calls) {
+			if (call.resolvedFile === undefined) {
+				continue
+			}
+			const rel = toWorkspaceRel(root, call.resolvedFile)
+			if (rel === undefined || rel === module.path || !moduleSet.has(rel)) {
+				continue
+			}
+			const names = byTarget.get(rel) ?? []
+			if (!names.includes(call.callee)) {
+				names.push(call.callee)
+			}
+			byTarget.set(rel, names)
+		}
+		for (const [target, names] of byTarget) {
+			names.sort()
+			const shown = names.length > CALL_NAMES_CAP ? [...names.slice(0, CALL_NAMES_CAP), `… (${names.length} callees)`] : names
+			edges.push({ from: module.path, to: target, kind: "call", specifier: shown.join(", ") })
+		}
+	}
+	return { edges, externalDeps }
+}
+
+/** Run the Python AST extractor and emit import edges. */
+async function extractPythonEdges(root: string, modules: ModuleEntry[]): Promise<{ edges: CodemapEdge[]; externalDeps: Record<string, string[]> }> {
+	const pyModules = modules.filter((m) => m.language === "python")
+	const edges: CodemapEdge[] = []
+	const externalDeps: Record<string, string[]> = {}
+	if (pyModules.length === 0) {
+		return { edges, externalDeps }
+	}
+	const moduleSet = new Set(modules.map((m) => m.path))
+
+	// Run the extractor with the payload on stdin (spawn — execFile has no
+	// `input` option, and the file list can be thousands of entries).
+	const stdout = await runPythonExtractor(root, pyModules.map((m) => m.path))
+	if (stdout === undefined) {
+		// python3 missing or the script failed — non-fatal: log and continue
+		// with the rest of the map (matches the project's non-fatal pattern
+		// for auxiliary subsystems). The inventory still lists the modules.
+		return { edges, externalDeps }
+	}
+
+	let parsed: { files?: Record<string, Array<{ specifier: string; kind: string; resolved: string | null }>> }
+	try {
+		parsed = JSON.parse(stdout)
+	} catch {
+		console.warn("[codemap] python extractor returned malformed output — skipped")
+		return { edges, externalDeps }
+	}
+	for (const [file, imports] of Object.entries(parsed.files ?? {})) {
+		const externals = new Set<string>()
+		for (const imp of imports) {
+			if (imp.resolved === null) {
+				externals.add(imp.specifier)
+				continue
+			}
+			if (!moduleSet.has(imp.resolved)) {
+				externals.add(imp.specifier)
+				continue
+			}
+			edges.push({ from: file, to: imp.resolved, kind: "import", specifier: imp.specifier })
+		}
+		if (externals.size > 0) {
+			externalDeps[file] = [...externals].sort()
+		}
+	}
+	return { edges, externalDeps }
+}
+
+/** Regex-based C/C++ `#include` edges (best-effort path resolution). */
+function extractCppEdges(root: string, modules: ModuleEntry[]): { edges: CodemapEdge[]; externalDeps: Record<string, string[]> } {
+	const cppModules = modules.filter((m) => m.language === "cpp" || m.language === "c")
+	const edges: CodemapEdge[] = []
+	const externalDeps: Record<string, string[]> = {}
+	if (cppModules.length === 0) {
+		return { edges, externalDeps }
+	}
+	const moduleSet = new Set(modules.map((m) => m.path))
+
+	const resolveInclude = (absFile: string, specifier: string, angle: boolean): string | undefined => {
+		const candidates: string[] = []
+		if (angle) {
+			// `<foo/bar.h>`: try workspace-root-relative first, then the
+			// including file's directory (some projects quote-import adjacent).
+			candidates.push(path.join(root, specifier.split("/").join(path.sep)))
+			candidates.push(path.join(path.dirname(absFile), specifier.split("/").join(path.sep)))
+		} else {
+			// `"foo/bar.h"`: file-dir-relative first, then root-relative.
+			candidates.push(path.join(path.dirname(absFile), specifier.split("/").join(path.sep)))
+			candidates.push(path.join(root, specifier.split("/").join(path.sep)))
+		}
+		for (const candidate of candidates) {
+			try {
+				if (fs.statSync(candidate).isFile()) {
+					return toWorkspaceRel(root, path.resolve(candidate))
+				}
+			} catch {
+				// keep trying
+			}
+		}
+		return undefined
+	}
+
+	for (const module of cppModules) {
+		const abs = path.join(root, module.path)
+		let source: string
+		try {
+			source = fs.readFileSync(abs, "utf-8")
+		} catch {
+			continue
+		}
+		const seen = new Set<string>()
+		const externals = new Set<string>()
+		INCLUDE_RE.lastIndex = 0
+		let match: RegExpExecArray | null
+		while ((match = INCLUDE_RE.exec(source)) !== null) {
+			const specifier = match[1]!
+			const angle = source[match.index + match[0].indexOf("<")] === "<"
+			const rel = resolveInclude(abs, specifier, angle)
+			const key = rel ?? `unresolved:${specifier}`
+			if (seen.has(key)) {
+				continue
+			}
+			seen.add(key)
+			if (rel === undefined || !moduleSet.has(rel)) {
+				externals.add(specifier)
+				continue
+			}
+			edges.push({ from: module.path, to: rel, kind: "include", specifier })
+		}
+		if (externals.size > 0) {
+			externalDeps[module.path] = [...externals].sort()
+		}
+	}
+	return { edges, externalDeps }
+}
+
+/**
+ * Run scripts/codemap-python-extract.py with the file list on stdin and
+ * return its stdout. undefined when python3 is missing or the script fails
+ * (callers treat that as "no python edges", never as a crash).
+ */
+function runPythonExtractor(root: string, files: string[]): Promise<string | undefined> {
+	return new Promise((resolve) => {
+		const child = spawn("python3", [pythonExtractorScript()], { cwd: root })
+		let stdout = ""
+		let stderr = ""
+		child.stdout.on("data", (d: Buffer) => {
+			stdout += d.toString("utf-8")
+			if (stdout.length > 64 * 1024 * 1024) {
+				child.kill()
+				resolve(undefined)
+			}
+		})
+		child.stderr.on("data", (d: Buffer) => {
+			stderr += d.toString("utf-8")
+		})
+		child.on("error", (err) => {
+			resolve(undefined)
+			void err
+		})
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve(stdout)
+			} else {
+				console.warn(`[codemap] python extractor exited ${code}: ${stderr.trim().slice(0, 400)}`)
+				resolve(undefined)
+			}
+		})
+		child.stdin.on("error", () => {
+			// stdin closed early (child died) — nothing to do
+		})
+		child.stdin.end(JSON.stringify({ root, files }))
+	})
+}
+
+/**
+ * Extract every import/include edge for the workspace's modules. Edges are
+ * deduplicated and sorted for determinism.
+ */
+export async function extractEdges(
+	root: string,
+	modules: ModuleEntry[],
+): Promise<{ edges: CodemapEdge[]; externalDeps: Record<string, string[]> }> {
+	const ts = extractTypeScriptEdges(root, modules)
+	const py = await extractPythonEdges(root, modules)
+	const cpp = extractCppEdges(root, modules)
+
+	const edges = [...ts.edges, ...py.edges, ...cpp.edges]
+	const byKey = new Map<string, CodemapEdge>()
+	for (const edge of edges) {
+		const key = `${edge.from}\u0000${edge.to}\u0000${edge.kind}\u0000${edge.specifier}`
+		if (!byKey.has(key)) {
+			byKey.set(key, edge)
+		}
+	}
+	const deduped = [...byKey.values()].sort((a, b) => (a.from === b.from ? a.to.localeCompare(b.to) : a.from.localeCompare(b.from)))
+
+	const externalDeps: Record<string, string[]> = {}
+	for (const dep of [ts.externalDeps, py.externalDeps, cpp.externalDeps]) {
+		for (const [file, specs] of Object.entries(dep)) {
+			const merged = new Set(externalDeps[file] ?? [])
+			for (const s of specs) {
+				merged.add(s)
+			}
+			externalDeps[file] = [...merged].sort()
+		}
+	}
+	return { edges: deduped, externalDeps }
+}

package/src/codemap/files.ts

@@ -0,0 +1,236 @@
+/**
+ * Module inventory for the codemap: git-aware file discovery + a
+ * naming-convention-based size/role heuristic (entrypoint, test, config,
+ * vendor/generated — NO semantics, per issue #17's scope).
+ *
+ * Discovery reuses src/codesearch/files.ts's `walkSourceFiles` — the
+ * git-aware walker (git ls-files with .gitignore semantics, generated-dir
+ * exclusions, a hard file cap) — and narrows its result to the source
+ * languages the codemap actually draws a graph over. Reusing it means the
+ * inventory and the codebase-search index can never disagree about what is a
+ * project file.
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+import { walkSourceFiles } from "../codesearch/files.js"
+import type { ModuleEntry, ModuleLanguage, ModuleRole } from "./types.js"
+
+/** Source/config extensions the codemap inventories + draws edges for. */
+const CODEMAP_EXTENSIONS = new Set([
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs",
+	".py",
+	".c",
+	".h",
+	".cpp",
+	".hpp",
+	".cc",
+	".hh",
+	".cxx",
+	".hxx",
+	// Config files get inventoried (and role-tagged) even though they carry
+	// no import edges — a codemap that omits package.json/tsconfig.json is a
+	// map of the code without the knobs that shape it.
+	".json",
+	".toml",
+	".yaml",
+	".yml",
+])
+
+const TS_EXTENSIONS = new Set([".ts", ".tsx", ".mts", ".cts"])
+const JS_EXTENSIONS = new Set([".js", ".jsx", ".mjs", ".cjs"])
+const PY_EXTENSIONS = new Set([".py"])
+const C_EXTENSIONS = new Set([".c", ".h"])
+const CPP_EXTENSIONS = new Set([".cpp", ".hpp", ".cc", ".hh", ".cxx", ".hxx"])
+
+/** Map an extension to the coarse language family. */
+export function languageForExtension(ext: string): ModuleLanguage {
+	const e = ext.toLowerCase()
+	if (TS_EXTENSIONS.has(e)) {
+		return "typescript"
+	}
+	if (JS_EXTENSIONS.has(e)) {
+		return "javascript"
+	}
+	if (PY_EXTENSIONS.has(e)) {
+		return "python"
+	}
+	if (CPP_EXTENSIONS.has(e)) {
+		return "cpp"
+	}
+	if (C_EXTENSIONS.has(e)) {
+		return "c"
+	}
+	return "other"
+}
+
+/** Test-file naming conventions across the three supported stacks. */
+function isTestFile(rel: string, language: ModuleLanguage): boolean {
+	const base = path.basename(rel)
+	if (language === "python") {
+		return /^test_.*\.py$/.test(base) || /_test\.py$/.test(base)
+	}
+	if (language === "typescript" || language === "javascript") {
+		return /\.(test|spec)\.[cm]?[jt]sx?$/.test(base)
+	}
+	if (language === "cpp" || language === "c") {
+		return /(^|[_-])test[._-]/.test(base) || /_test\.(c|h|cpp|hpp|cc|hh|cxx|hxx)$/.test(base)
+	}
+	return false
+}
+
+/**
+ * Entrypoint naming conventions: main/cli/__main__ files. `__main__.py`
+ * (the `python -m` entry) and main.* count anywhere; cli/index count only
+ * when shallow (root or one dir deep, e.g. src/cli.ts) — a deep
+ * src/codesearch/cli.ts is a subcommand module, not a repo entrypoint.
+ * `__init__.py` is deliberately NOT an entrypoint: it is a package marker
+ * (a large Python repo alone can have ~190 of them; tagging them all as
+ * entrypoints drowns the real ones).
+ */
+function isEntrypointFile(rel: string): boolean {
+	const base = path.basename(rel)
+	if (/^main(\.[^.]*)?$/.test(base) || /^__main__\./.test(base) || rel.startsWith("bin/")) {
+		return true
+	}
+	if (/^(cli|index)(\.[^.]*)?$/.test(base)) {
+		const depth = rel.split("/").length
+		return depth <= 2
+	}
+	return false
+}
+
+/** Config-file naming conventions: well-known manifests + config extensions. */
+function isConfigFile(rel: string, language: ModuleLanguage): boolean {
+	const base = path.basename(rel).toLowerCase()
+	if (language !== "other") {
+		return false
+	}
+	return (
+		/\.(json|toml|ya?ml)$/.test(rel) ||
+		/\.config\.[a-z0-9]+$/.test(base) ||
+		[
+			"package.json",
+			"tsconfig.json",
+			"jsconfig.json",
+			"pyproject.toml",
+			"setup.cfg",
+			"requirements.txt",
+			"cargo.toml",
+			"go.mod",
+			"cmakelists.txt",
+			"makefile",
+			"dockerfile",
+			"compose.yaml",
+			"compose.yml",
+			".eslintrc",
+			".prettierrc",
+			".gitlab-ci.yml",
+			".github/workflows/",
+		].some((name) => rel.toLowerCase().includes(name))
+	)
+}
+
+/** Vendor/generated directory-name heuristics (path-segment based). */
+function isVendorOrGenerated(rel: string): { vendor: boolean; generated: boolean } {
+	const segments = rel.split("/")
+	let vendor = false
+	let generated = false
+	for (const segment of segments) {
+		if (["vendor", "third_party", "third-party", "node_modules", ".venv", "venv", "site-packages"].includes(segment)) {
+			vendor = true
+		}
+		if (["generated", "gen", "dist", "build", "out", "target"].includes(segment)) {
+			generated = true
+		}
+	}
+	// Type declaration files are compiler outputs in spirit (they describe
+	// other code); they stay in the graph but are tagged generated.
+	if (/\.d\.[cm]?ts$/.test(rel)) {
+		generated = true
+	}
+	return { vendor, generated }
+}
+
+/** The naming-convention role for a module (source by default). */
+export function classifyRole(rel: string, language: ModuleLanguage): ModuleRole {
+	const { vendor, generated } = isVendorOrGenerated(rel)
+	if (vendor) {
+		return "vendor"
+	}
+	if (generated) {
+		return "generated"
+	}
+	if (isTestFile(rel, language)) {
+		return "test"
+	}
+	if (isEntrypointFile(rel)) {
+		return "entrypoint"
+	}
+	if (isConfigFile(rel, language)) {
+		return "config"
+	}
+	return "source"
+}
+
+/** Read a file's byte size + line count (best-effort; 0s on read failure). */
+export function statLines(abs: string): { sizeBytes: number; lineCount: number } {
+	try {
+		const st = fs.statSync(abs)
+		const raw = fs.readFileSync(abs, "utf-8")
+		let lines = 0
+		for (let i = 0; i < raw.length; i++) {
+			if (raw.charCodeAt(i) === 10) {
+				lines++
+			}
+		}
+		return { sizeBytes: st.size, lineCount: raw.length === 0 ? 0 : lines + 1 }
+	} catch {
+		return { sizeBytes: 0, lineCount: 0 }
+	}
+}
+
+/**
+ * Build the module inventory for a workspace: every supported source/config
+ * file with its role, language, size, line count and content hash. The hash
+ * is the fingerprint key the lock file uses for change detection.
+ */
+export async function inventoryModules(
+	workspaceRoot: string,
+	contentHash: (content: string) => string,
+): Promise<ModuleEntry[]> {
+	const files = await walkSourceFiles(workspaceRoot)
+	const modules: ModuleEntry[] = []
+	for (const file of files) {
+		const ext = path.extname(file.rel).toLowerCase()
+		if (!CODEMAP_EXTENSIONS.has(ext)) {
+			continue
+		}
+		const language = languageForExtension(ext)
+		const { sizeBytes, lineCount } = statLines(file.abs)
+		let content: string
+		try {
+			content = fs.readFileSync(file.abs, "utf-8")
+		} catch {
+			continue
+		}
+		modules.push({
+			path: file.rel,
+			language,
+			role: classifyRole(file.rel, language),
+			sizeBytes,
+			lineCount,
+			hash: contentHash(content),
+		})
+	}
+	modules.sort((a, b) => a.path.localeCompare(b.path))
+	return modules
+}

package/src/codemap/fingerprint.ts

@@ -0,0 +1,65 @@
+/**
+ * Content hashing + lock comparison for the codemap's change detection.
+ *
+ * The lock file (codemap.lock) records a sha256 per module path. A rebuild
+ * recomputes the current hashes and compares them with the stored ones: an
+ * identical key-set AND identical hash per key means "nothing changed" and
+ * the build writes nothing. Any diff — a changed file, a new file, a deleted
+ * file — means a (full) regeneration. Full regen is deliberate for v1: the
+ * extraction is fast and cheap, so incremental per-module regeneration would
+ * add complexity with no measurable win (issue #17 explicitly allows it).
+ */
+
+import * as crypto from "node:crypto"
+
+import type { Codemap, CodemapLock } from "./types.js"
+
+/** sha256 hex of a string (the same digest the codesearch index uses). */
+export function contentHash(content: string): string {
+	return crypto.createHash("sha256").update(content, "utf-8").digest("hex")
+}
+
+/** Current fingerprint map for the given modules (path -> content hash). */
+export function fingerprintMap(modules: ReadonlyArray<{ path: string; hash: string }>): Record<string, string> {
+	const out: Record<string, string> = {}
+	for (const m of modules) {
+		out[m.path] = m.hash
+	}
+	return out
+}
+
+/** True when the current modules exactly match the stored lock (no writes needed). */
+export function lockMatches(lock: CodemapLock | undefined, modules: ReadonlyArray<{ path: string; hash: string }>): boolean {
+	if (lock === undefined) {
+		return false
+	}
+	const current = fingerprintMap(modules)
+	const stored = lock.fingerprints
+	const currentKeys = Object.keys(current)
+	if (currentKeys.length !== Object.keys(stored).length) {
+		return false
+	}
+	for (const key of currentKeys) {
+		if (stored[key] !== current[key]) {
+			return false
+		}
+	}
+	return true
+}
+
+/**
+ * Deterministic content fingerprint for the whole codemap: sha256 over the
+ * sorted module paths+hashes and the sorted edges. Stable across
+ * regenerations of an unchanged repo.
+ */
+export function codemapFingerprint(codemap: Pick<Codemap, "project" | "modules" | "edges" | "externalDeps">): string {
+	const h = crypto.createHash("sha256")
+	const moduleLines = codemap.modules.map((m) => `${m.path}\t${m.hash}`).join("\n")
+	h.update(`modules:\n${moduleLines}\n`)
+	const edgeLines = codemap.edges
+		.map((e) => `${e.from}\t${e.to}\t${e.kind}\t${e.specifier}`)
+		.sort()
+		.join("\n")
+	h.update(`edges:\n${edgeLines}\n`)
+	return h.digest("hex")
+}

package/src/codemap/flows.ts

@@ -0,0 +1,62 @@
+/**
+ * Entrypoint-rooted end-to-end flows for the codemap (Phase 2, issue #18):
+ * for each entrypoint module, the sorted list of every module reachable from
+ * it along directed import+call edges.
+ *
+ * Phase 2 explicitly considered RANKING flows by "importance" (entrypoint
+ * fan-out, path length to a sink, …) and deliberately punted: every sketch
+ * either needed per-framework semantics (FastAPI routes, Celery tasks,
+ * pub/sub topics) that can't be derived without the project-specific pattern
+ * lists, or reduced to "sort by size of the reachable set" in a trench coat.
+ * The useful, honest half is surfacing the flows themselves — a human or a
+ * worker can filter them, while a wrong ranking is worse than no ranking
+ * (the original prompt's "Mark any relationship without source evidence as
+ * unknown. Do not guess."). Deterministic: same repo, same flows.
+ */
+
+import type { CodemapEdge, ModuleEntry } from "./types.js"
+
+/**
+ * Compute the entrypoint-rooted flow map for a set of modules + edges.
+ *
+ * BFS along edge direction (imports, includes and calls all count — a call
+ * is as much a "flow" as an import). Result keys are the sorted entrypoint
+ * paths; values are the sorted reachable module paths, excluding the
+ * entrypoint itself. A pure function of modules + edges, so it is derived
+ * (not fingerprinted) by the build.
+ */
+export function computeEntrypointFlows(
+	modules: ReadonlyArray<Pick<ModuleEntry, "path" | "role">>,
+	edges: ReadonlyArray<Pick<CodemapEdge, "from" | "to">>,
+): Record<string, string[]> {
+	const byPath = new Set(modules.map((m) => m.path))
+	const adjacency = new Map<string, string[]>()
+	for (const edge of edges) {
+		if (!byPath.has(edge.from) || !byPath.has(edge.to)) {
+			continue
+		}
+		const targets = adjacency.get(edge.from) ?? []
+		if (!targets.includes(edge.to)) {
+			targets.push(edge.to)
+		}
+		adjacency.set(edge.from, targets)
+	}
+
+	const flows: Record<string, string[]> = {}
+	for (const entrypoint of modules.filter((m) => m.role === "entrypoint").map((m) => m.path).sort()) {
+		const reachable = new Set<string>()
+		const queue = [...(adjacency.get(entrypoint) ?? [])]
+		while (queue.length > 0) {
+			const current = queue.shift()!
+			if (reachable.has(current)) {
+				continue
+			}
+			reachable.add(current)
+			for (const next of adjacency.get(current) ?? []) {
+				queue.push(next)
+			}
+		}
+		flows[entrypoint] = [...reachable].sort()
+	}
+	return flows
+}