@crouton-kit/tsym 0.1.0

package/dist/index/graph.d.ts

@@ -0,0 +1,82 @@
+export type DeclarationKind = 'module' | 'function' | 'class' | 'interface' | 'type' | 'enum' | 'namespace' | 'const' | 'let' | 'var' | 'method' | 'property' | 'getter' | 'setter' | 'constructor';
+export interface DeclarationNode {
+    key: string;
+    at: string;
+    name: string;
+    qname: string;
+    kind: DeclarationKind;
+    exported: boolean;
+    file: string;
+    dir: string;
+    top: string;
+    line: number;
+    col: number;
+    endLine: number;
+    lines: number;
+    declCount: number;
+    container: string | null;
+}
+export interface ExternalNode {
+    key: string;
+    module: string;
+    name: string;
+}
+export type ReferenceRole = 'definition' | 'call' | 'import' | 'type' | 'write' | 'read';
+export type TypePosition = 'parameter' | 'return' | 'property' | 'variable' | 'type';
+export interface ContainsRelationship {
+    type: 'CONTAINS';
+    from: string;
+    to: string;
+}
+export interface ReferenceRelationship {
+    type: 'REFERENCES';
+    from: string;
+    to: string;
+    line: number;
+    col: number;
+    role: ReferenceRole;
+}
+export interface CallRelationship {
+    type: 'CALLS';
+    from: string;
+    to: string;
+    line: number;
+    col: number;
+    dispatch: boolean;
+}
+export interface TypeMentionRelationship {
+    type: 'TYPE_MENTION';
+    from: string;
+    to: string;
+    line: number;
+    col: number;
+    position: TypePosition;
+}
+export interface ImportRelationship {
+    type: 'IMPORTS';
+    from: string;
+    to: string;
+    line: number;
+    names: string;
+}
+export interface ExportRelationship {
+    type: 'EXPORTS';
+    from: string;
+    to: string;
+    name: string;
+    line: number;
+    col: number;
+}
+export type IndexRelationship = ContainsRelationship | ReferenceRelationship | CallRelationship | TypeMentionRelationship | ImportRelationship | ExportRelationship;
+export interface FileGraph {
+    declarations: readonly string[];
+    relationships: readonly IndexRelationship[];
+}
+export interface IndexGraph {
+    declarations: ReadonlyMap<string, DeclarationNode>;
+    externals: ReadonlyMap<string, ExternalNode>;
+    files: ReadonlyMap<string, FileGraph>;
+    relationships: readonly IndexRelationship[];
+    internalSites: number;
+    unresolvedOccurrences: number;
+}

package/dist/index/graph.js

@@ -0,0 +1 @@
+export {};

package/dist/index/heritage.d.ts

@@ -0,0 +1,15 @@
+import { Ts7Host } from '../ts7/api.js';
+import { ConfiguredProjects } from '../ts7/projects.js';
+import type { IndexGraph } from './graph.js';
+export interface HeritageRelationship {
+    type: 'EXTENDS' | 'IMPLEMENTS';
+    from: string;
+    to: string;
+}
+export interface HeritageGraph {
+    graph: IndexGraph;
+    relationships: readonly HeritageRelationship[];
+    dispatchCalls: number;
+}
+/** Adds compiler-resolved heritage edges and marks calls that require implementation dispatch. */
+export declare function addHeritage(root: string, program: Ts7Host, projects: ConfiguredProjects, graph: IndexGraph): HeritageGraph;

package/dist/index/heritage.js

