@mycodemap/mycodemap 1.9.0 → 2.7.0

package/docs/TESTING.md

@@ -0,0 +1,81 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Testing
+
+## Test Stack
+
+CodeMap uses Vitest (`^1.1.0`) for unit, integration, and workflow tests. Coverage reporting is provided by `@vitest/coverage-v8` (`^1.6.1`).
+
+The default configuration (`vitest.config.ts`) runs tests in `src/**/*.test.ts` with a Node environment, `globals: true`, and a `threads` pool (max 2 threads). The E2E suite uses a separate configuration (`vitest.e2e.config.ts`) that runs `tests/e2e/**/*.test.ts` with up to 4 threads. Both configs enforce a 10-second timeout per test and hook.
+
+No global setup file is required; install dependencies with `npm ci` (or `npm install`) and run tests directly.
+
+## Main Test Commands
+
+| Command | Purpose |
+|---|---|
+| `npm test` | Run the default Vitest suite (all `src/**/*.test.ts` files) |
+| `npm run test:e2e` | Run the end-to-end workflow suite (`tests/e2e/**/*.test.ts`) |
+| `npx vitest` | Start Vitest in watch mode |
+| `npm run benchmark` | Run benchmark validation |
+| `npm run test:all` | Run tests followed by benchmarks |
+| `npm run check:all` | Run typecheck, lint, tests, and docs validation |
+
+## What the Tests Cover
+
+- CLI command behavior and output formatting
+- parser and analyzer logic
+- storage backends and fallback behavior
+- HTTP API route handling
+- MCP and env-contract plumbing
+- release, workflow, and guardrail commands
+
+## Practical Guidance
+
+- Prefer real filesystem and subprocess behavior for workflow and integration tests.
+- Use mocks for small units, but do not substitute mocks for end-to-end behavior that the repository already exercises with real I/O.
+- When a test changes command output, update the docs if the user-facing behavior changed.
+
+## Running a Single File
+
+```bash
+npx vitest run src/core/__tests__/analyzer.test.ts
+```
+
+## Writing New Tests
+
+Unit and integration tests live next to source code in `src/**/__tests__/*.test.ts`. End-to-end tests live in `tests/e2e/*.e2e.test.ts`. There is no dedicated global setup or shared helper file; tests import Vitest's `describe`, `it`, and `expect` directly.
+
+When adding a new test:
+- Place unit tests in `src/<module>/__tests__/<name>.test.ts`
+- Place E2E tests in `tests/e2e/<name>.e2e.test.ts`
+- Use `tests/fixtures/` for sample project data and `tests/golden/` for expected output snapshots
+
+## Coverage Requirements
+
+No minimum coverage threshold is configured in `vitest.config.ts`. Coverage is generated on demand with:
+
+```bash
+npx vitest run --coverage
+```
+
+The default reporter outputs text, lcov, and HTML to `./coverage`.
+
+## CI Integration
+
+Tests run in the **CI Gateway** workflow (`.github/workflows/ci-gateway.yml`), which triggers on pushes and pull requests to `main` and `develop`.
+
+Relevant CI steps:
+1. `npm test` — runs the default Vitest suite
+2. `npm run test:e2e` — runs the E2E workflow guardrail
+
+The same workflow also runs typecheck, lint, docs validation, contract gate checks, and CLI guardrails before considering the build green.
+
+## Before Release
+
+Run the validation gates that protect the repo:
+
+```bash
+npm run docs:check
+npm run docs:check:pre-release
+```

package/docs/ai-guide/COMMANDS.md

@@ -2,8 +2,9 @@
 
 > 完整的 CLI 命令详解
 >
-> CodeMap 是 AI-first 代码地图工具。以下文档记录当前公开命令，并补充已移除命令的迁移提示。  
-> 当前 CLI 过渡现实：多数命令显式使用 `--json` 输出机器可读结果；`analyze` 额外支持 `--output-mode machine|human`。
+> CodeMap 是 AI-Native 优先、人类友好的代码架构治理基础设施。以下文档记录当前公开命令，并补充已移除命令的迁移提示。  
+> 命名规范：公开命令示例统一使用 `mycodemap`；`codemap` 只作为兼容别名保留，不作为新示例首选。  
+> v2.0 AI-First Default Output：默认输出 JSON/NDJSON（非 TTY 或显式 `--json`），人类阅读使用 `--human` 或 TTY 自动检测。
 
 ---
 
@@ -124,7 +125,9 @@ mycodemap impact -f "src/cli/index.ts" -j   # JSON 输出
 
 ---
 
