@mycodemap/mycodemap 0.5.0 → 0.5.1

package/docs/ai-guide/OUTPUT.md

@@ -77,15 +77,33 @@ interface CodeMap {
   summary: ProjectSummary;
   modules: ModuleInfo[];
   dependencies: DependencyGraph;
+  graphStatus?: "complete" | "partial";
+  failedFileCount?: number;
+  parseFailureFiles?: string[];
   actualMode?: "fast" | "smart";
   pluginReport?: PluginExecutionReport;
 }
 ```
 
+### graph integrity 语义
+
+| 字段 | 含义 | 何时出现 |
+|------|------|----------|
+| `graphStatus` | 当前图是否完整：`complete` / `partial` | `generate` 输出总会写入 |
+| `failedFileCount` | 发现到但未成功进入最终图的文件数 | `generate` 输出总会写入 |
+| `parseFailureFiles` | 失败文件路径列表 | 仅当 `failedFileCount > 0` 时出现 |
+
+- `summary.totalFiles` 仍表示**成功进入最终图**的模块数，不代表发现阶段的总文件数。
+- 若 `graphStatus = "partial"`，Agent / 自动化流程必须把图视为**降级结果**，不能伪装成完整 truth。
+- `generate --symbol-level` 与默认 generate 都遵守同一套 `graphStatus` 语义；差别只在是否 materialize symbol-level `call` 依赖。
+
 ### 示例
 
 ```json
 {
+  "graphStatus": "partial",
+  "failedFileCount": 1,
+  "parseFailureFiles": ["src/broken.ts"],
   "pluginReport": {
     "loadedPlugins": ["complexity-analyzer", "my-local-plugin"],
     "generatedFiles": ["plugins/good.txt"],
@@ -110,6 +128,144 @@ interface CodeMap {
 
 ---
 
+## experimental MCP tool 输出结构
+
+> canonical MCP path 是 `generate --symbol-level → mcp install → host 启动 mcp start`。当前只暴露 `codemap_query` / `codemap_impact` 两个工具。
+
+```typescript
+type McpToolStatus = "ok" | "not_found" | "ambiguous" | "unavailable";
+type McpToolConfidence = "high" | "ambiguous" | "unavailable";
+type McpGraphStatus = "complete" | "partial" | "missing";
+type McpErrorCode = "GRAPH_NOT_FOUND" | "SYMBOL_NOT_FOUND" | "AMBIGUOUS_EDGE";
+
+interface McpSymbolRef {
+  id: string;
+  module_id: string;
+  name: string;
+  kind: string;
+  visibility: "public" | "private" | "protected" | "internal";
+  file_path: string;
+  line: number;
+  column: number;
+  signature?: string;
+}
+
+interface McpQueryResult {
+  status: McpToolStatus;
+  confidence: McpToolConfidence;
+  graph_status: McpGraphStatus;
+  generated_at: string | null;
+  failed_file_count: number;
+  parse_failure_files: string[];
+  symbol?: McpSymbolRef;
+  callers: McpSymbolRef[];
+  callees: McpSymbolRef[];
+  error?: {
+    code: McpErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+  };
+}
+
+interface McpImpactResult {
+  status: McpToolStatus;
+  confidence: McpToolConfidence;
+  graph_status: McpGraphStatus;
+  generated_at: string | null;
+  failed_file_count: number;
+  parse_failure_files: string[];
+  root_symbol?: McpSymbolRef;
+  affected_symbols: Array<{
+    symbol: McpSymbolRef;
+    depth: number;
+    path: string[];
+  }>;
+  depth: number;
+  limit: number;
+  truncated: boolean;
+  error?: {
+    code: McpErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+  };
+}
+```
+
+### `codemap_query`
+
+输入：
+
+```typescript
+interface CodemapQueryInput {
+  symbol: string;
+  filePath?: string;
+}
+```
+
+语义：
+- `status = "ok"`：返回 `symbol`、`callers`、`callees`
+- `status = "unavailable"` + `GRAPH_NOT_FOUND`：还没生成 symbol-level 图
+- `status = "not_found"` + `SYMBOL_NOT_FOUND`：目标符号不存在
+- `status = "ambiguous"` + `AMBIGUOUS_EDGE`：同名符号无法仅靠 `symbol` / `filePath` 消歧
+
+### `codemap_impact`
+
+输入：
+
+```typescript
+interface CodemapImpactInput {
+  symbol: string;
+  filePath?: string;
+  depth?: number;
+  limit?: number;
+}
+```
+
+语义：
+- `affected_symbols` 按 caller impact 链返回，`path` 从 root symbol id 开始
+- `depth` / `limit` 会被收敛到首期限额，防止 host 挂起
+- `truncated = true` 说明结果已命中 `limit`
+
+### MCP 结果示例
+
+```json
+{
+  "status": "ok",
+  "confidence": "high",
+  "graph_status": "partial",
+  "generated_at": "2026-04-19T00:00:00.000Z",
+  "failed_file_count": 1,
+  "parse_failure_files": ["src/broken.ts"],
+  "symbol": {
+    "id": "sym-target",
+    "module_id": "mod-target",
+    "name": "target",
+    "kind": "function",
+    "visibility": "public",
+    "file_path": "src/target.ts",
+    "line": 1,
+    "column": 1,
+    "signature": "target() => void"
+  },
+  "callers": [
+    {
+      "id": "sym-caller",
+      "module_id": "mod-caller",
+      "name": "caller",
+      "kind": "function",
+      "visibility": "public",
+      "file_path": "src/caller.ts",
+      "line": 1,
+      "column": 1,
+      "signature": "caller() => void"
+    }
+  ],
+  "callees": []
+}
+```
+
+---
+
 ## query 命令输出结构
 
 ### JSON 输出 (-j)
@@ -211,6 +367,7 @@ interface AnalyzeOutput {
   };
   results: AnalyzeResult[];
   warnings?: AnalyzeWarning[];
+  diagnostics?: AnalyzeDiagnostics;
   analysis?: ReadAnalysis | LinkAnalysis | ShowAnalysis;
   metadata: {
     total: number;
@@ -219,13 +376,35 @@ interface AnalyzeOutput {
   };
 }
 
+interface AnalyzeDiagnostics {
+  status: "success" | "partialFailure" | "failure";
+  items: AnalyzeDiagnostic[];
+  failedTools?: string[];
+  degradedTools?: string[];
+}
+
+interface AnalyzeDiagnostic {
+  code: string;
+  severity: "info" | "warning" | "error";
+  message: string;
+  source: string;
+  recoverable: boolean;
+  details?: Record<string, unknown>;
+}
+
 interface AnalyzeWarning {
-  code: "deprecated-intent";
+  code:
+    | "deprecated-intent"
+    | "git-history-unavailable"
+    | "git-history-precompute-recommended"
+    | "git-history-stale"
+    | "git-history-unsupported-intent";
   severity: "warning";
   message: string;
-  deprecatedIntent: "impact" | "dependency" | "search" | "documentation" | "complexity" | "overview" | "reference";
-  replacementIntent: AnalyzeIntent;
-  sunsetPolicy: "2-minor-window";
+  details?: Record<string, string | number | boolean | null>;
+  deprecatedIntent?: "impact" | "dependency" | "search" | "documentation" | "complexity" | "overview" | "reference";
+  replacementIntent?: AnalyzeIntent;
+  sunsetPolicy?: "2-minor-window";
 }
 
 interface AnalyzeResult {
@@ -241,6 +420,15 @@ interface AnalyzeResult {
     testFile?: string;      // 关联的测试文件
     dependencies?: string[];
     impactCount?: number;
+    historyRisk?: {
+      status: "ok" | "ambiguous" | "not_found" | "unavailable";
+      level: "high" | "medium" | "low" | "unavailable";
+      confidence: "high" | "medium" | "low" | "unavailable";
+      freshness: "fresh" | "stale" | "expired" | "unknown";
+      score: number | null;
+      factors: string[];
+      analyzedAt: string | null;
+    };
     complexityMetrics?: {
       cyclomatic: number;
       cognitive: number;
@@ -269,6 +457,22 @@ interface ReadAnalysis {
     };
     risk: "high" | "medium" | "low";
   }>;
+  history?: Array<{
+    file: string;
+    status: "ok" | "ambiguous" | "not_found" | "unavailable";
+    confidence: "high" | "medium" | "low" | "unavailable";
+    freshness: "fresh" | "stale" | "expired" | "unknown";
+    source: "git-live" | "sqlite-materialized" | "sqlite-cache" | "unavailable";
+    scopeMode: "full" | "partial" | "top-files-only" | "precompute-required";
+    analyzedAt: string | null;
+    risk: {
+      level: "high" | "medium" | "low" | "unavailable";
+      score: number | null;
+      gravity: number | null;
+      impact: number | null;
+      factors: string[];
+    };
+  }>;
 }
 
 interface LinkAnalysis {
@@ -301,6 +505,13 @@ interface ShowAnalysis {
 }
 ```
 
+### analyze find failure semantics
+
+- `diagnostics.status = "success"` 且 `results=[]`：扫描链路可信完成，表示真实 0 命中。
+- `diagnostics.status = "partialFailure"`：主扫描退化，但配置感知 fallback 已返回可用结果；读取 `degradedTools[]` 和 `items[]`。
+- `diagnostics.status = "failure"`：主扫描与 fallback 都失败，不能把 `results=[]` 当作“代码不存在”；JSON/machine 模式会设置非零 exit code。
+- 通用查找默认仍推荐 `query -S "XXX" -j`；`analyze -i find -k "XXX" --json --structured` 用于需要统一 analyze schema 与 diagnostics 的 Agent 流程。
+
 ### 纯结构化输出 (--structured --json)
 
 移除了 `content` 字段，只保留结构化数据：
@@ -375,7 +586,16 @@ interface StructuredResult {
         "dependencies": [
           "src/orchestrator/intent-router.ts"
         ],
-        "riskLevel": "medium"
+        "riskLevel": "medium",
+        "historyRisk": {
+          "status": "ok",
+          "level": "high",
+          "confidence": "high",
+          "freshness": "fresh",
+          "score": 0.82,
+          "factors": ["recent bugfixes"],
+          "analyzedAt": "2026-04-15T00:00:00.000Z"
+        }
       }
     }
   ],
@@ -393,6 +613,24 @@ interface StructuredResult {
         "impactCount": 3,
         "risk": "medium"
       }
+    ],
+    "history": [
+      {
+        "file": "src/cli/commands/analyze.ts",
+        "status": "ok",
+        "confidence": "high",
+        "freshness": "fresh",
+        "source": "git-live",
+        "scopeMode": "full",
+        "analyzedAt": "2026-04-15T00:00:00.000Z",
+        "risk": {
+          "level": "high",
+          "score": 0.82,
+          "gravity": 0.6,
+          "impact": 0.8,
+          "factors": ["recent bugfixes"]
+        }
+      }
     ]
   },
   "metadata": {
@@ -425,7 +663,14 @@ type DesignContractDiagnosticCode =
   | "duplicate-section"
   | "empty-section"
   | "unknown-section"
-  | "ambiguous-heading";
+  | "ambiguous-heading"
+  | "invalid-frontmatter"
+  | "invalid-rules-root"
+  | "invalid-rule-type"
+  | "missing-rule-field"
+  | "invalid-rule-severity"
+  | "unknown-rule-field"
+  | "unknown-frontmatter-field";
 
 interface DesignValidateOutput {
   ok: boolean;
@@ -434,6 +679,11 @@ interface DesignValidateOutput {
   title?: string;
   missingRequiredSections: Array<"goal" | "constraints" | "acceptanceCriteria" | "nonGoals">;
   diagnostics: DesignContractDiagnostic[];
+  rules: Array<{
+    name: string;
+    type: "layer_direction" | "forbidden_imports" | "module_public_api_only";
+    severity: "error" | "warn";
+  }>;
   sections: Array<{
     id: DesignContractSectionId;
     title: string;
@@ -464,6 +714,7 @@ interface DesignContractDiagnostic {
   "missingRequiredSections": [
     "acceptanceCriteria"
   ],
+  "rules": [],
   "diagnostics": [
     {
       "code": "missing-section",
@@ -487,6 +738,225 @@ interface DesignContractDiagnostic {
 
 ---
 
+## check 命令输出结构
+
+### JSON 输出（默认）
+
+```typescript
+interface ContractCheckResult {
+  passed: boolean;
+  scan_mode: "full" | "diff";
+  contract_path: string;
+  against_path: string;
+  changed_files: string[];
+  scanned_files: string[];
+  warnings: Array<{
+    code: string;
+    message: string;
+    details?: Record<string, string | number | boolean | null>;
+  }>;
+  history?: {
+    status: "ok" | "ambiguous" | "not_found" | "unavailable";
+    confidence: "high" | "medium" | "low" | "unavailable";
+    freshness: "fresh" | "stale" | "expired" | "unknown";
+    scope_mode: "full" | "partial" | "top-files-only" | "precompute-required";
+    enriched_file_count: number;
+    unavailable_count: number;
+    stale_count: number;
+    low_confidence_count: number;
+    requires_precompute: boolean;
+  };
+  violations: Array<{
+    rule: string;
+    rule_type: "layer_direction" | "forbidden_imports" | "module_public_api_only" | "complexity_threshold";
+    severity: "error" | "warn";
+    location: string;
+    message: string;
+    dependency_chain: string[];
+    hard_fail: boolean;
+    diagnostic?: {
+      file?: string;
+      line?: number;
+      column?: number;
+      endLine?: number;
+      endColumn?: number;
+      scope: "line" | "file" | "general";
+      source: "dependency-cruiser" | "custom-evaluator";
+      category: "dependency" | "module_boundary" | "complexity";
+      degraded: boolean;
+    };
+    risk?: {
+      status: "ok" | "ambiguous" | "not_found" | "unavailable";
+      level: "high" | "medium" | "low" | "unavailable";
+      confidence: "high" | "medium" | "low" | "unavailable";
+      freshness: "fresh" | "stale" | "expired" | "unknown";
+      score: number | null;
+      factors: string[];
+      analyzed_at: string | null;
+    };
+  }>;
+  summary: {
+    total_violations: number;
+    error_count: number;
+    warn_count: number;
+    scanned_file_count: number;
+    rule_count: number;
+  };
+}
+```
+
+### 示例
+
+```json
+{
+  "passed": false,
+  "scan_mode": "diff",
+  "contract_path": "/repo/mycodemap.design.md",
+  "against_path": "src",
+  "changed_files": ["src/domain/index.ts"],
+  "scanned_files": ["src/app/use-domain.ts", "src/domain/index.ts"],
+  "warnings": [
+    {
+      "code": "hard-gate-window-exceeded",
+      "message": "changed files=11 超出 calibrated hard-gate window <=10",
+      "details": {
+        "calibrated": false,
+        "changed_files": 11,
+        "max_changed_files": 10,
+        "recommended_mode": "warn-only"
+      }
+    }
+  ],
+  "history": {
+    "status": "ok",
+    "confidence": "high",
+    "freshness": "fresh",
+    "scope_mode": "full",
+    "enriched_file_count": 1,
+    "unavailable_count": 0,
+    "stale_count": 0,
+    "low_confidence_count": 0,
+    "requires_precompute": false
+  },
+  "violations": [
+    {
+      "rule": "app 不可依赖 domain barrel",
+      "rule_type": "layer_direction",
+      "severity": "error",
+      "location": "src/app/use-domain.ts",
+      "message": "src/app/use-domain.ts 依赖 src/domain/index.ts，违反规则 app 不可依赖 domain barrel",
+      "dependency_chain": ["src/app/use-domain.ts", "src/domain/index.ts"],
+      "hard_fail": true,
+      "diagnostic": {
+        "file": "src/app/use-domain.ts",
+        "line": 3,
+        "column": 1,
+        "scope": "line",
+        "source": "dependency-cruiser",
+        "category": "dependency",
+        "degraded": false
+      },
+      "risk": {
+        "status": "ok",
+        "level": "high",
+        "confidence": "high",
+        "freshness": "fresh",
+        "score": 0.88,
+        "factors": ["recent bugfixes", "high blast radius"],
+        "analyzed_at": "2026-04-15T00:00:00.000Z"
+      }
+    }
+  ],
+  "summary": {
+    "total_violations": 1,
+    "error_count": 1,
+    "warn_count": 0,
+    "scanned_file_count": 2,
+    "rule_count": 1
+  }
+}
+```
+
+> `check` 默认就是纯 JSON；`--human` 只改变渲染，不改变底层 `ContractCheckResult` truth。
+> Git history risk 是 additive enrichment：它补充 `history` 与 `violations[].risk`，但不会改变 `severity:error` / exit 语义。history 不可用时应显式返回 `unavailable` / warning，而不是伪装成低风险。
+> CI-native truth：PR 默认 hard gate 仅在 calibration 通过且 `changed files <= 10` 时启用；若出现 `diff-scope-fallback`、`hard-gate-window-exceeded` 或 `false-positive rate >10%`，CI 必须回退 `warn-only / fallback`。校准命令：`node scripts/calibrate-contract-gate.mjs --max-changed-files 10 --max-false-positive-rate 0.10`
+
+### Annotation-friendly diagnostics
+
+```typescript
+interface ContractViolationDiagnostic {
+  file?: string;
+  line?: number;
+  column?: number;
+  endLine?: number;
+  endColumn?: number;
+  scope: "line" | "file" | "general";
+  source: "dependency-cruiser" | "custom-evaluator";
+  category: "dependency" | "module_boundary" | "complexity";
+  degraded: boolean;
+}
+
+type ContractGateRecommendation = "hard-gate-ok" | "warn-only" | "re-scope";
+
+interface GitLabContractAnnotation {
+  description: string;
+  check_name: string;
+  fingerprint: string;
+  severity: "major" | "minor";
+  location: {
+    path: string;
+    lines: {
+      begin: number;
+    };
+  };
+}
+```
+
+- `--annotation-format github` 会直接输出 GitHub Actions annotations；允许 file-scoped degraded diagnostics，但不会伪造不存在的行号。
+- `--annotation-format gitlab --annotation-file gl-code-quality-report.json` 会输出 GitLab Code Quality artifact；只包含 `scope="line"` 且有 `line` 的 diagnostics。
+- `recommended_mode` 是 CI 编排 truth：当 calibration 失败、`changed files <= 10` 条件不满足或 false-positive 漂移时，workflow 必须走 `warn-only / fallback`。
+
+---
+
+## history 命令输出结构
+
+### JSON 输出（默认）
+
+```typescript
+interface HistoryCommandResult {
+  query: string;
+  status: "ok" | "ambiguous" | "not_found" | "unavailable";
+  symbol: null | {
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+  };
+  candidates: Array<{
+    symbolId: string;
+    name: string;
+    file: string;
+    line: number;
+  }>;
+  files: string[];
+  warnings: string[];
+  risk: {
+    level: "high" | "medium" | "low" | "unavailable";
+    score: number | null;
+    riskFactors: string[];
+  };
+}
+```
+
+### 失败语义
+
+- `ok`: 找到唯一 symbol，并返回 timeline + risk
+- `ambiguous`: 找到多个候选 symbol，不自动合并
+- `not_found`: storage 中找不到 symbol
+- `unavailable`: Git history 不可用或无持久化快照
+
+---
+
 ## design map 命令输出结构
 
 ### JSON 输出 (--json)

package/docs/ai-guide/PATTERNS.md

@@ -170,6 +170,9 @@ node dist/cli/index.js ci check-headers
 # Step 3: 评估变更风险
 node dist/cli/index.js ci assess-risk
 
+# Step 3.5: 需要看某个符号为什么危险 / 最近谁改过时
+node dist/cli/index.js history --symbol createCheckCommand
+
 # Step 4: 检查输出契约（如果修改了 analyze）
 node dist/cli/index.js ci check-output-contract
 
@@ -180,6 +183,8 @@ node dist/cli/index.js ci check-docs-sync
 npm test
 ```
 
+> `ci assess-risk`、`check`、`history` 共用同一套 Git history risk truth；若历史不可用，输出会显式返回 `unavailable` / warning，而不是默默降成低风险。
+
 ---
 
 ### 模式 F: 复杂分析任务（analysis-only workflow）
@@ -201,6 +206,12 @@ node dist/cli/index.js design handoff mycodemap.design.md --json
 # Step 0.9: 基于 reviewed handoff truth 做 verification / drift 检查
 node dist/cli/index.js design verify mycodemap.design.md --json
 
+# Step 0.95: 先校准当前仓库是否还能默认 hard gate
+node scripts/calibrate-contract-gate.mjs --max-changed-files 10 --max-false-positive-rate 0.10
+
+# Step 0.97: 如果需要把 contract 变成 PR 门禁，显式输出 GitHub annotations
+node dist/cli/index.js check --contract mycodemap.design.md --against src --base origin/main --annotation-format github
+
 # Step 1: 启动工作流
 node dist/cli/index.js workflow start "实现用户认证模块"
 
@@ -227,11 +238,33 @@ node dist/cli/index.js workflow checkpoint
 3. `link` - 汇总依赖、引用与关联关系
 4. `show` - 生成概览、摘要与展示型结果
 
-> 说明：`workflow` 仍只保留 `find` / `read` / `link` / `show` 四阶段；如果任务由人类设计驱动，先走 `design validate → design map → design handoff → design verify` 固定输入、候选范围、review gate 与 drift 检查，再进入 workflow。
+> 说明：`workflow` 仍只保留 `find` / `read` / `link` / `show` 四阶段；如果任务由人类设计驱动，先走 `design validate → design map → design handoff → design verify` 固定输入、候选范围、review gate 与 drift 检查；若还需要执行仓库级代码门禁，先校准再显式运行 `check`。
+
+### 模式 G: CI-native contract gate
+
+**适用场景**: 需要把 `mycodemap.design.md` 真正接进 PR / CI，同时保持 annotation 可见且避免 noisy hard gate
+
+**执行步骤**:
+
+```bash
+# Step 1: 校准当前仓库的 hard-gate 窗口
+node scripts/calibrate-contract-gate.mjs --max-changed-files 10 --max-false-positive-rate 0.10
+
+# Step 2: 在 GitHub PR 中输出 annotation-friendly diagnostics
+node dist/cli/index.js check --contract mycodemap.design.md --against src --base origin/main --annotation-format github
+
+# Step 3: 如需 GitLab artifact，写出 line-scoped code-quality 报告
+node dist/cli/index.js check --contract mycodemap.design.md --against src --base origin/main --annotation-format gitlab --annotation-file gl-code-quality-report.json
+```
+
+**决策要点**:
+- PR 默认 hard gate 只在 calibration 通过且 `changed files <= 10` 时开启。
+- 超过窗口、出现 `diff-scope-fallback`，或 `false-positive rate >10%` 时必须显式退回 `warn-only / fallback`。
+- GitHub 允许 file-scoped degraded diagnostics；GitLab 只应输出 line-scoped diagnostics，不伪造行号。
 
 ---
 
-### 模式 G: 切换图存储后端
+### 模式 H: 切换图存储后端
 
 **适用场景**: 需要把 CodeGraph 从默认文件系统存储切到 KùzuDB，或验证 graph backend 是否真正生效
 
@@ -244,24 +277,21 @@ cat mycodemap.config.json
 # Step 2: 选择后端
 # {
 #   "storage": {
-#     "type": "kuzudb",
-#     "databasePath": ".codemap/kuzu"
+#     "type": "sqlite",
+#     "databasePath": ".codemap/governance.sqlite"
 #   }
 # }
 
-# Step 3: 如需 Kùzu 图数据库后端，安装可选依赖
-npm install kuzu
-
-# Step 4: 重新生成代码地图
+# Step 3: 重新生成代码地图
 node dist/cli/index.js generate
 
-# Step 5: 验证同一 backend 可被读取
+# Step 4: 验证同一 backend 可被读取
 node dist/cli/index.js export json -o /tmp/codemap.json
 ```
 
 **决策要点**:
-- 旧的 `neo4j` 配置现在应该直接报迁移错误；缺少 `kuzu` 时也应看到显式错误，而不是静默 fallback。
-- `storage.type = "auto"` 当前仍保守落到 `filesystem`，不要把阈值字段误读成已上线自动切换。
+- 旧的 `neo4j` / `kuzudb` 配置现在应该直接报迁移错误；显式 `sqlite` 但运行时不满足条件时也应看到显式错误，而不是静默 fallback。
+- `storage.type = "auto"` 当前优先落到 `sqlite`；只有 SQLite 不可用时才回退 `filesystem`，不要把阈值字段误读成更复杂的调度器。
 - 图存储生产化只收口存储面，不重新开放公共 HTTP API 产品面。
 
 ---