@mycodemap/mycodemap 0.4.2 → 0.5.1

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）
@@ -189,13 +194,31 @@ npm test
 **执行步骤**:
 
 ```bash
+# Step 0: 如果任务来自人类设计，先校验 design contract
+node dist/cli/index.js design validate mycodemap.design.md --json
+
+# Step 0.5: 把 design contract 映射成 candidate code scope
+node dist/cli/index.js design map mycodemap.design.md --json
+
+# Step 0.75: 生成 reviewer / agent 共用的 handoff package
+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 "实现用户认证模块"
 
 # Step 2: 查看当前阶段建议
 node dist/cli/index.js workflow status
 
-# Step 3: 执行当前阶段的分析和实现
+# Step 3: 执行当前阶段的分析（实现/提交/CI 不在 workflow phase 内）
 
 # Step 4: 完成阶段后推进
 node dist/cli/index.js workflow proceed
@@ -214,14 +237,34 @@ node dist/cli/index.js workflow checkpoint
 2. `read` - 阅读影响范围、复杂度与上下文
 3. `link` - 汇总依赖、引用与关联关系
 4. `show` - 生成概览、摘要与展示型结果
-5. `commit` - 提交验证
-6. `ci` - CI 验证
 
-> 说明：以上是当前公开实现，不代表最终收敛模型；如果只需要代码地图能力，优先使用前面几个核心分析模式。
+> 说明：`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 是否真正生效
 
@@ -234,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 产品面。
 
 ---

package/docs/ai-guide/PROMPTS.md

@@ -340,32 +340,43 @@
 
 请执行以下步骤：
 
-1. **相关代码搜索**
+1. **先把设计写成可验证输入**
+   ```bash
+   cp docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md mycodemap.design.md
+   node dist/cli/index.js design validate mycodemap.design.md --json
+   ```
+
+2. **如果这是架构边界类需求，先跑 contract gate**
+   ```bash
+   node dist/cli/index.js check --contract mycodemap.design.md --against src
+   ```
+
+3. **相关代码搜索**
    ```bash
    node dist/cli/index.js analyze -i find -k "{{RELATED_KEYWORD}}" --topK 10 --json
    ```
 
-2. **参考现有实现**
+4. **参考现有实现**
    分析类似功能的实现方式
 
-3. **确定实现位置**
+5. **确定实现位置**
    ```bash
    node dist/cli/index.js analyze -i read -t "候选目录" --json
    ```
    选择复杂度最低的模块
 
-4. **影响分析**（如果需要修改现有代码）
+6. **影响分析**（如果需要修改现有代码）
    ```bash
    node dist/cli/index.js analyze -i read -t "目标文件" --json
    ```
 
-5. **实现步骤**
+7. **实现步骤**
    - [ ] 创建新文件（添加 [META] [WHY] 头）
    - [ ] 实现核心功能
    - [ ] 添加单元测试
    - [ ] 运行测试验证
 
