@mycodemap/mycodemap 0.5.0 → 0.5.2-beta.1

package/docs/ideation/2026-04-15-executable-architecture-constitution-ideation.md

@@ -0,0 +1,102 @@
+---
+date: 2026-04-15
+topic: executable-architecture-constitution
+focus: Pivot CodeMap to an "Executable Architecture Constitution" — making design.md a diff-aware, git-history-risk-weighted, CI-enforceable gate
+---
+
+# Ideation: Executable Architecture Constitution
+
+## Codebase Context
+
+**Project**: CodeMap — TypeScript CLI tool that generates structured code context for AI/Agents (dependency graphs, symbol maps, etc.). Currently pivoting from "AI code map tool" to "Executable Architecture Constitution" — an architecture contract governance engine.
+
+**Key Assets**:
+- MVP3 6-layer architecture is enforced (Interface → Infrastructure → Domain → Server → CLI)
+- `design validate/map/handoff/verify` commands already exist with full JSON output contracts
+- `docs/backlog.md` contains a v0.6 product重塑提案 to pivot to "architecture contract validation & guardrail system"
+- Historical CI gateway exists (`codemap ci check-commits`, `check-headers`, `assess-risk`) but some are archived
+- Git risk analyzer was designed and archived (GRAVITY/HEAT/IMPACT scoring formula exists in `src/orchestrator/workflow/git-analyzer.ts` but is dormant)
+- Storage is currently KùzuDB; proposal suggests migrating to `better-sqlite3` + in-memory directed graph
+- Tree-sitter parser exists for TS/Go/Python
+- Current `design verify` only checks handoff drift; it does NOT scan actual `src/` code against architecture rules
+
+**Pain Points**:
+- `src/core/` and `src/parser/` migration debt
+- Multiple temp output dirs
+- Docs-sync pressure
+- No diff-aware incremental validation exists yet
+
+## Ranked Ideas
+
+### 1. Diff-Aware Contract Enforcement
+**Description:** Upgrade `mycodemap verify` into a true contract enforcer that scans `src/` code. By default, only validate files touched by `git diff` and their dependency chains. Return non-zero exit codes when `layer_direction`, `forbidden_imports`, or `module_public_api_only` rules are violated.
+**Rationale:** This is the core product soul of the pivot. Today `design verify` only checks handoff drift and never touches source code — creating a dangerous false sense of security for users.
+**Downsides:** Bridging design.md's text constraints with tree-sitter symbol extraction requires careful engineering for the first rule.
+**Confidence:** 90%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 2. SQLite + In-Memory Graph Storage Migration
+**Description:** Remove the KùzuDB adapter and replace it with `better-sqlite3` for persisting symbol relationships, plus a lightweight in-memory directed graph (Map/Set adjacency list) loaded at startup. The same storage layer should handle code graphs, git blame history, and contract metadata.
+**Rationale:** KùzuDB installation failures are the top onboarding friction. SQLite's single-file nature turns CodeMap into a version-controllable CLI tool rather than a system requiring database ops.
+**Downsides:** Must validate startup time and memory footprint against large codebases (target: <1s for 10K files, <200MB RAM).
+**Confidence:** 85%
+**Complexity:** Medium-High
+**Status:** Unexplored
+
+### 3. Revive Git History Risk Scoring (GRAVITY/HEAT/IMPACT)
+**Description:** Harden the existing but dormant `calculateRiskScore` in `src/orchestrator/workflow/git-analyzer.ts` and rewire the GRAVITY/HEAT/IMPACT three-dimensional model into `verify` and `impact` outputs.
+**Rationale:** Competitors cannot replicate the causal narrative of "who changed this block, what regressions this dependency chain caused before." The formula is already designed — it just needs to be wired up.
+**Downsides:** Requires high-quality historical data (rollbacks, incident correlations); young codebases may have weak signal.
+**Confidence:** 80%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 4. Auto-Generate design.md from Existing Codebase
+**Description:** Instead of asking humans to write `design.md` from scratch, use the existing tree-sitter parser to scan `src/` for module boundaries and public APIs, then generate a baseline contract. Users only review and lock it.
+**Rationale:** Eliminates the root cause of "docs vs code divergence." If contract generation cost approaches zero, maintenance cost collapses too.
+**Downsides:** Auto-generated rules may be too permissive or capture too many implementation details; needs smart UX to "lock" which rules matter.
+**Confidence:** 75%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 5. Auto-Generate Architecture Remediation Patches
+**Description:** When `verify` finds a module boundary violation, don't just report it — generate a concrete refactoring patch (e.g., "move this import down to the adapter layer").
+**Rationale:** In the AI era, "errors without fixes" is a half-measure. This was also highlighted in Codex's second opinion as a core element of the coolest version.
+**Downsides:** Requires semantic understanding beyond import graphs; fully automated fixes risk introducing bugs.
+**Confidence:** 65%
+**Complexity:** High
+**Status:** Unexplored
+
+### 6. Self-Healing Design Contract (Drift Approval)
+**Description:** Allow `design.md` to evolve with the code through an approval workflow. When drift is detected, provide `codemap design evolve --approve` to snapshot current code boundaries back into the contract as the new baseline.
+**Rationale:** Architecture decay is an organizational norm. If contracts forever forbid drift, they get abandoned. A reviewable, approvable evolution mechanism is the only way they survive long-term.
+**Downsides:** Requires strict versioning and multi-level approval, otherwise it becomes a channel for "legitimizing tech debt."
+**Confidence:** 70%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 7. MCP `verify_contract` Tool
+**Description:** Wrap the `design verify` JSON output contract as an MCP Server tool for Claude Code / Cursor to call before every code modification.
+**Rationale:** Minimal engineering investment for maximum ecosystem leverage. Transforms CodeMap from "a CLI developers remember to run" into "infrastructure AI calls by default."
+**Downsides:** The MCP ecosystem is still early; interface standardization may shift.
+**Confidence:** 85%
+**Complexity:** Low
+**Status:** Unexplored
+
+## Rejection Summary
+
+| # | Idea | Reason Rejected |
+|---|------|-----------------|
+| 1 | Zero-config CI Gateway | Too narrow; essentially a packaging simplification of existing `ci` subcommands, not a strategic improvement |
+| 2 | Auto-sync docs guardrail | High engineering complexity for low leverage; contributes marginally to the pivot's core value |
+| 3 | Architecture-as-Test-Suite | Functionally duplicates #1 with a different shape (Vitest vs CLI); drifts from CodeMap's CLI-native identity |
+| 4 | GitHub Action as the only interface | Radical but too costly; conflicts with existing CLI investment and user base |
+| 5 | Risk-weighted soft gate | Historically explored; soft thresholds rarely change developer behavior in practice |
+| 6 | Commit message as architecture signal | Over-relies on LLM inference; high cost and unpredictable signal quality |
+| 7 | TypeScript-only deep constitution | Strategic but would discard existing Go/Python parser work; unclear cost/benefit |
+| 8 | One-shot removal of core/parser debt | A refactoring task, not a product improvement idea |
+
+## Session Log
+
+- 2026-04-15: Initial ideation — ~40 candidates generated across 4 frames, 7 survived after adversarial filtering

