@crouton-kit/tsym 0.1.0

package/dist/index/walk.js

@@ -0,0 +1,550 @@
+import path from 'node:path';
+import { SymbolFlags } from 'typescript/unstable/sync';
+import * as ts from '../ts7/ast.js';
+import { declarationTarget, moduleTarget, relative } from './classify.js';
+import { describeFile } from './descriptor.js';
+import { isIndexedDeclaration } from './scope.js';
+const walkStates = new WeakMap();
+/** Returns the snapshot-backed file state created by walkIndex for heritage enrichment. */
+export function walkFileStates(graph) {
+    const states = walkStates.get(graph);
+    if (!states)
+        throw new Error('Heritage enrichment requires the graph returned by walkIndex.');
+    return states;
+}
+export function walkIndex(root, program, projects) {
+    const states = statesFor(root, program, projects.records());
+    const lookup = {
+        root,
+        indexedByStart: new Map(states.map((state) => [state.file, state.byStart])),
+        modulesByFile: new Map(states.map((state) => [state.file, state.indexed.find((descriptor) => descriptor.scope === 'module').key])),
+    };
+    const declarations = new Map();
+    const externals = new Map();
+    const fileRelationships = new Map();
+    let internalSites = 0;
+    let unresolvedOccurrences = 0;
+    const addExternal = (node) => { externals.set(node.key, node); };
+    const addTarget = (target, unresolved) => {
+        if (target === null) {
+            internalSites++;
+            return null;
+        }
+        if (unresolved) {
+            unresolvedOccurrences++;
+            return null;
+        }
+        if (target.external)
+            addExternal(target.node);
+        return target.key;
+    };
+    for (const state of states) {
+        const relationships = [];
+        fileRelationships.set(state.file, relationships);
+        for (const descriptor of state.indexed) {
+            const existing = declarations.get(descriptor.key);
+            if (existing) {
+                existing.declCount++;
+                continue;
+            }
+            const declaration = declarationNode(state, descriptor);
+            declarations.set(declaration.key, declaration);
+        }
+    }
+    const { symbols: symbolTargets, definitions } = declarationSymbolTargets(states);
+    const resolvedTargets = new Map();
+    for (const state of states) {
+        const relationships = fileRelationships.get(state.file);
+        const added = new Set();
+        const add = (relationship) => {
+            const site = `${relationship.type}:${relationship.from}:${relationship.to}:${'line' in relationship ? relationship.line : ''}:${'col' in relationship ? relationship.col : ''}:${'name' in relationship ? relationship.name : ''}`;
+            if (!added.has(site)) {
+                added.add(site);
+                relationships.push(relationship);
+            }
+        };
+        for (const descriptor of state.indexed) {
+            const declaration = declarations.get(descriptor.key);
+            if (declaration.container)
+                add({ type: 'CONTAINS', from: declaration.container, to: declaration.key });
+        }
+        const definitionTargets = definitions.get(state.file) ?? new Map();
+        const positions = [...new Set(state.semanticNodes.map((node) => node.getStart(state.source)).filter((position) => !definitionTargets.has(position) || state.typeIdentifierPositions.has(position)))];
+        const symbols = state.checker.getSymbolAtPosition(state.absolute, positions);
+        const symbolsByPosition = new Map(positions.map((position, index) => [position, symbols[index]]));
+        const symbolFor = (node) => symbolsByPosition.get(node.getStart(state.source));
+        const seenReferences = new Set();
+        const callTargets = new Map();
+        const seenTypes = new Set();
+        const seenUnresolved = new Set();
+        const aliases = new Map();
+        const alias = (symbol) => {
+            const cached = aliases.get(symbol.id);
+            if (cached)
+                return cached;
+            const resolved = symbol.flags & SymbolFlags.Alias ? state.checker.getAliasedSymbol(symbol) : symbol;
+            aliases.set(symbol.id, resolved);
+            return resolved;
+        };
+        const externalModules = new Map();
+        state.source.forEachChild((node) => {
+            if (!ts.isImportDeclaration(node))
+                return;
+            const moduleSpecifier = node.moduleSpecifier;
+            const moduleText = ts.isStringLiteral(moduleSpecifier) ? moduleSpecifier.text : moduleSpecifier.getText(state.source);
+            const target = moduleTarget(symbolFor(moduleSpecifier), lookup, alias, moduleText);
+            if (!target?.external)
+                return;
+            for (const binding of importBindings(node)) {
+                const symbol = symbolFor(binding);
+                if (symbol)
+                    externalModules.set(symbol.id, target.node.module);
+            }
+        });
+        const targetFor = (symbol, position) => {
+            if (!symbol || state.checker.isUnknownSymbol(symbol)) {
+                if (!seenUnresolved.has(position)) {
+                    seenUnresolved.add(position);
+                    unresolvedOccurrences++;
+                }
+                return null;
+            }
+            const resolved = alias(symbol);
+            if (symbolTargets.has(resolved.id)) {
+                const key = symbolTargets.get(resolved.id);
+                if (key === null) {
+                    internalSites++;
+                    return null;
+                }
+                return key;
+            }
+            const externalIdentity = externalModules.get(symbol.id);
+            const cacheKey = `${resolved.id}:${externalIdentity ?? ''}`;
+            const target = resolvedTargets.has(cacheKey) ? resolvedTargets.get(cacheKey) : declarationTarget(resolved, lookup, (candidate) => candidate, externalIdentity);
+            resolvedTargets.set(cacheKey, target);
+            return addTarget(target, false);
+        };
+        const definitionTarget = (position) => {
+            if (!definitionTargets.has(position))
+                return undefined;
+            const target = definitionTargets.get(position);
+            if (target === null)
+                internalSites++;
+            return target;
+        };
+        const ownerFor = (node) => ownerForNode(state, node).key;
+        const point = (node) => {
+            const value = state.source.getLineAndCharacterOfPosition(node.getStart(state.source));
+            return { line: value.line + 1, col: value.character + 1 };
+        };
+        const reference = (node, role, target) => {
+            const start = node.getStart(state.source);
+            if (seenReferences.has(start))
+                return;
+            seenReferences.add(start);
+            const resolved = typeof target === 'function' ? target() : target === undefined ? targetFor(symbolFor(node), start) : target;
+            if (!resolved)
+                return;
+            const site = point(node);
+            add({ type: 'REFERENCES', from: ownerFor(node), to: resolved, ...site, role });
+        };
+        const call = (node, callee) => {
+            const start = callee.getStart(state.source);
+            const target = targetFor(symbolFor(callee), start);
+            callTargets.set(start, target);
+            reference(callee, 'call', target);
+            if (!target)
+                return;
+            const site = point(callee);
+            add({ type: 'CALLS', from: ownerFor(callee), to: target, ...site, dispatch: false });
+        };
+        const typeMention = (node) => {
+            const start = node.getStart(state.source);
+            if (seenTypes.has(start))
+                return;
+            seenTypes.add(start);
+            const identifier = firstIdentifier(node);
+            if (!identifier)
+                return;
+            const target = targetFor(symbolFor(identifier), start);
+            if (!target)
+                return;
+            const site = point(node);
+            add({ type: 'TYPE_MENTION', from: ownerFor(node), to: target, ...site, position: typePosition(node) });
+        };
+        const visit = (node) => {
+            const callee = callCallee(node);
+            if (callee)
+                call(node, callee);
+            if (ts.isIdentifier(node)) {
+                const start = node.getStart(state.source);
+                reference(node, referenceRole(node, callee !== null), () => {
+                    if (callTargets.has(start))
+                        return callTargets.get(start);
+                    const target = definitionTarget(start);
+                    return target === undefined ? targetFor(symbolFor(node), start) : target;
+                });
+            }
+            if (isTypeNode(node))
+                typeMention(node);
+            if (ts.isImportDeclaration(node)) {
+                const moduleSpecifier = node.moduleSpecifier;
+                const moduleText = ts.isStringLiteral(moduleSpecifier) ? moduleSpecifier.text : moduleSpecifier.getText(state.source);
+                const target = moduleTarget(symbolFor(moduleSpecifier), lookup, alias, moduleText);
+                const key = addTarget(target, false);
+                if (key) {
+                    const site = point(moduleSpecifier);
+                    add({ type: 'IMPORTS', from: `${state.file}#<module>`, to: key, line: site.line, names: importNames(node, state.source) });
+                }
+            }
+            if (ts.isExportDeclaration(node))
+                exportDeclaration(node, state, lookup, addTarget, add, alias);
+            node.forEachChild(visit);
+        };
+        state.source.forEachChild(visit);
+        directExports(state, add);
+    }
+    const files = new Map();
+    for (const state of states) {
+        const ids = [...new Set(state.indexed.map((descriptor) => descriptor.key))];
+        files.set(state.file, { declarations: ids, relationships: fileRelationships.get(state.file) });
+    }
+    const graph = { declarations, externals, files, relationships: [...fileRelationships.values()].flat(), internalSites, unresolvedOccurrences };
+    walkStates.set(graph, states);
+    return graph;
+}
+function statesFor(root, program, configured) {
+    const owner = new Map();
+    for (const project of configured)
+        for (const file of project.files)
+            if (!owner.has(file))
+                owner.set(file, project);
+    return program.withSnapshot((snapshot) => [...owner].sort(([left], [right]) => left.localeCompare(right)).flatMap(([absolute, configuredProject]) => {
+        const project = snapshot.getProject(configuredProject.config);
+        const source = project?.program.getSourceFile(absolute);
+        if (!source || !project)
+            return [];
+        const file = relative(root, absolute);
+        const descriptors = describeFile(file, source.text);
+        const indexed = descriptors.filter(isIndexedDeclaration);
+        const byStart = new Map(indexed.map((descriptor) => [descriptor.start, descriptor]));
+        const module = indexed.find((descriptor) => descriptor.scope === 'module');
+        if (!module)
+            throw new Error(`No module declaration exists for ${file}.`);
+        const nodesByStart = new Map();
+        const ownersByStart = new Map();
+        const semanticNodes = [];
+        const typeIdentifierPositions = new Set();
+        const collect = (node, parentOwner) => {
+            const start = node.getStart(source);
+            const nextOwner = byStart.get(start) ?? parentOwner;
+            if (!nodesByStart.has(start))
+                nodesByStart.set(start, node);
+            if (!ownersByStart.has(start))
+                ownersByStart.set(start, nextOwner);
+            if (ts.isIdentifier(node))
+                semanticNodes.push(node);
+            if (isTypeNode(node)) {
+                const identifier = firstIdentifier(node);
+                if (identifier)
+                    typeIdentifierPositions.add(identifier.getStart(source));
+            }
+            if (ts.isImportDeclaration(node))
+                semanticNodes.push(node.moduleSpecifier);
+            node.forEachChild((child) => collect(child, nextOwner));
+        };
+        source.forEachChild((node) => collect(node, module));
+        return [{
+                absolute,
+                file,
+                source,
+                project,
+                checker: project.checker,
+                descriptors,
+                indexed,
+                byStart,
+                nodesByStart,
+                ownersByStart,
+                semanticNodes,
+                typeIdentifierPositions,
+            }];
+    }));
+}
+function ownerForNode(state, node) {
+    if (ts.isSourceFile(node))
+        return state.indexed.find((descriptor) => descriptor.scope === 'module');
+    const owner = state.ownersByStart.get(node.getStart(state.source));
+    if (owner && ownsSites(state, owner))
+        return owner;
+    for (let current = node.parent; current && !ts.isSourceFile(current); current = current.parent) {
+        const descriptor = state.byStart.get(current.getStart(state.source));
+        if (descriptor && ownsSites(state, descriptor))
+            return descriptor;
+    }
+    return state.indexed.find((descriptor) => descriptor.scope === 'module');
+}
+function ownsSites(state, descriptor) {
+    const node = state.nodesByStart.get(descriptor.start);
+    if (!node)
+        return true;
+    if (ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isClassExpression(node))
+        return false;
+    if (!(ts.isVariableDeclaration(node) || ts.isBindingElement(node) || ts.isPropertyDeclaration(node)))
+        return true;
+    const initializer = node.initializer;
+    return !!initializer && (ts.isFunctionExpression(initializer) || ts.isArrowFunction(initializer) || ts.isClassExpression(initializer));
+}
+function declarationSymbolTargets(states) {
+    const descriptorsByFileStart = new Map();
+    for (const state of states)
+        for (const descriptor of state.descriptors)
+            descriptorsByFileStart.set(`${path.resolve(state.absolute)}:${descriptor.start}`, { state, descriptor });
+    const symbolsById = new Map();
+    const definitions = new Map();
+    for (const state of states) {
+        const descriptors = state.descriptors.filter((descriptor) => descriptor.scope !== 'module');
+        const symbols = state.checker.getSymbolAtPosition(state.absolute, descriptors.map((descriptor) => descriptor.nameStart));
+        for (const symbol of symbols) {
+            if (!symbol)
+                continue;
+            const declarations = symbol.declarations.flatMap((handle) => {
+                const declaration = handle.resolve();
+                if (!declaration)
+                    return [];
+                const file = path.resolve(declaration.getSourceFile().fileName);
+                const target = descriptorsByFileStart.get(`${file}:${declaration.getStart(declaration.getSourceFile())}`);
+                return target ? [target] : [];
+            });
+            if (declarations.length === 0)
+                continue;
+            const target = declarations.find(({ descriptor }) => isIndexedDeclaration(descriptor))?.descriptor.key ?? null;
+            symbolsById.set(symbol.id, target);
+            for (const { state: declarationState, descriptor } of declarations) {
+                const file = definitions.get(declarationState.file) ?? new Map();
+                file.set(descriptor.nameStart, target);
+                definitions.set(declarationState.file, file);
+            }
+        }
+    }
+    return { symbols: symbolsById, definitions };
+}
+function declarationNode(state, descriptor) {
+    const name = state.source.getLineAndCharacterOfPosition(descriptor.nameStart);
+    const start = state.source.getLineAndCharacterOfPosition(descriptor.start);
+    const end = state.source.getLineAndCharacterOfPosition(descriptor.end);
+    const declaration = state.nodesByStart.get(descriptor.start);
+    const kind = declarationKind(descriptor, declaration);
+    const container = descriptor.scope === 'module'
+        ? null
+        : declaration
+            ? parameterPropertyContainer(state, descriptor, declaration)
+            : `${state.file}#<module>`;
+    const dir = path.posix.dirname(state.file);
+    const segments = state.file.split('/');
+    return {
+        key: descriptor.key,
+        at: `${state.file}:${name.line + 1}:${name.character + 1}`,
+        name: descriptor.name,
+        qname: descriptor.path,
+        kind,
+        exported: descriptor.scope !== 'module' && !!declaration && isExported(declaration),
+        file: state.file,
+        dir: dir === '.' ? '' : dir,
+        top: segments.length >= 2 ? `${segments[0]}/${segments[1]}` : dir,
+        line: descriptor.scope === 'module' ? 0 : name.line + 1,
+        col: descriptor.scope === 'module' ? 0 : name.character + 1,
+        endLine: end.line + 1,
+        // The full declaration span (modifiers and decorators included): `show` recovers its first line as `endLine - lines + 1`.
+        lines: Math.max(1, end.line - start.line + 1),
+        declCount: 1,
+        container,
+    };
+}
+function declarationKind(descriptor, node) {
+    switch (descriptor.kind) {
+        case 'FunctionDeclaration': return 'function';
+        case 'ClassDeclaration':
+        case 'ClassExpression': return 'class';
+        case 'InterfaceDeclaration': return 'interface';
+        case 'TypeAliasDeclaration': return 'type';
+        case 'EnumDeclaration': return 'enum';
+        case 'ModuleDeclaration': return 'namespace';
+        case 'MethodDeclaration':
+        case 'MethodSignature': return 'method';
+        case 'Parameter':
+        case 'PropertyDeclaration':
+        case 'PropertySignature':
+        case 'EnumMember': return 'property';
+        case 'GetAccessor': return 'getter';
+        case 'SetAccessor': return 'setter';
+        case 'Constructor': return 'constructor';
+        case 'VariableDeclaration':
+        case 'BindingElement': return variableKind(node);
+        case 'FunctionExpression':
+        case 'ArrowFunction': return 'function';
+        default: return descriptor.scope === 'module' ? 'module' : 'property';
+    }
+}
+function parameterPropertyContainer(state, descriptor, declaration) {
+    if (descriptor.kind === 'Parameter' && ts.isParameterDeclaration(declaration) && ts.isConstructorDeclaration(declaration.parent) && declaration.parent.parent)
+        return ownerForNode(state, declaration.parent.parent).key;
+    return ownerForNode(state, declaration.parent).key;
+}
+function variableKind(node) {
+    for (let current = node; current; current = current.parent) {
+        if (!ts.isVariableDeclaration(current))
+            continue;
+        const parent = current.parent;
+        const flags = ts.isVariableDeclarationList(parent) ? parent.flags : 0;
+        if (flags & ts.NodeFlags.Const)
+            return 'const';
+        if (flags & ts.NodeFlags.Let)
+            return 'let';
+        return 'var';
+    }
+    return 'var';
+}
+function isExported(node) {
+    if (node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword))
+        return true;
+    if (ts.isExportAssignment(node))
+        return true;
+    // Only a variable's own statement can export it; a loop variable or a nested local inside an exported statement is not exported.
+    let current = node;
+    while (ts.isBindingElement(current) || ts.isObjectBindingPattern(current) || ts.isArrayBindingPattern(current) || ts.isVariableDeclaration(current))
+        current = current.parent;
+    const statement = ts.isVariableDeclarationList(current) ? current.parent : undefined;
+    return !!statement && ts.isVariableStatement(statement) && statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) === true;
+}
+function callCallee(node) {
+    let expression;
+    if (ts.isCallExpression(node) || ts.isNewExpression(node))
+        expression = node.expression;
+    else if (ts.isTaggedTemplateExpression(node))
+        expression = node.tag;
+    else if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node))
+        expression = node.tagName;
+    else
+        return null;
+    return ts.isPropertyAccessExpression(expression) ? expression.name : expression;
+}
+function referenceRole(node, call) {
+    for (let current = node; current; current = current.parent) {
+        if (ts.isImportDeclaration(current) || ts.isImportSpecifier(current) || ts.isNamespaceImport(current) || ts.isImportClause(current) || ts.isExportSpecifier(current))
+            return 'import';
+        if (isTypeNode(current))
+            return 'type';
+        if (call)
+            return 'call';
+        if (isWrite(node, current))
+            return 'write';
+    }
+    return isDeclarationName(node) ? 'definition' : 'read';
+}
+function isDeclarationName(node) {
+    if (node.parent.name !== node)
+        return false;
+    switch (node.parent.kind) {
+        case ts.SyntaxKind.FunctionDeclaration:
+        case ts.SyntaxKind.ClassDeclaration:
+        case ts.SyntaxKind.InterfaceDeclaration:
+        case ts.SyntaxKind.TypeAliasDeclaration:
+        case ts.SyntaxKind.EnumDeclaration:
+        case ts.SyntaxKind.ModuleDeclaration:
+        case ts.SyntaxKind.VariableDeclaration:
+        case ts.SyntaxKind.BindingElement:
+        case ts.SyntaxKind.Parameter:
+        case ts.SyntaxKind.TypeParameter:
+        case ts.SyntaxKind.MethodDeclaration:
+        case ts.SyntaxKind.MethodSignature:
+        case ts.SyntaxKind.PropertyDeclaration:
+        case ts.SyntaxKind.PropertySignature:
+        case ts.SyntaxKind.PropertyAssignment:
+        case ts.SyntaxKind.ShorthandPropertyAssignment:
+        case ts.SyntaxKind.EnumMember:
+        case ts.SyntaxKind.GetAccessor:
+        case ts.SyntaxKind.SetAccessor:
+            return true;
+        default:
+            return false;
+    }
+}
+function isWrite(node, current) {
+    if ((ts.isBinaryExpression(current) && current.left === node && current.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && current.operatorToken.kind <= ts.SyntaxKind.LastAssignment) || ts.isPrefixUnaryExpression(current) || ts.isPostfixUnaryExpression(current))
+        return true;
+    return false;
+}
+function isTypeNode(node) {
+    return node.kind >= ts.SyntaxKind.FirstTypeNode && node.kind <= ts.SyntaxKind.LastTypeNode;
+}
+function firstIdentifier(node) {
+    if (ts.isIdentifier(node))
+        return node;
+    return node.forEachChild(firstIdentifier);
+}
+function typePosition(node) {
+    const parent = node.parent;
+    if (ts.isParameterDeclaration(parent))
+        return 'parameter';
+    if (isFunctionLike(parent))
+        return 'return';
+    if (ts.isPropertyDeclaration(parent) || parent.kind === ts.SyntaxKind.PropertySignature)
+        return 'property';
+    if (ts.isVariableDeclaration(parent))
+        return 'variable';
+    return 'type';
+}
+function isFunctionLike(node) {
+    return node.kind === ts.SyntaxKind.FunctionDeclaration || node.kind === ts.SyntaxKind.FunctionExpression || node.kind === ts.SyntaxKind.ArrowFunction || node.kind === ts.SyntaxKind.MethodDeclaration || node.kind === ts.SyntaxKind.MethodSignature || node.kind === ts.SyntaxKind.GetAccessor || node.kind === ts.SyntaxKind.SetAccessor || node.kind === ts.SyntaxKind.Constructor || node.kind === ts.SyntaxKind.CallSignature || node.kind === ts.SyntaxKind.ConstructSignature || node.kind === ts.SyntaxKind.IndexSignature;
+}
+function importNames(node, _source) {
+    const clause = node.importClause;
+    if (!clause)
+        return '*';
+    const names = [];
+    if (clause.name)
+        names.push(clause.name.text);
+    if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings))
+        names.push(`* as ${clause.namedBindings.name.text}`);
+    if (clause.namedBindings && ts.isNamedImports(clause.namedBindings))
+        for (const element of clause.namedBindings.elements)
+            names.push(element.propertyName ? `${element.propertyName.text} as ${element.name.text}` : element.name.text);
+    return names.join(', ');
+}
+function importBindings(node) {
+    const clause = node.importClause;
+    if (!clause)
+        return [];
+    const bindings = [];
+    if (clause.name)
+        bindings.push(clause.name);
+    if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings))
+        bindings.push(clause.namedBindings.name);
+    if (clause.namedBindings && ts.isNamedImports(clause.namedBindings))
+        for (const element of clause.namedBindings.elements)
+            bindings.push(element.name);
+    return bindings;
+}
+function directExports(state, add) {
+    for (const descriptor of state.indexed) {
+        const node = state.nodesByStart.get(descriptor.start);
+        if (!node || !isExported(node))
+            continue;
+        const site = state.source.getLineAndCharacterOfPosition(descriptor.nameStart);
+        add({ type: 'EXPORTS', from: `${state.file}#<module>`, to: descriptor.key, name: descriptor.name, line: site.line + 1, col: site.character + 1 });
+    }
+}
+function exportDeclaration(stateNode, state, lookup, addTarget, add, alias) {
+    const clause = stateNode.exportClause;
+    if (!clause || !ts.isNamedExports(clause))
+        return;
+    for (const element of clause.elements) {
+        const symbol = state.checker.getExportSpecifierLocalTargetSymbol(element);
+        const target = symbol ? declarationTarget(symbol, lookup, alias) : null;
+        const key = addTarget(target, !symbol);
+        if (!key || target?.external)
+            continue;
+        const site = state.source.getLineAndCharacterOfPosition(element.name.getStart(state.source));
+        add({ type: 'EXPORTS', from: `${state.file}#<module>`, to: key, name: element.name.text, line: site.line + 1, col: site.character + 1 });
+    }
+}

package/dist/index/watch.d.ts

@@ -0,0 +1,18 @@
+import { type ConfiguredProjects } from '../ts7/projects.js';
+export interface WatchBatch {
+    fileChanges: {
+        changed?: string[];
+        created?: string[];
+        deleted?: string[];
+    } | {
+        invalidateAll: true;
+    };
+    full: boolean;
+    git: boolean;
+}
+export interface IndexWatcher {
+    close(): void;
+    refresh(): void;
+}
+/** Watches configured source directories; events supply text changes, never semantic invalidation. */
+export declare function watchIndex(root: string, projects: ConfiguredProjects, refresh: (batch: WatchBatch) => Promise<void>, reportError: (error: unknown) => void, markStale: (flush: () => Promise<void>) => void): IndexWatcher;