@mycodemap/mycodemap 0.1.0 → 0.2.0

package/docs/archive/design-docs/REFACTOR_RESULT_FUSION_DESIGN.md

@@ -0,0 +1,321 @@
+# 多工具结果融合详细设计
+
+> 归档时间：2026-03-15
+> 归档原因：历史结果融合设计稿，统一结果结构与当前实现不再完全一致。
+> 当前依据：`ARCHITECTURE.md`、`src/orchestrator/result-fusion.ts`、`src/orchestrator/types.ts`
+> 状态：仅供历史对照，不作为当前执行依据。
+
+
+> 版本: 2.6
+> 所属模块: 编排层 - 结果融合
+> 更新日期: 2026-03-03
+
+---
+
+## 1. 设计目标
+
+所有工具的结果都转换为统一的中间格式，然后按统一规则处理（加权合并、去重、排序）。
+
+---
+
+## 2. 数据结构设计
+
+### 2.1 统一结果格式
+
+```typescript
+// src/orchestrator/types.ts
+
+interface UnifiedResult {
+  // 唯一标识
+  id: string;
+
+  // 来源信息
+  source: 'codemap' | 'ast-grep' | 'rg-internal';
+  toolScore: number;        // 工具返回的原始分数
+
+  // 内容信息
+  type: 'file' | 'symbol' | 'code' | 'documentation';
+  file: string;
+  line?: number;
+  content: string;           // 截断后的内容
+  preview?: string;          // 上下文预览
+
+  // 语义信息
+  relevance: number;          // 0-1 归一化相关度
+  keywords: string[];         // 匹配的关键词
+
+  // 元数据
+  metadata?: {
+    symbolType?: 'class' | 'function' | 'interface' | 'variable';
+    dependencies?: string[];
+    testFile?: string;
+    commitCount?: number;
+  };
+}
+```
+
+---
+
+## 3. 接口设计
+
+### 3.1 结果融合类
+
+```typescript
+// src/orchestrator/result-fusion.ts
+
+class ResultFusion {
+  /**
+   * 多工具结果融合
+   * 策略：加权合并 → 去重 → 排序
+   */
+  fuse(
+    resultsByTool: Map<string, UnifiedResult[]>,
+    options: { topK: number; keywordWeights: Record<string, number> }
+  ): UnifiedResult[] {
+    // 1. 加权合并
+    let allResults: UnifiedResult[] = [];
+    for (const [tool, results] of resultsByTool) {
+      const toolWeight = this.getToolWeight(tool);
+      const weighted = results.map(r => ({
+        ...r,
+        relevance: r.relevance * toolWeight
+      }));
+      allResults = allResults.concat(weighted);
+    }
+
+    // 2. 去重（基于文件+行号）
+    const seen = new Map<string, UnifiedResult>();
+    for (const result of allResults) {
+      const key = `${result.file}:${result.line || ''}`;
+      if (!seen.has(key)) {
+        seen.set(key, result);
+      } else {
+        // 保留分数更高的
+        const existing = seen.get(key)!;
+        if (result.relevance > existing.relevance) {
+          seen.set(key, result);
+        }
+      }
+    }
+
+    // 3. 按相关度排序
+    const sorted = Array.from(seen.values())
+      .sort((a, b) => b.relevance - a.relevance);
+
+    // 4. 关键词加权
+    const keywordBoosted = this.applyKeywordBoost(sorted, options.keywordWeights);
+
+    return keywordBoosted.slice(0, options.topK);
+  }
+
+  private getToolWeight(tool: string): number {
+    const weights: Record<string, number> = {
+      'ast-grep': 1.0,      // AST 分析最准确
+      'codemap': 0.9,       // 结构分析次之
+      'rg-internal': 0.7    // 文本搜索兜底（仅内部调试用）
+    };
+    return weights[tool] || 0.5;
+  }
+
+  /**
+   * 应用关键词加权
+   */
+  private applyKeywordBoost(
+    results: UnifiedResult[],
+    keywordWeights: Record<string, number>
+  ): UnifiedResult[] {
+    if (Object.keys(keywordWeights).length === 0) {
+      return results;
+    }
+
+    return results.map(r => {
+      let boost = 0;
+      for (const keyword of r.keywords) {
+        boost += keywordWeights[keyword] || 0;
+      }
+      return {
+        ...r,
+        relevance: r.relevance + boost
+      };
+    }).sort((a, b) => b.relevance - a.relevance);
+  }
+}
+```
+
+---
+
+## 4. Token 截断
+
+### 4.1 按 token 数量截断内容
+
+```typescript
+/**
+ * 按 token 数量截断内容（而非字符数）
+ * 简单估算：英文约 4 字符 = 1 token，中文约 1 字符 = 1-2 token
+ */
+function truncateByToken(content: string, maxTokens: number): string {
+  const tokens = content.split(/[\s\u4e00-\u9fa5]/).filter(Boolean);
+  if (tokens.length <= maxTokens) return content;
+  return tokens.slice(0, maxTokens).join(' ') + '...';
+}
+```
+
+---
+
+## 5. 模块依赖
+
+```
+结果融合模块 (result-fusion.ts)
+    │
+    ├── 依赖类型: UnifiedResult (输入/输出)
+    │
+    └── 被以下模块使用:
+        └── ToolOrchestrator (tool-orchestrator.ts)
+        └── AnalyzeCommand (analyze.ts)
+        └── CIGateway (ci-gateway.ts)
+        └── WorkflowOrchestrator (workflow-orchestrator.ts) (v2.5)
+```
+
+---
+
+## 6. 工作流上下文融合 (v2.5)
+
+### 6.1 跨阶段结果传递
+
+在工作流中，每个阶段的分析结果需要传递给下一阶段：
+
+```typescript
+// 工作流上下文中的结果缓存
+
+interface WorkflowFusionContext {
+  phaseResults: Map<WorkflowPhase, UnifiedResult[]>;
+  accumulatedContext: Map<string, UnifiedResult>;
+}
+
+// 跨阶段结果合并策略
+class WorkflowResultFusion {
+  /**
+   * 将新阶段结果与已有上下文合并
+   */
+  mergeWithContext(
+    newResults: UnifiedResult[],
+    context: WorkflowFusionContext
+  ): UnifiedResult[] {
+    // 1. 合并所有历史结果
+    const allResults = [
+      ...Array.from(context.phaseResults.values()).flat(),
+      ...newResults
+    ];
+
+    // 2. 应用工作流特定的加权
+    const workflowWeighted = this.applyWorkflowWeights(allResults, context);
+
+    // 3. 按工作流阶段优先级排序
+    return this.sortByWorkflowPriority(workflowWeighted);
+  }
+
+  /**
+   * 工作流阶段权重
+   * 越近期的阶段权重越高
+   */
+  private applyWorkflowWeights(
+    results: UnifiedResult[],
+    context: WorkflowFusionContext
+  ): UnifiedResult[] {
+    const phaseWeights: Record<WorkflowPhase, number> = {
+      'reference': 0.8,
+      'impact': 0.9,
+      'risk': 1.0,
+      'implementation': 0.7,
+      'commit': 0.6,
+      'ci': 0.5
+    };
+
+    return results.map(r => {
+      // 根据结果来源确定阶段权重
+      const sourcePhase = this.inferPhase(r.source);
+      const weight = phaseWeights[sourcePhase] || 0.5;
+
+      return {
+        ...r,
+        relevance: r.relevance * weight
+      };
+    });
+  }
+}
+```
+
+### 6.2 阶段间结果继承
+
+```typescript
+// 阶段间的结果继承逻辑
+
+class PhaseInheritance {
+  /**
+   * 获取下一阶段应该继承的结果
+   */
+  getInheritedResults(
+    currentPhase: WorkflowPhase,
+    allResults: UnifiedResult[]
+  ): UnifiedResult[] {
+    switch (currentPhase) {
+      case 'reference':
+        // 影响分析继承参考搜索的结果
+        return allResults.filter(r =>
+          r.source === 'ast-grep' || r.source === 'codemap'
+        );
+
+      case 'impact':
+        // 风险评估继承影响分析 + 参考搜索
+        return allResults;
+
+      case 'risk':
+        // 代码实现继承所有分析结果
+        return allResults;
+
+      default:
+        return allResults;
+    }
+  }
+}
+```
+
+---
+
+## 7. 融合策略总结
+
+| 阶段 | 策略 | 说明 |
+|------|------|------|
+| 1 | 加权合并 | 按工具权重调整 relevance |
+| 2 | 去重 | 基于 file:line 作为 key |
+| 3 | 排序 | 按 relevance 降序 |
+| 4 | 关键词加权 | 提升匹配关键词的结果 |
+| 5 | 截断 | Top-K + Token 限制 |
+
+**示例输出**：
+```
+[SEARCH RESULTS] - Sorted by Relevance
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. src/auth/jwt.ts (relevance: 92%)
+   Type: function | Line: 45
+   Content: export function verifyToken(token: string): Payload {...}
+
+2. src/cache/lru-cache.ts (relevance: 85%)
+   Type: class | Line: 12
+   Content: export class LRUCache<K, V> {...}
+
+3. src/utils/date.ts (relevance: 45%)
+   Type: function | Line: 8
+   Content: export function formatDate(d: Date): string {...}
+```
+
+---
+
+## 附录：版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 2.4 | 2026-02-28 | 添加 AI 饲料融合、风险加权 |
+| 2.5 | 2026-03-01 | 添加工作流上下文融合 |
+| 2.6 | 2026-03-03 | 移除 AI 饲料相关功能，简化融合策略 |

