@mycodemap/mycodemap 0.4.1 → 0.5.0

package/docs/ai-guide/OUTPUT.md

@@ -4,7 +4,18 @@
 
 ---
 
-## 何时使用 --json
+## Phase 1 契约基线
+
+| 维度 | 目标态 | 当前 CLI 现实 |
+|------|--------|---------------|
+| 机器可读 | 机器可读优先，适合 AI/Agent 继续处理 | 多数命令仍通过 `--json` 显式返回结构化结果 |
+| 人类可读 | 显式的人类阅读入口 | `analyze` 当前支持 `--output-mode human`，其余命令多保留现有文本输出 |
+| analyze 收敛 | 输出契约应逐步收敛 | 当前公共契约已固定为 `find` / `read` / `link` / `show`，legacy alias 通过 `warnings[]` 暴露迁移提示 |
+| 文件发现 | 扫描类命令共享一个文件发现模块 | 先尊重仓库 `.gitignore`，无 `.gitignore` 时回退到默认 `exclude` |
+
+---
+
+## 当前 CLI 现实：何时使用 --json
 
 | 场景 | 使用 `--json` | 原因 |
 |------|--------------|------|
@@ -17,6 +28,88 @@
 
 ---
 
+## 文件发现契约
+
+```typescript
+type DiscoveryFallbackExclude =
+  | "node_modules/**"
+  | "dist/**"
+  | "build/**"
+  | "coverage/**"
+  | "**/*.test.ts"
+  | "**/*.spec.ts"
+  | "**/*.d.ts";
+
+interface DiscoveryContract {
+  gitignore: true;
+  fallbackExclude: DiscoveryFallbackExclude[];
+  sharedBy: ["generate", "analyze", "ci check-headers -d"];
+}
+```
+
+> `generate`、`analyze` 与 `ci check-headers -d` 会共享同一个文件发现模块；若仓库没有 `.gitignore`，则回退到上面的默认排除列表。
+
+---
+
+## generate / codemap.json 插件扩展字段
+
+> 仅当 `mycodemap.config.json` **显式声明** `plugins` 段时，`generate` 输出才会包含 `pluginReport`。
+
+```typescript
+interface PluginDiagnostic {
+  plugin?: string;
+  stage: "load" | "initialize" | "analyze" | "generate";
+  level: "warning" | "error";
+  message: string;
+}
+
+interface PluginExecutionReport {
+  loadedPlugins: string[];
+  generatedFiles: string[];
+  metrics: Record<string, unknown>;
+  diagnostics: PluginDiagnostic[];
+}
+
+interface CodeMap {
+  version: string;
+  generatedAt: string;
+  project: ProjectInfo;
+  summary: ProjectSummary;
+  modules: ModuleInfo[];
+  dependencies: DependencyGraph;
+  actualMode?: "fast" | "smart";
+  pluginReport?: PluginExecutionReport;
+}
+```
+
+### 示例
+
+```json
+{
+  "pluginReport": {
+    "loadedPlugins": ["complexity-analyzer", "my-local-plugin"],
+    "generatedFiles": ["plugins/good.txt"],
+    "metrics": {
+      "complexity-analyzer": {
+        "complexityAnalysis": {
+          "totalCyclomaticComplexity": 17
+        }
+      }
+    },
+    "diagnostics": [
+      {
+        "plugin": "my-local-plugin",
+        "stage": "analyze",
+        "level": "warning",
+        "message": "my-local-plugin warning"
+      }
+    ]
+  }
+}
+```
+
+---
+
 ## query 命令输出结构
 
 ### JSON 输出 (-j)
