@laitszkin/apollo-toolkit 4.0.11 → 4.1.1

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

@@ -0,0 +1,133 @@
+import { describe, it, mock, before } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+const mockSearchResults = [];
+// ---------------------------------------------------------------------------
+// Pre-load @colbymchenry/codegraph so we can mock its methods before
+// cmd-explore.js performs its own require().
+// ---------------------------------------------------------------------------
+const require = createRequire(import.meta.url);
+const { CodeGraph } = require('@colbymchenry/codegraph');
+let mockInstance;
+before(() => {
+    mockInstance = {
+        searchNodes: () => mockSearchResults.map(r => ({ node: r.node, score: r.score })),
+        getCallers: () => [],
+        getCallees: () => [],
+        getCode: async () => null,
+        close: () => { },
+    };
+    mock.method(CodeGraph, 'open', async () => mockInstance);
+});
+// ---------------------------------------------------------------------------
+// Import the module under test (same cached CodeGraph is used internally)
+// ---------------------------------------------------------------------------
+let handleExplore;
+before(async () => {
+    const mod = await import('./cmd-explore.js');
+    handleExplore = mod.handleExplore;
+});
+// =========================================================================
+// REGTEST-7: Explore output should group symbols by file
+// =========================================================================
+describe('REGTEST-7: Explore grouping by file', () => {
+    it('should group symbols under a single file header', async () => {
+        // Arrange: two symbols in the same file
+        mockSearchResults.length = 0;
+        mockSearchResults.push({
+            node: {
+                id: '1',
+                name: 'addUser',
+                kind: 'function',
+                filePath: 'src/utils.ts',
+                startLine: 10,
+                endLine: 25,
+                qualifiedName: 'utils.addUser',
+                signature: '(name: string, age: number): User',
+            },
+            score: 0.95,
+        }, {
+            node: {
+                id: '2',
+                name: 'deleteUser',
+                kind: 'function',
+                filePath: 'src/utils.ts',
+                startLine: 30,
+                endLine: 40,
+                qualifiedName: 'utils.deleteUser',
+                signature: '(id: number): void',
+            },
+            score: 0.85,
+        });
+        // Capture stdout
+        const stdoutChunks = [];
+        const origWrite = process.stdout.write;
+        process.stdout.write = ((chunk) => {
+            stdoutChunks.push(String(chunk));
+            return true;
+        });
+        try {
+            // Act
+            const exitCode = await handleExplore('/fake/project', 'utils', {});
+            // Assert
+            assert.strictEqual(exitCode, 0);
+            const output = stdoutChunks.join('');
+            // Exactly one file header for the shared filePath
+            const headerMatches = output.match(/=== src\/utils\.ts ===/g);
+            assert.strictEqual(headerMatches?.length, 1, 'Expected exactly one file header for src/utils.ts, ' +
+                `got ${headerMatches?.length ?? 0}`);
+            // Both symbols appear in the output
+            assert.ok(output.includes('addUser'), 'Output should contain addUser');
+            assert.ok(output.includes('deleteUser'), 'Output should contain deleteUser');
+            // File header precedes both symbols (not duplicated)
+            const headerIdx = output.indexOf('=== src/utils.ts ===');
+            assert.ok(headerIdx < output.indexOf('addUser'), 'File header should appear before addUser');
+            assert.ok(headerIdx < output.indexOf('deleteUser'), 'File header should appear before deleteUser');
+        }
+        finally {
+            process.stdout.write = origWrite;
+        }
+    });
+});
+// =========================================================================
+// REGTEST-8: Explore --feature acceptance
+// =========================================================================
+describe('REGTEST-8: Explore --feature acceptance', () => {
+    it('should accept feature parameter without error', async () => {
+        // Arrange: at least one result so the feature line is emitted
+        mockSearchResults.length = 0;
+        mockSearchResults.push({
+            node: {
+                id: '3',
+                name: 'authLogin',
+                kind: 'function',
+                filePath: 'src/auth.ts',
+                startLine: 5,
+                endLine: 20,
+                qualifiedName: 'auth.login',
+                signature: '(credentials: Record<string, unknown>): Session',
+            },
+            score: 0.9,
+        });
+        const stdoutChunks = [];
+        const origWrite = process.stdout.write;
+        process.stdout.write = ((chunk) => {
+            stdoutChunks.push(String(chunk));
+            return true;
+        });
+        try {
+            // Act — pass feature without json, expect no error
+            const exitCode = await handleExplore('/fake/project', 'authLogin', {
+                feature: 'auth',
+                json: false,
+            });
+            // Assert
+            assert.strictEqual(exitCode, 0, 'Should return exit code 0');
+            const output = stdoutChunks.join('');
+            assert.ok(output.includes('Feature: auth'), 'Output should include "Feature: auth" header');
+        }
+        finally {
+            process.stdout.write = origWrite;
+        }
+    });
+});

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

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

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