@@ -0,0 +1,122 @@
+import { SymbolFlags } from 'typescript/unstable/sync';
+import * as ts from '../ts7/ast.js';
+import { isIndexedDeclaration } from './scope.js';
+import { relative } from './classify.js';
+import { walkFileStates } from './walk.js';
+/** Adds compiler-resolved heritage edges and marks calls that require implementation dispatch. */
+export function addHeritage(root, program, projects, graph) {
+    const states = walkFileStates(graph);
+    const stateByFile = new Map(states.map((state) => [state.file, state]));
+    const declarationsByKey = new Map();
+    for (const state of states)
+        for (const descriptor of state.descriptors) {
+            if (!graph.declarations.has(descriptor.key))
+                continue;
+            const node = state.nodesByStart.get(descriptor.start);
+            if (!node)
+                continue;
+            const nodes = declarationsByKey.get(descriptor.key) ?? [];
+            nodes.push(node);
+            declarationsByKey.set(descriptor.key, nodes);
+        }
+    const targetKey = (checker, symbol) => {
+        if (!symbol)
+            return undefined;
+        const resolved = symbol.flags & SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+        for (const handle of resolved.declarations) {
+            const declaration = handle.resolve();
+            if (!declaration)
+                continue;
+            const file = relative(root, declaration.getSourceFile().fileName);
+            const state = stateByFile.get(file);
+            const descriptor = state?.byStart.get(declaration.getStart(declaration.getSourceFile()));
+            if (descriptor && graph.declarations.has(descriptor.key))
+                return descriptor.key;
+        }
+        return undefined;
+    };
+    const relationships = new Map();
+    const add = (relationship) => { relationships.set(`${relationship.type}:${relationship.from}:${relationship.to}`, relationship); };
+    for (const state of states) {
+        const visit = (node) => {
+            if (ts.isClassDeclaration(node) || ts.isClassExpression(node) || ts.isInterfaceDeclaration(node)) {
+                const source = state.byStart.get(node.getStart(state.source));
+                if (source && graph.declarations.has(source.key)) {
+                    for (const clause of node.heritageClauses ?? []) {
+                        for (const type of clause.types) {
+                            const target = targetKey(state.checker, state.checker.getSymbolAtLocation(type.expression));
+                            if (!target)
+                                continue;
+                            if (clause.token === ts.SyntaxKind.ImplementsKeyword && (ts.isClassDeclaration(node) || ts.isClassExpression(node)))
+                                add({ type: 'IMPLEMENTS', from: source.key, to: target });
+                            else if (clause.token === ts.SyntaxKind.ExtendsKeyword)
+                                add({ type: 'EXTENDS', from: source.key, to: target });
+                            if (ts.isClassDeclaration(node) || ts.isClassExpression(node))
+                                addMatchingMembers(node, state, target, targetKey, declarationsByKey, add);
+                        }
+                    }
+                }
+            }
+            node.forEachChild(visit);
+        };
+        state.source.forEachChild(visit);
+    }
+    const dispatch = (target) => (declarationsByKey.get(target) ?? []).some(isDispatchTarget);
+    const decoratedRelationships = graph.relationships.map((relationship) => relationship.type === 'CALLS'
+        ? { ...relationship, dispatch: dispatch(relationship.to) }
+        : relationship);
+    const decoratedByFile = new Map();
+    for (const relationship of decoratedRelationships) {
+        const file = graph.declarations.get(relationship.from)?.file;
+        if (file)
+            (decoratedByFile.get(file) ?? decoratedByFile.set(file, []).get(file)).push(relationship);
+    }
+    const files = new Map([...graph.files].map(([file, record]) => [file, { ...record, relationships: decoratedByFile.get(file) ?? [] }]));
+    const decorated = { ...graph, files, relationships: decoratedRelationships };
+    const dispatchCalls = decoratedRelationships.filter((relationship) => relationship.type === 'CALLS' && relationship.dispatch).length;
+    return { graph: decorated, relationships: [...relationships.values()], dispatchCalls };
+}
+function addMatchingMembers(node, state, target, targetKey, declarationsByKey, add) {
+    const targetDeclaration = declarationsByKey.get(target)?.find((candidate) => ts.isInterfaceDeclaration(candidate) || ts.isClassDeclaration(candidate));
+    if (!targetDeclaration?.name)
+        return;
+    const targetType = state.checker.getTypeAtLocation(targetDeclaration.name);
+    if (!targetType)
+        return;
+    for (const member of node.members) {
+        const descriptor = state.byStart.get(member.getStart(state.source));
+        const name = memberName(member);
+        if (!descriptor || !name || !isIndexedDeclaration(descriptor) || hasModifier(member, ts.SyntaxKind.AbstractKeyword))
+            continue;
+        const baseMember = state.checker.getPropertyOfType(targetType, name);
+        const memberTarget = targetKey(state.checker, baseMember);
+        const dispatch = baseMember?.declarations.some((handle) => {
+            const declaration = handle.resolve();
+            return declaration !== undefined && isDispatchTarget(declaration);
+        }) === true;
+        if (memberTarget && dispatch)
+            add({ type: 'IMPLEMENTS', from: descriptor.key, to: memberTarget });
+    }
+}
+function memberName(node) {
+    const name = node.name;
+    return name?.text;
+}
+function isDispatchTarget(node) {
+    if (ts.isMethodSignatureDeclaration(node))
+        return true;
+    if (!(ts.isMethodDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node) || ts.isConstructorDeclaration(node) || ts.isVariableDeclaration(node)))
+        return false;
+    if (hasModifier(node, ts.SyntaxKind.AbstractKeyword) || hasModifier(node, ts.SyntaxKind.DeclareKeyword))
+        return true;
+    for (let current = node.parent; current; current = current.parent) {
+        if (hasModifier(current, ts.SyntaxKind.DeclareKeyword))
+            return true;
+        if (ts.isSourceFile(current))
+            return current.fileName.endsWith('.d.ts');
+    }
+    return false;
+}
+function hasModifier(node, kind) {
+    return node.modifiers?.some((modifier) => modifier.kind === kind) === true;
+}

