@crouton-kit/tsym 0.1.0

package/dist/core/declarations.js

@@ -0,0 +1,153 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { query } from '../store/query.js';
+export class DeclarationError extends Error {
+    code;
+    candidates;
+    constructor(code, message, candidates = []) {
+        super(message);
+        this.code = code;
+        this.candidates = candidates;
+    }
+}
+export class DeclarationResolutionErrors extends Error {
+    errors;
+    constructor(errors) {
+        super(errors.map((error) => error.message).join('\n'));
+        this.errors = errors;
+    }
+}
+/** Resolves every declaration identity from the committed index. */
+export class DeclarationResolver {
+    root;
+    source;
+    storeFor;
+    constructor(root, source, storeFor) {
+        this.root = root;
+        this.source = source;
+        this.storeFor = storeFor;
+    }
+    async resolve(input) {
+        const address = parseAddress(input);
+        return address ? this.resolveAddress(address) : this.resolveName(input);
+    }
+    async resolveAll(inputs) {
+        const records = [];
+        const errors = [];
+        for (const input of inputs) {
+            try {
+                records.push(await this.resolve(input));
+            }
+            catch (error) {
+                if (error instanceof DeclarationError)
+                    errors.push(error);
+                else
+                    throw error;
+            }
+        }
+        if (errors.length > 0)
+            throw new DeclarationResolutionErrors(errors);
+        return records;
+    }
+    async resolveAddress(address) {
+        const file = path.resolve(this.root, address.path);
+        if (!existsSync(file))
+            throw new DeclarationError('no-such-path', `${address.path} does not exist`);
+        if (address.line === 0 || address.col === 0) {
+            if (address.line !== 0 || address.col !== 0)
+                throw new DeclarationError('invalid-address', `${inputAddress(address)} mixes zero module coordinates with a source position`);
+            const module = this.rows(`MATCH (d:Declaration) WHERE d.file = $file AND d.line = 0 AND d.col = 0 RETURN ${columns()}`, { file: relative(this.root, file) });
+            if (module.length === 0)
+                throw this.notInProgram(address.path);
+            return this.record(module[0]);
+        }
+        this.validatePosition(address, file);
+        const relativeFile = relative(this.root, file);
+        const source = this.source.read(file);
+        const position = offsetAt(source, address.line, address.col);
+        const declarations = this.rows(`MATCH (d:Declaration) WHERE d.file = $file AND d.line = $line RETURN ${columns()}`, { file: relativeFile, line: address.line })
+            .filter((row) => {
+            const nameSpan = this.source.declarationNameSpanAt(file, number(row, 'line'), number(row, 'col'));
+            return nameSpan !== null && nameSpan.start <= position && position < nameSpan.end;
+        });
+        const references = declarations.length === 0
+            ? this.rows(`MATCH (owner:Declaration)-[r:REFERENCES]->(d:Declaration) WHERE owner.file = $file AND r.line = $line AND r.col <= $col RETURN ${columns()}, r.col AS referenceCol`, { file: relativeFile, line: address.line, col: address.col })
+                .filter((row) => address.col < number(row, 'referenceCol') + identifierLengthAt(source, address.line, number(row, 'referenceCol')))
+            : [];
+        const enclosing = declarations.length === 0 && references.length === 0
+            ? this.rows(`MATCH (d:Declaration) WHERE d.file = $file AND d.line > 0 AND d.endLine - d.lines + 1 <= $line AND $line <= d.endLine RETURN ${columns()}`, { file: relativeFile, line: address.line })
+                .flatMap((row) => {
+                const span = this.source.declarationSpanAt(file, number(row, 'line'), number(row, 'col'));
+                return span && span.start <= position && position < span.end ? [{ row, span }] : [];
+            })
+                .sort((left, right) => left.span.end - left.span.start - (right.span.end - right.span.start) || right.span.start - left.span.start)
+                .slice(0, 1)
+                .map(({ row }) => row)
+            : [];
+        const records = unique((declarations.length > 0 ? declarations : references.length > 0 ? references : enclosing).map((row) => this.record(row)));
+        if (records.length === 0) {
+            if (this.rows('MATCH (d:Declaration) WHERE d.file = $file AND d.line = 0 RETURN d.key AS key', { file: relativeFile }).length === 0)
+                throw this.notInProgram(address.path);
+            throw new DeclarationError('unresolvable-symbol', this.unresolvableAddress(address, relativeFile));
+        }
+        if (records.length > 1)
+            throw new DeclarationError('ambiguous-symbol', `${inputAddress(address)} resolves to several declarations`, records.map((item) => item.address));
+        return records[0];
+    }
+    async resolveName(name) {
+        const qualified = name.includes('.');
+        const declarations = this.rows(`MATCH (d:Declaration) WHERE d.${qualified ? 'qname' : 'name'} = $name RETURN ${columns()}`, { name })
+            .filter((row) => text(row, 'name') !== '<module>' && (qualified || text(row, 'container').endsWith('#<module>')));
+        const aliases = qualified ? [] : this.rows(`MATCH (:Declaration)-[e:EXPORTS]->(d:Declaration) WHERE e.name = $name RETURN ${columns()}`, { name })
+            .filter((row) => text(row, 'container').endsWith('#<module>'));
+        const normalized = unique([...declarations, ...aliases].map((row) => this.record(row)));
+        if (normalized.length === 0)
+            throw new DeclarationError('unresolvable-symbol', `No declaration matches ${name}`);
+        if (normalized.length > 1)
+            throw new DeclarationError('ambiguous-symbol', `${name} is ambiguous`, normalized.map((item) => item.address));
+        return normalized[0];
+    }
+    fromSyntax(file, declaration) {
+        const location = declaration.kind === 'module' ? { path: relative(this.root, file), line: 0, col: 0 } : addressAt(this.source.read(file), declaration.nameSpan.start, relative(this.root, file));
+        return { address: inputAddress(location), location, file, kind: declaration.kind, name: declaration.name, qualifiedName: declaration.containerName ? `${declaration.containerName}.${declaration.name}` : declaration.name, nameSpan: declaration.nameSpan, span: declaration.span };
+    }
+    rows(cypher, parameters = {}) {
+        const store = this.storeFor();
+        if (!store)
+            throw new DeclarationError('not-in-program', 'The TypeScript index is not available yet.');
+        return query(store, cypher, parameters);
+    }
+    record(row) {
+        const location = { path: text(row, 'file'), line: number(row, 'line'), col: number(row, 'col') };
+        const file = path.join(this.root, location.path);
+        const source = this.source.read(file);
+        const name = location.line === 0 ? path.basename(file) : text(row, 'name');
+        const nameStart = location.line === 0 ? 0 : offsetAt(source, location.line, location.col);
+        const startLine = location.line === 0 ? 1 : number(row, 'endLine') - number(row, 'lines') + 1;
+        const start = location.line === 0 ? 0 : offsetAt(source, startLine, 1);
+        const end = location.line === 0 ? source.length : offsetAt(source, number(row, 'endLine') + 1, 1);
+        return { address: inputAddress(location), location, file, kind: text(row, 'kind'), name, qualifiedName: location.line === 0 ? name : text(row, 'qname'), nameSpan: { start: nameStart, end: nameStart + name.length }, span: { start, end } };
+    }
+    unresolvableAddress(address, file) {
+        const topLevel = this.rows('MATCH (d:Declaration) WHERE d.file = $file AND d.line > 0 AND d.container = $module RETURN d.at AS at, d.kind AS kind, d.qname AS qname ORDER BY d.line, d.col', { file, module: `${file}#<module>` });
+        const shown = topLevel.slice(0, 20);
+        const tail = topLevel.length > shown.length ? `\n+${topLevel.length - shown.length} more, run outline ${file}` : '';
+        return `${inputAddress(address)} does not resolve to a declaration.\nModule: ${file}:0:0\nTop-level declarations:\n${shown.map((row) => `${text(row, 'at')}  ${text(row, 'kind')}  ${text(row, 'qname')}`).join('\n')}${tail}`;
+    }
+    validatePosition(address, file) {
+        const lines = this.source.read(file).split('\n');
+        if (address.line < 1 || address.col < 1 || address.line > lines.length || address.col > lines[address.line - 1].length + 1)
+            throw new DeclarationError('invalid-address', `${inputAddress(address)} is outside the source text`);
+    }
+    notInProgram(file) { return new DeclarationError('not-in-program', `${file} exists but is not part of a TypeScript project under ${this.root}`); }
+}
+function parseAddress(value) { const match = /^(.*):(\d+):(\d+)$/.exec(value); return match ? { path: match[1], line: Number(match[2]), col: Number(match[3]) } : null; }
+function inputAddress(address) { return `${address.path}:${address.line}:${address.col}`; }
+function relative(root, file) { return path.relative(root, file).split(path.sep).join('/'); }
+function offsetAt(source, line, col) { const lines = source.split('\n'); return lines.slice(0, Math.max(0, line - 1)).reduce((offset, value) => offset + value.length + 1, 0) + Math.max(0, col - 1); }
+function identifierLengthAt(source, line, col) { return /^(?:[$_\p{ID_Start}]|\\u[0-9A-Fa-f]{4}|\\u\{[0-9A-Fa-f]+\})(?:[$_\p{ID_Continue}\u200C\u200D]|\\u[0-9A-Fa-f]{4}|\\u\{[0-9A-Fa-f]+\})*/u.exec(source.slice(offsetAt(source, line, col)))?.[0].length ?? 0; }
+function addressAt(source, offset, file) { const before = source.slice(0, offset); return { path: file, line: before.split('\n').length, col: before.length - before.lastIndexOf('\n') }; }
+function text(row, key) { return String(row[key] ?? ''); }
+function number(row, key) { return Number(row[key]); }
+function unique(records) { return [...new Map(records.map((record) => [record.address, record])).values()]; }
+function columns() { return 'd.at AS at, d.name AS name, d.qname AS qname, d.kind AS kind, d.file AS file, d.line AS line, d.col AS col, d.endLine AS endLine, d.lines AS lines, d.container AS container'; }

