@mycodemap/mycodemap 0.4.0 → 0.4.2

package/docs/product-specs/README.md

@@ -5,7 +5,14 @@
 ## 当前状态
 
 - 截至 2026-03-15，历史重构需求草稿已归档到 `docs/archive/product-specs/`。
-- 当前活跃产品规格暂为空；若后续需要新规格，请基于当前实现事实重新整理。
+
+## 当前有效规格
+
+- `MVP3-ARCHITECTURE-COMPARISON.md`：把历史设计目标与 `v1.3` 已落地基线并列，防止把愿景误写成现实。
+- `MVP3-ARCHITECTURE-REDESIGN-PRD.md`：记录当前产品边界、Deferred 范围与用户价值。
+- `MVP3-ARCHITECTURE-REDESIGN-TECH-PRD.md`：记录当前技术基线、目录现实、护栏与迁移语义。
+
+> 以上 3 份规格目前都属于“已交付基线同步版”，不是新的待实施 roadmap。
 
 ## 应放内容
 

package/docs/rules/architecture-guardrails.md

@@ -35,7 +35,7 @@ CodeMap 采用 **MVP3 分层架构**，各层职责如下：
 ├─────────────────────────────────────────────────────────────┤
 │                   Infrastructure Layer                      │
 │  src/infrastructure/ - 技术实现细节                          │
-│  - storage/: FileSystemStorage, MemoryStorage, KuzuDBStorage, Neo4jStorage
+│  - storage/: FileSystemStorage, MemoryStorage, KuzuDBStorage
 │  - parser/: TypeScriptParser, GoParser, PythonParser, ParserRegistry
 │  - repositories/: CodeGraphRepositoryImpl（仓库接口实现）     │
 ├─────────────────────────────────────────────────────────────┤
@@ -180,7 +180,6 @@ src/
       FileSystemStorage.ts
       MemoryStorage.ts
       KuzuDBStorage.ts
-      Neo4jStorage.ts
       StorageFactory.ts
     parser/                # 解析器
       interfaces/

package/docs/rules/engineering-with-codex-openai.md

@@ -45,11 +45,16 @@
 - 仓库内调试与验证优先使用 `node dist/cli/index.js <command>`，因为当前真实 CLI 入口是 `dist/cli/index.js`。
 - 需求澄清、影响分析、引用定位优先走 `query`、`analyze`、`deps`、`impact`，不要直接全仓漫游。
 - 修改 `analyze`、`query`、`ci`、`workflow` 等高影响命令时，至少验证：
-  - `--help` 输出与文档示例一致；
-  - 受影响的真实子命令可以在当前仓库运行；
-  - 若涉及机器输出，`--output-mode machine --json` 仍保持纯 JSON 契约。
+  - `node dist/cli/index.js analyze --help` 与文档示例一致；
+  - `find` / `read` / `link` / `show` 中受影响的 public intent 可以在当前仓库运行；
+  - 若文档保留 legacy alias 说明，真实输出仍会返回 `warnings[]`；
+  - 若涉及机器输出，`--json` 与 `--structured --json` 仍保持纯 JSON 契约。
+- 修改 `README.md`、`AI_GUIDE.md`、`docs/ai-guide/OUTPUT.md`、`ARCHITECTURE.md` 这类入口文档时，必须明确区分“目标产品基线”和“当前 CLI 现实”，尤其是 `Server Layer` / `mycodemap server` 的命名边界。
+- 修改 `docs/product-specs/*` 现行规格时，必须同步 `docs/product-specs/README.md` 与 `scripts/validate-docs.js` 的高信号断言，避免规格正文和目录索引分叉。
 - 若改动会影响 agent 执行手册、README 示例、测试事实或入口路由，先执行 `npm run docs:check`。
-- 若希望通过统一 CLI 护栏入口执行同一检查，使用 `node dist/cli/index.js ci check-docs-sync`。
+- 若希望通过统一 CLI 护栏入口执行同一检查，使用 `node dist/cli/index.js ci check-docs-sync`；该命令会同时执行 docs guardrail 与 `sync-analyze-docs.js --check`。
+- `ci check-branch --allow` 支持 `*` 通配；在 CI / PR 环境中，分支识别会回退到 `GITHUB_HEAD_REF` / `GITHUB_REF_NAME`。
+- `generate`、`analyze` 与 `ci check-headers -d` 共享 `.gitignore` 感知文件发现模块；没有 `.gitignore` 时回退到统一默认 `exclude`。
 - 涉及发布边界时，再补 `npm run build` 与 `npm run validate-pack`；不要把本地临时产物当成发布事实。
 
 ## 5. 当前项目的 CI 护栏
