@mycodemap/mycodemap 0.1.0 → 0.2.0

package/docs/exec-plans/completed/2026-03-03-deps-path-extension-fix.md

@@ -0,0 +1,186 @@
+# 依赖路径扩展名修复计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 修复 `codemap deps` 命令显示 `.js` 扩展名而非源代码 `.ts` 扩展名的问题
+
+**Architecture:** 在 fast-parser 中添加路径规范化逻辑，将构建路径转换为源代码路径
+
+**Tech Stack:** TypeScript, Node.js, 正则表达式
+
+---
+
+## 问题分析
+
+当前 `codemap deps` 输出示例：
+```
+⬇️  直接依赖 (dependencies):
+   • ../types/index.js [source]
+   • ./interfaces/IParser.js [source]
+```
+
+期望输出：
+```
+⬇️  直接依赖 (dependencies):
+   • ../types/index.ts [source]
+   • ./interfaces/IParser.ts [source]
+```
+
+**根源位置:** `src/parser/implementations/fast-parser.ts:141`
+- 直接使用 import 语句中的原始路径
+- 未将 `.js` 后缀转换为 `.ts` 后缀
+
+---
+
+## 任务 1: 添加路径规范化函数
+
+**Files:**
+- Modify: `src/parser/implementations/fast-parser.ts`
+
+**Step 1: 添加规范化函数**
+
+在 `fast-parser.ts` 文件末尾添加路径规范化函数：
+
+```typescript
+/**
+ * 将构建路径转换为源代码路径
+ * 例如: ../types/index.js -> ../types/index.ts
+ */
+function normalizeSourcePath(depPath: string): string {
+  // 已经是 .ts 或 .tsx 的不需要转换
+  if (depPath.endsWith('.ts') || depPath.endsWith('.tsx')) {
+    return depPath;
+  }
+
+  // 替换 .js/.jsx 后缀为 .ts/.tsx
+  return depPath.replace(/\.js$/i, '.ts').replace(/\.jsx$/i, '.tsx');
+}
+```
+
+**Step 2: 在 extractImportsSimple 中使用**
+
+找到第 140-145 行，修改 import 路径处理：
+
+```typescript
+// 原代码
+imports.push({
+  source: match[4],  // <-- 直接使用原始路径
+  sourceType: match[4].startsWith('.') ? 'relative' : 'alias',
+  specifiers: specifiers.map(s => ({ name: s, isTypeOnly: false })) as any,
+  isTypeOnly: false
+});
+
+// 修改为
+imports.push({
+  source: normalizeSourcePath(match[4]),  // <-- 使用规范化路径
+  sourceType: match[4].startsWith('.') ? 'relative' : 'alias',
+  specifiers: specifiers.map(s => ({ name: s, isTypeOnly: false })) as any,
+  isTypeOnly: false
+});
+```
+
+**Step 3: 构建并测试**
+
+```bash
+npm run build
+node dist/cli/index.js deps -m "src/parser"
+```
+
+预期输出应显示 `.ts` 扩展名。
+
+**Step 4: 提交**
+
+```bash
+git add src/parser/implementations/fast-parser.ts
+git commit -m "fix: normalize .js to .ts in dependency paths"
+```
+
+---
+
+## 任务 2: 验证影响分析命令
+
+**Files:**
+- Test: 运行 `node dist/cli/index.js impact -f src/cache/lru-cache.ts`
+
+**Step 1: 验证 impact 命令**
+
+impact 命令也使用相同的 codemap.json 数据，路径问题应该已自动修复。
+
+**Step 2: 提交**
+
+```bash
+git commit -m "test: verify impact command uses normalized paths"
+```
+
+---
+
+## 任务 3: 添加回归测试
+
+**Files:**
+- Modify: `src/parser/__tests__/fast-parser.test.ts`
+
+**Step 1: 添加测试用例**
+
+```typescript
+describe('normalizeSourcePath', () => {
+  it('should convert .js to .ts', () => {
+    expect(normalizeSourcePath('../types/index.js')).toBe('../types/index.ts');
+  });
+
+  it('should keep .ts unchanged', () => {
+    expect(normalizeSourcePath('../types/index.ts')).toBe('../types/index.ts');
+  });
+
+  it('should handle nested paths', () => {
+    expect(normalizeSourcePath('./foo/bar.js')).toBe('./foo/bar.ts');
+  });
+});
+```
+
+**Step 2: 运行测试**
+
+```bash
+npm test -- --run src/parser/__tests__/fast-parser.test.ts
+```
+
+**Step 3: 提交**
+
+```bash
+git add src/parser/__tests__/fast-parser.test.ts
+git commit -m "test: add path normalization tests"
+```
+
+---
+
+## 验证命令
+
+修复完成后运行以下命令验证：
+
+```bash
+# 1. 依赖分析
+node dist/cli/index.js deps -m "src/parser"
+# 期望: 显示 .ts 而非 .js
+
+# 2. 影响分析
+node dist/cli/index.js impact -f src/cache/lru-cache.ts --transitive
+# 期望: 显示 .ts 而非 .js
+
+# 3. 构建
+npm run build
+# 期望: 无错误
+
+# 4. 测试
+npm test -- --run
+# 期望: 713+ 通过
+```
+
+---
+
+## 回滚计划
+
+如果修复导致问题：
+
+```bash
+git revert HEAD
+git push
+```