package/dist/index/refresh.d.ts

@@ -0,0 +1,28 @@
+import { 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 HeritageGraph } from './heritage.js';
+import { type BuiltIndex } from './build.js';
+export interface RefreshOptions {
+    fileChanges: {
+        changed?: string[];
+        created?: string[];
+        deleted?: string[];
+    } | {
+        invalidateAll: true;
+    };
+    full?: boolean;
+    validate?: boolean;
+}
+export interface RefreshResult {
+    built: BuiltIndex;
+    changedFiles: readonly string[];
+    stored: 'full' | 'files' | 'none';
+    validation: 'off' | 'matched';
+}
+/** Updates the TS7 snapshot, conservatively re-walks the union, then writes only changed file records. */
+export declare function refreshIndex(root: string, program: Ts7Host, projects: ConfiguredProjects, store: Store, previous: BuiltIndex, options: RefreshOptions): RefreshResult;
+export declare function graphsEqual(left: HeritageGraph, right: HeritageGraph): boolean;
+export declare function fileFingerprint(graph: BuiltIndex['graph'], heritage: readonly HeritageGraph['relationships'][number][], file: string): string;
+export declare function graphFingerprint(graph: StoreGraph): string;

package/dist/index/refresh.js

@@ -0,0 +1,110 @@
+import { execFileSync } from 'node:child_process';
+import { loadGraph, replaceFiles } from '../store/load.js';
+import { metadataFor, writeMetadata } from '../store/meta.js';
+import { addHeritage } from './heritage.js';
+import { storeGraph } from './build.js';
+import { walkIndex } from './walk.js';
+/** Updates the TS7 snapshot, conservatively re-walks the union, then writes only changed file records. */
+export function refreshIndex(root, program, projects, store, previous, options) {
+    const started = performance.now();
+    // The update carries a rewritten config's new text, so it must precede the rediscovery that reads membership from it.
+    program.update({ fileChanges: options.fileChanges });
+    if (options.full)
+        projects.reload();
+    const candidate = indexGraph(root, program, projects);
+    const graph = storeGraph(candidate);
+    const changedFiles = differingFiles(previous, candidate);
+    let stored = 'none';
+    if (options.full && changedFiles.length > 0) {
+        loadGraph(store, graph);
+        stored = 'full';
+    }
+    else if (changedFiles.length > 0) {
+        replaceFiles(store, changedFiles, fileGraph(graph, changedFiles));
+        stored = 'files';
+    }
+    const durationMs = performance.now() - started;
+    writeMetadata(store.path, metadataFor(root, projects, headCommit(root), durationMs));
+    let validation = 'off';
+    if (options.validate) {
+        const verification = indexGraph(root, program, projects);
+        if (!graphsEqual(candidate, verification))
+            throw new Error('Index validation failed: the conservative refresh and full rebuild produced different graphs.');
+        validation = 'matched';
+    }
+    return { built: built(candidate, graph, durationMs), changedFiles, stored, validation };
+}
+export function graphsEqual(left, right) {
+    return graphFingerprint(storeGraph(left)) === graphFingerprint(storeGraph(right));
+}
+function indexGraph(root, program, projects) {
+    return addHeritage(root, program, projects, walkIndex(root, program, projects));
+}
+function differingFiles(previous, next) {
+    const previousHeritage = heritageByFile(previous.graph, previous.heritage);
+    const nextHeritage = heritageByFile(next.graph, next.relationships);
+    const files = new Set([...previous.graph.files.keys(), ...next.graph.files.keys()]);
+    return [...files].filter((file) => fileFingerprint(previous.graph, previousHeritage.get(file) ?? [], file) !== fileFingerprint(next.graph, nextHeritage.get(file) ?? [], file)).sort();
+}
+export function fileFingerprint(graph, heritage, file) {
+    const record = graph.files.get(file);
+    const declarations = [...new Set(record?.declarations ?? [])].flatMap((key) => {
+        const declaration = graph.declarations.get(key);
+        return declaration === undefined ? [] : [declaration];
+    });
+    return `{"declarations":[${serializedRows(declarations).join(',')}],"relationships":[${serializedRows([...(record?.relationships ?? []), ...heritage]).join(',')}]}`;
+}
+function heritageByFile(graph, heritage) {
+    const filesByDeclaration = new Map();
+    for (const [file, record] of graph.files)
+        for (const key of record.declarations)
+            (filesByDeclaration.get(key) ?? filesByDeclaration.set(key, []).get(key)).push(file);
+    const grouped = new Map();
+    for (const relationship of heritage)
+        for (const file of filesByDeclaration.get(relationship.from) ?? [])
+            (grouped.get(file) ?? grouped.set(file, []).get(file)).push(relationship);
+    return grouped;
+}
+function fileGraph(graph, files) {
+    const replaced = new Set(files);
+    const declarations = graph.declarations.filter((declaration) => replaced.has(declaration.file));
+    const keys = new Set(declarations.map((declaration) => declaration.key));
+    const relationships = graph.relationships.filter((relationship) => keys.has(relationship.from) || keys.has(relationship.to));
+    const externalKeys = new Set(relationships.filter((relationship) => relationship.target === 'External').map((relationship) => relationship.to));
+    return { declarations, externals: graph.externals.filter((external) => externalKeys.has(external.key)), relationships };
+}
+function built(index, graph, durationMs) {
+    const receipt = receiptFor(graph);
+    return {
+        graph: index.graph,
+        heritage: index.relationships,
+        receipt: {
+            ...receipt,
+            internalSites: index.graph.internalSites,
+            unresolvedOccurrences: index.graph.unresolvedOccurrences,
+            dispatchCalls: index.dispatchCalls,
+            durationMs,
+        },
+    };
+}
+function receiptFor(graph) {
+    const relationships = Object.fromEntries(['CONTAINS', 'REFERENCES', 'CALLS', 'IMPLEMENTS', 'EXTENDS', 'TYPE_MENTION', 'IMPORTS', 'EXPORTS', 'CHANGED', 'RENAMED_FROM'].map((type) => [type, 0]));
+    for (const relationship of graph.relationships)
+        relationships[relationship.type]++;
+    return { declarations: graph.declarations.length, externals: graph.externals.length, commits: graph.commits?.length ?? 0, relationships };
+}
+export function graphFingerprint(graph) {
+    const commits = graph.commits === undefined ? '' : `,"commits":[${serializedRows(graph.commits).join(',')}]`;
+    return `{"declarations":[${serializedRows(graph.declarations).join(',')}],"externals":[${serializedRows(graph.externals).join(',')}]${commits},"relationships":[${serializedRows(graph.relationships).join(',')}]}`;
+}
+function serializedRows(rows) {
+    return rows.map((row) => JSON.stringify(row)).sort((left, right) => left.localeCompare(right));
+}
+function headCommit(root) {
+    try {
+        return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/index/scope.d.ts

@@ -0,0 +1,4 @@
+import { type DescriptorScope, type KeyedDeclaration } from './descriptor.js';
+export declare function isIndexedDeclaration(declaration: KeyedDeclaration): boolean;
+export declare function indexedDeclarations(file: string, text: string): KeyedDeclaration[];
+export declare function scopeOf(declaration: KeyedDeclaration): DescriptorScope;

package/dist/index/scope.js

@@ -0,0 +1,21 @@
+import { describeFile } from './descriptor.js';
+export function isIndexedDeclaration(declaration) {
+    switch (declaration.scope) {
+        case 'module':
+        case 'top-level':
+        case 'named-member':
+        case 'function-local':
+            return true;
+        case 'anonymous-expression':
+            return declaration.ownsCallSite;
+        case 'excluded':
+        case 'other':
+            return false;
+    }
+}
+export function indexedDeclarations(file, text) {
+    return describeFile(file, text).filter(isIndexedDeclaration);
+}
+export function scopeOf(declaration) {
+    return declaration.scope;
+}

package/dist/index/state.d.ts

@@ -0,0 +1,22 @@
+import type { BuiltIndex } from './build.js';
+export type IndexStatus = 'current' | 'indexing' | 'stale';
+export interface IndexSnapshot {
+    indexedAt: string;
+    state: IndexStatus;
+    built: BuiltIndex;
+}
+/** Serializes index rebuilds and exposes only a completed index to store readers. */
+export declare class IndexStateController {
+    private readonly publish;
+    private snapshot;
+    private pending;
+    private startStale;
+    private staleGeneration;
+    constructor(initial: IndexSnapshot, publish: (snapshot: IndexSnapshot) => void);
+    current(): IndexSnapshot;
+    markStale(start: () => Promise<void>): void;
+    rebuild(work: () => Promise<IndexSnapshot>): Promise<void>;
+    /** Resolves against a completed index, forcing the watcher's pending batch rather than waiting out its debounce. */
+    wait(): Promise<IndexSnapshot>;
+    private set;
+}

package/dist/index/state.js

@@ -0,0 +1,63 @@
+/** Serializes index rebuilds and exposes only a completed index to store readers. */
+export class IndexStateController {
+    publish;
+    snapshot;
+    pending;
+    startStale;
+    staleGeneration = 0;
+    constructor(initial, publish) {
+        this.publish = publish;
+        this.snapshot = initial;
+        publish(initial);
+    }
+    current() { return this.snapshot; }
+    markStale(start) {
+        this.staleGeneration++;
+        this.startStale = start;
+        if (!this.pending)
+            this.set({ ...this.snapshot, state: 'stale' });
+    }
+    rebuild(work) {
+        const run = async () => {
+            const generation = this.staleGeneration;
+            this.set({ ...this.snapshot, state: 'indexing' });
+            try {
+                const next = await work();
+                if (generation !== this.staleGeneration)
+                    this.set({ ...next, state: 'stale' });
+                else {
+                    this.startStale = undefined;
+                    this.set(next);
+                }
+            }
+            catch (error) {
+                this.set({ ...this.snapshot, state: 'stale' });
+                throw error;
+            }
+        };
+        const previous = this.pending ?? Promise.resolve();
+        const tracked = previous.then(run, run).finally(() => { if (this.pending === tracked)
+            this.pending = undefined; });
+        this.pending = tracked;
+        return tracked;
+    }
+    /** Resolves against a completed index, forcing the watcher's pending batch rather than waiting out its debounce. */
+    async wait() {
+        for (;;) {
+            if (this.snapshot.state === 'stale') {
+                const start = this.startStale;
+                if (!start)
+                    throw new Error('The index is stale and no rebuild is scheduled.');
+                await start();
+            }
+            else if (this.pending)
+                await this.pending;
+            else
+                return this.snapshot;
+        }
+    }
+    set(snapshot) {
+        this.snapshot = snapshot;
+        this.publish(snapshot);
+    }
+}

package/dist/index/walk.d.ts

@@ -0,0 +1,23 @@
+import { type Checker, type Project } from 'typescript/unstable/sync';
+import * as ts from '../ts7/ast.js';
+import { Ts7Host } from '../ts7/api.js';
+import { ConfiguredProjects } from '../ts7/projects.js';
+import { type KeyedDeclaration } from './descriptor.js';
+import type { IndexGraph } from './graph.js';
+export interface WalkFileState {
+    absolute: string;
+    file: string;
+    source: ts.SourceFile;
+    project: Project;
+    checker: Checker;
+    descriptors: readonly KeyedDeclaration[];
+    indexed: readonly KeyedDeclaration[];
+    byStart: ReadonlyMap<number, KeyedDeclaration>;
+    nodesByStart: ReadonlyMap<number, ts.Node>;
+    ownersByStart: ReadonlyMap<number, KeyedDeclaration>;
+    semanticNodes: readonly ts.Node[];
+    typeIdentifierPositions: ReadonlySet<number>;
+}
+/** Returns the snapshot-backed file state created by walkIndex for heritage enrichment. */
+export declare function walkFileStates(graph: IndexGraph): readonly WalkFileState[];
+export declare function walkIndex(root: string, program: Ts7Host, projects: ConfiguredProjects): IndexGraph;