-### mcp - experimental 本地 MCP 集成
+### mcp - MCP 集成 (CLI-as-MCP Automatic Gateway)
+
+> v2.0 升级为 CLI-as-MCP Automatic Gateway。所有 20+ schema 定义的 CLI 命令自动暴露为 MCP tools；动态 tool 注册。
 
 ```bash
 mycodemap mcp install                     # 把当前仓库写入 .mcp.json
@@ -134,14 +137,14 @@ mycodemap generate --symbol-level         # 使用前必须先生成 symbol-leve
 
 | 子命令 | 说明 |
 |--------|------|
-| `install` | 更新当前仓库根目录 `.mcp.json`，追加 `mycodemap-experimental` server entry |
-| `start` | 启动 local-only / read-only / stdio-first experimental MCP server |
+| `install` | 更新当前仓库根目录 `.mcp.json`，追加 `mycodemap` server entry |
+| `start` | 启动 local-only / read-only / stdio-first MCP server |
 
-**首期规则**:
-- `mcp` 是 experimental surface，不要把它当成稳定长期 public API。
+**v2.0 行为**:
+- CLI-as-MCP Automatic Gateway：所有 schema 定义的命令（`generate`、`query`、`deps`、`impact`、`analyze`、`doctor`、`benchmark`、`design`、`check`、`ci`、`history`、`workflow` 等）自动映射为 MCP tools。
+- 动态 tool 注册：新增命令无需手动更新 MCP server，schema 变更后自动生效。
 - `mcp start` 的 `stdout` 只能承载 MCP 协议帧；欢迎信息、迁移提示与 runtime log 不会走这条流。
-- 当前只暴露两个工具：`codemap_query`、`codemap_impact`。
-- `codemap_query` / `codemap_impact` 都会返回 `graph_status`、`generated_at` 与显式 `error.code`。
+- 所有 MCP tools 返回 `graph_status`、`generated_at` 与显式 `error.code`。
 - 若图尚未生成，会返回 `GRAPH_NOT_FOUND`；若符号不存在，返回 `SYMBOL_NOT_FOUND`；若同名符号无法消歧，返回 `AMBIGUOUS_EDGE`。
 - 详细安装步骤见 `docs/ai-guide/INTEGRATION.md`；完整 output contract 见 `docs/ai-guide/OUTPUT.md`。
 
@@ -248,6 +251,7 @@ mycodemap analyze -i show -t "src/index.ts" --output-mode human
 | `--include-tests` | 包含测试文件关联 | - |
 | `--include-git-history` | 包含 Git 历史分析 | - |
 | `--json` | JSON 格式输出 | - |
+| `--human` | 强制人类可读输出（覆盖非 TTY 默认 JSON 行为） | - |
 | `--structured` | 纯结构化输出（移除自然语言字段，配合 `--json` 使用） | - |
 | `--output-mode <mode>` | 输出模式：`machine`/`human` | `human` |
 <!-- END GENERATED: analyze-commands-options -->
@@ -515,6 +519,60 @@ mycodemap workflow template recommend "任务"  # 推荐模板
 
 ---
 
+## doctor - 持续健康诊断
+
+> v2.0 新增。检测 ghost 命令、native 依赖问题、workspace drift、agent 连通性。
+
+```bash
+mycodemap doctor              # 人类可读摘要
+mycodemap doctor --json       # 机器可读完整诊断
+```
+
+| 类别 | 检查项 | 说明 |
+|------|--------|------|
+| `install` | native 依赖完整性 | 检查 `better-sqlite3` 等 native 模块是否可加载 |
+| `config` | workspace 完整性 | 检查 `.mycodemap/config.json`、图存储后端配置 |
+| `runtime` | ghost 命令检测 | 检测已注册但无实际实现的命令 |
+| `agent` | MCP 连通性 | 检查 MCP server 注册与工具发现是否正常 |
+
+- 每个类别独立返回 `ok` / `warn` / `error` 状态
+- `--json` 输出纯结构化 diagnostics，包含 `categories[]`、`summary`、`recommendations`
+- `error` 级别诊断会设置非零 exit code
+
+---
+
+## benchmark - WASM vs Native 性能对比
+
+> v2.0 新增。对比 WASM fallback 与 Native 实现的性能差异。
+
+```bash
+mycodemap benchmark           # 完整对比（WASM + Native）
+mycodemap benchmark --wasm    # 仅 WASM 性能
+mycodemap benchmark --native  # 仅 Native 性能
+mycodemap benchmark --json    # JSON 输出
+```
+
+- 输出包含各分析阶段的耗时对比（generate、query、deps、impact 等）
+- `--json` 输出结构化 benchmark 结果，便于 CI 集成与回归检测
+- 用于决定是否启用 WASM fallback 或排查性能退化
+
+---
+
+## --schema - 接口契约输出
+
+> v2.0 新增。输出完整的 Interface Contract Schema JSON，供 agent 自省与动态 tool 注册。
+
+```bash
+mycodemap --schema            # 输出完整 schema JSON
+mycodemap --schema | jq '.'   # 格式化查看
+```
+
+- 单一 schema 同时生成：parser、MCP tools、`--help-json`、shell completions
+- Agent 可通过读取 schema 动态发现所有可用命令及其参数契约
+- 输出包含所有 20+ 命令的完整接口定义（参数、类型、返回值结构）
+
+---
+
 ## 已移除的公共命令
 
 以下命令已从 public CLI 移除；直接调用时，CLI 会显式失败并给出迁移提示，而不是继续执行旧功能。
@@ -544,7 +602,7 @@ mycodemap export json -o ./output.json       # 指定输出
 
 ### ship - 一键智能发布（非代码地图首屏能力）
 
-> `ship` 负责发布整合，不是 AI-first 代码地图工具的首屏入口；首次接触项目时优先使用分析命令而非发布命令。
+> `ship` 负责发布整合，不是 CodeMap 代码分析的首屏入口；首次接触项目时优先使用分析命令而非发布命令。
 
 ```bash
 mycodemap ship                              # 完整发布流程

