@mycodemap/mycodemap 0.4.2 → 0.5.0

package/dist/orchestrator/ai-feed-generator.js

@@ -0,0 +1,377 @@
+// [META] since:2026-03-02 | owner:orchestrator-team | stable:true
+// [WHY] AI feed generator with date format alignment for JSON serialization
+/**
+ * AI Feed Generator
+ * Generates structured data for AI consumption (ai-feed.txt)
+ * Provides code metadata, dependency complexity, modification heat, etc.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { globby } from 'globby';
+/**
+ * File header comment scanner
+ * Scans [META]/[WHY]/[DEPS] comments at the top of files
+ */
+export class FileHeaderScanner {
+    /**
+     * Scan file header comments
+     * Only reads first 10 lines of the file
+     *
+     * @param filePath - Full file path
+     * @returns FileMeta parsing result
+     */
+    scan(filePath) {
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const lines = content.split('\n').slice(0, 10);
+            const header = lines.join('\n');
+            return this.parseHeader(header);
+        }
+        catch {
+            // Return empty object on read failure
+            return {};
+        }
+    }
+    /**
+     * Parse file header content string (public for testing)
+     * Alias for parseHeaderContent for backward compatibility
+     *
+     * @param header - File header content (first 10 lines as string)
+     * @returns FileMeta parsing result with flat structure
+     */
+    parseHeader(header) {
+        return this.parseHeaderContent(header);
+    }
+    /**
+     * Parse file header content (public for testing)
+     * Returns nested structure for backward compatibility with tests
+     *
+     * @param header - File header content (first 10 lines)
+     * @returns FileHeader parsing result with nested meta
+     */
+    parseHeaderContent(header) {
+        const result = {};
+        // Parse [META]
+        const metaMatch = header.match(/\/\/\s*\[META\]\s*(.+)/);
+        if (metaMatch) {
+            const metaStr = metaMatch[1];
+            result.meta = {
+                since: metaStr.match(/since:(\S+)/)?.[1],
+                owner: metaStr.match(/owner:(\S+)/)?.[1],
+                stable: metaStr.includes('stable:true')
+            };
+            // Also set flat properties for compatibility
+            result.since = result.meta.since;
+            result.owner = result.meta.owner;
+            result.stable = result.meta.stable;
+        }
+        // Parse [WHY]
+        const whyMatch = header.match(/\/\/\s*\[WHY\]\s*(.+)/);
+        if (whyMatch) {
+            result.why = whyMatch[1].trim();
+        }
+        // Parse [DEPS]
+        const depsMatch = header.match(/\/\/\s*\[DEPS\]\s*(.+)/);
+        if (depsMatch) {
+            result.deps = depsMatch[1]
+                .split(',')
+                .map(d => d.trim())
+                .filter(d => d.length > 0);
+        }
+        return result;
+    }
+    /**
+     * Validate file header completeness
+     * Used by CI gateway
+     *
+     * @param filePath - File path
+     * @returns Validation result
+     */
+    validate(filePath) {
+        const meta = this.scan(filePath);
+        const missing = [];
+        if (!meta.since) {
+            missing.push('[META] since');
+        }
+        if (!meta.why) {
+            missing.push('[WHY]');
+        }
+        return {
+            valid: missing.length === 0,
+            missing
+        };
+    }
+}
+/**
+ * AI Feed Generator class
+ * Generates structured data for AI consumption
+ */
+export class AIFeedGenerator {
+    gitAnalyzer;
+    headerScanner;
+    /**
+     * Constructor
+     *
+     * @param gitAnalyzer - GitAnalyzer instance
+     */
+    constructor(gitAnalyzer) {
+        this.gitAnalyzer = gitAnalyzer;
+        this.headerScanner = new FileHeaderScanner();
+    }
+    /**
+     * Generate AI feed
+     * Integrated into codemap generate command
+     *
+     * @param projectRoot - Project root directory
+     * @param options - Generation options
+     * @param options.includeGitHistory - Whether to include Git history analysis (default: false)
+     * @returns AIFeed[] feed list (sorted by gravity descending)
+     */
+    async generate(projectRoot, options) {
+        const includeGitHistory = options?.includeGitHistory ?? false;
+        // 1. Get all TypeScript files
+        const files = await globby(['src/**/*.ts'], {
+            cwd: projectRoot,
+            ignore: ['**/*.d.ts', '**/node_modules/**', '**/dist/**']
+        });
+        const feed = [];
+        // 2. First pass: collect basic info
+        for (const file of files) {
+            const fullPath = path.join(projectRoot, file);
+            // Skip non-existent files (globby may return deleted files)
+            if (!fs.existsSync(fullPath)) {
+                continue;
+            }
+            const header = this.headerScanner.scan(fullPath);
+            // Only scan Git history if explicitly enabled
+            const heat = includeGitHistory
+                ? await this.scanGitHistory(file, projectRoot)
+                : { freq30d: 0, lastType: 'unknown', lastDate: null, stability: true };
+            feed.push({
+                file,
+                gravity: 0, // Will be calculated in second pass
+                heat,
+                meta: {
+                    since: header.since,
+                    owner: header.owner,
+                    stable: header.stable,
+                    why: header.why
+                },
+                deps: header.deps ?? [],
+                dependents: []
+            });
+        }
+        // 3. Second pass: calculate dependencies
+        this.calculateDependencies(feed, projectRoot);
+        // 4. Sort by gravity descending
+        return feed.sort((a, b) => b.gravity - a.gravity);
+    }
+    /**
+     * Output AI feed file
+     *
+     * @param feed - AI feed list
+     * @param outputPath - Output file path
+     */
+    writeFeedFile(feed, outputPath) {
+        const lines = [
+            '# CODEMAP AI FEED',
+            `# Generated: ${new Date().toISOString()}`,
+            ''
+        ];
+        for (const f of feed) {
+            const lastDateStr = f.heat.lastDate ?? 'never';
+            lines.push(`FILE: ${f.file}`);
+            lines.push(`GRAVITY: ${f.gravity} | HEAT: ${f.heat.freq30d}/${f.heat.lastType}/${lastDateStr}`);
+            lines.push(`META: since=${f.meta.since ?? 'unknown'} stable=${f.meta.stable ?? 'unknown'} why=${f.meta.why ?? 'none'}`);
+            lines.push(`IMPACT: ${f.dependents.length} files depend on this`);
+            lines.push(`DEPS: ${f.deps.join(', ') || 'none'}`);
+            lines.push('---');
+            lines.push('');
+        }
+        // Ensure directory exists
+        const outputDir = path.dirname(outputPath);
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+        fs.writeFileSync(outputPath, lines.join('\n'), 'utf-8');
+    }
+    /**
+     * Scan Git history for heat score
+     *
+     * @param filePath - File path (relative to projectRoot)
+     * @param projectRoot - Project root directory
+     * @returns HeatScore heat score
+     */
+    async scanGitHistory(filePath, projectRoot) {
+        return this.gitAnalyzer.analyzeFileHeat(filePath, projectRoot);
+    }
+    /**
+     * Calculate dependencies
+     * Scan import statements, build dependency graph
+     *
+     * @param feed - AI feed list
+     * @param projectRoot - Project root directory
+     */
+    calculateDependencies(feed, projectRoot) {
+        const fileMap = new Map();
+        // Build file map
+        for (const item of feed) {
+            fileMap.set(item.file, item);
+        }
+        // Scan import statements for each file
+        for (const item of feed) {
+            const fullPath = path.join(projectRoot, item.file);
+            try {
+                const content = fs.readFileSync(fullPath, 'utf-8');
+                // Scan import statements, match relative path imports
+                // Match: import ... from './path' or import ... from '../path'
+                const importMatches = [...content.matchAll(/from\s+['"](\.\.?\/[^'"]+)['"]/g)];
+                for (const match of importMatches) {
+                    const importPath = match[1];
+                    if (!importPath)
+                        continue;
+                    // Resolve import path to path relative to src
+                    const resolvedPath = this.resolveImportPath(item.file, importPath);
+                    if (resolvedPath) {
+                        // Normalize path: convert .js to .ts, or add .ts if no extension
+                        let normalizedPath;
+                        if (resolvedPath.endsWith('.ts')) {
+                            normalizedPath = resolvedPath;
+                        }
+                        else if (resolvedPath.endsWith('.js')) {
+                            normalizedPath = resolvedPath.slice(0, -3) + '.ts';
+                        }
+                        else {
+                            normalizedPath = resolvedPath + '.ts';
+                        }
+                        if (!item.deps.includes(normalizedPath)) {
+                            item.deps.push(normalizedPath);
+                        }
+                        // Check if target file exists in feed and add to dependents
+                        const possiblePaths = [
+                            resolvedPath,
+                            resolvedPath.endsWith('.js') ? resolvedPath.slice(0, -3) + '.ts' : resolvedPath + '.ts',
+                            resolvedPath + '/index.ts'
+                        ];
+                        for (const possiblePath of possiblePaths) {
+                            if (fileMap.has(possiblePath)) {
+                                // Add to target file's dependents
+                                const target = fileMap.get(possiblePath);
+                                if (target && !target.dependents.includes(item.file)) {
+                                    target.dependents.push(item.file);
+                                }
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // Skip on read failure
+            }
+        }
+        // Recalculate gravity (out-degree + in-degree)
+        for (const item of feed) {
+            item.gravity = item.deps.length + item.dependents.length;
+        }
+    }
+    /**
+     * Resolve import path to path relative to project root
+     *
+     * @param currentFile - Current file path
+     * @param importPath - Import path from import statement
+     * @returns Resolved path, or null if cannot resolve
+     */
+    resolveImportPath(currentFile, importPath) {
+        // Get current file's directory
+        const currentDir = path.dirname(currentFile);
+        // Resolve relative path
+        const resolved = path.normalize(path.join(currentDir, importPath));
+        // Ensure path is under src directory
+        if (!resolved.startsWith('src/')) {
+            return null;
+        }
+        return resolved;
+    }
+    /**
+     * Scan file header (convenience method)
+     * Delegates to FileHeaderScanner
+     *
+     * @param filePath - File path
+     * @returns FileMeta file metadata
+     */
+    scanFileHeader(filePath) {
+        return this.headerScanner.scan(filePath);
+    }
+    /**
+     * Calculate scores for a single feed item
+     * Returns normalized scores
+     *
+     * @param feed - AI feed item
+     * @param maxGravity - Maximum gravity value for normalization
+     * @param maxImpact - Maximum impact value for normalization
+     * @returns Object with gravity, impact, heat scores
+     */
+    calculateScores(feed, maxGravity = 20, maxImpact = 50) {
+        const gravity = feed.deps.length + feed.dependents.length;
+        const impact = feed.dependents.length;
+        const heat = feed.heat.freq30d;
+        return {
+            gravity: Math.min(gravity / (maxGravity || 1), 1),
+            impact: Math.min(impact / (maxImpact || 1), 1),
+            heat: Math.min(heat / 10, 1)
+        };
+    }
+    /**
+     * Calculate file risk level
+     * Based on REQUIREMENTS section 8.6 risk scoring formula
+     *
+     * @param feed - Single file AI feed
+     * @returns Risk level: 'high' | 'medium' | 'low'
+     */
+    calculateRisk(feed) {
+        const gravity = feed.gravity;
+        const heat = feed.heat;
+        const impact = feed.dependents.length;
+        const stable = feed.meta.stable ?? true;
+        return this.gitAnalyzer.calculateRiskLevel(gravity, heat, impact, stable);
+    }
+    /**
+     * Batch calculate risk levels
+     *
+     * @param feedList - AI feed list
+     * @returns Map<file path, risk level>
+     */
+    calculateRisks(feedList) {
+        const result = new Map();
+        for (const feed of feedList) {
+            result.set(feed.file, this.calculateRisk(feed));
+        }
+        return result;
+    }
+    /**
+     * Get high risk file list
+     *
+     * @param feedList - AI feed list
+     * @returns High risk file list
+     */
+    getHighRiskFiles(feedList) {
+        return feedList.filter(f => this.calculateRisk(f) === 'high');
+    }
+    /**
+     * Generate JSON format AI feed
+     * For programmatic processing
+     *
+     * @param feed - AI feed list
+     * @param outputPath - Output file path
+     */
+    writeFeedFileJson(feed, outputPath) {
+        // Ensure directory exists
+        const outputDir = path.dirname(outputPath);
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+        fs.writeFileSync(outputPath, JSON.stringify(feed, null, 2), 'utf-8');
+    }
+}
+//# sourceMappingURL=ai-feed-generator.js.map

package/dist/orchestrator/ai-feed-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-feed-generator.js","sourceRoot":"","sources":["../../src/orchestrator/ai-feed-generator.ts"],"names":[],"mappings":"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"}

package/docs/ai-guide/COMMANDS.md

@@ -214,6 +214,79 @@ mycodemap analyze -i show -t "src/index.ts" --output-mode human
 
 ---
 
+## design - 设计契约输入、范围映射与验证
+
+> `design` 为 human-authored design contract 提供正式输入面。默认文件名是 `mycodemap.design.md`，canonical 模板位于 `docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md`。
+
+### validate
+
+```bash
+# 使用默认文件名
+mycodemap design validate mycodemap.design.md --json
+
+# 显式指定文件
+mycodemap design validate docs/designs/login.design.md
+```
+
+### 必填 sections
+
+| Section | 作用 |
+|---------|------|
+| `Goal` | 定义本次要达成的结果 |
+| `Constraints` | 定义边界、兼容性和约束 |
+| `Acceptance Criteria` | 定义可验证的成功标准 |
+| `Non-Goals` | 明确本次不做什么，防止 scope drift |
+
+### 输出与失败语义
+
+- `--json` 输出纯结构化 diagnostics
+- 缺失必填 section、重复 section、空 section、未知 heading 都会被显式报告
+- blocker diagnostics 存在时命令返回非零 exit code
+
+### map
+
+```bash
+# 先校验，再映射 candidate scope
+mycodemap design validate mycodemap.design.md --json
+mycodemap design map mycodemap.design.md --json
+```
+
+- `design map` 返回 `summary`、`candidates`、`diagnostics`、`unknowns`
+- `candidates[]` 会同时暴露 `kind`、`path`、`reasons`、`dependencies`、`testImpact`、`risk`、`confidence`
+- blocker diagnostics 包括 `no-candidates`、`over-broad-scope`、`high-risk-scope`
+- 若 diagnostics 中存在 blocker，命令返回非零 exit code
+
+### handoff
+
+```bash
+# 先固定 design input / scope，再生成 handoff package
+mycodemap design validate mycodemap.design.md --json
+mycodemap design map mycodemap.design.md --json
+mycodemap design handoff mycodemap.design.md --json
+```
+
+- `design handoff` 返回 `readyForExecution`、`approvals`、`assumptions`、`openQuestions`
+- human mode 默认写入 `.mycodemap/handoffs/{stem}.handoff.md|json`
+- `--json` 保持纯 JSON，不混入 prose
+- review-needed 通过 `readyForExecution=false` 表达；只有 blocker diagnostics 才返回非零 exit code
+
+### verify
+
+```bash
+# 使用 reviewed handoff truth 做 checklist / drift 校验
+mycodemap design validate mycodemap.design.md --json
+mycodemap design map mycodemap.design.md --json
+mycodemap design handoff mycodemap.design.md --json
+mycodemap design verify mycodemap.design.md --json
+```
+
+- `design verify` 返回 `summary`、`checklist`、`drift`、`diagnostics`
+- `checklist[]` 直接来自 `Acceptance Criteria`，并保留 `status` + `evidenceRefs`
+- `drift[]` 至少区分 `scope-extra`、`acceptance-unverified`、`handoff-missing`
+- review-needed 通过 `readyForExecution=false` + warning diagnostics 表达；只有 `ok=false` 或 blocker diagnostics 才返回非零 exit code
+
+---
+
 ## ci - CI 门禁
 
 ### 子命令