package/docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md

@@ -23,9 +23,48 @@
 - `Non-Goals` 不能为空；它是防止越界实现的第一道护栏。
 - 如果某个关键决策尚未确定，写进 `Open Questions`，不要让 AI 自行猜测。
 
+## Frontmatter Rules
+
+把可执行规则写在文件开头的 YAML frontmatter 中。当前 Phase 25 只支持三种规则：
+
+- `layer_direction`
+- `forbidden_imports`
+- `module_public_api_only`
+
+```yaml
+---
+rules:
+  - type: layer_direction
+    name: "core 不可依赖 cli"
+    from: "src/core/**"
+    to: "src/cli/**"
+    severity: error
+  - type: forbidden_imports
+    name: "parser 禁止直接引用 fs"
+    module: "src/infrastructure/parser/**"
+    forbidden:
+      - fs
+      - path
+    severity: warn
+  - type: module_public_api_only
+    name: "domain 模块对外仅暴露 index.ts"
+    module: "src/domain/**"
+    public_api: "index.ts"
+    severity: error
+---
+```
+
 ## Copy-Paste Template
 
 ```markdown
+---
+rules:
+  - type: layer_direction
+    name: "core 不可依赖 cli"
+    from: "src/core/**"
+    to: "src/cli/**"
+    severity: error
+---
 # Design Contract: <feature name>
 
 ## Goal
@@ -59,6 +98,14 @@
 ## Minimal Example
 
 ```markdown
