@laitszkin/apollo-toolkit 4.0.11 → 4.1.0

package/packages/tools/codegraph/lib/formatter.ts

@@ -0,0 +1,130 @@
+/**
+ * Format structured data for CLI output.
+ *
+ * - TTY mode produces human-readable tables and headings.
+ * - Non-TTY or `--json` produces JSON.stringify with 2-space indent.
+ * - Auto-detects TTY via `process.stdout.isTTY`.
+ */
+
+export interface FormatOptions {
+  json?: boolean;
+  tty?: boolean;
+}
+
+function isTTY(options: FormatOptions): boolean {
+  if (options.json) return false;
+  if (options.tty !== undefined) return options.tty;
+  return !!process.stdout.isTTY;
+}
+
+/**
+ * Format generic data for output.
+ */
+export function formatOutput(data: unknown, options: FormatOptions = {}): string {
+  if (!isTTY(options)) {
+    return JSON.stringify(data, null, 2);
+  }
+  // Fallback: JSON for complex objects in TTY too
+  if (typeof data === 'string') return data;
+  if (data === null || data === undefined) return '';
+  return JSON.stringify(data, null, 2);
+}
+
+/**
+ * Format a key-value summary block for human-readable output.
+ * Example:
+ *   Files:       42
+ *   Nodes:     1280
+ *   Edges:     5600
+ */
+export function formatSummary(rows: [string, string | number][]): string {
+  const width = rows.reduce((max, [key]) => Math.max(max, key.length + 1), 0);
+  return rows
+    .map(([key, val]) => `${key.padEnd(width, ' ')} ${val}`)
+    .join('\n');
+}
+
+/**
+ * Format a list of search results as a human-readable table.
+ */
+export function formatSearchResults(
+  results: Array<{ node: { name: string; kind: string; filePath: string; startLine: number }; score: number }>,
+): string {
+  if (results.length === 0) return 'No results found.';
+  const lines = results.map((r, i) => {
+    const score = (r.score * 100).toFixed(0);
+    return `  ${i + 1}. ${r.node.name}  [${r.node.kind}]  ${r.node.filePath}:${r.node.startLine}  (${score}%)`;
+  });
+  return `Results (${results.length}):\n${lines.join('\n')}`;
+}
+
+/**
+ * Format an API directory listing for human-readable output.
+ */
+export function formatApiList(
+  apis: Array<{
+    name: string;
+    kind: string;
+    filePath: string;
+    startLine: number;
+    signature?: string;
+    callerCount: number;
+    callers?: Array<{ name: string; filePath: string; startLine: number }>;
+  }>,
+): string {
+  if (apis.length === 0) return 'No public APIs found.';
+  const lines: string[] = [];
+  for (const a of apis) {
+    const sig = a.signature ? `  ${a.signature}` : '';
+    lines.push(`  ${a.name}  [${a.kind}]  ${a.filePath}:${a.startLine}  (${a.callerCount} callers)${sig}`);
+    if (a.callerCount > 0 && a.callers) {
+      const callerLines = a.callers.slice(0, 5).map(c => `      Called by: ${c.name}  ${c.filePath}:${c.startLine}`);
+      lines.push(...callerLines);
+      if (a.callerCount > 5) lines.push(`      ... and ${a.callerCount - 5} more`);
+    }
+  }
+  return `APIs (${apis.length}):\n${lines.join('\n')}`;
+}
+
+/**
+ * Format an API listing grouped by directory.
+ */
+export function formatApiListGrouped(
+  apis: Array<{
+    name: string;
+    kind: string;
+    filePath: string;
+    startLine: number;
+    signature?: string;
+    callerCount: number;
+    callers?: Array<{ name: string; filePath: string; startLine: number }>;
+  }>,
+): string {
+  if (apis.length === 0) return 'No public APIs found.';
+  // Group by directory
+  const groups = new Map<string, typeof apis>();
+  for (const a of apis) {
+    const dir = a.filePath.substring(0, a.filePath.lastIndexOf('/'));
+    if (!groups.has(dir)) groups.set(dir, []);
+    groups.get(dir)!.push(a);
+  }
+  // Render with directory headers
+  const lines: string[] = [];
+  const sortedDirs = [...groups.keys()].sort();
+  for (const dir of sortedDirs) {
+    const entries = groups.get(dir)!;
+    lines.push('');
+    lines.push(`=== ${dir}/ ===`);
+    for (const a of entries) {
+      const sig = a.signature ? `  ${a.signature}` : '';
+      lines.push(`  ${a.name}  [${a.kind}]  ${a.filePath}:${a.startLine}  (${a.callerCount} callers)${sig}`);
+      if (a.callerCount > 0 && a.callers) {
+        const callerLines = a.callers.slice(0, 5).map(c => `      Called by: ${c.name}  ${c.filePath}:${c.startLine}`);
+        lines.push(...callerLines);
+        if (a.callerCount > 5) lines.push(`      ... and ${a.callerCount - 5} more`);
+      }
+    }
+  }
+  lines.push('');
+  return lines.join('\n').trimStart();
+}

