@crouton-kit/tsym 0.1.0 → 0.2.0

package/README.md

@@ -44,7 +44,7 @@ The bundled TypeScript 7 process is always used, so `tsym` works in a checkout w
 
 ## 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`.
+`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`. Prose output of `show`, `type`, or `outline` may be preceded by an `<auto-loaded-context>` block when run inside a crtr node.
 
 ## License
 

package/dist/commands/handlers/find.js

@@ -9,15 +9,13 @@ const handler = async (context, invocation) => {
     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))
+    for (const declaration of declarations(context, name, qualified, prefix)) {
+        if (declaration.kind === 'module' || !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))
+    for (const alias of aliases(context, name, prefix)) {
+        if (!keep(alias, flags))
             continue;
         rows.set(alias.address, alias);
     }
@@ -31,15 +29,18 @@ const handler = async (context, invocation) => {
         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) {
+function declarations(context, name, qualified, prefix) {
     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) }));
+    const property = qualified ? 'qname' : 'name';
+    const comparison = prefix ? 'STARTS WITH' : '=';
+    return query(context.store, `MATCH (d:Declaration) WHERE d.${property} ${comparison} $name 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`, { name }).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) {
+function aliases(context, name, prefix) {
     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 comparison = prefix ? 'STARTS WITH' : '=';
+    return query(context.store, `MATCH (m:Declaration)-[e:EXPORTS]->(d:Declaration) WHERE e.name ${comparison} $name 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`, { name }).flatMap((row) => {
         const fromFile = String(row.fromFile);
         const line = Number(row.line);
         const col = Number(row.col);

package/dist/commands/handlers/inspect.js

@@ -1,9 +1,21 @@
 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 { implementations, memberSummaries, references, traverse } from '../../relations/store-relations.js';
 import { renderGraph } from '../../relations/mermaid.js';
-const relationOrder = ['refs', 'callers', 'calls', 'impl'];
+const relationOrder = ['refs', 'callers', 'calls', 'impl', 'members'];
+const containerKinds = new Set(['class', 'interface', 'enum', 'namespace', 'module', 'type']);
+const callableMemberKinds = new Set(['function', 'method', 'constructor']);
+// A zero is only worth the scope caveat when the kind could have had that relation: a function never has
+// implementations and an interface never makes calls, so those zeros are structural, not a visibility gap.
+const applicableKinds = {
+    refs: undefined,
+    callers: new Set(['function', 'method', 'constructor', 'getter', 'setter', 'class', 'const', 'let', 'var', 'property', 'module', 'namespace']),
+    calls: new Set(['function', 'method', 'constructor', 'getter', 'setter', 'class', 'const', 'let', 'var', 'property', 'module', 'namespace']),
+    impl: new Set(['class', 'interface']),
+};
+function applies(relation, kind) { return applicableKinds[relation]?.has(kind) ?? true; }
+const zeroScopeReceipt = '0 counts cover indexed, compiler-resolved relations only; framework, HTTP, and dependency-injection invocation are not visible';
 const handler = async (context, invocation) => {
     const started = performance.now();
     const selected = selectedRelations(invocation.input.flags['--only']);
@@ -16,35 +28,54 @@ const handler = async (context, invocation) => {
         return graphAnswer(context, seeds, selected, depth, filters, started);
     const blocks = [];
     let answers = 0;
+    let hasZeroRelation = false;
     const receiptParts = [];
     for (const seed of seeds) {
         const header = await signature(context, seed);
+        const summaries = containerKinds.has(seed.kind) ? await memberSummaries(context, seed) : [];
+        const isContainer = summaries.length > 0;
         const relations = [];
+        const seedReceipt = [];
         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`);
+                hasZeroRelation ||= rows.length === 0;
+                relations.push(refBlock(rows, each, true));
+                seedReceipt.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`);
+                hasZeroRelation ||= rows.length === 0 && applies('impl', seed.kind);
+                relations.push(implBlock(rows, each, applies('impl', seed.kind)));
+                seedReceipt.push(`${rows.length} impl`);
+            }
+            else if (relation === 'members') {
+                if (isContainer) {
+                    answers += summaries.length;
+                    relations.push(membersBlock(summaries, each));
+                    seedReceipt.push(`${summaries.length} members`);
+                }
             }
             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` : ''}`);
+                hasZeroRelation ||= result.rows.length === 0 && applies(relation, seed.kind);
+                relations.push(traversalBlock(relation, result, each, applies(relation, seed.kind)));
+                seedReceipt.push(`${result.rows.length} ${relation}${result.excluded ? `, ${result.excluded} excluded` : ''}${result.unresolved ? `, ${result.unresolved} unresolved` : ''}${result.dispatch ? `, ${result.dispatch} dispatch` : ''}`);
             }
         }
+        if (isContainer)
+            seedReceipt.push(memberGuidance(seed, summaries));
+        receiptParts.push(`${seed.name}: ${seedReceipt.join(', ') || 'no indexed members'}`);
         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}` };
+    const capped = selected.length > 0 && each > 0;
+    const only = selected.length === relationOrder.length ? '' : ` ${selected.map((relation) => `--only ${relation}`).join(' ')}`;
+    const rerun = capped ? `; re-run tsym inspect ${invocation.input.args.join(' ')}${only} --each 0 for all rows` : '';
+    const scope = hasZeroRelation ? `; ${zeroScopeReceipt}` : '';
+    return { data: blocks, count: answers, receipt: `${receiptParts.join('; ')}, ${Math.round(performance.now() - started)} ms${rerun}${scope}` };
 };
 async function graphAnswer(context, seeds, selected, depth, filters, started) {
     const relations = [];
@@ -56,25 +87,38 @@ async function graphAnswer(context, seeds, selected, depth, filters, started) {
     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` };