+---
+rules:
+  - type: layer_direction
+    name: "core 不可依赖 cli"
+    from: "src/core/**"
+    to: "src/cli/**"
+    severity: error
+---
 # Design Contract: Add design validate command
 
 ## Goal

package/docs/product-specs/MVP3-ARCHITECTURE-COMPARISON.md

@@ -22,7 +22,7 @@
 |------|--------|----------------|
 | CLI | 多个命令直接碰核心实现 | 公共 CLI 收口为分析优先的命令面，命名边界清晰 |
 | Server Layer | 设计概念模糊，易与公共 `server` 命令混淆 | `src/server/` 保留为**内部架构层**；公共 `server` 命令已移除 |
-| Storage | 以文件输出为中心，图存储路径不稳定 | `filesystem` / `memory` / `kuzudb` / `auto` 为正式 surface；`neo4j` 已退出正式支持 |
+| Storage | 以文件输出为中心，图存储路径不稳定 | `filesystem` / `memory` / `sqlite` / `auto` 为正式 surface；`neo4j` 与 `kuzudb` 已退出正式支持 |
 | Parser | 以 TypeScript 逻辑为主，扩展能力弱 | `ParserRegistry` + `TypeScript/JavaScript`、`Go`、`Python` 三类已落地实现 |
 | Workflow | 设计上曾试图扩到更多工程阶段 | 当前公开能力仅保留 analysis-only：`find → read → link → show` |
 | Docs / CI | 文档与实现容易漂移 | `docs:check` + `ci check-docs-sync` + CI gateway 固定当前契约 |
@@ -68,7 +68,7 @@ Domain Layer (`src/domain/`)
   └─ 面向业务模型，不直接暴露 CLI 细节
 
 Infrastructure Layer (`src/infrastructure/`)
-  ├─ storage: FileSystem / Memory / KùzuDB
+  ├─ storage: FileSystem / SQLite / Memory
   ├─ parser: TypeScript(JS) / Go / Python
   └─ repositories / shared graph helpers
 
@@ -80,7 +80,7 @@ Interface Layer (`src/interface/`)
 ### 当前架构要点
 
 - `Server Layer` 是内部架构层，不等于公共 `mycodemap server`
-- 图存储正式产品面已收敛为 Kùzu-only 主线，不再把 `neo4j` 当成受支持 backend
+- 图存储正式产品面已收敛为 `filesystem` / `sqlite` / `memory` / `auto`；旧 `neo4j` / `kuzudb` 配置只保留迁移诊断
 - `workflow` 是公开能力，但仅编排分析阶段，不再混入实现/提交/CI 阶段
 
 ---
