@crouton-kit/tsym 0.1.0

package/dist/index/watch.js

@@ -0,0 +1,175 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, statSync, watch } from 'node:fs';
+import path from 'node:path';
+import { discoverDirectories, isProgramFileCandidate, skippedDirectories } from '../ts7/projects.js';
+/** Watches configured source directories; events supply text changes, never semantic invalidation. */
+export function watchIndex(root, projects, refresh, reportError, markStale) {
+    let knownFiles = new Set();
+    let knownDirectories = new Set();
+    let rootWatcher;
+    let gitWatcher;
+    let timer;
+    let firstEventAt;
+    let invalidated = false;
+    let full = false;
+    let git = false;
+    const events = new Map();
+    let chain = Promise.resolve();
+    const debounceMs = configuredDebounceMs();
+    const resetDirectories = () => {
+        gitWatcher?.close();
+        const sourceFiles = projects.records().flatMap((project) => [...project.files]);
+        const configs = projects.records().map((project) => project.config);
+        // Configs are known files: rewriting one is a change, and calling it a creation leaves TypeScript on the stale config.
+        knownFiles = new Set([...sourceFiles, ...configs]);
+        knownDirectories = new Set(discoverDirectories(root));
+        gitWatcher = watchGit(root, () => { git = true; invalidate(); });
+    };
+    const onRootEvent = (_event, name) => {
+        // Deleting the root arrives as one event named after the root itself, which no file filter below would keep.
+        if (name === null || !existsSync(root)) {
+            invalidate();
+            return;
+        }
+        const file = path.resolve(root, name.toString());
+        const relative = path.relative(root, file);
+        if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) || relative.split(path.sep).some((part) => skippedDirectories.has(part)))
+            return;
+        // fs.watch reports renames for a directory move and does not enumerate every moved child.
+        if (isDirectory(file) || knownDirectories.has(file) || [...knownFiles].some((known) => known.startsWith(`${file}${path.sep}`))) {
+            invalidate();
+            return;
+        }
+        const known = knownFiles.has(file);
+        if (!known && !isProgramFileCandidate(file))
+            return;
+        const configuration = path.basename(file) === 'tsconfig.json' || path.basename(file) === 'package.json';
+        // A membership change needs the full path, which resets knownFiles from the reloaded project records.
+        if (existsSync(file))
+            record(file, known ? 'changed' : 'created', configuration || !known);
+        else
+            record(file, 'deleted', configuration || known);
+    };
+    function record(file, event, requiresFull) {
+        if (event === 'created')
+            knownFiles.add(file);
+        events.set(file, event);
+        schedule(requiresFull);
+    }
+    function invalidate() {
+        invalidated = true;
+        schedule(true);
+    }
+    /** Marks the index stale on a batch's first event and debounces the flush that clears it. */
+    function schedule(requiresFull) {
+        full ||= requiresFull;
+        const now = Date.now();
+        if (firstEventAt === undefined)
+            markStale(flush);
+        firstEventAt ??= now;
+        if (timer)
+            clearTimeout(timer);
+        const cap = Math.max(0, 5_000 - (now - firstEventAt));
+        timer = setTimeout(() => { void flush(); }, Math.min(debounceMs, cap));
+        timer.unref();
+    }
+    /** Refreshes whatever has accumulated and resolves when every batch queued so far has been applied. */
+    function flush() {
+        if (timer)
+            clearTimeout(timer);
+        timer = undefined;
+        if (!invalidated && events.size === 0)
+            return chain;
+        const batch = {
+            fileChanges: invalidated ? { invalidateAll: true } : { changed: files('changed'), created: files('created'), deleted: files('deleted') },
+            full,
+            git,
+        };
+        invalidated = false;
+        full = false;
+        git = false;
+        events.clear();
+        firstEventAt = undefined;
+        chain = chain.then(() => refresh(batch), () => refresh(batch));
+        void chain.catch(reportError);
+        return chain;
+    }
+    function files(event) {
+        return [...events].filter(([, recorded]) => recorded === event).map(([file]) => file);
+    }
+    resetDirectories();
+    rootWatcher = watch(root, { recursive: true }, onRootEvent);
+    return {
+        close() {
+            if (timer)
+                clearTimeout(timer);
+            rootWatcher?.close();
+            gitWatcher?.close();
+        },
+        refresh: resetDirectories,
+    };
+}
+function isDirectory(file) {
+    try {
+        return statSync(file).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function watchGit(root, changed) {
+    let state = gitState(root);
+    const gitDir = gitPath(root, '--git-dir');
+    const commonDir = gitPath(root, '--git-common-dir');
+    let watchers = [];
+    const bind = () => {
+        for (const watcher of watchers)
+            watcher.close();
+        const paths = new Set([
+            gitDir === undefined ? undefined : path.join(gitDir, 'HEAD'),
+            commonDir === undefined ? undefined : path.join(commonDir, 'packed-refs'),
+            commonDir === undefined ? undefined : path.join(commonDir, 'refs', 'heads'),
+            commonDir === undefined || state.ref === undefined ? undefined : path.dirname(path.join(commonDir, state.ref)),
+            commonDir === undefined || state.ref === undefined ? undefined : path.join(commonDir, state.ref),
+        ].filter((target) => target !== undefined));
+        watchers = [];
+        for (const target of paths) {
+            if (!existsSync(target))
+                continue;
+            try {
+                watchers.push(watch(target, check));
+            }
+            catch { /* A ref can disappear while its branch changes; the remaining watcher reconnects when HEAD moves. */ }
+        }
+    };
+    const check = () => {
+        const next = gitState(root);
+        if (next.head === state.head && next.ref === state.ref)
+            return;
+        state = next;
+        bind();
+        changed();
+    };
+    bind();
+    return { close: () => { for (const watcher of watchers)
+            watcher.close(); } };
+}
+function gitState(root) {
+    return { head: gitOutput(root, ['rev-parse', 'HEAD']), ref: gitOutput(root, ['symbolic-ref', '-q', 'HEAD']) };
+}
+function gitPath(root, value) {
+    const output = gitOutput(root, ['rev-parse', value]);
+    return output === undefined ? undefined : path.resolve(root, output);
+}
+function gitOutput(root, args) {
+    try {
+        return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function configuredDebounceMs() {
+    const value = process.env.TSYM_DEBOUNCE_MS;
+    return value !== undefined && /^\d+$/.test(value) ? Number(value) : 300;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { parseInvocation } from './commands/tree.js';
+export { renderCompletion } from './output.js';
+export type { Answer, Completion, Invocation, InvocationError, ToolError } from './commands/types.js';
+export type { Graph, GraphEdge, GraphNode, RelationRow, TraversalResult } from './relations/types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { parseInvocation } from './commands/tree.js';
+export { renderCompletion } from './output.js';

package/dist/output.d.ts

@@ -0,0 +1,12 @@
+import type { Completion, OutputNode } from './commands/types.js';
+/** Assembles chrome — help and error blocks — whose body is already rendered markup. Answer data goes through renderNode instead. */
+export declare function xml(name: string, attributes?: Record<string, string | number | boolean | undefined>, body?: string): string;
+/** Output is XML-shaped prose for an agent, never parsed as XML; only a double quote inside an attribute value is escaped, so the value's boundary stays readable. */
+export declare function escapeAttribute(value: string): string;
+export declare function renderCompletion(completion: Completion, json: boolean): {
+    stdout: string;
+    stderr: string;
+    exitCode: 0 | 1 | 2 | 3;
+};
+export declare function completionCode(completion: Completion): 0 | 1 | 2 | 3;
+export declare function renderNode(node: OutputNode): string;

package/dist/output.js

@@ -0,0 +1,54 @@
+/** Assembles chrome — help and error blocks — whose body is already rendered markup. Answer data goes through renderNode instead. */
+export function xml(name, attributes = {}, body = '') {
+    const rendered = Object.entries(attributes).filter(([, value]) => value !== undefined).map(([key, value]) => ` ${key}="${escapeAttribute(String(value))}"`).join('');
+    return body === '' ? `<${name}${rendered}/>` : `<${name}${rendered}>\n${body}\n</${name}>`;
+}
+/** Output is XML-shaped prose for an agent, never parsed as XML; only a double quote inside an attribute value is escaped, so the value's boundary stays readable. */
+export function escapeAttribute(value) { return value.replace(/"/g, '&quot;'); }
+export function renderCompletion(completion, json) {
+    const exitCode = completionCode(completion);
+    const payload = json ? JSON.stringify(completion) + '\n' : render(completion) + '\n';
+    const stdout = payload;
+    const stderr = receipt(completion);
+    return { stdout, stderr, exitCode };
+}
+export function completionCode(completion) {
+    if (isAnswer(completion))
+        return completion.count > 0 ? 0 : 1;
+    if (completion.category === 'invocation')
+        return 2;
+    return 3;
+}
+function render(completion) {
+    if (isAnswer(completion))
+        return nodes(completion.data);
+    if (completion.category === 'invocation')
+        return renderInvocationError(completion);
+    return renderToolError(completion);
+}
+function nodes(data) { return (Array.isArray(data) ? data : [data]).map(renderNode).join('\n'); }
+export function renderNode(node) {
+    const attributes = Object.entries(node.attributes ?? {}).filter(([, value]) => value !== undefined).map(([key, value]) => ` ${key}="${escapeAttribute(String(value))}"`).join('');
+    const body = [node.text ?? '', ...(node.children ?? []).map(renderNode)].filter(Boolean).join('\n');
+    return body === '' ? `<${node.element}${attributes}/>` : `<${node.element}${attributes}>\n${body}\n</${node.element}>`;
+}
+function renderInvocationError(error) {
+    const body = error.problems.map((problem) => {
+        const expected = problem.expected.endsWith('.') ? problem.expected : `${problem.expected}.`;
+        return `${problem.field}: received ${problem.received}; expected ${expected}\nNext: ${problem.next ?? ''}`;
+    }).join('\n');
+    return xml('error', { code: error.code }, body);
+}
+function renderToolError(error) {
+    const lines = [error.message, error.received ? `received: ${error.received}` : null, error.expected ? `expected: ${error.expected}` : null, error.logPath ? `log: ${error.logPath}` : null, error.next ? `Next: ${error.next}` : null].filter((line) => line !== null);
+    return xml('error', { code: error.code, ...error.attributes }, lines.join('\n'));
+}
+function receipt(completion) {
+    if (isAnswer(completion)) {
+        const answer = completion;
+        const base = answer.receipt ?? `${answer.count} answer${answer.count === 1 ? '' : 's'}, 0 ms`;
+        return answer.startupMs === undefined ? base : `${base} (server started, ${answer.startupMs} ms)`;
+    }
+    return completion.category === 'invocation' ? `invocation rejected, 0 ms` : `tool failed, 0 ms`;
+}
+function isAnswer(completion) { return !('category' in completion); }

package/dist/read/read.d.ts

@@ -0,0 +1,32 @@
+import type { SemanticContext } from '../server/context.js';
+export interface Position {
+    line: number;
+    offset: number;
+}
+export interface Span {
+    start: Position;
+    end: Position;
+}
+export interface ReadSymbol {
+    address: string;
+    path: string;
+    name: string;
+    qualifiedName: string;
+    kind: string;
+    exported: boolean;
+    span: Span;
+    children: ReadSymbol[];
+}
+export declare function displayPath(root: string, file: string): string;
+export declare function positionOffset(source: string, position: Position): number;
+export declare function lineCount(source: string, span: Span): number;
+export declare function isContainer(symbol: ReadSymbol): boolean;
+export declare function keep(symbol: ReadSymbol, flags: Record<string, boolean | number | string | string[]>): boolean;
+/** Operands resolve from the client cwd; an empty operand list means the workspace root. */
+export declare function scopeFiles(context: SemanticContext, cwd: string, inputs: readonly string[]): Promise<{
+    files: string[];
+    notInProgram: number;
+}>;
+export declare function sourceSpan(source: string, span: Span): string;
+export declare function declarationText(source: string, span: Span, kind: string): string;
+export declare function normalKind(kind: string): string;

package/dist/read/read.js

@@ -0,0 +1,89 @@
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { DeclarationError } from '../core/declarations.js';
+import { matchesPathFilters } from '../core/receipt.js';
+import { openWorkspace } from '../core/workspace.js';
+const containers = new Set(['class', 'interface', 'enum', 'namespace']);
+const extensions = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs']);
+export function displayPath(root, file) { return path.relative(root, file).split(path.sep).join('/'); }
+export function positionOffset(source, position) {
+    let line = 1;
+    let offset = 0;
+    while (line < position.line && offset < source.length) {
+        const newline = source.indexOf('\n', offset);
+        offset = newline < 0 ? source.length : newline + 1;
+        line++;
+    }
+    return offset + position.offset - 1;
+}
+export function lineCount(source, span) {
+    const start = positionOffset(source, span.start);
+    const end = positionOffset(source, span.end);
+    return source.slice(start, end).split('\n').length - (end > start && source[end - 1] === '\n' ? 1 : 0);
+}
+export function isContainer(symbol) { return containers.has(symbol.kind); }
+export function keep(symbol, flags) {
+    const kinds = flags['--kind'];
+    return (!kinds || kinds.includes(symbol.kind)) && (flags['--exported'] !== true || symbol.exported) && matchesPathFilters(symbol.path, { in: flags['--in'], exclude: flags['--exclude'] });
+}
+/** Operands resolve from the client cwd; an empty operand list means the workspace root. */
+export async function scopeFiles(context, cwd, inputs) {
+    const workspace = openWorkspace(context.root);
+    const listed = workspace.files().filter((file) => extensions.has(path.extname(file)));
+    const selected = new Set();
+    for (const input of inputs.length === 0 ? [context.root] : inputs) {
+        const absolute = path.resolve(cwd, input);
+        const relative = displayPath(context.root, absolute);
+        const glob = /[*?[{]/.test(input);
+        if (existsSync(absolute)) {
+            const stat = statSync(absolute);
+            if (stat.isFile()) {
+                if (!extensions.has(path.extname(absolute)))
+                    throw new DeclarationError('not-in-program', `${input} is not a TypeScript-family source file`);
+                const membership = await context.projects.membership(absolute);
+                if (!membership)
+                    throw new DeclarationError('not-in-program', `${input} exists but is not part of a TypeScript project under ${context.root}`);
+                selected.add(displayPath(context.root, absolute));
+            }
+            else if (stat.isDirectory()) {
+                for (const file of listed)
+                    if (relative === '' || file === relative || file.startsWith(`${relative.replace(/\/$/, '')}/`))
+                        selected.add(file);
+            }
+        }
+        else if (glob) {
+            for (const file of listed)
+                if (workspace.files(relative).includes(file))
+                    selected.add(file);
+        }
+        else
+            throw new DeclarationError('no-such-path', `${input} does not exist`);
+    }
+    let notInProgram = 0;
+    const files = [];
+    for (const relative of [...selected].sort()) {
+        const absolute = path.join(context.root, relative);
+        if (await context.projects.membership(absolute))
+            files.push(absolute);
+        else
+            notInProgram++;
+    }
+    return { files, notInProgram };
+}
+export function sourceSpan(source, span) { return source.slice(positionOffset(source, span.start), positionOffset(source, span.end)); }
+export function declarationText(source, span, kind) {
+    if (!['const', 'let', 'var'].includes(kind))
+        return sourceSpan(source, span);
+    const start = positionOffset(source, span.start);
+    const lineStart = source.lastIndexOf('\n', start - 1) + 1;
+    const prefix = source.slice(lineStart, start);
+    const end = positionOffset(source, span.end);
+    const statementEnd = source.indexOf(';', end);
+    return /^(\s*)(?:export\s+)?(?:declare\s+)?(?:const|let|var)\b/.test(prefix) ? source.slice(lineStart, statementEnd < 0 ? end : statementEnd + 1) : sourceSpan(source, span);
+}
+export function normalKind(kind) {
+    const declarations = { FunctionDeclaration: 'function', ClassDeclaration: 'class', InterfaceDeclaration: 'interface', TypeAliasDeclaration: 'type', EnumDeclaration: 'enum', VariableDeclaration: 'const', MethodDeclaration: 'method', PropertyDeclaration: 'property', GetAccessor: 'getter', SetAccessor: 'setter', Constructor: 'constructor', ModuleDeclaration: 'module', ImportSpecifier: 'alias', ExportSpecifier: 'alias' };
+    if (kind === 'alias' || kind === 'enum member')
+        return kind === 'enum member' ? 'property' : kind;
+    return declarations[kind] ?? kind;
+}

package/dist/relations/graph.d.ts

@@ -0,0 +1,23 @@
+import type { Graph, GraphNode, RelationRow, TraversalResult, UnresolvedSite } from './types.js';
+import type { Direction, EdgeKind } from './types.js';
+export declare class GraphBuilder {
+    readonly nodes: Map<string, GraphNode>;
+    private readonly edges;
+    private readonly unresolved;
+    addNode(node: GraphNode): void;
+    addEdge(from: string, to: string, kind: EdgeKind, siteId: string): void;
+    addUnresolved(site: UnresolvedSite): void;
+    build(): Graph;
+}
+/** Remove excluded declarations, then retain only declarations still reachable from surviving seeds. */
+export declare function graphAfterExclusion(graph: Graph, exclude: readonly string[], direction: Direction): Graph;
+/** Keep returned rows, seeds, and every declaration connecting a seed to a returned row. */
+export declare function graphForItems(graph: Graph, rowIds: ReadonlySet<string>, direction: Direction): Graph;
+export declare function projectGraph(graph: Graph, direction: Direction, inGlobs: readonly string[]): TraversalResult;
+export declare function mergeGraphs(graphs: readonly Graph[]): Graph;
+export declare function rowsForGraph(graph: Graph, direction: Direction): RelationRow[];
+export declare function traversalLinks(graph: Graph, allowed: ReadonlySet<string>, direction: Direction): {
+    children: Map<string, string[]>;
+    parents: Map<string, string[]>;
+};
+export declare function selectGraph(graph: Graph, ids: ReadonlySet<string>): Graph;

package/dist/relations/graph.js

@@ -0,0 +1,115 @@
+import { matchesPathFilters } from '../core/receipt.js';
+export class GraphBuilder {
+    nodes = new Map();
+    edges = new Map();
+    unresolved = new Map();
+    addNode(node) {
+        const prior = this.nodes.get(node.id);
+        if (!prior || node.depth < prior.depth)
+            this.nodes.set(node.id, node);
+    }
+    addEdge(from, to, kind, siteId) {
+        const key = `${from}\0${to}\0${kind}`;
+        const edge = this.edges.get(key) ?? { from, to, kind, siteIds: new Set() };
+        edge.siteIds.add(siteId);
+        this.edges.set(key, edge);
+    }
+    addUnresolved(site) { this.unresolved.set(site.siteId, site); }
+    build() {
+        return {
+            nodes: [...this.nodes.values()].sort(compareNodes),
+            edges: [...this.edges.values()].map((edge) => ({ ...edge, siteIds: [...edge.siteIds].sort(), callSites: edge.siteIds.size })).sort(compareEdges),
+            unresolved: [...this.unresolved.values()].sort(compareUnresolved),
+        };
+    }
+}
+/** Remove excluded declarations, then retain only declarations still reachable from surviving seeds. */
+export function graphAfterExclusion(graph, exclude, direction) {
+    const allowed = new Set(graph.nodes.filter((node) => matchesPathFilters(node.path, { exclude })).map((node) => node.id));
+    const links = traversalLinks(graph, allowed, direction);
+    const kept = new Set(graph.nodes.filter((node) => node.depth === 0 && allowed.has(node.id)).map((node) => node.id));
+    const queue = [...kept];
+    for (let index = 0; index < queue.length; index++)
+        for (const child of links.children.get(queue[index]) ?? [])
+            if (!kept.has(child)) {
+                kept.add(child);
+                queue.push(child);
+            }
+    return selectGraph(graph, kept);
+}
+/** Keep returned rows, seeds, and every declaration connecting a seed to a returned row. */
+export function graphForItems(graph, rowIds, direction) {
+    const ids = new Set(graph.nodes.map((node) => node.id));
+    const links = traversalLinks(graph, ids, direction);
+    const kept = new Set(graph.nodes.filter((node) => node.depth === 0).map((node) => node.id));
+    const queue = [...rowIds].filter((id) => ids.has(id));
+    for (let index = 0; index < queue.length; index++) {
+        const id = queue[index];
+        if (kept.has(id))
+            continue;
+        kept.add(id);
+        for (const parent of links.parents.get(id) ?? [])
+            queue.push(parent);
+    }
+    const selected = selectGraph(graph, kept);
+    return { ...selected, nodes: selected.nodes.map((node) => node.depth === 0 || rowIds.has(node.id) ? withoutConnecting(node) : { ...node, connecting: true }) };
+}
+export function projectGraph(graph, direction, inGlobs) {
+    const preProjection = graph.nodes.filter((node) => node.depth > 0).length;
+    const rowIds = new Set(graph.nodes.filter((node) => node.depth > 0 && matchesPathFilters(node.path, { in: inGlobs })).map((node) => node.id));
+    const projected = graphForItems(graph, rowIds, direction);
+    const rows = rowsForGraph(projected, direction);
+    const unresolved = projected.unresolved.length;
+    const dispatch = new Set([
+        ...projected.unresolved.filter((site) => site.dispatch).map((site) => site.siteId),
+        ...projected.edges.filter((edge) => edge.kind === 'impl').flatMap((edge) => edge.siteIds),
+    ]).size;
+    return { graph: projected, rows, excluded: preProjection - rows.length, unresolved, dispatch };
+}
+export function mergeGraphs(graphs) {
+    const builder = new GraphBuilder();
+    for (const graph of graphs) {
+        for (const node of graph.nodes) {
+            const prior = builder.nodes.get(node.id);
+            const connecting = node.connecting && prior?.connecting;
+            builder.addNode(connecting ? { ...node, connecting: true } : withoutConnecting(node));
+        }
+        for (const edge of graph.edges)
+            for (const siteId of edge.siteIds)
+                builder.addEdge(edge.from, edge.to, edge.kind, siteId);
+        for (const site of graph.unresolved)
+            builder.addUnresolved(site);
+    }
+    return builder.build();
+}
+export function rowsForGraph(graph, direction) {
+    const rows = new Map();
+    for (const node of graph.nodes)
+        if (node.depth > 0 && !node.connecting)
+            rows.set(node.id, { ...node, callSites: 0, edgeKinds: [] });
+    for (const edge of graph.edges) {
+        const row = rows.get(direction === 'calls' ? edge.to : edge.from);
+        if (!row)
+            continue;
+        row.callSites += edge.callSites;
+        row.edgeKinds = [...new Set([...row.edgeKinds, edge.kind])];
+    }
+    return [...rows.values()].sort(compareRows);
+}
+export function traversalLinks(graph, allowed, direction) {
+    const children = new Map();
+    const parents = new Map();
+    const link = (parent, child) => { children.set(parent, [...(children.get(parent) ?? []), child]); parents.set(child, [...(parents.get(child) ?? []), parent]); };
+    for (const edge of graph.edges)
+        if (allowed.has(edge.from) && allowed.has(edge.to))
+            direction === 'calls' ? link(edge.from, edge.to) : link(edge.to, edge.from);
+    return { children, parents };
+}
+export function selectGraph(graph, ids) {
+    return { nodes: graph.nodes.filter((node) => ids.has(node.id)), edges: graph.edges.filter((edge) => ids.has(edge.from) && ids.has(edge.to)), unresolved: graph.unresolved.filter((site) => ids.has(site.from)) };
+}
+function withoutConnecting(node) { const { connecting: _connecting, ...rest } = node; return rest; }
+function compareNodes(a, b) { return a.depth - b.depth || a.id.localeCompare(b.id); }
+function compareEdges(a, b) { return a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.kind.localeCompare(b.kind); }
+function compareUnresolved(a, b) { return a.siteId.localeCompare(b.siteId); }
+function compareRows(a, b) { return a.depth - b.depth || a.path.localeCompare(b.path) || a.start.line - b.start.line || a.start.col - b.start.col; }

package/dist/relations/mermaid.d.ts

@@ -0,0 +1,3 @@
+import type { Graph } from './types.js';
+/** Pure graph-to-Mermaid renderer. */
+export declare function renderGraph(graph: Graph): string;

package/dist/relations/mermaid.js

@@ -0,0 +1,37 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+/** Pure graph-to-Mermaid renderer. */
+export function renderGraph(graph) {
+    const lines = ['flowchart TD'];
+    const ids = new Map(graph.nodes.map((node) => [node.id, mermaidId(node.id)]));
+    const directories = new Map();
+    for (const node of graph.nodes) {
+        const directory = path.posix.dirname(node.path);
+        const nodes = directories.get(directory) ?? [];
+        nodes.push(node);
+        directories.set(directory, nodes);
+    }
+    for (const [directory, nodes] of [...directories].sort(([a], [b]) => a.localeCompare(b))) {
+        lines.push(`  subgraph ${mermaidId(`directory:${directory}`)}["${escape(directory)}"]`);
+        for (const node of nodes.sort((a, b) => a.id.localeCompare(b.id)))
+            lines.push(`    ${ids.get(node.id)}["${escape(node.qualifiedName)}<br/>${escape(node.id)}"]`);
+        lines.push('  end');
+    }
+    const connecting = graph.nodes.filter((node) => node.connecting).map((node) => ids.get(node.id));
+    if (connecting.length) {
+        lines.push('  classDef connecting stroke-dasharray: 5 5');
+        lines.push(`  class ${connecting.join(',')} connecting`);
+    }
+    for (const edge of graph.edges) {
+        const label = `${edge.kind === 'impl' ? 'impl' : ''}${edge.callSites > 1 ? `${edge.kind === 'impl' ? ' ' : ''}${edge.callSites}` : ''}`;
+        lines.push(`  ${ids.get(edge.from)} ${edge.kind === 'impl' ? '-.->' : '-->'}${label ? `|${label}|` : ''} ${ids.get(edge.to)}`);
+    }
+    const reasons = [...new Set(graph.unresolved.map((site) => site.reason))].sort();
+    for (const reason of reasons)
+        lines.push(`  unresolved_${reason}["${reason}"]`);
+    for (const site of graph.unresolved)
+        lines.push(`  ${ids.get(site.from)} -.-> unresolved_${site.reason}`);
+    return `${lines.join('\n')}\n`;
+}
+function mermaidId(value) { return `n_${createHash('sha256').update(value).digest('hex').slice(0, 16)}`; }
+function escape(value) { return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }

package/dist/relations/store-relations.d.ts

@@ -0,0 +1,20 @@
+import type { DeclarationRecord } from '../core/declarations.js';
+import type { SemanticContext } from '../server/context.js';
+import { type Direction, type TraversalResult } from './types.js';
+export interface ReferenceRow {
+    path: string;
+    line: number;
+    col: number;
+    kind: string;
+    qualifiedName: string;
+    role: string;
+}
+export declare function references(context: SemanticContext, record: DeclarationRecord, filters: {
+    in: readonly string[];
+    exclude: readonly string[];
+}): Promise<ReferenceRow[]>;
+export declare function implementations(context: SemanticContext, record: DeclarationRecord): Promise<DeclarationRecord[]>;
+export declare function traverse(context: SemanticContext, seeds: readonly DeclarationRecord[], direction: Direction, depth: number, filters: {
+    in: readonly string[];
+    exclude: readonly string[];
+}): Promise<TraversalResult>;