@crouton-kit/tsym 0.1.0

package/dist/commands/handlers/query.js

@@ -0,0 +1,196 @@
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathsForRoot } from '../../server/lifecycle.js';
+import { ingestCommits } from '../../index/commits.js';
+import { query } from '../../store/query.js';
+const address = /^(.*):(\d+):(\d+)$/;
+const handler = async (context, invocation) => {
+    const cypher = invocation.input.args[0] ?? '';
+    if (cypher.trim() === '')
+        return rejected('cypher', 'an empty query', 'one non-empty Cypher statement', 'Pass a Cypher statement as the positional argument or pipe one to `tsym query -`.');
+    const bound = parametersFor(invocation);
+    if ('error' in bound)
+        return bound.error;
+    const parameters = bound.parameters;
+    if (invocation.input.flags['--since'] !== undefined) {
+        const commits = commitsSince(context.root, invocation.input.flags['--since']);
+        if (!Array.isArray(commits))
+            return commits;
+        if (!context.store)
+            throw new Error('The query leaf requires the resident store and index state.');
+        ingestCommits(context.root, context.store, commits);
+        parameters.commits = commits;
+    }
+    const { store, index } = context;
+    if (!store || !index)
+        throw new Error('The query leaf requires the resident store and index state.');
+    const started = performance.now();
+    let records;
+    try {
+        records = query(store, cypher, parameters);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'Interrupted.')
+            return { category: 'tool', code: 'query-timeout', message: error.message };
+        return rejected('cypher', error instanceof Error ? error.message : String(error), 'a Cypher statement accepted by LadybugDB', 'Correct the query using the engine message and retry.');
+    }
+    const ordered = hasTopLevelOrderBy(cypher) ? records : orderDefault(records);
+    const rows = ordered.map(renderRow);
+    const limit = invocation.input.flags['--rows'];
+    const shown = limit === 0 ? rows : rows.slice(0, limit);
+    const output = invocation.input.flags['--out'];
+    const complete = rows.join('\n');
+    const resultPath = output === undefined
+        ? shown.length < rows.length ? path.join(pathsForRoot(context.root).results, `${randomUUID()}.txt`) : undefined
+        : path.resolve(invocation.cwd, output);
+    if (resultPath !== undefined)
+        writeFileSync(resultPath, complete === '' ? '' : `${complete}\n`, { mode: 0o600 });
+    const unordered = !hasTopLevelOrderBy(cypher) && ordered.some((record) => addressFor(record) === undefined);
+    const elapsed = Math.round(performance.now() - started);
+    return {
+        data: {
+            element: 'query',
+            attributes: { rows: rows.length, shown: shown.length, indexedAt: index.indexedAt, state: index.state, ms: elapsed },
+            text: shown.join('\n'),
+            children: shown.length < rows.length && resultPath !== undefined
+                ? [{ element: 'truncated', attributes: { rows: rows.length, shown: shown.length, file: resultPath }, text: 'Re-run with --rows 0 for every row on stdout.' }]
+                : undefined,
+        },
+        count: rows.length,
+        receipt: `${shown.length} of ${rows.length} query row${rows.length === 1 ? '' : 's'}${unordered ? ', unordered' : ''}, ${elapsed} ms`,
+    };
+};
+function parametersFor(invocation) {
+    const values = {};
+    const problems = [];
+    const problem = (received, expected, next) => problems.push({ field: '--param', received, expected, next });
+    for (const raw of invocation.input.flags['--param'] ?? []) {
+        const separator = raw.indexOf('=');
+        if (separator <= 0) {
+            problem(raw, 'NAME=VALUE', 'Name the Cypher parameter before `=`.');
+            continue;
+        }
+        const name = raw.slice(0, separator);
+        if (!/^[_A-Za-z][_0-9A-Za-z]*$/.test(name)) {
+            problem(raw, 'NAME=VALUE with a Cypher parameter name', 'Use letters, digits, and underscores; the name cannot begin with a digit.');
+            continue;
+        }
+        if (name in values) {
+            problem(raw, `one binding for $${name}`, 'Bind each parameter once.');
+            continue;
+        }
+        if (name === 'commits' && invocation.input.flags['--since'] !== undefined) {
+            problem(raw, '$commits bound by --since', 'Remove --param commits or omit --since.');
+            continue;
+        }
+        values[name] = parseParameter(raw.slice(separator + 1));
+    }
+    if (problems.length > 0)
+        return { error: { category: 'invocation', code: 'query-rejected', problems } };
+    return { parameters: values };
+}
+function parseParameter(value) {
+    if (/^-?\d+$/.test(value))
+        return Number(value);
+    if (/^-?(?:\d+\.\d*|\d*\.\d+)(?:[eE][+-]?\d+)?$/.test(value))
+        return Number(value);
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return value;
+}
+function commitsSince(root, ref) {
+    try {
+        const output = execFileSync('git', ['rev-list', `${ref}..HEAD`], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+        return output.split('\n').filter(Boolean);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return rejected('--since', ref, 'a git ref reachable from this workspace', `Git could not resolve that ref: ${message}`);
+    }
+}
+function renderRow(record) {
+    const entry = addressFor(record);
+    const values = Object.entries(record)
+        .filter(([name]) => !entry?.columns.includes(name))
+        .map(([, value]) => renderValue(value));
+    return [entry?.value, ...values].filter((value) => value !== undefined).join('  ');
+}
+function addressFor(record) {
+    if (typeof record.at === 'string' && address.test(record.at))
+        return { value: record.at, columns: ['at'] };
+    const file = record.file;
+    const line = record.line;
+    const col = record.col;
+    if (typeof file === 'string' && typeof line === 'number' && typeof col === 'number')
+        return { value: `${file}:${line}:${col}`, columns: ['file', 'line', 'col'] };
+    for (const [column, value] of Object.entries(record)) {
+        if (typeof value === 'string' && address.test(value))
+            return { value, columns: [column] };
+    }
+    return undefined;
+}
+function renderValue(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint')
+        return String(value);
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return `[${value.map(renderValue).join(', ')}]`;
+    if (value instanceof Map)
+        return `{${[...value.entries()].map(([key, entry]) => `${renderValue(key)}: ${renderValue(entry)}`).join(', ')}}`;
+    return `{${Object.entries(value).map(([key, entry]) => `${key}: ${renderValue(entry)}`).join(', ')}}`;
+}
+function orderDefault(records) {
+    const addressed = records.filter((record) => addressFor(record) !== undefined).sort((left, right) => compareAddresses(addressFor(left).value, addressFor(right).value));
+    const unaddressed = records.filter((record) => addressFor(record) === undefined);
+    return [...addressed, ...unaddressed];
+}
+function compareAddresses(left, right) {
+    const leftParts = address.exec(left);
+    const rightParts = address.exec(right);
+    return leftParts[1].localeCompare(rightParts[1]) || Number(leftParts[2]) - Number(rightParts[2]) || Number(leftParts[3]) - Number(rightParts[3]);
+}
+function hasTopLevelOrderBy(cypher) {
+    let depth = 0;
+    let quote;
+    for (let index = 0; index < cypher.length; index++) {
+        const character = cypher[index];
+        if (quote !== undefined) {
+            if (character === quote) {
+                if (cypher[index + 1] === quote)
+                    index++;
+                else
+                    quote = undefined;
+            }
+            continue;
+        }
+        if (character === "'" || character === '"' || character === '`') {
+            quote = character;
+            continue;
+        }
+        if (character === '(' || character === '[' || character === '{') {
+            depth++;
+            continue;
+        }
+        if (character === ')' || character === ']' || character === '}') {
+            depth--;
+            continue;
+        }
+        if (depth !== 0 || !/[Oo]/.test(character))
+            continue;
+        const candidate = cypher.slice(index, index + 32);
+        if (/^order\s+by\b/i.test(candidate) && !/[A-Za-z0-9_]/.test(cypher[index - 1] ?? ''))
+            return true;
+    }
+    return false;
+}
+function rejected(field, received, expected, next) {
+    return { category: 'invocation', code: 'query-rejected', problems: [{ field, received, expected, next }] };
+}
+export default handler;

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

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

package/dist/commands/handlers/rename.js

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import { matchesPathFilters } from '../../core/receipt.js';
+import { RenamePreflightError, renameFromOccurrences } from '../../ts7/checker.js';
+import { query } from '../../store/query.js';
+const handler = async (context, invocation) => {
+    const [input, newName] = invocation.input.args;
+    if (!input || !newName)
+        return invalid('rename needs a symbol and a replacement identifier.', input ?? 'none', 'exactly two values: <symbol> <newName>');
+    await context.projects.bootstrap();
+    const declaration = await context.resolver.resolve(input);
+    try {
+        if (!context.store)
+            throw new Error('The TypeScript index is not available yet.');
+        const edits = renameFromOccurrences(context.program, context.root, context.projects.configured(), declaration, occurrences(context.store, declaration.location.path, declaration.location.line, declaration.location.col), newName);
+        const plan = buildPlan(context.root, declaration.address, declaration.name, newName, edits, context.source.read.bind(context.source));
+        const visible = plan.files.filter((file) => matchesPathFilters(file.path, { in: strings(invocation.input.flags['--in']), exclude: strings(invocation.input.flags['--exclude']) }));
+        const sites = visible.reduce((total, file) => total + file.edits.length, 0);
+        const answer = {
+            data: { element: 'rename', attributes: { symbol: declaration.address, from: declaration.name, to: newName, sites, files: visible.length, applied: false }, children: visible.map(renderFile) },
+            count: sites,
+            receipt: `${sites} rename site${sites === 1 ? '' : 's'} across ${visible.length} file${visible.length === 1 ? '' : 's'}, 0 ms`,
+            renamePlan: plan,
+        };
+        return answer;
+    }
+    catch (error) {
+        if (error instanceof RenamePreflightError)
+            return refusal(error, input);
+        return { category: 'tool', code: 'typescript-error', message: `TypeScript could not prepare this rename: ${message(error)}.`, received: input, expected: 'checker-resolved occurrence locations', next: 'Read server status and retry after repairing the workspace.' };
+    }
+};
+function occurrences(store, file, line, col) {
+    return query(store, 'MATCH (owner:Declaration)-[r:REFERENCES]->(d:Declaration) WHERE d.file = $file AND d.line = $line AND d.col = $col RETURN owner.file AS file, r.line AS line, r.col AS col', { file, line, col }).map((row) => ({ file: String(row.file), line: Number(row.line), col: Number(row.col) }));
+}
+function buildPlan(root, symbol, from, to, locations, read) {
+    const grouped = new Map();
+    for (const location of locations) {
+        const file = path.resolve(root, location.file);
+        grouped.set(file, [...(grouped.get(file) ?? []), { startUtf16: location.startUtf16, endUtf16: location.endUtf16, line: location.line, col: location.col, oldText: location.oldText, replacement: location.replacement }]);
+    }
+    const files = [...grouped].map(([file, edits]) => ({ path: path.relative(root, file).split(path.sep).join('/'), snapshot: Buffer.from(read(file)).toString('base64'), edits: edits.sort((left, right) => left.startUtf16 - right.startUtf16 || left.endUtf16 - right.endUtf16) })).sort((left, right) => left.path.localeCompare(right.path));
+    return { root, symbol, from, to, files };
+}
+function refusal(error, received) {
+    return { category: 'invocation', code: error.code, problems: [{ field: '<symbol>', received: `${error.site}: ${error.message}`, expected: 'a rename without an unsupported site or name conflict', next: 'Choose a different symbol or replacement identifier, then retry rename.' }] };
+}
+function renderFile(file) {
+    return { element: 'file', attributes: { path: file.path, sites: file.edits.length }, text: file.edits.map((edit) => `${edit.line}:${edit.col}  ${edit.oldText} → ${edit.replacement}`).join('\n') };
+}
+function strings(value) { return Array.isArray(value) ? value : undefined; }
+function invalid(message, received, expected) { return { category: 'invocation', code: 'cannot-rename', problems: [{ field: '<symbol>', received, expected: `${expected}; ${message}`, next: 'Choose a symbol TypeScript can rename, then retry.' }] }; }
+function message(error) { return error instanceof Error ? error.message : String(error); }
+export default handler;

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

@@ -0,0 +1,5 @@
+import type { Answer, Invocation, InvocationError, ToolError } from '../types.js';
+import type { SemanticHandler } from '../handlers.js';
+export declare function localSearch(invocation: Invocation): Promise<Answer | InvocationError | ToolError>;
+declare const handler: SemanticHandler;
+export default handler;

package/dist/commands/handlers/search.js

@@ -0,0 +1,32 @@
+import { search } from '../../core/search.js';
+import { openWorkspace } from '../../core/workspace.js';
+export async function localSearch(invocation) {
+    const pattern = invocation.input.args[0];
+    let result;
+    try {
+        result = await search(openWorkspace(invocation.root), pattern, {
+            in: invocation.input.flags['--in'],
+            exclude: invocation.input.flags['--exclude'],
+            limit: invocation.input.flags['--limit'],
+        });
+    }
+    catch (error) {
+        if (isInvalidPattern(error))
+            return { category: 'invocation', code: 'invalid-pattern', problems: [{ field: '<pattern>', received: pattern, expected: `one ast-grep pattern that parses as a single TypeScript node; ${error.message}`, next: 'Wrap the fragment so it is one node, for example a class body, or use --in with a simpler pattern.' }] };
+        throw error;
+    }
+    return {
+        data: {
+            element: 'search',
+            attributes: { pattern, count: result.count, shown: result.receipt.truncated ? result.items.length : undefined },
+            text: result.items.map((match) => `${match.path}:${match.start.line}:${match.start.col}  ${match.text}`).join('\n'),
+        },
+        count: result.count,
+        receipt: `${result.receipt.truncated ? `${result.items.length} of ${result.count} search rows shown, limit ${result.receipt.limit}` : `${result.items.length} search row${result.items.length === 1 ? '' : 's'}`}${result.receipt.excluded > 0 ? `, ${result.receipt.excluded} excluded` : ''}, ${result.receipt.elapsed_ms} ms`,
+    };
+}
+function isInvalidPattern(error) {
+    return error instanceof Error && error.code === 'InvalidArg' && error.message.includes('Rule contains invalid pattern matcher.');
+}
+const handler = async (_context, invocation) => localSearch(invocation);
+export default handler;

package/dist/commands/handlers/server-reload.d.ts

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

package/dist/commands/handlers/server-reload.js

@@ -0,0 +1,7 @@
+const handler = async (_context, invocation) => ({
+    category: 'tool',
+    code: 'not-implemented',
+    message: `tsym ${invocation.path.join(' ')} has no semantic handler yet.`,
+    next: 'Retry after the corresponding leaf handler lands.',
+});
+export default handler;

package/dist/commands/handlers/server-status.d.ts

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

package/dist/commands/handlers/server-status.js

@@ -0,0 +1,7 @@
+const handler = async (_context, invocation) => ({
+    category: 'tool',
+    code: 'not-implemented',
+    message: `tsym ${invocation.path.join(' ')} has no semantic handler yet.`,
+    next: 'Retry after the corresponding leaf handler lands.',
+});
+export default handler;

package/dist/commands/handlers/server-stop.d.ts

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

package/dist/commands/handlers/server-stop.js

@@ -0,0 +1,7 @@
+const handler = async (_context, invocation) => ({
+    category: 'tool',
+    code: 'not-implemented',
+    message: `tsym ${invocation.path.join(' ')} has no semantic handler yet.`,
+    next: 'Retry after the corresponding leaf handler lands.',
+});
+export default handler;

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

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

package/dist/commands/handlers/show.js

@@ -0,0 +1,63 @@
+import { DeclarationError } from '../../core/declarations.js';
+import { query } from '../../store/query.js';
+const handler = async (context, invocation) => {
+    await context.projects.bootstrap();
+    const started = performance.now();
+    const resolved = await context.resolver.resolveAll(invocation.input.args);
+    const rendered = [];
+    for (const declaration of resolved) {
+        const source = context.source.read(declaration.file);
+        const span = storedSpan(context, declaration);
+        const sites = declaration.location.line === 0 ? [{ source, span }] : await declarationSites(context, declaration, span);
+        const text = declaration.location.line === 0 ? source : sites.map((site) => declarationText(site.source, site.span)).join('\n');
+        const lines = declaration.location.line === 0 ? sourceLines(source) : sites.reduce((total, site) => total + site.span.lines, 0);
+        rendered.push({ element: 'symbol', attributes: { at: declaration.address, name: declaration.name, kind: declaration.kind, lines }, text });
+    }
+    const limit = invocation.input.flags['--limit'];
+    const shown = limit === undefined ? rendered : rendered.slice(0, limit);
+    const capped = shown.length < rendered.length;
+    return {
+        data: { element: 'show', attributes: { count: rendered.length, shown: capped ? shown.length : undefined }, children: shown },
+        count: rendered.length,
+        receipt: capped ? `${shown.length} of ${rendered.length} show rows shown, limit ${limit}, ${Math.round(performance.now() - started)} ms` : `${shown.length} show declaration${shown.length === 1 ? '' : 's'}, ${Math.round(performance.now() - started)} ms`,
+    };
+};
+function storedSpan(context, declaration) {
+    if (!context.store)
+        throw new DeclarationError('not-in-program', 'The TypeScript index is not available yet.');
+    const row = query(context.store, 'MATCH (d:Declaration) WHERE d.file = $file AND d.line = $line AND d.col = $col RETURN d.endLine AS endLine, d.lines AS lines, d.declCount AS declCount', { file: declaration.location.path, line: declaration.location.line, col: declaration.location.col })[0];
+    if (!row)
+        throw new DeclarationError('unresolvable-symbol', `${declaration.address} is absent from the TypeScript index`);
+    return { endLine: Number(row.endLine), lines: Number(row.lines), declCount: Number(row.declCount) };
+}
+async function declarationSites(context, declaration, stored) {
+    if (stored.declCount === 1)
+        return [{ source: context.source.read(declaration.file), span: stored }];
+    const membership = await context.projects.membership(declaration.file);
+    if (!membership)
+        throw new DeclarationError('not-in-program', `${declaration.location.path} exists but is not part of a TypeScript project under ${context.root}`);
+    const sites = context.program.withSnapshot((snapshot) => {
+        const project = snapshot.getProject(membership.config);
+        if (!project)
+            throw new Error(`TypeScript project ${membership.config} is not loaded.`);
+        const symbol = project.checker.getSymbolAtPosition(declaration.file, declaration.nameSpan.start);
+        return (symbol?.declarations ?? []).flatMap((handle) => {
+            const node = handle.resolve(project);
+            if (!node)
+                return [];
+            const source = node.getSourceFile();
+            const start = source.getLineAndCharacterOfPosition(node.getStart(source));
+            const end = source.getLineAndCharacterOfPosition(node.getEnd());
+            return [{ source: context.source.read(source.fileName), span: { endLine: end.line + 1, lines: end.line - start.line + 1, declCount: stored.declCount } }];
+        });
+    });
+    if (sites.length === 0)
+        throw new DeclarationError('unresolvable-symbol', `${declaration.address} has no declaration sites in the TypeScript program`);
+    return sites;
+}
+function declarationText(source, span) {
+    const firstLine = span.endLine - span.lines + 1;
+    return source.split('\n').slice(firstLine - 1, span.endLine).join('\n');
+}
+function sourceLines(source) { return source.split('\n').length - (source.endsWith('\n') ? 1 : 0); }
+export default handler;

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

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

package/dist/commands/handlers/type.js

@@ -0,0 +1,45 @@
+import { DeclarationError, DeclarationResolutionErrors } from '../../core/declarations.js';
+import { normalKind } from '../../read/read.js';
+import { typeAt } from '../../ts7/checker.js';
+const handler = async (context, invocation) => {
+    try {
+        await context.projects.bootstrap();
+        const declarations = await context.resolver.resolveAll(invocation.input.args);
+        const includeDefinition = invocation.input.flags['--def'] === true;
+        const symbols = [];
+        let answers = 0;
+        for (const declaration of declarations) {
+            const project = await context.projects.membership(declaration.file);
+            if (!project)
+                throw new DeclarationError('not-in-program', `${declaration.location.path} exists but is not part of a TypeScript project under ${context.root}`);
+            const answer = typeAt(context.program, context.root, project.config, declaration.file, declaration.nameSpan.start, { ...declaration, kind: normalKind(declaration.kind) });
+            if (answer !== null)
+                answers++;
+            symbols.push(renderSymbol(declaration, answer, includeDefinition));
+        }
+        return { data: { element: 'type', children: symbols }, count: answers };
+    }
+    catch (error) {
+        if (error instanceof DeclarationError || error instanceof DeclarationResolutionErrors)
+            throw error;
+        return failure(error);
+    }
+};
+function renderSymbol(declaration, answer, includeDefinition) {
+    const attributes = {
+        at: declaration.address,
+        name: declaration.name,
+        kind: normalKind(answer?.kind ?? declaration.kind),
+        modifiers: answer?.modifiers,
+        typeAt: includeDefinition && answer && answer.definitions.length > 0 ? answer.definitions.join(' ') : undefined,
+    };
+    if (answer === null)
+        return { element: 'symbol', attributes };
+    const children = [documentation(answer.documentation), ...answer.tags.map((tag) => ({ element: 'tag', attributes: { name: tag.name }, text: tag.text }))].filter((node) => node !== null);
+    return { element: 'symbol', attributes, text: answer.signature, children };
+}
+function documentation(text) { return text ? { element: 'doc', text } : null; }
+function failure(error) {
+    return { category: 'tool', code: 'typescript-error', message: 'TypeScript could not answer the type query.', received: error instanceof Error ? error.message : String(error), expected: 'a successful checker type query', next: 'Read the server log, then retry.' };
+}
+export default handler;

package/dist/commands/handlers.d.ts

@@ -0,0 +1,12 @@
+import { DeclarationError } from '../core/declarations.js';
+import type { SemanticContext } from '../server/context.js';
+import type { Completion, Invocation, InvocationError } from './types.js';
+/** A leaf handler answers, or returns an invocation error (exit 2) or a tool error (exit 3). It never writes output. */
+export type SemanticHandler = (context: SemanticContext, invocation: Invocation) => Promise<Completion>;
+export declare function executeSemantic(context: SemanticContext, invocation: Invocation): Promise<Completion>;
+/**
+ * A resolver rejection is the caller's input being wrong, not the tool failing: exit 2 with the leaf's `-h` as
+ * the next step. Handlers may let `DeclarationError` propagate and rely on this mapping, or return an
+ * `InvocationError` themselves when they know a sharper field or next step.
+ */
+export declare function declarationError(error: DeclarationError, invocation: Invocation): InvocationError;

package/dist/commands/handlers.js

@@ -0,0 +1,44 @@
+import { DeclarationError, DeclarationResolutionErrors } from '../core/declarations.js';
+const modules = {
+    outline: () => import('./handlers/outline.js'), find: () => import('./handlers/find.js'), show: () => import('./handlers/show.js'), type: () => import('./handlers/type.js'), inspect: () => import('./handlers/inspect.js'), query: () => import('./handlers/query.js'), search: () => import('./handlers/search.js'), check: () => import('./handlers/check.js'), rename: () => import('./handlers/rename.js'), 'server-status': () => import('./handlers/server-status.js'), 'server-stop': () => import('./handlers/server-stop.js'), 'server-reload': () => import('./handlers/server-reload.js'),
+};
+export async function executeSemantic(context, invocation) {
+    const handler = invocation.declaration.handler;
+    if (!handler)
+        return { category: 'tool', code: 'not-implemented', message: `tsym ${invocation.path.join(' ')} has no handler.`, next: 'Register an executable leaf handler.' };
+    try {
+        return await (await modules[handler]()).default(context, invocation);
+    }
+    catch (error) {
+        if (error instanceof DeclarationError)
+            return declarationError(error, invocation);
+        if (error instanceof DeclarationResolutionErrors)
+            return declarationErrors(error, invocation);
+        throw error;
+    }
+}
+/**
+ * A resolver rejection is the caller's input being wrong, not the tool failing: exit 2 with the leaf's `-h` as
+ * the next step. Handlers may let `DeclarationError` propagate and rely on this mapping, or return an
+ * `InvocationError` themselves when they know a sharper field or next step.
+ */
+export function declarationError(error, invocation) {
+    return { category: 'invocation', code: error.code, problems: [declarationProblem(error, invocation)] };
+}
+function declarationErrors(errors, invocation) {
+    return { category: 'invocation', code: errors.errors[0].code, problems: errors.errors.map((error) => declarationProblem(error, invocation)) };
+}
+function declarationProblem(error, invocation) {
+    const leaf = `tsym ${invocation.path.join(' ')}`;
+    const expected = {
+        'no-such-path': 'an existing file or directory under --root',
+        'not-in-program': 'a file that a tsconfig under --root includes',
+        'unresolvable-symbol': 'a declaration name, qualified member name, or path:line:col address',
+        'ambiguous-symbol': 'one canonical address',
+        'invalid-address': 'path:line:col with both coordinates positive, or path:0:0 for a module',
+    };
+    const next = error.code === 'ambiguous-symbol' && error.candidates.length > 0
+        ? `Pass one of: ${error.candidates.join(' ')}`
+        : `Run \`${leaf} -h\` for the accepted input forms.`;
+    return { field: invocation.declaration.argument?.name ?? 'argument', received: error.message, expected: expected[error.code], next };
+}

package/dist/commands/help.d.ts

@@ -0,0 +1,2 @@
+import type { CommandDeclaration } from './types.js';
+export declare function renderHelp(node: CommandDeclaration, serverState?: string): string;

package/dist/commands/help.js

@@ -0,0 +1,27 @@
+import { xml, escapeAttribute } from '../output.js';
+import { commandTree } from './tree.js';
+export function renderHelp(node, serverState = '<server state="stopped"/>') {
+    const lines = [];
+    if (node.model)
+        lines.push(`<model>\n${node.model}${node === commandTree || node.state ? `\n\n${serverState}` : ''}\n</model>`);
+    if (serverState && node !== commandTree && !node.state)
+        lines.push(serverState);
+    if (node.children)
+        lines.push(...node.children.map((child) => `<subcommand name="${child.name}" description="${escapeAttribute(child.description)}" whenToUse="${escapeAttribute(child.whenToUse ?? '')}"/>`));
+    if (node.argument || node.flags?.length)
+        lines.push(`<input>\n${[node.argument ? argument(node.argument) : null, ...(node.flags ?? []).map(flag)].filter((line) => line !== null).join('\n')}\n</input>`);
+    if (node.output)
+        lines.push(`<output>${node.output}</output>`);
+    if (node.effects)
+        lines.push(`<effects>${node.effects}</effects>`);
+    if (node === commandTree) {
+        lines.push('<globals>\n  <flag name="--root" type="path">Workspace root, overriding discovery from the current directory.</flag>\n  <flag name="--json" type="bool">Raw JSON on stdout for programmatic consumers.</flag>\n</globals>');
+        lines.push('<io>Flags and positional arguments on input. Stdout is one named XML block per call. One receipt goes to stderr on every call. Exit 0 with results, 1 with none, 2 when the invocation was wrong, 3 when the tool could not answer.</io>');
+    }
+    return xml('command', { name: node.name, description: node.description }, lines.join('\n'));
+}
+function argument(declaration) { return `  <arg name="${declaration.name}" repeat="${declaration.repeat}">${declaration.description}</arg>`; }
+function flag(declaration) {
+    const attrs = [`name="${declaration.name}"`, `type="${declaration.type}"`, declaration.repeat ? 'repeat="yes"' : null, declaration.default !== undefined ? `default="${declaration.default}"` : null].filter(Boolean).join(' ');
+    return `  <flag ${attrs}>${declaration.description}</flag>`;
+}

package/dist/commands/rename-apply.d.ts

@@ -0,0 +1,37 @@
+import { chmod, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import type { ToolError } from './types.js';
+export interface RenameEdit {
+    startUtf16: number;
+    endUtf16: number;
+    line: number;
+    col: number;
+    oldText: string;
+    replacement: string;
+}
+export interface RenameFilePlan {
+    path: string;
+    snapshot: string;
+    edits: RenameEdit[];
+}
+export interface RenamePlan {
+    root: string;
+    symbol: string;
+    from: string;
+    to: string;
+    files: RenameFilePlan[];
+}
+export type RenameAnswer = {
+    renamePlan: RenamePlan;
+};
+export interface RenameFileOperations {
+    readFile: typeof readFile;
+    writeFile: typeof writeFile;
+    rename: typeof rename;
+    rm: typeof rm;
+    stat: typeof stat;
+    chmod: typeof chmod;
+}
+/** Apply a complete compiler-produced plan without asking the resident to recompute it. */
+export declare function applyRenamePlan(plan: RenamePlan, operations?: RenameFileOperations): Promise<{
+    applied: true;
+} | ToolError>;