@laitszkin/apollo-toolkit 4.0.11 → 4.1.0

package/packages/tools/codegraph/dist/lib/cmd-init.test.js

@@ -0,0 +1,51 @@
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+// Mock cg-instance before importing cmd-init so the mock takes effect
+// before module resolution caches anything.
+mock.module('./cg-instance.js', {
+    namedExports: {
+        createOrOpenIndex: async (_projectRoot, _options) => ({
+            getStats: () => ({ fileCount: 42, nodeCount: 1280, edgeCount: 5600 }),
+            close: () => { },
+        }),
+        closeIndex: () => { },
+    },
+});
+describe('handleInit', () => {
+    it('should include Duration: in TTY summary output when --index is used', async () => {
+        const writes = [];
+        const origWrite = process.stdout.write.bind(process.stdout);
+        process.stdout.write = (chunk, ..._rest) => {
+            writes.push(String(chunk));
+            return true;
+        };
+        try {
+            const { handleInit } = await import('./cmd-init.js');
+            const code = await handleInit('/tmp/test-project', { index: true, json: false });
+            assert.strictEqual(code, 0);
+            const output = writes.join('');
+            assert.ok(output.includes('Duration:'), `Expected summary output to contain "Duration:", got:\n${output}`);
+        }
+        finally {
+            process.stdout.write = origWrite;
+        }
+    });
+    it('should include durationMs in JSON output when --index is used', async () => {
+        const writes = [];
+        const origWrite = process.stdout.write.bind(process.stdout);
+        process.stdout.write = (chunk, ..._rest) => {
+            writes.push(String(chunk));
+            return true;
+        };
+        try {
+            const { handleInit } = await import('./cmd-init.js');
+            const code = await handleInit('/tmp/test-project', { index: true, json: true });
+            assert.strictEqual(code, 0);
+            const output = writes.join('');
+            assert.ok(output.includes('durationMs'), `Expected JSON output to contain "durationMs", got:\n${output}`);
+        }
+        finally {
+            process.stdout.write = origWrite;
+        }
+    });
+});

package/packages/tools/codegraph/dist/lib/cmd-list-apis.d.ts

@@ -0,0 +1,5 @@
+export interface ListApisOptions {
+    json?: boolean;
+    all?: boolean;
+}
+export declare function handleListApis(projectRoot: string, feature?: string, options?: ListApisOptions): Promise<number>;

package/packages/tools/codegraph/dist/lib/cmd-list-apis.js

@@ -0,0 +1,64 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+import { closeIndex } from './cg-instance.js';
+import { formatApiList, formatApiListGrouped, formatOutput } from './formatter.js';
+export async function handleListApis(projectRoot, feature, options = {}) {
+    const { CodeGraph } = require('@colbymchenry/codegraph');
+    const cg = await CodeGraph.open(projectRoot, { sync: false, readOnly: true });
+    let nodes = cg.getNodesByKind('function');
+    // Filter by feature directory if specified
+    if (feature) {
+        const featurePath = feature.replace(/^\/?/, '').replace(/\/?$/, '/');
+        nodes = nodes.filter((n) => n.filePath.startsWith(featurePath));
+    }
+    // Only exported functions unless --all is specified
+    if (!options.all) {
+        nodes = nodes.filter((n) => n.isExported);
+    }
+    const apis = [];
+    for (const node of nodes) {
+        const callers = cg.getCallers(node.id).map((c) => ({
+            name: c.node.name,
+            filePath: c.node.filePath,
+            startLine: c.node.startLine,
+        }));
+        apis.push({
+            name: node.name,
+            kind: node.kind,
+            filePath: node.filePath,
+            startLine: node.startLine,
+            endLine: node.endLine,
+            qualifiedName: node.qualifiedName,
+            signature: node.signature,
+            isExported: !!node.isExported,
+            callerCount: callers.length,
+            callers,
+        });
+    }
+    closeIndex(cg);
+    if (options.json) {
+        // For JSON with --all, group by directory
+        if (options.all) {
+            const grouped = {};
+            for (const api of apis) {
+                const dir = api.filePath.substring(0, api.filePath.lastIndexOf('/'));
+                if (!grouped[dir])
+                    grouped[dir] = [];
+                grouped[dir].push(api);
+            }
+            process.stdout.write(formatOutput(grouped, { json: true }) + '\n');
+        }
+        else {
+            process.stdout.write(formatOutput(apis, { json: true }) + '\n');
+        }
+    }
+    else {
+        if (options.all) {
+            process.stdout.write(formatApiListGrouped(apis) + '\n');
+        }
+        else {
+            process.stdout.write(formatApiList(apis) + '\n');
+        }
+    }
+    return 0;
+}

