headlesscode 1.0.2

package/src/codeintel/program.ts

@@ -0,0 +1,350 @@
+/**
+ * Shared TypeScript program loading for the code-intelligence tools
+ * (`outline`, `go_to_definition`, `find_references`, `import_graph`).
+ *
+ * All four tools need the same foundational capability — parse the target
+ * workspace's real TypeScript source respecting its actual `tsconfig.json`
+ * (including `paths` aliases like this repo's `vscode` → shim mapping) — so
+ * they share ONE module that owns program loading, instead of four
+ * independent implementations drifting into four subtly different analyses.
+ *
+ * Loading is deliberately built on the real Compiler API, never a regex or a
+ * hand-rolled parser:
+ *   - `ts.findConfigFile` + `ts.readConfigFile` +
+ *     `ts.parseJsonConfigFileContent` for tsconfig handling (not hand-rolled)
+ *   - `ts.createProgram` for the type-checked program
+ *   - `ts.createLanguageService` (backed by the program) for definition
+ *     resolution (`getDefinitionAtPosition`) and reference finding
+ *     (`getReferencesAtPosition`)
+ *
+ * Caching: rebuilding a full TS program is expensive, so a loaded program is
+ * cached per workspace root for a session's lifetime and only rebuilt when a
+ * file the program covers has actually changed. We track the mtimes of the
+ * project's own source files (the tsconfig's resolved `fileNames`, i.e. the
+ * files an edit tool can realistically touch) plus the tsconfig file itself;
+ * node_modules types are deliberately NOT tracked (they don't change
+ * mid-session). The model edits a `.ts` file in the workspace → its mtime
+ * changes → the next tool call rebuilds. `CodeIntelCache.programLoadCount`
+ * exists so tests can prove the cache is reused with a real call counter,
+ * mirroring how caching behavior is proven elsewhere in this project.
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+import * as ts from "typescript"
+
+/** Everything a code-intelligence tool call needs from a loaded workspace. */
+export interface CodeIntel {
+	program: ts.Program
+	languageService: ts.LanguageService
+	compilerOptions: ts.CompilerOptions
+	/** Absolute path of the tsconfig that produced this program (undefined if none). */
+	configFilePath: string | undefined
+	/** Absolute paths of the project's own source files (tsconfig `fileNames`). */
+	projectFiles: string[]
+	/**
+	 * Ad-hoc files served by the language-service host that are NOT part of
+	 * the program (e.g. a `.ts` file the model just created with write_to_file
+	 * after the program was last loaded). They parse on demand against the
+	 * program's compiler options; cross-file resolution still goes through the
+	 * program's checker.
+	 */
+	includeExtraFile(fileName: string): void
+}
+
+/** A per-workspace cache of a loaded program + language service. */
+export class CodeIntelCache {
+	/** Real load counter: 1 per actual program build (tests assert on this). */
+	programLoadCount = 0
+
+	private loaded: { intel: CodeIntel; trackedMtimes: Map<string, number> } | undefined
+
+	constructor(readonly workspaceRoot: string) {}
+
+	/** Load-or-reuse the cached program, rebuilding only if a covered file changed. */
+	get(): CodeIntel {
+		if (this.loaded !== undefined && !this.hasCoveredFileChanged()) {
+			return this.loaded.intel
+		}
+		const intel = loadCodeIntel(this.workspaceRoot)
+		this.loaded = { intel, trackedMtimes: trackMtimes(intel) }
+		this.programLoadCount += 1
+		return intel
+	}
+
+	/** Drop the cached program (used by tests; not needed by session code). */
+	invalidate(): void {
+		this.loaded = undefined
+	}
+
+	private hasCoveredFileChanged(): boolean {
+		for (const [file, mtime] of this.loaded!.trackedMtimes) {
+			try {
+				if (fs.statSync(file).mtimeMs !== mtime) {
+					return true
+				}
+			} catch {
+				// File deleted since load — definitely stale.
+				return true
+			}
+		}
+		return false
+	}
+}
+
+/**
+ * Per-workspace caches, keyed by the (resolved) workspace root. One process
+ * can host several workspaces (headless session + reviewer/QA executors), and
+ * each keeps its own program — same pattern as the browser sessions registry.
+ */
+const caches = new Map<string, CodeIntelCache>()
+
+/** Get (creating if needed) the program cache for a workspace root. */
+export function getCodeIntelCache(workspaceRoot: string): CodeIntelCache {
+	const root = path.resolve(workspaceRoot)
+	let cache = caches.get(root)
+	if (cache === undefined) {
+		cache = new CodeIntelCache(root)
+		caches.set(root, cache)
+	}
+	return cache
+}
+
+/** Drop every cached program (test isolation). */
+export function resetCodeIntelCaches(): void {
+	caches.clear()
+}
+
+/** Record the mtimes of the files whose change invalidates the program. */
+function trackMtimes(intel: CodeIntel): Map<string, number> {
+	const mtimes = new Map<string, number>()
+	for (const file of intel.projectFiles) {
+		try {
+			mtimes.set(file, fs.statSync(file).mtimeMs)
+		} catch {
+			// File vanished between program load and tracking — leave untracked;
+			// the next get() rebuilds only when a TRACKED file changes. A deleted
+			// untracked file is still served from the cached program snapshot.
+		}
+	}
+	if (intel.configFilePath !== undefined) {
+		try {
+			mtimes.set(intel.configFilePath, fs.statSync(intel.configFilePath).mtimeMs)
+		} catch {
+			// Same as above.
+		}
+	}
+	return mtimes
+}
+
+function loadCodeIntel(workspaceRoot: string): CodeIntel {
+	const configFilePath = ts.findConfigFile(workspaceRoot, ts.sys.fileExists, "tsconfig.json")
+
+	let compilerOptions: ts.CompilerOptions
+	let rootNames: string[]
+	let configFileParsingDiagnostics: ts.Diagnostic[] = []
+
+	if (configFilePath !== undefined) {
+		const read = ts.readConfigFile(configFilePath, ts.sys.readFile)
+		if (read.error !== undefined) {
+			throw new Error(
+				`cannot read tsconfig at ${configFilePath}: ${ts.flattenDiagnosticMessageText(read.error.messageText, "\n")}`,
+			)
+		}
+		const parsed = ts.parseJsonConfigFileContent(
+			read.config,
+			{
+				useCaseSensitiveFileNames: ts.sys.useCaseSensitiveFileNames,
+				readDirectory: ts.sys.readDirectory,
+				fileExists: ts.sys.fileExists,
+				readFile: ts.sys.readFile,
+			},
+			path.dirname(configFilePath),
+			undefined,
+			configFilePath,
+		)
+		compilerOptions = parsed.options
+		rootNames = parsed.fileNames
+		configFileParsingDiagnostics = parsed.errors
+	} else {
+		// No tsconfig: fall back to a sensible default program over every
+		// TypeScript file in the workspace (excluding deps/vcs/hidden dirs).
+		// This keeps the tools working on scratch workspaces and fixtures
+		// without requiring the target to have a tsconfig of its own.
+		compilerOptions = {
+			target: ts.ScriptTarget.ES2022,
+			module: ts.ModuleKind.ESNext,
+			moduleResolution: ts.ModuleResolutionKind.Bundler,
+			strict: false,
+			skipLibCheck: true,
+		}
+		rootNames = discoverTypeScriptFiles(workspaceRoot)
+	}
+
+	const program = ts.createProgram({
+		rootNames,
+		options: compilerOptions,
+		configFileParsingDiagnostics,
+	})
+
+	const host = new LsHost(program, compilerOptions)
+	const languageService = ts.createLanguageService(host)
+
+	return {
+		program,
+		languageService,
+		compilerOptions,
+		configFilePath: configFilePath ?? undefined,
+		projectFiles: rootNames,
+		includeExtraFile: (fileName) => host.includeExtraFile(fileName),
+	}
+}
+
+/** Recursively find every `.ts`/`.tsx`/`.mts`/`.cts` file, skipping noise dirs. */
+function discoverTypeScriptFiles(root: string): string[] {
+	const found: string[] = []
+	const skip = new Set(["node_modules", ".git", ".hg", ".svn", "dist", "out", "build", "coverage"])
+	const walk = (dir: string): void => {
+		let entries: fs.Dirent[]
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true })
+		} catch {
+			return
+		}
+		for (const entry of entries) {
+			if (entry.name.startsWith(".") || skip.has(entry.name)) {
+				continue
+			}
+			const full = path.join(dir, entry.name)
+			if (entry.isDirectory()) {
+				walk(full)
+			} else if (isSupportedSource(entry.name)) {
+				found.push(full)
+			}
+		}
+	}
+	walk(root)
+	return found
+}
+
+/** True for file names the TS compiler can parse as source. */
+export function isSupportedSource(fileName: string): boolean {
+	return /\.(m|c)?(t|j)sx?$/i.test(fileName) || /\.d\.(m|c)?ts$/i.test(fileName)
+}
+
+/**
+ * Map a file name to the TS ScriptKind by extension. The compiler's internal
+ * `getScriptKindFromFileName` exists at runtime but is NOT part of the public
+ * d.ts, so we keep a small local equivalent rather than casting to an untyped
+ * API.
+ */
+export function scriptKindFromFileName(fileName: string): ts.ScriptKind {
+	const lower = fileName.toLowerCase()
+	if (lower.endsWith(".tsx")) {
+		return ts.ScriptKind.TSX
+	}
+	if (lower.endsWith(".jsx")) {
+		return ts.ScriptKind.JSX
+	}
+	if (lower.endsWith(".mts") || lower.endsWith(".cts") || lower.endsWith(".ts")) {
+		return ts.ScriptKind.TS
+	}
+	if (lower.endsWith(".mjs") || lower.endsWith(".cjs") || lower.endsWith(".js")) {
+		return ts.ScriptKind.JS
+	}
+	if (lower.endsWith(".json")) {
+		return ts.ScriptKind.JSON
+	}
+	return ts.ScriptKind.Unknown
+}
+
+/**
+ * Language-service host backed by the cached program's already-parsed source
+ * files (no re-reading from disk for program files), with an ad-hoc escape
+ * hatch for files created after the program was loaded.
+ */
+class LsHost implements ts.LanguageServiceHost {
+	private readonly extraFiles = new Set<string>()
+
+	constructor(
+		private readonly program: ts.Program,
+		private readonly options: ts.CompilerOptions,
+	) {}
+
+	includeExtraFile(fileName: string): void {
+		this.extraFiles.add(fileName)
+	}
+
+	getCompilationSettings(): ts.CompilerOptions {
+		return this.options
+	}
+
+	getScriptFileNames(): string[] {
+		const names = this.program.getSourceFiles().map((sf) => sf.fileName)
+		for (const extra of this.extraFiles) {
+			if (!names.includes(extra)) {
+				names.push(extra)
+			}
+		}
+		return names
+	}
+
+	getScriptVersion(fileName: string): string {
+		const sf = this.program.getSourceFile(fileName)
+		if (sf !== undefined) {
+			// Program files: the whole program + LS is rebuilt on any tracked
+			// change, so a static version is correct here.
+			return "1"
+		}
+		if (this.extraFiles.has(fileName)) {
+			// Version = mtime: a re-edit of an extra file invalidates the
+			// language service's cached parse of it.
+			try {
+				return String(fs.statSync(fileName).mtimeMs)
+			} catch {
+				return "1"
+			}
+		}
+		return ""
+	}
+
+	getScriptSnapshot(fileName: string): ts.IScriptSnapshot | undefined {
+		const sf = this.program.getSourceFile(fileName)
+		if (sf !== undefined) {
+			return ts.ScriptSnapshot.fromString(sf.text)
+		}
+		if (this.extraFiles.has(fileName)) {
+			const text = ts.sys.readFile(fileName)
+			return text === undefined ? undefined : ts.ScriptSnapshot.fromString(text)
+		}
+		return undefined
+	}
+
+	getCurrentDirectory(): string {
+		return this.program.getCurrentDirectory()
+	}
+
+	getDefaultLibFileName(options: ts.CompilerOptions): string {
+		return ts.getDefaultLibFilePath(options)
+	}
+
+	fileExists(fileName: string): boolean {
+		return ts.sys.fileExists(fileName)
+	}
+
+	readFile(fileName: string): string | undefined {
+		return ts.sys.readFile(fileName)
+	}
+
+	readDirectory(path: string, extensions?: readonly string[], exclude?: readonly string[], include?: readonly string[], depth?: number): string[] {
+		return ts.sys.readDirectory(path, extensions, exclude, include, depth)
+	}
+
+	useCaseSensitiveFileNames(): boolean {
+		return ts.sys.useCaseSensitiveFileNames
+	}
+
+	getScriptKind(fileName: string): ts.ScriptKind {
+		return scriptKindFromFileName(fileName)
+	}
+}