package/dist/core/receipt.d.ts

@@ -0,0 +1,7 @@
+export interface PathFilters {
+    /** Restrict results to paths matching any glob. */
+    in?: string | readonly string[];
+    /** Remove results whose paths match any glob. */
+    exclude?: string | readonly string[];
+}
+export declare function matchesPathFilters(path: string, filters: PathFilters): boolean;

package/dist/core/receipt.js

@@ -0,0 +1,9 @@
+import { matchesGlob } from './workspace.js';
+export function matchesPathFilters(path, filters) {
+    const included = globs(filters.in);
+    const excluded = globs(filters.exclude);
+    return (included.length === 0 || included.some((glob) => matchesGlob(path, glob))) && !excluded.some((glob) => matchesGlob(path, glob));
+}
+function globs(value) {
+    return value === undefined ? [] : typeof value === 'string' ? [value] : value;
+}

package/dist/core/search.d.ts

@@ -0,0 +1,29 @@
+import type { PathFilters } from './receipt.js';
+import { type Workspace } from './workspace.js';
+export interface SearchOptions extends PathFilters {
+    limit?: number | null;
+}
+export interface SearchMatch {
+    path: string;
+    start: {
+        line: number;
+        col: number;
+    };
+    end: {
+        line: number;
+        col: number;
+    };
+    text: string;
+}
+export interface SearchResult {
+    count: number;
+    items: SearchMatch[];
+    receipt: {
+        elapsed_ms: number;
+        excluded: number;
+        truncated: boolean;
+        limit: number | null;
+    };
+}
+/** Structural syntax search that stays outside the TypeScript resident. */
+export declare function search(ws: Workspace, pattern: string, opts?: SearchOptions): Promise<SearchResult>;

