@crouton-kit/tsym 0.1.0

package/dist/commands/rename-apply.js

@@ -0,0 +1,115 @@
+import { chmod, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+const filesystem = { readFile, writeFile, rename, rm, stat, chmod };
+/** Apply a complete compiler-produced plan without asking the resident to recompute it. */
+export async function applyRenamePlan(plan, operations = filesystem) {
+    const prepared = [];
+    try {
+        for (const file of orderedFiles(plan)) {
+            const absolute = absolutePath(plan.root, file.path);
+            const original = await operations.readFile(absolute);
+            if (!original.equals(Buffer.from(file.snapshot, 'base64')))
+                return writeFailure(`The source changed after the rename preview: ${file.path}.`, 'Re-run rename to produce a plan for the current source.');
+            const replacement = applyEdits(original, file);
+            const metadata = await operations.stat(absolute);
+            const suffix = `.tsym-rename-${randomUUID()}`;
+            prepared.push({ file, original, replacement, mode: metadata.mode & 0o7777, temp: `${absolute}${suffix}.new`, restore: `${absolute}${suffix}.restore`, replaced: false });
+        }
+        for (const entry of prepared) {
+            await operations.writeFile(entry.temp, entry.replacement, { mode: entry.mode, flag: 'wx' });
+            await operations.chmod(entry.temp, entry.mode);
+            await operations.writeFile(entry.restore, entry.original, { mode: entry.mode, flag: 'wx' });
+            await operations.chmod(entry.restore, entry.mode);
+        }
+    }
+    catch (error) {
+        await removePrepared(prepared, operations);
+        return writeFailure(`Rename preparation failed: ${message(error)}.`, 'Fix the filesystem error, then re-run rename.');
+    }
+    try {
+        for (const entry of prepared) {
+            await operations.rename(entry.temp, absolutePath(plan.root, entry.file.path));
+            entry.replaced = true;
+        }
+    }
+    catch (error) {
+        const rollbackFailures = [];
+        for (const entry of [...prepared].reverse()) {
+            if (!entry.replaced)
+                continue;
+            try {
+                await operations.rename(entry.restore, absolutePath(plan.root, entry.file.path));
+                entry.replaced = false;
+            }
+            catch {
+                rollbackFailures.push(entry.restore);
+            }
+        }
+        await removePrepared(prepared, operations, new Set(rollbackFailures));
+        if (rollbackFailures.length > 0) {
+            return {
+                category: 'tool',
+                code: 'rename-rollback-failed',
+                message: `Rename commit failed (${message(error)}) and restoration also failed. Original backups remain at: ${rollbackFailures.join(', ')}.`,
+                received: rollbackFailures.join(', '),
+                expected: 'the listed original-content backups to remain available for manual restoration',
+                next: 'Restore the listed backups over their source files before retrying rename.',
+            };
+        }
+        return writeFailure(`Rename commit failed and every replaced file was restored: ${message(error)}.`, 'Fix the filesystem error, then re-run rename.');
+    }
+    const cleanupFailures = [];
+    for (const entry of prepared) {
+        try {
+            await operations.rm(entry.restore, { force: false });
+        }
+        catch {
+            cleanupFailures.push(entry.restore);
+        }
+    }
+    if (cleanupFailures.length > 0) {
+        return {
+            category: 'tool',
+            code: 'rename-write-failed',
+            message: `Rename committed, but cleanup could not remove restore files. Changed files: ${prepared.map((entry) => entry.file.path).join(', ')}. Restore files still present: ${cleanupFailures.join(', ')}.`,
+            received: cleanupFailures.join(', '),
+            expected: 'all restore files to be removed after every replacement was committed',
+            next: 'Verify the changed files, then remove the listed restore files.',
+        };
+    }
+    return { applied: true };
+}
+function orderedFiles(plan) { return [...plan.files].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0); }
+function absolutePath(root, file) { return path.resolve(root, file); }
+function applyEdits(source, file) {
+    const text = source.toString('utf8');
+    const edits = [...file.edits].sort((left, right) => left.startUtf16 - right.startUtf16 || left.endUtf16 - right.endUtf16);
+    let previous = 0;
+    for (const edit of edits) {
+        if (!Number.isInteger(edit.startUtf16) || !Number.isInteger(edit.endUtf16) || edit.startUtf16 < previous || edit.endUtf16 < edit.startUtf16 || edit.endUtf16 > text.length)
+            throw new Error(`Invalid or overlapping edit in ${file.path}.`);
+        previous = edit.endUtf16;
+    }
+    const chunks = [];
+    let end = source.length;
+    for (const edit of [...edits].reverse()) {
+        const startByte = Buffer.byteLength(text.slice(0, edit.startUtf16));
+        const endByte = Buffer.byteLength(text.slice(0, edit.endUtf16));
+        chunks.unshift(source.subarray(endByte, end));
+        chunks.unshift(Buffer.from(edit.replacement));
+        end = startByte;
+    }
+    chunks.unshift(source.subarray(0, end));
+    return Buffer.concat(chunks);
+}
+async function removePrepared(prepared, operations, retain = new Set()) {
+    await Promise.all(prepared.flatMap((entry) => [entry.temp, entry.restore]).filter((file) => !retain.has(file)).map(async (file) => { try {
+        await operations.rm(file, { force: true });
+    }
+    catch { } }));
+}
+function writeFailure(message, next) {
+    return { category: 'tool', code: 'rename-write-failed', message, expected: 'every file in the preview to still match its recorded source snapshot', next };
+}
+function message(error) { return error instanceof Error ? error.message : String(error); }