package/docs/archive/design-docs/REFACTOR_TEST_LINKER_DESIGN.md

@@ -0,0 +1,317 @@
+# 测试关联器详细设计
+
+> 归档时间：2026-03-15
+> 归档原因：历史测试关联设计稿，已被当前测试规则和实现替代。
+> 当前依据：`docs/rules/testing.md`、`src/orchestrator/test-linker.ts`
+> 状态：仅供历史对照，不作为当前执行依据。
+
+
+> 版本: 2.4
+> 所属模块: 编排层 - 测试关联器
+
+---
+
+## 1. 功能定位
+
+在影响分析场景中，根据源代码文件自动关联相关的测试文件。
+
+---
+
+## 2. 数据结构设计
+
+### 2.1 测试配置
+
+```typescript
+// src/orchestrator/test-linker.ts
+
+interface TestConfig {
+  framework: 'jest' | 'vitest' | 'none';
+  patterns: {
+    testFile: string[];      // 测试文件匹配模式
+    testDir: string[];       // 测试目录
+  };
+  sourceToTestMap: Map<string, string[]>;  // 源文件 → 测试文件映射
+}
+```
+
+---
+
+## 3. 接口设计
+
+### 3.1 测试关联器类
+
+```typescript
+class TestLinker {
+  private config: TestConfig | null = null;
+
+  /**
+   * 加载测试配置
+   * 读取 jest.config.js / vitest.config.ts
+   */
+  async loadConfig(projectRoot: string): Promise<TestConfig> {
+    const fsPromises = require('fs').promises;
+
+    // 1. 尝试读取 vitest.config.ts
+    const vitestPath = path.join(projectRoot, 'vitest.config.ts');
+    if (await this.pathExists(vitestPath)) {
+      return this.parseVitestConfig(vitestPath);
+    }
+
+    // 2. 尝试读取 jest.config.js
+    const jestPath = path.join(projectRoot, 'jest.config.js');
+    if (await this.pathExists(jestPath)) {
+      return this.parseJestConfig(jestPath);
+    }
+
+    // 3. 使用默认模式
+    const defaultConfig: TestConfig = {
+      framework: 'vitest',
+      patterns: {
+        testFile: ['**/*.test.ts', '**/*.spec.ts'],
+        testDir: ['__tests__', 'test', 'tests']
+      },
+      sourceToTestMap: new Map()
+    };
+
+    // 赋值到实例变量
+    this.config = defaultConfig;
+    return this.config;
+  }
+
+  /**
+   * 检查文件是否存在
+   * 使用 fsPromises.access 替代已废弃的 fs.exists
+   */
+  private async pathExists(filePath: string): Promise<boolean> {
+    try {
+      await require('fs').promises.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 确保配置已加载
+   * 在使用 this.config 前调用
+   */
+  private assertConfig(): void {
+    if (!this.config) {
+      throw new Error('TestLinker 配置未初始化，请先调用 loadConfig');
+    }
+  }
+}
+```
+
+### 3.2 构建映射
+
+```typescript
+/**
+ * 构建源文件 → 测试文件 映射
+ * 基于测试框架的匹配规则
+ */
+async buildMapping(projectRoot: string, codemap: CodemapData): Promise<void> {
+  // 确保配置已加载
+  if (!this.config) {
+    throw new Error('请先调用 loadConfig 加载测试配置');
+  }
+
+  const testFiles = await this.findTestFiles(projectRoot);
+
+  for (const testFile of testFiles) {
+    // 从测试文件名推断源文件
+    // 例如: lru-cache.test.ts → lru-cache.ts
+    const sourceFile = this.inferSourceFile(testFile);
+
+    if (sourceFile) {
+      const existing = this.config.sourceToTestMap.get(sourceFile) || [];
+      existing.push(testFile);
+      this.config.sourceToTestMap.set(sourceFile, existing);
+    }
+
+    // 扫描测试文件内容，找出 import 的源文件
+    const imports = await this.scanTestImports(testFile);
+    for (const imported of imports) {
+      const existing = this.config.sourceToTestMap.get(imported) || [];
+      if (!existing.includes(testFile)) {
+        existing.push(testFile);
+        this.config.sourceToTestMap.set(imported, existing);
+      }
+    }
+  }
+}
+```
+
+### 3.3 查找相关测试
+
+```typescript
+/**
+ * 查找相关测试文件
+ */
+findRelatedTests(sourceFiles: string[]): string[] {
+  // 确保配置已加载
+  if (!this.config) {
+    throw new Error('请先调用 loadConfig 加载测试配置');
+  }
+
+  const relatedTests = new Set<string>();
+
+  for (const sourceFile of sourceFiles) {
+    // 直接映射
+    const direct = this.config.sourceToTestMap.get(sourceFile) || [];
+    direct.forEach(t => relatedTests.add(t));
+
+    // 目录级别匹配
+    // src/cache/lru-cache.ts → src/cache/__tests__/
+    const dirTests = this.findDirLevelTests(sourceFile);
+    dirTests.forEach(t => relatedTests.add(t));
+  }
+
+  return Array.from(relatedTests);
+}
+```
+
+### 3.4 源文件推断
+
+```typescript
+private inferSourceFile(testFile: string): string | null {
+  // lru-cache.test.ts → lru-cache.ts
+  // src/cache/__tests__/lru-cache.test.ts → src/cache/lru-cache.ts
+  const normalized = testFile.replace(/\\/g, '/');
+  const baseMatch = normalized.match(/^(.+?)\.(test|spec)\.ts$/);
+  if (!baseMatch) return null;
+
+  const base = baseMatch[1];
+  // 处理任意层级的 __tests__ 目录
+  if (base.includes('/__tests__/')) {
+    return base.replace('/__tests__/', '/') + '.ts';
+  }
+  return base + '.ts';
+}
+```
+
+---
+
+## 4. 测试关联策略
+
+| 策略 | 示例 | 优先级 |
+|------|------|--------|
+| **文件名匹配** | `lru-cache.ts` → `lru-cache.test.ts` | 高 |
+| **目录匹配** | `src/cache/file.ts` → `src/cache/__tests__/*.test.ts` | 高 |
+| **import 扫描** | 测试 import 了源文件 | 中 |
+| **反向覆盖** | 哪些测试覆盖了目标代码 | 低（可选） |
+
+---
+
+## 5. 模块依赖
+
+```
+测试关联器 (test-linker.ts)
+    │
+    ├── 依赖: fs.promises (文件系统)
+    │
+    └── 被以下模块使用:
+        └── AnalyzeCommand (analyze.ts)
+        └── WorkflowOrchestrator (workflow-orchestrator.ts) (v2.5 新增)
+```
+
+---
+
+## 7. 工作流阶段的测试关联 (v2.5 规划)
+
+### 7.1 阶段特定的测试策略
+
+```typescript
+// 工作流阶段与测试关联的映射
+
+const PHASE_TEST_STRATEGY: Record<WorkflowPhase, TestStrategy> = {
+  reference: {
+    // 参考搜索阶段：查找相关测试作为参考
+    mode: 'find-similar',
+    includePatterns: ['**/*.test.ts', '**/*.spec.ts'],
+    excludePatterns: []
+  },
+  impact: {
+    // 影响分析阶段：查找所有可能受影响的测试
+    mode: 'find-affected',
+    includePatterns: ['**/*.test.ts', '**/*.spec.ts'],
+    excludePatterns: []
+  },
+  risk: {
+    // 风险评估阶段：关注高风险模块的测试
+    mode: 'focus-high-risk',
+    includePatterns: ['**/*.test.ts'],
+    excludePatterns: [],
+    priority: 'high-risk-first'
+  },
+  implementation: {
+    // 代码实现阶段：需要通过的测试
+    mode: 'required-tests',
+    includePatterns: ['**/*.test.ts', '**/*.spec.ts'],
+    excludePatterns: []
+  },
+  commit: {
+    // 提交阶段：验证测试通过
+    mode: 'verify',
+    includePatterns: ['**/*.test.ts', '**/*.spec.ts'],
+    excludePatterns: []
+  },
+  ci: {
+    // CI 阶段：完整测试套件
+    mode: 'full-suite',
+    includePatterns: ['**/*.test.ts', '**/*.spec.ts', '**/*.test.js'],
+    excludePatterns: []
+  }
+};
+```
+
+### 7.2 工作流测试建议生成
+
+```typescript
+class WorkflowTestLinker {
+  /**
+   * 根据当前工作流阶段生成测试建议
+   */
+  getTestSuggestions(
+    phase: WorkflowPhase,
+    sourceFiles: string[],
+    context: WorkflowContext
+  ): TestSuggestion[] {
+    const strategy = PHASE_TEST_STRATEGY[phase];
+    const testFiles = this.findRelatedTests(sourceFiles, strategy);
+
+    return testFiles.map(testFile => ({
+      file: testFile,
+      relevance: this.calculateRelevance(testFile, sourceFiles),
+      action: this.getSuggestedAction(phase, testFile),
+      priority: this.getPriority(phase, testFile, context)
+    }));
+  }
+
+  private getSuggestedAction(phase: WorkflowPhase, testFile: string): string {
+    switch (phase) {
+      case 'reference':
+        return '参考此测试的实现模式';
+      case 'impact':
+        return '修改后需运行此测试';
+      case 'risk':
+        return '重点关注此测试，确保通过';
+      case 'implementation':
+        return '实现完成后运行此测试';
+      case 'commit':
+        return '提交前确保此测试通过';
+      case 'ci':
+        return 'CI 会自动运行此测试';
+    }
+  }
+}
+```
+
+---
+
+## 6. 风险与缓解
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|----------|
+| 测试框架配置解析失败 | 无法关联测试 | 使用默认模式 |
+| 复杂 import 关系 | 关联不准确 | 多种策略组合 |