@laitszkin/apollo-toolkit 4.0.11 → 4.1.1

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');
+  });
+});

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

@@ -0,0 +1,172 @@
+import type { CodeGraph } from '@colbymchenry/codegraph';
+
+export interface VerifyItem {
+  type: 'feature' | 'submodule' | 'function' | 'edge' | 'variable';
+  location: string;
+  action?: string;
+  suggestion?: string;
+}
+
+export interface VerifyReport {
+  passed: number;
+  failed: VerifyItem[];
+  skipped: number;
+  total: number;
+}
+
+/**
+ * Verify an architecture overlay against the actual CodeGraph to confirm
+ * that every referenced symbol, submodule, and edge actually exists in the
+ * indexed codebase.
+ *
+ * Overlay format follows the atlas convention:
+ * ```json
+ * {
+ *   "features": {
+ *     "<slug>": {
+ *       "submodules": [{ "slug": "...", "kind": "...", "role": "...", "functions": [...] }],
+ *       "edges": [{ "from": "...", "to": "...", "kind": "..." }]
+ *     }
+ *   },
+ *   "removed": { "features": [...], "submodules": [...] }
+ * }
+ * ```
+ */
+export async function verifyOverlay(
+  cg: CodeGraph,
+  overlay: any,
+): Promise<VerifyReport> {
+  const passed: VerifyItem[] = [];
+  const failed: VerifyItem[] = [];
+  let skipped = 0;
+
+  const features = overlay.features || {};
+
+  for (const [slug, feature] of Object.entries<any>(features)) {
+    // If the feature itself declares `action: add`, it's a new feature — skip verification
+    if (feature.action === 'add') {
+      skipped++;
+      continue;
+    }
+
+    // Check feature slug exists in codebase
+    const featureSearch = cg.searchNodes(slug, { limit: 5 });
+    // Features are directory-level; we check if any file matches the slug pattern
+    const hasFeatureFiles = cg.getFiles().some((f) => f.path.startsWith(slug + '/') || f.path.includes('/' + slug + '/'));
+    if (!hasFeatureFiles && featureSearch.length === 0) {
+      failed.push({
+        type: 'feature',
+        location: slug,
+        suggestion: `No files or symbols found matching feature "${slug}". Verify the feature slug is correct or add it with "action: add".`,
+      });
+      continue;
+    }
+    passed.push({ type: 'feature', location: slug });
+
+    // Check each submodule
+    const submodules = feature.submodules || [];
+    for (const sub of submodules) {
+      if (sub.action === 'add') {
+        skipped++;
+        continue;
+      }
+
+      // Check submodule functions exist in the codebase
+      const functions = sub.functions || [];
+      for (const fn of functions) {
+        if (typeof fn === 'string') {
+          // Simple string function name
+          const fnSearch = cg.searchNodes(fn, { limit: 3 });
+          if (fnSearch.length === 0) {
+            failed.push({
+              type: 'function',
+              location: `${slug}/${sub.slug}::${fn}`,
+              suggestion: `Function "${fn}" not found in codeGraph index for ${slug}/${sub.slug}. Verify the name or add via "action: add".`,
+            });
+          } else {
+            passed.push({ type: 'function', location: `${slug}/${sub.slug}::${fn}` });
+          }
+        } else if (typeof fn === 'object' && fn.name) {
+          const fnSearch = cg.searchNodes(fn.name, { limit: 3 });
+          if (fnSearch.length === 0) {
+            failed.push({
+              type: 'function',
+              location: `${slug}/${sub.slug}::${fn.name}`,
+              suggestion: `Function "${fn.name}" not found in codeGraph index.`,
+            });
+          } else {
+            passed.push({ type: 'function', location: `${slug}/${sub.slug}::${fn.name}` });
+          }
+        }
+      }
+    }
+
+    // Check edges — verify both endpoints exist AND the caller/callee relationship
+    const edges = feature.edges || [];
+    for (const edge of edges) {
+      const { from, to } = edge;
+      const fromName = typeof from === 'string' ? from : from?.submodule;
+      const toName = typeof to === 'string' ? to : to?.submodule;
+
+      if (!fromName || !toName) {
+        failed.push({
+          type: 'edge',
+          location: `${slug}: ${fromName || '?'} -> ${toName || '?'}`,
+          suggestion: `Edge missing from or to field.`,
+        });
+        continue;
+      }
+
+      const fromSearch = cg.searchNodes(fromName, { limit: 3 });
+      if (fromSearch.length === 0) {
+        failed.push({
+          type: 'edge',
+          location: `${slug}: ${fromName} -> ${toName}`,
+          suggestion: `Edge source "${fromName}" not found in codeGraph index.`,
+        });
+        continue;
+      }
+
+      const toSearch = cg.searchNodes(toName, { limit: 3 });
+      if (toSearch.length === 0) {
+        failed.push({
+          type: 'edge',
+          location: `${slug}: ${fromName} -> ${toName}`,
+          suggestion: `Edge target "${toName}" not found in codeGraph index.`,
+        });
+        continue;
+      }
+
+      // Both endpoints exist — verify the actual caller/callee relationship
+      let relationshipFound = false;
+      for (const fromResult of fromSearch) {
+        try {
+          const callees = cg.getCallees(fromResult.node.id, 1);
+          if (callees.some((c) => c.node.name === toName || toSearch.some((tr) => tr.node.id === c.node.id))) {
+            relationshipFound = true;
+            break;
+          }
+        } catch {
+          // If getCallees fails for this node, try the next match
+        }
+      }
+
+      if (relationshipFound) {
+        passed.push({ type: 'edge', location: `${slug}: ${fromName} -> ${toName}` });
+      } else {
+        failed.push({
+          type: 'edge',
+          location: `${slug}: ${fromName} -> ${toName}`,
+          suggestion: `No actual call relationship found from "${fromName}" to "${toName}". Verify the edge definition or add the call in source code.`,
+        });
+      }
+    }
+  }
+
+  return {
+    passed: passed.length,
+    failed,
+    skipped,
+    total: passed.length + failed.length + skipped,
+  };
+}

