@mycodemap/mycodemap 0.1.0 → 0.1.1

package/docs/plans/POST_TASK_PLAN.md

@@ -0,0 +1,129 @@
+# CodeMap 后续任务计划
+
+> 生成时间: 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](../docs/REFACTOR_ARCHITECTURE_OVERVIEW.md)
+- [REFACTOR_ORCHESTRATOR_DESIGN.md](../docs/REFACTOR_ORCHESTRATOR_DESIGN.md)
+- [CI_GATEWAY_DESIGN.md](../docs/CI_GATEWAY_DESIGN.md)
+
+### 代码位置
+
+- 工作流核心: `src/orchestrator/workflow/`
+- CLI 命令: `src/cli/commands/workflow.ts`
+- CI 命令: `src/cli/commands/ci.ts`
+
+---
+
+*此文档由 Claude Code 自动生成*

package/docs/plans/archive/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/examples/README.md

@@ -0,0 +1,61 @@
+# MyCodeMap 配置示例
+
+本目录包含各种 AI 助手和开发环境的配置示例。
+
+## 目录结构
+
+```
+examples/
+├── kimi/                    # Kimi CLI 配置
+│   └── codemap-skill.md    # Skill 定义文件
+├── claude/                  # Claude Code 配置
+│   └── codemap-skill.md    # Skill 定义文件
+├── codex/                   # Codex CLI 配置
+│   └── codemap-agent.md    # Agent 定义文件
+├── copilot/                 # GitHub Copilot 配置
+│   └── copilot-instructions.md  # 提示词文件
+└── README.md               # 本文件
+```
+
+## 快速使用
+
+### Kimi CLI
+
+```bash
+mkdir -p .kimi/skills/codemap
+cp examples/kimi/codemap-skill.md .kimi/skills/codemap/SKILL.md
+```
+
+### Claude Code
+
+```bash
+mkdir -p .claude/skills/codemap
+cp examples/claude/codemap-skill.md .claude/skills/codemap/SKILL.md
+```
+
+### Codex CLI
+
+```bash
+mkdir -p .agents/skills/codemap
+cp examples/codex/codemap-agent.md .agents/skills/codemap/SKILL.md
+```
+
+### GitHub Copilot
+
+```bash
+mkdir -p .github
+cp examples/copilot/copilot-instructions.md .github/copilot-instructions.md
+```
+
+## 自定义配置
+
+复制示例文件后，可以根据项目需求进行调整：
+
+1. **修改命令别名** - 如果项目中使用了不同的命令别名
+2. **添加项目特定规则** - 针对项目结构的特殊处理
+3. **调整输出格式** - 根据 AI 助手的解析能力调整
+
+## 更多信息
+
+- [安装配置指南](../docs/SETUP_GUIDE.md)
+- [AI 助手集成指南](../docs/AI_ASSISTANT_SETUP.md)

package/examples/claude/codemap-skill.md

