headlesscode 1.0.2

package/src/codeintel/call-graph.ts

@@ -0,0 +1,78 @@
+/**
+ * CALL-edge extraction for the codemap's Phase 2 (issue #18): which function
+ * in module A calls which function in module B — resolved with the real TS
+ * checker, not text matching.
+ *
+ * For every CallExpression/NewExpression in the program we ask the type
+ * checker for the RESOLVED signature and take its `declaration` — the actual
+ * function/method/constructor the call binds to. The declaration's source
+ * file is the edge's target. This is the same resolution the language
+ * service uses for go-to-definition, so overloads, re-exports, aliased
+ * imports and method calls all land on the real implementation (the 
+ * deterministic answer the issue's "no LLM" requirement demands — no
+ * name-matching heuristics anywhere).
+ *
+ * Call targets that resolve OUTSIDE the scanned workspace (lib.d.ts,
+ * node_modules) or don't resolve at all (calls on `any`, dynamic JS calls)
+ * are carried with `resolvedFile: undefined` — the consumer (codemap's
+ * extractor) drops them, because external call targets are already visible
+ * through the module's import edges + externalDeps.
+ */
+
+import * as ts from "typescript"
+
+import type { CodeIntel } from "./program.js"
+
+/** One call site in a source file, resolved to its real callee declaration. */
+export interface CallEdge {
+	/** Human-readable callee expression as written, e.g. "greet", "obj.method", "Foo". */
+	callee: string
+	/** Absolute path of the file declaring the callee (undefined when unresolvable). */
+	resolvedFile: string | undefined
+}
+
+/** Per absolute file path: every call site in that file. */
+export type CallGraph = Map<string, CallEdge[]>
+
+/**
+ * Build (or return the cached) call graph for the program. A pure function
+ * of the program's source files, so it is computed once and reused until the
+ * program itself is rebuilt — same caching idiom as the import graph.
+ *
+ * Walking every program source file (not just `projectFiles`) matters: a
+ * module can be part of the program because a project file imports it, and
+ * calls FROM it must still resolve.
+ */
+export function getCallGraph(intel: CodeIntel): CallGraph {
+	const cached = (intel as { __callGraph?: CallGraph }).__callGraph
+	if (cached !== undefined) {
+		return cached
+	}
+
+	const checker = intel.program.getTypeChecker()
+	const graph: CallGraph = new Map()
+
+	for (const sourceFile of intel.program.getSourceFiles()) {
+		const edges: CallEdge[] = []
+
+		const collect = (node: ts.Node): void => {
+			if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+				const signature = checker.getResolvedSignature(node)
+				const declaration = signature?.declaration
+				edges.push({
+					callee: node.expression.getText(sourceFile),
+					resolvedFile: declaration?.getSourceFile().fileName,
+				})
+			}
+			ts.forEachChild(node, collect)
+		}
+		collect(sourceFile)
+
+		if (edges.length > 0) {
+			graph.set(sourceFile.fileName, edges)
+		}
+	}
+
+	;(intel as { __callGraph?: CallGraph }).__callGraph = graph
+	return graph
+}

package/src/codeintel/find-references.ts