package/docs/ai-guide/INTEGRATION.md

@@ -1,6 +1,6 @@
 # AI Guide - MCP / Agent 集成
 
-> 当前 canonical integration path：**真实本地 stdio MCP server**。旧 CLI wrapper 只作为 fallback。
+> v2.0 更新：CLI-as-MCP Automatic Gateway。所有 schema 定义的 CLI 命令自动暴露为 MCP tools。
 
 ---
 
@@ -11,11 +11,16 @@
 | transport | 本地 `stdio` |
 | 读写权限 | **只读** |
 | public surface | `mycodemap mcp install`、`mycodemap mcp start` |
-| MCP tools | `codemap_query`、`codemap_impact` |
+| MCP tools | **ALL 20+ schema 定义的 CLI 命令** |
 | 图前置条件 | 先执行 `mycodemap generate --symbol-level` |
-| 稳定性 | **experimental** |
+| 稳定性 | **stable (v2.0)** |
 | 非目标 | HTTP MCP、远程 transport、写操作、全局 host lifecycle |
 
+### 动态 Tool 注册
+
+- 向 `Interface Contract Schema` 添加新命令 → 重启 MCP server → 新 tool 自动出现在 host 中
+- 无需手写 tool 定义、无需修改 MCP server 代码、无需重新安装
+
 ---
 
 ## 1.1 速查表
