@laitszkin/apollo-toolkit 4.0.11 → 4.1.1

package/packages/tools/codegraph/lib/cmd-explore.ts

@@ -0,0 +1,129 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+import { closeIndex } from './cg-instance.js';
+import { formatOutput } from './formatter.js';
+
+export interface ExploreOptions {
+  json?: boolean;
+  feature?: string;
+}
+
+export async function handleExplore(
+  projectRoot: string,
+  query: string,
+  options: ExploreOptions = {},
+): Promise<number> {
+  const { CodeGraph } = require('@colbymchenry/codegraph');
+  const cg = await CodeGraph.open(projectRoot, { sync: false, readOnly: true });
+
+  // Step 1: Search for the query
+  const searchResults = cg.searchNodes(query, { limit: 10 });
+
+  if (searchResults.length === 0) {
+    process.stdout.write('No symbols found matching the query.\n');
+    closeIndex(cg);
+    return 0;
+  }
+
+  // Step 2: For each result, get callers, callees, and source code
+  type SymbolDetail = {
+    name: string;
+    kind: string;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    qualifiedName: string;
+    signature?: string;
+    callers: Array<{ name: string; filePath: string; startLine: number }>;
+    callees: Array<{ name: string; filePath: string; startLine: number }>;
+    code: string | null;
+  };
+
+  const details: SymbolDetail[] = [];
+  for (const result of searchResults) {
+    const node = result.node;
+    const callers = cg.getCallers(node.id).map((c: any) => ({
+      name: c.node.name,
+      filePath: c.node.filePath,
+      startLine: c.node.startLine,
+    }));
+    const callees = cg.getCallees(node.id).map((c: any) => ({
+      name: c.node.name,
+      filePath: c.node.filePath,
+      startLine: c.node.startLine,
+    }));
+    const code = await cg.getCode(node.id);
+
+    details.push({
+      name: node.name,
+      kind: node.kind,
+      filePath: node.filePath,
+      startLine: node.startLine,
+      endLine: node.endLine,
+      qualifiedName: node.qualifiedName,
+      signature: node.signature,
+      callers,
+      callees,
+      code,
+    });
+  }
+
+  closeIndex(cg);
+
+  if (options.json) {
+    process.stdout.write(formatOutput(details, { json: true }) + '\n');
+    return 0;
+  }
+
+  // Human-readable output — group by filePath
+  const grouped = new Map<string, SymbolDetail[]>();
+  for (const d of details) {
+    const group = grouped.get(d.filePath) ?? [];
+    group.push(d);
+    grouped.set(d.filePath, group);
+  }
+
+  if (options.feature) {
+    process.stdout.write(`Feature: ${options.feature}\n`);
+  }
+
+  for (const [filePath, symbols] of grouped) {
+    process.stdout.write(`\n=== ${filePath} ===\n\n`);
+    for (const d of symbols) {
+      process.stdout.write(`  ${d.name} [${d.kind}] line ${d.startLine}-${d.endLine}\n`);
+      process.stdout.write(`    QName: ${d.qualifiedName}\n`);
+      if (d.signature) process.stdout.write(`    Signature: ${d.signature}\n`);
+
+      process.stdout.write(`    Callers (${d.callers.length}):\n`);
+      if (d.callers.length === 0) {
+        process.stdout.write('      (none)\n');
+      } else {
+        for (const c of d.callers.slice(0, 20)) {
+          process.stdout.write(`      ${c.name}  ${c.filePath}:${c.startLine}\n`);
+        }
+      }
+
+      process.stdout.write(`    Callees (${d.callees.length}):\n`);
+      if (d.callees.length === 0) {
+        process.stdout.write('      (none)\n');
+      } else {
+        for (const c of d.callees.slice(0, 20)) {
+          process.stdout.write(`      ${c.name}  ${c.filePath}:${c.startLine}\n`);
+        }
+      }
+
+      if (d.code) {
+        process.stdout.write(`    Source (${d.filePath}):\n`);
+        const lines = d.code.split('\n');
+        for (let i = 0; i < Math.min(lines.length, 30); i++) {
+          process.stdout.write(`      ${lines[i]}\n`);
+        }
+        if (lines.length > 30) {
+          process.stdout.write(`      ... (${lines.length - 30} more lines)\n`);
+        }
+      }
+    }
+  }
+
+  return 0;
+}

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

