@laitszkin/apollo-toolkit 4.0.11 → 4.1.1

package/packages/tools/codegraph/index.ts

@@ -0,0 +1,362 @@
+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);
+
+  // Main help: no args, --help, -h, or "help" subcommand
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+    printHelp(stdout);
+    return 0;
+  }
+
+  const subcommand = args[0];
+
+  // Per-subcommand help: e.g., "apltk codegraph search --help"
+  // Check for --help/-h at position 1 (after the subcommand name)
+  const rest = args.slice(1);
+  if (rest.includes('--help') || rest.includes('-h')) {
+    printSubcommandHelp(subcommand, stdout, stderr);
+    return 0;
+  }
+
+  // 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]
+
+CodeGraph code intelligence — parse source code into a knowledge graph
+of symbols (functions, classes) and relationships (call edges), backed by
+a local SQLite database with FTS5 full-text search.
+
+Powered by @colbymchenry/codegraph (tree-sitter-backed code knowledge graph).
+
+Subcommands:
+
+  lifecycle:
+    init               Initialize CodeGraph for the project
+                       --index    Run initial indexing immediately after init
+                       --json     JSON output
+
+    sync               Sync the index with current file state
+                       --json     JSON output
+
+    status             Show index statistics (files, nodes, edges, languages)
+                       --json     JSON output
+
+  discovery:
+    search <query>     Search the code graph for symbols via FTS5
+                       --limit N  Max results (default: 20, max: 100)
+                       --json     JSON output
+
+    explore <query>    Deep-dive on a symbol — show callers, callees, and source
+                       --feature <name>  Only show results within this feature
+                       --json            JSON output
+
+    survey [dir]       Scan a directory, suggest submodule groupings and
+                       cross-boundary edges for atlas modelling
+                       --feature <name>  Feature context for grouping
+                       --json            JSON output
+
+    list-apis [path]   List public APIs in the project or within a sub-path
+                       --all      Include non-exported (internal) symbols
+                       --json     JSON output
+
+  validation:
+    verify --spec <dir>
+                       Verify a spec overlay against actual code —
+                       checks that every declared feature, submodule,
+                       function, and edge exists in the code graph
+                       --json     JSON output
+
+Global options:
+    --json             Output as JSON instead of human-readable format
+    --help, -h         Show this help message
+
+Use "apltk codegraph <subcommand> --help" for per-subcommand details.
+
+Examples:
+  apltk codegraph init
+  apltk codegraph init --index
+  apltk codegraph status --json
+  apltk codegraph search getUser
+  apltk codegraph search getUser --limit 5 --json
+  apltk codegraph explore handleLogin
+  apltk codegraph survey src/
+  apltk codegraph survey src/ --feature auth --json
+  apltk codegraph list-apis --all
+  apltk codegraph verify --spec docs/plans/2026-05-11/add-2fa
+`);
+}
+
+function printSubcommandHelp(subcommand: string, stream: NodeJS.WriteStream, errStream: NodeJS.WriteStream): void {
+  const PAD = '  ';
+
+  const helps: Record<string, string> = {
+    init: `Usage: apltk codegraph init [--index] [--json]
+
+Initialize the CodeGraph knowledge graph for the project.
+Creates the .codegraph/ directory and SQLite database.
+
+Flags:
+  --index    Run initial indexing immediately after init, so the
+             knowledge graph is ready for queries right away.
+             Without this flag, you need to run "apltk codegraph sync"
+             separately before searching or exploring.
+  --json     Output confirmation as JSON.
+
+Examples:
+  apltk codegraph init
+  apltk codegraph init --index
+`,
+    sync: `Usage: apltk codegraph sync [--json]
+
+Sync the code graph index with the current state of files on disk.
+Parses changed files and updates the SQLite database.
+
+This is needed after you modify source files if you want queries
+to reflect the latest code. Runs incrementally — only reprocesses
+files whose mtime has changed.
+
+Flags:
+  --json     Output sync results (files added/removed/updated) as JSON.
+
+Examples:
+  apltk codegraph sync
+  apltk codegraph sync --json
+`,
+    status: `Usage: apltk codegraph status [--json]
+
+Show index statistics: file count, symbol (node) count, edge count,
+languages detected, and last-sync timestamp.
+
+Flags:
+  --json     Output full statistics as a JSON object.
+
+Examples:
+  apltk codegraph status
+  apltk codegraph status --json
+`,
+    search: `Usage: apltk codegraph search <query> [--limit N] [--json]
+
+Full-text search the code graph for symbols (functions, classes, variables).
+Uses FTS5 (SQLite full-text search) under the hood.
+
+Arguments:
+  query      Search term (required). Matches against symbol names and
+             source code content.
+
+Flags:
+  --limit N  Max results to return (default: 20, max: 100).
+  --json     Output results as a JSON array.
+
+Examples:
+  apltk codegraph search getUser
+  apltk codegraph search handleLogin --limit 5
+  apltk codegraph search "class.*Handler" --limit 10 --json
+`,
+    explore: `Usage: apltk codegraph explore <query> [--feature <name>] [--json]
+
+Deep-dive on a symbol — shows who calls it, what it calls, and its
+full source code. Useful for understanding how a function or class
+fits into the broader codebase.
+
+Arguments:
+  query      Symbol name to explore (required).
+
+Flags:
+  --feature <name>
+             Scope results to only show callers/callees within a
+             specific feature directory (e.g. "auth", "billing").
+  --json     Output full exploration data as JSON (callers, callees,
+             source code, file path, line numbers).
+
+Examples:
+  apltk codegraph explore handleLogin
+  apltk codegraph explore authenticate --feature auth
+  apltk codegraph explore sendEmail --json
+`,
+    survey: `Usage: apltk codegraph survey [dir] [--feature <name>] [--json]
+
+Scan a directory and produce a structured survey report with suggested
+submodule groupings, cross-boundary edges, and entry points.
+
+This is the primary input for the "init-project-html" skill's Step 1 —
+it tells the LLM how to model features and submodules for the atlas.
+
+Arguments:
+  dir        Directory to scan (default: current directory ".").
+
+Flags:
+  --feature <name>
+             Feature context: scope the survey to only one feature's
+             boundary. Helps the grouper cluster symbols more accurately.
+  --json     Output survey results as JSON — best for LLM consumption.
+
+Examples:
+  apltk codegraph survey
+  apltk codegraph survey src/
+  apltk codegraph survey src/auth --feature auth --json
+`,
+    'list-apis': `Usage: apltk codegraph list-apis [path] [--all] [--json]
+
+List public (exported) symbols in the project or a specific sub-path.
+Useful for understanding the public surface area of a module.
+
+Arguments:
+  path       Sub-path to scan (e.g. "src/auth"). When omitted, scans
+             the entire project.
+
+Flags:
+  --all      Include non-exported (internal) symbols in the listing.
+  --json     Output API list as JSON.
+
+Examples:
+  apltk codegraph list-apis
+  apltk codegraph list-apis src/auth
+  apltk codegraph list-apis --all --json
+`,
+    verify: `Usage: apltk codegraph verify --spec <spec-dir> [--json]
+
+Verify a spec overlay's architecture proposals against actual code.
+Checks that every feature, submodule, function, and edge referenced
+in the overlay's atlas state actually exists in the code graph.
+
+Flags:
+  --spec <spec-dir>
+             Path to the spec directory containing an architecture_diff/
+             overlay (required). For example, "docs/plans/2026-05-11/add-2fa".
+  --json     Output verification results as JSON (passed/failed checks).
+
+Examples:
+  apltk codegraph verify --spec docs/plans/2026-05-11/add-2fa
+  apltk codegraph verify --spec docs/plans/2026-05-11/add-2fa --json
+`,
+  };
+
+  const text = helps[subcommand];
+  if (text) {
+    stream.write(text);
+  } else {
+    errStream.write(`Unknown subcommand: "${subcommand}". Use "apltk codegraph --help" for the list of available subcommands.\n`);
+  }
+}
+
+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;
+    }
+  });
+});