headlesscode 1.0.2

package/src/codeintel/import-graph.ts

@@ -0,0 +1,173 @@
+/**
+ * `import_graph` analysis: (a) what a file imports, resolved to real file
+ * paths (not raw specifiers), and (b) what imports it (reverse lookup).
+ *
+ * Static analysis of `ts.ImportDeclaration` / `ts.ExportDeclaration` /
+ * `ts.ImportEqualsDeclaration` nodes — imports are syntactic, not
+ * type-dependent, so this needs no type-checking: specifiers are resolved
+ * with `ts.resolveModuleName` against the cached program's compiler options
+ * (so `paths` aliases like `vscode` → the shim resolve exactly as the
+ * compiler would).
+ *
+ * The whole-program import map is built ONCE per loaded program and cached
+ * alongside it (see CodeIntelCache): reverse lookups never rescan the
+ * project per call.
+ */
+
+import * as path from "node:path"
+import * as ts from "typescript"
+
+import type { CodeIntel } from "./program.js"
+
+export interface ImportEdge {
+	/** Raw module specifier as written in source (e.g. "./foo" or "vscode"). */
+	specifier: string
+	/** Real resolved file path (undefined when resolution fails). */
+	resolved: string | undefined
+	/** True for `export ... from` re-exports. */
+	isReExport: boolean
+	/** True for `import type` / `export type`. */
+	isTypeOnly: boolean
+}
+
+export interface ImportGraph {
+	/** Per absolute file path: everything it imports. */
+	imports: Map<string, ImportEdge[]>
+	/** Per resolved file path: every absolute file path that imports it. */
+	importedBy: Map<string, string[]>
+}
+
+/** Resolve a module specifier the same way the compiler would. */
+function resolveSpecifier(
+	intel: CodeIntel,
+	containingFile: string,
+	specifier: string,
+): string | undefined {
+	const result = ts.resolveModuleName(specifier, containingFile, intel.compilerOptions, {
+		fileExists: ts.sys.fileExists,
+		readFile: ts.sys.readFile,
+		getCurrentDirectory: () => path.dirname(containingFile),
+		directoryExists: ts.sys.directoryExists,
+	})
+	return result.resolvedModule?.resolvedFileName
+}
+
+/**
+ * Build (or return the cached) import graph for the program. The graph is a
+ * pure function of the program's source files, so it is computed once and
+ * reused until the program itself is rebuilt.
+ */
+export function getImportGraph(intel: CodeIntel): ImportGraph {
+	const cached = (intel as { __importGraph?: ImportGraph }).__importGraph
+	if (cached !== undefined) {
+		return cached
+	}
+
+	const imports = new Map<string, ImportEdge[]>()
+	const importedBy = new Map<string, string[]>()
+
+	const addReverseEdge = (resolved: string | undefined, importer: string): void => {
+		if (resolved === undefined) {
+			return
+		}
+		const list = importedBy.get(resolved) ?? []
+		if (!list.includes(importer)) {
+			list.push(importer)
+			importedBy.set(resolved, list)
+		}
+	}
+
+	for (const sourceFile of intel.program.getSourceFiles()) {
+		const fileImports: ImportEdge[] = []
+
+		const collect = (node: ts.Node): void => {
+			if (ts.isImportDeclaration(node)) {
+				if (ts.isStringLiteral(node.moduleSpecifier)) {
+					const specifier = node.moduleSpecifier.text
+					const resolved = resolveSpecifier(intel, sourceFile.fileName, specifier)
+					fileImports.push({
+						specifier,
+						resolved,
+						isReExport: false,
+						// The flag lives on the import clause, not the declaration.
+						isTypeOnly: node.importClause?.isTypeOnly === true,
+					})
+					addReverseEdge(resolved, sourceFile.fileName)
+				}
+			} else if (ts.isExportDeclaration(node)) {
+				// ExportDeclaration.moduleSpecifier is optional (`export {}`).
+				if (node.moduleSpecifier !== undefined && ts.isStringLiteral(node.moduleSpecifier)) {
+					const specifier = node.moduleSpecifier.text
+					const resolved = resolveSpecifier(intel, sourceFile.fileName, specifier)
+					fileImports.push({
+						specifier,
+						resolved,
+						isReExport: true,
+						isTypeOnly: node.isTypeOnly === true,
+					})
+					addReverseEdge(resolved, sourceFile.fileName)
+				}
+			} else if (ts.isImportEqualsDeclaration(node)) {
+				const ref = node.moduleReference
+				if (ts.isExternalModuleReference(ref) && ref.expression !== undefined && ts.isStringLiteral(ref.expression)) {
+					const specifier = ref.expression.text
+					const resolved = resolveSpecifier(intel, sourceFile.fileName, specifier)
+					fileImports.push({
+						specifier,
+						resolved,
+						isReExport: false,
+						isTypeOnly: false,
+					})
+					addReverseEdge(resolved, sourceFile.fileName)
+				}
+			}
+		}
+
+		ts.forEachChild(sourceFile, (node) => collect(node))
+		if (fileImports.length > 0) {
+			imports.set(sourceFile.fileName, fileImports)
+		}
+	}
+
+	const graph: ImportGraph = { imports, importedBy }
+	;(intel as { __importGraph?: ImportGraph }).__importGraph = graph
+	return graph
+}
+
+/** Absolute path → workspace-relative (posix) for display; absolute if outside. */
+function displayPath(workspaceRoot: string, p: string): string {
+	const rel = path.relative(workspaceRoot, p)
+	return rel === "" || rel.startsWith("..") ? p : rel.split(path.sep).join("/")
+}
+
+/** Render the import graph for one file. */
+export function formatImportGraph(
+	workspaceRoot: string,
+	fileName: string,
+	graph: ImportGraph,
+): string {
+	const out: string[] = []
+
+	const edges = graph.imports.get(fileName) ?? []
+	out.push(`imports (${edges.length}):`)
+	if (edges.length === 0) {
+		out.push("  (none)")
+	}
+	for (const edge of edges) {
+		const target = edge.resolved !== undefined ? displayPath(workspaceRoot, edge.resolved) : `(unresolved: ${edge.specifier})`
+		const typeOnly = edge.isTypeOnly ? "type " : ""
+		const reExport = edge.isReExport ? "export " : "import "
+		out.push(`  ${reExport}${typeOnly}${edge.specifier} -> ${target}`)
+	}
+
+	const importers = graph.importedBy.get(fileName) ?? []
+	out.push(`imported by (${importers.length}):`)
+	if (importers.length === 0) {
+		out.push("  (none)")
+	}
+	for (const importer of importers.sort()) {
+		out.push(`  ${displayPath(workspaceRoot, importer)}`)
+	}
+
+	return out.join("\n")
+}