+    const scope = relations.some((result) => result.rows.length === 0) ? `; ${zeroScopeReceipt}` : '';
+    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${scope}` };
 }
 async function signature(_context, record) { return `${normalKind(record.kind)} ${record.qualifiedName}`; }
-function relationBlock(element, rows, path, each, format) {
+function relationBlock(element, rows, path, each, format, scoped = false) {
     if (!rows.length)
-        return { element, attributes: { count: 0 } };
+        return { element, attributes: { count: 0, scope: scoped ? 'compiler-resolved' : undefined } };
     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 refBlock(rows, each, scoped) {
+    return relationBlock('refs', rows, (row) => row.path, each, (row) => `${row.path}:${row.line}:${row.col}  ${row.kind}  ${row.qualifiedName}  ${row.role}`, scoped);
+}
+function implBlock(rows, each, scoped) {
+    return relationBlock('impl', rows, (row) => row.location.path, each, (row) => `${row.address}  ${normalKind(row.kind)}  ${row.qualifiedName}`, scoped);
 }
-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, scoped) {
+    return relationBlock(relation, result.rows, (row) => row.path, each, formatTraversal, scoped);
 }
-function traversalBlock(relation, result, each) {
-    return relationBlock(relation, result.rows, (row) => row.path, each, formatTraversal);
+function membersBlock(rows, each) {
+    return relationBlock('members', rows, (row) => row.path, each, formatMember);
 }
 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 formatMember(row) {
+    const incoming = callableMemberKinds.has(row.kind) ? `${row.callers} callers` : `${row.refs} refs`;
+    return `${row.address}  ${row.kind}  ${row.qualifiedName}  (${incoming}, ${row.calls} calls)`;
+}
+function memberGuidance(seed, members) {
+    const target = [...members].sort((left, right) => right.callers - left.callers || left.line - right.line || left.col - right.col)[0];
+    const callerScope = seed.kind === 'class' ? 'callers are constructor/type uses' : 'container callers do not include member calls';
+    return `${callerScope}; methods have their own — inspect ${target.qualifiedName}`;
+}
 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)]; }

package/dist/commands/handlers/outline.js

@@ -1,6 +1,7 @@
 import { statSync } from 'node:fs';
 import path from 'node:path';
 import { DeclarationError } from '../../core/declarations.js';
+import { membersByContainer } from '../../core/members.js';
 import { matchesPathFilters } from '../../core/receipt.js';
 import { displayPath, scopeFiles } from '../../read/read.js';
 import { query } from '../../store/query.js';
@@ -12,8 +13,9 @@ const handler = async (context, invocation) => {
     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 selectedFiles = [...selected];
+    const declarations = indexed(context, selectedFiles).filter((declaration) => declaration.kind !== 'module');
+    const imports = flags['--imports'] === true && flags['--exported'] !== true && !flags['--kind'] ? indexedImports(context, selectedFiles) : [];
     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();
@@ -23,6 +25,7 @@ const handler = async (context, invocation) => {
         }
     });
     const requestedDirectory = directory !== undefined;
+    const outlinedFile = directFile(invocation);
     const files = new Map();
     for (const declaration of declarations)
         files.set(declaration.path, [...(files.get(declaration.path) ?? []), declaration]);
@@ -33,33 +36,41 @@ const handler = async (context, invocation) => {
     }
     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));
+        : [...files.entries()].flatMap(([file, items]) => [...select(items, flags, requestedDirectory ? depth - 1 : depth).map((symbol) => symbolRow(context.root, 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 };
+    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, displayedFiles: outlinedFile && shown.length > 0 ? [outlinedFile] : [...new Set(shown.flatMap((row) => row.file ? [row.file] : []))], receipt };
 };
-function indexed(context) {
+function directFile(invocation) {
+    if (invocation.input.args.length !== 1)
+        return undefined;
+    const candidate = path.resolve(invocation.cwd, invocation.input.args[0]);
+    try {
+        return statSync(candidate).isFile() ? candidate : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function indexed(context, files) {
     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);
+    return files.length === 0 ? [] : query(context.store, 'MATCH (d:Declaration) WHERE d.file IN $files 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', { files: [...files] }).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) {
+function indexedImports(context, files) {
     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')
+    return files.length === 0 ? [] : query(context.store, 'MATCH (m:Declaration)-[e:IMPORTS]->(d:Declaration) WHERE m.file IN $files 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) WHERE m.file IN $files RETURN m.file AS file, e.line AS line, e.names AS names, external.module AS target', { files: [...files] })
         .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 byContainer = membersByContainer(items);
     const roots = items.filter((item) => item.container === `${item.path}#<module>`);
     const out = [];
     const visit = (item, remaining) => {
@@ -77,10 +88,10 @@ function keep(item, flags) {
     const kinds = flags['--kind'];
     return (!kinds || kinds.includes(item.kind)) && (flags['--exported'] !== true || item.exported);
 }
-function symbolRow(symbol, items, flags) {
+function symbolRow(root, 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 };
+    return { text: `${symbol.address}  ${symbol.kind}${symbol.exported ? '  export' : ''}  ${symbol.qualifiedName}  (${symbol.lines}L${memberCount})`, line: symbol.line, col: symbol.col, file: path.join(root, symbol.path) };
 }
 function importRow(item) { return { text: `${item.address}  import  ${item.name}  ${item.target}`, line: item.line, col: 1 }; }
 function containerRows(root, files, imports, flags, directory) {

package/dist/commands/handlers/show.js

@@ -8,17 +8,18 @@ const handler = async (context, invocation) => {
     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 sites = declaration.location.line === 0 ? [{ file: declaration.file, 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 });
+        rendered.push({ node: { element: 'symbol', attributes: { at: declaration.address, name: declaration.name, kind: declaration.kind, lines }, text }, files: sites.map((site) => site.file) });
     }
     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 },
+        data: { element: 'show', attributes: { count: rendered.length, shown: capped ? shown.length : undefined }, children: shown.map((item) => item.node) },
         count: rendered.length,
+        displayedFiles: [...new Set(shown.flatMap((item) => item.files))],
         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`,
     };
 };
@@ -32,7 +33,7 @@ function storedSpan(context, declaration) {
 }
 async function declarationSites(context, declaration, stored) {
     if (stored.declCount === 1)
-        return [{ source: context.source.read(declaration.file), span: stored }];
+        return [{ file: declaration.file, 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}`);
@@ -48,7 +49,7 @@ async function declarationSites(context, declaration, stored) {
             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 } }];