@@ -59,7 +64,8 @@
   - 当变更涉及 README、`docs/`、CLI 入口、测试配置或 CI 配置时，`.githooks/pre-commit` 还会执行 `npm run docs:check`。
   - `.githooks/commit-msg` 会校验 `[TAG] scope: message` 格式与单次 commit 文件数量。
 - 服务端护栏：
-  - `.github/workflows/ci-gateway.yml` 会执行 `npm run docs:check`、`npm run typecheck`、`npm test`、`npm run build`，然后再通过 `node dist/cli/index.js ci ...` 执行 `check-docs-sync`、`check-commits`、`check-commit-size`、`check-headers`、`assess-risk`、`check-output-contract` 与 AI feed 同步检查。
+  - `.github/workflows/ci-gateway.yml` 会执行 `npm run docs:check`、`npm run typecheck`、`npm test`、`npm run build`，并通过 `node dist/cli/index.js ci ...` 执行 `check-docs-sync`（含 docs guardrail + analyze generated block）、`check-commits`、`check-commit-size`、`check-headers`、`assess-risk`、`check-output-contract` 与 AI feed 同步检查。
+  - `check-working-tree`、`check-branch`、`check-scripts` 作为共享发布前 gate checks，由本地 `ci` 命令提供，`ship` 的 CHECK 阶段直接复用它们。
   - `.github/workflows/publish.yml` 会在发布前执行 `npm test` 与 `npm run build`。
 - 仓库协议仍然禁止通过 `--no-verify`、关闭 hook、放宽阈值、删除检查项来"修复"问题。
 
@@ -89,7 +95,7 @@ AI 生成代码时，以下模式触发**硬性阻断**：
 │  src/cli/ - 命令行接口，注册命令、参数解析、用户交互          │
 ├─────────────────────────────────────────────────────────────┤
 │                      Server Layer                           │
-│  src/server/ - HTTP API 服务器，RESTful 端点，Handler 处理    │
+│  src/server/ - 内部 Server Layer / transport，Handler 处理    │
 ├─────────────────────────────────────────────────────────────┤
 │                       Domain Layer                          │
 │  src/domain/ - 核心业务逻辑，领域实体与服务                   │
@@ -100,7 +106,7 @@ AI 生成代码时，以下模式触发**硬性阻断**：
 ├─────────────────────────────────────────────────────────────┤
 │                   Infrastructure Layer                      │
 │  src/infrastructure/ - 技术实现细节                          │
-│  - storage/: FileSystemStorage, MemoryStorage, KuzuDBStorage, Neo4jStorage
+│  - storage/: FileSystemStorage, MemoryStorage, KuzuDBStorage
 │  - parser/: TypeScriptParser, GoParser, PythonParser, ParserRegistry
 │  - repositories/: CodeGraphRepositoryImpl                   │
 ├─────────────────────────────────────────────────────────────┤
@@ -155,7 +161,7 @@ import type { IStorage } from '../interface/types/storage'; // 正确：只依
 至少预演一个失败模式，而不是只验证 happy path。当前仓库已经出现过两类高信号风险：
 
 - 文档漂移：例如测试规则曾与真实 `vitest.config.ts` 不一致，导致 agent 按旧规则执行错误命令。
-- 文档检索盲区：当 `analyze documentation` 无法命中文档时，agent 需要立即回退到 `rg` / 直接读文件，并在适用时记录 CodeMap 缺陷，而不是假装"没问题"。
+- 文档检索盲区：当 `analyze -i show` 无法命中文档概览时，agent 需要立即回退到 `rg` / 直接读文件，并在适用时记录 CodeMap 缺陷，而不是假装"没问题"。
 
 ## 10. 最小交付清单（更新版 - Harness 规范）
 
@@ -177,7 +183,7 @@ import type { IStorage } from '../interface/types/storage'; // 正确：只依
 | 你的改动 | 必须更新的文档 |
 |---------|--------------|
 | 新增/修改 CLI 命令或参数 | `CLAUDE.md`、`docs/rules/engineering-with-codex-openai.md` |
-| 新增/修改配置项或 Schema | `README.md`、相关配置示例 |
+| 新增/修改配置项或 Schema | `README.md`、`docs/SETUP_GUIDE.md`、`docs/AI_ASSISTANT_SETUP.md`、相关配置示例 |
 | 修改类型定义/公共接口 | 接口注释、`docs/rules/` 中相关文档 |
 | 修改 CI/CD 流程 | `docs/rules/validation.md`、`.github/workflows/` |
 | 修改 Git Hooks | `docs/rules/validation.md` |

package/docs/rules/validation.md

@@ -4,9 +4,13 @@
 
 1. 先验证与你改动最相关的命令、测试或模块。
 2. 若改动影响 agent 路由、CLI 示例、规则文档或测试事实，先执行 `npm run docs:check`。