package/packages/tools/codegraph/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@laitszkin/tool-codegraph",
+  "version": "4.0.8",
+  "description": "Apollo Toolkit — CodeGraph code intelligence: init, sync, status, search, explore, survey, list-apis, verify",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "test": "node --test dist/"
+  },
+  "dependencies": {
+    "@colbymchenry/codegraph": "^0.9.0",
+    "@laitszkin/tool-registry": "*"
+  }
+}

package/packages/tools/codegraph/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": true,
+    "strict": true,
+    "composite": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["dist", "node_modules"],
+  "references": [
+    { "path": "../../tool-registry" },
+    { "path": "../../tool-utils" }
+  ]
+}

package/resources/project-architecture/atlas/atlas.history.log

@@ -4,3 +4,35 @@
 {"ts":"2026-05-29T13:27:26.796Z","action":"submodule remove","args":{"feature":"eval-isolation","slug":"context-factory"},"mode":"base"}
 {"ts":"2026-05-29T13:27:29.784Z","action":"submodule set","args":{"feature":"eval-executor","slug":"trace-recorder","role":"多輪tool-use loop軌跡記錄：tool_call/tool_result事件序列、JSONL行號標記、.done完成標記"},"mode":"base"}
 {"ts":"2026-05-29T13:27:30.597Z","action":"submodule set","args":{"feature":"eval-scorer","slug":"judge-prompt-builder","role":"評分提示詞構建：trace事件摘要含JSONL行號(L{N})引用、三維度評分指示"},"mode":"base"}