package/packages/tools/codegraph/dist/lib/cmd-list-apis.test.d.ts

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

package/packages/tools/codegraph/dist/lib/cmd-list-apis.test.js

@@ -0,0 +1,69 @@
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+describe('handleListApis', () => {
+    it('should group APIs by directory when --all is used and show ungrouped output without --all', async (ctx) => {
+        const nodes = [
+            {
+                id: 'n1',
+                name: 'funcA',
+                kind: 'function',
+                filePath: 'src/feature/a.ts',
+                startLine: 10,
+                endLine: 30,
+                qualifiedName: 'funcA',
+                signature: '(x: string): void',
+                isExported: true,
+            },
+            {
+                id: 'n2',
+                name: 'funcB',
+                kind: 'function',
+                filePath: 'src/lib/b.ts',
+                startLine: 5,
+                endLine: 25,
+                qualifiedName: 'funcB',
+                signature: '(y: number): string',
+                isExported: true,
+            },
+        ];
+        // Use manual require + mock.method instead of ctx.mock.module,
+        // because lazy CJS require() inside handlers bypasses mock.module interception.
+        const { CodeGraph } = require('@colbymchenry/codegraph');
+        const openMock = mock.method(CodeGraph, 'open', async () => ({
+            getNodesByKind: (_kind) => nodes,
+            getCallers: (_id) => [],
+            close: () => { },
+        }));
+        const { handleListApis } = await import('./cmd-list-apis.js');
+        // Test 1: --all produces directory-grouped output
+        {
+            const chunks = [];
+            ctx.mock.method(process.stdout, 'write', (chunk) => {
+                chunks.push(String(chunk));
+            });
+            await handleListApis('/fake/root', undefined, { all: true });
+            const output = chunks.join('');
+            assert.ok(output.includes('=== src/feature/ ==='), 'should group under src/feature/');
+            assert.ok(output.includes('=== src/lib/ ==='), 'should group under src/lib/');
+            assert.ok(output.includes('funcA'), 'should list funcA in output');
+            assert.ok(output.includes('funcB'), 'should list funcB in output');
+            ctx.mock.reset();
+        }
+        // Test 2: without --all, output is not grouped
+        {
+            const chunks = [];
+            ctx.mock.method(process.stdout, 'write', (chunk) => {
+                chunks.push(String(chunk));
+            });
+            await handleListApis('/fake/root', undefined, { all: false });
+            const output = chunks.join('');
+            assert.ok(!output.includes('=== src/feature/ ==='), 'should not group under src/feature/');
+            assert.ok(!output.includes('=== src/lib/ ==='), 'should not group under src/lib/');
+            assert.ok(output.includes('APIs'), 'should start with APIs count');
+        }
+        // Clean up all mocks (including CodeGraph.open)
+        mock.reset();
+    });
+});

package/packages/tools/codegraph/dist/lib/cmd-search.d.ts

@@ -0,0 +1,5 @@
+export interface SearchOptions {
+    limit?: number;
+    json?: boolean;
+}
+export declare function handleSearch(projectRoot: string, query: string, options?: SearchOptions): Promise<number>;

package/packages/tools/codegraph/dist/lib/cmd-search.js

@@ -0,0 +1,21 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+import { closeIndex } from './cg-instance.js';
+import { formatSearchResults, formatOutput } from './formatter.js';
+export async function handleSearch(projectRoot, query, options = {}) {
+    const { CodeGraph } = require('@colbymchenry/codegraph');
+    if (!CodeGraph.isInitialized(projectRoot)) {
+        process.stderr.write('CodeGraph is not initialized. Run `apltk codegraph init` first.\n');
+        return 1;
+    }
+    const cg = await CodeGraph.open(projectRoot, { sync: false, readOnly: true });
+    const results = cg.searchNodes(query, { limit: options.limit ?? 20 });
+    closeIndex(cg);
+    if (options.json) {
+        process.stdout.write(formatOutput(results, { json: true }) + '\n');
+    }
+    else {
+        process.stdout.write(formatSearchResults(results) + '\n');
+    }
+    return 0;
+}

package/packages/tools/codegraph/dist/lib/cmd-search.test.d.ts

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

package/packages/tools/codegraph/dist/lib/cmd-search.test.js