package/docs/exec-plans/completed/2026-03-03-post-task-plan.md

@@ -0,0 +1,135 @@
+# CodeMap 后续任务计划
+
+> 归档时间：2026-03-15
+> 归档原因：原位于 `docs/exec-plans/active/`，但内容记录的是 2026-03-03 的后续计划与当时状态，已不再属于活跃计划。
+> 当前依据：`docs/exec-plans/README.md`；新的进行中计划请放入 `docs/exec-plans/active/`
+> 状态：历史计划归档，供复盘参考。
+
+
+> 生成时间: 2026-03-03
+> 状态: 规划中
+
+---
+
+## 一、v2.5 工作流编排器实现状态
+
+### ✅ 已完成 (核心功能)
+
+| 模块 | 实现文件 | 状态 |
+|------|---------|------|
+| WorkflowOrchestrator | `src/orchestrator/workflow/workflow-orchestrator.ts` | ✅ |
+| WorkflowPersistence | `src/orchestrator/workflow/workflow-persistence.ts` | ✅ |
+| PhaseCheckpoint | `src/orchestrator/workflow/phase-checkpoint.ts` | ✅ |
+| WorkflowContext | `src/orchestrator/workflow/workflow-context.ts` | ✅ |
+| CLI Commands | `src/cli/commands/workflow.ts` | ✅ |
+| CI Integration | `src/cli/commands/ci.ts` | ✅ |
+
+### ⚠️ 扩展功能 (v2.6 规划)
+
+| 模块 | 设计位置 | 优先级 | 说明 |
+|------|---------|--------|------|
+| WorkflowResultFusion | RESULT_FUSION_DESIGN.md §8.1 | P2 | 跨阶段结果融合 |
+| PhaseInheritance | RESULT_FUSION_DESIGN.md §8.2 | P2 | 阶段结果继承 |
+| WorkflowTestLinker | TEST_LINKER_DESIGN.md §7.2 | P3 | 工作流测试建议 |
+| WorkflowGitAnalyzer | GIT_ANALYZER_DESIGN.md §10.2 | P3 | 工作流Git分析 |
+| WorkflowCIExecutor | CI_GATEWAY_DESIGN.md §11.2 | P3 | 工作流CI执行 |
+
+---
+
+## 二、后续任务清单
+
+### P0 - 立即执行 (24小时内)
+
+| 任务ID | 任务描述 | 依赖 | 状态 |
+|--------|---------|------|------|
+| T001 | 运行完整测试套件验证功能 | - | ✅ done |
+| T002 | 更新 README.md 工作流文档 | T001 | pending |
+
+### P1 - 高优先级 (本周)
+
+| 任务ID | 任务描述 | 依赖 | 状态 |
+|--------|---------|------|------|
+| T003 | 实现 WorkflowResultFusion 跨阶段融合 | T001 | pending |
+| T004 | 实现 PhaseInheritance 阶段继承 | T003 | pending |
+| T005 | 添加工作流 E2E 集成测试 | T001 | pending |
+
+### P2 - 中优先级 (本月)
+
+| 任务ID | 任务描述 | 依赖 | 状态 |
+|--------|---------|------|------|
+| T006 | WorkflowTestLinker 实现 | T005 | pending |
+| T007 | WorkflowGitAnalyzer 实现 | T005 | pending |
+| T008 | WorkflowCIExecutor 实现 | T005 | pending |
+
+### P3 - 低优先级 (季度)
+
+| 任务ID | 任务描述 | 依赖 | 状态 |
+|--------|---------|------|------|
+| T009 | 工作流可视化 UI | T005 | pending |
+| T010 | 工作流模板系统 | T005 | pending |
+
+---
+
+## 三、验收标准
+
+### 功能验收
+
+- [x] 所有 CLI 命令正常工作 (`workflow start/status/proceed/resume/checkpoint`)
+- [x] CI 门禁全部通过 (`check-commits/check-headers/assess-risk/check-output-contract`)
+- [x] 单元测试通过率 >= 80% (723/723)
+- [x] 工作流持久化正常工作
+
+### 性能验收
+
+- [ ] Hit@8 >= 90% (需要基准测试验证)
+- [ ] Token 消耗降低 >= 40% (需要基准测试验证)
+- [ ] CLI 响应时间 < 2s
+
+### 文档验收
+
+- [ ] README.md 更新
+- [ ] CLI 命令文档完整
+- [ ] API 文档同步更新
+
+---
+
+## 四、里程碑
+
+### M1: v2.5 正式发布 (目标: 2026-03-07)
+- [x] P0 任务全部完成 (测试已通过)
+- [x] 核心功能稳定 (723/723 测试通过)
+- [ ] 文档更新完成 (README.md 待更新)
+
+### M2: v2.6 规划 (目标: 2026-04-01)
+- [ ] P1 任务全部完成
+- [ ] 扩展功能实现
+
+---
+
+## 五、技术债务
+
+| 债务项 | 描述 | 优先级 |
+|--------|------|--------|
+| TEST_PATTERNS 硬编码 | 测试匹配模式应配置化 | P2 |
+| 缺少错误重试机制 | 网络/IO 错误应自动重试 | P2 |
+| 日志轮转配置 | 生产环境需要日志轮转 | P3 |
+
+---
+
+## 六、资源
+
+### 相关文档
+
+- [REFACTOR_ARCHITECTURE_OVERVIEW.md](../../design-docs/REFACTOR_ARCHITECTURE_OVERVIEW.md)
+- [REFACTOR_ORCHESTRATOR_DESIGN.md](../../design-docs/REFACTOR_ORCHESTRATOR_DESIGN.md)
+- [CI_GATEWAY_DESIGN.md](../../design-docs/CI_GATEWAY_DESIGN.md)
+
+### 代码位置
+
+- 工作流核心: `src/orchestrator/workflow/`
+- CLI 命令: `src/cli/commands/workflow.ts`
+- CI 命令: `src/cli/commands/ci.ts`
+
+---
+
+*此文档由 Claude Code 自动生成*