package/dist/core/search.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import { findInFiles } from '@ast-grep/napi';
+import { langFor, matchesGlob } from './workspace.js';
+/** Structural syntax search that stays outside the TypeScript resident. */
+export async function search(ws, pattern, opts = {}) {
+    const startedAt = performance.now();
+    const byLang = new Map();
+    for (const file of ws.files()) {
+        const lang = langFor(file);
+        if (lang !== null)
+            (byLang.get(lang) ?? byLang.set(lang, []).get(lang)).push(path.join(ws.root, file));
+    }
+    const matches = [];
+    for (const [lang, paths] of byLang) {
+        let seen = 0;
+        const count = await findInFiles(lang, { paths, matcher: { rule: { pattern } } }, (error, nodes) => {
+            seen++;
+            if (error)
+                return;
+            for (const node of nodes) {
+                const range = node.range();
+                matches.push({
+                    path: ws.rel(node.getRoot().filename()),
+                    start: { line: range.start.line + 1, col: range.start.column + 1 },
+                    end: { line: range.end.line + 1, col: range.end.column + 1 },
+                    text: node.text().split('\n', 1)[0]?.trim() ?? '',
+                });
+            }
+        });
+        await drained(() => seen >= count);
+    }
+    matches.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : a.start.line - b.start.line || a.start.col - b.start.col));
+    const filtered = matches.filter((match) => matchesPathFilters(match.path, opts));
+    const limit = opts.limit ?? null;
+    const truncated = limit !== null && filtered.length > limit;
+    return { count: filtered.length, items: truncated ? filtered.slice(0, limit) : filtered, receipt: { elapsed_ms: Math.round(performance.now() - startedAt), excluded: matches.length - filtered.length, truncated, limit } };
+}
+function matchesPathFilters(file, filters) {
+    const included = values(filters.in);
+    const excluded = values(filters.exclude);
+    return (included.length === 0 || included.some((glob) => matchesGlob(file, glob))) && !excluded.some((glob) => matchesGlob(file, glob));
+}
+function values(value) { return value === undefined ? [] : typeof value === 'string' ? [value] : value; }
+async function drained(done) {
+    while (!done())
+        await new Promise((resolve) => setImmediate(resolve));
+}