@@ -0,0 +1,30 @@
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+describe('REGTEST-R2-03: handleSearch — CodeGraph init check', () => {
+    it('should return exit code 1 when CodeGraph is not initialized', async () => {
+        // Mock CodeGraph.isInitialized to return false before importing the module under test
+        const { CodeGraph } = require('@colbymchenry/codegraph');
+        const initMock = mock.method(CodeGraph, 'isInitialized', () => false);
+        // Import after mock is in place
+        const { handleSearch } = await import('./cmd-search.js');
+        // Capture stderr writes
+        const stderrChunks = [];
+        const originalStderrWrite = process.stderr.write.bind(process.stderr);
+        process.stderr.write = (chunk) => {
+            stderrChunks.push(String(chunk));
+            return true;
+        };
+        try {
+            const exitCode = await handleSearch('/test/project', 'testQuery', {});
+            assert.strictEqual(exitCode, 1);
+            const stderrOutput = stderrChunks.join('');
+            assert.ok(stderrOutput.includes('CodeGraph is not initialized'), 'stderr should contain "CodeGraph is not initialized" message');
+        }
+        finally {
+            process.stderr.write = originalStderrWrite;
+            initMock.mock.restore();
+        }
+    });
+});

package/packages/tools/codegraph/dist/lib/cmd-status.d.ts

@@ -0,0 +1,4 @@
+export interface StatusOptions {
+    json?: boolean;
+}
+export declare function handleStatus(projectRoot: string, options?: StatusOptions): Promise<number>;

package/packages/tools/codegraph/dist/lib/cmd-status.js

@@ -0,0 +1,44 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+import { closeIndex, getCodeGraphModule } from './cg-instance.js';
+import { formatSummary, formatOutput } from './formatter.js';
+export async function handleStatus(projectRoot, options = {}) {
+    if (!getCodeGraphModule().CodeGraph.isInitialized(projectRoot)) {
+        process.stderr.write('CodeGraph is not initialized. Run `apltk codegraph init` first.\n');
+        return 1;
+    }
+    const cg = await getCodeGraphModule().CodeGraph.open(projectRoot, { sync: false, readOnly: true });
+    const stats = cg.getStats();
+    closeIndex(cg);
+    if (options.json) {
+        process.stdout.write(formatOutput(stats, { json: true }) + '\n');
+    }
+    else {
+        // Summarize nodes by kind (skip zero entries)
+        const kindEntries = Object.entries(stats.nodesByKind).filter(([, v]) => v > 0);
+        const nodeKindSummary = kindEntries.map(([kind, count]) => `    ${kind.padEnd(14)} ${count}`).join('\n');
+        const edgeKindEntries = Object.entries(stats.edgesByKind).filter(([, v]) => v > 0);
+        const edgeKindSummary = edgeKindEntries.map(([kind, count]) => `    ${kind.padEnd(14)} ${count}`).join('\n');
+        const langEntries = Object.entries(stats.filesByLanguage || {}).filter(([, v]) => v > 0);
+        const langSummary = langEntries.length > 0
+            ? langEntries.map(([lang, count]) => `    ${lang.padEnd(14)} ${count}`).join('\n')
+            : '    (no files indexed)';
+        const summary = [
+            ['Project:', projectRoot],
+            ['Files:', stats.fileCount],
+            ['Nodes:', stats.nodeCount],
+            ['Edges:', stats.edgeCount],
+            ['DB size:', `${(stats.dbSizeBytes / 1024).toFixed(1)} KB`],
+            ['Last updated:', new Date(stats.lastUpdated).toISOString()],
+            ['', ''],
+            ['Nodes by kind:', ''],
+        ];
+        process.stdout.write(formatSummary(summary) + '\n');
+        process.stdout.write(nodeKindSummary + '\n');
+        process.stdout.write('\nEdges by kind:\n');
+        process.stdout.write(edgeKindSummary + '\n');
+        process.stdout.write('\nLanguages:\n');
+        process.stdout.write(langSummary + '\n');
+    }
+    return 0;
+}

package/packages/tools/codegraph/dist/lib/cmd-status.test.d.ts

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

package/packages/tools/codegraph/dist/lib/cmd-status.test.js