@@ -0,0 +1,123 @@
+/**
+ * `find_references` analysis: every real usage site of the symbol at
+ * (file, line[, character | symbol]) via the language service's real
+ * reference finding — `getReferencesAtPosition` — never grep.
+ *
+ * Output is compact `file:line` entries plus a short snippet of the line
+ * itself, so the model doesn't have to read each file just to see context.
+ * Results are capped (see MAX_REFERENCES): a symbol with a huge number of
+ * usages (e.g. a common utility) must not dump hundreds of lines back into
+ * the model's context, which would defeat the point of the tool.
+ */
+
+import * as ts from "typescript"
+
+import { scriptKindFromFileName, type CodeIntel } from "./program.js"
+import { identifierAtPosition } from "./position.js"
+
+export interface ReferenceSite {
+	fileName: string
+	line: number
+	character: number
+	/**
+	 * Absolute character offset of the identifier's start within `fileName`
+	 * (the language service's raw `textSpan.start`). The tools only need
+	 * line/column for display, but `rename_symbol` needs the exact offset to
+	 * edit the file — computed here once instead of re-derived per consumer.
+	 */
+	start: number
+	/** Write access (assignment / declaration) vs read access. */
+	isWriteAccess: boolean
+	snippet: string
+}
+
+/** Hard cap on reference entries per call (keeps model context bounded). */
+export const MAX_REFERENCES = 50
+
+/** Read a line from the program's snapshot or straight from disk. */
+function snippetFor(intel: CodeIntel, fileName: string, line1based: number): string {
+	const sourceFile = intel.program.getSourceFile(fileName)
+	const text = sourceFile?.text ?? (ts.sys.readFile(fileName) ?? "")
+	const line = text.split(/\r?\n/)[line1based - 1]
+	if (line === undefined) {
+		return ""
+	}
+	const trimmed = line.trim()
+	return trimmed.length > 120 ? `${trimmed.slice(0, 120)}…` : trimmed
+}
+
+/** Parse a file standalone (for files created after the program was loaded). */
+function readStandalone(file: string): ts.SourceFile | undefined {
+	const text = ts.sys.readFile(file)
+	if (text === undefined) {
+		return undefined
+	}
+	return ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKindFromFileName(file))
+}
+
+/**
+ * Find all references to the symbol at `line` (1-based) in `file`.
+ * `character` (1-based column) and/or `symbol` (name) disambiguate when the
+ * line holds multiple identifiers. The result includes the declaration site
+ * itself (the language service counts it as a "reference").
+ */
+export function findReferences(
+	intel: CodeIntel,
+	file: string,
+	line: number,
+	character: number | undefined,
+	symbol: string | undefined,
+): ReferenceSite[] {
+	const sourceFile = intel.program.getSourceFile(file) ?? readStandalone(file)
+	if (sourceFile === undefined) {
+		throw new Error(`file is not part of the loaded TypeScript program: ${file}`)
+	}
+	const identifier = identifierAtPosition(sourceFile, line, character, symbol)
+	if (identifier === undefined) {
+		return []
+	}
+
+	intel.includeExtraFile(file)
+	const references = intel.languageService.getReferencesAtPosition(file, identifier.getStart(sourceFile)) ?? []
+
+	const seen = new Set<string>()
+	const sites: ReferenceSite[] = []
+	for (const ref of references) {
+		const key = `${ref.fileName}:${ref.textSpan.start}`
+		if (seen.has(key)) {
+			continue
+		}
+		seen.add(key)
+		// Line/column must be computed against the REFERENCE's own file, which
+		// may differ from the file we started from (references span the program).
+		const refSourceFile = intel.program.getSourceFile(ref.fileName)
+		if (refSourceFile === undefined) {
+			continue
+		}
+		const lineAndChar = ts.getLineAndCharacterOfPosition(refSourceFile, ref.textSpan.start)
+		sites.push({
+			fileName: ref.fileName,
+			line: lineAndChar.line + 1,
+			character: lineAndChar.character + 1,
+			start: ref.textSpan.start,
+			isWriteAccess: ref.isWriteAccess,
+			snippet: snippetFor(intel, ref.fileName, lineAndChar.line + 1),
+		})
+	}
+	sites.sort((a, b) => a.fileName.localeCompare(b.fileName) || a.line - b.line)
+	return sites
+}
+
+/** Render reference sites as compact `file:line — snippet` lines, capped. */
+export function formatReferences(rel: (p: string) => string, sites: ReferenceSite[]): string {
+	if (sites.length === 0) {
+		return "No references found for that symbol."
+	}
+	const shown = sites.slice(0, MAX_REFERENCES)
+	const lines = shown.map((r) => `${rel(r.fileName)}:${r.line}${r.isWriteAccess ? " (write)" : ""} — ${r.snippet}`)
+	const overflow = sites.length - shown.length
+	if (overflow > 0) {
+		lines.push(`…${overflow} more reference(s) not shown — narrow your search to a more specific symbol`)
+	}
+	return lines.join("\n")
+}

package/src/codeintel/go-to-definition.ts