@@ -0,0 +1,94 @@
+# MyCodeMap Code Analysis
+
+## Overview
+
+Use MyCodeMap to analyze TypeScript/JavaScript project structure, query symbols, analyze dependencies, and assess change impact.
+
+## CLI Detection
+
+Detect MyCodeMap CLI availability:
+
+```bash
+# Check global installation
+if command -v mycodemap &> /dev/null; then
+    CODEMAP="mycodemap"
+# Check local installation
+elif [ -f "./node_modules/.bin/mycodemap" ]; then
+    CODEMAP="./node_modules/.bin/mycodemap"
+# Fallback to npx
+else
+    CODEMAP="npx @mycodemap/mycodemap"
+fi
+```
+
+## Commands
+
+### Generate Code Map
+```bash
+$CODEMAP generate
+```
+Generates: `.mycodemap/AI_MAP.md`, `.mycodemap/CONTEXT.md`, `.mycodemap/codemap.json`
+
+### Query Symbol
+```bash
+$CODEMAP query -s "<symbol-name>"
+$CODEMAP query -s "<symbol-name>" -j  # JSON output
+```
+
+### Query Module
+```bash
+$CODEMAP query -m "<module-path>"
+```
+
+### Search
+```bash
+$CODEMAP query -S "<keyword>" -l 10
+```
+
+### Dependency Analysis
+```bash
+$CODEMAP deps -m "<module-path>"
+$CODEMAP deps -m "<module-path>" -j
+```
+
+### Impact Analysis
+```bash
+$CODEMAP impact -f "<file-path>"
+$CODEMAP impact -f "<file-path>" --transitive
+```
+
+### Cycle Detection
+```bash
+$CODEMAP cycles
+```
+
+### Complexity Analysis
+```bash
+$CODEMAP complexity
+$CODEMAP complexity -f "<file-path>"
+```
+
+## Workflows
+
+### Understanding Project Structure
+
+1. Generate code map: `$CODEMAP generate`
+2. Read `.mycodemap/AI_MAP.md` for overview
+3. Query specific modules as needed
+
+### Before Code Changes
+
+1. Run impact analysis: `$CODEMAP impact -f "<file>" --transitive`
+2. Review affected files
+3. Suggest test cases based on impact
+
+### Finding Code
+
+1. Search symbol: `$CODEMAP query -s "<name>"`
+2. If not found, fuzzy search: `$CODEMAP query -S "<name>"`
+3. Check module context: `$CODEMAP query -m "<path>"`
+
+## Output Format
+
+- Default: Human-readable text
+- JSON: Add `-j` flag for structured data

package/examples/codex/codemap-agent.md

@@ -0,0 +1,66 @@
+# MyCodeMap Skill
+
+## Description
+
+Code analysis tool for TypeScript/JavaScript projects. Provides project structure analysis, symbol querying, dependency analysis, and impact assessment.
+
+## CLI Command Detection
+
+```bash
+# Priority: global > local > npx
+if command -v mycodemap &> /dev/null; then
+    CODEMAP_CMD="mycodemap"
+elif [ -f "./node_modules/.bin/mycodemap" ]; then
+    CODEMAP_CMD="./node_modules/.bin/mycodemap"
+else
+    CODEMAP_CMD="npx @mycodemap/mycodemap"
+fi
+```
+
+## Available Commands
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `generate` | Generate code map | `$CODEMAP_CMD generate` |
+| `query -s` | Query symbol | `$CODEMAP_CMD query -s "ClassName"` |
+| `query -m` | Query module | `$CODEMAP_CMD query -m "src/parser"` |
+| `query -S` | Fuzzy search | `$CODEMAP_CMD query -S "keyword"` |
+| `deps` | Dependency analysis | `$CODEMAP_CMD deps -m "src/core"` |
+| `impact` | Impact analysis | `$CODEMAP_CMD impact -f "src/index.ts"` |
+| `cycles` | Cycle detection | `$CODEMAP_CMD cycles` |
+| `complexity` | Complexity metrics | `$CODEMAP_CMD complexity` |
+
+## Usage Patterns
+
+### Pattern 1: Project Onboarding
+```
+User: "Explain this project structure"
+Agent:
+1. $CODEMAP_CMD generate
+2. Read .mycodemap/AI_MAP.md
+3. Summarize key components
+```
+
+### Pattern 2: Change Impact
+```
+User: "What happens if I modify X?"
+Agent:
+1. $CODEMAP_CMD impact -f "<path>" --transitive
+2. Analyze output
+3. List affected files and suggest tests
+```
+
+### Pattern 3: Code Navigation
+```
+User: "Where is function Y defined?"
+Agent:
+1. $CODEMAP_CMD query -s "Y"
+2. Report location
+3. Offer to show code context
+```
+
+## Best Practices
+
+- Always generate code map before queries if `.mycodemap/` is stale
+- Use `-j` flag for programmatic processing
+- Use `--transitive` for complete impact analysis

package/examples/copilot/copilot-instructions.md