@@ -103,7 +103,7 @@ await fs.writeFile(path.join(outputDir, 'AI_MAP.md'), markdown);
 ### After：存储契约已稳定，但产品面已收敛
 
 ```typescript
-export type StorageType = 'filesystem' | 'kuzudb' | 'memory';
+export type StorageType = 'filesystem' | 'sqlite' | 'memory';
 
 export interface StorageConfig {
   type: StorageType | 'auto';
@@ -118,10 +118,11 @@ export interface StorageConfig {
 
 当前事实：
 
-- **正式支持**：`filesystem`、`memory`、`kuzudb`、`auto`
-- **不再正式支持**：`neo4j`
-- **迁移语义**：旧 `neo4j` 配置会返回显式错误，不会静默 fallback
-- **`auto` 现状**：配置面存在，但当前仍保守落到 `filesystem`；阈值字段是契约，不代表已完成智能切换
+- **正式支持**：`filesystem`、`memory`、`sqlite`、`auto`
+- **不再正式支持**：`neo4j`、`kuzudb`
+- **迁移语义**：旧 `neo4j` / `kuzudb` 配置会返回显式错误，不会静默 fallback
+- **`auto` 现状**：配置面存在，当前优先选择 `sqlite`；仅当 SQLite 运行时不可用时 warning 后回退 `filesystem`
+- **SQLite runtime**：显式 `sqlite` 需要 `better-sqlite3` + Node.js `>=20`；否则返回 `SQLITE_NOT_AVAILABLE`
 
 ---
 
@@ -209,7 +210,7 @@ mycodemap ci check-docs-sync
 | 能力 | 当前状态 |
 |------|----------|
 | `neo4j` 正式支持 | 已移除出正式产品面 |
-| 更丰富的自动后端切换启发式 | 仍 deferred；`auto` 当前保守落到 `filesystem` |
+| 更丰富的自动后端切换启发式 | 仍 deferred；`auto` 当前优先选择 `sqlite`，仅在 SQLite 不可用时回退 `filesystem` |
 | Java / Rust / C/C++ 等更多 parser 实现 | 接口预留，未作为当前 shipped reality |
 | `viz` / `tui` / CLI 可视化套件 | 未作为当前 public CLI 基线交付 |
 | 公共 HTTP API / `mycodemap server` 产品面 | 未开放；`Server Layer` 仍是 internal-only |
@@ -221,7 +222,7 @@ mycodemap ci check-docs-sync
 `MVP3` 的核心价值已经从“理想化设计图”收口成了当前可验证的产品基线：
 
 - 5 层架构已在目录结构与职责边界上落地
-- 存储面已稳定为 Kùzu-only 主线
+- 存储面已稳定为 `filesystem` / `sqlite` / `memory` / `auto` 四态 surface
 - 解析器已具备可扩展注册机制，并落地 3 类实现
 - 公共 CLI 已回到分析优先的可维护命令面
 - 文档、测试与 CI 已能共同约束这些边界

package/docs/product-specs/MVP3-ARCHITECTURE-REDESIGN-PRD.md

@@ -54,9 +54,9 @@ MVP3 重构的原始目的，是把 CodeMap 从“CLI 直接拼接分析逻辑
 |------|------|------|
 | `filesystem` | shipped | 默认、最稳定 |
 | `memory` | shipped | 测试/内存场景 |
-| `kuzudb` | shipped | 当前图存储主线 |
-| `auto` | shipped surface | 配置面存在，但当前仍保守落到 `filesystem` |
-| `neo4j` | removed | 不再是正式支持 backend；旧配置返回显式迁移错误 |
+| `sqlite` | shipped | 当前图存储主线 |
+| `auto` | shipped surface | 配置面存在，当前优先选择 `sqlite`；SQLite 不可用时回退 `filesystem` |
+| `neo4j` / `kuzudb` | removed | 不再是正式支持 backend；旧配置返回显式迁移错误 |
 
 ### 3.3 解析器能力
 
@@ -108,7 +108,7 @@ analyze / ci / workflow / export / ship
 | 需求 | 当前状态 |
 |------|----------|
 | 五层架构与命名边界稳定 | 已满足 |
-| Kùzu-only 图存储主线 | 已满足 |
+| SQLite 图存储主线 + 显式迁移诊断 | 已满足 |
 | 历史 `neo4j` 配置迁移诊断 | 已满足 |
 | 解析器注册机制与 3 类实现 | 已满足 |
 | `analyze` / `workflow` / `server` 边界收口 | 已满足 |
@@ -122,7 +122,7 @@ analyze / ci / workflow / export / ship
 | Java / Rust / C/C++ 等更多 parser 实现 | Deferred |
 | `viz` / `tui` / 更丰富 CLI 可视化 | Deferred |
 | 公共 HTTP API / `mycodemap server` 产品面 | Deferred |
-| 更深的 Kùzu-native 查询优化 | Deferred |
+| 更深的 SQLite / in-memory 协同查询优化 | Deferred |
 
 ### 4.3 明确不在当前基线内
 
@@ -170,8 +170,8 @@ analyze / ci / workflow / export / ship
 
 当前交付：
 
-- `filesystem` / `memory` / `kuzudb` / `auto` 为正式配置面
-- 旧 `neo4j` 配置会显式报错，不再静默 fallback
+- `filesystem` / `memory` / `sqlite` / `auto` 为正式配置面
+- 旧 `neo4j` / `kuzudb` 配置会显式报错，不再静默 fallback
 
 ---
 
@@ -194,7 +194,7 @@ analyze / ci / workflow / export / ship
 
 更准确的当前表达是：
 
-- Kùzu 路径已接入正式产品面
+- SQLite 路径已接入正式产品面；显式 `sqlite` 缺少 `better-sqlite3` 或 Node.js `<20` 时会返回 `SQLITE_NOT_AVAILABLE`
 - 更激进的 DB-native 查询优化属于后续候选项，而非 `v1.3` 既成事实
 
 ---
@@ -206,7 +206,7 @@ analyze / ci / workflow / export / ship
 | `v1.0` | AI-first 定位、公共 CLI 收口、analyze/workflow/ship/docs guardrail 基线 |
 | `v1.1` | 插件扩展点产品化 |
 | `v1.2` | 图数据库后端生产化 |
-| `v1.3` | Kùzu-only 收敛、高信号 debt 清偿、docs/CI 自动验证闭环 |
+| `v1.3` | SQLite 主线收口、高信号 debt 清偿、docs/CI 自动验证闭环 |
 
 ---
 
@@ -216,7 +216,7 @@ analyze / ci / workflow / export / ship
 |------|----------|----------|
 | 文档继续把历史设计写成当前现实 | 高信号风险 | 持续运行 `docs:check` 与 `ci check-docs-sync` |
 | `Server Layer` 与公共 `server` 命令再次混淆 | 高信号风险 | 在 README / AI docs / 架构文档统一措辞 |
-| `auto` 被误读为“已完成智能切换” | 中 | 文档明确写明当前仍保守落到 `filesystem` |
+| `auto` 被误读为“已完成智能切换” | 中 | 文档明确写明当前优先选择 `sqlite`，仅在 SQLite 不可用时回退 `filesystem` |
 | repo-wide lint warnings 演变成阻断项 | 中 | 单独开新 milestone 清理 warning baseline |
 
 ---

package/docs/product-specs/MVP3-ARCHITECTURE-REDESIGN-TECH-PRD.md

@@ -87,7 +87,7 @@ src/
 ### 4.1 当前类型契约
 
 ```typescript