@@ -0,0 +1,193 @@
+/**
+ * `go_to_definition` analysis: resolve a symbol at (file, line[, character |
+ * symbol]) to its real definition site(s) via the type checker's actual
+ * symbol resolution — the LanguageService's `getDefinitionAtPosition` — not a
+ * text search.
+ *
+ * Handles the three hard cases the spec calls out:
+ *   - definition in a `.d.ts` / vendored / `node_modules` location: returned
+ *     as the real location, never refused for being outside `src/`
+ *   - symbol with no resolvable definition (ambient / `any`-typed /
+ *     genuinely unresolvable): a clear "could not resolve" result, not a crash
+ *   - multiple candidate definitions (e.g. an overloaded function): ALL of
+ *     them are returned, never one silently picked
+ */
+
+import * as path from "node:path"
+import * as ts from "typescript"
+
+import { scriptKindFromFileName, type CodeIntel } from "./program.js"
+import { identifierAtPosition } from "./position.js"
+
+export interface DefinitionSite {
+	/** Absolute path of the defining file. */
+	fileName: string
+	/** 1-based line + 1-based column of the definition's name. */
+	line: number
+	character: number
+	kind: string
+	name: string
+	/** Container (e.g. class/namespace) the definition lives in, if any. */
+	containerName?: string
+	/** The full text of the definition's line, for context without a read_file. */
+	snippet: string
+}
+
+/** Read a definition's line text from the program or straight from disk. */
+function snippetFor(intel: CodeIntel, fileName: string, line1based: number): string {
+	const sourceFile = intel.program.getSourceFile(fileName)
+	const text = sourceFile?.text ?? (ts.sys.readFile(fileName) ?? "")
+	const lines = text.split(/\r?\n/)
+	const line = lines[line1based - 1]
+	if (line === undefined) {
+		return ""
+	}
+	const trimmed = line.trim()
+	return trimmed.length > 120 ? `${trimmed.slice(0, 120)}…` : trimmed
+}
+
+/**
+ * Resolve the definition(s) of the symbol at `line` (1-based) in `file`.
+ * `character` (1-based column) and/or `symbol` (name) disambiguate when the
+ * line holds multiple identifiers.
+ */
+export function findDefinition(
+	intel: CodeIntel,
+	file: string,
+	line: number,
+	character: number | undefined,
+	symbol: string | undefined,
+): DefinitionSite[] {
+	const sourceFile = intel.program.getSourceFile(file) ?? readStandalone(file)
+	if (sourceFile === undefined) {
+		throw new Error(`file is not part of the loaded TypeScript program: ${file}`)
+	}
+	const identifier = identifierAtPosition(sourceFile, line, character, symbol)
+	if (identifier === undefined) {
+		return []
+	}
+
+	intel.includeExtraFile(file)
+	const definitions = intel.languageService.getDefinitionAtPosition(file, identifier.getStart(sourceFile)) ?? []
+
+	// The language service returns ONE definition per position — but an
+	// overloaded function is one symbol with several declarations, and the spec
+	// says return ALL candidates, never one silently picked. Expand through the
+	// type checker's symbol: resolve alias imports to their target, then take
+	// every declaration the symbol has.
+	const checker = intel.program.getTypeChecker()
+	let resolvedSymbol = checker.getSymbolAtLocation(identifier)
+	if (resolvedSymbol !== undefined && (resolvedSymbol.flags & ts.SymbolFlags.Alias) !== 0) {
+		resolvedSymbol = checker.getAliasedSymbol(resolvedSymbol)
+	}
+	const symbolDeclarations = (resolvedSymbol?.declarations ?? []).map(declarationSite)
+
+	// Dedup by file+line: the language service's answer and the checker's
+	// declaration list usually overlap (non-overloaded symbols appear once).
+	const seen = new Set<string>()
+	const sites: DefinitionSite[] = []
+	const push = (site: DefinitionSite): void => {
+		const key = `${site.fileName}:${site.line}:${site.character}`
+		if (seen.has(key)) {
+			return
+		}
+		seen.add(key)
+		sites.push(site)
+	}
+
+	for (const def of definitions) {
+		// Line/column must be computed against the DEFINITION's own file
+		// (it may not even be in the program — e.g. a d.ts pulled from
+		// node_modules is, but a definition in an untyped extra file is not).
+		const defSourceFile = intel.program.getSourceFile(def.fileName) ?? readStandalone(def.fileName)
+		if (defSourceFile === undefined) {
+			continue
+		}
+		const lineAndChar = ts.getLineAndCharacterOfPosition(defSourceFile, def.textSpan.start)
+		push({
+			fileName: def.fileName,
+			line: lineAndChar.line + 1,
+			character: lineAndChar.character + 1,
+			kind: def.kind,
+			name: def.name,
+			containerName: def.containerName,
+			snippet: snippetFor(intel, def.fileName, lineAndChar.line + 1),
+		})
+	}
+	for (const site of symbolDeclarations) {
+		push(site)
+	}
+	return sites.sort((a, b) => a.fileName.localeCompare(b.fileName) || a.line - b.line)
+}
+
+/** Short kind label for a checker symbol declaration (overload expansion). */
+function kindOfDeclaration(decl: ts.Declaration): string {
+	if (ts.isFunctionDeclaration(decl)) return "function"
+	if (ts.isClassDeclaration(decl)) return "class"
+	if (ts.isInterfaceDeclaration(decl)) return "interface"
+	if (ts.isTypeAliasDeclaration(decl)) return "type"
+	if (ts.isEnumDeclaration(decl)) return "enum"
+	if (ts.isModuleDeclaration(decl)) return "namespace"
+	if (ts.isMethodDeclaration(decl) || ts.isMethodSignature(decl)) return "method"
+	if (ts.isPropertyDeclaration(decl) || ts.isPropertySignature(decl)) return "property"
+	if (ts.isGetAccessorDeclaration(decl)) return "getter"
+	if (ts.isSetAccessorDeclaration(decl)) return "setter"
+	if (ts.isVariableDeclaration(decl)) {
+		const list = decl.parent
+		if (ts.isVariableDeclarationList(list)) {
+			if (list.flags & ts.NodeFlags.Const) return "const"
+			if (list.flags & ts.NodeFlags.Let) return "let"
+			return "var"
+		}
+		return "variable"
+	}
+	return "declaration"
+}
+
+/** A definition site from a raw declaration node (name anchor, own file). */
+function declarationSite(decl: ts.Declaration): DefinitionSite {
+	const sourceFile = decl.getSourceFile()
+	const nameNode = (decl as { name?: ts.Node }).name
+	const anchor = nameNode ?? decl
+	const lineAndChar = ts.getLineAndCharacterOfPosition(sourceFile, anchor.getStart(sourceFile))
+	const lineText = sourceFile.text.split(/\r?\n/)[lineAndChar.line] ?? ""
+	const trimmed = lineText.trim()
+	return {
+		fileName: sourceFile.fileName,
+		line: lineAndChar.line + 1,
+		character: lineAndChar.character + 1,
+		kind: kindOfDeclaration(decl),
+		name: nameNode !== undefined && ts.isIdentifier(nameNode) ? nameNode.text : "",
+		snippet: trimmed.length > 120 ? `${trimmed.slice(0, 120)}…` : trimmed,
+	}
+}
+
+/** Parse a file standalone (for files created after the program was loaded). */
+function readStandalone(file: string): ts.SourceFile | undefined {
+	const text = ts.sys.readFile(file)
+	if (text === undefined) {
+		return undefined
+	}
+	return ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKindFromFileName(file))
+}
+
+/** Render definition sites as compact, dedup-friendly lines. */
+export function formatDefinitions(rel: (p: string) => string, defs: DefinitionSite[]): string {
+	if (defs.length === 0) {
+		return "Could not resolve a definition for that symbol (it may be ambient, any-typed, or otherwise unresolvable by the type checker)."
+	}
+	return defs
+		.map(
+			(d) =>
+				`${rel(d.fileName)}:${d.line}:${d.character} ${d.kind} ${d.name}${d.containerName ? ` (in ${d.containerName})` : ""} — ${d.snippet}`,
+		)
+		.join("\n")
+}
+
+/** Relative-path formatter used by the handlers (stable ordering across tools). */
+export function makeRelativizer(workspaceRoot: string): (p: string) => string {
+	return (p) => {
+		const rel = path.relative(workspaceRoot, p)
+		return rel === "" || rel.startsWith("..") ? p : rel.split(path.sep).join("/")
+	}
+}