package/docs/exec-plans/completed/harness-engineering-rollout.md

@@ -0,0 +1,184 @@
+# Harness Engineering 方法论落地执行计划
+
+> 目标：将 Harness Engineering 方法论落地到 CodeMap 项目
+> 创建日期：2026-03-17
+> 状态：已完成
+
+## 1. 计划概述
+
+### 1.1 背景
+
+基于 `docs/references/tmp.md` 中的 Harness Engineering 方法论，结合 CodeMap 项目现有规范体系，进行渐进式增强。
+
+### 1.2 目标
+
+- 建立显式任务分级制度（L0-L3）
+- 引入结构化可信度自评机制
+- 完善代码质量红线与架构护栏
+- 提供 AI 任务执行模板与验收清单
+
+### 1.3 范围
+
+- 更新现有入口文档（AGENTS.md、CLAUDE.md）
+- 创建专项规范文档（architecture-guardrails、code-quality-redlines）
+- 更新工程规则文档
+- 配置工具脚本与 AI 集成
+
+## 2. 执行阶段
+
+### Phase 1: 核心规范文档更新 ✅
+
+| 任务 | 文件 | 状态 | 完成日期 |
+|------|------|------|---------|
+| 更新 AGENTS.md | `/data/codemap/AGENTS.md` | ✅ 已完成 | 2026-03-17 |
+| 更新 CLAUDE.md | `/data/codemap/CLAUDE.md` | ✅ 已完成 | 2026-03-17 |
+| 更新工程规则 | `/data/codemap/docs/rules/engineering-with-codex-openai.md` | ✅ 已完成 | 2026-03-17 |
+
+**Phase 1 交付内容**：
+- 任务分级制度（L0-L3）定义
+- 可信度自评格式规范
+- 技术债务标记规范
+- 代码生成红线规则
+- 任务初始化模板
+- 验收清单格式
+
+### Phase 2: 专项规范文档创建 ✅
+
+| 任务 | 文件 | 状态 | 完成日期 |
+|------|------|------|---------|
+| 创建架构护栏文档 | `/data/codemap/docs/rules/architecture-guardrails.md` | ✅ 已完成 | 2026-03-17 |
+| 创建代码质量红线文档 | `/data/codemap/docs/rules/code-quality-redlines.md` | ✅ 已完成 | 2026-03-17 |
+| 创建执行跟踪 | `/data/codemap/docs/exec-plans/active/harness-engineering-rollout.md` | ✅ 已完成 | 2026-03-17 |
+
+### Phase 3: 工具配置增强 ✅
+
+| 任务 | 文件 | 状态 | 备注 |
+|------|------|------|------|
+| 更新 package.json 脚本 | `/data/codemap/package.json` | ✅ 已完成 | 添加 check:all、ai:* 脚本 |
+| 创建 Claude 配置 | `/data/codemap/.claude/CLAUDE.md` | ✅ 已完成 | AI 工具集成配置 |
+
+### Phase 4: 验收验证 ✅
+
+| 检查项 | 状态 | 备注 |
+|--------|------|------|
+| 文档完整性检查 | ✅ 通过 | 所有规划文档已创建 |
+| npm run docs:check | ✅ 通过 | 文档护栏通过 |
+| npm run typecheck | ✅ 通过 | 类型检查通过 |
+| npm test | ✅ 通过 | 全部测试通过 |
+| npm run lint | ⚠️ 已知问题 | 缺少 ESLint 配置，记录在 tech-debt |
+| 新脚本验证 | ✅ 通过 | check:all、ai:pre-task 可用 |
+
+## 3. 文件变更清单
+
+| 文件路径 | 操作 | 优先级 | 状态 |
+|---------|------|--------|------|
+| AGENTS.md | 修改 | P0 | ✅ 已完成 |
+| CLAUDE.md | 修改 | P0 | ✅ 已完成 |
+| docs/rules/engineering-with-codex-openai.md | 修改 | P0 | ✅ 已完成 |
+| docs/rules/architecture-guardrails.md | 新增 | P1 | ✅ 已完成 |
+| docs/rules/code-quality-redlines.md | 新增 | P1 | ✅ 已完成 |
+| docs/exec-plans/active/harness-engineering-rollout.md | 新增 | P1 | ✅ 已完成 |
+| package.json | 修改 | P1 | ✅ 已完成 |
+| .claude/CLAUDE.md | 新增 | P1 | ✅ 已完成 |
+
+## 4. 风险评估与缓解
+
+| 风险 | 可能性 | 影响 | 缓解策略 | 状态 |
+|------|--------|------|---------|------|
+| 文档过多导致阅读负担 | 中 | 中 | 保持入口文档短小，细节下沉到子文档 | 已缓解 |
+| 与现有规范冲突 | 低 | 高 | 渐进式实施，每步验证兼容性 | 已验证无冲突 |
+| 工具依赖缺失 | 中 | 低 | 脚本中提供降级方案 | 已处理 |
+| 团队适应成本 | 中 | 中 | 从 L0 任务开始试运行 | 待观察 |
+
+## 5. 验收标准（Definition of Done）
+
+### 5.1 文档完整性 ✅
+
+- [x] AGENTS.md 包含任务分级、可信度自评、技术债务标记
+- [x] CLAUDE.md 包含任务初始化模板和执行计划模板
+- [x] docs/rules/ 包含架构护栏和代码质量红线文档
+- [x] package.json 包含 check:all、ai:pre-task、ai:post-task 脚本
+- [x] .claude/CLAUDE.md 配置已创建
+
+### 5.2 验证通过 ✅
+
+- [x] `npm run docs:check` 通过
+- [x] `npm run typecheck` 通过
+- [x] `npm test` 通过
+- [ ] `npm run lint` - 已知问题，记录在 `docs/exec-plans/tech-debt/2026-03-15-lint-guardrail-gap.md`
+
+### 5.3 新功能验证 ✅
+
+- [x] `npm run check:all` 可用（类型 + 测试 + Lint）
+- [x] `npm run ai:pre-task` 可用
+- [x] `npm run ai:post-task` 可用
+- [x] `npm run check:architecture` 已配置（待安装 dependency-cruiser）
+- [x] `npm run check:security` 已配置
+
+## 6. 新增脚本使用说明
+
+### 6.1 验证脚本
+
+```bash
+# 运行所有检查（类型 + Lint + 测试）
+npm run check:all
+
+# 架构检查（需先安装 dependency-cruiser）
+npm run check:architecture
+
+# 安全检查
+npm run check:security
+
+# 未使用代码检查（需先安装 knip）
+npm run check:unused
+```
+
+### 6.2 AI 任务钩子
+
+```bash
+# 任务前检查
+npm run ai:pre-task
+
+# 任务后检查+修复
+npm run ai:post-task
+
+# 自动修复
+npm run fix:all
+```
+
+## 7. 变更日志
+
+### 2026-03-17
+
+- ✅ 创建 Phase 1-4 执行计划
+- ✅ 更新 AGENTS.md，添加任务分级、可信度自评、技术债务标记
+- ✅ 更新 CLAUDE.md，添加任务初始化模板、验收清单
+- ✅ 更新 engineering-with-codex-openai.md，添加上下文披露、红线规则
+- ✅ 创建 architecture-guardrails.md
+- ✅ 创建 code-quality-redlines.md
+- ✅ 更新 package.json，添加 Harness 标准脚本
+- ✅ 创建 .claude/CLAUDE.md AI 工具配置
+- ✅ 完成验收验证
+
+## 8. 后续建议
+
+1. **试运行**：选择一个 L0 级任务（如文档更新）试用新规范
+2. **ESLint 配置**：解决 lint 护栏缺口，参考 `docs/exec-plans/tech-debt/2026-03-15-lint-guardrail-gap.md`
+3. **dependency-cruiser**：如需架构依赖检查，安装并配置 `.dependency-cruiser.js`
+4. **团队培训**：向团队成员介绍新的 Harness Engineering 规范
+
+## 9. 参考文档
+
+- `docs/references/tmp.md` - Harness Engineering 方法论来源
+- `AGENTS.md` - 仓库级强约束（已更新）
+- `CLAUDE.md` - 执行清单（已更新）
+- `docs/rules/architecture-guardrails.md` - 架构护栏（新增）
+- `docs/rules/code-quality-redlines.md` - 代码质量红线（新增）
+- `docs/rules/engineering-with-codex-openai.md` - 工程规则（已更新）
+- `.claude/CLAUDE.md` - AI 工具配置（新增）
+
+---
+
+**计划状态**：已完成 ✅  
+**完成日期**：2026-03-17  
+**执行者**：AI Agent  