@@ -0,0 +1,94 @@
+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: string) => nodes,
+      getCallers: (_id: string) => [],
+      close: () => {},
+    }));
+
+    const { handleListApis } = await import('./cmd-list-apis.js');
+
+    // Test 1: all=true — all symbols appear, grouped by directory
+    {
+      const chunks: string[] = [];
+      ctx.mock.method(process.stdout, 'write', (chunk: string | Uint8Array) => {
+        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: string[] = [];
+      ctx.mock.method(process.stdout, 'write', (chunk: string | Uint8Array) => {
+        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/lib/cmd-init.test.ts

@@ -0,0 +1,68 @@
+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: string, _options?: object) => ({
+      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: string[] = [];
+    const origWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (
+      chunk: unknown,
+      ..._rest: unknown[]
+    ): boolean => {
+      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: string[] = [];
+    const origWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (
+      chunk: unknown,
+      ..._rest: unknown[]
+    ): boolean => {
+      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/lib/cmd-init.ts

@@ -0,0 +1,60 @@
+import { createOrOpenIndex, closeIndex } from './cg-instance.js';
+import { formatSummary, formatOutput } from './formatter.js';
+
+export interface InitOptions {
+  index?: boolean;
+  json?: boolean;
+}
+
+export async function handleInit(projectRoot: string, options: InitOptions = {}): Promise<number> {
+  const progressEvents: Array<{ phase: string; current: number; total: number }> = [];
+  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: [string, string | number][] = [
+      ['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/lib/cmd-list-apis.test.ts

@@ -0,0 +1,80 @@
+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: string) => nodes,
+      getCallers: (_id: string) => [],
+      close: () => {},
+    }));
+
+    const { handleListApis } = await import('./cmd-list-apis.js');
+
+    // Test 1: --all produces directory-grouped output
+    {
+      const chunks: string[] = [];
+      ctx.mock.method(process.stdout, 'write', (chunk: string | Uint8Array) => {
+        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: string[] = [];
+      ctx.mock.method(process.stdout, 'write', (chunk: string | Uint8Array) => {
+        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/lib/cmd-list-apis.ts

@@ -0,0 +1,90 @@
+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 interface ListApisOptions {
+  json?: boolean;
+  all?: boolean;
+}
+
+export async function handleListApis(
+  projectRoot: string,
+  feature?: string,
+  options: ListApisOptions = {},
+): Promise<number> {
+  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: any) => n.filePath.startsWith(featurePath));
+  }
+
+  // Only exported functions unless --all is specified
+  if (!options.all) {
+    nodes = nodes.filter((n: any) => n.isExported);
+  }
+
+  type ApiEntry = {
+    name: string;
+    kind: string;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    qualifiedName: string;
+    signature?: string;
+    isExported: boolean;
+    callerCount: number;
+    callers: Array<{ name: string; filePath: string; startLine: number }>;
+  };
+
+  const apis: ApiEntry[] = [];
+  for (const node of nodes) {
+    const callers = cg.getCallers(node.id).map((c: any) => ({
+      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: Record<string, ApiEntry[]> = {};
+      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/lib/cmd-search.test.ts

@@ -0,0 +1,37 @@
+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') as { CodeGraph: { isInitialized: Function; open: Function } };
+    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: string[] = [];
+    const originalStderrWrite = process.stderr.write.bind(process.stderr);
+    process.stderr.write = (chunk: unknown) => {
+      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/lib/cmd-search.ts

@@ -0,0 +1,32 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+import { closeIndex } from './cg-instance.js';
+import { formatSearchResults, formatOutput } from './formatter.js';
+
+export interface SearchOptions {
+  limit?: number;
+  json?: boolean;
+}
+
+export async function handleSearch(
+  projectRoot: string,
+  query: string,
+  options: SearchOptions = {},
+): Promise<number> {
+  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/lib/cmd-status.test.ts

@@ -0,0 +1,86 @@
+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') as { CodeGraph: { open: Function; isInitialized: Function } };
+    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: string[] = [];
+    const originalWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (chunk: unknown) => {
+      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') as { CodeGraph: { isInitialized: Function; open: Function } };
+    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: string[] = [];
+    const originalStderrWrite = process.stderr.write.bind(process.stderr);
+    process.stderr.write = (chunk: unknown) => {
+      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();
+    }
+  });
+});