package/src/codeintel/rename-symbol.ts

@@ -0,0 +1,213 @@
+/**
+ * `rename_symbol` analysis: rename a symbol at (file, line[, character |
+ * symbol]) to a new name across EVERY real usage site in the workspace, as
+ * ONE atomic operation.
+ *
+ * Site enumeration reuses `findReferences` — the language service's real
+ * `getReferencesAtPosition` resolution, never grep — so the same "which
+ * identifiers are actually this symbol" correctness that `find_references`
+ * already has applies to the edit side too. Nothing here re-parses or
+ * guesses: the reference spans ARE the edit targets.
+ *
+ * Atomicity contract: either every site updates or none do.
+ *   - All files are read and all new contents are COMPUTED before the first
+ *     write, so a mismatch (file changed since the program snapshot) aborts
+ *     with nothing written.
+ *   - The writes then go file-by-file; if any write fails, every file
+ *     already written is restored from its captured original before the
+ *     error propagates. A partial rename leaving the codebase inconsistent
+ *     is worse than the N-round-trip status quo this replaces.
+ *
+ * Scope guard (matches find_references/go_to_definition's boundary — see
+ * src/codeintel/program.ts): TypeScript/JavaScript source files only, and
+ * every site must resolve inside the workspace root. A reference outside
+ * the workspace (e.g. into node_modules) REFUSES the whole rename rather
+ * than silently skipping a site or editing outside the sandbox.
+ */
+
+import * as path from "node:path"
+import * as ts from "typescript"
+
+import { scriptKindFromFileName, type CodeIntel } from "./program.js"
+import { identifierAtPosition } from "./position.js"
+import { findReferences } from "./find-references.js"
+import { readFile, writeFile } from "node:fs/promises"
+
+/** A rename edit target, captured BEFORE any file is written. */
+export interface RenameSite {
+	fileName: string
+	line: number
+	/** Write access (declaration / assignment) vs read access. */
+	isWriteAccess: boolean
+	/** The line's text as it looked BEFORE the rename (for the result). */
+	snippet: string
+}
+
+export interface RenameResult {
+	oldName: string
+	newName: string
+	/** Every edited site, pre-rename text (sorted by file, then line). */
+	sites: RenameSite[]
+}
+
+/** A valid TS identifier (what `new_name` must be). */
+const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+export function isValidIdentifier(name: string): boolean {
+	return IDENTIFIER_RE.test(name)
+}
+
+/** 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))
+}
+
+/** True when `p` resolves inside `root` (path-safety mirror of safeTarget). */
+function isInside(root: string, p: string): boolean {
+	const rel = path.relative(root, p)
+	return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))
+}
+
+/**
+ * Rename the symbol at `line` (1-based) in `file` to `newName` everywhere it
+ * is referenced across the workspace. Throws with a clear message on any
+ * pre-write validation failure (bad new name, no references, a reference
+ * outside the workspace, a span that no longer matches the old name) and on
+ * a mid-write failure (after rolling back the files already written).
+ */
+export async function renameSymbol(
+	intel: CodeIntel,
+	workspaceRoot: string,
+	file: string,
+	line: number,
+	character: number | undefined,
+	symbol: string | undefined,
+	newName: string,
+): Promise<RenameResult> {
+	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) {
+		throw new Error(`no identifier found at ${rel(workspaceRoot, file)}:${line} — nothing to rename`)
+	}
+	const oldName = identifier.text
+	if (oldName === newName) {
+		throw new Error(`new name must differ from the current name '${oldName}'`)
+	}
+	if (!isValidIdentifier(newName)) {
+		throw new Error(`'${newName}' is not a valid TypeScript identifier — use a plain name like 'renamedFoo'`)
+	}
+
+	intel.includeExtraFile(file)
+	const sites = findReferences(intel, file, line, character, symbol)
+	if (sites.length === 0) {
+		throw new Error(`no references found for '${oldName}' — nothing to rename`)
+	}
+
+	// Group the absolute edit offsets by file, refusing any site outside the
+	// workspace BEFORE anything is read or written (all-or-nothing).
+	const offsetsByFile = new Map<string, number[]>()
+	for (const site of sites) {
+		if (!isInside(workspaceRoot, site.fileName)) {
+			throw new Error(
+				`rename refused: reference to '${oldName}' at ${rel(workspaceRoot, site.fileName)}:${site.line} is outside the workspace root — renaming would edit outside the sandbox`,
+			)
+		}
+		const list = offsetsByFile.get(site.fileName) ?? []
+		list.push(site.start)
+		offsetsByFile.set(site.fileName, list)
+	}
+
+	// Phase 1: read every target file. A read failure aborts with nothing
+	// written — the file may have been deleted/renamed since the snapshot.
+	const originals = new Map<string, string>()
+	for (const fileName of offsetsByFile.keys()) {
+		try {
+			originals.set(fileName, await readFile(fileName, "utf-8"))
+		} catch (err) {
+			throw new Error(
+				`rename aborted: cannot read ${rel(workspaceRoot, fileName)} for the rename: ${err instanceof Error ? err.message : String(err)}`,
+			)
+		}
+	}
+
+	// Phase 2: compute every updated content in memory. Each span must still
+	// hold the old name — a mismatch means the file changed since the
+	// reference snapshot (the program would normally have rebuilt, but be
+	// defensive), and aborting here still writes nothing.
+	const updated = new Map<string, string>()
+	for (const [fileName, offsets] of offsetsByFile) {
+		const text = originals.get(fileName)!
+		// Descending order: later edits never shift earlier offsets.
+		const sorted = [...offsets].sort((a, b) => b - a)
+		let result = text
+		for (const start of sorted) {
+			const spanText = result.slice(start, start + oldName.length)
+			if (spanText !== oldName) {
+				throw new Error(
+					`rename aborted: expected '${oldName}' at ${rel(workspaceRoot, fileName)} (offset ${start}) but found '${spanText}' — the file changed since the reference snapshot; re-read it and re-run the rename`,
+				)
+			}
+			result = result.slice(0, start) + newName + result.slice(start + oldName.length)
+		}
+		updated.set(fileName, result)
+	}
+
+	// Phase 3: write every file; roll back the already-written ones on any
+	// failure so no partial rename survives.
+	const written: string[] = []
+	try {
+		for (const [fileName, content] of updated) {
+			await writeFile(fileName, content, "utf-8")
+			written.push(fileName)
+		}
+	} catch (err) {
+		for (const fileName of written) {
+			try {
+				await writeFile(fileName, originals.get(fileName)!, "utf-8")
+			} catch {
+				// Best-effort rollback; the primary error below is the signal.
+			}
+		}
+		throw new Error(
+			`rename failed while writing ${rel(workspaceRoot, written[written.length - 1] ?? "(unknown)")}: ${
+				err instanceof Error ? err.message : String(err)
+			} — all files already written were rolled back to their original content`,
+		)
+	}
+
+	const byFile = new Map<string, RenameSite[]>()
+	for (const site of sites) {
+		const list = byFile.get(site.fileName) ?? []
+		list.push({
+			fileName: site.fileName,
+			line: site.line,
+			isWriteAccess: site.isWriteAccess,
+			snippet: site.snippet,
+		})
+		byFile.set(site.fileName, list)
+	}
+	const flat = [...byFile.values()]
+		.flat()
+		.sort((a, b) => a.fileName.localeCompare(b.fileName) || a.line - b.line)
+
+	return { oldName, newName, sites: flat }
+}
+
+/** Workspace-relative (posix) display path; absolute if somehow outside. */
+function rel(workspaceRoot: string, p: string): string {
+	const r = path.relative(workspaceRoot, p)
+	return r === "" || r.startsWith("..") ? p : r.split(path.sep).join("/")
+}
+
+/** Render a rename result as compact `file:line — snippet` lines. */
+export function formatRenameResult(workspaceRoot: string, result: RenameResult): string {
+	const lines = result.sites.map((s) => `${rel(workspaceRoot, s.fileName)}:${s.line}${s.isWriteAccess ? " (write)" : ""} — ${s.snippet}`)
+	return `Renamed '${result.oldName}' → '${result.newName}' across ${result.sites.length} site(s):\n${lines.join("\n")}`
+}