@@ -0,0 +1,72 @@
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+describe('REGTEST-6: handleStatus — Languages section', () => {
+    it('should display filesByLanguage entries in human-readable output', async () => {
+        const testStats = {
+            fileCount: 100,
+            nodeCount: 500,
+            edgeCount: 200,
+            dbSizeBytes: 1_024_000,
+            lastUpdated: new Date('2026-06-01T12:00:00Z').toISOString(),
+            nodesByKind: { function: 50, class: 10 },
+            edgesByKind: { calls: 30, extends: 5 },
+            filesByLanguage: { typescript: 10, javascript: 5 },
+        };
+        const mockCg = {
+            getStats: () => testStats,
+            close: () => { },
+        };
+        // Load the same CodeGraph module that cmd-status.js uses (shared CJS cache),
+        // then mock CodeGraph.open + isInitialized so handleStatus uses our fake instance.
+        const { CodeGraph } = require('@colbymchenry/codegraph');
+        const openMock = mock.method(CodeGraph, 'open', async () => mockCg);
+        const initMock = mock.method(CodeGraph, 'isInitialized', () => true);
+        // Import the module under test AFTER the mock is in place
+        const { handleStatus } = await import('./cmd-status.js');
+        // Capture stdout writes
+        const chunks = [];
+        const originalWrite = process.stdout.write.bind(process.stdout);
+        process.stdout.write = (chunk) => {
+            chunks.push(String(chunk));
+            return true;
+        };
+        try {
+            const exitCode = await handleStatus('/test/project', {});
+            assert.strictEqual(exitCode, 0);
+            const output = chunks.join('');
+            assert.ok(output.includes('Languages:'), 'Output should contain "Languages:" section header');
+            assert.ok(output.includes('typescript'), 'Output should contain "typescript" language name');
+            assert.ok(output.includes('javascript'), 'Output should contain "javascript" language name');
+        }
+        finally {
+            process.stdout.write = originalWrite;
+            openMock.mock.restore();
+            initMock.mock.restore();
+        }
+    });
+    it('REGTEST-R2-02: should return exit code 1 when CodeGraph is not initialized', async () => {
+        const { CodeGraph } = require('@colbymchenry/codegraph');
+        const initMock = mock.method(CodeGraph, 'isInitialized', () => false);
+        // Import fresh (module cache returns same CodeGraph reference with mocked isInitialized)
+        const { handleStatus } = await import('./cmd-status.js');
+        // Capture stderr writes
+        const stderrChunks = [];
+        const originalStderrWrite = process.stderr.write.bind(process.stderr);
+        process.stderr.write = (chunk) => {
+            stderrChunks.push(String(chunk));
+            return true;
+        };
+        try {
+            const exitCode = await handleStatus('/test/project', {});
+            assert.strictEqual(exitCode, 1);
+            const stderrOutput = stderrChunks.join('');
+            assert.ok(stderrOutput.includes('CodeGraph is not initialized'), 'stderr should contain "CodeGraph is not initialized" message');
+        }
+        finally {
+            process.stderr.write = originalStderrWrite;
+            initMock.mock.restore();
+        }
+    });
+});

package/packages/tools/codegraph/dist/lib/cmd-survey.d.ts

@@ -0,0 +1,36 @@
+export interface SurveyOptions {
+    feature?: string;
+    json?: boolean;
+}
+export interface SurveyReport {
+    directory: string;
+    feature?: string;
+    totalFiles: number;
+    totalSymbols: number;
+    files: Array<{
+        filePath: string;
+        language: string;
+        symbolCount: number;
+    }>;
+    entryPoints: Array<{
+        name: string;
+        kind: string;
+        filePath: string;
+        startLine: number;
+        isExported: boolean;
+    }>;
+    suggestedSubmodules: Array<{
+        slug: string;
+        kind: string;
+        role: string;
+        memberFunctions: string[];
+        memberFiles: string[];
+    }>;
+    suggestedEdges: Array<{
+        source: string;
+        target: string;
+        kind: string;
+        label: string;
+    }>;
+}
+export declare function handleSurvey(projectRoot: string, dirPath: string, options?: SurveyOptions): Promise<number>;

package/packages/tools/codegraph/dist/lib/cmd-survey.js