-6. **验证**
+8. **验证**
    ```bash
    node dist/cli/index.js ci check-headers -f "新文件.ts"
    npm test

package/docs/archive/test-report-symbol-search.md

@@ -0,0 +1,384 @@
+# CodeMap 符号搜索对比测试报告
+
+## 测试概述
+
+**测试目标**: 对比 `codemap query -s/-S` 与 `grep/rg` 在搜索代码符号时的差异
+
+**测试环境**: /data/codemap 目录
+
+**测试时间**: 2026-03-02
+
+---
+
+## 测试场景1: 精确搜索符号 "ModuleInfo"
+
+### 测试目的
+搜索项目中广泛使用的类型名称 "ModuleInfo"，对比各工具的精确匹配能力。
+
+### CodeMap 执行
+```bash
+npx codemap query -s "ModuleInfo"
+```
+
+**输出:**
+```
+🔍 查询 "ModuleInfo" (symbol)
+   找到 5 个结果
+
+   moduleInfo
+      类型: variable
+      路径: /data/codemap/src/core/analyzer.ts
+      定义于 src/core/analyzer.ts:55
+
+   moduleInfo
+      类型: variable
+      路径: /data/codemap/src/core/analyzer.ts
+      定义于 src/core/analyzer.ts:63
+
+   moduleInfo
+      类型: variable
+      路径: /data/codemap/src/core/analyzer.ts
+      定义于 src/core/analyzer.ts:76
+
+   ModuleInfo
+      类型: interface
+      路径: /data/codemap/src/types/index.ts
+      导出于 src/types/index.ts
+
+   ModuleInfo
+      类型: interface
+      路径: /data/codemap/src/types/index.ts
+      定义于 src/types/index.ts:154
+```
+
+**执行时间**: 0.538s (real)
+
+### rg 执行
+```bash
+rg -n "ModuleInfo" src/
+```
+
+**输出:** (共找到 82 处匹配，以下为部分示例)
+```
+src/parser/index.ts:8:import type { ModuleInfo, ImportInfo, ExportInfo, ModuleSymbol, SymbolKind, DecoratorInfo } from '../types/index.js';
+src/parser/index.ts:60:export async function parseFile(filePath: string): Promise<ModuleInfo> {
+src/core/analyzer.ts:5:import type { CodeMap, AnalysisOptions, ModuleInfo, DependencyGraph, ProjectInfo, ProjectSummary } from '../types/index.js';
+src/core/analyzer.ts:43:  const modules: ModuleInfo[] = [];
+src/types/index.ts:154:export interface ModuleInfo {
+src/cache/index.ts:10:import type { ModuleInfo } from '../types/index.js';
+...
+```
+
+**执行时间**: 0.008s (real)
+
+### grep 执行
+```bash
+grep -rn "ModuleInfo" src/
+```
+
+**输出:** (与 rg 类似，共 82 处匹配)
+
+**执行时间**: 0.003s (real)
+
+### 对比分析
+
+| 维度 | CodeMap | rg | grep |
+|------|---------|-----|------|
+| **速度** | 0.538s | 0.008s | 0.003s |
+| **结果数量** | 5 个符号定义 | 82 处匹配 | 82 处匹配 |
+| **准确性** | 仅返回符号定义和导出 | 返回所有文本匹配 | 返回所有文本匹配 |
+| **符号类型识别** | ✅ 是 (interface, variable) | ❌ 否 | ❌ 否 |
+| **导出信息** | ✅ 显示导出位置 | ❌ 否 | ❌ 否 |
+| **可读性** | 结构化，带类型标签 | 纯文本行 | 纯文本行 |
+
+### 发现的问题
+
+1. **CodeMap 速度较慢**: CodeMap 比 rg 慢约 67 倍，比 grep 慢约 179 倍
+2. **CodeMap 结果不完整**: CodeMap 只返回 5 个结果，而 rg/grep 返回 82 处匹配
+3. **CodeMap 区分大小写问题**: 搜索 "ModuleInfo" 时，变量名 "moduleInfo"（小写）也被返回，但可能并非用户期望的精确匹配
+4. **rg/grep 缺乏语义**: 无法区分类型定义、变量声明和普通文本引用
+
+---
+
+## 测试场景2: 模糊搜索 "cache"
+
+### 测试目的
+使用模糊搜索查找与 "cache" 相关的符号，对比各工具的模糊匹配能力。
+
+### CodeMap 执行
+```bash
+npx codemap query -S "cache"
+```
+
+**输出:**
+```
+🔍 查询 "cache" (search)
+   找到 20 个结果
+
+   cached
+      类型: variable
+      路径: /data/codemap/src/ai/factory.ts
+      定义于 src/ai/factory.ts:25
+
+   clearCache
+      类型: method
+      路径: /data/codemap/src/ai/factory.ts
+      定义于 src/ai/factory.ts:95
+
+   src/cache/file-hash-cache.ts
+      类型: module
+      路径: /data/codemap/src/cache/file-hash-cache.ts
+      模块匹配
+
+   FileHashCache
+      类型: export (class)
+      路径: /data/codemap/src/cache/file-hash-cache.ts
+      导出于 src/cache/file-hash-cache.ts
+
+   generateCacheKey
+      类型: export (function)
+      路径: /data/codemap/src/cache/file-hash-cache.ts
+      导出于 src/cache/file-hash-cache.ts
+
+   parseCacheKey
+      类型: export (function)
+      路径: /data/codemap/src/cache/file-hash-cache.ts
+      导出于 src/cache/file-hash-cache.ts
+
+   FileHashCache
+      类型: class
+      路径: /data/codemap/src/cache/file-hash-cache.ts
+      定义于 src/cache/file-hash-cache.ts:66
+
+   ... (共20个结果)
+```
+
+**执行时间**: 0.642s (real)
+
+### rg 执行
+```bash
+rg -n "cache" src/ -i
+```
+
+**输出:** (共找到约 300+ 处匹配，以下为部分)
+```
+src/cache/file-hash-cache.ts:2:// File Hash Cache - 文件哈希缓存
+src/cache/file-hash-cache.ts:66:export class FileHashCache {
+src/cache/file-hash-cache.ts:67:  private hashCache = new Map<string, { hash: string; mtime: number }>();
+src/cache/lru-cache.ts:2:// LRU Cache Implementation - 最近最少使用缓存
+src/cache/lru-cache.ts:9:export class LRUCache<K, V> {
+src/cache/index.ts:2:// Cache Module - 缓存系统入口
+...
+```
+
+**执行时间**: 0.007s (real)
+
+### 对比分析
+
+| 维度 | CodeMap (-S) | rg (-i) |
+|------|--------------|---------|
+| **速度** | 0.642s | 0.007s |
+| **结果数量** | 20 个符号 | 300+ 处文本匹配 |
+| **匹配模式** | 符号级模糊匹配 | 文本级正则匹配 |
+| **信息类型** | 符号定义、导出、模块 | 所有文本行 |
+| **去重** | ✅ 符号去重 (如 FileHashCache 类只出现一次定义) | ❌ 每行都显示 |
+| **可读性** | 结构化，带类型信息 | 纯文本，含代码上下文 |
+
+### 发现的问题
+
+1. **CodeMap 模糊搜索速度慢**: 比 rg 慢约 91 倍
+2. **CodeMap 结果数量受限**: 仅返回 20 个结果，而 rg 返回 300+ 处
+3. **CodeMap 不显示引用位置**: 只显示定义位置，不显示使用位置
+4. **rg 结果噪音大**: 返回所有包含 "cache" 文本的行，包括注释、字符串、变量名等
+
+---
+
+## 测试场景3: 搜索类/接口定义 "Analyzer"
+
+### 测试目的
+搜索类或接口定义，对比各工具的类型识别能力。
+
+### CodeMap 执行
+```bash
+npx codemap query -s "Analyzer"
+```
+
+**输出:**
+```
+🔍 查询 "Analyzer" (symbol)
+   找到 1 个结果
+
+   analyzer
+      类型: variable
+      路径: /data/codemap/src/orchestrator/__tests__/git-analyzer.test.ts
+      定义于 src/orchestrator/__tests__/git-analyzer.test.ts:27
+```
+
+**执行时间**: 0.515s (real)
+
+### rg 执行 (类/接口定义模式)
+```bash
+rg -n "class Analyzer|interface Analyzer" src/
+```
+
+**输出:**
+```
+(无匹配，退出码 1)
+```
+
+**执行时间**: 0.009s (real)
+
+### rg 执行 (扩展搜索)
+```bash
+rg -n "Analyzer" src/ | head -30
+```
+
+**输出:**
+```
+src/cli/commands/ci.ts:9:import { GitAnalyzer } from '../../orchestrator/git-analyzer.js';
+src/orchestrator/git-analyzer.ts:118: * GitAnalyzer 类
+src/orchestrator/git-analyzer.ts:121:export class GitAnalyzer {
+src/plugins/built-in/complexity-analyzer.ts:96:class ComplexityAnalyzerPlugin implements CodeMapPlugin {
+src/orchestrator/index.ts:53:  GitAnalyzer,
+...
+```
+
+### grep 执行
+```bash
+grep -rn "Analyzer" src/ | head -30
+```
+
+**输出:** (与 rg 类似)
+
+### 对比分析
+
+| 维度 | CodeMap | rg (class/interface) | rg (extended) |
+|------|---------|---------------------|---------------|
+| **速度** | 0.515s | 0.009s | 0.010s |
+| **结果** | 1 个变量 | 0 个 | 约 50+ 处 |
+| **类型过滤** | ❌ 未正确过滤 | ✅ 精确匹配模式 | ❌ 无过滤 |
+| **大小写敏感** | ❌ 不敏感 ("analyzer" 匹配 "Analyzer") | ✅ 敏感 | ✅ 敏感 |
+
+### 发现的问题
+
+1. **CodeMap 搜索 "Analyzer" 未找到 GitAnalyzer 类**: 这是严重问题！项目中存在 `GitAnalyzer` 类和 `ComplexityAnalyzerPlugin` 类，但 CodeMap 只找到一个测试文件中的变量 `analyzer`。
+2. **CodeMap 大小写不敏感问题**: 搜索 "Analyzer" 却匹配了 "analyzer" (小写变量名)。
+3. **rg 精确模式有效但过于严格**: `class Analyzer|interface Analyzer` 精确模式没有匹配到 `class GitAnalyzer` (因为类名是 GitAnalyzer 不是 Analyzer)。
+4. **CodeMap 缺少子串匹配**: CodeMap 似乎未将 "GitAnalyzer" 中的 "Analyzer" 子串作为匹配结果。
+
+---
+
+## 综合分析
+
+### 速度对比
+
+| 工具 | Test1 (ModuleInfo) | Test2 (cache) | Test3 (Analyzer) | 平均 |
+|------|-------------------|---------------|------------------|------|
+| CodeMap | 0.538s | 0.642s | 0.515s | **0.565s** |
+| rg | 0.008s | 0.007s | 0.010s | **0.008s** |
+| grep | 0.003s | - | - | **0.003s** |
+
+**结论**: CodeMap 比 rg 慢约 70 倍，比 grep 慢约 188 倍。
+
+### 准确性对比
+
+| 场景 | CodeMap | rg/grep |
+|------|---------|---------|
+| 精确搜索 | ⚠️ 仅返回定义，遗漏大量引用 | ✅ 返回所有文本匹配 |
+| 模糊搜索 | ✅ 返回相关符号，结构化 | ⚠️ 返回所有文本，噪音大 |
+| 类型搜索 | ❌ 严重遗漏 (未找到 GitAnalyzer) | ⚠️ 需要复杂正则 |
+
+### 信息丰富度对比
+
+| 信息类型 | CodeMap | rg | grep |
+|---------|---------|-----|------|
+| 符号类型 | ✅ | ❌ | ❌ |
+| 导出信息 | ✅ | ❌ | ❌ |
+| 文件路径 | ✅ | ✅ | ✅ |
+| 行号 | ✅ | ✅ | ✅ |
+| 代码上下文 | ❌ | ✅ | ✅ |
+| 依赖关系 | ❌ | ❌ | ❌ |
+
+### 易用性对比
+
+| 维度 | CodeMap | rg | grep |
+|------|---------|-----|------|
+| 命令简洁度 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
+| 输出可读性 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
+| 学习曲线 | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
+| 无需索引 | ❌ | ✅ | ✅ |
+
+---
+
+## 发现的关键问题
+
+### 🔴 严重问题
+
+1. **符号搜索遗漏严重**: CodeMap 在搜索 "Analyzer" 时完全遗漏了 `GitAnalyzer` 类和 `ComplexityAnalyzerPlugin` 类，只找到一个不相关的变量。
+   - 检查 codemap.json 发现 GitAnalyzer 存在于索引中（多处）
+   - 可能是搜索算法未正确处理子串匹配或类名前缀
+
+2. **大小写处理不一致**: 
+   - 搜索 "ModuleInfo" 返回了 "moduleInfo" (小写变量)
+   - 搜索 "Analyzer" 返回了 "analyzer" (小写变量)
+   - 但搜索 "cache" 却正确区分了大小写变体
+
+### 🟡 中等问题
+
+3. **速度性能差**: CodeMap 比传统工具慢 70-180 倍，对于大型项目可能无法接受。
+
+4. **结果数量有限**: 模糊搜索仅返回 20 个结果，可能遗漏重要符号。
+
+### 🟢 轻微问题
+
+5. **缺少引用信息**: CodeMap 只返回定义位置，不显示符号在哪里被使用。
+
+6. **无代码上下文**: 不像 rg/grep 那样显示匹配的代码行。
+
+---
+
+## 建议
+
+### 对 CodeMap 的改进建议
+
+1. **修复搜索算法**: 
+   - 确保子串匹配正常工作（如 "Analyzer" 应匹配 "GitAnalyzer"）
+   - 检查符号索引的查询逻辑
+
+2. **优化性能**: 
+   - 使用更高效的数据结构（如 Trie 树）进行符号查找
+   - 考虑使用 SQLite 或嵌入式数据库加速查询
+
+3. **增强搜索选项**:
+   - 添加 `--case-sensitive` 和 `--case-insensitive` 选项
+   - 添加 `--include-references` 选项显示符号引用位置
+   - 添加 `-n/--limit` 选项控制结果数量
+
+4. **显示代码上下文**:
+   - 添加选项显示匹配行的代码片段
+
+### 使用建议
+
+| 场景 | 推荐工具 | 原因 |
+|------|---------|------|
+| 快速查找文本 | rg/grep | 速度快，无需索引 |
+| 查找符号定义 | CodeMap | 结构化输出，带类型信息 |
+| 理解代码结构 | CodeMap | 显示导出和模块关系 |
+| 查找类/接口定义 | rg + 正则 | CodeMap 当前有遗漏问题 |
+| 模糊探索代码库 | CodeMap | 符号级模糊匹配减少噪音 |
+
+---
+
+## 附录: 测试原始数据
+
+### CodeMap 索引统计
+- 总文件数: 104
+- 总行数: 28,878
+- 总模块数: 104
+- 总导出: 378
+- 总类型: 70
+
+### 发现的符号
+- `ModuleInfo` 接口定义于: src/types/index.ts:154
+- `GitAnalyzer` 类定义于: src/orchestrator/git-analyzer.ts:121
+- `ComplexityAnalyzerPlugin` 类定义于: src/plugins/built-in/complexity-analyzer.ts:96