package/dist/commands/tree.d.ts

@@ -0,0 +1,9 @@
+import type { CommandDeclaration, Invocation, InvocationError } from './types.js';
+export declare const commandTree: CommandDeclaration;
+export declare function findNode(tokens: readonly string[]): {
+    node: CommandDeclaration;
+    consumed: number;
+};
+export declare function parseInvocation(argv: readonly string[], cwd?: string): Invocation | InvocationError | {
+    help: CommandDeclaration;
+};

package/dist/commands/tree.js

@@ -0,0 +1,277 @@
+import { realpathSync } from 'node:fs';
+const kinds = ['function', 'class', 'interface', 'type', 'enum', 'const', 'let', 'var', 'method', 'property', 'getter', 'setter', 'constructor', 'module'];
+const relations = ['refs', 'callers', 'calls', 'impl'];
+const inspectUnknownFlags = { '--limit': 'Inspect caps rows per relation with `--each N`.' };
+const filters = [
+    { name: '--in', type: 'glob', repeat: true, description: 'Keep only rows under matching paths.' },
+    { name: '--exclude', type: 'glob', repeat: true, description: 'Drop matching paths. Wins over --in.' },
+];
+const selectedTraversal = {
+    check(input) {
+        const only = input.flags['--only'] ?? [...relations];
+        const traverses = only.some((value) => value === 'callers' || value === 'calls');
+        const problems = [];
+        if (input.explicit.has('--depth') && !traverses)
+            problems.push({ field: '--depth', received: only.join(', '), expected: 'at least one of callers or calls', next: 'Omit --depth or select callers or calls.' });
+        if (input.explicit.has('--graph') && !traverses)
+            problems.push({ field: '--graph', received: only.join(', '), expected: 'at least one of callers or calls, because refs and impl produce no edges to draw', next: 'Omit --graph or select callers or calls.' });
+        if (input.explicit.has('--each') && input.flags['--graph'] === true)
+            problems.push({ field: '--each', received: String(input.flags['--each']), expected: 'not used with --graph', next: 'Omit --each; graphs are never capped.' });
+        return problems;
+    },
+};
+const renameApplyFilters = {
+    check(input) {
+        if (input.flags['--apply'] === true && (input.explicit.has('--in') || input.explicit.has('--exclude')))
+            return [{ field: '--apply', received: '--apply with a path filter', expected: '--apply without --in or --exclude', next: 'Preview a filtered rename without --apply, or apply the complete rename.' }];
+        return [];
+    },
+};
+const renameIdentifier = {
+    check(input) {
+        const name = input.args[1];
+        if (input.args.length !== 2 || !name || identifier.test(name) && !keywords.has(name))
+            return [];
+        return [{ field: '<newName>', received: name, expected: 'a TypeScript identifier that is not a reserved keyword', next: 'Choose a valid replacement identifier, then retry rename.' }];
+    },
+};
+function queryHelp() {
+    return `One Cypher statement against the selected declarations and relationships in the union of this workspace's configured TypeScript projects. 
+
+Rows lead with a path:line:col address whenever the query returns file, line, col or an at column, and every printed address is accepted by show, type, inspect, and rename. Results over --rows go to a file, named in the output; the printed count is always the true total.
+
+<schema>
+Two node labels.
+(:Declaration { key, at, name, qname, kind, exported, file, dir, top, line, col, endLine, lines, declCount, container })
+key is src/core/runtime/revive.ts#reviveNode: module path followed by enclosing names, stable across edits around it. Members are src/api/client.ts#CrtrClient.reviveNode; locals are …#reviveNode.attempt. at is the printed path:line:col address. kind is module | function | class | interface | type | enum | namespace | const | let | var | method | property | getter | setter | constructor. top is the first two path segments, such as src/core. declCount records overloads, get/set pairs, and declaration merging. container is the enclosing declaration key.
+(:External { key: node:fs#readFile, module: node:fs, name: readFile })
+Every configured file contributes a module Declaration at path:0:0. Nothing under node_modules is a Declaration.
+</schema>
+
+<relationships>
+Compiler-resolved: (d)-[:CONTAINS]->(member); (d)-[:REFERENCES {line,col,role}]->(target), role definition|call|import|type|write|read; (d)-[:CALLS {line,col,dispatch}]->(target); (d)-[:IMPLEMENTS]->(target); (d)-[:EXTENDS]->(base); (d)-[:TYPE_MENTION {line,col,position}]->(type); (module)-[:IMPORTS {line,names}]->(module|External); (module)-[:EXPORTS {name,line,col}]->(d); (c:Commit {hash,ts,author,subject})-[:CHANGED {added,removed}]->(d).
+Inferred: (new:Declaration)-[:RENAMED_FROM {oldKey,basis}]->(c:Commit), basis text-identical | container-renamed | file-moved.
+Excluded internal declaration occurrences are counted as internal sites, not stored. Every stored call occurrence is both a CALLS and REFERENCES edge at the same address. A dispatch call targets an interface or abstract member with dispatch=true; concrete members are <-[:IMPLEMENTS]-. IMPLEMENTS is heritage-based; structural object-literal satisfaction is not an edge. The graph holds one revision: the working tree.
+</relationships>
+
+<examples>
+Every export nothing outside its own file references:
+MATCH (d:Declaration) WHERE d.exported AND NOT EXISTS { MATCH (s:Declaration)-[:REFERENCES]->(d) WHERE s.file <> d.file } RETURN d.key, d.file, d.line, d.col ORDER BY d.key
+
+A module's public surface, each export with fan-in and its top three callers:
+MATCH (d:Declaration) WHERE d.exported AND d.file = $file OPTIONAL MATCH (r:Declaration)-[ref:REFERENCES]->(d) WITH d, count(ref) AS fanIn OPTIONAL MATCH (caller:Declaration)-[call:CALLS]->(d) WITH d, fanIn, caller.key AS caller, count(call) AS sites ORDER BY sites DESC, caller SKIP 0 WITH d, fanIn, collect(CASE WHEN caller IS NOT NULL THEN {caller: caller, sites: sites} ELSE NULL END) AS callers RETURN d.key, fanIn, coalesce(callers[1:3], []) AS topCallers ORDER BY d.key
+
+Every implementation of an interface or abstract member:
+MATCH (impl:Declaration)-[:IMPLEMENTS]->(target:Declaration) WHERE target.key = $key RETURN DISTINCT impl.key, impl.file, impl.line, impl.col ORDER BY impl.key
+
+Every function whose signature mentions a type:
+MATCH (f:Declaration)-[:TYPE_MENTION]->(t:Declaration) WHERE t.key = $key AND f.kind IN ['function','method'] RETURN DISTINCT f.key, f.file, f.line, f.col ORDER BY f.key
+
+Every call crossing a boundary it should not:
+MATCH (caller:Declaration)-[call:CALLS]->(callee:Declaration) WHERE caller.top = 'src/commands' AND callee.top = 'src/daemon' RETURN caller.key, callee.key, call.line, call.col ORDER BY caller.key, callee.key, call.line
+UNION
+MATCH (caller:Declaration)-[call:CALLS]->(ext:External) WHERE caller.top = 'src/api' AND ext.module <> 'lib' RETURN caller.key, ext.key AS callee, call.line, call.col ORDER BY caller.key, callee, call.line
+
+Every symbol this branch changed, each with its callers — pass --since main:
+UNWIND $commits AS hash MATCH (c:Commit)-[:CHANGED]->(d:Declaration) WHERE c.hash = hash WITH DISTINCT d OPTIONAL MATCH (caller:Declaration)-[:CALLS]->(d) RETURN d.key, coalesce(collect(DISTINCT caller.key), []) AS callers ORDER BY d.key
+
+Functions and methods with no incoming calls:
+MATCH (f:Declaration) WHERE f.kind IN ['function','method'] AND NOT EXISTS { MATCH (:Declaration)-[:CALLS]->(f) } RETURN f.key, f.file, f.line, f.col ORDER BY f.key
+
+Everything that reaches a symbol within three call hops:
+MATCH (caller:Declaration)-[:CALLS*1..3]->(hub:Declaration) WHERE hub.key = $key RETURN DISTINCT caller.key ORDER BY caller.key
+
+Everything a symbol reaches within five call hops:
+MATCH (hub:Declaration)-[:CALLS*1..5]->(callee:Declaration) WHERE hub.key = $key RETURN DISTINCT callee.key ORDER BY callee.key
+</examples>
+
+<dialect>
+The engine is LadybugDB 0.20.4, openCypher. Five runtime-verified differences from Neo4j Cypher: CALL { ... } and correlated CALL (d) { ... } are rejected; aggregate with WITH, OPTIONAL MATCH, then collect. List comprehensions [x IN list WHERE p | e] are rejected; use UNWIND/WITH, or projection and aggregation. WITH ... ORDER BY ... WITH ... needs SKIP or LIMIT between them; ORDER BY sites DESC, caller SKIP 0 imposes no cap. List slices are 1-based inclusive: [1:3] takes three elements. collect() over only nulls yields null, not []; wrap it with coalesce(collect(...), []). Always bound variable-length patterns, for example [:CALLS*1..3], never [:CALLS*]. An unbounded walk over a cyclic call graph is killed at 30 seconds.
+</dialect>`;
+}
+const identifier = /^[$_\p{ID_Start}][$_\u200C\u200D\p{ID_Continue}]*$/u;
+const keywords = new Set(['await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'yield']);
+function leaf(name, description, whenToUse, handler, argument, flags, output, effects = 'None.') {
+    return { name, description, whenToUse, handler, argument, flags, output, effects };
+}
+export const commandTree = {
+    name: 'tsym',
+    description: 'Symbol-level reading of a TypeScript codebase, from the compiler\'s own resolution.',
+    model: 'Every answer comes from a loaded TypeScript program, not text matching. With no name or address in hand, start at outline; with a name, go straight to find, show, type, or inspect. An address on a declared name or reference resolves to that symbol; any other address inside an indexed declaration resolves to the innermost enclosing declaration. Outside every declaration, the error lists the module address and top-level declaration addresses. A resident server starts when a semantic command needs it and exits after idle time. Server state is stopped, ready, or stopping.',
+    children: [
+        leaf('outline', 'Structure of a file, a directory, or the whole repository.', 'Reach for this first when you need the shape of unfamiliar code before reading declarations.', 'outline', { name: 'path', repeat: '0+', description: 'File, directory, or glob, relative to the current directory. Default: the workspace root.' }, [{ name: '--depth', type: 'int', default: 1, minimum: 1, description: 'Levels to descend. On a file, depth 1 is top-level declarations. On a directory, depth 1 is immediate file and subdirectory containers; depth 2 lists declarations in every file below it, however deeply nested. Directories never consume a level.' }, { name: '--kind', type: 'string', repeat: true, values: kinds, description: `Keep only these kinds: ${kinds.join(', ')}.` }, { name: '--exported', type: 'bool', description: 'Keep only exported declarations.' }, { name: '--members', type: 'bool', description: 'Expand members on reached class, interface, enum, and module rows. Does not consume depth.' }, { name: '--imports', type: 'bool', description: 'Include one row per import statement, which is dropped by default.' }, ...filters, { name: '--limit', type: 'int', minimum: 0, description: 'Cap rows.' }], 'One <outline> element. Symbol rows are `path:line:col  kind  [export]  name  (NL[, N members])`, ordered by source position. Container rows are `path  (N files, N symbols)`; their files and symbols counts are after filters. The element symbols count is the total declarations and files is the files in scope. Count is the true total and shown appears only when capped.'),
+        leaf('find', 'Locate a declaration by name.', 'Reach for this to disambiguate a name when several declarations share it or you need its container; when the name is unique, pass it straight to show, inspect, or type.', 'find', { name: 'name', repeat: '1', description: 'Declared name. Container.name narrows to a member.' }, [{ name: '--prefix', type: 'bool', description: 'Match names beginning with the input.' }, { name: '--kind', type: 'string', repeat: true, values: kinds, description: 'Keep only these kinds.' }, ...filters, { name: '--limit', type: 'int', minimum: 0, description: 'Cap rows.' }], 'One <find> element. Rows are `path:line:col  kind  [export]  qualifiedName`, ordered by path then position. Alias rows and member rows are included. Count is the true total and shown appears only when capped.'),
+        leaf('show', 'The declaration\'s source text.', 'Reach for this to read one declaration in full without reading its file.', 'show', { name: 'symbol', repeat: '1+', description: 'path:line:col, or a name. Address resolution follows the root command contract.' }, [{ name: '--limit', type: 'int', minimum: 0, description: 'Cap how many declarations are printed.' }], 'One <show> element containing one <symbol> per argument, in argument order. Each symbol has at, name, kind, and lines attributes; its body is the whole source lines of the declaration\'s span, and a line shared with another declaration is printed once, in full. Count is the true total and shown appears only when capped.'),
+        leaf('type', 'Resolved type, signature, and doc comment.', 'Reach for this when source text does not answer the compiler-resolved type.', 'type', { name: 'symbol', repeat: '1+', description: 'path:line:col, or a name. Address resolution follows the root command contract.' }, [{ name: '--def', type: 'bool', description: 'Also resolve the declaration of the type.' }], 'One <type> element containing one <symbol> per argument. Each symbol has at, name, kind, modifiers, and optional typeAt attributes; its body is the resolved signature, followed by optional <doc> and <tag name="…"> sections.', 'Opens and closes a document in the server. No persistent change.'),
+        { ...leaf('inspect', 'How a symbol relates to the rest of the code.', 'Reach for this for references, callers, calls, implementations, or where a component is rendered; JSX uses a component as a call, so `inspect Component` answers which components render it and which it renders.', 'inspect', { name: 'symbol', repeat: '1+', description: 'path:line:col, or a name. Address resolution follows the root command contract. Each symbol gets its own result block.' }, [{ name: '--only', type: 'string', repeat: true, values: relations, description: `Run only these relations: ${relations.join(', ')}. Default: all four.` }, { name: '--each', type: 'int', default: 10, minimum: 0, description: 'Rows per relation. Use 0 for every row. --limit is rejected; use --each instead. Rejected with --graph because graphs are never capped.' }, { name: '--depth', type: 'int', default: 1, minimum: 1, description: 'Levels to follow for callers and calls, including implementation edges. Rejected unless callers or calls is selected.' }, { name: '--graph', type: 'bool', description: 'Requires callers or calls. Render one Mermaid flowchart for all seeds instead of row mode; it prints no refs or impl blocks. Rejected with --each; graphs are never capped.' }, { name: '--in', type: 'glob', repeat: true, description: 'Keep only rows under matching paths. In a graph, projects rows while retaining connecting nodes.' }, { name: '--exclude', type: 'glob', repeat: true, description: 'Drop matching paths. In traversals, also prune nodes reachable only through them. Wins over --in.' }], 'One <inspect> element per symbol, opening with the resolved signature. By default it contains <refs>, <callers>, <calls>, and <impl> blocks; --only emits only selected blocks. Empty selected relations render count="0". Refs rows are `path:line:col  kind  qualifiedName  role`; callers and calls rows are `path:line:col  depth  kind  qualifiedName  (N sites[, impl])`; impl rows are `path:line:col  kind  qualifiedName`. Callers of a class or interface are sites that construct it, so one reached only by injection or a type annotation has zero callers; trace calls through its methods (`inspect Class.method` or `outline --members`) or `<refs>`. Each block count is the true total, files is distinct result paths, and shown appears only when capped by --each. The receipt names excluded, unresolved, and dispatch counts when nonzero. --graph instead returns one Mermaid flowchart; each node label includes a path:line:col address.', 'None.'), constraints: [selectedTraversal], unknownFlagNext: inspectUnknownFlags },
+        { ...leaf('query', 'Set-shaped questions over the whole index, in Cypher.', 'Reach for this when the answer is a set over the whole index rather than one symbol\'s neighbourhood.', 'query', { name: 'cypher', repeat: '1', description: 'The query. `-` reads it from stdin.' }, [{ name: '--param', type: 'string', repeat: true, description: 'NAME=VALUE, binding $NAME. Integers, floats, true and false are parsed; everything else is a string.' }, { name: '--since', type: 'string', description: 'A git ref. Resolves REF..HEAD, ingests any commits the index lacks, and binds the hash list as $commits.' }, { name: '--rows', type: 'int', default: 100, minimum: 0, description: 'Rows printed to stdout. 0 prints every row and creates no implicit file; --out still writes.' }, { name: '--out', type: 'path', description: 'Always write the complete result here, even below --rows or with --rows 0. Printing still honours --rows.' }], 'One <query> element with rows, shown, indexedAt, state and ms attributes. A record returning file/line/col or an at column leads with that address; remaining columns follow in RETURN order, two spaces apart. With no ORDER BY, addressed rows sort by path, line, column and the receipt says unordered for records without addresses. Over --rows, a <truncated> element names the true total and the file holding every row.', '--since may write Commit and CHANGED rows. --out always writes a complete result file; truncation writes one implicitly without --out. Source files are not changed.'), model: queryHelp() },
+        leaf('search', 'Structural syntax search over the source.', 'Reach for this when the pattern is syntax shape rather than a named symbol.', 'search', { name: 'pattern', repeat: '1', description: 'An ast-grep pattern that parses as one node. $NAME captures a node; $$$NAME captures a list. Each file is parsed as its own language: ts, tsx, js, or jsx by extension.' }, [...filters, { name: '--limit', type: 'int', minimum: 0, description: 'Cap rows.' }], 'One <search> element. Rows are `path:line:col  matched text, first line`, ordered by path then position. Count is the true total and shown appears only when capped.'),
+        leaf('check', 'Semantic and syntactic diagnostics.', 'Reach for this after editing to check changed files or the complete program.', 'check', { name: 'path', repeat: '0+', description: 'Files or globs, relative to the current directory. Default: the whole program. Paths are checked synchronously; without paths, the bundled TypeScript 7 checker examines the whole program in about 1–3 seconds on crouter.' }, [{ name: '--errors-only', type: 'bool', description: 'Drop warnings and suggestions.' }, ...filters, { name: '--limit', type: 'int', minimum: 0, description: 'Cap diagnostics.' }], 'One <check> element with scope, errors, warnings, suggestions, and ms attributes, containing diagnostics ordered by path then position. A diagnostic is `<diagnostic at="path:line:col" severity="error|warning|suggestion" code="N">message</diagnostic>`. Count is the true total and shown appears only when capped. A clean check has no diagnostics and exits 1.', 'Opens and closes documents. No persistent change.'),
+        { ...leaf('rename', 'Rename a symbol across the program.', 'Reach for this instead of editing call sites by hand when a rename crosses files.', 'rename', { name: 'symbol and newName', repeat: '1+', description: 'Exactly two values: path:line:col or a name, then a TypeScript identifier that is not a reserved keyword. Address resolution follows the root command contract.' }, [{ name: '--apply', type: 'bool', description: 'Write the complete compiler-provided edit plan. Rejected with --in or --exclude.' }, ...filters], 'One <rename> element with symbol, from, to, sites, files, and applied attributes, containing one <file path="…" sites="N"> per affected file. File rows are `line:col  old → new`. Applied says whether every listed file was written.', 'Without --apply: none. With --apply: every planned file is rewritten, all or none for failures observed by this process.'), constraints: [renameApplyFilters, renameIdentifier] },
+        {
+            name: 'server', description: 'The resident TypeScript process.', whenToUse: 'Reach for this only when the server is wrong rather than absent, such as after a branch switch or dependency install.',
+            model: 'One server per workspace root holds the bundled TypeScript 7 program and its index. Ordinary file edits need nothing; reload is for changes to program shape. Every semantic command starts a missing server and reuses a live one; it exits after 14400 seconds idle.',
+            state: () => null,
+            children: [
+                leaf('status', 'Whether a server is live, and what it is running.', 'Reach for this after an unexpected failure or slow command to read server identity and log path.', 'server-status', undefined, [], 'One <server> element. State is stopped, ready, or stopping. A live result reports root, pid, port, uptime, resident memory, the bundled TypeScript 7 version, store path, indexed commit, selected-scope declaration and edge counts, files outside configured projects, index state, last index duration, and log path. A stopped server is an answered empty result and exits 1.'),
+                leaf('stop', 'Stop the server for this root.', 'Reach for this to free resident memory or recover a server.', 'server-stop', undefined, [], 'One <server> element describing whether the process for this root stopped.', 'Stops the resident process; it never starts one.'),
+                leaf('reload', 'Restart the server, discarding the loaded program and index.', 'Reach for this after a branch switch, tsconfig change, or dependency install.', 'server-reload', undefined, [], 'One <server> element describing the fresh ready process.', 'Stops then starts the resident process and forces a full index rebuild.'),
+            ],
+        },
+    ],
+};
+const globals = [
+    { name: '--root', type: 'path', description: 'Workspace root, overriding discovery from the current directory.' },
+    { name: '--json', type: 'bool', description: 'Raw JSON on stdout for programmatic consumers.' },
+];
+export function findNode(tokens) {
+    let node = commandTree;
+    let consumed = 0;
+    while (node.children?.length && tokens[consumed]) {
+        const child = node.children.find((candidate) => candidate.name === tokens[consumed]);
+        if (!child)
+            break;
+        node = child;
+        consumed++;
+    }
+    return { node, consumed };
+}
+export function parseInvocation(argv, cwd = realpathSync(process.cwd())) {
+    const helpIndex = argv.findIndex((token) => token === '-h' || token === '--help');
+    const withoutHelp = helpIndex >= 0 ? [...argv.slice(0, helpIndex), ...argv.slice(helpIndex + 1)] : [...argv];
+    const { tokens: noHelp, commandTokens } = normalizeGlobals(withoutHelp);
+    const pathTokens = [];
+    for (const token of commandTokens) {
+        if (token === '--' || token.startsWith('-'))
+            break;
+        pathTokens.push(token);
+    }
+    const { node, consumed } = findNode(pathTokens);
+    if (helpIndex >= 0)
+        return { help: node };
+    if (node.children && consumed < pathTokens.length)
+        return invalid(node, [{ field: 'command', received: pathTokens[consumed], expected: `one of ${node.children.map((child) => child.name).join(', ')}`, next: `Run tsym ${node.name === 'tsym' ? '' : node.name + ' '}-h and read the command tree.` }]);
+    const parsed = parseArgs(noHelp.slice(consumed), node);
+    if (node.children && consumed === pathTokens.length && parsed.problems.length === 0 && parsed.input.args.length === 0)
+        return { help: node };
+    const root = parsed.input.flags['--root'];
+    const json = parsed.input.flags['--json'] === true;
+    const constraintProblems = (node.constraints ?? []).flatMap((constraint) => constraint.check(parsed.input));
+    if (parsed.problems.length > 0 || constraintProblems.length > 0)
+        return invalid(node, [...parsed.problems, ...constraintProblems]);
+    return { root, cwd, json, path: noHelp.slice(0, consumed), declaration: node, input: parsed.input };
+}
+function parseArgs(tokens, node) {
+    const flags = new Map([...globals, ...(node.flags ?? [])].map((flag) => [flag.name, flag]));
+    const values = {};
+    const explicit = new Set();
+    for (const declaration of flags.values())
+        if (declaration.default !== undefined)
+            values[declaration.name] = declaration.default;
+    const args = [];
+    const problems = [];
+    let positional = true;
+    for (let index = 0; index < tokens.length; index++) {
+        const token = tokens[index];
+        if (token === '--') {
+            positional = false;
+            continue;
+        }
+        if (positional && token.startsWith('-') && token !== '-') {
+            const [name, inline] = token.split('=', 2);
+            const declaration = flags.get(name);
+            if (!declaration) {
+                const renamed = node.unknownFlagNext?.[name];
+                problems.push({ field: name, received: token, expected: `a declared flag for tsym ${[...nodePath(node), node.name].filter(Boolean).join(' ')}`, next: renamed ?? helpNext(node) });
+                continue;
+            }
+            const duplicated = explicit.has(name) && !declaration.repeat;
+            explicit.add(name);
+            if (declaration.type === 'bool') {
+                if (duplicated)
+                    problems.push({ field: name, received: token, expected: 'one occurrence; this flag is not repeatable', next: helpNext(node) });
+                if (inline !== undefined)
+                    problems.push({ field: name, received: token, expected: 'a boolean flag with no value', next: helpNext(node) });
+                else
+                    values[name] = true;
+                continue;
+            }
+            const raw = inline ?? tokens[++index];
+            if (raw === undefined) {
+                problems.push({ field: name, received: token, expected: `${declaration.type} value`, next: helpNext(node) });
+                continue;
+            }
+            const parsed = repeatValues(raw, declaration, problems, node);
+            if (parsed.length === 0)
+                continue;
+            if (declaration.repeat)
+                values[name] = [...(values[name] ?? []), ...parsed.map(String)];
+            else if (duplicated)
+                problems.push({ field: name, received: raw, expected: 'one value; this flag is not repeatable', next: helpNext(node) });
+            else
+                values[name] = parsed[0];
+        }
+        else
+            args.push(token);
+    }
+    const argument = node.argument;
+    if (argument) {
+        const invalidCount = (argument.repeat === '1' && args.length !== 1) || (argument.repeat === '1+' && args.length < 1);
+        if (invalidCount)
+            problems.push({ field: `<${argument.name}>`, received: args.length === 0 ? 'none' : args.join(' '), expected: argument.repeat === '1' ? 'exactly one value' : 'one or more values', next: helpNext(node) });
+        if (node.name === 'rename' && args.length !== 2)
+            problems.push({ field: '<symbol> <newName>', received: args.join(' ') || 'none', expected: 'exactly two values', next: helpNext(node) });
+    }
+    else if (args.length > 0)
+        problems.push({ field: 'arguments', received: args.join(' '), expected: 'no positional arguments', next: helpNext(node) });
+    return { input: { args, flags: values, explicit }, problems };
+}
+function repeatValues(raw, declaration, problems, node) {
+    const values = declaration.repeat && declaration.type === 'string' && declaration.values ? raw.split(',') : [raw];
+    return values.map((value) => parseValue(value, declaration, problems, node)).filter((value) => value !== undefined);
+}
+function parseValue(raw, declaration, problems, node) {
+    if (declaration.type === 'int') {
+        if (!/^-?\d+$/.test(raw)) {
+            problems.push({ field: declaration.name, received: raw, expected: 'an integer', next: helpNext(node) });
+            return undefined;
+        }
+        const value = Number(raw);
+        if (declaration.minimum !== undefined && value < declaration.minimum) {
+            problems.push({ field: declaration.name, received: raw, expected: `an integer at least ${declaration.minimum}`, next: helpNext(node) });
+            return undefined;
+        }
+        return value;
+    }
+    if (declaration.values && !declaration.values.includes(raw)) {
+        problems.push({ field: declaration.name, received: raw, expected: `one of ${declaration.values.join(', ')}`, next: helpNext(node) });
+        return undefined;
+    }
+    return raw;
+}
+function normalizeGlobals(tokens) {
+    const commandTokens = [];
+    const globals = [];
+    for (let index = 0; index < tokens.length; index++) {
+        const token = tokens[index];
+        if (token === '--json') {
+            globals.push(token);
+            continue;
+        }
+        if (token === '--root') {
+            globals.push(token);
+            if (tokens[index + 1] !== undefined)
+                globals.push(tokens[++index]);
+            continue;
+        }
+        if (token.startsWith('--root=')) {
+            globals.push(token);
+            continue;
+        }
+        commandTokens.push(token);
+    }
+    return { tokens: [...commandTokens, ...globals], commandTokens };
+}
+function nodePath(node) { return node === commandTree ? [] : []; }
+function helpNext(node) { return `Run \`tsym ${node.name === 'tsym' ? '' : node.name + ' '}-h\` and read the schema before re-issuing.`; }
+function invalid(node, problems) { return { category: 'invocation', code: 'invalid-invocation', problems: problems.map((problem) => ({ ...problem, next: problem.next ?? helpNext(node) })) }; }

package/dist/commands/types.d.ts

@@ -0,0 +1,80 @@
+export type Primitive = 'bool' | 'int' | 'path' | 'glob' | 'string';
+export interface FlagDeclaration {
+    name: string;
+    type: Primitive;
+    repeat?: true;
+    default?: boolean | number | string;
+    values?: readonly string[];
+    minimum?: number;
+    description: string;
+}
+export interface ArgumentDeclaration {
+    name: string;
+    repeat: '0+' | '1' | '1+';
+    description: string;
+}
+export interface Constraint {
+    check(input: ParsedInput): ValidationProblem[];
+}
+export interface CommandDeclaration {
+    name: string;
+    description: string;
+    whenToUse?: string;
+    model?: string;
+    argument?: ArgumentDeclaration;
+    flags?: readonly FlagDeclaration[];
+    constraints?: readonly Constraint[];
+    output?: string;
+    effects?: string;
+    children?: readonly CommandDeclaration[];
+    handler?: HandlerName;
+    state?: () => string | null;
+}
+export type HandlerName = 'outline' | 'find' | 'show' | 'type' | 'inspect' | 'query' | 'search' | 'check' | 'rename' | 'server-status' | 'server-stop' | 'server-reload';
+export interface ParsedInput {
+    args: string[];
+    flags: Record<string, boolean | number | string | string[]>;
+    explicit: ReadonlySet<string>;
+}
+export interface ValidationProblem {
+    field: string;
+    received: string;
+    expected: string;
+    next?: string;
+}
+export interface Invocation {
+    root: string | undefined;
+    /** The client's real working directory. Filesystem operands resolve from it; symbol addresses resolve from root. */
+    cwd: string;
+    json: boolean;
+    path: string[];
+    declaration: CommandDeclaration;
+    input: ParsedInput;
+}
+export interface InvocationError {
+    category: 'invocation';
+    code: string;
+    problems: ValidationProblem[];
+}
+export interface ToolError {
+    category: 'tool';
+    code: string;
+    attributes?: Record<string, string>;
+    message: string;
+    logPath?: string;
+    received?: string;
+    expected?: string;
+    next?: string;
+}
+export interface OutputNode {
+    element: string;
+    attributes?: Record<string, string | number | boolean | undefined>;
+    text?: string;
+    children?: OutputNode[];
+}
+export interface Answer {
+    data: OutputNode | OutputNode[];
+    count: number;
+    receipt?: string;
+}
+export type Completion = Answer | InvocationError | ToolError;

package/dist/commands/types.js

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

package/dist/core/declarations.d.ts

@@ -0,0 +1,48 @@
+import { SourceReader, type SyntaxDeclaration } from './source.js';
+export interface DeclarationAddress {
+    path: string;
+    line: number;
+    col: number;
+}
+export interface DeclarationRecord {
+    address: string;
+    location: DeclarationAddress;
+    file: string;
+    kind: string;
+    name: string;
+    qualifiedName: string;
+    nameSpan: {
+        start: number;
+        end: number;
+    };
+    span: {
+        start: number;
+        end: number;
+    };
+}
+export declare class DeclarationError extends Error {
+    readonly code: 'no-such-path' | 'not-in-program' | 'unresolvable-symbol' | 'ambiguous-symbol' | 'invalid-address';
+    readonly candidates: string[];
+    constructor(code: 'no-such-path' | 'not-in-program' | 'unresolvable-symbol' | 'ambiguous-symbol' | 'invalid-address', message: string, candidates?: string[]);
+}
+export declare class DeclarationResolutionErrors extends Error {
+    readonly errors: readonly DeclarationError[];
+    constructor(errors: readonly DeclarationError[]);
+}
+/** Resolves every declaration identity from the committed index. */
+export declare class DeclarationResolver {
+    readonly root: string;
+    readonly source: SourceReader;
+    private readonly storeFor;
+    constructor(root: string, source: SourceReader, storeFor: () => import('../store/store.js').Store | undefined);
+    resolve(input: string): Promise<DeclarationRecord>;
+    resolveAll(inputs: readonly string[]): Promise<DeclarationRecord[]>;
+    resolveAddress(address: DeclarationAddress): Promise<DeclarationRecord>;
+    resolveName(name: string): Promise<DeclarationRecord>;
+    fromSyntax(file: string, declaration: SyntaxDeclaration): DeclarationRecord;
+    private rows;
+    private record;
+    private unresolvableAddress;
+    private validatePosition;
+    private notInProgram;
+}