package/dist/core/source.d.ts

@@ -0,0 +1,32 @@
+import type { ProjectRegistry } from '../server/projects.js';
+export interface SourceSpan {
+    start: number;
+    end: number;
+}
+export interface SyntaxDeclaration {
+    name: string;
+    kind: string;
+    nameSpan: SourceSpan;
+    span: SourceSpan;
+    containerName?: string;
+}
+/** Syntax-only reader backed by the resident TypeScript 7 snapshot. */
+export declare class SourceReader {
+    private readonly projects;
+    constructor(projects: Pick<ProjectRegistry, 'refreshFile' | 'sourceFile' | 'anySourceFile'>);
+    read(file: string): string;
+    declarationAt(file: string, line: number, offset: number): SyntaxDeclaration | null;
+    declarationNameSpanAt(file: string, line: number, offset: number): SourceSpan | null;
+    declarationSpanAt(file: string, line: number, offset: number): SourceSpan | null;
+    declarationForSpan(file: string, start: {
+        line: number;
+        offset: number;
+    }): SyntaxDeclaration | null;
+    ownerForSpan(file: string, start: {
+        line: number;
+        offset: number;
+    }): SyntaxDeclaration;
+    module(file: string): SyntaxDeclaration;
+    private parse;
+    private tokenAt;
+}

package/dist/core/source.js