-3. 若改动同时影响 CLI 护栏入口，再补 `node dist/cli/index.js ci check-docs-sync`。
-4. 再扩大到 `npm run typecheck`、`npm run lint`、`npm test`。
-5. 涉及发布或打包时，再执行 `npm run build` 与 `npm run validate-pack`。
+3. 若改动同时影响 CLI 护栏入口，再补 `node dist/cli/index.js ci check-docs-sync`；该命令会串联 docs guardrail 与 analyze generated block 校验。
+4. 若改动涉及 `analyze` canonical 示例、选项表或 `AI_GUIDE.md` 速查模板，优先用 `node scripts/sync-analyze-docs.js --check` 直接定位 generated block 漂移。
+5. 若改动涉及产品定位、输出契约、共享文件发现规则或 `Server Layer` / `mycodemap server` 边界，确认 README、AI 文档、架构文档和 guardrail 脚本使用同一套措辞。
+6. 若改动涉及 `docs/product-specs/*` 的现行规格，确认 `docs/product-specs/README.md`、相关规格文档与 `scripts/validate-docs.js` 同步；当前 docs guardrail 会显式校验 MVP3 三份架构规格的 shipped baseline 表述。
+7. 若改动涉及 `mycodemap.config.json.storage` 或图数据库适配器，至少补跑对应 storage adapter 定点测试，并确认 `README.md`、`AI_GUIDE.md`、`docs/ai-guide/COMMANDS.md`、`docs/SETUP_GUIDE.md`、`mycodemap.config.schema.json` 与 guardrail 脚本同步。
+8. 再扩大到 `npm run typecheck`、`npm run lint`、`npm test`。
+9. 涉及发布或打包时，再执行 `npm run build` 与 `npm run validate-pack`。
 
 ## CI Gateway 验证流程
 
@@ -17,7 +21,9 @@ CI Gateway 已集成以下自动检查（按执行顺序）：
 3. `npm run lint` - ESLint 代码质量检查（渐进式规则，0 error 通过）
 4. `npm test` - 单元测试
 5. `npm run build` - 构建验证
-6. CLI 相关检查（commit 格式、文件头等）
+6. CLI 相关检查（当前 CI Gateway 直接执行 `check-docs-sync`、commit 格式、文件头、risk、output contract；`ship` 的本地 CHECK 阶段复用 `check-working-tree`、`check-branch`、`check-scripts`）
+
+> 当前 `check-docs-sync` 会串联 docs guardrail 与 analyze generated block 校验。
 
 ## 强约束
 
@@ -26,11 +32,27 @@ CI Gateway 已集成以下自动检查（按执行顺序）：
 - 涉及 CI / hooks / 输出契约时，必须给出失败场景与修复验证证据。
 - 严禁使用 `--no-verify`、禁用 hooks、删除检查项规避失败。
 
