@mycodemap/mycodemap 0.1.1 → 0.3.4

package/docs/rules/architecture-guardrails.md

@@ -0,0 +1,349 @@
+# 架构护栏规则
+
+> MVP3 分层架构依赖规则与 Enforcement 策略
+
+## 1. 架构分层原则（MVP3）
+
+**第一性原理**：业务逻辑必须与实现细节解耦，确保可测试性和技术栈可替换性。
+
+CodeMap 采用 **MVP3 分层架构**，各层职责如下：
+
+| 层级 | 目录 | 职责 | 允许依赖 |
+|------|------|------|---------|
+| **CLI 层** | `src/cli/` | 命令解析、用户交互、平台检查 | Server, Domain (via Interface), Interface |
+| **Server 层** | `src/server/` | HTTP API 服务器、路由处理、Handler | Domain (via Interface), Interface |
+| **Domain 层** | `src/domain/` | 核心业务逻辑、领域实体、领域服务、领域事件 | Interface |
+| **Infrastructure 层** | `src/infrastructure/` | 技术实现：存储、解析器、仓库实现 | Domain (接口实现), Interface |
+| **Interface 层** | `src/interface/` | 类型定义、契约接口、配置 | 无（纯契约定义） |
+
+### 分层依赖规则
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        CLI Layer                            │
+│  src/cli/ - 命令行接口，注册命令、参数解析、用户交互          │
+├─────────────────────────────────────────────────────────────┤
+│                      Server Layer                           │
+│  src/server/ - HTTP API 服务器，RESTful 端点，Handler 处理    │
+├─────────────────────────────────────────────────────────────┤
+│                       Domain Layer                          │
+│  src/domain/ - 核心业务逻辑，领域实体与服务                   │
+│  - entities/: Project, Module, Symbol, Dependency, CodeGraph │
+│  - services/: CodeGraphBuilder                              │
+│  - events/: DomainEvent                                     │
+│  - repositories/: 仓库接口（仅接口，非实现）                  │
+├─────────────────────────────────────────────────────────────┤
+│                   Infrastructure Layer                      │
+│  src/infrastructure/ - 技术实现细节                          │
+│  - storage/: FileSystemStorage, MemoryStorage, KuzuDBStorage, Neo4jStorage
+│  - parser/: TypeScriptParser, GoParser, PythonParser, ParserRegistry
+│  - repositories/: CodeGraphRepositoryImpl（仓库接口实现）     │
+├─────────────────────────────────────────────────────────────┤
+│                     Interface Layer                         │
+│  src/interface/ - 类型定义与契约，跨层共享的接口              │
+│  - types/: 核心类型定义                                     │
+│  - config/: 配置接口                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**依赖方向**（严格自上而下）：
+- CLI → Server → Domain → Infrastructure → Interface
+- **禁止跨层依赖**（如 Domain 层不得导入 CLI 模块）
+- 同层内可以相互依赖
+
+---
+
+## 2. 与旧架构的关系
+
+### 2.1 历史架构（已迁移）
+
+MVP3 之前的旧架构：
+```
+src/cli/ → src/orchestrator/ → src/core/ → src/parser/
+                                    ↓
+                              src/generator/
+```
+
+### 2.2 迁移映射
+
+| 旧架构 | MVP3 新架构 | 说明 |
+|--------|------------|------|
+| `src/cli/` | `src/cli/` | 保留，职责不变 |
+| `src/orchestrator/` | 功能分散到 Server/CLI | 适配器部分移至 Infrastructure |
+| `src/core/` | `src/domain/` | 核心业务逻辑下沉到 Domain 层 |
+| `src/parser/` | `src/infrastructure/parser/` | 解析器作为基础设施 |
+| `src/generator/` | `src/domain/services/` | 生成逻辑作为领域服务 |
+| `src/types/` | `src/interface/` | 类型定义提升为独立层 |
+| 新增 | `src/server/` | MVP3 新增 HTTP API 层 |
+| 新增 | `src/infrastructure/storage/` | MVP3 新增存储抽象 |
+| 新增 | `src/infrastructure/repositories/` | MVP3 新增仓库实现 |
+
+---
+
+## 3. 依赖流向规则
+
+### 3.1 禁止的依赖方向
+
+```
+Domain ←── 禁止 ── CLI 层不得直接依赖 Domain 具体实现（应通过 Interface）
+Infrastructure ←── 禁止 ── Domain 层不得依赖 Infrastructure 具体实现
+Server ←── 禁止 ── CLI 层不得直接依赖 Server 层（应通过 Interface）
+Interface ←── 禁止 ── 任何层不得修改 Interface 层（只读）
+```
+
+### 3.2 允许的依赖方向
+
+```
+CLI → Server → Domain → Infrastructure → Interface
+CLI → Interface
+Server → Interface
+Domain → Interface
+Infrastructure → Interface
+```
+
+---
+
+## 4. 依赖注入规范
+
+### 4.1 原则
+
+- 高层模块不应依赖低层模块，两者都应依赖抽象（Interface 层契约）
+- 使用构造函数注入或工厂函数注入
+- 禁止在模块内部直接 `new` 高阶服务
+
+### 4.2 合规示例
+
+```typescript
+// ✅ 合规：通过 Interface 层契约注入
+// src/domain/services/CodeGraphBuilder.ts
+import type { IStorage } from '../../interface/types/storage';
+import type { IParserRegistry } from '../../interface/types/parser';
+
+export interface CodeGraphBuilderDeps {
+  storage: IStorage;
+  parserRegistry: IParserRegistry;
+}
+
+export class CodeGraphBuilder {
+  constructor(private deps: CodeGraphBuilderDeps) {}
+  
+  async build(files: string[]) {
+    const parser = this.deps.parserRegistry.getParser('typescript');
+    const ast = await parser.parse(files);
+    return this.deps.storage.save(ast);
+  }
+}
+```
+
+```typescript
+// ❌ 违规：直接实例化 Infrastructure 具体实现
+// src/domain/services/CodeGraphBuilder.ts
+import { FileSystemStorage } from '../../infrastructure/storage/FileSystemStorage';
+import { TypeScriptParser } from '../../infrastructure/parser/implementations/TypeScriptParser';
+
+export class CodeGraphBuilder {
+  private storage = new FileSystemStorage(); // 错误！硬编码实现
+  private parser = new TypeScriptParser();   // 错误！难以测试和替换
+}
+```
+
+---
+
+## 5. 文件组织规范
+
+### 5.1 目录结构（MVP3）
+
+```
+src/
+  cli/                      # CLI 层
+    commands/               # 子命令实现
+    index.ts               # CLI 入口
+  server/                   # Server 层（MVP3 新增）
+    CodeMapServer.ts       # HTTP 服务器
+    handlers/              # 请求处理器
+    routes/                # 路由定义
+  domain/                   # Domain 层
+    entities/              # 领域实体
+      Project.ts
+      Module.ts
+      Symbol.ts
+      Dependency.ts
+      CodeGraph.ts
+    services/              # 领域服务
+      CodeGraphBuilder.ts
+    events/                # 领域事件
+      DomainEvent.ts
+    repositories/          # 仓库接口（仅接口）
+      CodeGraphRepository.ts
+  infrastructure/           # Infrastructure 层
+    storage/               # 存储适配器
+      FileSystemStorage.ts
+      MemoryStorage.ts
+      KuzuDBStorage.ts
+      Neo4jStorage.ts
+      StorageFactory.ts
+    parser/                # 解析器
+      interfaces/
+      implementations/
+      registry/
+    repositories/          # 仓库实现
+      CodeGraphRepositoryImpl.ts
+  interface/                # Interface 层
+    types/                 # 类型定义
+    config/                # 配置接口
+```
+
+### 5.2 文件命名规范
+
+- **实现文件**：`kebab-case.ts`（如 `code-graph-builder.ts`）
+- **接口文件**：`I{PascalCase}.ts`（如 `IStorage.ts`）或 `types.ts`
+- **测试文件**：`{name}.test.ts` 或 `__tests__/{name}.test.ts`
+- **实体文件**：`PascalCase.ts`（如 `CodeGraph.ts`）
+
+---
+
+## 6. Enforcement 策略
+
+### 6.1 自动检测
+
+使用 `dependency-cruiser` 配置架构规则：
+
+```javascript
+// .dependency-cruiser.js（待配置）
+module.exports = {
+  forbidden: [
+    {
+      name: 'no-domain-in-cli',
+      comment: 'CLI 层不得直接依赖 Domain 层（应通过 Interface）',
+      severity: 'error',
+      from: { path: '^src/cli' },
+      to: { path: '^src/domain', pathNot: '^src/domain/[^/]+\.ts$' }
+    },
+    {
+      name: 'no-infrastructure-in-domain',
+      comment: 'Domain 层不得依赖 Infrastructure 层',
+      severity: 'error',
+      from: { path: '^src/domain' },
+      to: { path: '^src/infrastructure' }
+    },
+    {
+      name: 'no-server-in-cli',
+      comment: 'CLI 层不得依赖 Server 层',
+      severity: 'error',
+      from: { path: '^src/cli' },
+      to: { path: '^src/server' }
+    }
+  ]
+};
+```
+
+### 6.2 手动检查
+
+使用 CodeMap CLI 检查模块依赖：
+
+```bash
+# 检查某模块的依赖
+node dist/cli/index.js deps -m "src/domain/services"
+
+# 检查某文件的影响范围
+node dist/cli/index.js impact -f "src/interface/types/index.ts"
+
+# 检查跨层依赖（使用 analyze）
+node dist/cli/index.js analyze -i dependency -t src/domain
+```
+
+### 6.3 CI 检查
+
+在 CI 中添加架构合规检查：
+
+```yaml
+# .github/workflows/ci-gateway.yml
+- name: Check architecture compliance
+  run: npm run check:architecture
+```
+
+---
+
+## 7. 违规处理
+
+### 7.1 发现违规时
+
+1. **暂停任务**：不得继续添加更多代码
+2. **评估影响**：使用 `impact` 命令评估影响范围
+3. **重构方案**：将直接依赖改为接口注入
+4. **验证修复**：重新运行架构检查
+
+### 7.2 临时例外
+
+若因紧急需求必须暂时违规，必须按技术债务标记：
+
+```typescript
+// TODO-DEBT [L2] [日期:2026-03-20] [作者:AI] [原因:紧急修复]
+// 问题：Domain 层临时依赖 Infrastructure 具体实现
+// 风险：破坏分层架构，难以单元测试
+// 偿还计划：提取接口，通过依赖注入传递
+import { FileSystemStorage } from '../infrastructure/storage/FileSystemStorage';
+```
+
+---
+
+## 8. 最佳实践
+
+### 8.1 依赖注入模式
+
+```typescript
+// 推荐：工厂函数模式
+export function createCodeGraphBuilder(deps: Partial<CodeGraphBuilderDeps> = {}) {
+  return new CodeGraphBuilder({
+    storage: deps.storage ?? createStorage(),
+    parserRegistry: deps.parserRegistry ?? createParserRegistry(),
+  });
+}
+
+// 使用
+const builder = createCodeGraphBuilder(); // 生产环境
+const testBuilder = createCodeGraphBuilder({ storage: mockStorage }); // 测试环境
+```
+
+### 8.2 接口定义位置
+
+- 接口定义在 **Interface 层**（`src/interface/`）
+- 或定义在被依赖方的接口目录
+
+```typescript
+// src/interface/types/storage.ts
+export interface IStorage {
+  save(data: unknown): Promise<void>;
+  load(): Promise<unknown>;
+}
+
+// src/infrastructure/storage/FileSystemStorage.ts
+import type { IStorage } from '../../interface/types/storage';
+export class FileSystemStorage implements IStorage { ... }
+
+// src/domain/services/CodeGraphBuilder.ts
+import type { IStorage } from '../../interface/types/storage';
+export class CodeGraphBuilder {
+  constructor(private storage: IStorage) {}
+}
+```
+
+---
+
+## 9. 验证清单
+
+修改架构相关代码前，检查：
+
+- [ ] 新模块的依赖方向是否符合 MVP3 分层规则
+- [ ] 是否使用了依赖注入而非直接实例化
+- [ ] 接口定义是否在 Interface 层
+- [ ] 是否可以通过 `check:architecture` 验证
+
+---
+
+## 10. 相关文档
+
+- `ARCHITECTURE.md` - 系统总图与模块边界
+- `docs/rules/engineering-with-codex-openai.md` - 工程规则与 CI 护栏
+- `docs/rules/code-quality-redlines.md` - 代码质量红线
+- `docs/exec-plans/MVP3-IMPLEMENTATION-ROADMAP.md` - MVP3 重构路线图