@@ -0,0 +1,142 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { closeIndex } from './cg-instance.js';
+import { formatOutput } from './formatter.js';
+import { scanDirectory } from './survey/scanner.js';
+import { groupIntoSubmodules } from './survey/grouper.js';
+export async function handleSurvey(projectRoot, dirPath, options = {}) {
+    // Check that the target directory exists
+    const targetPath = path.resolve(projectRoot, dirPath);
+    if (!existsSync(targetPath)) {
+        process.stderr.write(`Error: Directory not found: ${dirPath}\n`);
+        return 1;
+    }
+    const { CodeGraph } = require('@colbymchenry/codegraph');
+    const cg = await CodeGraph.open(projectRoot, { sync: false, readOnly: true });
+    // Scan the directory
+    const scan = await scanDirectory(cg, dirPath);
+    const fileSet = new Set(scan.files.map((f) => f.filePath));
+    // Group into submodule suggestions
+    const suggestions = groupIntoSubmodules(scan, cg);
+    // Build edge suggestions from cross-file call relationships
+    const edgeSuggestions = buildEdgeSuggestions(scan, cg, fileSet);
+    // Determine entry points: exported symbols called from outside the scanned directory
+    const entryPoints = scan.allSymbols.filter(s => {
+        if (!s.isExported)
+            return false;
+        const nodes = cg.getNodesByName(s.name);
+        for (const node of nodes) {
+            if (node.filePath !== s.filePath)
+                continue;
+            const callers = cg.getCallers(node.id);
+            for (const caller of callers) {
+                if (!fileSet.has(caller.node.filePath)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    });
+    closeIndex(cg);
+    const report = {
+        directory: dirPath,
+        feature: options.feature,
+        totalFiles: scan.totalFiles,
+        totalSymbols: scan.totalSymbols,
+        files: scan.files.map((f) => ({
+            filePath: f.filePath,
+            language: f.language,
+            symbolCount: f.symbols.length,
+        })),
+        entryPoints,
+        suggestedSubmodules: suggestions.map((s) => ({
+            slug: s.slug,
+            kind: s.kind,
+            role: s.role,
+            memberFunctions: s.memberFunctions,
+            memberFiles: s.memberFiles,
+        })),
+        suggestedEdges: edgeSuggestions,
+    };
+    if (options.json) {
+        process.stdout.write(formatOutput(report, { json: true }) + '\n');
+    }
+    else {
+        // Human-readable output
+        process.stdout.write(`\n=== Survey: ${dirPath} ===\n`);
+        if (report.feature) {
+            process.stdout.write(`Feature: ${report.feature}\n`);
+        }
+        process.stdout.write('\n');
+        process.stdout.write(`Files: ${report.totalFiles}  Symbols: ${report.totalSymbols}\n\n`);
+        process.stdout.write('Files:\n');
+        for (const f of report.files) {
+            process.stdout.write(`  ${f.filePath}  [${f.language}]  (${f.symbolCount} symbols)\n`);
+        }
+        process.stdout.write('\nEntry Points:\n');
+        if (report.entryPoints.length === 0) {
+            process.stdout.write('  (none)\n');
+        }
+        else {
+            for (const ep of report.entryPoints) {
+                process.stdout.write(`  ${ep.name}  [${ep.kind}]  ${ep.filePath}:${ep.startLine}\n`);
+            }
+        }
+        process.stdout.write('\nSuggested Submodules:\n');
+        if (report.suggestedSubmodules.length === 0) {
+            process.stdout.write('  (none)\n');
+        }
+        else {
+            for (const sub of report.suggestedSubmodules) {
+                process.stdout.write(`  ${sub.slug}  [${sub.kind}]  ${sub.role}\n`);
+                process.stdout.write(`    Functions: ${sub.memberFunctions.join(', ')}\n`);
+                process.stdout.write(`    Files: ${sub.memberFiles.join(', ')}\n\n`);
+            }
+        }
+        process.stdout.write('Suggested Edges:\n');
+        if (report.suggestedEdges.length === 0) {
+            process.stdout.write('  (none)\n');
+        }
+        else {
+            for (const edge of report.suggestedEdges) {
+                process.stdout.write(`  ${edge.source} --[${edge.kind}]--> ${edge.target}  (${edge.label})\n`);
+            }
+        }
+        process.stdout.write('\n');
+    }
+    return 0;
+}
+/**
+ * Build suggested edges from cross-file call relationships in the scanned directory.
+ */
+function buildEdgeSuggestions(scan, cg, fileSet) {
+    const edges = [];
+    const dedup = new Set();
+    // For each symbol in the scan, check if it calls symbols outside the scanned directory
+    for (const sym of scan.allSymbols) {
+        const nodes = cg.getNodesByName(sym.name);
+        for (const node of nodes) {
+            if (node.filePath !== sym.filePath)
+                continue;
+            const callees = cg.getCallees(node.id);
+            for (const callee of callees) {
+                // Only consider callees OUTSIDE the scanned directory (cross-boundary edges)
+                if (!fileSet.has(callee.node.filePath)) {
+                    const edgeKey = `${sym.name}::${callee.node.name}`;
+                    if (dedup.has(edgeKey))
+                        continue;
+                    dedup.add(edgeKey);
+                    edges.push({
+                        source: sym.name,
+                        target: callee.node.name,
+                        kind: 'call',
+                        label: `${sym.filePath} -> ${callee.node.filePath}`,
+                    });
+                }
+            }
+        }
+    }
+    return edges;
+}

package/packages/tools/codegraph/dist/lib/cmd-survey.test.d.ts

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