+## 典型失败模式
+
+- 入口文档改成 AI-first，但 `scripts/validate-docs.js` 仍检查旧措辞 → `npm run docs:check` 失败。
+- 把 `Server Layer` 和公共 `mycodemap server` 命令混写成同一件事 → 架构文档与命令文档发生边界漂移。
+- 手改 `README.md`、`docs/ai-guide/COMMANDS.md` 或 `AI_GUIDE.md` 的 `analyze` canonical 代码块 / 选项表 / 速查模板，却没同步 generated block → `node scripts/sync-analyze-docs.js --check` 失败。
+- 文档声称扫描类命令会尊重 `.gitignore`，但实现仍保留手写跳过规则 → `analyze` 与 `check-headers -d` 的文件集合漂移。
+- 把 `workflow` 重新扩回非分析阶段，却没同步 README / AI 命令文档 / guardrail 脚本 → `npm run docs:check` 失败。
+- `docs/product-specs/README.md` 仍写“当前活跃产品规格暂为空”，但目录里已经有现行规格 → 目录索引与规格正文自相矛盾。
+- MVP3 规格文档继续把历史设计愿景写成当前现实（例如把 `neo4j`、14 种语言或公共 `server` 产品面写回去）→ `npm run docs:check` 失败。
+- `config-loader` 已支持 `storage`，但 schema / README / AI 文档没同步 → 用户能写配置，编辑器和 guardrail 却仍把它当非法字段。
+- 旧的 `neo4j` 配置已经不受支持，但文档还把它写成正式 backend，或缺少 `kuzu` 时却被文档写成会自动 fallback → 现场排障方向错误，误判为实现 bug。
+
 ## 常用命令
 
 ```bash
 npm run docs:check
+node scripts/sync-analyze-docs.js --check
 node dist/cli/index.js ci check-docs-sync
+node dist/cli/index.js ci check-working-tree
+node dist/cli/index.js ci check-branch
+SHIP_IN_CI=1 node dist/cli/index.js ci check-scripts
 npm run typecheck
 npm test
 npm run lint

package/mycodemap.config.schema.json

@@ -5,18 +5,22 @@
   "description": "Configuration schema for MyCodeMap CLI tool",
   "type": "object",
   "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for editor tooling"
+    },
     "mode": {
       "type": "string",
-      "enum": ["fast", "smart"],
-      "default": "fast",
-      "description": "Parsing mode: fast (regex-based) or smart (TypeScript AST)"
+      "enum": ["fast", "smart", "hybrid"],
+      "default": "hybrid",
+      "description": "Parsing mode: fast (regex-based), smart (TypeScript AST), or hybrid (auto-select)"
     },
     "include": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "default": ["src/**/*"],
+      "default": ["src/**/*.ts"],
       "description": "Glob patterns to include"
     },
     "exclude": {
@@ -24,7 +28,7 @@
       "items": {
         "type": "string"
       },
-      "default": ["node_modules/**", "dist/**", "**/*.test.ts", "**/*.spec.ts"],
+      "default": ["node_modules/**", "dist/**", "build/**", "coverage/**", "**/*.test.ts", "**/*.spec.ts", "**/*.d.ts"],
       "description": "Glob patterns to exclude"
     },
     "output": {
@@ -36,6 +40,73 @@
       "type": "boolean",
       "default": false,
       "description": "Enable watch mode for file changes"
+    },
+    "storage": {
+      "type": "object",
+      "description": "Graph storage backend configuration",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["filesystem", "kuzudb", "memory", "auto"],
+          "default": "filesystem",
+          "description": "Storage backend type (Neo4j is no longer supported)"
+        },
+        "outputPath": {
+          "type": "string",
+          "default": ".codemap/storage",
+          "description": "Filesystem storage directory"
+        },
+        "databasePath": {
+          "type": "string",
+          "description": "KùzuDB database directory relative to project root"
+        },
+        "autoThresholds": {
+          "type": "object",
+          "description": "Thresholds for auto backend selection",
+          "properties": {
+            "useGraphDBWhenFileCount": {
+              "type": "number",
+              "description": "Prefer graph DB when file count reaches this threshold"
+            },
+            "useGraphDBWhenNodeCount": {
+              "type": "number",
+              "description": "Prefer graph DB when graph node count reaches this threshold"
+            }
+          },
+          "required": ["useGraphDBWhenFileCount", "useGraphDBWhenNodeCount"],
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "plugins": {
+      "type": "object",
+      "description": "Plugin loading options",
+      "properties": {
+        "builtInPlugins": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable built-in plugins"
+        },
+        "pluginDir": {
+          "type": "string",
+          "description": "Additional plugin directory"
+        },
+        "plugins": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Named plugins to load explicitly"
+        },
+        "debug": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable plugin debug logging"
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycodemap/mycodemap",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "TypeScript 代码地图工具 - 为 AI 辅助开发提供结构化上下文",
   "repository": {
     "type": "git",

package/scripts/pre-release-check.js

@@ -94,9 +94,19 @@ function getFileSize(filePath) {
 }
 
 function extractVersionFromText(content) {
-  // 匹配 "version: x.x.x" 或 "版本: x.x.x" 或 "Version x.x.x"
-  const match = content.match(/(?:version|版本)[:\s]+v?(\d+\.\d+\.\d+)/i);
-  return match ? match[1] : null;
+  const patterns = [
+    /(?:version|版本)[:\s]+v?(\d+\.\d+\.\d+(?:-[\w.]+)?)/i,
+    /"version"\s*:\s*"(\d+\.\d+\.\d+(?:-[\w.]+)?)"/i
+  ];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match) {
+      return match[1];
+    }
+  }
+
+  return null;
 }
 
 function extractVersionFromYAML(content) {
@@ -238,6 +248,11 @@ async function checkVersionConsistency(failures) {
       versions[file] = version;
       console.log(`  📄 ${file}: v${version}`);
     } else {
+      failures.push({
+        type: 'missing_version_in_file',
+        file,
+        message: `${file} 中未找到可解析的版本号`,
+      });
       console.log(yellow(`  ⚠️  ${file}: 未找到版本号`));
     }
   }
@@ -655,7 +670,10 @@ async function runPreReleaseChecks() {
     f.type === 'missing_required_file' ||
     f.type === 'missing_llms_txt' ||
     f.type === 'version_mismatch' ||
+    f.type === 'missing_version_in_file' ||
+    f.type === 'invalid_semver' ||
     f.type === 'llms_txt_standard_violation' ||
+    f.type === 'changelog_not_synced' ||
     f.type === 'missing_release_file'
   );