@crouton-kit/tsym 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silas Rhyneer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# tsym
+
+Symbol-level reading of a TypeScript codebase, from the compiler's own resolution.
+
+`tsym` answers questions about TypeScript symbols — where something is declared, what its type resolves to, who calls it, what it calls, what implements it — through a resident bundled TypeScript 7 process and its persisted index rather than by matching text. The answers come from the same program the compiler builds, so they can be acted on without re-reading files to confirm.
+
+Output is one named XML block on stdout per call, with a one-line receipt on stderr. It is written for agents first: `-h` on any command prints a machine-readable description of its arguments, flags, and output contract.
+
+## Install
+
+```bash
+npm install -g @crouton-kit/tsym
+```
+
+Requires Node 22.13 or newer (the resident server locks its per-workspace slot with `node:sqlite`).
+
+## Commands
+
+| Command | What it answers |
+| --- | --- |
+| `tsym outline` | Structure of a file, a directory, or the whole repository. |
+| `tsym find <name>` | The canonical address of a declaration. |
+| `tsym show <target>` | The declaration's source text. |
+| `tsym type <target>` | Resolved type, signature, and doc comment. |
+| `tsym inspect <target>` | References, callers, calls, and implementations. |
+| `tsym search <pattern>` | Structural syntax search (ast-grep patterns). |
+| `tsym check` | Semantic and syntactic diagnostics. |
+| `tsym rename <target> <new>` | Rename a symbol across the program. |
+| `tsym server` | Status, reload, and stop for the resident process. |
+
+Every printed `path:line:col` address is accepted by every symbol command, so an address from `find`, `outline`, or `inspect` can be passed straight to `show` or `type`.
+
+```bash
+tsym find reviveNode
+tsym inspect reviveNode --only callers --each 3
+tsym server status
+```
+
+## The resident server
+
+A semantic command starts one resident process per workspace root and leaves it running, so the second and later commands reuse the loaded program and persisted index. It exits on its own after an idle period. `tsym server status` reports the process, memory, bundled TypeScript 7 version, store path, indexed commit, selected-scope counts, files outside configured projects, index state, and last index duration; `tsym server reload` forces a full index rebuild after a branch switch or dependency install; `tsym server stop` ends it.
+
+The bundled TypeScript 7 process is always used, so `tsym` works in a checkout with no dependencies installed.
+
+## Using it from crtr
+
+`tsym` is available inside [crtr](https://www.npmjs.com/package/@north-light/crouter) as `crtr tsym` via the `tsym` plugin in the crouter official marketplace. The plugin passes through to this executable, so it must be on `PATH`.
+
+## License
+
+MIT

package/bin/tsym.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,89 @@
+import { renderHelp } from './commands/help.js';
+import { localSearch } from './commands/handlers/search.js';
+import { applyRenamePlan } from './commands/rename-apply.js';
+import { parseInvocation } from './commands/tree.js';
+import { renderCompletion, renderNode } from './output.js';
+import { invokeResident, serverReload, serverStatus, serverStop } from './server/client.js';
+import { discoverRoot, pathsForRoot, readState } from './server/lifecycle.js';
+import { readMetadata } from './store/meta.js';
+async function main(argv) {
+    const parsed = parseInvocation(argv);
+    if ('help' in parsed) {
+        const state = parsed.help.name === 'search' ? '' : helpState(rootFlag(argv));
+        process.stdout.write(renderHelp(parsed.help, state) + '\n');
+        process.stderr.write('1 answer, 0 ms\n');
+        return 0;
+    }
+    if ('category' in parsed)
+        return emit(parsed, false);
+    return emit(await dispatch(parsed), parsed.json);
+}
+async function dispatch(invocation) {
+    switch (invocation.declaration.handler) {
+        case 'server-status': return serverStatus(invocation.root);
+        case 'server-stop': return serverStop(invocation.root);
+        case 'server-reload': return serverReload(invocation.root);
+        case 'search': return localSearch(invocation);
+        case 'rename': return applyRename(invocation);
+        case 'query': return queryFromStdin(invocation);
+        default: return invokeResident(invocation);
+    }
+}
+async function queryFromStdin(invocation) {
+    if (invocation.input.args[0] !== '-')
+        return invokeResident(invocation);
+    if (process.stdin.isTTY)
+        return { category: 'invocation', code: 'usage', problems: [{ field: '<cypher>', received: '- with no piped input', expected: 'a query on stdin', next: 'Pipe the query or pass it as the positional argument.' }] };
+    invocation.input.args[0] = await readStdin();
+    return invokeResident(invocation);
+}
+async function readStdin() {
+    let text = '';
+    for await (const chunk of process.stdin)
+        text += chunk;
+    return text;
+}
+async function applyRename(invocation) {
+    const completion = await invokeResident(invocation);
+    if (invocation.input.flags['--apply'] !== true || !isRenameAnswer(completion))
+        return completion;
+    const applied = await applyRenamePlan(completion.renamePlan);
+    if ('category' in applied)
+        return applied;
+    const stamp = (node) => ({ ...node, attributes: { ...node.attributes, applied: true } });
+    return { ...completion, data: Array.isArray(completion.data) ? [stamp(completion.data[0]), ...completion.data.slice(1)] : stamp(completion.data) };
+}
+function isRenameAnswer(completion) { return !('category' in completion) && 'renamePlan' in completion; }
+function helpState(rootOverride) {
+    const root = discoverRoot(rootOverride);
+    const paths = pathsForRoot(root);
+    const state = readState(paths);
+    if (!state)
+        return '<server state="stopped"/>';
+    const metadata = readMetadata(paths.store);
+    return renderNode({ element: 'server', attributes: { root, state: state.state, indexedCommit: metadata?.indexedCommit, indexDuration: metadata === null ? undefined : `${Math.round(metadata.indexDurationMs)}ms`, index: state.index, declarations: state.declarations } });
+}
+function rootFlag(argv) {
+    for (let index = 0; index < argv.length; index++) {
+        if (argv[index] === '--root')
+            return argv[index + 1];
+        if (argv[index]?.startsWith('--root='))
+            return argv[index].slice('--root='.length);
+    }
+    return undefined;
+}
+function emit(completion, json) {
+    const rendered = renderCompletion(completion, json);
+    if (rendered.stdout)
+        process.stdout.write(rendered.stdout);
+    process.stderr.write(rendered.stderr.endsWith('\n') ? rendered.stderr : rendered.stderr + '\n');
+    return rendered.exitCode;
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
+    const completion = { category: 'tool', code: 'internal', message: error instanceof Error ? error.message : String(error) };
+    const rendered = renderCompletion(completion, false);
+    if (rendered.stdout)
+        process.stdout.write(rendered.stdout);
+    process.stderr.write(rendered.stderr.endsWith('\n') ? rendered.stderr : rendered.stderr + '\n');
+    process.exit(rendered.exitCode);
+});