@@ -44,7 +49,7 @@ mycodemap generate --symbol-level
 mycodemap mcp install
 ```
 
-该命令当前只做一件事：在**当前仓库根目录**的 `.mcp.json` 里写入一个 experimental server entry。
+该命令在当前仓库根目录的 `.mcp.json` 里写入一个 v2.0 server entry。
 
 ### Step 3: 让 MCP host 启动 stdio server
 
@@ -57,6 +62,8 @@ mycodemap mcp start
 - `stdout` 只承载 MCP 协议帧
 - 欢迎信息、迁移提示、runtime log 不会混入 `stdout`
 
+> **v2.0 关键变更**：所有在 `Interface Contract Schema` 中定义的命令自动作为 MCP tools 可用。无需手写 tool 定义，无需逐个注册。
+
 ---
 
 ## 3. `.mcp.json` 参考配置
@@ -66,7 +73,7 @@ mycodemap mcp start
 ```json
 {
   "mcpServers": {
-    "mycodemap-experimental": {
+    "mycodemap": {
       "command": "node",
       "args": ["dist/cli/index.js", "mcp", "start"],
       "cwd": "/absolute/path/to/repo",
@@ -80,7 +87,7 @@ mycodemap mcp start
 
 ### 当前宿主支持边界
 
-- 当前文档只保证**repo-local `.mcp.json`** 这一路径
+- 当前文档只保证 **repo-local `.mcp.json`** 这一路径
 - 不承诺全局安装、升级覆盖策略或卸载命令
 - 若你的 host 不读取 `.mcp.json`，请手动拷贝上面的 server entry 到宿主自己的 MCP 配置文件
 
@@ -88,7 +95,25 @@ mycodemap mcp start
 
 ## 4. MCP tool contract
 
-### `codemap_query`
+### Gateway 模式
+
+CLI-as-MCP Automatic Gateway 将所有 CLI 命令统一映射为 MCP tools：
+
+| CLI 命令 | MCP tool 名 | 输入参数 |
+|----------|-------------|----------|
+| `mycodemap query -s X` | `codemap_query` | `{ symbol: string, filePath?: string }` |
+| `mycodemap impact -f X` | `codemap_impact` | `{ symbol: string, filePath?: string, depth?: number, limit?: number }` |
+| `mycodemap doctor` | `codemap_doctor` | `{ category?: string, json?: boolean }` |
+| `mycodemap benchmark` | `codemap_benchmark` | `{ command?: string, json?: boolean }` |
+| `mycodemap analyze -i find -k X` | `codemap_analyze` | `{ intent: string, keyword: string, ... }` |
+| ... | ... | ... |
+
+映射规则：
+- CLI 命令名 → MCP tool 名前缀为 `codemap_`
+- CLI 短选项（`-s`）和长选项（`--symbol`）→ MCP tool 参数名使用长选项名
+- CLI 输出结构 → MCP tool 返回结构完全一致
+
+### `codemap_query`（示例之一）
 
 输入：
 
@@ -107,7 +132,7 @@ interface CodemapQueryInput {
 - `generated_at`
 - `error.code`（若失败）
 
-### `codemap_impact`
+### `codemap_impact`（示例之一）
 
 输入：
 
@@ -128,7 +153,7 @@ interface CodemapImpactInput {
 - `generated_at`
 - `error.code`（若失败）
 
-> 完整输出类型见 `docs/ai-guide/OUTPUT.md`。
+> 完整输出类型见 `docs/ai-guide/OUTPUT.md`。以上仅为 20+ tools 中的两个示例。
 
 ---
 
@@ -140,6 +165,40 @@ interface CodemapImpactInput {
 | `SYMBOL_NOT_FOUND` | 请求的 symbol 不存在 | 检查拼写，或先用 `query -S` / `analyze -i find` 搜索 |
 | `AMBIGUOUS_EDGE` | 同名 symbol 无法仅靠 `symbol` / `filePath` 消歧 | 补充更具体的 `filePath` |
 
+### Failure-to-Action Protocol
+
+v2.0 错误响应包含可执行的修复指引：
+
+```typescript
+interface McpError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+  // Failure-to-Action Protocol 字段
+  rootCause?: string;           // 根因分析
+  remediationPlan?: string[];   // 修复步骤（按优先级）
+  confidence: "high" | "medium" | "low";
+  nextCommand?: string;         // 建议执行的下一步命令
+}
+```
+
+示例：
+
+```json
+{
+  "code": "GRAPH_NOT_FOUND",
+  "message": "symbol-level 图不存在",
+  "rootCause": "未执行 mycodemap generate --symbol-level",
+  "remediationPlan": [
+    "mycodemap generate --symbol-level",
+    "mycodemap mcp install",
+    "重启 MCP host"
+  ],
+  "confidence": "high",
+  "nextCommand": "mycodemap generate --symbol-level"
+}
+```
+
 ### `graph_status` 解读
 
 | 值 | 含义 |
@@ -158,6 +217,8 @@ interface CodemapImpactInput {
 mycodemap query -s "SymbolName" -j
 mycodemap impact -f "src/file.ts" -j
 mycodemap analyze -i find -k "SymbolName" --json --structured
+mycodemap doctor --json
+mycodemap benchmark --json
 ```
 
 但要注意：
@@ -178,7 +239,7 @@ mycodemap generate --symbol-level
 ### `mcp install` 后看不到 server
 
 - 确认 host 会读取当前仓库根目录的 `.mcp.json`
-- 不会读取的话，手动复制 `mycodemap-experimental` entry 到宿主配置
+- 不会读取的话，手动复制 `mycodemap` entry 到宿主配置
 
 ### `mcp start` 无法启动
 
@@ -200,6 +261,12 @@ npm ls better-sqlite3
 - 先检查 `graph_status` 是否为 `partial`
 - 再检查 symbol 是否真的唯一；必要时补 `filePath`
 
+### 新增命令后 MCP host 看不到新 tool
+
+- 确认新命令已注册到 `Interface Contract Schema`（`mycodemap --schema` 检查）
+- 重启 MCP server（host 侧或 `mycodemap mcp start`）
+- 不需要重新运行 `mcp install`，除非 server entry 本身有变更
+
 ### storage 运行时错误速查表
 
 | 错误 / 信号 | 含义 | 处理方式 |