package/src/codeintel/outline.ts

@@ -0,0 +1,180 @@
+/**
+ * `outline` analysis: every top-level (and one level of nested) declaration
+ * in a source file, as `line kind signature` — one compact line per symbol,
+ * signatures only, no bodies. Built on the real AST (`ts.forEachChild`), not
+ * regex: kinds come from the node types, lines from
+ * `ts.getLineAndCharacterOfPosition`, and signatures are the node's own
+ * source text cut at its body — so `14 function foo(x: string): void` is
+ * exactly what the source says, no guesswork.
+ */
+
+import * as ts from "typescript"
+
+export interface OutlineEntry {
+	/** 1-based line of the declaration's name. */
+	line: number
+	kind: string
+	signature: string
+	/** Nesting depth: 0 = top level, 1 = class/interface/namespace member. */
+	depth: number
+}
+
+/** Map a TS node to a short human kind label. */
+function kindOf(node: ts.Node): string | undefined {
+	if (ts.isFunctionDeclaration(node)) return "function"
+	if (ts.isClassDeclaration(node)) return "class"
+	if (ts.isInterfaceDeclaration(node)) return "interface"
+	if (ts.isTypeAliasDeclaration(node)) return "type"
+	if (ts.isEnumDeclaration(node)) return "enum"
+	if (ts.isModuleDeclaration(node)) return "namespace"
+	if (ts.isVariableStatement(node)) return "var"
+	if (ts.isMethodDeclaration(node)) return "method"
+	if (ts.isPropertyDeclaration(node)) return "property"
+	if (ts.isGetAccessorDeclaration(node)) return "getter"
+	if (ts.isSetAccessorDeclaration(node)) return "setter"
+	if (ts.isPropertySignature(node)) return "property"
+	if (ts.isMethodSignature(node)) return "method"
+	if (ts.isCallSignatureDeclaration(node)) return "call-signature"
+	if (ts.isConstructSignatureDeclaration(node)) return "construct-signature"
+	if (ts.isIndexSignatureDeclaration(node)) return "index-signature"
+	return undefined
+}
+
+/** True for function-like nodes whose body is a block we must cut off. */
+function hasBlockBody(node: ts.Node): boolean {
+	return (
+		ts.isFunctionDeclaration(node) ||
+		ts.isMethodDeclaration(node) ||
+		ts.isGetAccessorDeclaration(node) ||
+		ts.isSetAccessorDeclaration(node)
+	)
+}
+
+/** A container whose members are worth outlining one level deep. */
+function isContainer(node: ts.Node): boolean {
+	return (
+		ts.isClassDeclaration(node) ||
+		ts.isInterfaceDeclaration(node) ||
+		ts.isModuleDeclaration(node) ||
+		ts.isEnumDeclaration(node)
+	)
+}
+
+/**
+ * The declaration's signature text WITHOUT its body: for functions, source
+ * from the node start up to the body's `{`; for types/classes/interfaces,
+ * up to the first `{` or `;`. Internal whitespace is collapsed to one space
+ * so multi-line signatures stay on a single output line.
+ */
+function signatureOf(node: ts.Node, sourceFile: ts.SourceFile): string {
+	const full = node.getText(sourceFile)
+	let cut = full
+	if (hasBlockBody(node)) {
+		const body = (node as ts.FunctionLikeDeclaration).body
+		if (body !== undefined) {
+			cut = full.slice(0, body.getStart(sourceFile) - node.getStart(sourceFile))
+		}
+	} else {
+		const brace = cut.indexOf("{")
+		const semi = cut.indexOf(";")
+		if (brace !== -1 && (semi === -1 || brace < semi)) {
+			cut = cut.slice(0, brace)
+		} else if (semi !== -1) {
+			cut = cut.slice(0, semi)
+		}
+	}
+	return stripLeadingKeywords(cut.replace(/\s+/g, " ").trim())
+}
+
+/**
+ * Leading tokens to drop from a signature: visibility/export modifiers and the
+ * declaration keyword itself (`export function foo()`, `abstract class Shape`,
+ * `public readonly x`). The kind column already prints the keyword, so keeping
+ * it would duplicate ("function export function foo()").
+ */
+const STRIP_PREFIX = [
+	"export", "default", "declare", "abstract", "async",
+	"public", "private", "protected", "readonly", "static", "override",
+	"function", "class", "interface", "type", "enum", "namespace", "module",
+	"const", "let", "var",
+]
+
+/** Strip leading modifier/kind tokens, keeping the name onward intact. */
+function stripLeadingKeywords(text: string): string {
+	const words = text.split(/\s+/)
+	let i = 0
+	while (i < words.length && STRIP_PREFIX.includes(words[i]!)) {
+		i++
+	}
+	return words.slice(i).join(" ")
+}
+
+/** Variable statements declare each name separately (kind from the statement). */
+function variableEntries(stmt: ts.VariableStatement, sourceFile: ts.SourceFile): OutlineEntry[] {
+	const flags = stmt.declarationList.flags
+	const kind = flags & ts.NodeFlags.Const ? "const" : flags & ts.NodeFlags.Let ? "let" : "var"
+	return stmt.declarationList.declarations.map((decl) => {
+		const name = decl.name.getText(sourceFile)
+		const type = decl.type !== undefined ? decl.type.getText(sourceFile) : undefined
+		return {
+			line: ts.getLineAndCharacterOfPosition(sourceFile, decl.getStart(sourceFile)).line + 1,
+			kind,
+			// The kind column already prints the keyword — don't repeat it.
+			signature: `${name}${type !== undefined ? `: ${type}` : ""}`,
+			depth: 0,
+		}
+	})
+}
+
+/**
+ * Outline a source file. `maxDepth` controls how deep into the declaration
+ * tree we go: 0 = top level only, 1 (default) = also members of classes,
+ * interfaces, and namespaces. Function bodies are never descended into —
+ * nested locals are noise for a structure overview.
+ */
+export function outlineSourceFile(sourceFile: ts.SourceFile, maxDepth = 1): OutlineEntry[] {
+	const entries: OutlineEntry[] = []
+
+	const walk = (node: ts.Node, depth: number): void => {
+		if (ts.isVariableStatement(node)) {
+			entries.push(...variableEntries(node, sourceFile))
+		} else {
+			const kind = kindOf(node)
+			if (kind !== undefined) {
+				const named = node as { name?: ts.Node }
+				entries.push({
+					line:
+						ts.getLineAndCharacterOfPosition(sourceFile, named.name ? named.name.getStart(sourceFile) : node.getStart(sourceFile))
+							.line + 1,
+					kind,
+					signature: signatureOf(node, sourceFile),
+					depth,
+				})
+			}
+		}
+
+		if (depth >= maxDepth) {
+			return
+		}
+		// Never look inside function bodies; containers get one deeper level.
+		if (hasBlockBody(node) || ts.isVariableStatement(node)) {
+			return
+		}
+		if (isContainer(node)) {
+			ts.forEachChild(node, (child) => walk(child, depth + 1))
+			return
+		}
+		ts.forEachChild(node, (child) => walk(child, depth))
+	}
+
+	ts.forEachChild(sourceFile, (child) => walk(child, 0))
+	return entries
+}
+
+/** Render outline entries as the compact `line kind signature` lines. */
+export function formatOutline(entries: OutlineEntry[]): string {
+	if (entries.length === 0) {
+		return "No declarations found in this file."
+	}
+	return entries.map((e) => `${"  ".repeat(e.depth)}${e.line} ${e.kind} ${e.signature}`).join("\n")
+}