+{"ts":"2026-06-03T12:34:41.876Z","action":"merge","args":{"specs":["docs/plans/2026-06-03/codegraph-integration"]},"mode":"base"}
+{"ts":"2026-06-03T12:35:20.204Z","action":"merge","args":{"specs":["docs/plans/2026-06-03/codegraph-integration"]},"mode":"base"}
+{"ts":"2026-06-03T13:17:20.902Z","action":"actor add","args":{"id":"codegraph-npm","label":"@colbymchenry/codegraph npm package"},"mode":"base"}
+{"ts":"2026-06-03T13:17:21.339Z","action":"actor add","args":{"id":"tool-registry","label":"Tool Registry (@laitszkin/tool-registry)"},"mode":"base"}
+{"ts":"2026-06-03T13:17:21.782Z","action":"actor add","args":{"id":"tui-lib","label":"TUI Library (@laitszkin/tui)"},"mode":"base"}
+{"ts":"2026-06-03T13:17:28.148Z","action":"edge add","args":{"from":{"feature":"eval-cli"},"to":{"feature":"tool-registry"},"kind":"call","label":"所有 CLI 工具透過 ToolDefinition 註冊到 tool-registry"},"mode":"base"}
+{"ts":"2026-06-03T13:17:32.395Z","action":"edge add","args":{"from":{"feature":"eval-cli"},"to":{"feature":"actor:tool-registry"},"kind":"call","label":"CLI 工具透過 ToolDefinition 註冊"},"mode":"base"}
+{"ts":"2026-06-03T13:17:40.638Z","action":"edge add","args":{"from":{"feature":"eval-cli","submodule":"cli-handler"},"to":{"feature":"user-dev"},"kind":"call","label":"開發者透過 CLI 觸發評測","id":"eval-cli-user"},"mode":"base"}
+{"ts":"2026-06-03T13:17:51.133Z","action":"function add","args":{"feature":"eval-cli","submodule":"cli-handler","name":"evalHandler"},"mode":"base"}
+{"ts":"2026-06-03T13:17:58.482Z","action":"undo","mode":"base"}
+{"ts":"2026-06-03T13:18:20.853Z","action":"function add","args":{"feature":"eval-cli","submodule":"cli-handler","name":"evalHandler"},"mode":"base"}
+{"ts":"2026-06-03T13:18:21.437Z","action":"function add","args":{"feature":"eval-cli","submodule":"cli-handler","name":"parseArgs"},"mode":"base"}
+{"ts":"2026-06-03T13:18:22.010Z","action":"function add","args":{"feature":"eval-cli","submodule":"cli-handler","name":"tool"},"mode":"base"}
+{"ts":"2026-06-03T13:18:24.988Z","action":"function add","args":{"feature":"eval-executor","submodule":"trace-recorder","name":"runSingleTest"},"mode":"base"}
+{"ts":"2026-06-03T13:18:25.681Z","action":"function add","args":{"feature":"eval-executor","submodule":"exec-api-client","name":"withRetry"},"mode":"base"}
+{"ts":"2026-06-03T13:18:26.471Z","action":"function add","args":{"feature":"eval-scorer","submodule":"judge-prompt-builder","name":"buildJudgePrompt"},"mode":"base"}
+{"ts":"2026-06-03T13:18:27.104Z","action":"function add","args":{"feature":"eval-scorer","submodule":"judge-api-client","name":"callJudgeModel"},"mode":"base"}
+{"ts":"2026-06-03T13:18:30.197Z","action":"function add","args":{"feature":"eval-isolation","submodule":"tool-dispatcher","name":"buildSystemPrompt"},"mode":"base"}
+{"ts":"2026-06-03T13:18:30.842Z","action":"function add","args":{"feature":"eval-question","submodule":"question-loader","name":"loadQuestions"},"mode":"base"}
+{"ts":"2026-06-03T13:18:31.691Z","action":"function add","args":{"feature":"eval-question","submodule":"variant-generator","name":"generateVariants"},"mode":"base"}
+{"ts":"2026-06-03T13:18:32.174Z","action":"function add","args":{"feature":"eval-reporter","submodule":"report-composer","name":"generateReport"},"mode":"base"}
+{"ts":"2026-06-03T13:18:34.967Z","action":"function add","args":{"feature":"eval-optimizer","submodule":"issue-extractor","name":"extractIssues"},"mode":"base"}
+{"ts":"2026-06-03T13:18:35.639Z","action":"function add","args":{"feature":"eval-optimizer","submodule":"dedup-engine","name":"deduplicateIssues"},"mode":"base"}
+{"ts":"2026-06-03T13:18:36.404Z","action":"function add","args":{"feature":"eval-optimizer","submodule":"issue-extractor","name":"generateOptimizationPlan"},"mode":"base"}
+{"ts":"2026-06-03T13:18:37.146Z","action":"function add","args":{"feature":"eval-ci-gate","submodule":"workflow-trigger","name":"detectSkillChanges"},"mode":"base"}
+{"ts":"2026-06-03T13:18:40.020Z","action":"edge add","args":{"from":{"feature":"eval-cli","submodule":"cli-handler"},"to":{"feature":"eval-executor","submodule":"trace-recorder"},"kind":"call","label":"evalHandler 觸發 runSingleTest","id":"eval-cli-exec"},"mode":"base"}
+{"ts":"2026-06-03T13:18:40.712Z","action":"edge add","args":{"from":{"feature":"eval-executor","submodule":"trace-recorder"},"to":{"feature":"eval-isolation","submodule":"tool-dispatcher"},"kind":"call","label":"執行隔離環境中的工具調用","id":"eval-exec-iso"},"mode":"base"}
+{"ts":"2026-06-03T13:18:41.390Z","action":"edge add","args":{"from":{"feature":"eval-executor","submodule":"trace-recorder"},"to":{"feature":"eval-scorer","submodule":"judge-prompt-builder"},"kind":"data-row","label":"trace events 送入評分","id":"eval-exec-scorer"},"mode":"base"}
+{"ts":"2026-06-03T13:18:42.015Z","action":"edge add","args":{"from":{"feature":"eval-scorer","submodule":"judge-api-client"},"to":{"feature":"judge-model-api"},"kind":"call","label":"呼叫 Judge Model API 評分","id":"eval-judge-api"},"mode":"base"}
+{"ts":"2026-06-03T13:18:56.177Z","action":"edge add","args":{"from":{"feature":"eval-scorer"},"to":{"feature":"eval-reporter"},"kind":"data-row","label":"ScoreResult 送入報告組合","id":"eval-scorer-reporter"},"mode":"base"}
+{"ts":"2026-06-03T13:18:56.778Z","action":"edge add","args":{"from":{"feature":"eval-executor"},"to":{"feature":"eval-optimizer"},"kind":"data-row","label":"執行結果觸發優化","id":"eval-exec-optimizer"},"mode":"base"}
+{"ts":"2026-06-03T13:18:57.451Z","action":"edge add","args":{"from":{"feature":"eval-cli"},"to":{"feature":"eval-ci-gate"},"kind":"call","label":"CI 模式下觸發 PR 回報","id":"eval-cli-ci"},"mode":"base"}