package/packages/tools/codegraph/lib/survey/grouper.test.ts

@@ -0,0 +1,72 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { groupIntoSubmodules } from './grouper.js';
+
+describe('groupIntoSubmodules', () => {
+  it('groups connected call graph symbols into one submodule (hybrid connectivity grouping)', () => {
+    // -----------------------------------------------------------------------
+    // GIVEN a scan result with functions A, B, C where A calls B and B calls C
+    // (all in the same file, forming a connected chain)
+    // -----------------------------------------------------------------------
+    const filePath = 'src/module.ts';
+
+    const scan = {
+      directory: 'src',
+      files: [
+        {
+          filePath,
+          language: 'typescript',
+          symbols: [
+            { name: 'A', kind: 'function', qualifiedName: 'A', startLine: 1, endLine: 5, isExported: true },
+            { name: 'B', kind: 'function', qualifiedName: 'B', startLine: 6, endLine: 10, isExported: true },
+            { name: 'C', kind: 'function', qualifiedName: 'C', startLine: 11, endLine: 15, isExported: false },
+          ],
+        },
+      ],
+      allSymbols: [
+        { name: 'A', kind: 'function', filePath, qualifiedName: 'A', startLine: 1, isExported: true },
+        { name: 'B', kind: 'function', filePath, qualifiedName: 'B', startLine: 6, isExported: true },
+        { name: 'C', kind: 'function', filePath, qualifiedName: 'C', startLine: 11, isExported: false },
+      ],
+      totalFiles: 1,
+      totalSymbols: 3,
+    };
+
+    // Mock call graph: A -> B -> C
+    const mockCg = {
+      getNodesByName(name: string) {
+        const nodeId = `node-${name}`;
+        return [{ id: nodeId, filePath }];
+      },
+      getCallees(nodeId: string) {
+        const calleeMap: Record<string, string[]> = {
+          'node-A': ['B'],
+          'node-B': ['C'],
+          'node-C': [],
+        };
+        return (calleeMap[nodeId] || []).map((calleeName: string) => ({
+          node: { name: calleeName },
+        }));
+      },
+    };
+
+    // -----------------------------------------------------------------------
+    // WHEN groupIntoSubmodules(scan, mockCg) runs
+    // -----------------------------------------------------------------------
+    const result = groupIntoSubmodules(scan as any, mockCg);
+
+    // -----------------------------------------------------------------------
+    // THEN A, B, C are grouped into one submodule
+    //   (connectivity-based grouping takes priority over per-file isolation)
+    // -----------------------------------------------------------------------
+    assert.equal(result.length, 1, 'should produce exactly one submodule');
+
+    const sortedMembers = [...result[0].memberFunctions].sort();
+    assert.deepEqual(sortedMembers, ['A', 'B', 'C'], 'should contain A, B, C');
+
+    assert.ok(
+      result[0].memberFiles.includes(filePath),
+      'should include the source file in memberFiles',
+    );
+  });
+});

package/packages/tools/codegraph/lib/survey/grouper.ts