@@ -0,0 +1,96 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import * as ts from '../ts7/ast.js';
+/** Syntax-only reader backed by the resident TypeScript 7 snapshot. */
+export class SourceReader {
+    projects;
+    constructor(projects) { this.projects = projects; }
+    read(file) { return readFileSync(file, 'utf8'); }
+    declarationAt(file, line, offset) {
+        const source = this.parse(file);
+        return declarationAt(this.tokenAt(source, source.getPositionOfLineAndCharacter(line - 1, offset - 1)), source);
+    }
+    declarationNameSpanAt(file, line, offset) {
+        const source = this.parse(file);
+        const declaration = indexedDeclarationFor(this.tokenAt(source, source.getPositionOfLineAndCharacter(line - 1, offset - 1)));
+        const name = declaration && declaration.name;
+        return name ? { start: name.getStart(source), end: name.getEnd() } : null;
+    }
+    declarationSpanAt(file, line, offset) {
+        const source = this.parse(file);
+        const declaration = indexedDeclarationFor(this.tokenAt(source, source.getPositionOfLineAndCharacter(line - 1, offset - 1)));
+        return declaration ? { start: declaration.getStart(source), end: declaration.getEnd() } : null;
+    }
+    declarationForSpan(file, start) { return this.declarationAt(file, start.line, start.offset); }
+    ownerForSpan(file, start) {
+        const source = this.parse(file);
+        return ownerAt(this.tokenAt(source, source.getPositionOfLineAndCharacter(start.line - 1, start.offset - 1)), source) ?? moduleFor(source);
+    }
+    module(file) { return moduleFor(this.parse(file)); }
+    parse(file) {
+        this.projects.refreshFile(file);
+        const source = this.projects.sourceFile(file) ?? this.projects.anySourceFile(file);
+        if (!source)
+            throw new Error(`${file} is not loaded in the TypeScript 7 snapshot.`);
+        return source;
+    }
+    tokenAt(source, position) {
+        let current = source;
+        for (;;) {
+            const child = current.forEachChild((candidate) => position >= candidate.getFullStart() && position < candidate.getEnd() ? candidate : undefined);
+            if (!child)
+                return current;
+            current = child;
+        }
+    }
+}
+function declarationAt(node, source) {
+    let current = node;
+    while (current) {
+        const declaration = declarationFor(current);
+        if (declaration)
+            return describe(declaration, source);
+        current = current.parent;
+    }
+    return null;
+}
+function ownerAt(node, source) {
+    let current = node;
+    while (current) {
+        const declaration = declarationFor(current);
+        if (declaration && namedCallable(declaration))
+            return describe(declaration, source);
+        current = current.parent;
+    }
+    return null;
+}
+function indexedDeclarationFor(node) {
+    let current = node;
+    while (current) {
+        if (ts.isVariableDeclaration(current) || ts.isFunctionDeclaration(current) || ts.isFunctionExpression(current) || ts.isClassDeclaration(current) || ts.isClassExpression(current) || ts.isInterfaceDeclaration(current) || ts.isTypeAliasDeclaration(current) || ts.isEnumDeclaration(current) || ts.isModuleDeclaration(current) || ts.isMethodDeclaration(current) || current.kind === ts.SyntaxKind.MethodSignature || ts.isPropertyDeclaration(current) || current.kind === ts.SyntaxKind.PropertySignature || ts.isGetAccessorDeclaration(current) || ts.isSetAccessorDeclaration(current) || ts.isConstructorDeclaration(current) || ts.isParameterDeclaration(current) || ts.isBindingElement(current) || ts.isImportSpecifier(current) || ts.isExportSpecifier(current) || ts.isExportAssignment(current) || ts.isArrowFunction(current))
+            return current;
+        current = current.parent;
+    }
+    return null;
+}
+function declarationFor(node) {
+    if (ts.isVariableDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isEnumDeclaration(node) || ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node) || ts.isParameterDeclaration(node) || ts.isImportSpecifier(node) || ts.isExportSpecifier(node))
+        return node;
+    return null;
+}
+function namedCallable(node) {
+    if (ts.isVariableDeclaration(node) || ts.isPropertyDeclaration(node))
+        return !!node.name && !!node.initializer && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer));
+    return (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isMethodDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node)) && !!node.name;
+}
+function describe(node, source) {
+    const name = node.name;
+    if (!name || !ts.isIdentifier(name) && !ts.isPrivateIdentifier(name) && !ts.isStringLiteral(name))
+        return null;
+    const parent = node.parent;
+    const container = parent && (ts.isClassDeclaration(parent) || ts.isInterfaceDeclaration(parent) || ts.isEnumDeclaration(parent)) && parent.name ? parent.name.text : undefined;
+    return { name: name.text, kind: ts.SyntaxKind[node.kind] ?? 'unknown', nameSpan: { start: name.getStart(source), end: name.getEnd() }, span: { start: node.getStart(source), end: node.getEnd() }, containerName: container };
+}
+function moduleFor(source) {
+    return { name: path.basename(source.fileName), kind: 'module', nameSpan: { start: 0, end: 0 }, span: { start: 0, end: source.getEnd() } };
+}

