dsh-plugin-codegraph-tree-sitter 0.1.0

package/lib/languages.js

@@ -0,0 +1,107 @@
+/**
+ * Per-language extraction tables: which tree-sitter node types are definitions, which are call
+ * sites, and which anchor an import, for every grammar this package loads today.
+ *
+ * The table is deliberately small. It covers the definition/call/import core the seam's operations
+ * depend on — not every declaration shape a language can produce — because the alternative is porting
+ * the reference indexer's language-specific resolution, which the proposal this package implements
+ * defers until the core proves itself against real workspaces.
+ * @module dsh-plugin-codegraph-tree-sitter/languages
+ */
+/** Definitions common to every ECMAScript-family grammar (JavaScript, JSX, TypeScript, TSX). */
+const ECMASCRIPT_DEFINITIONS = [
+    { nodeType: 'function_declaration', kind: 'function', nameField: 'name' },
+    { nodeType: 'generator_function_declaration', kind: 'function', nameField: 'name' },
+    { nodeType: 'method_definition', kind: 'method', nameField: 'name' },
+    { nodeType: 'class_declaration', kind: 'class', nameField: 'name' },
+    {
+        nodeType: 'variable_declarator',
+        kind: 'function',
+        nameField: 'name',
+        value: { field: 'value', types: ['arrow_function', 'function_expression', 'generator_function'] },
+    },
+];
+/** Definitions TypeScript and TSX add on top of {@link ECMASCRIPT_DEFINITIONS}. */
+const TYPESCRIPT_DEFINITIONS = [
+    ...ECMASCRIPT_DEFINITIONS,
+    { nodeType: 'interface_declaration', kind: 'interface', nameField: 'name' },
+    { nodeType: 'type_alias_declaration', kind: 'type_alias', nameField: 'name' },
+    { nodeType: 'enum_declaration', kind: 'enum', nameField: 'name' },
+];
+const ECMASCRIPT_CALL_TYPES = ['call_expression'];
+const ECMASCRIPT_IMPORT_TYPES = ['import_statement'];
+/** Every grammar this package loads, keyed by the seam language label it produces. */
+export const LANGUAGE_TABLE = [
+    {
+        language: 'typescript',
+        extensions: ['.ts', '.mts', '.cts'],
+        wasmFile: 'tree-sitter-typescript.wasm',
+        definitions: TYPESCRIPT_DEFINITIONS,
+        callTypes: ECMASCRIPT_CALL_TYPES,
+        callFunctionField: 'function',
+        importTypes: ECMASCRIPT_IMPORT_TYPES,
+    },
+    {
+        language: 'tsx',
+        extensions: ['.tsx'],
+        wasmFile: 'tree-sitter-tsx.wasm',
+        definitions: TYPESCRIPT_DEFINITIONS,
+        callTypes: ECMASCRIPT_CALL_TYPES,
+        callFunctionField: 'function',
+        importTypes: ECMASCRIPT_IMPORT_TYPES,
+    },
+    {
+        language: 'javascript',
+        extensions: ['.js', '.mjs', '.cjs'],
+        wasmFile: 'tree-sitter-javascript.wasm',
+        definitions: ECMASCRIPT_DEFINITIONS,
+        callTypes: ECMASCRIPT_CALL_TYPES,
+        callFunctionField: 'function',
+        importTypes: ECMASCRIPT_IMPORT_TYPES,
+    },
+    {
+        language: 'jsx',
+        extensions: ['.jsx'],
+        // The plain JavaScript grammar already parses JSX syntax; tree-sitter-wasms ships no separate
+        // "jsx" binary, only distinct typescript/tsx binaries.
+        wasmFile: 'tree-sitter-javascript.wasm',
+        definitions: ECMASCRIPT_DEFINITIONS,
+        callTypes: ECMASCRIPT_CALL_TYPES,
+        callFunctionField: 'function',
+        importTypes: ECMASCRIPT_IMPORT_TYPES,
+    },
+    {
+        language: 'python',
+        extensions: ['.py', '.pyi'],
+        wasmFile: 'tree-sitter-python.wasm',
+        definitions: [
+            { nodeType: 'function_definition', kind: 'function', nameField: 'name' },
+            { nodeType: 'class_definition', kind: 'class', nameField: 'name' },
+        ],
+        callTypes: ['call'],
+        callFunctionField: 'function',
+        importTypes: ['import_statement', 'import_from_statement'],
+    },
+    {
+        language: 'go',
+        extensions: ['.go'],
+        wasmFile: 'tree-sitter-go.wasm',
+        definitions: [
+            { nodeType: 'function_declaration', kind: 'function', nameField: 'name' },
+            { nodeType: 'method_declaration', kind: 'method', nameField: 'name' },
+            { nodeType: 'type_spec', kind: 'type_alias', nameField: 'name' },
+        ],
+        callTypes: ['call_expression'],
+        callFunctionField: 'function',
+        importTypes: ['import_declaration'],
+    },
+];
+/**
+ * The grammar for a file extension, or `undefined` when this package indexes nothing for it.
+ * @param extension - the file extension, including the leading dot, e.g. `.ts`.
+ * @returns the matching language's extraction table entry, or `undefined`.
+ */
+export function languageFor(extension) {
+    return LANGUAGE_TABLE.find(spec => spec.extensions.includes(extension));
+}
+//# sourceMappingURL=languages.js.map