@@ -0,0 +1,226 @@
+import type { ScanResult } from './scanner.js';
+
+export interface SubmoduleSuggestion {
+  slug: string;
+  kind: 'api' | 'service' | 'db' | 'ui' | 'pure-fn' | 'queue';
+  role: string;
+  memberFunctions: string[];
+  memberFiles: string[];
+}
+
+/**
+ * Group scanned symbols into suggested submodule groupings.
+ *
+ * Algorithm (hybrid):
+ * 1. Build adjacency map from call graph: for each symbol, find callees within the scan
+ * 2. BFS on undirected graph to find connected components
+ * 3. Components with >=2 symbols create connectivity-based submodule suggestions
+ * 4. Remaining (isolated) symbols fall back to per-file grouping
+ * 5. Apply mergeByDirectoryPrefix as final step
+ */
+export function groupIntoSubmodules(scan: ScanResult, cg: any): SubmoduleSuggestion[] {
+  if (scan.allSymbols.length === 0) return [];
+
+  // --- Phase 1: Build adjacency map from call graph connectivity ---
+  const allNameSet = new Set(scan.allSymbols.map(s => s.name));
+  const adj = new Map<string, Set<string>>();
+  const nodeKeyMap = new Map<string, { name: string; filePath: string; kind: string; isExported: boolean }>();
+
+  for (const sym of scan.allSymbols) {
+    const key = `${sym.filePath}::${sym.name}`;
+    const calleeSet = new Set<string>();
+    adj.set(key, calleeSet);
+    nodeKeyMap.set(key, sym);
+
+    const nodes = cg.getNodesByName(sym.name);
+    for (const node of nodes) {
+      if (node.filePath !== sym.filePath) continue;
+      const callees = cg.getCallees(node.id);
+      for (const callee of callees) {
+        if (allNameSet.has(callee.node.name)) {
+          calleeSet.add(callee.node.name);
+        }
+      }
+    }
+  }
+
+  // Build reverse index: name -> list of symbol keys (for efficient BFS lookup)
+  const nameToKeys = new Map<string, string[]>();
+  for (const [key, sym] of nodeKeyMap.entries()) {
+    const arr = nameToKeys.get(sym.name) || [];
+    arr.push(key);
+    nameToKeys.set(sym.name, arr);
+  }
+
+  // --- Phase 2: BFS to find connected components (undirected graph) ---
+  const visited = new Set<string>();
+  const components: Array<Array<{ name: string; filePath: string; kind: string; isExported: boolean }>> = [];
+
+  for (const key of adj.keys()) {
+    if (visited.has(key)) continue;
+
+    const component: Array<{ name: string; filePath: string; kind: string; isExported: boolean }> = [];
+    const queue = [key];
+    visited.add(key);
+
+    while (queue.length > 0) {
+      const currentKey = queue.shift()!;
+      const sym = nodeKeyMap.get(currentKey)!;
+      component.push(sym);
+
+      const calleeNames = adj.get(currentKey) || new Set();
+      for (const calleeName of calleeNames) {
+        const targetKeys = nameToKeys.get(calleeName) || [];
+        for (const tk of targetKeys) {
+          if (!visited.has(tk)) {
+            visited.add(tk);
+            queue.push(tk);
+          }
+        }
+      }
+    }
+
+    if (component.length > 0) {
+      components.push(component);
+    }
+  }
+
+  // --- Phase 3: Build suggestions from connected components ---
+  const suggestions: SubmoduleSuggestion[] = [];
+  const processed = new Set<string>();
+
+  // Components with >=2 symbols become connectivity-based submodules
+  for (const component of components) {
+    if (component.length < 2) continue;
+
+    const files = [...new Set(component.map(s => s.filePath))];
+    const representativePath = files[0];
+    const fileName = representativePath.split('/').pop() || '';
+    const slug = fileName.replace(/\.\w+$/, '').replace(/[_ ]/g, '-').toLowerCase();
+    const kind = inferKind(representativePath, component);
+    const role = inferRole(kind, slug, component.filter(s => s.isExported));
+
+    for (const s of component) {
+      processed.add(`${s.filePath}::${s.name}`);
+    }
+
+    suggestions.push({
+      slug,
+      kind,
+      role,
+      memberFunctions: [...new Set(component.map(s => s.name))],
+      memberFiles: files,
+    });
+  }
+
+  // --- Phase 4: Remaining (isolated) symbols fall back to per-file grouping ---
+  for (const file of scan.files) {
+    const unprocessedSymbols = file.symbols.filter(
+      s => !processed.has(`${file.filePath}::${s.name}`)
+    );
+    if (unprocessedSymbols.length === 0 && file.symbols.length === 0) continue;
+
+    const fileName = file.filePath.split('/').pop() || '';
+    const slug = fileName.replace(/\.\w+$/, '').replace(/[_ ]/g, '-').toLowerCase();
+    const kind = inferKind(file.filePath, file.symbols);
+    const symbols = unprocessedSymbols.map(s => s.name);
+    if (symbols.length === 0) continue;
+
+    for (const s of unprocessedSymbols) processed.add(`${file.filePath}::${s.name}`);
+
+    const role = inferRole(kind, slug, file.symbols.filter(s => s.isExported));
+    suggestions.push({
+      slug,
+      kind,
+      role,
+      memberFunctions: symbols,
+      memberFiles: [file.filePath],
+    });
+  }
+
+  // --- Phase 5: Merge small files sharing a directory prefix ---
+  const merged = mergeByDirectoryPrefix(suggestions, scan.directory);
+  return merged;
+}
+
+function inferKind(filePath: string, symbols: Array<{ name: string; kind: string }>): SubmoduleSuggestion['kind'] {
+  const lower = filePath.toLowerCase();
+
+  // Detect by path patterns
+  if (lower.includes('/api/') || lower.includes('/routes/') || lower.includes('/controller')) return 'api';
+  if (lower.includes('/db/') || lower.includes('/model/') || lower.includes('/repository') || lower.includes('/schema')) return 'db';
+  if (lower.includes('/ui/') || lower.includes('/component/') || lower.includes('/page/') || lower.includes('/view')) return 'ui';
+  if (lower.includes('/queue/') || lower.includes('/job/') || lower.includes('/worker')) return 'queue';
+
+  // Detect by symbol kinds
+  const hasHandler = symbols.some((s) => s.kind === 'route' || s.kind === 'component');
+  if (hasHandler) return 'api';
+
+  const hasModel = symbols.some((s) => s.kind === 'interface' || s.kind === 'struct');
+  if (hasModel) return 'db';
+
+  return 'service';
+}
+
+function inferRole(kind: SubmoduleSuggestion['kind'], slug: string, exportedSymbols: Array<{ name: string; kind: string }>): string {
+  const name = slug.replace(/-/g, ' ');
+  switch (kind) {
+    case 'api':
+      return `Handles API requests for ${name}`;
+    case 'db':
+      return `Manages data access and persistence for ${name}`;
+    case 'service':
+      return `Contains business logic for ${name}`;
+    case 'ui':
+      return `Renders UI components for ${name}`;
+    case 'queue':
+      return `Processes background jobs for ${name}`;
+    case 'pure-fn':
+      return `Provides pure utility functions for ${name}`;
+    default:
+      return `Supports ${name} functionality`;
+  }
+}
+
+function mergeByDirectoryPrefix(
+  suggestions: SubmoduleSuggestion[],
+  _directory: string,
+): SubmoduleSuggestion[] {
+  // When there are many single-file suggestions, merge those
+  // that share a common 2-segment directory prefix
+  const prefixMap = new Map<string, SubmoduleSuggestion>();
+
+  for (const s of suggestions) {
+    if (s.memberFiles.length !== 1) {
+      // Already contains multiple files, keep as-is
+      const key = s.slug;
+      prefixMap.set(key, s);
+      continue;
+    }
+
+    const filePath = s.memberFiles[0];
+    const parts = filePath.split('/');
+    // Use the parent directory as merge key for files in subdirs
+    const mergeKey = parts.length >= 3 ? parts.slice(0, -1).join('/') : s.slug;
+
+    if (prefixMap.has(mergeKey)) {
+      const existing = prefixMap.get(mergeKey)!;
+      existing.memberFunctions.push(...s.memberFunctions);
+      existing.memberFiles.push(...s.memberFiles);
+      // Keep more specific kind
+      if (existing.kind === 'service' && s.kind !== 'service') {
+        existing.kind = s.kind;
+      }
+    } else {
+      prefixMap.set(mergeKey, {
+        slug: mergeKey.replace(/\//g, '-'),
+        kind: s.kind,
+        role: s.role,
+        memberFunctions: [...s.memberFunctions],
+        memberFiles: [...s.memberFiles],
+      });
+    }
+  }
+
+  return Array.from(prefixMap.values());
+}

package/packages/tools/codegraph/lib/survey/scanner.ts

@@ -0,0 +1,89 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+
+export interface FileScan {
+  filePath: string;
+  language: string;
+  symbols: Array<{
+    name: string;
+    kind: string;
+    qualifiedName: string;
+    startLine: number;
+    endLine: number;
+    isExported: boolean;
+    signature?: string;
+  }>;
+}
+
+export interface ScanResult {
+  directory: string;
+  files: FileScan[];
+  allSymbols: Array<{
+    name: string;
+    kind: string;
+    filePath: string;
+    qualifiedName: string;
+    startLine: number;
+    isExported: boolean;
+  }>;
+  totalFiles: number;
+  totalSymbols: number;
+}
+
+/**
+ * Scan a directory for all files and symbols tracked by CodeGraph.
+ */
+export async function scanDirectory(
+  cg: any,
+  dirPath: string,
+): Promise<ScanResult> {
+  const { CodeGraph } = require('@colbymchenry/codegraph');
+  const files = cg.getFiles();
+  const dirPrefix = dirPath.replace(/^\/?/, '').replace(/\/?$/, '') + '/';
+
+  // Filter files within the directory
+  const dirFiles = files.filter((f: { path: string }) => f.path.startsWith(dirPrefix));
+
+  const fileScans: FileScan[] = [];
+  const allSymbols: ScanResult['allSymbols'] = [];
+
+  for (const file of dirFiles) {
+    const nodes = cg.getNodesInFile(file.path);
+    const symbols = nodes
+      .filter((n: any) => !['file', 'import', 'parameter'].includes(n.kind))
+      .map((n: any) => ({
+        name: n.name,
+        kind: n.kind,
+        qualifiedName: n.qualifiedName,
+        startLine: n.startLine,
+        endLine: n.endLine,
+        isExported: !!n.isExported,
+        signature: n.signature,
+      }));
+
+    fileScans.push({
+      filePath: file.path,
+      language: file.language,
+      symbols,
+    });
+
+    for (const sym of symbols) {
+      allSymbols.push({
+        name: sym.name,
+        kind: sym.kind,
+        filePath: file.path,
+        qualifiedName: sym.qualifiedName,
+        startLine: sym.startLine,
+        isExported: sym.isExported,
+      });
+    }
+  }
+
+  return {
+    directory: dirPath,
+    files: fileScans,
+    allSymbols,
+    totalFiles: dirFiles.length,
+    totalSymbols: allSymbols.length,
+  };
+}

package/packages/tools/codegraph/lib/verify/checker.test.ts

@@ -0,0 +1,140 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+/**
+ * REGTEST-2: Verify that `verifyOverlay` correctly validates edge
+ * relationships by checking `getCallees()` / `getCallers()`.
+ *
+ * The fix added a caller/callee relationship check after confirming both
+ * edge endpoints exist in the CodeGraph index. Previously, edges were
+ * only validated for existence of the from/to symbols, not for actual
+ * call relationships.
+ */
+describe('REGTEST-2: Edge relationship validation', () => {
+  it('should report edge failure when no caller/callee relationship exists', async () => {
+    // Mock CodeGraph where:
+    // - funcA and funcB both exist as nodes
+    // - funcA has NO callees (no relationship with funcB)
+    // - The feature slug resolves to a known file so the feature check passes
+    const mockCg = {
+      searchNodes: (name: string) => {
+        if (name === 'test-feature') return [{ node: { id: 'id-feature', name: 'test-feature' } }];
+        if (name === 'funcA') return [{ node: { id: 'id-a', name: 'funcA' } }];
+        if (name === 'funcB') return [{ node: { id: 'id-b', name: 'funcB' } }];
+        return [];
+      },
+      getFiles: () => [{ path: 'test-feature/mod-a.ts' }],
+      getCallees: () => [],
+      getCallers: () => [],
+    };
+
+    const { verifyOverlay } = await import('./checker.js');
+
+    const overlay = {
+      features: {
+        'test-feature': {
+          submodules: [{ slug: 'mod-a', functions: ['funcA', 'funcB'] }],
+          edges: [{ from: 'funcA', to: 'funcB', kind: 'call' }],
+        },
+      },
+    };
+
+    const report = await verifyOverlay(mockCg as any, overlay);
+
+    // Feature and functions should pass; the edge should fail
+    assert.ok(Array.isArray(report.failed), 'failed should be an array');
+    const edgeFails = report.failed.filter((f) => f.type === 'edge');
+    assert.strictEqual(edgeFails.length, 1, 'should report exactly 1 edge failure');
+
+    const edgeFail = edgeFails[0];
+    assert.match(
+      edgeFail.location,
+      /funcA\s*->\s*funcB/,
+      'edge failure location should mention funcA -> funcB',
+    );
+    assert.ok(
+      edgeFail.suggestion?.toLowerCase().includes('no actual call'),
+      'failure suggestion should mention missing call relationship',
+    );
+
+    assert.strictEqual(report.passed, 3, 'feature + 2 functions should pass');
+    assert.strictEqual(report.total, 4, 'total = 3 passed + 1 failed');
+  });
+
+  it('should pass edge when caller/callee relationship exists', async () => {
+    // Mock CodeGraph where:
+    // - funcA and funcB both exist as nodes
+    // - funcA's getCallees returns funcB (relationship exists)
+    const mockCg = {
+      searchNodes: (name: string) => {
+        if (name === 'test-feature') return [{ node: { id: 'id-feature', name: 'test-feature' } }];
+        if (name === 'funcA') return [{ node: { id: 'id-a', name: 'funcA' } }];
+        if (name === 'funcB') return [{ node: { id: 'id-b', name: 'funcB' } }];
+        return [];
+      },
+      getFiles: () => [{ path: 'test-feature/mod-a.ts' }],
+      getCallees: (id: string) => {
+        if (id === 'id-a') return [{ node: { id: 'id-b', name: 'funcB' } }];
+        return [];
+      },
+      getCallers: () => [],
+    };
+
+    const { verifyOverlay } = await import('./checker.js');
+
+    const overlay = {
+      features: {
+        'test-feature': {
+          submodules: [{ slug: 'mod-a', functions: ['funcA', 'funcB'] }],
+          edges: [{ from: 'funcA', to: 'funcB', kind: 'call' }],
+        },
+      },
+    };
+
+    const report = await verifyOverlay(mockCg as any, overlay);
+
+    assert.strictEqual(report.failed.length, 0, 'no failures expected');
+    // 1 feature + 2 functions + 1 edge = 4 passed
+    assert.strictEqual(report.passed, 4, 'feature + 2 functions + edge should all pass');
+    assert.strictEqual(report.total, 4, 'total = 4 passed');
+  });
+
+  it('should handle getCallees throwing gracefully (fallback to next result)', async () => {
+    // Mock CodeGraph where getCallees throws on the first search result
+    // but the second result has the relationship
+    const mockCg = {
+      searchNodes: (name: string) => {
+        if (name === 'test-feature') return [{ node: { id: 'id-feature', name: 'test-feature' } }];
+        if (name === 'funcA') return [
+          { node: { id: 'id-a-bad', name: 'funcA' } },
+          { node: { id: 'id-a-good', name: 'funcA' } },
+        ];
+        if (name === 'funcB') return [{ node: { id: 'id-b', name: 'funcB' } }];
+        return [];
+      },
+      getFiles: () => [{ path: 'test-feature/mod-a.ts' }],
+      getCallees: (id: string) => {
+        if (id === 'id-a-bad') throw new Error('index error');
+        if (id === 'id-a-good') return [{ node: { id: 'id-b', name: 'funcB' } }];
+        return [];
+      },
+      getCallers: () => [],
+    };
+
+    const { verifyOverlay } = await import('./checker.js');
+
+    const overlay = {
+      features: {
+        'test-feature': {
+          submodules: [{ slug: 'mod-a', functions: ['funcA', 'funcB'] }],
+          edges: [{ from: 'funcA', to: 'funcB', kind: 'call' }],
+        },
+      },
+    };
+
+    const report = await verifyOverlay(mockCg as any, overlay);
+
+    assert.strictEqual(report.failed.length, 0, 'no failures expected despite thrown error on first result');
+    assert.strictEqual(report.passed, 4, 'all checks should pass');
+  });
+});