@@ -0,0 +1,24 @@
+# MyCodeMap Integration
+
+This project uses MyCodeMap for code analysis.
+
+## Available Commands
+
+Before answering questions about project structure, run:
+```bash
+mycodemap generate
+```
+
+Then read `.mycodemap/AI_MAP.md` for context.
+
+## Common Queries
+
+- Find symbol: `mycodemap query -s "<name>"`
+- Check dependencies: `mycodemap deps -m "<path>"`
+- Impact analysis: `mycodemap impact -f "<path>"`
+
+## When Answering
+
+1. Always check the code map first for structural questions
+2. Use impact analysis before suggesting changes
+3. Reference specific files and line numbers

package/examples/kimi/codemap-skill.md

@@ -0,0 +1,92 @@
+---
+name: codemap
+description: MyCodeMap 代码分析技能，用于项目结构分析、符号查询、依赖分析和影响评估。
+---
+
+# MyCodeMap Skill
+
+## 环境检测
+
+首先检测 CLI 是否可用：
+
+```bash
+# 检测全局安装的 mycodemap
+if command -v mycodemap &> /dev/null; then
+    CODEMAP_CMD="mycodemap"
+# 检测本地安装的 mycodemap
+elif [ -f "./node_modules/.bin/mycodemap" ]; then
+    CODEMAP_CMD="./node_modules/.bin/mycodemap"
+# 使用 npx
+else
+    CODEMAP_CMD="npx @mycodemap/mycodemap"
+fi
+```
+
+## 常用命令
+
+### 生成代码地图
+```bash
+$CODEMAP_CMD generate
+```
+
+### 查询符号
+```bash
+$CODEMAP_CMD query -s "<symbol-name>"
+```
+
+### 查询模块
+```bash
+$CODEMAP_CMD query -m "<module-path>"
+```
+
+### 模糊搜索
+```bash
+$CODEMAP_CMD query -S "<keyword>" -l 10
+```
+
+### 依赖分析
+```bash
+$CODEMAP_CMD deps -m "<module-path>"
+```
+
+### 影响范围分析
+```bash
+$CODEMAP_CMD impact -f "<file-path>"
+```
+
+### 循环依赖检测
+```bash
+$CODEMAP_CMD cycles
+```
+
+### 复杂度分析
+```bash
+$CODEMAP_CMD complexity -f "<file-path>"
+```
+
+## 使用场景
+
+### 场景 1：理解项目结构
+
+当用户询问项目结构或特定模块时：
+1. 运行 `$CODEMAP_CMD generate` 生成最新代码地图
+2. 阅读 `.mycodemap/AI_MAP.md` 获取项目概览
+3. 根据需要使用 `query` 或 `deps` 获取详细信息
+
+### 场景 2：代码变更影响分析
+
+当用户要修改某个文件时：
+1. 运行 `$CODEMAP_CMD impact -f "<file-path>" --transitive`
+2. 分析输出结果，告知用户受影响的模块和文件
+
+### 场景 3：查找代码定义
+
+当用户询问某个类/函数的位置时：
+1. 运行 `$CODEMAP_CMD query -s "<symbol-name>"`
+2. 根据结果提供精确的文件路径和行号
+
+## 输出处理
+
+- 直接返回 CLI 输出给用户
+- 使用 `-j` 参数获取 JSON 格式便于解析
+- 复杂输出可重定向到临时文件分析

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycodemap/mycodemap",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "TypeScript 代码地图工具 - 为 AI 辅助开发提供结构化上下文",
   "main": "./dist/index.js",
   "type": "module",
@@ -14,6 +14,8 @@
   },
   "files": [
     "dist/",
+    "docs/",
+    "examples/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
@@ -25,10 +27,10 @@
     "test": "vitest run",
     "lint": "eslint src --ext .ts",
     "typecheck": "tsc --noEmit",
-    "postinstall": "sh scripts/hooks/install-hooks.sh",
     "benchmark": "bash scripts/run-benchmark.sh",
     "test:all": "npm run test && npm run benchmark",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && npm test",
+    "validate-pack": "node scripts/validate-pack.js"
   },
   "keywords": [
     "typescript",