package/dist/core/workspace.d.ts

@@ -0,0 +1,28 @@
+import { Lang } from '@ast-grep/napi';
+/** refs/callers/impact were asked for a file with no TypeScript project around it. */
+export declare class NoProject extends Error {
+}
+export declare class Workspace {
+    readonly root: string;
+    /** The tsconfig.json at the root, when the root was chosen because of one. */
+    readonly tsconfig: string | null;
+    /** Which marker chose the root; `none` means `dir` itself was used because nothing above it is a project. */
+    readonly marker: 'tsconfig.json' | 'package.json' | '.git' | 'none';
+    private fileList;
+    constructor(root: string, tsconfig: string | null, marker: Workspace['marker']);
+    /** Path relative to the root, `/`-separated. */
+    rel(abs: string): string;
+    /**
+     * Source files (TS/JS family) in the workspace, relative to the root.
+     * Uses `git ls-files` (tracked + untracked, honoring .gitignore) when the root is in a git repo,
+     * else a directory walk that skips node_modules/dist/build/.git.
+     */
+    files(globs?: string | readonly string[]): string[];
+}
+/**
+ * Resolve the workspace containing `dir`: the nearest ancestor holding a tsconfig.json,
+ * else package.json, else a .git directory, else `dir` itself.
+ */
+export declare function openWorkspace(dir?: string): Workspace;
+export declare function langFor(file: string): Lang | null;
+export declare function matchesGlob(file: string, glob: string): boolean;

package/dist/core/workspace.js