package/lib/resolve.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Workspace-wide, two-pass call resolution over every file's raw extraction.
+ *
+ * Pass 1 collects every definition into a name index. Pass 2 resolves each call site's callee name,
+ * in order: (1) the enclosing file imports that name from a relative specifier resolving to a file
+ * this run indexed — that file's matching declaration wins; (2) otherwise exactly one definition
+ * workspace-wide carries the name — it wins; (3) otherwise the call is recorded in `unresolved` and no
+ * `calls` edge is written. An ambiguous edge is worse than a missing one: the model acts on `callers`
+ * output, so a confidently wrong caller sends it to edit the wrong file, while a missing caller merely
+ * sends it back to text search.
+ *
+ * Rule 3's `unresolved` entries are not one uniform signal. Each carries {@link UnresolvedRef.likelyExternal},
+ * which is true for a member call (no type information behind its receiver) or a name the file itself
+ * imports (a known external origin the specifier just didn't resolve) — both real code that was never a
+ * candidate for a workspace edge, as against a bare, undeclared name, which is the actual gap this
+ * resolver's conservative rule leaves behind.
+ * @module dsh-plugin-codegraph-tree-sitter/resolve
+ */
+import type { FileExtraction } from './extract.ts';
+/** One file's extraction, positioned in the workspace. */
+export interface ExtractedFile {
+    /** Project-relative path, forward-slash separated. */
+    readonly path: string;
+    readonly language: string;
+    readonly size: number;
+    readonly modifiedAt: number;
+    /** SHA-256 of the file's content, hex-encoded. */
+    readonly contentHash: string;
+    /** Total line count, for the synthetic file node's span. */
+    readonly lineCount: number;
+    readonly extraction: FileExtraction;
+}
+/** One resolved graph node — a file or a declaration. */
+export interface GraphNode {
+    readonly id: string;
+    readonly kind: string;
+    readonly name: string;
+    readonly qualifiedName: string;
+    readonly filePath: string;
+    readonly language: string;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly startColumn: number;
+    readonly endColumn: number;
+    readonly isExported: boolean;
+    readonly isAsync: boolean;
+    readonly isStatic: boolean;
+    readonly updatedAt: number;
+}
+/** One resolved graph edge. */
+export interface GraphEdge {
+    readonly source: string;
+    readonly target: string;
+    readonly kind: string;
+    readonly line?: number;
+    readonly col?: number;
+    readonly provenance: string;
+}
+/** One call site whose callee could not be resolved to exactly one declaration. */
+export interface UnresolvedRef {
+    readonly source: string;
+    readonly filePath: string;
+    readonly calleeName: string;
+    readonly line: number;
+    readonly col: number;
+    /**
+     * Whether this site's own shape makes a workspace declaration structurally unlikely, rather than
+     * merely unresolved: a member access (`x.map()`, `expect(v).toBe()`) has no type information behind
+     * its receiver, and a bare name the file itself imports (`import { expect } from 'vitest'`) already
+     * has a known, non-workspace origin even though the specifier never resolved to an indexed file.
+     * Neither is a gap in the graph — both are real code that was never a candidate for a workspace edge
+     * — so a caller sizing "how much did resolution miss" should discount them.
+     */
+    readonly likelyExternal: boolean;
+}
+/** The resolved workspace graph. */
+export interface ResolvedGraph {
+    readonly nodes: GraphNode[];
+    readonly edges: GraphEdge[];
+    readonly unresolved: UnresolvedRef[];
+}
+/**
+ * Resolve every file's raw extraction into the workspace graph.
+ * @param files - every file this run parsed, with its raw extraction.
+ * @param now - epoch milliseconds recorded as every node's `updatedAt`.
+ * @returns the resolved nodes, edges, and unresolved call sites.
+ */
+export declare function resolveWorkspace(files: readonly ExtractedFile[], now: number): ResolvedGraph;
+//# sourceMappingURL=resolve.d.ts.map

package/lib/resolve.js

@@ -0,0 +1,218 @@
+/**
+ * Workspace-wide, two-pass call resolution over every file's raw extraction.
+ *
+ * Pass 1 collects every definition into a name index. Pass 2 resolves each call site's callee name,
+ * in order: (1) the enclosing file imports that name from a relative specifier resolving to a file
+ * this run indexed — that file's matching declaration wins; (2) otherwise exactly one definition
+ * workspace-wide carries the name — it wins; (3) otherwise the call is recorded in `unresolved` and no
+ * `calls` edge is written. An ambiguous edge is worse than a missing one: the model acts on `callers`
+ * output, so a confidently wrong caller sends it to edit the wrong file, while a missing caller merely
+ * sends it back to text search.
+ *
+ * Rule 3's `unresolved` entries are not one uniform signal. Each carries {@link UnresolvedRef.likelyExternal},
+ * which is true for a member call (no type information behind its receiver) or a name the file itself
+ * imports (a known external origin the specifier just didn't resolve) — both real code that was never a
+ * candidate for a workspace edge, as against a bare, undeclared name, which is the actual gap this
+ * resolver's conservative rule leaves behind.
+ * @module dsh-plugin-codegraph-tree-sitter/resolve
+ */
+import { posix } from 'node:path';
+/** File extensions tried, in order, when a relative specifier names no extension of its own. */
+const RESOLUTION_SUFFIXES = {
+    typescript: ['.ts', '.tsx', '.d.ts', '/index.ts', '/index.tsx'],
+    tsx: ['.tsx', '.ts', '/index.tsx', '/index.ts'],
+    javascript: ['.js', '.jsx', '.mjs', '.cjs', '/index.js', '/index.jsx'],
+    jsx: ['.jsx', '.js', '/index.jsx', '/index.js'],
+    python: ['.py', '/__init__.py'],
+};
+/**
+ * Resolve a relative import specifier to a file this run indexed.
+ * @param fromPath - the importing file's project-relative path.
+ * @param specifier - the raw specifier text, e.g. `./bar` or `.bar`.
+ * @param language - the importing file's seam language label.
+ * @param indexed - every project-relative path this run indexed.
+ * @returns the resolved path, or `undefined` when the specifier is not relative, the language has no
+ * relative-import convention this package resolves, or nothing indexed matches.
+ */
+function resolveSpecifier(fromPath, specifier, language, indexed) {
+    const suffixes = RESOLUTION_SUFFIXES[language];
+    if (suffixes === undefined)
+        return undefined;
+    const fromDir = posix.dirname(fromPath);
+    const base = language === 'python' ? pythonRelativeBase(fromDir, specifier) : ecmascriptRelativeBase(fromDir, specifier);
+    if (base === undefined)
+        return undefined;
+    if (indexed.has(base))
+        return base;
+    for (const suffix of suffixes) {
+        const candidate = `${base}${suffix}`;
+        if (indexed.has(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** The ECMAScript relative-import base path, or `undefined` when `specifier` is not relative. */
+function ecmascriptRelativeBase(fromDir, specifier) {
+    if (!specifier.startsWith('.'))
+        return undefined;
+    return posix.normalize(posix.join(fromDir, specifier));
+}
+/** The Python relative-import base path, or `undefined` when `specifier` carries no leading dots. */
+function pythonRelativeBase(fromDir, specifier) {
+    const match = /^(\.+)(.*)$/.exec(specifier);
+    if (match === null)
+        return undefined;
+    const [, dots = '', rest = ''] = match;
+    let dir = fromDir;
+    // One dot means "this package" (no directory change); each additional dot climbs one level, matching
+    // Python's relative-import level convention.
+    for (let level = 1; level < dots.length; level++)
+        dir = posix.dirname(dir);
+    return rest === '' ? dir : posix.normalize(posix.join(dir, rest.replaceAll('.', '/')));
+}
+/**
+ * A map's value for `key`, asserting it is present. Every call site below looks up a key this same
+ * function inserted earlier in the same pass, so absence would mean a bug in that bookkeeping, not
+ * data this function must tolerate.
+ * @param map - the map to read.
+ * @param key - the key, guaranteed present by the caller's own construction.
+ * @returns the value.
+ */
+function mustGet(map, key) {
+    const value = map.get(key);
+    /* v8 ignore next 2 -- every call site inserts `key` earlier in this same resolution pass. */
+    if (value === undefined)
+        throw new Error(`codegraph-tree-sitter: resolve.ts expected a value for ${String(key)}`);
+    return value;
+}
+/** The workspace's global declaration name index: every declaration name to the nodes carrying it. */
+function buildNameIndex(nodesByFile) {
+    const index = new Map();
+    for (const nodes of nodesByFile.values()) {
+        for (const node of nodes) {
+            const existing = index.get(node.name);
+            if (existing === undefined)
+                index.set(node.name, [node]);
+            else
+                existing.push(node);
+        }
+    }
+    return index;
+}
+/** Resolve one file's raw imports against the indexed workspace. */
+function resolveImports(path, language, imports, indexed) {
+    const byLocalName = new Map();
+    const targetFiles = new Set();
+    for (const binding of imports) {
+        const targetFile = resolveSpecifier(path, binding.specifier, language, indexed);
+        if (targetFile === undefined)
+            continue;
+        targetFiles.add(targetFile);
+        if (binding.importedName !== '*')
+            byLocalName.set(binding.localName, { targetFile, importedName: binding.importedName });
+    }
+    return { byLocalName, targetFiles };
+}
+/**
+ * Resolve every file's raw extraction into the workspace graph.
+ * @param files - every file this run parsed, with its raw extraction.
+ * @param now - epoch milliseconds recorded as every node's `updatedAt`.
+ * @returns the resolved nodes, edges, and unresolved call sites.
+ */
+export function resolveWorkspace(files, now) {
+    const indexed = new Set(files.map(file => file.path));
+    const nodesByFile = new Map();
+    const fileNodeId = new Map();
+    const defIdByKey = new Map();
+    const nodes = [];
+    const edges = [];
+    for (const file of files) {
+        const id = `file:${file.path}`;
+        fileNodeId.set(file.path, id);
+        const fileNode = {
+            id,
+            kind: 'file',
+            name: posix.basename(file.path),
+            qualifiedName: file.path,
+            filePath: file.path,
+            language: file.language,
+            startLine: 1,
+            endLine: Math.max(1, file.lineCount),
+            startColumn: 0,
+            endColumn: 0,
+            isExported: false,
+            isAsync: false,
+            isStatic: false,
+            updatedAt: now,
+        };
+        nodes.push(fileNode);
+        const keyToId = new Map();
+        const fileNodes = [];
+        for (const def of file.extraction.definitions) {
+            const qualifiedName = def.container.length === 0
+                ? `${file.path}::${def.name}`
+                : `${file.path}::${[...def.container, def.name].join('.')}`;
+            const nodeId = `${file.path}:${def.startLine}:${def.startColumn}`;
+            keyToId.set(def.key, nodeId);
+            fileNodes.push({
+                id: nodeId,
+                kind: def.kind,
+                name: def.name,
+                qualifiedName,
+                filePath: file.path,
+                language: file.language,
+                startLine: def.startLine,
+                endLine: def.endLine,
+                startColumn: def.startColumn,
+                endColumn: def.endColumn,
+                isExported: def.isExported,
+                isAsync: def.isAsync,
+                isStatic: def.isStatic,
+                updatedAt: now,
+            });
+        }
+        nodes.push(...fileNodes);
+        nodesByFile.set(file.path, fileNodes);
+        defIdByKey.set(file.path, keyToId);
+        for (const def of file.extraction.definitions) {
+            const source = def.parentKey === null ? id : mustGet(keyToId, def.parentKey);
+            edges.push({ source, target: mustGet(keyToId, def.key), kind: 'contains', provenance: 'tree-sitter' });
+        }
+    }
+    const nameIndex = buildNameIndex(nodesByFile);
+    const unresolved = [];
+    for (const file of files) {
+        const bindings = resolveImports(file.path, file.language, file.extraction.imports, indexed);
+        for (const target of bindings.targetFiles) {
+            edges.push({ source: mustGet(fileNodeId, file.path), target: mustGet(fileNodeId, target), kind: 'imports', provenance: 'tree-sitter' });
+        }
+        const keyToId = mustGet(defIdByKey, file.path);
+        const importedLocalNames = new Set(file.extraction.imports.map(binding => binding.localName));
+        for (const call of file.extraction.calls) {
+            const callerId = call.callerKey === null ? mustGet(fileNodeId, file.path) : mustGet(keyToId, call.callerKey);
+            const resolved = resolveCall(call.calleeName, bindings, nodesByFile, nameIndex);
+            if (resolved === undefined) {
+                const likelyExternal = call.isMemberCall || importedLocalNames.has(call.calleeName);
+                unresolved.push({ source: callerId, filePath: file.path, calleeName: call.calleeName, line: call.line, col: call.column, likelyExternal });
+                continue;
+            }
+            edges.push({ source: callerId, target: resolved, kind: 'calls', line: call.line, col: call.column, provenance: 'tree-sitter' });
+        }
+    }
+    return { nodes, edges, unresolved };
+}
+/** Resolve one call's callee name to exactly one declaration, or `undefined` per rule 3. */
+function resolveCall(calleeName, bindings, nodesByFile, nameIndex) {
+    const bound = bindings.byLocalName.get(calleeName);
+    if (bound !== undefined) {
+        const targetNodes = mustGet(nodesByFile, bound.targetFile);
+        const candidates = bound.importedName === 'default'
+            ? targetNodes.filter(node => node.isExported)
+            : targetNodes.filter(node => node.name === bound.importedName);
+        if (candidates.length === 1)
+            return candidates[0]?.id;
+    }
+    const workspaceWide = nameIndex.get(calleeName) ?? [];
+    return workspaceWide.length === 1 ? workspaceWide[0]?.id : undefined;
+}
+//# sourceMappingURL=resolve.js.map

package/lib/schema.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Schema-v4 database writer: create the on-disk tables `dsh-plugin-codegraph-sqlite` reads —
+ * verbatim in structure, so the store and the external `codegraph` CLI stay able to open what this
+ * package writes — and insert one indexing run's resolved graph.
+ *
+ * Writing replaces whatever was at the path: an indexing run is a full rebuild, not an incremental
+ * update. The new graph is built on a same-directory temporary file and `rename`d into place, so a
+ * reader opening `databasePath` at any point either sees the complete previous graph or the complete
+ * new one — never a window where the file exists with a fresh, empty schema and no rows yet, which a
+ * naive "delete then recreate" leaves open between `CREATE TABLE` and the first `COMMIT`.
+ * @module dsh-plugin-codegraph-tree-sitter/schema
+ */
+import type { ExtractedFile, GraphEdge, GraphNode, UnresolvedRef } from './resolve.ts';
+/** The schema version this package writes, matching the format `dsh-codegraph-sqlite` reads. */
+export declare const SCHEMA_VERSION = 4;
+/** One indexing run's complete output, ready to write. */
+export interface WriteInput {
+    readonly files: readonly ExtractedFile[];
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly GraphEdge[];
+    readonly unresolved: readonly UnresolvedRef[];
+    readonly indexedAt: number;
+}
+/**
+ * Replace the graph at `databasePath` with one indexing run's output.
+ *
+ * The full build happens on a temporary file beside `databasePath`; only a successful build is
+ * `rename`d over the real path, atomically on the same filesystem. A reader with a connection already
+ * open on the old file keeps reading it (POSIX unlink semantics) until it reopens — that half of
+ * freshness is the sqlite store's responsibility, not this writer's.
+ * @param databasePath - absolute path of the `.codegraph/codegraph.db` file to (re)create.
+ * @param input - the run's resolved graph and per-file metadata.
+ */
+export declare function writeGraph(databasePath: string, input: WriteInput): Promise<void>;
+//# sourceMappingURL=schema.d.ts.map

package/lib/schema.js

@@ -0,0 +1,126 @@
+/**
+ * Schema-v4 database writer: create the on-disk tables `dsh-plugin-codegraph-sqlite` reads —
+ * verbatim in structure, so the store and the external `codegraph` CLI stay able to open what this
+ * package writes — and insert one indexing run's resolved graph.
+ *
+ * Writing replaces whatever was at the path: an indexing run is a full rebuild, not an incremental
+ * update. The new graph is built on a same-directory temporary file and `rename`d into place, so a
+ * reader opening `databasePath` at any point either sees the complete previous graph or the complete
+ * new one — never a window where the file exists with a fresh, empty schema and no rows yet, which a
+ * naive "delete then recreate" leaves open between `CREATE TABLE` and the first `COMMIT`.
+ * @module dsh-plugin-codegraph-tree-sitter/schema
+ */
+import { mkdir, rename, rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { randomUUID } from 'node:crypto';
+/** The schema version this package writes, matching the format `dsh-codegraph-sqlite` reads. */
+export const SCHEMA_VERSION = 4;
+/**
+ * DDL for every table this package writes. Structurally identical to the subset
+ * `dsh-codegraph-sqlite` reads, plus `unresolved_refs`, which no store reads today — it exists so an
+ * indexing run's conservative gaps are inspectable on disk, not only summarized in the run's report.
+ */
+const SCHEMA = `
+CREATE TABLE schema_versions (version INTEGER PRIMARY KEY, applied_at INTEGER NOT NULL, description TEXT);
+CREATE TABLE nodes (
+  id TEXT PRIMARY KEY, kind TEXT NOT NULL, name TEXT NOT NULL, qualified_name TEXT NOT NULL,
+  file_path TEXT NOT NULL, language TEXT NOT NULL, start_line INTEGER NOT NULL, end_line INTEGER NOT NULL,
+  start_column INTEGER NOT NULL, end_column INTEGER NOT NULL, docstring TEXT, signature TEXT,
+  visibility TEXT, is_exported INTEGER DEFAULT 0, is_async INTEGER DEFAULT 0, is_static INTEGER DEFAULT 0,
+  is_abstract INTEGER DEFAULT 0, decorators TEXT, type_parameters TEXT, updated_at INTEGER NOT NULL);
+CREATE TABLE edges (
+  id INTEGER PRIMARY KEY AUTOINCREMENT, source TEXT NOT NULL, target TEXT NOT NULL, kind TEXT NOT NULL,
+  metadata TEXT, line INTEGER, col INTEGER, provenance TEXT DEFAULT NULL);
+CREATE TABLE files (
+  path TEXT PRIMARY KEY, content_hash TEXT NOT NULL, language TEXT NOT NULL, size INTEGER NOT NULL,
+  modified_at INTEGER NOT NULL, indexed_at INTEGER NOT NULL, node_count INTEGER DEFAULT 0, errors TEXT);
+CREATE VIRTUAL TABLE nodes_fts USING fts5(
+  id, name, qualified_name, docstring, signature, content='nodes', content_rowid='rowid');
+CREATE TRIGGER nodes_ai AFTER INSERT ON nodes BEGIN
+  INSERT INTO nodes_fts(rowid, id, name, qualified_name, docstring, signature)
+  VALUES (NEW.rowid, NEW.id, NEW.name, NEW.qualified_name, NEW.docstring, NEW.signature);
+END;
+CREATE TABLE unresolved_refs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT, source TEXT NOT NULL, file_path TEXT NOT NULL,
+  callee_name TEXT NOT NULL, line INTEGER, col INTEGER);
+`;
+/** Remove a database file and its WAL/SHM sidecars, tolerating any of the three being absent. */
+async function removeGraphFiles(path) {
+    await rm(path, { force: true });
+    await rm(`${path}-wal`, { force: true });
+    await rm(`${path}-shm`, { force: true });
+}
+/**
+ * Replace the graph at `databasePath` with one indexing run's output.
+ *
+ * The full build happens on a temporary file beside `databasePath`; only a successful build is
+ * `rename`d over the real path, atomically on the same filesystem. A reader with a connection already
+ * open on the old file keeps reading it (POSIX unlink semantics) until it reopens — that half of
+ * freshness is the sqlite store's responsibility, not this writer's.
+ * @param databasePath - absolute path of the `.codegraph/codegraph.db` file to (re)create.
+ * @param input - the run's resolved graph and per-file metadata.
+ */
+export async function writeGraph(databasePath, input) {
+    await mkdir(dirname(databasePath), { recursive: true });
+    const tempPath = `${databasePath}.tmp-${process.pid}-${randomUUID()}`;
+    // Defensive: a previous run that crashed mid-write may have left this exact temp name behind.
+    await removeGraphFiles(tempPath);
+    try {
+        const db = new DatabaseSync(tempPath);
+        try {
+            db.exec('BEGIN');
+            db.exec(SCHEMA);
+            db.prepare('INSERT INTO schema_versions (version, applied_at, description) VALUES (?, ?, ?)')
+                .run(SCHEMA_VERSION, input.indexedAt, 'dsh-codegraph-tree-sitter');
+            const insertNode = db.prepare(`INSERT INTO nodes
+        (id, kind, name, qualified_name, file_path, language, start_line, end_line, start_column,
+         end_column, is_exported, is_async, is_static, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+            for (const node of input.nodes) {
+                insertNode.run(node.id, node.kind, node.name, node.qualifiedName, node.filePath, node.language, node.startLine, node.endLine, node.startColumn, node.endColumn, node.isExported ? 1 : 0, node.isAsync ? 1 : 0, node.isStatic ? 1 : 0, node.updatedAt);
+            }
+            const insertEdge = db.prepare('INSERT INTO edges (source, target, kind, line, col, provenance) VALUES (?, ?, ?, ?, ?, ?)');
+            for (const edge of input.edges) {
+                insertEdge.run(edge.source, edge.target, edge.kind, edge.line ?? null, edge.col ?? null, edge.provenance);
+            }
+            const insertFile = db.prepare(`INSERT INTO files
+        (path, content_hash, language, size, modified_at, indexed_at, node_count)
+        VALUES (?, ?, ?, ?, ?, ?, ?)`);
+            const nodeCountByFile = new Map();
+            for (const node of input.nodes) {
+                if (node.kind === 'file')
+                    continue;
+                nodeCountByFile.set(node.filePath, (nodeCountByFile.get(node.filePath) ?? 0) + 1);
+            }
+            for (const file of input.files) {
+                insertFile.run(file.path, file.contentHash, file.language, file.size, file.modifiedAt, input.indexedAt, nodeCountByFile.get(file.path) ?? 0);
+            }
+            const insertUnresolved = db.prepare('INSERT INTO unresolved_refs (source, file_path, callee_name, line, col) VALUES (?, ?, ?, ?, ?)');
+            for (const ref of input.unresolved) {
+                insertUnresolved.run(ref.source, ref.filePath, ref.calleeName, ref.line, ref.col);
+            }
+            db.exec('COMMIT');
+        }
+        catch (cause) {
+            db.exec('ROLLBACK');
+            throw cause;
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (cause) {
+        await removeGraphFiles(tempPath);
+        throw cause;
+    }
+    // The old file's sidecars, if any, describe the graph being replaced, not the new one; clear them
+    // before the rename so the new file never inherits a stale WAL/SHM pair.
+    await rm(`${databasePath}-wal`, { force: true });
+    await rm(`${databasePath}-shm`, { force: true });
+    await rename(tempPath, databasePath);
+    // rename() only moves the main file; the temp name's own sidecars (should the driver have left any)
+    // never travel with it and would otherwise linger under the temp name forever.
+    await removeGraphFiles(tempPath);
+}
+//# sourceMappingURL=schema.js.map

package/lib/walk.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Workspace directory walk: find every file this package can extract from, parse it, and hand back
+ * one {@link ExtractedFile} per file that was actually indexed.
+ *
+ * The walk is deliberately simple: `exclude` entries name directory segments to never descend into
+ * (not wildcard globs — the default set needs none), and every bound (`maxFileBytes`, `maxFiles`) is
+ * a config field the deployment can retune rather than a constant, per the same-name entries this
+ * package's `Config` exposes.
+ * @module dsh-plugin-codegraph-tree-sitter/walk
+ */
+import type { GitignoreRule } from './gitignore.ts';
+import type { ExtractedFile } from './resolve.ts';
+/**
+ * Whether one directory entry is excluded from both the index and (for `watcher.ts`) the watch tree —
+ * the single definition both consult, so "what the index covers" and "what gets watched" can never
+ * drift apart.
+ * @param name - the entry's own name (not a path), matched against `excluded` verbatim.
+ * @param relativePath - the entry's project-relative path, matched against the `.gitignore` rules.
+ * @param isDirectory - whether the entry is a directory, for `.gitignore`'s directory-only rules.
+ * @param excluded - directory/file segment names never descended into.
+ * @param gitignoreRules - the project's parsed `.gitignore`, or empty when not respected.
+ */
+export declare function isExcluded(name: string, relativePath: string, isDirectory: boolean, excluded: ReadonlySet<string>, gitignoreRules: readonly GitignoreRule[]): boolean;
+/** The walk's tunable bounds, mirroring this package's `Config`. */
+export interface WalkConfig {
+    /** Directory segment names never descended into. */
+    readonly exclude: readonly string[];
+    /** Files larger than this are skipped and counted, never parsed. */
+    readonly maxFileBytes: number;
+    /** The walk stops discovering new files once this many have been found. */
+    readonly maxFiles: number;
+    /** Files parsed concurrently. */
+    readonly concurrency: number;
+    /** Restrict extraction to these seam language labels when set; every loaded grammar otherwise. */
+    readonly languages?: readonly string[];
+    /**
+     * Also exclude whatever the project root's `.gitignore` names, unioned with `exclude`. A project
+     * that compiles to a gitignored directory (`lib`, `dist`, ...) would otherwise hand the same symbol
+     * to the resolver twice — once from source, once from the build output — and "the one unique
+     * workspace-wide name wins" call resolution would pick between them arbitrarily.
+     */
+    readonly respectGitignore: boolean;
+}
+/** What the walk produced. */
+export interface WalkResult {
+    readonly files: ExtractedFile[];
+    readonly filesSkipped: number;
+}
+/**
+ * Walk `projectRoot` and parse every candidate file it finds.
+ * @param projectRoot - absolute path of the workspace to index.
+ * @param config - the walk's bounds.
+ * @param signal - aborts the walk.
+ * @returns the parsed files and how many candidates were skipped (over size, or past `maxFiles`).
+ */
+export declare function walkAndExtract(projectRoot: string, config: WalkConfig, signal?: AbortSignal): Promise<WalkResult>;
+//# sourceMappingURL=walk.d.ts.map