-export type StorageType = 'filesystem' | 'kuzudb' | 'memory';
+export type StorageType = 'filesystem' | 'sqlite' | 'memory';
 
 export interface StorageConfig {
   type: StorageType | 'auto';
@@ -106,27 +106,31 @@ export interface StorageConfig {
 |------|------|----------|
 | `filesystem` | `FileSystemStorage` | shipped |
 | `memory` | `MemoryStorage` | shipped |
-| `kuzudb` | `KuzuDBStorage` | shipped |
-| `auto` | `StorageFactory.determineStorageType()` | shipped surface，但当前保守返回 `filesystem` |
+| `sqlite` | `SQLiteStorage` | shipped |
+| `auto` | `StorageFactory.determineStorageType()` | shipped surface，当前优先返回 `sqlite`，不可用时 warning 后回退 `filesystem` |
 
 ### 4.3 已移除的正式产品面
 
-`neo4j` 已不再是正式支持 backend。
+`neo4j` 与 `kuzudb` 已不再是正式支持 backend。
 
 当前技术语义：
 
 - 旧配置若出现 `neo4j`，`StorageFactory` 会抛出 `UNSUPPORTED_STORAGE_TYPE`
-- 文档和实现都不再承诺 Neo4j runtime surface
+- 旧配置若出现 `kuzudb`，`StorageFactory` 会抛出 `STORAGE_BACKEND_MIGRATED`
+- 显式选择 `sqlite` 且运行时缺少 `better-sqlite3` 或 Node.js `<20` 时，`StorageFactory` 会抛出 `SQLITE_NOT_AVAILABLE`
+- 文档和实现都不再承诺 Neo4j / Kùzu runtime surface
 
 ### 4.4 `auto` 的真实状态
 
-`autoThresholds` 仍保留在契约里，但当前 `StorageFactory` 的保守行为是：
+`autoThresholds` 仍保留在契约里，但当前 `StorageFactory` 的实际行为是：
 
 ```typescript
-const thresholds = config.autoThresholds ?? {
-  useGraphDBWhenFileCount: 1000,
-  useGraphDBWhenNodeCount: 10000,
-};
+const sqliteAvailable = await this.checkSQLiteAvailability();
+if (sqliteAvailable) {
+  return 'sqlite';
+}
+
+console.warn('[StorageFactory] SQLite unavailable, falling back to filesystem');
 
 return 'filesystem';
 ```
@@ -134,6 +138,7 @@ return 'filesystem';
 因此：
 
 - `auto` 是稳定配置面
+- `auto` 会先探测 SQLite runtime，可用时返回 `sqlite`，不可用时 warning 后回退 `filesystem`
 - 但“按规模自动切到图数据库”的更强启发式仍是未来候选，而不是当前完成能力
 
 ---
@@ -279,11 +284,11 @@ find → read → link → show
 
 | 项目 | 说明 |
 |------|------|
-| 更强的 auto storage heuristic | 当前仍保守返回 `filesystem` |
+| 更强的 auto storage heuristic | 当前仍只在 `sqlite` / `filesystem` 间切换，未按规模动态调度更多后端 |
 | 更多 parser 实现 | 接口预留，当前未交付 |
 | 公共 HTTP API 产品化 | 当前不在范围内 |
 | `viz` / `tui` / 更强交互可视化 | 当前不在公共 CLI 基线中 |
-| Kùzu-native 深度查询优化 | 后续候选，不属于 `v1.3` 已交付事实 |
+| 更深的 SQLite / in-memory 协同查询优化 | 后续候选，不属于 `v1.3` 已交付事实 |
 
 ---
 

package/docs/rules/README.md

@@ -1,16 +1,21 @@
-# docs/rules/
+# `docs/rules/` 速查索引
 
-本目录存放会直接影响开发与交付行为的规则文档。
+> 只保留会直接影响 agent / 人类开发行为的规则。每份文档都应短、可执行、可 grep。
 
-## 当前文件
+## 先读哪份文档
 
-- `engineering-with-codex-openai.md`：面向 agent 的工程原则与当前仓库 CLI / CI 护栏。
-- `testing.md`：测试框架、覆盖率、测试文件位置。
-- `validation.md`：构建、类型检查、lint、CI 验证顺序。
-- `deployment.md`：打包、发布前检查与发布边界。
+| 场景 | 文档 | 主命令 |
+|---|---|---|
+| 改 TypeScript / Python 实现，担心触发红线 | `code-quality-redlines.md` | `npm run typecheck` / `npm run lint` |
+| 改分层、依赖方向、模块边界 | `architecture-guardrails.md` | `node dist/cli/index.js deps -m "<module>"` |
+| 改测试、fixture、测试文件布局 | `testing.md` | `npm test` |
+| 改 hooks、CI、验证顺序、repo-local guardrail | `validation.md` | `npm run docs:check` / `python3 scripts/validate-rules.py code --report-only` |
+| 改 agent 执行协议、CLI/CI 工程护栏 | `engineering-with-codex-openai.md` | `node dist/cli/index.js ci check-docs-sync` |
+| 改发布/打包流程 | `deployment.md` | `npm run build` / `npm run validate-pack` |
+| 改发布前 checklist / 版本同步 | `pre-release-checklist.md` | `npm run docs:check:pre-release` |
 
-## 写作边界
+## 使用规则
 
-- 写“必须怎么做”，不写长篇设计推演。
-- 若规则来自代码事实，优先引用 `package.json`、`tsconfig.json`、CI 或 hooks。
-- 若规则变化会影响 agent 行为，应同步检查入口文档。
+- 入口文档先路由，再按需下钻；不要一次性读完整个 `docs/rules/`。
+- 若规则变化会影响 agent 行为，同步检查 `AGENTS.md`、`CLAUDE.md`、`AI_GUIDE.md` 与相关 `docs/ai-guide/*.md`。
+- 若规则来自代码事实，优先用 `package.json`、`.githooks/*`、`.github/workflows/*`、`scripts/*` 作为真相来源。