@@ -0,0 +1,137 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { Lang } from '@ast-grep/napi';
+const SOURCE_EXT = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs']);
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git', 'coverage']);
+/** refs/callers/impact were asked for a file with no TypeScript project around it. */
+export class NoProject extends Error {
+}
+export class Workspace {
+    root;
+    /** The tsconfig.json at the root, when the root was chosen because of one. */
+    tsconfig;
+    /** Which marker chose the root; `none` means `dir` itself was used because nothing above it is a project. */
+    marker;
+    fileList = null;
+    constructor(root, tsconfig, marker) {
+        this.root = root;
+        this.tsconfig = tsconfig;
+        this.marker = marker;
+    }
+    /** Path relative to the root, `/`-separated. */
+    rel(abs) {
+        return path.relative(this.root, abs).split(path.sep).join('/');
+    }
+    /**
+     * Source files (TS/JS family) in the workspace, relative to the root.
+     * Uses `git ls-files` (tracked + untracked, honoring .gitignore) when the root is in a git repo,
+     * else a directory walk that skips node_modules/dist/build/.git.
+     */
+    files(globs) {
+        if (!this.fileList)
+            this.fileList = listFiles(this.root);
+        if (!globs)
+            return this.fileList;
+        const patterns = typeof globs === 'string' ? [globs] : globs;
+        return this.fileList.filter((f) => patterns.some((glob) => matchesGlob(f, glob)));
+    }
+}
+/**
+ * Resolve the workspace containing `dir`: the nearest ancestor holding a tsconfig.json,
+ * else package.json, else a .git directory, else `dir` itself.
+ */
+export function openWorkspace(dir = process.cwd()) {
+    const start = path.resolve(dir);
+    for (const marker of ['tsconfig.json', 'package.json', '.git']) {
+        let cur = start;
+        for (;;) {
+            const candidate = path.join(cur, marker);
+            if (existsSync(candidate)) {
+                return new Workspace(cur, marker === 'tsconfig.json' ? candidate : nearestTsconfig(cur, cur), marker);
+            }
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                break;
+            cur = parent;
+        }
+    }
+    return new Workspace(start, null, 'none');
+}
+function nearestTsconfig(dir, stopAt) {
+    let current = dir;
+    for (;;) {
+        const candidate = path.join(current, 'tsconfig.json');
+        if (existsSync(candidate))
+            return candidate;
+        if (current === stopAt)
+            return null;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+export function langFor(file) {
+    switch (path.extname(file)) {
+        case '.ts':
+        case '.mts':
+        case '.cts':
+            return Lang.TypeScript;
+        case '.tsx':
+            return Lang.Tsx;
+        case '.js':
+        case '.mjs':
+        case '.cjs':
+        case '.jsx':
+            return Lang.JavaScript;
+        default:
+            return null;
+    }
+}
+export function matchesGlob(file, glob) {
+    // A bare directory matches as a prefix; a bare filename matches in any directory.
+    if (!/[*?[{]/.test(glob)) {
+        const normalized = glob.replace(/\/$/, '');
+        return file === normalized || file.startsWith(normalized + '/') || (!normalized.includes('/') && file.split('/').includes(normalized));
+    }
+    const pattern = glob.includes('/') ? glob : `**/${glob}`;
+    return path.matchesGlob(file, pattern);
+}
+function listFiles(root) {
+    let out;
+    try {
+        const raw = execFileSync('git', ['ls-files', '-co', '--exclude-standard', '-z'], {
+            cwd: root,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            maxBuffer: 1 << 28,
+        });
+        out = raw.split('\0').filter(Boolean);
+    }
+    catch {
+        out = [];
+        walk(root, '', out);
+    }
+    return out.filter((f) => SOURCE_EXT.has(path.extname(f)) && !f.split('/').some((seg) => SKIP_DIRS.has(seg)) && existsSync(path.join(root, f)));
+}
+function walk(root, rel, out) {
+    for (const entry of readdirSync(path.join(root, rel), { withFileTypes: true })) {
+        const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name))
+                walk(root, relPath, out);
+        }
+        else if (entry.isFile() || (entry.isSymbolicLink() && safeIsFile(path.join(root, relPath)))) {
+            out.push(relPath);
+        }
+    }
+}
+function safeIsFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index/build.d.ts

@@ -0,0 +1,22 @@
+import { type LoadReceipt, type StoreGraph } from '../store/load.js';
+import { Store } from '../store/store.js';
+import { Ts7Host } from '../ts7/api.js';
+import { ConfiguredProjects } from '../ts7/projects.js';
+import type { IndexGraph } from './graph.js';
+import { type HeritageGraph } from './heritage.js';
+export interface BuildReceipt extends LoadReceipt {
+    internalSites: number;
+    unresolvedOccurrences: number;
+    dispatchCalls: number;
+    durationMs: number;
+}
+export interface BuiltIndex {
+    graph: IndexGraph;
+    heritage: HeritageGraph['relationships'];
+    receipt: BuildReceipt;
+}
+/** Walks the configured project union, adds heritage facts, and atomically replaces the persisted graph. */
+export declare function buildIndex(root: string, program: Ts7Host, projects: ConfiguredProjects, store: Store): BuiltIndex;
+/** Rehydrates an unchanged persisted graph without re-walking the TypeScript program. */
+export declare function reuseIndex(store: Store): BuiltIndex;
+export declare function storeGraph(index: HeritageGraph): StoreGraph;

package/dist/index/build.js

@@ -0,0 +1,79 @@
+import { execFileSync } from 'node:child_process';
+import { loadGraph, readGraph } from '../store/load.js';
+import { metadataFor, readMetadata, writeMetadata } from '../store/meta.js';
+import { addHeritage } from './heritage.js';
+import { walkIndex } from './walk.js';
+/** Walks the configured project union, adds heritage facts, and atomically replaces the persisted graph. */
+export function buildIndex(root, program, projects, store) {
+    const started = performance.now();
+    const walked = walkIndex(root, program, projects);
+    const enriched = addHeritage(root, program, projects, walked);
+    const loaded = loadGraph(store, storeGraph(enriched));
+    const durationMs = performance.now() - started;
+    writeMetadata(store.path, metadataFor(root, projects, headCommit(root), durationMs));
+    return {
+        graph: enriched.graph,
+        heritage: enriched.relationships,
+        receipt: {
+            ...loaded,
+            internalSites: enriched.graph.internalSites,
+            unresolvedOccurrences: enriched.graph.unresolvedOccurrences,
+            dispatchCalls: enriched.dispatchCalls,
+            durationMs,
+        },
+    };
+}
+/** Rehydrates an unchanged persisted graph without re-walking the TypeScript program. */
+export function reuseIndex(store) {
+    const persisted = readGraph(store);
+    const metadata = readMetadata(store.path);
+    if (!metadata)
+        throw new Error('reuseIndex requires persisted store metadata; canReuse must pass first.');
+    const durationMs = metadata.indexDurationMs;
+    const declarations = new Map(persisted.declarations.map((declaration) => [declaration.key, declaration]));
+    const externals = new Map(persisted.externals.map((external) => [external.key, external]));
+    const relationships = persisted.relationships.filter((relationship) => ['CONTAINS', 'REFERENCES', 'CALLS', 'TYPE_MENTION', 'IMPORTS', 'EXPORTS'].includes(relationship.type)).map(({ target: _target, ...relationship }) => relationship);
+    const heritage = persisted.relationships.filter((relationship) => relationship.type === 'IMPLEMENTS' || relationship.type === 'EXTENDS').map(({ target: _target, ...relationship }) => relationship);
+    const files = new Map();
+    for (const declaration of declarations.values())
+        files.set(declaration.file, { declarations: [], relationships: [] });
+    for (const declaration of declarations.values())
+        files.get(declaration.file).declarations.push(declaration.key);
+    for (const relationship of relationships) {
+        const owner = declarations.get(relationship.from);
+        if (owner)
+            files.get(owner.file).relationships.push(relationship);
+    }
+    const counts = Object.fromEntries(['CONTAINS', 'REFERENCES', 'CALLS', 'IMPLEMENTS', 'EXTENDS', 'TYPE_MENTION', 'IMPORTS', 'EXPORTS', 'CHANGED', 'RENAMED_FROM'].map((type) => [type, 0]));
+    for (const relationship of persisted.relationships)
+        counts[relationship.type]++;
+    return {
+        graph: { declarations, externals, files, relationships, internalSites: 0, unresolvedOccurrences: 0 },
+        heritage,
+        receipt: { declarations: persisted.declarations.length, externals: persisted.externals.length, commits: persisted.commits?.length ?? 0, relationships: counts, internalSites: 0, unresolvedOccurrences: 0, dispatchCalls: persisted.relationships.filter((relationship) => relationship.type === 'CALLS' && relationship.dispatch === true).length, durationMs },
+    };
+}
+export function storeGraph(index) {
+    return {
+        declarations: [...index.graph.declarations.values()].map(declarationRow),
+        externals: [...index.graph.externals.values()],
+        relationships: [
+            ...index.graph.relationships.map((relationship) => relationshipRow(relationship, index.graph)),
+            ...index.relationships.map((relationship) => ({ ...relationship, target: 'Declaration' })),
+        ],
+    };
+}
+function declarationRow(node) {
+    return { ...node, container: node.container };
+}
+function relationshipRow(relationship, graph) {
+    return { ...relationship, target: graph.externals.has(relationship.to) ? 'External' : 'Declaration' };
+}
+function headCommit(root) {
+    try {
+        return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        return 'unknown';
+    }
+}