@@ -101,18 +194,24 @@ interface ContextLine {
 
 ## analyze 命令输出结构
 
+> 当前 `analyze` 的公共契约为 `find` / `read` / `link` / `show`；legacy alias 会在输出中返回 `warnings[]`，其中 `refactor` 不在兼容白名单内。
+
 ### 标准 JSON 输出 (--json)
 
 ```typescript
+type AnalyzeIntent = "find" | "read" | "link" | "show";
+
 interface AnalyzeOutput {
   schemaVersion: "v1.0.0";
-  intent: "impact" | "dependency" | "search" | "documentation" | "complexity" | "overview" | "refactor" | "reference";
+  intent: AnalyzeIntent;
   tool: string;
   confidence: {
     score: number;        // 0.0 - 1.0
     level: "high" | "medium" | "low";
   };
   results: AnalyzeResult[];
+  warnings?: AnalyzeWarning[];
+  analysis?: ReadAnalysis | LinkAnalysis | ShowAnalysis;
   metadata: {
     total: number;
     scope: "direct" | "transitive";
@@ -120,6 +219,15 @@ interface AnalyzeOutput {
   };
 }
 
+interface AnalyzeWarning {
+  code: "deprecated-intent";
+  severity: "warning";
+  message: string;
+  deprecatedIntent: "impact" | "dependency" | "search" | "documentation" | "complexity" | "overview" | "reference";
+  replacementIntent: AnalyzeIntent;
+  sunsetPolicy: "2-minor-window";
+}
+
 interface AnalyzeResult {
   file: string;
   location?: {
@@ -131,10 +239,66 @@ interface AnalyzeResult {
   relevance: number;        // 0.0 - 1.0
   metadata?: {
     testFile?: string;      // 关联的测试文件
-    complexity?: number;    // 复杂度分数
-    [key: string]: any;
+    dependencies?: string[];
+    impactCount?: number;
+    complexityMetrics?: {
+      cyclomatic: number;
+      cognitive: number;
+      maintainability: number;
+    };
+    riskLevel?: "high" | "medium" | "low";
+    [key: string]: unknown;
   };
 }
+
+interface ReadAnalysis {
+  intent: "read";
+  impact?: Array<{
+    file: string;
+    changedFiles: string[];
+    transitiveDependencies: string[];
+    impactCount: number;
+    risk: "high" | "medium" | "low";
+  }>;
+  complexity?: Array<{
+    file: string;
+    metrics: {
+      cyclomatic: number;
+      cognitive: number;
+      maintainability: number;
+    };
+    risk: "high" | "medium" | "low";
+  }>;
+}
+
+interface LinkAnalysis {
+  intent: "link";
+  reference?: Array<{
+    target: string;
+    callers: string[];
+    callees: string[];
+  }>;
+  dependency?: Array<{
+    file: string;
+    imports: string[];
+    importedBy: string[];
+  }>;
+}
+
+interface ShowAnalysis {
+  intent: "show";
+  overview?: Array<{
+    title: string;
+    file: string;
+    overview: string;
+    exports: string[];
+  }>;
+  documentation?: Array<{
+    title: string;
+    file: string;
+    content: string;
+  }>;
+}
 ```
 
 ### 纯结构化输出 (--structured --json)
@@ -144,13 +308,15 @@ interface AnalyzeResult {
 ```typescript
 interface StructuredAnalyzeOutput {
   schemaVersion: "v1.0.0";
-  intent: string;
+  intent: AnalyzeIntent;
   tool: string;
   confidence: {
     score: number;
     level: "high" | "medium" | "low";
   };
   results: StructuredResult[];
+  warnings?: AnalyzeWarning[];
+  analysis?: ReadAnalysis | LinkAnalysis | ShowAnalysis;
   metadata: {
     total: number;
     scope: string;
@@ -168,7 +334,7 @@ interface StructuredResult {
   // 注意：没有 content 字段
   relevance: number;
   metadata?: {
-    [key: string]: any;
+    [key: string]: unknown;
   };
 }
 ```
@@ -178,12 +344,22 @@ interface StructuredResult {
 ```json
 {
   "schemaVersion": "v1.0.0",
-  "intent": "impact",
-  "tool": "codemap-impact",
+  "intent": "read",
+  "tool": "codemap-read",
   "confidence": {
     "score": 0.85,
     "level": "high"
   },
+  "warnings": [
+    {
+      "code": "deprecated-intent",
+      "severity": "warning",
+      "message": "legacy intent \"impact\" 已弃用，请改用 \"read\"",
+      "deprecatedIntent": "impact",
+      "replacementIntent": "read",
+      "sunsetPolicy": "2-minor-window"
+    }
+  ],
   "results": [
     {
       "file": "src/cli/commands/analyze.ts",
@@ -192,13 +368,33 @@ interface StructuredResult {
         "line": 45,
         "column": 1
       },
-      "content": "导入自 src/orchestrator/intent-router.ts 的 IntentRouter 类",
+      "content": "被 3 个模块依赖",
       "relevance": 0.95,
       "metadata": {
-        "testFile": "src/cli/commands/analyze.test.ts"
+        "impactCount": 3,
+        "dependencies": [
+          "src/orchestrator/intent-router.ts"
+        ],
+        "riskLevel": "medium"
       }
     }
   ],
+  "analysis": {
+    "intent": "read",
+    "impact": [
+      {
+        "file": "src/cli/commands/analyze.ts",
+        "changedFiles": [
+          "src/cli/commands/analyze.ts"
+        ],
+        "transitiveDependencies": [
+          "src/orchestrator/intent-router.ts"
+        ],
+        "impactCount": 3,
+        "risk": "medium"
+      }
+    ]
+  },
   "metadata": {
     "total": 8,
     "scope": "transitive",
@@ -209,6 +405,421 @@ interface StructuredResult {
 
 ---
 
+## design validate 命令输出结构
+
+### JSON 输出 (--json)
+
+```typescript
+type DesignContractSectionId =
+  | "goal"
+  | "constraints"
+  | "acceptanceCriteria"
+  | "nonGoals"
+  | "context"
+  | "openQuestions"
+  | "notes";
+
+type DesignContractDiagnosticCode =
+  | "file-not-found"
+  | "missing-section"
+  | "duplicate-section"
+  | "empty-section"
+  | "unknown-section"
+  | "ambiguous-heading";
+
+interface DesignValidateOutput {
+  ok: boolean;
+  exists: boolean;
+  filePath: string;
+  title?: string;
+  missingRequiredSections: Array<"goal" | "constraints" | "acceptanceCriteria" | "nonGoals">;
+  diagnostics: DesignContractDiagnostic[];
+  sections: Array<{
+    id: DesignContractSectionId;
+    title: string;
+    line: number;
+    itemCount: number;
+  }>;
+}
+
+interface DesignContractDiagnostic {
+  code: DesignContractDiagnosticCode;
+  severity: "error" | "warning" | "info";
+  message: string;
+  section?: DesignContractSectionId;
+  heading?: string;
+  line?: number;
+  suggestion?: string;
+}
+```
+
+### 示例
+
+```json
+{
+  "ok": false,
+  "exists": true,
+  "filePath": "/repo/mycodemap.design.md",
+  "title": "Design Contract: Missing acceptance example",
+  "missingRequiredSections": [
+    "acceptanceCriteria"
+  ],
+  "diagnostics": [
+    {
+      "code": "missing-section",
+      "severity": "error",
+      "message": "缺少必填 section: Acceptance Criteria",
+      "section": "acceptanceCriteria"
+    }
+  ],
+  "sections": [
+    {
+      "id": "goal",
+      "title": "Goal",
+      "line": 3,
+      "itemCount": 1
+    }
+  ]
+}
+```
+
+> `design validate --json` 必须保持纯 JSON；不要在前后拼接说明性 prose。
+
+---
+
+## design map 命令输出结构
+
+### JSON 输出 (--json)
+
+```typescript
+type DesignMappingCandidateKind = "file" | "module" | "symbol";
+
+type DesignMappingDiagnosticCode =
+  | "no-candidates"
+  | "over-broad-scope"
+  | "high-risk-scope"
+  | string;
+
+interface DesignMappingReason {
+  section: DesignContractSectionId;
+  matchedText: string;
+  evidenceType: string;
+}
+
+interface DesignMappingCandidate {
+  kind: DesignMappingCandidateKind;
+  path: string;
+  moduleName?: string;
+  symbolName?: string;
+  reasons: DesignMappingReason[];
+  dependencies: string[];
+  testImpact: string[];
+  risk: "high" | "medium" | "low";
+  confidence: {
+    score: number;
+    level: "high" | "medium" | "low";
+  };
+  unknowns: string[];
+}
+
+interface DesignMappingDiagnostic {
+  code: DesignMappingDiagnosticCode;
+  severity: "error" | "warning" | "info";
+  blocker: boolean;
+  message: string;
+  candidatePaths?: string[];
+}
+
+interface DesignMapOutput {
+  ok: boolean;
+  filePath: string;
+  summary: {
+    candidateCount: number;
+    blocked: boolean;
+    unknownCount: number;
+    diagnosticCount: number;
+  };
+  candidates: DesignMappingCandidate[];
+  diagnostics: DesignMappingDiagnostic[];
+}
+```
+
+### 示例
+
+```json
+{
+  "ok": false,
+  "filePath": "/repo/mycodemap.design.md",
+  "summary": {
+    "candidateCount": 1,
+    "blocked": true,
+    "unknownCount": 0,
+    "diagnosticCount": 1
+  },
+  "candidates": [
+    {
+      "kind": "file",
+      "path": "src/cli/commands/analyze.ts",
+      "reasons": [
+        {
+          "section": "goal",
+          "matchedText": "src/cli/commands/analyze.ts",
+          "evidenceType": "path-anchor"
+        }
+      ],
+      "dependencies": [],
+      "testImpact": [],
+      "risk": "high",
+      "confidence": {
+        "score": 0.92,
+        "level": "high"
+      },
+      "unknowns": []
+    }
+  ],
+  "diagnostics": [
+    {
+      "code": "high-risk-scope",
+      "severity": "error",
+      "blocker": true,
+      "message": "候选范围命中了高 blast-radius 文件；请先补充更具体的 design scope，再继续执行。"
+    }
+  ]
+}
+```
+
+> `design map --json` 必须保持纯 JSON；不要在前后拼接说明性 prose。`unknowns` 与 `diagnostics` 都属于正式契约，不是可选注释。
+
+---
+
+## design handoff 命令输出结构
+
+### JSON 输出 (--json)
+
+```typescript
+type DesignHandoffApprovalStatus = "approved" | "needs-review";
+
+interface DesignHandoffTraceItem {
+  id: string;
+  text: string;
+  sourceRefs: string[];
+}
+
+interface DesignHandoffOutput {
+  ok: boolean;
+  filePath: string;
+  outputDir: string;
+  readyForExecution: boolean;
+  artifacts: {
+    markdownPath: string;
+    jsonPath: string;
+  };
+  summary: {
+    approvalCount: number;
+    assumptionCount: number;
+    openQuestionCount: number;
+    requiresReview: boolean;
+  };
+  handoff: {
+    touchedFiles: string[];
+    constraints: string[];
+    tests: string[];
+    approvals: Array<DesignHandoffTraceItem & {
+      status: DesignHandoffApprovalStatus;
+    }>;
+    assumptions: DesignHandoffTraceItem[];
+    openQuestions: DesignHandoffTraceItem[];
+  };
+  diagnostics: Array<{
+    code: "blocked-mapping" | "review-required" | string;
+    blocker: boolean;
+    message: string;
+  }>;
+}
+```
+
+### 示例
+
+```json
+{
+  "ok": true,
+  "filePath": "/repo/mycodemap.design.md",
+  "outputDir": "/repo/.mycodemap/handoffs",
+  "readyForExecution": false,
+  "artifacts": {
+    "markdownPath": "/repo/.mycodemap/handoffs/mycodemap.handoff.md",
+    "jsonPath": "/repo/.mycodemap/handoffs/mycodemap.handoff.json"
+  },
+  "summary": {
+    "approvalCount": 4,
+    "assumptionCount": 1,
+    "openQuestionCount": 1,
+    "requiresReview": true
+  },
+  "handoff": {
+    "touchedFiles": [
+      "src/cli/design-handoff-builder.ts"
+    ],
+    "constraints": [
+      "默认 artifact path 必须复用 src/cli/paths.ts"
+    ],
+    "tests": [
+      "src/cli/__tests__/design-handoff-builder.test.ts"
+    ],
+    "approvals": [
+      {
+        "id": "approved-goal",
+        "status": "approved",
+        "text": "Goal 已被纳入 handoff 事实输入",
+        "sourceRefs": ["design:goal"]
+      }
+    ],
+    "assumptions": [
+      {
+        "id": "assumption-1-1",
+        "text": "需要补充 reviewer 对未知范围的确认",
+        "sourceRefs": ["candidate:src/cli/design-handoff-builder.ts"]
+      }
+    ],
+    "openQuestions": [
+      {
+        "id": "open-question-1",
+        "text": "低风险 assumptions 是否也必须显式批准？",
+        "sourceRefs": ["design:openQuestions"]
+      }
+    ]
+  },
+  "diagnostics": [
+    {
+      "code": "review-required",
+      "blocker": false,
+      "message": "Handoff generated successfully but still requires human review before execution."
+    }
+  ]
+}
+```
+
+> `design handoff --json` 必须保持纯 JSON；`readyForExecution`、`approvals`、`assumptions`、`openQuestions` 都属于正式契约。human mode 默认写出 `.mycodemap/handoffs/{stem}.handoff.md|json`。
+
+---
+
+## design verify 命令输出结构
+
+### JSON 输出 (--json)
+
+```typescript
+type DesignVerificationStatus =
+  | "satisfied"
+  | "needs-review"
+  | "violated"
+  | "blocked";
+
+type DesignDriftKind =
+  | "scope-extra"
+  | "acceptance-unverified"
+  | "handoff-missing"
+  | "blocked-input";
+
+interface DesignVerificationOutput {
+  ok: boolean;
+  filePath: string;
+  readyForExecution: boolean;
+  summary: {
+    checklistCount: number;
+    satisfiedCount: number;
+    needsReviewCount: number;
+    violatedCount: number;
+    blockedCount: number;
+    driftCount: number;
+    diagnosticCount: number;
+    reviewRequired: boolean;
+    blocked: boolean;
+  };
+  checklist: Array<{
+    id: string;
+    text: string;
+    status: DesignVerificationStatus;
+    evidenceRefs: string[];
+  }>;
+  drift: Array<{
+    kind: DesignDriftKind;
+    severity: "error" | "warning" | "info";
+    message: string;
+    sourceRefs: string[];
+  }>;
+  diagnostics: Array<{
+    code: "handoff-missing" | "handoff-invalid" | "blocked-input" | string;
+    blocker: boolean;
+    message: string;
+    sourceRefs: string[];
+  }>;
+}
+```
+
+### 示例
+
+```json
+{
+  "ok": true,
+  "filePath": "/repo/tests/fixtures/design-contracts/verify-ready.design.md",
+  "readyForExecution": false,
+  "summary": {
+    "checklistCount": 3,
+    "satisfiedCount": 1,
+    "needsReviewCount": 2,
+    "violatedCount": 0,
+    "blockedCount": 0,
+    "driftCount": 3,
+    "diagnosticCount": 1,
+    "reviewRequired": true,
+    "blocked": false
+  },
+  "checklist": [
+    {
+      "id": "acceptance-1",
+      "text": "src/cli/design-verification-builder.ts 会产出 conservative verification result",
+      "status": "satisfied",
+      "evidenceRefs": [
+        "candidate:src/cli/design-verification-builder.ts",
+        "diagnostic:handoff-missing"
+      ]
+    },
+    {
+      "id": "acceptance-2",
+      "text": "src/interface/types/design-verification.ts 会定义正式 verification schema",
+      "status": "needs-review",
+      "evidenceRefs": [
+        "design:acceptanceCriteria"
+      ]
+    }
+  ],
+  "drift": [
+    {
+      "kind": "handoff-missing",
+      "severity": "warning",
+      "message": "Canonical handoff artifact is missing, so verification remains review-needed even though a live handoff was rebuilt.",
+      "sourceRefs": [
+        "diagnostic:handoff-missing"
+      ]
+    }
+  ],
+  "diagnostics": [
+    {
+      "code": "handoff-missing",
+      "blocker": false,
+      "message": "Canonical handoff artifact is missing, so verification remains review-needed even though a live handoff was rebuilt.",
+      "sourceRefs": [
+        "diagnostic:handoff-missing"
+      ]
+    }
+  ]
+}
+```
+
+> `design verify --json` 必须保持纯 JSON；`checklist` 与 `drift` 都属于正式契约。`readyForExecution=false` 不等于 blocker，只有 `ok=false` 或 blocker diagnostics 才应返回非零 exit code。
+
+---
+
 ## impact 命令输出结构
 
 ### JSON 输出 (-j)