package/src/codeintel/position.ts

@@ -0,0 +1,77 @@
+/**
+ * Position → identifier resolution shared by `go_to_definition` and
+ * `find_references`.
+ *
+ * The TS LanguageService APIs (`getDefinitionAtPosition`,
+ * `getReferencesAtPosition`) take a character OFFSET into the file, not a
+ * line number — so the tools' `{ line, character?, symbol? }` parameter
+ * shape is resolved here into a concrete `ts.Identifier` the LS can answer
+ * about:
+ *   - `character` given (1-based column): the identifier touching that column
+ *   - `symbol` given: the first identifier on the line whose text matches
+ *   - neither: the first identifier on the line
+ *
+ * Identifiers come from a real AST walk (`ts.forEachChild`), so text inside
+ * strings, comments, and import specifiers is naturally excluded — except
+ * import clause names (`import { foo }` parses `foo` as an Identifier), which
+ * is exactly what we want: "go to definition" on an imported name must
+ * resolve through the checker to its real declaration.
+ */
+
+import * as ts from "typescript"
+
+/** Collect every Identifier whose text range falls on `line` (1-based). */
+export function identifiersOnLine(sourceFile: ts.SourceFile, line: number): ts.Identifier[] {
+	const line0 = line - 1
+	const found: ts.Identifier[] = []
+	const visit = (node: ts.Node): void => {
+		if (ts.isIdentifier(node)) {
+			const { line: nodeLine } = ts.getLineAndCharacterOfPosition(sourceFile, node.getStart(sourceFile))
+			if (nodeLine === line0) {
+				found.push(node)
+			}
+		}
+		ts.forEachChild(node, visit)
+	}
+	visit(sourceFile)
+	return found
+}
+
+/**
+ * Resolve a (1-based line, optional 1-based character) + optional symbol name
+ * to the identifier a user means, or undefined when nothing resolvable sits
+ * at that spot. "Touching" semantics: a character pointing at the LAST char
+ * of an identifier still selects it, so a model that guessed the column one
+ * short of the end still gets the right symbol.
+ */
+export function identifierAtPosition(
+	sourceFile: ts.SourceFile,
+	line: number,
+	character: number | undefined,
+	symbol: string | undefined,
+): ts.Identifier | undefined {
+	if (line < 1 || line > sourceFile.getLineStarts().length) {
+		return undefined
+	}
+	const onLine = identifiersOnLine(sourceFile, line)
+	if (onLine.length === 0) {
+		return undefined
+	}
+
+	if (character !== undefined && character >= 1) {
+		const lineStart = ts.getPositionOfLineAndCharacter(sourceFile, line - 1, 0)
+		const pos = lineStart + (character - 1)
+		for (const id of onLine) {
+			if (pos >= id.getStart(sourceFile) && pos <= id.getEnd()) {
+				return id
+			}
+		}
+		return undefined
+	}
+
+	if (symbol !== undefined && symbol.trim() !== "") {
+		return onLine.find((id) => id.text === symbol)
+	}
+
+	return onLine[0]
+}