@@ -0,0 +1,83 @@
+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-01: handleListApis --all flag splice', () => {
+    it('should include non-exported symbols with all=true and filter them with all=false', async (ctx) => {
+        // Arrange: three nodes — two exported, one non-exported
+        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: false,
+            },
+            {
+                id: 'n3',
+                name: 'funcC',
+                kind: 'function',
+                filePath: 'src/lib/c.ts',
+                startLine: 1,
+                endLine: 20,
+                qualifiedName: 'funcC',
+                signature: '(z: boolean): void',
+                isExported: true,
+            },
+        ];
+        // Mock CodeGraph.open before importing the module under test
+        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=true — all symbols appear, grouped by directory
+        {
+            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('funcA'), 'all=true: should include exported funcA');
+            assert.ok(output.includes('funcB'), 'all=true: should include non-exported funcB');
+            assert.ok(output.includes('funcC'), 'all=true: should include exported funcC');
+            assert.ok(output.includes('=== src/feature/ ==='), 'all=true: should group src/feature/');
+            assert.ok(output.includes('=== src/lib/ ==='), 'all=true: should group src/lib/');
+            ctx.mock.reset();
+        }
+        // Test 2: all=false — only exported symbols, ungrouped
+        {
+            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('funcA'), 'all=false: should include exported funcA');
+            assert.ok(!output.includes('funcB'), 'all=false: should NOT include non-exported funcB');
+            assert.ok(output.includes('funcC'), 'all=false: should include exported funcC');
+            assert.ok(!output.includes('=== src/feature/ ==='), 'all=false: should not group');
+            assert.ok(!output.includes('=== src/lib/ ==='), 'all=false: should not group');
+        }
+        // Clean up global mocks (CodeGraph.open)
+        mock.reset();
+    });
+});

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

@@ -0,0 +1,5 @@
+export interface InitOptions {
+    index?: boolean;
+    json?: boolean;
+}
+export declare function handleInit(projectRoot: string, options?: InitOptions): Promise<number>;

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

@@ -0,0 +1,50 @@
+import { createOrOpenIndex, closeIndex } from './cg-instance.js';
+import { formatSummary, formatOutput } from './formatter.js';
+export async function handleInit(projectRoot, options = {}) {
+    const progressEvents = [];
+    const start = Date.now();
+    const cg = await createOrOpenIndex(projectRoot, {
+        index: options.index,
+        onProgress: (p) => {
+            progressEvents.push({ phase: p.phase, current: p.current, total: p.total });
+            if (process.stdout.isTTY) {
+                process.stdout.write(`\r  Indexing: ${p.phase} ${p.current}/${p.total}${p.currentFile ? `  ${p.currentFile}` : ''}`);
+            }
+        },
+    });
+    if (options.index && process.stdout.isTTY) {
+        process.stdout.write('\n');
+    }
+    const stats = cg.getStats();
+    closeIndex(cg);
+    const durationMs = Date.now() - start;
+    const result = {
+        projectRoot,
+        initialized: true,
+        indexed: !!options.index,
+        durationMs,
+        stats: {
+            fileCount: stats.fileCount,
+            nodeCount: stats.nodeCount,
+            edgeCount: stats.edgeCount,
+        },
+        progress: progressEvents.length > 0 ? progressEvents : undefined,
+    };
+    if (options.json) {
+        process.stdout.write(formatOutput(result, { json: true }) + '\n');
+    }
+    else {
+        const summary = [
+            ['Project:', projectRoot],
+            ['Status:', 'Initialized'],
+        ];
+        if (options.index) {
+            summary.push(['Files:', stats.fileCount]);
+            summary.push(['Nodes:', stats.nodeCount]);
+            summary.push(['Edges:', stats.edgeCount]);
+            summary.push(['Duration:', `${durationMs}ms`]);
+        }
+        process.stdout.write(formatSummary(summary) + '\n');
+    }
+    return 0;
+}

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

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

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 {};