@laitszkin/apollo-toolkit 4.0.11 → 4.1.0

package/packages/tools/codegraph/index.ts

@@ -0,0 +1,173 @@
+import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
+import { findProjectRoot } from './lib/cg-instance.js';
+import { handleInit } from './lib/cmd-init.js';
+import { handleSync } from './lib/cmd-sync.js';
+import { handleStatus } from './lib/cmd-status.js';
+import { handleSearch } from './lib/cmd-search.js';
+import { handleExplore } from './lib/cmd-explore.js';
+import { handleSurvey } from './lib/cmd-survey.js';
+import { handleListApis } from './lib/cmd-list-apis.js';
+import { handleVerify } from './lib/cmd-verify.js';
+
+export async function codegraphHandler(args: string[], context: ToolContext): Promise<number> {
+  const stdout = context.stdout || process.stdout;
+  const stderr = context.stderr || process.stderr;
+  const projectRoot = findProjectRoot(context.cwd || process.cwd());
+
+  // Parse --json flag early (can appear anywhere)
+  const jsonIndex = args.indexOf('--json');
+  const isJson = jsonIndex >= 0;
+  if (jsonIndex >= 0) args.splice(jsonIndex, 1);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    printHelp(stdout);
+    return 0;
+  }
+
+  const subcommand = args[0];
+  const rest = args.slice(1);
+
+  // Parse --spec <dir> for verify
+  const specIndex = rest.indexOf('--spec');
+  let specDir: string | undefined;
+  if (specIndex >= 0 && specIndex + 1 < rest.length) {
+    specDir = rest[specIndex + 1];
+    rest.splice(specIndex, 2);
+  }
+
+  // Parse --all flag for list-apis
+  const allIndex = rest.indexOf('--all');
+  const isAll = allIndex >= 0;
+  if (allIndex >= 0) rest.splice(allIndex, 1);
+
+  // Parse --index flag for init
+  const shouldIndex = rest.includes('--index');
+  const indexIdx = rest.indexOf('--index');
+  if (indexIdx >= 0) rest.splice(indexIdx, 1);
+
+  // Parse --feature <name> for survey
+  const featureIndex = rest.indexOf('--feature');
+  let featureName: string | undefined;
+  if (featureIndex >= 0 && featureIndex + 1 < rest.length) {
+    featureName = rest[featureIndex + 1];
+    rest.splice(featureIndex, 2);
+  }
+
+  // Parse limit for search
+  const limitIndex = rest.indexOf('--limit');
+  let limit: number | undefined;
+  if (limitIndex >= 0 && limitIndex + 1 < rest.length) {
+    limit = parseInt(rest[limitIndex + 1], 10);
+    rest.splice(limitIndex, 2);
+  }
+
+  try {
+    switch (subcommand) {
+      case 'init':
+        return await handleInit(projectRoot, { index: shouldIndex, json: isJson });
+
+      case 'sync':
+        return await handleSync(projectRoot, { json: isJson });
+
+      case 'status':
+        return await handleStatus(projectRoot, { json: isJson });
+
+      case 'search': {
+        const query = rest.join(' ');
+        if (!query) {
+          stderr.write('Usage: apltk codegraph search <query> [--limit N] [--json]\n');
+          return 1;
+        }
+        return await handleSearch(projectRoot, query, { limit, json: isJson });
+      }
+
+      case 'explore': {
+        const query = rest.join(' ');
+        if (!query) {
+          stderr.write('Usage: apltk codegraph explore <query> [--json]\n');
+          return 1;
+        }
+        return await handleExplore(projectRoot, query, { json: isJson, feature: featureName });
+      }
+
+      case 'survey': {
+        const dirPath = rest[0] || '.';
+        return await handleSurvey(projectRoot, dirPath, { feature: featureName, json: isJson });
+      }
+
+      case 'list-apis': {
+        const pathArg = rest[0];
+        const combinedPath = featureName
+          ? (pathArg ? `${featureName}/${pathArg.replace(/^\//, '')}` : featureName)
+          : pathArg;
+        return await handleListApis(projectRoot, combinedPath, { all: isAll, json: isJson });
+      }
+
+      case 'verify': {
+        if (!specDir) {
+          stderr.write('Usage: apltk codegraph verify --spec <spec-dir> [--json]\n');
+          return 1;
+        }
+        return await handleVerify(projectRoot, specDir, { json: isJson });
+      }
+
+      default:
+        stderr.write(`Unknown subcommand: ${subcommand}\n\n`);
+        printHelp(stderr);
+        return 1;
+    }
+  } catch (error: any) {
+    if (error.code === 'MODULE_NOT_FOUND' || (error.message && error.message.includes('Cannot find module'))) {
+      stderr.write('`@colbymchenry/codegraph` is not installed. Run `npm install @colbymchenry/codegraph` in your project directory.\n');
+    } else {
+      stderr.write(`Error running codegraph ${subcommand}: ${error.message}\n`);
+    }
+    return 1;
+  }
+}
+
+function printHelp(stream: NodeJS.WriteStream): void {
+  stream.write(`Usage: apltk codegraph <subcommand> [options]
+
+Subcommands:
+
+  lifecycle:
+    init               Initialize CodeGraph for the project
+                       --index    Run initial indexing after init
+
+    sync               Sync the index with current file state
+
+    status             Show index statistics (files, nodes, edges)
+
+  discovery:
+    search <query>     Search the code graph for symbols
+                       --limit N  Max results (default: 20)
+
+    explore <query>    Deep-dive on a symbol (callers, callees, source)
+                       --json     JSON output
+
+    survey [dir]       Scan a directory and suggest submodule groupings
+                       --feature <name>  Feature context
+                       --json            JSON output
+
+    list-apis [path]   List public APIs in the project or a sub-path
+                       --all      Include non-exported symbols
+                       --json     JSON output
+
+  validation:
+    verify             Verify a spec overlay against the actual code
+                       --spec <dir>  Spec directory (required)
+                       --json        JSON output
+
+Global options:
+    --json             Output as JSON instead of human-readable format
+    --help             Show this help message
+`);
+}
+
+export const tool: ToolDefinition = {
+  name: 'codegraph',
+  category: 'Code analysis',
+  description: 'CodeGraph code intelligence — init, sync, status, search, explore, survey, list-apis, verify',
+  handler: codegraphHandler,
+};