package/src/codeintel/handlers.ts

@@ -0,0 +1,190 @@
+/**
+ * Tool handlers for the four code-intelligence tools (`outline`,
+ * `go_to_definition`, `find_references`, `import_graph`).
+ *
+ * Thin layer over the shared analysis module (src/codeintel/program.ts +
+ * the per-tool analyzers): argument parsing, path safety, the "not supported
+ * for this file type" honesty rule, and result formatting. All four share ONE
+ * cached `ts.Program` per workspace root — see program.ts for the caching +
+ * mtime-invalidation contract.
+ *
+ * Non-TS/JS files NEVER produce a guessed answer: they get a clear
+ * "[Error] ... not a supported file type" result. Missing files and files
+ * that escaped the workspace root error the same way the rest of the
+ * executor does.
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+import * as ts from "typescript"
+
+import type { ToolContext, ToolResult } from "../engine/types.js"
+import { resolveWithinWorkspace } from "../tools/executor.js"
+import { getCodeIntelCache, isSupportedSource, scriptKindFromFileName } from "./program.js"
+import { formatOutline, outlineSourceFile } from "./outline.js"
+import { findDefinition, formatDefinitions, makeRelativizer } from "./go-to-definition.js"
+import { findReferences, formatReferences } from "./find-references.js"
+import { formatImportGraph, getImportGraph } from "./import-graph.js"
+import { formatRenameResult, renameSymbol } from "./rename-symbol.js"
+
+function ok(content: string): ToolResult {
+	return { content, isError: false }
+}
+
+function err(content: string): ToolResult {
+	return { content: `[Error] ${content}`, isError: true }
+}
+
+function requireStringArg(args: Record<string, unknown>, key: string, tool: string): string {
+	const v = args[key]
+	if (typeof v !== "string" || v.trim() === "") {
+		throw new Error(`${tool}: missing or invalid string argument '${key}' (got ${JSON.stringify(v)})`)
+	}
+	return v
+}
+
+function optionalStringArg(args: Record<string, unknown>, key: string): string | undefined {
+	const v = args[key]
+	if (v === undefined || v === null) {
+		return undefined
+	}
+	if (typeof v !== "string") {
+		return undefined
+	}
+	return v.trim() === "" ? undefined : v
+}
+
+/** Parse a 1-based line (required) or column (optional); invalid → throw/undefined. */
+function lineArg(args: Record<string, unknown>, tool: string): number {
+	const v = args["line"]
+	const n = typeof v === "number" ? v : typeof v === "string" ? Number(v) : NaN
+	if (!Number.isInteger(n) || n < 1) {
+		throw new Error(`${tool}: invalid line '${JSON.stringify(v)}' — must be a 1-based line number`)
+	}
+	return n
+}
+
+function optionalCharacterArg(args: Record<string, unknown>): number | undefined {
+	const v = args["character"]
+	const n = typeof v === "number" ? v : typeof v === "string" ? Number(v) : NaN
+	if (Number.isInteger(n) && n >= 1) {
+		return n
+	}
+	return undefined
+}
+
+/** Path-safety-checked absolute target + existence/type/support validation. */
+function resolveTarget(ctx: ToolContext, tool: string, p: string): string {
+	const target = resolveWithinWorkspace(ctx.workspaceRoot, p)
+	const rel = path.relative(ctx.workspaceRoot, target).split(path.sep).join("/") || path.basename(target)
+
+	let stat: fs.Stats
+	try {
+		stat = fs.statSync(target)
+	} catch {
+		throw new Error(`${tool}: cannot stat '${rel}' — file does not exist`)
+	}
+	if (!stat.isFile()) {
+		throw new Error(`${tool}: '${rel}' is not a file`)
+	}
+	if (!isSupportedSource(target)) {
+		throw new Error(
+			`${tool}: '${rel}' is not a supported file type — code-intelligence tools work on TypeScript/JavaScript source files only (.ts/.tsx/.mts/.cts/.js/.jsx)`,
+		)
+	}
+	return target
+}
+
+/** The cached program intel for a workspace (load-or-reuse). */
+function intelFor(ctx: ToolContext) {
+	return getCodeIntelCache(ctx.workspaceRoot).get()
+}
+
+// ─── outline ─────────────────────────────────────────────────────────────────
+
+export function outlineHandler(args: Record<string, unknown>, ctx: ToolContext): ToolResult {
+	const tool = "outline"
+	const filePath = requireStringArg(args, "path", tool)
+	const target = resolveTarget(ctx, tool, filePath)
+	const rel = path.relative(ctx.workspaceRoot, target).split(path.sep).join("/") || path.basename(target)
+
+	const intel = intelFor(ctx)
+	const sourceFile = intel.program.getSourceFile(target) ?? readStandalone(target)
+	if (sourceFile === undefined) {
+		return err(`${tool}: cannot parse '${rel}' as TypeScript`)
+	}
+	const entries = outlineSourceFile(sourceFile)
+	return ok(`Outline of ${rel}:\n${formatOutline(entries)}`)
+}
+
+// ─── go_to_definition ────────────────────────────────────────────────────────
+
+export function goToDefinitionHandler(args: Record<string, unknown>, ctx: ToolContext): ToolResult {
+	const tool = "go_to_definition"
+	const filePath = requireStringArg(args, "path", tool)
+	const target = resolveTarget(ctx, tool, filePath)
+	const line = lineArg(args, tool)
+	const character = optionalCharacterArg(args)
+	const symbol = optionalStringArg(args, "symbol")
+
+	const intel = intelFor(ctx)
+	const defs = findDefinition(intel, target, line, character, symbol)
+	const rel = makeRelativizer(ctx.workspaceRoot)
+	return ok(formatDefinitions(rel, defs))
+}
+
+// ─── find_references ─────────────────────────────────────────────────────────
+
+export function findReferencesHandler(args: Record<string, unknown>, ctx: ToolContext): ToolResult {
+	const tool = "find_references"
+	const filePath = requireStringArg(args, "path", tool)
+	const target = resolveTarget(ctx, tool, filePath)
+	const line = lineArg(args, tool)
+	const character = optionalCharacterArg(args)
+	const symbol = optionalStringArg(args, "symbol")
+
+	const intel = intelFor(ctx)
+	const sites = findReferences(intel, target, line, character, symbol)
+	const rel = makeRelativizer(ctx.workspaceRoot)
+	return ok(formatReferences(rel, sites))
+}
+
+// ─── rename_symbol ───────────────────────────────────────────────────────────
+
+export function renameSymbolHandler(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult> {
+	const tool = "rename_symbol"
+	const filePath = requireStringArg(args, "path", tool)
+	const target = resolveTarget(ctx, tool, filePath)
+	const line = lineArg(args, tool)
+	const character = optionalCharacterArg(args)
+	const symbol = optionalStringArg(args, "symbol")
+	const newName = requireStringArg(args, "new_name", tool)
+
+	const intel = intelFor(ctx)
+	// Throws (wrapped by ToolExecutor.execute as `Tool 'rename_symbol' failed:
+	// …`) on any validation failure or a mid-write failure after rollback.
+	return renameSymbol(intel, ctx.workspaceRoot, target, line, character, symbol, newName).then((result) =>
+		ok(formatRenameResult(ctx.workspaceRoot, result)),
+	)
+}
+
+// ─── import_graph ────────────────────────────────────────────────────────────
+
+export function importGraphHandler(args: Record<string, unknown>, ctx: ToolContext): ToolResult {
+	const tool = "import_graph"
+	const filePath = requireStringArg(args, "path", tool)
+	const target = resolveTarget(ctx, tool, filePath)
+
+	const intel = intelFor(ctx)
+	const graph = getImportGraph(intel)
+	return ok(formatImportGraph(ctx.workspaceRoot, target, graph))
+}
+
+/** Parse a source file standalone (for files created after program load). */
+function readStandalone(file: string): ts.SourceFile | undefined {
+	const text = ts.sys.readFile(file)
+	if (text === undefined) {
+		return undefined
+	}
+	return ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKindFromFileName(file))
+}