package/dist/commands/handlers/check.d.ts

@@ -0,0 +1,3 @@
+import type { SemanticHandler } from '../handlers.js';
+declare const handler: SemanticHandler;
+export default handler;

package/dist/commands/handlers/check.js

@@ -0,0 +1,94 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { matchesGlob, Workspace } from '../../core/workspace.js';
+import { diagnosticsForFiles } from '../../ts7/checker.js';
+const handler = async (context, invocation) => {
+    const started = performance.now();
+    try {
+        await context.projects.bootstrap();
+        const paths = invocation.input.args;
+        const files = paths.length > 0 ? await explicitFiles(context, invocation, paths) : undefined;
+        const diagnostics = diagnosticsForFiles(context.program, context.root, await diagnosticScopes(context, files));
+        const filtered = finish(diagnostics, invocation);
+        const limit = invocation.input.flags['--limit'];
+        const shown = limit === undefined ? filtered : filtered.slice(0, limit);
+        const capped = shown.length < filtered.length;
+        const errors = filtered.filter((diagnostic) => diagnostic.severity === 'error').length;
+        const warnings = filtered.filter((diagnostic) => diagnostic.severity === 'warning').length;
+        const suggestions = filtered.filter((diagnostic) => diagnostic.severity === 'suggestion').length;
+        return {
+            data: { element: 'check', attributes: { scope: paths.length === 0 ? 'project' : paths.join(' '), count: filtered.length, shown: capped ? shown.length : undefined, errors, warnings, suggestions, ms: Math.round(performance.now() - started) }, children: shown.map(renderDiagnostic) },
+            count: filtered.length,
+            receipt: capped
+                ? `${shown.length} of ${filtered.length} check rows shown, limit ${limit}, ${Math.round(performance.now() - started)} ms`
+                : `${shown.length} diagnostic${shown.length === 1 ? '' : 's'}, ${Math.round(performance.now() - started)} ms`,
+        };
+    }
+    catch (error) {
+        return failure(error);
+    }
+};
+async function explicitFiles(context, invocation, inputs) {
+    const workspace = new Workspace(context.root, null, 'none');
+    const candidates = workspace.files().map((file) => path.join(context.root, file));
+    const files = [];
+    for (const input of inputs) {
+        const glob = hasGlob(input);
+        const matches = glob
+            ? candidates.filter((file) => matchesGlob(relative(invocation.cwd, file), input))
+            : [path.resolve(invocation.cwd, input)];
+        if (matches.length === 0 || !glob && !existsSync(matches[0]))
+            throw invocationFailure('no-such-path', `${input} does not exist.`, input, 'an existing TypeScript file or glob with matches');
+        for (const file of matches) {
+            if (!existsSync(file))
+                throw invocationFailure('no-such-path', `${input} does not exist.`, input, 'an existing TypeScript file');
+            if (!await context.projects.membership(file))
+                throw invocationFailure('not-in-program', `${relative(context.root, file)} exists but is not part of a TypeScript project under ${context.root}.`, input, 'a file listed by a project tsconfig.json');
+            if (!files.includes(file))
+                files.push(file);
+        }
+    }
+    return files;
+}
+async function diagnosticScopes(context, files) {
+    const candidates = files ?? [...new Set(context.projects.records().flatMap((project) => [...project.files]))];
+    const scopes = new Map();
+    for (const file of candidates) {
+        const project = await context.projects.membership(file);
+        if (!project)
+            continue;
+        const owned = scopes.get(project.config) ?? [];
+        owned.push(file);
+        scopes.set(project.config, owned);
+    }
+    return [...scopes].map(([config, owned]) => ({ config, files: owned }));
+}
+function finish(diagnostics, invocation) {
+    const errorsOnly = invocation.input.flags['--errors-only'] === true;
+    const include = invocation.input.flags['--in'] ?? [];
+    const exclude = invocation.input.flags['--exclude'] ?? [];
+    return diagnostics
+        .filter((diagnostic) => !errorsOnly || diagnostic.severity === 'error')
+        .filter((diagnostic) => (include.length === 0 || include.some((glob) => matchesGlob(diagnostic.file, glob))) && !exclude.some((glob) => matchesGlob(diagnostic.file, glob)))
+        .sort(compare);
+}
+function renderDiagnostic(diagnostic) {
+    return { element: 'diagnostic', attributes: { at: `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}`, severity: diagnostic.severity, code: diagnostic.code }, text: diagnostic.message };
+}
+function compare(left, right) {
+    return (left.file < right.file ? -1 : left.file > right.file ? 1 : 0) || left.line - right.line || left.column - right.column || left.code - right.code;
+}
+function hasGlob(value) { return /[*?[{]/.test(value); }
+function relative(root, file) { return path.relative(root, file).split(path.sep).join('/'); }
+function invocationFailure(code, message, _received, expected) {
+    return { category: 'invocation', code, problems: [{ field: 'path', received: message, expected, next: 'Pass a file listed by the loaded TypeScript project.' }] };
+}
+function failure(error) {
+    if (isCompletionError(error))
+        return error;
+    return { category: 'tool', code: 'typescript-error', message: 'TypeScript could not answer the diagnostic query.', received: error instanceof Error ? error.message : String(error), expected: 'successful TypeScript Program diagnostics', next: 'Read the server log, then retry.' };
+}
+function isCompletionError(value) {
+    return typeof value === 'object' && value !== null && 'category' in value;
+}
+export default handler;

package/dist/commands/handlers/find.d.ts

@@ -0,0 +1,3 @@
+import type { SemanticHandler } from '../handlers.js';
+declare const handler: SemanticHandler;
+export default handler;

package/dist/commands/handlers/find.js

@@ -0,0 +1,56 @@
+import { DeclarationError } from '../../core/declarations.js';
+import { matchesPathFilters } from '../../core/receipt.js';
+import { query } from '../../store/query.js';
+const handler = async (context, invocation) => {
+    await context.projects.bootstrap();
+    const started = performance.now();
+    const name = invocation.input.args[0];
+    const flags = invocation.input.flags;
+    const prefix = flags['--prefix'] === true;
+    const qualified = name.includes('.');
+    const rows = new Map();
+    for (const declaration of declarations(context)) {
+        const candidate = qualified ? declaration.qualifiedName : declaration.name;
+        if (declaration.kind === 'module' || !(prefix ? candidate.startsWith(name) : candidate === name) || !keep(declaration, flags))
+            continue;
+        rows.set(declaration.address, declaration);
+    }
+    for (const alias of aliases(context)) {
+        const candidate = alias.qualifiedName;
+        if (!(prefix ? candidate.startsWith(name) : candidate === name) || !keep(alias, flags))
+            continue;
+        rows.set(alias.address, alias);
+    }
+    const sorted = [...rows.values()].sort((a, b) => a.path.localeCompare(b.path) || numericAddress(a.address, b.address));
+    const limit = flags['--limit'];
+    const shown = limit === undefined ? sorted : sorted.slice(0, limit);
+    const capped = shown.length < sorted.length;
+    return {
+        data: { element: 'find', attributes: { name, count: sorted.length, shown: capped ? shown.length : undefined }, text: shown.map((row) => `${row.address}  ${row.kind}${row.exported ? '  export' : ''}  ${row.qualifiedName}`).join('\n') },
+        count: sorted.length,
+        receipt: capped ? `${shown.length} of ${sorted.length} find rows shown, limit ${limit}, ${Math.round(performance.now() - started)} ms` : `${shown.length} find row${shown.length === 1 ? '' : 's'}, ${Math.round(performance.now() - started)} ms`,
+    };
+};
+function declarations(context) {
+    if (!context.store)
+        throw new DeclarationError('not-in-program', 'The TypeScript index is not available yet.');
+    return query(context.store, 'MATCH (d:Declaration) RETURN d.at AS at, d.file AS file, d.kind AS kind, d.exported AS exported, d.name AS name, d.qname AS qname').map((row) => ({ address: String(row.at), path: String(row.file), kind: String(row.kind), exported: Boolean(row.exported), name: String(row.name), qualifiedName: String(row.qname) }));
+}
+function aliases(context) {
+    if (!context.store)
+        throw new DeclarationError('not-in-program', 'The TypeScript index is not available yet.');
+    return query(context.store, 'MATCH (m:Declaration)-[e:EXPORTS]->(d:Declaration) RETURN m.file AS fromFile, e.name AS name, e.line AS line, e.col AS col, d.file AS file, d.line AS declarationLine, d.col AS declarationCol').flatMap((row) => {
+        const fromFile = String(row.fromFile);
+        const line = Number(row.line);
+        const col = Number(row.col);
+        if (fromFile === String(row.file) && line === Number(row.declarationLine) && col === Number(row.declarationCol))
+            return [];
+        return [{ address: `${fromFile}:${line}:${col}`, path: fromFile, kind: 'alias', exported: true, name: String(row.name), qualifiedName: String(row.name) }];
+    });
+}
+function keep(row, flags) {
+    const kinds = flags['--kind'];
+    return (!kinds || kinds.includes(row.kind)) && matchesPathFilters(row.path, { in: flags['--in'], exclude: flags['--exclude'] });
+}
+function numericAddress(a, b) { const [aLine, aColumn] = a.split(':').slice(-2).map(Number); const [bLine, bColumn] = b.split(':').slice(-2).map(Number); return aLine - bLine || aColumn - bColumn; }
+export default handler;

package/dist/commands/handlers/inspect.d.ts

@@ -0,0 +1,3 @@
+import type { SemanticHandler } from '../handlers.js';
+declare const handler: SemanticHandler;
+export default handler;

package/dist/commands/handlers/inspect.js

@@ -0,0 +1,81 @@
+import { matchesPathFilters } from '../../core/receipt.js';
+import { normalKind } from '../../read/read.js';
+import { mergeGraphs } from '../../relations/graph.js';
+import { implementations, references, traverse } from '../../relations/store-relations.js';
+import { renderGraph } from '../../relations/mermaid.js';
+const relationOrder = ['refs', 'callers', 'calls', 'impl'];
+const handler = async (context, invocation) => {
+    const started = performance.now();
+    const selected = selectedRelations(invocation.input.flags['--only']);
+    const each = invocation.input.flags['--each'];
+    const depth = invocation.input.flags['--depth'];
+    const graphMode = invocation.input.flags['--graph'] === true;
+    const filters = { in: strings(invocation.input.flags['--in']), exclude: strings(invocation.input.flags['--exclude']) };
+    const seeds = await context.resolver.resolveAll(invocation.input.args);
+    if (graphMode)
+        return graphAnswer(context, seeds, selected, depth, filters, started);
+    const blocks = [];
+    let answers = 0;
+    const receiptParts = [];
+    for (const seed of seeds) {
+        const header = await signature(context, seed);
+        const relations = [];
+        for (const relation of selected) {
+            if (relation === 'refs') {
+                const rows = await references(context, seed, filters);
+                answers += rows.length;
+                relations.push(refBlock(rows, each));
+                receiptParts.push(`${rows.length} refs`);
+            }
+            else if (relation === 'impl') {
+                const rows = (await implementations(context, seed)).filter((item) => matchesPathFilters(item.location.path, filters));
+                answers += rows.length;
+                relations.push(implBlock(rows, each));
+                receiptParts.push(`${rows.length} impl`);
+            }
+            else {
+                const result = await traverse(context, [seed], relation, depth, filters);
+                answers += result.rows.length;
+                relations.push(traversalBlock(relation, result, each));
+                receiptParts.push(`${result.rows.length} ${relation}${result.excluded ? `, ${result.excluded} excluded` : ''}${result.unresolved ? `, ${result.unresolved} unresolved` : ''}${result.dispatch ? `, ${result.dispatch} dispatch` : ''}`);
+            }
+        }
+        blocks.push({ element: 'inspect', attributes: { symbol: seed.address, name: seed.name, kind: normalKind(seed.kind), depth }, text: header, children: relations });
+    }
+    const capped = selected.some((relation) => relation === 'refs' || relation === 'impl' || relation === 'calls' || relation === 'callers') && each > 0;
+    const rerun = capped ? `; re-run tsym inspect ${invocation.input.args.join(' ')} --only ${selected[0]} --each 0 for all rows` : '';
+    return { data: blocks, count: answers, receipt: `${invocation.input.args.map((input, index) => `${seeds[index].name}: ${receiptParts.slice(index * selected.length, (index + 1) * selected.length).join(', ')}`).join('; ')}, ${Math.round(performance.now() - started)} ms${rerun}` };
+};
+async function graphAnswer(context, seeds, selected, depth, filters, started) {
+    const relations = [];
+    for (const relation of selected)
+        if (relation === 'callers' || relation === 'calls')
+            relations.push(await traverse(context, seeds, relation, depth, filters));
+    const graph = mergeGraphs(relations.map((result) => result.graph));
+    const count = relations.reduce((sum, result) => sum + result.rows.length, 0);
+    const unresolved = new Set(graph.unresolved.map((site) => site.siteId)).size;
+    const dispatch = new Set([...graph.unresolved.filter((site) => site.dispatch).map((site) => site.siteId), ...graph.edges.filter((edge) => edge.kind === 'impl').flatMap((edge) => edge.siteIds)]).size;
+    const excluded = relations.reduce((sum, result) => sum + result.excluded, 0);
+    return { data: { element: 'inspect', attributes: { graph: true, count }, text: renderGraph(graph).replace(/\n$/, '') }, count, receipt: `${count} traversal rows${excluded ? `, ${excluded} excluded` : ''}${unresolved ? `, ${unresolved} unresolved` : ''}${dispatch ? `, ${dispatch} dispatch` : ''}, ${Math.round(performance.now() - started)} ms` };
+}
+async function signature(_context, record) { return `${normalKind(record.kind)} ${record.qualifiedName}`; }
+function relationBlock(element, rows, path, each, format) {
+    if (!rows.length)
+        return { element, attributes: { count: 0 } };
+    const shown = shownRows(rows, each);
+    return { element, attributes: { count: rows.length, files: new Set(rows.map(path)).size, shown: shown.length < rows.length ? shown.length : undefined }, text: shown.map(format).join('\n') };
+}
+function refBlock(rows, each) {
+    return relationBlock('refs', rows, (row) => row.path, each, (row) => `${row.path}:${row.line}:${row.col}  ${row.kind}  ${row.qualifiedName}  ${row.role}`);
+}
+function implBlock(rows, each) {
+    return relationBlock('impl', rows, (row) => row.location.path, each, (row) => `${row.address}  ${normalKind(row.kind)}  ${row.qualifiedName}`);
+}
+function traversalBlock(relation, result, each) {
+    return relationBlock(relation, result.rows, (row) => row.path, each, formatTraversal);
+}
+function formatTraversal(row) { return `${row.id}  ${row.depth}  ${normalKind(row.kind)}  ${row.qualifiedName}  (${row.callSites} ${row.callSites === 1 ? 'site' : 'sites'}${row.edgeKinds.includes('impl') ? ', impl' : ''})`; }
+function shownRows(rows, each) { return each === 0 ? rows : rows.slice(0, each); }
+function selectedRelations(value) { const values = Array.isArray(value) ? value : relationOrder; return relationOrder.filter((relation) => values.includes(relation)); }
+function strings(value) { return Array.isArray(value) ? value : value === undefined ? [] : [String(value)]; }
+export default handler;

package/dist/commands/handlers/outline.d.ts

@@ -0,0 +1,3 @@
+import type { SemanticHandler } from '../handlers.js';
+declare const handler: SemanticHandler;
+export default handler;

package/dist/commands/handlers/outline.js

@@ -0,0 +1,101 @@
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { DeclarationError } from '../../core/declarations.js';
+import { matchesPathFilters } from '../../core/receipt.js';
+import { displayPath, scopeFiles } from '../../read/read.js';
+import { query } from '../../store/query.js';
+const containers = new Set(['class', 'interface', 'enum', 'namespace']);
+const handler = async (context, invocation) => {
+    await context.projects.bootstrap();
+    const started = performance.now();
+    const flags = invocation.input.flags;
+    const depth = flags['--depth'];
+    const scope = await scopeFiles(context, invocation.cwd, invocation.input.args);
+    const selected = new Set(scope.files.map((file) => displayPath(context.root, file)).filter((file) => matchesPathFilters(file, { in: flags['--in'], exclude: flags['--exclude'] })));
+    const declarations = indexed(context).filter((declaration) => selected.has(declaration.path) && declaration.kind !== 'module');
+    const imports = flags['--imports'] === true && flags['--exported'] !== true && !flags['--kind'] ? indexedImports(context).filter((item) => selected.has(item.path)) : [];
+    const directory = invocation.input.args.length === 0 ? context.root : invocation.input.args.map((input) => path.resolve(invocation.cwd, input)).find((candidate) => {
+        try {
+            return statSync(candidate).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+    const requestedDirectory = directory !== undefined;
+    const files = new Map();
+    for (const declaration of declarations)
+        files.set(declaration.path, [...(files.get(declaration.path) ?? []), declaration]);
+    const importsByFile = new Map();
+    for (const item of imports) {
+        files.set(item.path, files.get(item.path) ?? []);
+        importsByFile.set(item.path, [...(importsByFile.get(item.path) ?? []), item]);
+    }
+    const rows = requestedDirectory && depth === 1
+        ? containerRows(context.root, files, importsByFile, flags, directory ?? context.root)
+        : [...files.entries()].flatMap(([file, items]) => [...select(items, flags, requestedDirectory ? depth - 1 : depth).map((symbol) => symbolRow(symbol, items, flags)), ...(importsByFile.get(file) ?? []).map(importRow)].sort(byPosition));
+    const limit = flags['--limit'];
+    const shown = limit === undefined ? rows : rows.slice(0, limit);
+    const capped = shown.length < rows.length;
+    const symbols = [...files.values()].flatMap((items) => select(items, flags, requestedDirectory ? depth - 1 : depth)).length + imports.length;
+    const receipt = `${capped ? `${shown.length} of ${rows.length} outline rows shown, limit ${limit}` : `${shown.length} outline row${shown.length === 1 ? '' : 's'}`}${scope.notInProgram > 0 ? `, ${scope.notInProgram} not in program` : ''}, ${Math.round(performance.now() - started)} ms`;
+    return { data: { element: 'outline', attributes: { path: invocation.input.args.join(' ') || '.', depth, symbols, files: files.size, count: rows.length, shown: capped ? shown.length : undefined }, text: shown.map((row) => row.text).join('\n') }, count: rows.length, receipt };
+};
+function indexed(context) {
+    if (!context.store)
+        throw new DeclarationError('not-in-program', 'The TypeScript index is not available yet.');
+    return query(context.store, 'MATCH (d:Declaration) RETURN d.key AS key, d.at AS at, d.name AS name, d.qname AS qname, d.kind AS kind, d.exported AS exported, d.file AS file, d.line AS line, d.col AS col, d.lines AS lines, d.container AS container').map(declaration);
+}
+function declaration(row) {
+    return { key: String(row.key), address: String(row.at), path: String(row.file), name: String(row.name), qualifiedName: String(row.qname), kind: String(row.kind), exported: Boolean(row.exported), line: Number(row.line), col: Number(row.col), lines: Number(row.lines), container: row.container === null ? null : String(row.container) };
+}
+function indexedImports(context) {
+    if (!context.store)
+        throw new DeclarationError('not-in-program', 'The TypeScript index is not available yet.');
+    return query(context.store, 'MATCH (m:Declaration)-[e:IMPORTS]->(d:Declaration) RETURN m.file AS file, e.line AS line, e.names AS names, d.file AS target UNION MATCH (m:Declaration)-[e:IMPORTS]->(external:External) RETURN m.file AS file, e.line AS line, e.names AS names, external.module AS target')
+        .map((row) => ({ path: String(row.file), line: Number(row.line), address: `${String(row.file)}:${Number(row.line)}:1`, name: String(row.names), target: String(row.target) }));
+}
+function select(items, flags, depth, members = flags['--members'] === true) {
+    const byContainer = new Map();
+    for (const item of items)
+        if (item.container)
+            byContainer.set(item.container, [...(byContainer.get(item.container) ?? []), item]);
+    const roots = items.filter((item) => item.container === `${item.path}#<module>`);
+    const out = [];
+    const visit = (item, remaining) => {
+        if (keep(item, flags))
+            out.push(item);
+        if ((containers.has(item.kind) && (members || remaining > 1)) || (item.kind === 'function' && !members && remaining > 1))
+            for (const child of byContainer.get(item.key) ?? [])
+                visit(child, members ? remaining : remaining - 1);
+    };
+    for (const item of roots)
+        visit(item, depth);
+    return out.sort(byPosition);
+}
+function keep(item, flags) {
+    const kinds = flags['--kind'];
+    return (!kinds || kinds.includes(item.kind)) && (flags['--exported'] !== true || item.exported);
+}
+function symbolRow(symbol, items, flags) {
+    const members = items.filter((item) => item.container === symbol.key && keep(item, flags)).length;
+    const memberCount = containers.has(symbol.kind) ? `, ${members} members` : '';
+    return { text: `${symbol.address}  ${symbol.kind}${symbol.exported ? '  export' : ''}  ${symbol.qualifiedName}  (${symbol.lines}L${memberCount})`, line: symbol.line, col: symbol.col };
+}
+function importRow(item) { return { text: `${item.address}  import  ${item.name}  ${item.target}`, line: item.line, col: 1 }; }
+function containerRows(root, files, imports, flags, directory) {
+    const grouped = new Map();
+    for (const [file, items] of files) {
+        const relative = path.relative(directory, path.join(root, file)).split(path.sep).join('/');
+        const parts = relative.split('/');
+        const name = parts.length === 1 ? file : `${displayPath(root, path.join(directory, parts[0]))}/`;
+        grouped.set(name, [...(grouped.get(name) ?? []), { file, items }]);
+    }
+    return [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([name, groups]) => {
+        const count = groups.reduce((total, group) => total + select(group.items, flags, 1).length + (imports.get(group.file)?.length ?? 0), 0);
+        const fileCount = groups.length;
+        return { text: `${name}  (${fileCount} ${fileCount === 1 ? 'file' : 'files'}, ${count} symbols)`, line: 0, col: 0 };
+    });
+}
+function byPosition(a, b) { return a.line - b.line || a.col - b.col; }
+export default handler;

package/dist/commands/handlers/query.d.ts

@@ -0,0 +1,3 @@
+import type { SemanticHandler } from '../handlers.js';
+declare const handler: SemanticHandler;
+export default handler;