package/docs/rules/code-quality-redlines.md

@@ -0,0 +1,321 @@
+# 代码质量红线
+
+> 代码生成绝对禁止项清单与 Enforcement 策略
+
+## 1. 红线总则
+
+以下代码模式在 CodeMap 仓库中被视为**硬性阻断项**。AI 生成代码时必须主动避免，否则必须在可信度自评中标记风险。
+
+**红线判定标准**：
+- 可能导致安全漏洞
+- 严重降低代码可维护性
+- 破坏类型安全保证
+- 违反架构分层原则
+
+## 2. 红线清单
+
+### 2.1 敏感信息硬编码
+
+**禁止模式**：
+```typescript
+// ❌ 绝对禁止
+const API_KEY = "sk-abc123xyz";
+const password = "admin123";
+const secret = "my-jwt-secret";
+```
+
+**合规模式**：
+```typescript
+// ✅ 使用环境变量
+const API_KEY = process.env.OPENAI_API_KEY;
+if (!API_KEY) {
+  throw new Error('OPENAI_API_KEY is required');
+}
+```
+
+**检测方式**：
+```bash
+# 正则检测敏感信息字面量
+grep -rn "password.*=.*['\"]" src/ --include="*.ts"
+grep -rn "secret.*=.*['\"]" src/ --include="*.ts"
+grep -rn "api_key.*=.*['\"]" src/ --include="*.ts"
+```
+
+**阻断阈值**：生产代码中出现任何明文凭证
+
+### 2.2 `any` 类型使用
+
+**禁止模式**：
+```typescript
+// ❌ 非边界文件禁止使用 any
+function processData(data: any): any {
+  return data.value;
+}
+```
+
+**合规模式**：
+```typescript
+// ✅ 使用具体类型或 unknown + 类型守卫
+interface DataPayload {
+  value: string;
+}
+
+function processData(data: unknown): string {
+  if (typeof data === 'object' && data !== null && 'value' in data) {
+    return (data as DataPayload).value;
+  }
+  throw new Error('Invalid data format');
+}
+```
+
+**例外情况**（需标记 TODO-DEBT）：
+- 第三方库无类型定义时的临时处理
+- 与遗留系统集成的边界
+
+**检测方式**：
+```bash
+# TypeScript 编译器检查
+npx tsc --noImplicitAny --noEmit
+
+# ESLint 检查
+npx eslint src --rule '@typescript-eslint/no-explicit-any: error'
+```
+
+**阻断阈值**：非边界文件出现 `any` 类型
+
+### 2.3 函数超过 50 行
+
+**计算方式**：函数体实际代码行数（不含空行、注释、类型定义）
+
+**禁止模式**：
+```typescript
+// ❌ 超过 50 行的函数
+function complexFunction(data: Data) {
+  // 行 1
+  // 行 2
+  // ... 50+ 行
+  // 行 51
+  // 行 52
+}
+```
+
+**合规模式**：
+```typescript
+// ✅ 拆分为子函数
+function complexFunction(data: Data) {
+  const validated = validateData(data);
+  const transformed = transformData(validated);
+  return persistData(transformed);
+}
+
+function validateData(data: Data): ValidatedData { ... }
+function transformData(data: ValidatedData): TransformedData { ... }
+function persistData(data: TransformedData): Result { ... }
+```
+
+**检测方式**：
+```bash
+# 使用 ESLint 的 max-lines-per-function 规则
+npx eslint src --rule 'max-lines-per-function: [error, { max: 50, skipBlankLines: true, skipComments: true }]'
+```
+
+**阻断阈值**：单函数超过 50 行代码
+
+### 2.4 未处理 Promise
+
+**禁止模式**：
+```typescript
+// ❌ 未处理的异步操作
+fetchUserData(userId); // 没有 await 或 .catch()
+database.query(sql);   // 没有错误处理
+```
+
+**合规模式**：
+```typescript
+// ✅ 正确处理异步操作
+try {
+  const user = await fetchUserData(userId);
+} catch (error) {
+  logger.error('Failed to fetch user', error);
+  throw new UserFetchError(userId);
+}
+
+// 或显式忽略
+void fetchUserData(userId).catch(() => {}); // 有意的显式忽略
+```
+
+**检测方式**：
+```bash
+# ESLint 检查
+npx eslint src --rule '@typescript-eslint/no-floating-promises: error'
+```
+
+**阻断阈值**：未使用 `await` 或未附加错误处理的 Promise
+
+### 2.5 `console.log` 遗留代码
+
+**禁止模式**：
+```typescript
+// ❌ 生产代码中的调试语句
+console.log('Debug:', data);
+console.warn('Warning');
+```
+
+**合规模式**：
+```typescript
+// ✅ 使用 runtime-logger
+import { runtimeLogger } from '../cli/runtime-logger';
+runtimeLogger.debug('Debug:', data);
+runtimeLogger.warn('Warning');
+```
+
+**例外情况**：
+- `src/cli/runtime-logger.ts` 本身
+- 临时调试代码（提交前必须删除）
+
+**检测方式**：
+```bash
+# ESLint 检查
+npx eslint src --rule 'no-console: [error, { allow: ["error"] }]'
+```
+
+**阻断阈值**：非 logger 模块出现 `console.log`
+
+### 2.6 未使用 Import
+
+**禁止模式**：
+```typescript
+// ❌ 导入但未使用
+import { unusedFunction } from './utils';
+import type { UnusedType } from './types';
+
+export function doSomething() {
+  // 未使用上面的导入
+}
+```
+
+**合规模式**：
+```typescript
+// ✅ 删除未使用的导入
+export function doSomething() {
+  // 干净的代码
+}
+```
+
+**检测方式**：
+```bash
+# TypeScript 检查
+npx tsc --noUnusedLocals --noEmit
+
+# ESLint 检查
+npx eslint src --rule '@typescript-eslint/no-unused-vars: [error, { argsIgnorePattern: "^_" }]'
+```
+
+**阻断阈值**：存在未使用的 import 或变量
+
+### 2.7 缺少文件头注释
+
+**禁止模式**：
+```typescript
+// ❌ 缺少 META 和 WHY 注释
+export function analyze() { ... }
+```
+
+**合规模式**：
+```typescript
+// [META] since:2026-03 | owner:team | stable:false
+// [WHY] 分析器主入口，负责协调解析和生成流程
+export function analyze() { ... }
+```
+
+**检测方式**：
+```bash
+# pre-commit hook 自动检查
+# 或手动检查
+grep -L "\[META\]" src/**/*.ts | grep -v ".test.ts" | grep -v ".d.ts"
+```
+
+**阻断阈值**：TS 源文件缺少 `[META]` 或 `[WHY]` 注释
+
+## 3. 检测自动化
+
+### 3.1 集成到 CI
+
+```yaml
+# .github/workflows/ci-gateway.yml
+- name: Check code quality redlines
+  run: |
+    npx eslint src \
+      --rule '@typescript-eslint/no-explicit-any: error' \
+      --rule '@typescript-eslint/no-floating-promises: error' \
+      --rule 'no-console: [error, { allow: ["error"] }]'
+```
+
+### 3.2 本地检查脚本
+
+```json
+// package.json
+{
+  "scripts": {
+    "check:redlines": "npm run check:types && npm run check:lint",
+    "check:types": "tsc --noImplicitAny --noUnusedLocals --noEmit",
+    "check:lint": "eslint src --ext .ts"
+  }
+}
+```
+
+## 4. 自动修复策略
+
+| 红线 | 自动修复 | 修复命令 |
+|------|---------|---------|
+| `any` 类型 | 部分可行 | 使用类型推导工具（如 TS 语言服务） |
+| 未使用 import | 完全可行 | `eslint --fix` |
+| `console.log` | 部分可行 | 替换为 logger 引用（需人工确认） |
+| 函数长度 | 不可行 | 需人工重构 |
+| 未处理 Promise | 部分可行 | 添加 `await` 或 `.catch()`（需人工确认逻辑） |
+| 敏感信息 | 不可行 | 需人工替换为环境变量 |
+| 缺少文件头 | 部分可行 | 使用代码片段模板 |
+
+## 5. 例外处理
+
+### 5.1 技术债务标记
+
+若因特殊原因必须违反红线，必须标记为技术债务：
+
+```typescript
+// TODO-DEBT [L1] [日期:2026-03-17] [作者:AI] [原因:第三方库无类型定义]
+// 问题：被迫使用 any 类型处理无类型的第三方库
+// 风险：丢失类型安全
+// 偿还计划：提交 PR 给第三方库添加类型定义，或使用 @types 包
+function handleLegacyAPI(response: any): any {
+  return response.data;
+}
+```
+
+### 5.2 边界文件例外
+
+以下文件类型允许适当的灵活性：
+- 测试文件（`.test.ts`）
+- 类型声明文件（`.d.ts`）
+- 配置文件（如 `vitest.config.ts`）
+- 脚本文件（`scripts/` 目录）
+
+## 6. 验收检查清单
+
+提交代码前检查：
+
+- [ ] 无敏感信息硬编码
+- [ ] 无 `any` 类型（或已标记 TODO-DEBT）
+- [ ] 函数长度 <= 50 行（或已拆分为子函数）
+- [ ] 所有 Promise 都有错误处理
+- [ ] 无 `console.log` 遗留
+- [ ] 无未使用的 import
+- [ ] TS 源文件有 `[META]` 和 `[WHY]` 注释
+- [ ] `npm run check:redlines` 通过
+
+## 7. 相关文档
+
+- `AGENTS.md` - 任务分级与可信度自评
+- `CLAUDE.md` - 执行清单与验收标准
+- `docs/rules/engineering-with-codex-openai.md` - 工程规则
+- `docs/rules/architecture-guardrails.md` - 架构护栏

package/docs/rules/deployment.md

@@ -0,0 +1,23 @@
+# 发布与打包规则
+
+## 适用范围
+
+本项目当前主要交付形态是 npm 包与 CLI，而不是长期运行的服务部署。
+
+## 发布前检查
+
+- 运行 `npm run build`，确保 `dist/` 产物可生成。
+- 运行 `npm test`，确保核心行为未回退。
+- 运行 `npm run validate-pack`，检查打包内容。
+- 核对 `package.json` 中 `files`、`bin`、`exports` 是否与真实产物一致。
+
+## 当前事实
+
+- CLI bin：`dist/cli/index.js`
+- 库入口：`dist/index.js`
+- `prepublishOnly` 已要求构建并测试
+
+## 禁止事项
+
+- 不得通过跳过测试或伪造产物完成发布。
+- 不得把只存在于本地的临时输出目录当成发布事实。