package/packages/tools/codegraph/lib/cg-instance.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+import { createOrOpenIndex } from './cg-instance.js';
+
+describe('createOrOpenIndex', () => {
+  let tmpDir: string;
+
+  before(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-test-'));
+  });
+
+  after(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('should throw when project is already initialized', async () => {
+    // Arrange: create .codegraph/ and codegraph.db to simulate an initialized project
+    const codegraphDir = path.join(tmpDir, '.codegraph');
+    fs.mkdirSync(codegraphDir, { recursive: true });
+    fs.writeFileSync(path.join(codegraphDir, 'codegraph.db'), '');
+
+    // Act & Assert
+    await assert.rejects(
+      () => createOrOpenIndex(tmpDir),
+      (err: unknown) => {
+        assert.ok(err instanceof Error);
+        assert.match(err.message, /sync/);
+        return true;
+      },
+    );
+  });
+});

package/packages/tools/codegraph/lib/cg-instance.ts

@@ -0,0 +1,66 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+
+let _codeGraphModule: any = null;
+export function getCodeGraphModule(): { CodeGraph: any; findNearestCodeGraphRoot: any } {
+  if (!_codeGraphModule) {
+    _codeGraphModule = require('@colbymchenry/codegraph');
+  }
+  return _codeGraphModule;
+}
+
+/**
+ * Locate the project root by walking up from the given directory.
+ * Returns the nearest parent containing `.codegraph/`, or falls back
+ * to the nearest parent containing `package.json`.
+ */
+export function findProjectRoot(startPath?: string): string {
+  const cwd = startPath || process.cwd();
+  const codegraphRoot = getCodeGraphModule().findNearestCodeGraphRoot(cwd);
+  if (codegraphRoot) return codegraphRoot;
+
+  // Fallback: walk up looking for package.json
+  let dir = path.resolve(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return cwd; // hit filesystem root
+    dir = parent;
+  }
+}
+
+/**
+ * Initialize a CodeGraph index for the given project root.
+ *
+ * If the project is already initialized, throws an error suggesting
+ * `apltk codegraph sync` instead. Otherwise, initializes a new CodeGraph
+ * project. When `options.index` is true, runs initial indexing after init.
+ *
+ * Note: `CodeGraph.init()` supports an `{ index: true }` shorthand that
+ * runs initial indexing inline -- this deviates from a two-step init-then-index
+ * pattern but is the supported API through the npm package.
+ */
+export async function createOrOpenIndex(
+  projectRoot: string,
+  options?: { index?: boolean; onProgress?: (progress: any) => void },
+): Promise<any> {
+  const isInit = getCodeGraphModule().CodeGraph.isInitialized(projectRoot);
+  if (isInit) {
+    throw new Error(
+      `Project is already initialized at ${projectRoot}. Use \`apltk codegraph sync\` to update the index.`,
+    );
+  }
+  return getCodeGraphModule().CodeGraph.init(projectRoot, {
+    index: options?.index ?? false,
+    onProgress: options?.onProgress,
+  });
+}
+
+/**
+ * Close a CodeGraph instance and release resources.
+ */
+export function closeIndex(cg: any): void {
+  cg.close();
+}

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

@@ -0,0 +1,195 @@
+import { describe, it, mock, before } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+// ---------------------------------------------------------------------------
+// Shared mutable mock state — each test sets its own data before calling the
+// handler.  The mock instance's searchNodes captures this array by reference,
+// so mutations are reflected in every invocation.
+// ---------------------------------------------------------------------------
+interface MockSymbolNode {
+  id: string;
+  name: string;
+  kind: string;
+  filePath: string;
+  startLine: number;
+  endLine: number;
+  qualifiedName: string;
+  signature?: string;
+}
+
+interface MockSearchResult {
+  node: MockSymbolNode;
+  score: number;
+}
+
+const mockSearchResults: MockSearchResult[] = [];
+
+// ---------------------------------------------------------------------------
+// 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: {
+  searchNodes: () => { node: MockSymbolNode; score: number }[];
+  getCallers: () => never[];
+  getCallees: () => never[];
+  getCode: () => Promise<null>;
+  close: () => void;
+} | undefined;
+
+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: (
+  projectRoot: string,
+  query: string,
+  options?: Record<string, unknown>,
+) => Promise<number>;
+
+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: string[] = [];
+    const origWrite = process.stdout.write;
+    process.stdout.write = ((chunk: unknown) => {
+      stdoutChunks.push(String(chunk));
+      return true;
+    }) as typeof process.stdout.write;
+
+    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: string[] = [];
+    const origWrite = process.stdout.write;
+    process.stdout.write = ((chunk: unknown) => {
+      stdoutChunks.push(String(chunk));
+      return true;
+    }) as typeof process.stdout.write;
+
+    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/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();
+  });
+});