+            return [{ file: source.fileName, source: context.source.read(source.fileName), span: { endLine: end.line + 1, lines: end.line - start.line + 1, declCount: stored.declCount } }];
         });
     });
     if (sites.length === 0)

package/dist/commands/handlers/type.js

@@ -7,6 +7,7 @@ const handler = async (context, invocation) => {
         const declarations = await context.resolver.resolveAll(invocation.input.args);
         const includeDefinition = invocation.input.flags['--def'] === true;
         const symbols = [];
+        const displayedFiles = [];
         let answers = 0;
         for (const declaration of declarations) {
             const project = await context.projects.membership(declaration.file);
@@ -16,8 +17,9 @@ const handler = async (context, invocation) => {
             if (answer !== null)
                 answers++;
             symbols.push(renderSymbol(declaration, answer, includeDefinition));
+            displayedFiles.push(declaration.file);
         }
-        return { data: { element: 'type', children: symbols }, count: answers };
+        return { data: { element: 'type', children: symbols }, count: answers, displayedFiles: [...new Set(displayedFiles)] };
     }
     catch (error) {
         if (error instanceof DeclarationError || error instanceof DeclarationResolutionErrors)

package/dist/commands/help.js

@@ -16,7 +16,7 @@ export function renderHelp(node, serverState = '<server state="stopped"/>') {
         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>');
+        lines.push('<io>Flags and positional arguments on input. Stdout is one named XML block per call. Prose output of show, type, or outline may be preceded by an &lt;auto-loaded-context&gt; block when run inside a crtr node. 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'));
 }

package/dist/commands/tree.js

@@ -1,6 +1,6 @@
 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 relations = ['refs', 'callers', 'calls', 'impl', 'members'];
 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.' },
@@ -103,7 +103,7 @@ export const commandTree = {
         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('inspect', 'How a symbol relates to the rest of the code.', 'Reach for this for references, callers, calls, implementations, members, 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 five.` }, { 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, impl, or members 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>, <impl>, and, for a container with indexed members, <members> blocks; --only emits only selected blocks. Empty refs, callers, calls, and impl blocks render count="0" and scope="compiler-resolved". 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`; members rows are `path:line:col  kind  qualifiedName  (N callers|refs, N calls)`, in outline order. Class callers are constructor or type uses; inspect the member summary to follow method calls. The receipt names excluded, unresolved, and dispatch counts when nonzero, and explains once that zero counts cover only indexed compiler-resolved relations, not framework, HTTP, or dependency-injection invocation. Each block count is the true total, files is distinct result paths, and shown appears only when capped by --each. --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.'),

package/dist/commands/types.d.ts

@@ -76,5 +76,11 @@ export interface Answer {
     data: OutputNode | OutputNode[];
     count: number;
     receipt?: string;
+    /** Files whose declarations this result displayed; carried over the resident wire but never rendered. */
+    displayedFiles?: string[];
+    /** Read-routed memory returned by the client-side crouter call; never included in tsym JSON. */
+    context?: string;
+    /** Structured context-delivery failure written to stderr without changing the command result. */
+    contextError?: string;
 }
 export type Completion = Answer | InvocationError | ToolError;

package/dist/context-exposure.d.ts

@@ -0,0 +1,9 @@
+import type { Completion, Invocation } from './commands/types.js';
+export interface ExposureResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    error?: string;
+}
+export type ExposureRunner = (files: readonly string[], cwd: string) => Promise<ExposureResult>;
+export declare function attachReadContext(invocation: Invocation, completion: Completion, run?: ExposureRunner, nodeId?: string | undefined): Promise<Completion>;

package/dist/context-exposure.js

@@ -0,0 +1,55 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+export async function attachReadContext(invocation, completion, run = runContextExpose, nodeId = process.env.CRTR_NODE_ID) {
+    if (!nodeId?.trim() || invocation.json || !isReadLeaf(invocation) || !isAnswer(completion) || completion.count === 0)
+        return completion;
+    const files = [...new Set((completion.displayedFiles ?? []).map((file) => path.resolve(file)))];
+    if (files.length === 0)
+        return completion;
+    try {
+        const result = await run(files, invocation.cwd);
+        if (result.exitCode !== 0)
+            return withContextError(completion, deliveryError(result, 'context-expose-failed'));
+        const response = jsonObject(result.stdout);
+        if (!response)
+            return withContextError(completion, structuredError('context-expose-invalid-response', result.stderr || 'crtr sys context expose returned invalid JSON.'));
+        if (response.content === undefined)
+            return completion;
+        if (typeof response.content !== 'string')
+            return withContextError(completion, structuredError('context-expose-invalid-response', 'crtr sys context expose returned a non-string content field.'));
+        return { ...completion, context: response.content };
+    }
+    catch (error) {
+        return withContextError(completion, structuredError('context-expose-failed', error instanceof Error ? error.message : String(error)));
+    }
+}
+function isReadLeaf(invocation) { return invocation.declaration.handler === 'show' || invocation.declaration.handler === 'type' || invocation.declaration.handler === 'outline'; }
+function isAnswer(completion) { return !('category' in completion); }
+function withContextError(completion, contextError) { return { ...completion, contextError }; }
+function jsonObject(text) {
+    try {
+        const value = JSON.parse(text);
+        return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function deliveryError(result, code) {
+    const response = jsonObject(result.stdout);
+    if (response)
+        return JSON.stringify(response);
+    return structuredError(code, result.stderr || result.error || 'crtr sys context expose failed.');
+}
+function structuredError(error, message) { return JSON.stringify({ error, message }); }
+async function runContextExpose(files, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn('crtr', ['sys', 'context', 'expose', '--json', ...files.flatMap((file) => ['--file', file])], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        child.once('error', (error) => resolve({ exitCode: null, stdout, stderr, error: error.message }));
+        child.once('close', (exitCode) => resolve({ exitCode, stdout, stderr }));
+    });
+}

package/dist/core/members.d.ts

@@ -0,0 +1,9 @@
+export interface ContainerMember {
+    key: string;
+    container: string | null;
+    line: number;
+    col: number;
+}
+/** Direct members use the source-position order printed by outline. */
+export declare function directMembers<T extends ContainerMember>(items: readonly T[], container: string): T[];
+export declare function membersByContainer<T extends ContainerMember>(items: readonly T[]): ReadonlyMap<string, T[]>;

package/dist/core/members.js

@@ -0,0 +1,12 @@
+/** Direct members use the source-position order printed by outline. */
+export function directMembers(items, container) {
+    return items.filter((item) => item.container === container).sort(bySourcePosition);
+}
+export function membersByContainer(items) {
+    const groups = new Map();
+    for (const item of items)
+        if (item.container)
+            groups.set(item.container, [...(groups.get(item.container) ?? []), item]);
+    return new Map([...groups].map(([container, members]) => [container, members.sort(bySourcePosition)]));
+}
+function bySourcePosition(a, b) { return a.line - b.line || a.col - b.col; }

package/dist/index/build.d.ts

@@ -1,4 +1,5 @@
 import { type LoadReceipt, type StoreGraph } from '../store/load.js';
+import { type StoreFormatIdentity } from '../store/meta.js';
 import { Store } from '../store/store.js';
 import { Ts7Host } from '../ts7/api.js';
 import { ConfiguredProjects } from '../ts7/projects.js';
@@ -16,7 +17,7 @@ export interface BuiltIndex {
     receipt: BuildReceipt;
 }
 /** Walks the configured project union, adds heritage facts, and atomically replaces the persisted graph. */
-export declare function buildIndex(root: string, program: Ts7Host, projects: ConfiguredProjects, store: Store): BuiltIndex;
+export declare function buildIndex(root: string, program: Ts7Host, projects: ConfiguredProjects, store: Store, identity?: StoreFormatIdentity): BuiltIndex;
 /** Rehydrates an unchanged persisted graph without re-walking the TypeScript program. */
 export declare function reuseIndex(store: Store): BuiltIndex;
 export declare function storeGraph(index: HeritageGraph): StoreGraph;

package/dist/index/build.js

@@ -4,13 +4,13 @@ import { metadataFor, readMetadata, writeMetadata } from '../store/meta.js';
 import { addHeritage } from './heritage.js';
 import { walkIndex } from './walk.js';
 /** Walks the configured project union, adds heritage facts, and atomically replaces the persisted graph. */
-export function buildIndex(root, program, projects, store) {
+export function buildIndex(root, program, projects, store, identity) {
     const started = performance.now();
     const walked = walkIndex(root, program, projects);
     const enriched = addHeritage(root, program, projects, walked);
     const loaded = loadGraph(store, storeGraph(enriched));
     const durationMs = performance.now() - started;
-    writeMetadata(store.path, metadataFor(root, projects, headCommit(root), durationMs));
+    writeMetadata(store.path, metadataFor(root, projects, headCommit(root), durationMs, identity));
     return {
         graph: enriched.graph,
         heritage: enriched.relationships,
@@ -28,7 +28,7 @@ export function reuseIndex(store) {
     const persisted = readGraph(store);
     const metadata = readMetadata(store.path);
     if (!metadata)
-        throw new Error('reuseIndex requires persisted store metadata; canReuse must pass first.');
+        throw new Error('reuseIndex requires persisted store metadata.');
     const durationMs = metadata.indexDurationMs;
     const declarations = new Map(persisted.declarations.map((declaration) => [declaration.key, declaration]));
     const externals = new Map(persisted.externals.map((external) => [external.key, external]));

package/dist/index/refresh.d.ts

@@ -1,4 +1,5 @@
 import { type StoreGraph } from '../store/load.js';
+import { type StoreFormatIdentity } from '../store/meta.js';
 import { Store } from '../store/store.js';
 import { Ts7Host } from '../ts7/api.js';
 import { ConfiguredProjects } from '../ts7/projects.js';
@@ -22,7 +23,7 @@ export interface RefreshResult {
     validation: 'off' | 'matched';
 }
 /** Updates the TS7 snapshot, conservatively re-walks the union, then writes only changed file records. */
-export declare function refreshIndex(root: string, program: Ts7Host, projects: ConfiguredProjects, store: Store, previous: BuiltIndex, options: RefreshOptions): RefreshResult;
+export declare function refreshIndex(root: string, program: Ts7Host, projects: ConfiguredProjects, store: Store, previous: BuiltIndex, options: RefreshOptions, identity?: StoreFormatIdentity): RefreshResult;
 export declare function graphsEqual(left: HeritageGraph, right: HeritageGraph): boolean;
 export declare function fileFingerprint(graph: BuiltIndex['graph'], heritage: readonly HeritageGraph['relationships'][number][], file: string): string;
 export declare function graphFingerprint(graph: StoreGraph): string;

package/dist/index/refresh.js

@@ -5,7 +5,7 @@ import { addHeritage } from './heritage.js';
 import { storeGraph } from './build.js';
 import { walkIndex } from './walk.js';
 /** Updates the TS7 snapshot, conservatively re-walks the union, then writes only changed file records. */
-export function refreshIndex(root, program, projects, store, previous, options) {
+export function refreshIndex(root, program, projects, store, previous, options, identity) {
     const started = performance.now();
     // The update carries a rewritten config's new text, so it must precede the rediscovery that reads membership from it.
     program.update({ fileChanges: options.fileChanges });
@@ -24,7 +24,7 @@ export function refreshIndex(root, program, projects, store, previous, options)
         stored = 'files';
     }
     const durationMs = performance.now() - started;
-    writeMetadata(store.path, metadataFor(root, projects, headCommit(root), durationMs));
+    writeMetadata(store.path, metadataFor(root, projects, headCommit(root), durationMs, identity));
     let validation = 'off';
     if (options.validate) {
         const verification = indexGraph(root, program, projects);