package/docs/exec-plans/tech-debt/2026-03-15-lint-guardrail-gap.md

@@ -0,0 +1,30 @@
+# 2026-03-15 lint 护栏缺口
+
+## 目标
+
+- 记录当前仓库 `lint` 护栏无法纳入 CI Gateway 的根因、风险与后续 DoD。
+
+## 限制条件
+
+- 当前任务聚焦 CLI / CI 护栏最小可用落地，不能为了让 `npm run lint` 通过而一次性清洗全仓历史问题。
+- 不能通过删除 `lint` 脚本、关闭检查或跳过 CI 来伪造“已解决”。
+
+## 现状证据
+
+- `package.json:25` 已声明 `npm run lint`，命令为 `eslint src --ext .ts`。
+- `docs/rules/validation.md:8` 把 `npm run lint` 列为扩大量级验证的一部分。
+- `CLAUDE.md:40` 与 `docs/design-docs/PUBLISH_NPM_DESIGN_FINAL.md:256` 都把 lint 视为仓库应有护栏。
+- `npm run lint` 在 2026-03-15 的本轮验证中直接失败，错误为“ESLint couldn't find a configuration file”。
+- 试跑一个临时 `eslint:recommended + plugin:@typescript-eslint/recommended` 配置后，仓库会暴露 249 个现存错误，说明问题不是单个命令参数，而是“缺配置 + 历史债务”叠加。
+
+## 风险模式
+
+- 若继续把 `lint` 留在文档里、却不让 CI 真正执行，团队会误以为仓库已有静态质量护栏。
+- 若仓促接入推荐规则，CI 会被 180+ 到 249 个现存问题直接打红，阻断正常迭代。
+
+## 后续 DoD
+
+- 明确 ESLint 目标基线：只做 parser/syntax guardrail，还是逐步引入可修复规则集。
+- 落地正式 ESLint 配置文件，并让 `npm run lint` 在当前仓库稳定通过。
+- 把 `npm run lint` 纳入 `.github/workflows/ci-gateway.yml`，并补一条对应的失败回归测试或文档护栏。
+- 同步 `README.md`、`docs/SETUP_GUIDE.md`、`docs/rules/validation.md` 中的验证顺序说明，避免再次漂移。

package/docs/generated/README.md

@@ -0,0 +1,19 @@
+# docs/generated/
+
+本目录存放“由工具或流程生成”的文档说明与需要纳入版本管理的生成结果。
+
+## 应放内容
+
+- schema、结构化快照、分析报告
+- 与发布或验收直接相关的生成文档
+- 需要被人类或 agent 稳定引用的生成产物
+
+## 不应放内容
+
+- 本地临时调试输出
+- 可随时重建且无须版本管理的噪音文件
+- 与 `.mycodemap/` 运行时缓存混淆的临时结果
+
+## 说明
+
+若某类生成物已经由脚本稳定产出，应在这里补一份“生成方式 + 消费方式”的说明。