@mycodemap/mycodemap 0.4.2 → 0.5.1

package/docs/ai-guide/COMMANDS.md

@@ -16,6 +16,7 @@ mycodemap generate                          # hybrid 模式（推荐）
 mycodemap generate -m smart                 # AST 深度分析
 mycodemap generate -m fast                  # 快速正则分析
 mycodemap generate -o ./output              # 指定输出目录
+mycodemap generate --symbol-level           # 额外 materialize symbol-level call 依赖
 mycodemap generate --ai-context             # 生成 AI 描述
 ```
 
@@ -23,12 +24,15 @@ mycodemap generate --ai-context             # 生成 AI 描述
 |------|------|--------|
 | `-m, --mode <mode>` | 分析模式: fast/smart/hybrid | `hybrid` |
 | `-o, --output <dir>` | 输出目录 | `.mycodemap` |
+| `--symbol-level` | 仅在显式开启时把可解析的 symbol-level `call` 依赖写入图存储 | `false` |
 | `--ai-context` | 为每个文件生成描述 | - |
 
 **模式说明**:
 - `fast`: 正则匹配，极快，适合大型项目
 - `smart`: AST 分析，较慢，信息完整
 - `hybrid`: 自动选择，文件<50用fast，≥50用smart
+- `--symbol-level` 是首期实验性切片；默认 generate 仍只保证现有模块级行为兼容
+- `generate` 完成后，`codemap.json` 会带 `graphStatus`、`failedFileCount` 与可选 `parseFailureFiles`；若 `graphStatus = "partial"`，不要把结果当成完整图。
 
 **插件运行时说明**:
 - `generate` 不提供独立 `--plugin` flags；插件通过 `mycodemap.config.json` 的 `plugins` 段声明。
@@ -37,9 +41,9 @@ mycodemap generate --ai-context             # 生成 AI 描述
 
 **图存储运行时说明**:
 - `generate` 会读取 `mycodemap.config.json.storage`，并把 CodeGraph 写入所选后端。
-- `storage.type` 支持 `filesystem`、`kuzudb`、`memory`、`auto`；默认是 `filesystem`。
-- 旧的 `neo4j` 配置会直接报迁移错误；缺少 `kuzu` 时也会直接报错，不会静默 fallback 到 `filesystem`。
-- `storage.type = "auto"` 当前仍保守走 `filesystem`；阈值字段是配置契约，不代表自动切换已完成。
+- `storage.type` 支持 `filesystem`、`sqlite`、`memory`、`auto`；默认是 `filesystem`。
+- 旧的 `neo4j` / `kuzudb` 配置会直接报迁移错误；显式选择 `sqlite` 但运行时缺少 `better-sqlite3` 或 Node.js `<20` 时也会直接报错，不会静默 fallback 到 `filesystem`。
+- `storage.type = "auto"` 当前优先走 `sqlite`；只有 SQLite 不可用时才 warning 后回退 `filesystem`。
 
 ---
 
@@ -105,11 +109,35 @@ mycodemap impact -f "src/cli/index.ts" -j   # JSON 输出
 
 ---
 
+### mcp - experimental 本地 MCP 集成
+
+```bash
+mycodemap mcp install                     # 把当前仓库写入 .mcp.json
+mycodemap mcp start                       # 启动本地 stdio MCP server
+mycodemap generate --symbol-level         # 使用前必须先生成 symbol-level 图
+```
+
+| 子命令 | 说明 |
+|--------|------|
+| `install` | 更新当前仓库根目录 `.mcp.json`，追加 `mycodemap-experimental` server entry |
+| `start` | 启动 local-only / read-only / stdio-first experimental MCP server |
+
+**首期规则**:
+- `mcp` 是 experimental surface，不要把它当成稳定长期 public API。
+- `mcp start` 的 `stdout` 只能承载 MCP 协议帧；欢迎信息、迁移提示与 runtime log 不会走这条流。
+- 当前只暴露两个工具：`codemap_query`、`codemap_impact`。
+- `codemap_query` / `codemap_impact` 都会返回 `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`。
+
+---
+
 ### complexity - 复杂度分析
 
 ```bash
 mycodemap complexity                        # 项目整体
 mycodemap complexity -f "src/cli/index.ts"  # 指定文件
