@laitszkin/apollo-toolkit 4.0.11 → 4.1.0

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"}