feat: introduce code context runtime foundation#27
Conversation
Shift the project toward a Code Context Engine by adding runtime-facing domain contracts, lexical-first retrieval, and task-oriented context builders. This establishes structured bundles for review and coding agents while updating top-level docs to reflect the new direction. Made-with: Cursor
Add higher-level symbol navigation and shrink the adapter surface around the Code Context Engine runtime. This makes MCP and CLI thin agent-focused bridges while aligning package naming, docs, and tests with the new runtime-first architecture. Made-with: Cursor
![codegraphmars[bot]](https://avatars.githubusercontent.com/u/29228178?s=60&v=4){kind=small}
There was a problem hiding this comment.
CodaGraph Review 摘要
- PR: #27 feat: introduce code context runtime foundation
- 风险等级: critical
- 报告 ID: 9202
- 已发布行级评论: 8
PR 修改了代码或配置，但没有看到对应的测试改动，回归风险较高。 模式：LLM + 规则；风险等级：critical。 共审查 30 个文件，发现 77 个问题（critical 2 / high 36 / medium 39 / low 0）。
摘要中的补充问题
-
破坏性变更缺少迁移指南 (PR_OVERALL)
- 严重性: high
- 描述: 本次 PR 移除了 7 个 AI 子命令（搜索、图、归档、钩子）和大量 MCP 工具（AST 图查询、语义搜索等），属于破坏性变更。但 docs/mcp.md 仅提供精简概览，README 文档也未包含迁移说明，现有用户将面临功能突然失效的风险。
- 建议: 建议在 README 或单独的 MIGRATION.md 中添加迁移指南，明确列出已移除的功能及其替代方案（如有），并在 CHANGELOG 中标注为 BREAKING CHANGE。
-
新增核心模块缺少测试覆盖 (PR_OVERALL)
- 严重性: high
- 描述: PR 新增了大量核心功能模块（taskHandlers、taskTools、lexicalSearch、fileScanner、parseDiff 等），但 PR 不包含任何测试变更。这些模块涉及正则解析、文件扫描、任务处理等关键逻辑，存在边界条件处理缺陷（如 parseDiff 无法识别删除文件、lexicalSearch 正则安全风险）。
- 建议: 建议为核心新增模块补充单元测试，优先覆盖：1) parseDiff 的边界情况；2) lexicalSearch 的正则安全；3) taskHandlers 的输入校验。
-
品牌重命名跨文件不一致 (PR_OVERALL)
- 严重性: high
- 描述: 项目从 git-ai 重命名为 Code Context Engine，但 README.md 中 Agent Bundle 命令仍引用旧仓库路径，README.zh-CN.md 代码示例存在变量未定义问题。这可能导致用户按文档操作时遇到错误。
- 建议: 全面检查所有文档中的路径引用和代码示例，确保与新的包名、仓库路径一致，并验证示例代码可执行。
-
工具集精简后 schema 同步风险 (PR_OVERALL)
- 严重性: high
- 描述: src/mcp/server.ts 移除了大量工具，src/mcp/tools/index.ts 也进行了大规模重构。需确认 allTools 数组与实际导出的工具完全同步，否则可能导致 schema 缺失或运行时错误。
- 建议: 建议添加编译时或运行时校验，确保 allTools 与导出工具列表一致，或考虑使用自动生成机制。
-
Agent Bundle 命令引用旧仓库路径 (README.md:107)
- 严重性: high
- 描述: 项目已重命名为 code-context-engine，但
npx skills add命令仍引用mars167/git-ai-cli/skills/git-ai-code-search。如果仓库已迁移或重命名，此命令将失效；如果未迁移，则存在品牌不一致问题。 - 建议: 确认仓库是否已重命名。如已重命名，更新为
npx skills add <新仓库路径>/skills/git-ai-code-search；如未重命名，在 PR 描述中说明这是有意保留的兼容路径。
-
代码示例中变量未定义 (README.zh-CN.md:58)
- 严重性: high
- 描述: 示例代码中使用了
rawDiff变量，但该变量未在示例中定义。这会让复制代码的开发者遇到 'rawDiff is not defined' 错误，降低文档的实用性。 - 建议: 在示例开头添加变量定义，如
const rawDiff = '...';或添加注释说明rawDiff应从何处获取。
-
移除多个命令可能导致破坏性变更 (src/commands/ai.ts:1)
- 严重性: high
- 描述: 此次改动移除了 queryCommand、queryFilesCommand、semanticCommand、graphCommand、packCommand、unpackCommand 和 hooksCommand 共 7 个命令。如果用户脚本或工作流依赖这些命令，将直接中断。建议确认这些功能是否已迁移到其他模块，或在 CHANGELOG 中明确标注为破坏性变更。
- 建议: 1) 如果这些命令已迁移，请在 PR 描述中说明迁移路径；2) 考虑在移除前添加废弃警告版本；3) 更新 CHANGELOG 标注为 BREAKING CHANGE。
-
buildContainingScopeQuery 缺少 ref_id 返回字段 (src/core/astGraphQuery.ts:41)
- 严重性: high
- 描述: 该函数返回的列不包含 ref_id，与 buildDefinitionsByNameQuery、buildFindSymbolsQuery、buildChildrenQuery 等类似函数不一致。调用方如果需要唯一标识或进一步查询找到的作用域，将无法获取 ref_id，可能导致后续操作失败或需要额外查询。
- 建议: 在返回列中添加 ref_id，保持与其他查询函数的一致性：
?[ref_id, file, lang, name, kind, signature, start_line, end_line] := ...
| export * from './fileTools'; | ||
| export * from './searchTools'; | ||
| export * from './astGraphTools'; | ||
| export * from './taskTools'; No newline at end of file |
There was a problem hiding this comment.
CRITICAL · 移除 astGraphTools 导出可能导致破坏性变更
删除了 export * from './astGraphTools' 以及 7 个 AST 图查询工具。如果其他模块或外部代码依赖这些导出，将导致运行时错误。需要确认这些工具是否已迁移到其他位置，还是被完全废弃。
建议：确认 astGraphTools 的移除是否有对应的迁移计划。如果已废弃，建议在 CHANGELOG 或 PR 描述中明确标注此破坏性变更；如果已迁移，请更新导入路径。
| let current: ParsedDiffFile | null = null; | ||
|
|
||
| for (const rawLine of diffText.split(/\r?\n/)) { | ||
| if (rawLine.startsWith('+++ b/')) { |
There was a problem hiding this comment.
CRITICAL · 删除的文件无法被正确解析
当文件被删除时，diff 格式为 --- a/path 和 +++ /dev/null。由于代码只在检测到 +++ b/ 时创建文件条目，删除的文件会被完全忽略，导致解析结果丢失重要信息。
建议：同时检测 --- a/ 行来处理删除的文件，或者在检测到 --- a/ 时也创建文件条目，并从该行提取路径。
| @@ -1,87 +1,68 @@ | |||
| # PROJECT KNOWLEDGE BASE | |||
| # Code Context Engine Knowledge Base | |||
There was a problem hiding this comment.
HIGH · 移除了重要的编码规范和反模式文档
原文件包含 CONVENTIONS 和 ANTI-PATTERNS 章节，定义了 TypeScript strict 模式、错误处理规范、禁止 as any 等关键编码标准。这些规范对维护代码质量至关重要，移除后可能导致新贡献者不了解项目约定，引入不一致的代码风格或潜在缺陷。
建议：确认这些规范是否已迁移至其他文档（如 CONTRIBUTING.md 或 src/cli/AGENTS.md）。如未迁移，建议保留或在新架构文档中引用，确保编码标准不丢失。
| @@ -1,280 +1,36 @@ | |||
| # MCP Server Integration | |||
| # Code Context Engine MCP Adapter | |||
There was a problem hiding this comment.
HIGH · 重大变更缺少迁移指南
文档从 280 行缩减到 36 行，工具面从 primitive-first 完全变为 task-oriented。原有工具如 search_symbols、semantic_search、AST graph 工具、DSR 工具均被移除，但未提供迁移说明或废弃公告。现有用户的 Agent 配置和脚本将直接失效。
建议：添加 Migration 章节，说明：1) 哪些工具被废弃及其替代方案；2) git-ai 到 code-context-engine 的命令别名或兼容性；3) DSR 功能的后续计划。
|
|
||
| ```bash | ||
| git-ai ai serve --http --port 3000 | ||
| code-context-engine ai serve |
There was a problem hiding this comment.
HIGH · 命令名称变更未说明兼容性
命令从 git-ai ai serve 变更为 code-context-engine ai serve，这是破坏性变更。用户现有的启动脚本、CI 配置、MCP 客户端配置都需要修改。
建议：说明是否提供 git-ai 作为向后兼容的别名，或在文档中明确标注这是 breaking change。
| - **DSR** is "per-commit semantic artifacts (.git-ai/dsr)", used for semantic history/evolution queries | ||
| - DSR is per-commit, immutable, deterministic, enabling precise symbol change tracing | ||
| - All historical traversal must start from Git DAG (DSR only enriches nodes, doesn't define edges) | ||
| ### Index and repo access |
There was a problem hiding this comment.
HIGH · 新工具缺少功能说明和参数文档
新增的 task-oriented 工具（implementation_context、find_tests、find_impact、find_extension_points、review_context_for_diff）仅列出参数签名，未说明功能语义、使用场景、返回格式。Agent 无法正确使用这些工具。
建议：为每个工具添加简要功能说明、典型使用场景示例、返回值结构说明。参考旧版文档中 search_symbols 的文档风格。
| "test": "npm run build && node dist/bin/git-ai.js ai index --overwrite && node --test test/*.test.mjs test/*.test.ts test/*.test.js", | ||
| "test:cli": "bash test-cli.sh", | ||
| "start": "ts-node bin/code-context-engine.ts", | ||
| "test": "npm run build && node --test test/runtime.search.test.ts test/runtime.tasks.test.ts test/runtime.navigation.test.ts test/diffReviewContext.test.ts test/agentBundle.test.ts test/mcp.smoke.test.js", |
There was a problem hiding this comment.
HIGH · 测试覆盖范围可能缩小
原测试命令使用通配符 test/*.test.mjs test/*.test.ts test/*.test.js 可自动包含所有测试文件，现改为硬编码的具体文件列表。新增测试文件时容易被遗漏，且移除了 .mjs 测试文件的通配匹配。
建议：考虑保留通配符模式，或在 CI 中添加检查确保所有测试文件都被执行。如果是有意缩小范围，建议在 PR 中说明原因。
| "test": "npm run build && node dist/bin/git-ai.js ai index --overwrite && node --test test/*.test.mjs test/*.test.ts test/*.test.js", | ||
| "test:cli": "bash test-cli.sh", | ||
| "start": "ts-node bin/code-context-engine.ts", | ||
| "test": "npm run build && node --test test/runtime.search.test.ts test/runtime.tasks.test.ts test/runtime.navigation.test.ts test/diffReviewContext.test.ts test/agentBundle.test.ts test/mcp.smoke.test.js", |
There was a problem hiding this comment.
HIGH · 移除了测试前的索引初始化步骤
原测试命令包含 node dist/bin/git-ai.js ai index --overwrite，用于在测试前初始化索引。新命令移除了此步骤，可能导致依赖预置索引数据的测试失败或测试不完整。
建议：确认测试是否不再需要预置索引数据。如仍需要，应在测试脚本中保留初始化步骤或将其移至测试 setup 中。
1 participant
Summary
Test plan
npm run buildnode --test test/runtime.search.test.ts test/runtime.tasks.test.ts test/diffReviewContext.test.tsMade with Cursor