+mycodemap complexity -f "src/cli/index.ts" -j  # 单文件 JSON，顶层返回 file
 mycodemap complexity -d                     # 函数级详情
 mycodemap complexity -j                     # JSON 输出
 ```
@@ -121,6 +149,8 @@ mycodemap complexity -j                     # JSON 输出
 | `-j, --json` | JSON 格式输出 | - |
 | `--structured` | 纯结构化输出 | - |
 
+> `complexity -f "src/file.ts" -j` 的 JSON 顶层只返回 `file`；不会返回全项目 `modules` 数组。
+
 ---
 
 ### cycles - 循环依赖检测
@@ -148,10 +178,13 @@ mycodemap cycles -j                         # JSON 输出
 | 输出契约 | 多数命令显式 `--json`，`analyze` 额外提供 `--output-mode machine|human` | `--structured --json` 会移除自然语言 `content` |
 | analyze 意图 | `find` / `read` / `link` / `show` | legacy alias 会在输出中返回 `warnings[]`；`refactor` 直接报 `E0001_INVALID_INTENT` |
 
+> 通用搜索仍优先使用 `query -S "XXX" -j`。需要统一 analyze schema 时使用 `analyze -i find -k "XXX" --json --structured`，并读取 stdout JSON 的 `diagnostics.status` 区分真实 0 命中、`partialFailure` 降级与 `failure`。
+
 <!-- BEGIN GENERATED: analyze-commands-intents -->
 ```bash
 # 1. find - 查找符号 / 文本
 mycodemap analyze -i find -k "UnifiedResult"
+mycodemap analyze -i find -k "SourceLocation" --json --structured
 mycodemap analyze -i find -t "src/orchestrator" -k "IntentRouter" --topK 20
 
 # 2. read - 阅读文件（影响 + 复杂度）
@@ -214,6 +247,118 @@ mycodemap analyze -i show -t "src/index.ts" --output-mode human
 
 ---
 
+## design - 设计契约输入、范围映射与验证
+
+> `design` 为 human-authored design contract 提供正式输入面。默认文件名是 `mycodemap.design.md`，canonical 模板位于 `docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md`。
+
+### validate
+
+```bash
+# 使用默认文件名
+mycodemap design validate mycodemap.design.md --json
+
+# 显式指定文件
+mycodemap design validate docs/designs/login.design.md
+```
+
+### 必填 sections
+
+| Section | 作用 |
+|---------|------|
+| `Goal` | 定义本次要达成的结果 |
+| `Constraints` | 定义边界、兼容性和约束 |
+| `Acceptance Criteria` | 定义可验证的成功标准 |
+| `Non-Goals` | 明确本次不做什么，防止 scope drift |
+
+### 输出与失败语义
+
+- `--json` 输出纯结构化 diagnostics
+- 缺失必填 section、重复 section、空 section、未知 heading 都会被显式报告
+- blocker diagnostics 存在时命令返回非零 exit code
+
+### map
+
+```bash
+# 先校验，再映射 candidate scope
+mycodemap design validate mycodemap.design.md --json
+mycodemap design map mycodemap.design.md --json
+```
+
+- `design map` 返回 `summary`、`candidates`、`diagnostics`、`unknowns`
+- `candidates[]` 会同时暴露 `kind`、`path`、`reasons`、`dependencies`、`testImpact`、`risk`、`confidence`
+- blocker diagnostics 包括 `no-candidates`、`over-broad-scope`、`high-risk-scope`
+- 若 diagnostics 中存在 blocker，命令返回非零 exit code
+
+### handoff
+
+```bash
+# 先固定 design input / scope，再生成 handoff package
+mycodemap design validate mycodemap.design.md --json
+mycodemap design map mycodemap.design.md --json
+mycodemap design handoff mycodemap.design.md --json
+```
+
+- `design handoff` 返回 `readyForExecution`、`approvals`、`assumptions`、`openQuestions`
+- human mode 默认写入 `.mycodemap/handoffs/{stem}.handoff.md|json`
+- `--json` 保持纯 JSON，不混入 prose
+- review-needed 通过 `readyForExecution=false` 表达；只有 blocker diagnostics 才返回非零 exit code
+
+### verify
+
+```bash
+# 使用 reviewed handoff truth 做 checklist / drift 校验
+mycodemap design validate mycodemap.design.md --json
+mycodemap design map mycodemap.design.md --json
+mycodemap design handoff mycodemap.design.md --json
+mycodemap design verify mycodemap.design.md --json
+```
+
+- `design verify` 返回 `summary`、`checklist`、`drift`、`diagnostics`
+- `checklist[]` 直接来自 `Acceptance Criteria`，并保留 `status` + `evidenceRefs`
+- `drift[]` 至少区分 `scope-extra`、`acceptance-unverified`、`handoff-missing`
+- review-needed 通过 `readyForExecution=false` + warning diagnostics 表达；只有 `ok=false` 或 blocker diagnostics 才返回非零 exit code
+
+---
+
+## check - 执行 contract gate
+
+```bash
+# 默认 full scan
+mycodemap check --contract mycodemap.design.md --against src
+
+# 人类可读渲染
+mycodemap check --contract mycodemap.design.md --against src --human
+
+# PR / CI 显式 diff
+mycodemap check --contract mycodemap.design.md --against src --base origin/main
+
+# 显式 changed files
+mycodemap check --contract mycodemap.design.md --against src --changed-files src/core/service.ts
+
+# GitHub PR annotations
+mycodemap check --contract mycodemap.design.md --against src --base origin/main --annotation-format github
+
+# GitLab code quality artifact
+mycodemap check --contract mycodemap.design.md --against src --base origin/main --annotation-format gitlab --annotation-file gl-code-quality-report.json
+
+# 校准当前仓库是否允许默认 hard gate
+node scripts/calibrate-contract-gate.mjs --max-changed-files 10 --max-false-positive-rate 0.10
+```
+
+- 默认输出 `ContractCheckResult` JSON；`--human` 只改变渲染，不改变底层 truth
+- JSON 默认包含 `passed` 与 `summary`，Agent 不需要解析 prose 判断通过状态
+- `severity:error` 返回非零退出码，`severity:warn` 不阻断
+- diff-aware 只在显式提供 `--base` 或 `--changed-files` 时启用
+- 坏掉的 diff base 或越界 changed files 会回退 full scan，并把原因写进 `warnings[]`
+- 当前 rule families 为 `layer_direction` / `forbidden_imports` / `module_public_api_only` / `complexity_threshold`
+- `--annotation-format github` 会输出 GitHub Actions annotations；`gitlab` 需要配合 `--annotation-file gl-code-quality-report.json`，并只保留 line-scoped diagnostics
+- PR 默认 hard gate 只在 calibration 通过且 `changed files <= 10` 时开启；超窗、`diff-scope-fallback` 或 `false-positive rate >10%` 时必须显式切回 `warn-only / fallback`
+- calibration 输出的 recommendation 目前是 `hard-gate-ok` / `warn-only` / `re-scope`；fallback 不应伪装成稳定 hard gate
+- Git history risk 是 additive enrichment：会附加 `violations[].risk` 与顶层 `history`，但不会改变 `severity:error` / exit 语义
+- 仓库根 `mycodemap.design.md` 是当前 canonical contract truth
+
+---
+
 ## ci - CI 门禁
 
 ### 子命令
@@ -239,10 +384,11 @@ mycodemap ci check-headers
 mycodemap ci check-headers -d "src/domain"  # 指定目录
 mycodemap ci check-headers -f "file1.ts,file2.ts"
 
-# 评估变更风险
+# 评估变更风险（与 `check` / `history` 共用同一套 Git history risk truth）
 mycodemap ci assess-risk
 mycodemap ci assess-risk -t 0.5             # 设置阈值 0.5
 mycodemap ci assess-risk -f "changed.ts"
+mycodemap ci assess-risk --files "changed.ts" --json
 
 # 验证文档同步
 mycodemap ci check-docs-sync
@@ -261,6 +407,24 @@ mycodemap ci check-commit-size -m 15
 
 > `ship` 的 CHECK 阶段会复用 `ci check-working-tree`、`ci check-branch`、`ci check-scripts` 这三条发布前 gate checks。
 > `ci check-branch --allow` 支持 `*` 通配；`ci check-headers -d` 与 `generate` / `analyze` 共享同一套 `.gitignore` 感知排除规则，在没有 `.gitignore` 时回退到默认 `exclude`。
+> `ci assess-risk` 现在输出 `status / confidence / freshness / source / score / level`；若 Git history 不可用，会显式给出 `unavailable` / warning，并说明阈值未被应用。
+> `ci assess-risk --json` 顶层输出 `status: "passed" | "failed" | "skipped"`；`failed` 会设置非零 exit code，但 stdout 保持可解析 JSON。
+
+---
+
+## history - 符号级 Git history / risk 查询
+
+```bash
+# 默认输出 machine-first JSON
+mycodemap history --symbol createCheckCommand
+
+# 人类可读渲染
+mycodemap history --symbol createCheckCommand --human
+```
+
+- 返回 `ok` / `ambiguous` / `not_found` / `unavailable` 四种状态
+- `--human` 只改变展示，不改变结构化 truth
+- 与 `check` / `ci assess-risk` 共用同一套 history risk service；历史缺失时会显式返回 `unavailable`
 
 ### 支持的提交 TAG
 
@@ -287,6 +451,7 @@ mycodemap ci check-commit-size -m 15
 # 启动工作流
 mycodemap workflow start "实现用户认证模块"
 mycodemap workflow start "修复登录接口" --template bugfix
+mycodemap workflow start "inspect analyze find" --json
 
 # 查看状态
 mycodemap workflow status
@@ -312,6 +477,8 @@ mycodemap workflow resume
 mycodemap workflow resume "workflow-id"
 ```
 
+> `workflow start --json` 输出 `{ status, task, id, currentPhase, template, nextSteps }`，不改变 workflow 的 analysis-only 边界。
+
 ### 模板管理
 
 ```bash