spectra-cli 4.1.1

package/dist/batch/module-grouper.js

@@ -0,0 +1,286 @@
+/**
+ * 文件→模块分组与模块级拓扑排序
+ * 将 dependency-cruiser 的文件级 DependencyGraph 聚合为目录级模块
+ * 支持语言感知分组：同目录多语言文件拆分为带语言后缀的子模块（Feature 031）
+ * 支持目录语义分类过滤（Feature 095）
+ */
+import * as path from 'node:path';
+import { LanguageAdapterRegistry } from '../adapters/language-adapter-registry.js';
+import { classifyDirectories } from './directory-classifier.js';
+// ============================================================
+// 核心 API
+// ============================================================
+/**
+ * 将文件级依赖图聚合为模块级分组
+ *
+ * 分组规则：
+ * 1. 以 basePrefix（默认 'src/'）开头的文件，按其后第 depth 级目录分组
+ * 2. basePrefix 根目录下的散文件归入 rootModuleName 模块
+ * 3. 无 src/ 目录时按项目根目录下第一级目录分组
+ */
+export function groupFilesToModules(graph, options = {}) {
+    const { depth = 1, rootModuleName = 'root', languageAware = false, } = options;
+    // 自动检测 basePrefix
+    const basePrefix = options.basePrefix ?? detectBasePrefix(graph.modules.map((n) => n.source));
+    // 步骤 1：将每个文件分配到模块
+    const moduleMap = new Map();
+    for (const node of graph.modules) {
+        const moduleName = resolveModuleName(node.source, basePrefix, depth, rootModuleName);
+        if (!moduleMap.has(moduleName)) {
+            moduleMap.set(moduleName, []);
+        }
+        moduleMap.get(moduleName).push(node.source);
+    }
+    // 步骤 2：构建 ModuleGroup 列表（语言感知模式下可能拆分）
+    const groups = [];
+    if (languageAware) {
+        const registry = LanguageAdapterRegistry.getInstance();
+        for (const [name, files] of moduleMap) {
+            const dirPath = name === rootModuleName
+                ? basePrefix.replace(/\/$/, '') || '.'
+                : basePrefix ? `${basePrefix}${name}` : name;
+            // 按语言分组
+            const langGroups = new Map();
+            for (const file of files) {
+                const adapter = registry.getAdapter(file);
+                const langId = adapter?.id ?? 'unknown';
+                if (!langGroups.has(langId)) {
+                    langGroups.set(langId, []);
+                }
+                langGroups.get(langId).push(file);
+            }
+            if (langGroups.size <= 1) {
+                // 单语言目录：保持原名（向后兼容）
+                const langId = langGroups.keys().next().value;
+                groups.push({
+                    name,
+                    dirPath,
+                    files: files.sort(),
+                    language: langId,
+                });
+            }
+            else {
+                // 多语言目录：拆分为带语言后缀的子模块
+                for (const [langId, langFiles] of langGroups) {
+                    const subName = `${name}--${langId}`;
+                    groups.push({
+                        name: subName,
+                        dirPath,
+                        files: langFiles.sort(),
+                        language: langId,
+                    });
+                }
+            }
+        }
+    }
+    else {
+        for (const [name, files] of moduleMap) {
+            const dirPath = name === rootModuleName
+                ? basePrefix.replace(/\/$/, '') || '.'
+                : basePrefix ? `${basePrefix}${name}` : name;
+            groups.push({ name, dirPath, files: files.sort() });
+        }
+    }
+    // 步骤 3：构建模块间依赖关系
+    const fileToModule = new Map();
+    for (const group of groups) {
+        for (const file of group.files) {
+            fileToModule.set(file, group.name);
+        }
+    }
+    // 聚合文件级边为模块级边（去重，忽略模块内部依赖）
+    const moduleEdgeSet = new Set();
+    const moduleEdges = [];
+    for (const edge of graph.edges) {
+        const fromModule = fileToModule.get(edge.from);
+        const toModule = fileToModule.get(edge.to);
+        if (fromModule && toModule && fromModule !== toModule) {
+            const key = `${fromModule}->${toModule}`;
+            if (!moduleEdgeSet.has(key)) {
+                moduleEdgeSet.add(key);
+                moduleEdges.push({ from: fromModule, to: toModule });
+            }
+        }
+    }
+    // 步骤 3.5（可选）：目录语义分类过滤（FR-005）
+    // 将非 source 类别的模块标记，但仍保留在 groups 中（供 batch-orchestrator 决策是否跳过）
+    let sourceGroups;
+    if (options.classifyDirectories) {
+        const projectRoot = options.projectRoot ?? '';
+        // 构建目录绝对路径和 import 边
+        const dirPaths = groups.map((g) => {
+            // dirPath 可能是相对路径，尝试结合 projectRoot 解析
+            return projectRoot ? path.resolve(projectRoot, g.dirPath) : g.dirPath;
+        });
+        // 构建文件级 import 边（用于 import 反向引用信号）
+        const importEdges = graph.edges.map((e) => ({ from: e.from, to: e.to }));
+        const classifications = classifyDirectories(dirPaths, importEdges, options.directoryClassifierOptions);
+        const classMap = new Map();
+        for (let i = 0; i < groups.length; i++) {
+            classMap.set(groups[i].name, classifications[i]);
+        }
+        // sourceGroups：只保留 source 类别的模块进入 moduleOrder
+        sourceGroups = groups.filter((g) => {
+            const cls = classMap.get(g.name);
+            return !cls || cls.category === 'source';
+        });
+        // 安全回退：如果分类后 0 个模块，说明分类器过于激进，回退到不分类
+        if (sourceGroups.length === 0 && groups.length > 0) {
+            sourceGroups = groups;
+        }
+    }
+    else {
+        sourceGroups = groups;
+    }
+    // 步骤 3.6：扁平包自动降级为文件级分组
+    // 在目录分类过滤之后检查：仅当无标准源码目录布局（basePrefix === ''）
+    // 且 source 模块中只有 1 个非 root 模块且文件数 > 1 时触发
+    // 典型场景：Python 单包项目（graphify/pipeline.py, graphify/extract.py, ...），
+    // 即使有 tests/ 等目录也能正确降级（因 tests/ 被分类器过滤后不计入 sourceGroups）
+    const sourceNonRoot = sourceGroups.filter((g) => g.name !== rootModuleName);
+    if (basePrefix === '' && sourceNonRoot.length === 1 && sourceNonRoot[0].files.length > 1) {
+        const soleGroup = sourceNonRoot[0];
+        const rootGroup = sourceGroups.find((g) => g.name === rootModuleName);
+        // M1 修复：先用 stem 分配，冲突项改用包含扩展名的相对路径作为 name，确保全局唯一
+        // 冲突来源：同名文件（__init__.py/__init__.pyi）或不同目录的同名文件
+        const stemCount = new Map();
+        for (const file of soleGroup.files) {
+            const stem = path.basename(file).replace(/\.[^.]+$/, '');
+            stemCount.set(stem, (stemCount.get(stem) ?? 0) + 1);
+        }
+        // 将唯一 source 模块拆分为文件级子模块
+        const fileGroups = soleGroup.files.map((file) => {
+            const stem = path.basename(file).replace(/\.[^.]+$/, '');
+            // stem 有冲突时，改用包含扩展名的完整相对路径（路径分隔符替换为 __）作为唯一名称
+            // 保留扩展名是为了区分 __init__.py 和 __init__.pyi 这类同 stem 但不同扩展名的文件
+            const name = (stemCount.get(stem) ?? 0) > 1
+                ? file.replace(/[/\\]/g, '__').replace(/\./g, '_')
+                : stem;
+            return {
+                name,
+                dirPath: soleGroup.dirPath,
+                files: [file],
+                language: soleGroup.language,
+            };
+        });
+        // 重建 sourceGroups 和 groups
+        sourceGroups = [];
+        if (rootGroup)
+            sourceGroups.push(rootGroup);
+        sourceGroups.push(...fileGroups);
+        // 同步更新 groups 和 fileToModule：替换原模块为文件级模块
+        const soleIdx = groups.indexOf(soleGroup);
+        if (soleIdx >= 0) {
+            groups.splice(soleIdx, 1, ...fileGroups);
+        }
+        for (const fg of fileGroups) {
+            fileToModule.set(fg.files[0], fg.name);
+        }
+        // 重建模块边（原单模块内的文件级边现在可能变为跨模块边）
+        moduleEdgeSet.clear();
+        moduleEdges.length = 0;
+        for (const edge of graph.edges) {
+            const fromMod = fileToModule.get(edge.from);
+            const toMod = fileToModule.get(edge.to);
+            if (fromMod && toMod && fromMod !== toMod) {
+                const key = `${fromMod}->${toMod}`;
+                if (!moduleEdgeSet.has(key)) {
+                    moduleEdgeSet.add(key);
+                    moduleEdges.push({ from: fromMod, to: toMod });
+                }
+            }
+        }
+    }
+    // 步骤 4：模块级拓扑排序（仅对 source 模块排序）
+    const moduleOrder = topologicalSortModules(sourceGroups.map((g) => g.name), moduleEdges);
+    return { groups, moduleOrder, moduleEdges };
+}
+// ============================================================
+// 内部函数
+// ============================================================
+/**
+ * 自动检测基准目录前缀
+ * 如果所有文件都在 src/ 下则返回 'src/'，否则返回 ''
+ */
+function detectBasePrefix(filePaths) {
+    if (filePaths.length === 0)
+        return 'src/';
+    const srcCount = filePaths.filter((f) => f.startsWith('src/')).length;
+    // 超过 80% 的文件在 src/ 下
+    if (srcCount / filePaths.length > 0.8)
+        return 'src/';
+    const libCount = filePaths.filter((f) => f.startsWith('lib/')).length;
+    if (libCount / filePaths.length > 0.8)
+        return 'lib/';
+    return '';
+}
+/**
+ * 根据文件路径解析其所属的模块名
+ */
+function resolveModuleName(filePath, basePrefix, depth, rootModuleName) {
+    // 如果文件不在 basePrefix 下
+    if (basePrefix && !filePath.startsWith(basePrefix)) {
+        return rootModuleName;
+    }
+    // 取 basePrefix 之后的路径
+    const relativePath = basePrefix ? filePath.slice(basePrefix.length) : filePath;
+    const segments = relativePath.split('/');
+    // 直接在 basePrefix 根目录下的散文件（如 'src/entry.ts'）
+    if (segments.length <= 1) {
+        return rootModuleName;
+    }
+    // 按 depth 取目录层级
+    return segments.slice(0, depth).join('/');
+}
+/**
+ * 模块级 Kahn 拓扑排序
+ * 返回叶子模块优先（无依赖的模块先处理）的顺序
+ */
+function topologicalSortModules(moduleNames, edges) {
+    // 注意：这里的"依赖方向"是 from 依赖 to
+    // 拓扑排序中，被依赖的（to）应该先处理
+    const inDegree = new Map();
+    const adjacency = new Map();
+    for (const name of moduleNames) {
+        inDegree.set(name, 0);
+        adjacency.set(name, []);
+    }
+    // from 依赖 to → to 先处理 → to 的"出边"指向 from
+    // 即在拓扑排序中：to → from
+    for (const edge of edges) {
+        adjacency.get(edge.to)?.push(edge.from);
+        inDegree.set(edge.from, (inDegree.get(edge.from) ?? 0) + 1);
+    }
+    // Kahn 算法
+    const queue = [];
+    for (const [name, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(name);
+        }
+    }
+    const sorted = [];
+    while (queue.length > 0) {
+        // 稳定排序：字母序出队
+        queue.sort();
+        const node = queue.shift();
+        sorted.push(node);
+        for (const neighbor of adjacency.get(node) ?? []) {
+            const newDegree = (inDegree.get(neighbor) ?? 1) - 1;
+            inDegree.set(neighbor, newDegree);
+            if (newDegree === 0) {
+                queue.push(neighbor);
+            }
+        }
+    }
+    // 处理循环依赖：未排序的模块追加到末尾
+    if (sorted.length < moduleNames.length) {
+        const sortedSet = new Set(sorted);
+        for (const name of moduleNames) {
+            if (!sortedSet.has(name)) {
+                sorted.push(name);
+            }
+        }
+    }
+    return sorted;
+}
+//# sourceMappingURL=module-grouper.js.map

package/dist/batch/module-grouper.js.map

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

package/dist/batch/progress-reporter.d.ts

@@ -0,0 +1,68 @@
+import type { FailedModule, StageProgress } from '../models/module-spec.js';
+import type { CostSummary } from './cost-summary.js';
+/**
+ * 进度报告输出模式
+ *
+ * - `tty`：交互终端模式（ANSI 控制码 + 实时刷新）
+ * - `pipe`：管道/CI 模式（纯文本行日志）
+ * - `silent`：静默模式（Feature 146 / TD-002）— 所有方法 no-op，用于测试或后台运行场景
+ */
+export type ProgressMode = 'tty' | 'pipe' | 'silent';
+export interface BatchSummary {
+    totalModules: number;
+    successful: number;
+    failed: number;
+    skipped: number;
+    degraded: number;
+    duration: number;
+    modules: Array<{
+        path: string;
+        status: 'success' | 'failed' | 'skipped' | 'degraded';
+        duration?: number;
+    }>;
+}
+export interface ProgressReporter {
+    /** 开始处理某模块 */
+    start(modulePath: string): void;
+    /** 报告模块内阶段进度 */
+    stage(modulePath: string, progress: StageProgress): void;
+    /** 完成某模块处理 */
+    complete(modulePath: string, status: 'success' | 'failed' | 'skipped' | 'degraded'): void;
+    /** 生成最终摘要 */
+    finish(): BatchSummary;
+}
+/**
+ * 渲染进度条字符串（TTY 模式复用）。
+ *
+ * Feature 146 FR-010：扩展支持「进行中」三维状态。
+ * - active > 0 时：`[bar] X/N | 进行中: Y | 排队: Z`
+ * - active = 0 时：降级为原始二维格式 `[bar] X/N`（向后兼容）
+ *
+ * @param completed - 已完成模块数
+ * @param total     - 总模块数
+ * @param active    - 当前进行中的模块数（默认 0，等同未传入）
+ */
+export declare function renderProgressBar(completed: number, total: number, active?: number): string;
+/**
+ * 创建终端进度报告器
+ *
+ * @param total - 模块总数
+ * @param mode  - 输出模式（默认根据 process.stdout.isTTY 自动检测）
+ * @param options - Feature 146：可选配置，含 getActiveCount getter（FR-011：不改 ProgressReporter 接口签名）
+ * @returns ProgressReporter
+ */
+export declare function createReporter(total: number, mode?: ProgressMode, options?: {
+    getActiveCount?: () => number;
+}): ProgressReporter;
+/**
+ * 写入批处理摘要日志（FR-015）
+ *
+ * @param summary - 批处理摘要
+ * @param outputPath - 输出路径（specs/ 目录下）
+ * @param costSummary - 可选的 LLM 成本汇总（Feature 127 FR-008），存在时追加 "LLM 成本汇总" 节
+ * @param failedModules - 可选的失败模块详情（Bug 142），含 reason / retryCount / error；
+ *                         传入时追加 "## 失败详情" 节，让用户能直接看到失败原因
+ *                         （如 retry-budget-exceeded），不必再翻 checkpoint 文件
+ */
+export declare function writeSummaryLog(summary: BatchSummary, outputPath: string, costSummary?: CostSummary, failedModules?: FailedModule[]): void;
+//# sourceMappingURL=progress-reporter.d.ts.map

package/dist/batch/progress-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-reporter.d.ts","sourceRoot":"","sources":["../../src/batch/progress-reporter.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOrD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;QACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,gBAAgB;IAC/B,cAAc;IACd,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB;IAChB,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IACzD,cAAc;IACd,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GACpD,IAAI,CAAC;IACR,aAAa;IACb,MAAM,IAAI,YAAY,CAAC;CACxB;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAU,GAAG,MAAM,CAU9F;AAMD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE,GAC1C,gBAAgB,CAyLlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,WAAW,EACzB,aAAa,CAAC,EAAE,YAAY,EAAE,GAC7B,IAAI,CAqDN"}

package/dist/batch/progress-reporter.js

@@ -0,0 +1,273 @@
+/**
+ * 终端进度报告器
+ *
+ * 支持两种输出模式（由 {@link ProgressMode} 枚举控制）：
+ *
+ * - `tty`：交互终端模式，使用 ANSI 控制码（`\x1b[2K\r`）清行后重绘进度条；
+ *   日志从上方滚动，进度条固定底部，进度与模块日志不发生视觉交叉。
+ *
+ * - `pipe`：管道/CI 模式，输出纯文本行日志（`[N/Total] path ... status\n`）；
+ *   全程禁止 ANSI 控制码与 `\r`，适合重定向到文件或 CI 日志流。
+ *
+ * 模式选择策略：
+ * - 未指定 `mode` 时，根据 `process.stdout.isTTY` 自动检测；
+ * - `isTTY=true` → `tty`，否则 → `pipe`。
+ *
+ * 向后兼容性：
+ * - `createReporter(total)` 单参数调用方零改动，`mode` 为可选参数。
+ *
+ * [N/Total] Processing src/module... 格式（FR-015）
+ * 参见 contracts/batch-module.md
+ */
+import * as fs from 'node:fs';
+import { renderSummaryCostSection } from './cost-summary.js';
+// ============================================================
+// 内部工具函数
+// ============================================================
+/**
+ * 渲染进度条字符串（TTY 模式复用）。
+ *
+ * Feature 146 FR-010：扩展支持「进行中」三维状态。
+ * - active > 0 时：`[bar] X/N | 进行中: Y | 排队: Z`
+ * - active = 0 时：降级为原始二维格式 `[bar] X/N`（向后兼容）
+ *
+ * @param completed - 已完成模块数
+ * @param total     - 总模块数
+ * @param active    - 当前进行中的模块数（默认 0，等同未传入）
+ */
+export function renderProgressBar(completed, total, active = 0) {
+    const percent = total > 0 ? completed / total : 0;
+    const barWidth = 20;
+    const filled = Math.floor(percent * barWidth);
+    const bar = '='.repeat(filled).padEnd(barWidth, ' ');
+    if (active > 0) {
+        const queued = Math.max(0, total - completed - active);
+        return `[${bar}] ${completed}/${total} | 进行中: ${active} | 排队: ${queued}`;
+    }
+    return `[${bar}] ${completed}/${total}`;
+}
+// ============================================================
+// 工厂函数
+// ============================================================
+/**
+ * 创建终端进度报告器
+ *
+ * @param total - 模块总数
+ * @param mode  - 输出模式（默认根据 process.stdout.isTTY 自动检测）
+ * @param options - Feature 146：可选配置，含 getActiveCount getter（FR-011：不改 ProgressReporter 接口签名）
+ * @returns ProgressReporter
+ */
+export function createReporter(total, mode, options) {
+    // 自动检测模式：isTTY 为 true 时使用 tty，否则使用 pipe
+    // 'silent' 模式必须显式传入，不会被自动选中
+    const effectiveMode = mode ?? (process.stdout.isTTY ? 'tty' : 'pipe');
+    const startTime = Date.now();
+    let completed = 0;
+    const modules = [];
+    const moduleStartTimes = new Map();
+    // 读取「进行中」计数：未注入 getter 时返回 0（即降级为二维进度条，向后兼容）
+    const getActive = () => {
+        try {
+            return options?.getActiveCount?.() ?? 0;
+        }
+        catch {
+            return 0;
+        }
+    };
+    // ============================================================
+    // Silent 模式实现（Feature 146 / TD-002）
+    // ============================================================
+    if (effectiveMode === 'silent') {
+        return {
+            start(modulePath) {
+                moduleStartTimes.set(modulePath, Date.now());
+            },
+            stage(_modulePath, _progress) {
+                // no-op
+            },
+            complete(modulePath, status) {
+                completed++;
+                const moduleStart = moduleStartTimes.get(modulePath);
+                const duration = moduleStart ? Date.now() - moduleStart : undefined;
+                modules.push({ path: modulePath, status, duration });
+            },
+            finish() {
+                const duration = Date.now() - startTime;
+                return {
+                    totalModules: total,
+                    successful: modules.filter((m) => m.status === 'success').length,
+                    failed: modules.filter((m) => m.status === 'failed').length,
+                    skipped: modules.filter((m) => m.status === 'skipped').length,
+                    degraded: modules.filter((m) => m.status === 'degraded').length,
+                    duration,
+                    modules,
+                };
+            },
+        };
+    }
+    // ============================================================
+    // TTY 模式实现
+    // ============================================================
+    if (effectiveMode === 'tty') {
+        return {
+            start(modulePath) {
+                moduleStartTimes.set(modulePath, Date.now());
+                // 清行 → 输出模块开始日志 → 重绘进度条（completed 在 complete() 中递增，与 pipe 模式对齐）
+                process.stdout.write(`\x1b[2K\r[${completed + 1}/${total}] 正在处理 ${modulePath}...\n`);
+                process.stdout.write(`\x1b[2K\r${renderProgressBar(completed, total, getActive())}`);
+            },
+            stage(modulePath, progress) {
+                if (progress.duration === undefined) {
+                    // 阶段开始
+                    process.stdout.write(`\x1b[2K\r  → ${progress.message}\n`);
+                }
+                else {
+                    // 阶段完成
+                    process.stdout.write(`\x1b[2K\r  ✓ ${progress.stage}完成 (${progress.duration}ms)\n`);
+                }
+                // 重绘进度条
+                process.stdout.write(`\x1b[2K\r${renderProgressBar(completed, total, getActive())}`);
+            },
+            complete(modulePath, status) {
+                completed++;
+                const moduleStart = moduleStartTimes.get(modulePath);
+                const duration = moduleStart ? Date.now() - moduleStart : undefined;
+                const statusEmoji = {
+                    success: '✅',
+                    failed: '❌',
+                    skipped: '⏭️',
+                    degraded: '⚠️',
+                }[status];
+                // 清行 → 输出完成行 → 重绘进度条
+                process.stdout.write(`\x1b[2K\r  ${statusEmoji} ${modulePath} — ${status}${duration ? ` (${duration}ms)` : ''}\n`);
+                process.stdout.write(`\x1b[2K\r${renderProgressBar(completed, total, getActive())}`);
+                modules.push({ path: modulePath, status, duration });
+            },
+            finish() {
+                const duration = Date.now() - startTime;
+                const summary = {
+                    totalModules: total,
+                    successful: modules.filter((m) => m.status === 'success').length,
+                    failed: modules.filter((m) => m.status === 'failed').length,
+                    skipped: modules.filter((m) => m.status === 'skipped').length,
+                    degraded: modules.filter((m) => m.status === 'degraded').length,
+                    duration,
+                    modules,
+                };
+                // 清除进度行 → 输出摘要统计
+                process.stdout.write('\x1b[2K\r');
+                process.stdout.write('\n--- 批处理完成 ---\n');
+                process.stdout.write(`总计: ${total} 模块\n`);
+                process.stdout.write(`成功: ${summary.successful}\n`);
+                process.stdout.write(`失败: ${summary.failed}\n`);
+                process.stdout.write(`跳过: ${summary.skipped}\n`);
+                process.stdout.write(`降级: ${summary.degraded}\n`);
+                process.stdout.write(`耗时: ${(duration / 1000).toFixed(1)}s\n`);
+                return summary;
+            },
+        };
+    }
+    // ============================================================
+    // Pipe 模式实现
+    // ============================================================
+    return {
+        start(modulePath) {
+            // pipe 模式 start 记录开始时间，不输出（避免噪音）
+            moduleStartTimes.set(modulePath, Date.now());
+        },
+        stage(_modulePath, _progress) {
+            // pipe 模式 stage 不输出，避免噪音
+        },
+        complete(modulePath, status) {
+            completed++;
+            const moduleStart = moduleStartTimes.get(modulePath);
+            const duration = moduleStart ? Date.now() - moduleStart : undefined;
+            // 纯文本行日志：[N/Total] module-path ... status
+            const durationStr = duration ? ` (${duration}ms)` : '';
+            process.stdout.write(`[${completed}/${total}] ${modulePath} ... ${status}${durationStr}\n`);
+            modules.push({ path: modulePath, status, duration });
+        },
+        finish() {
+            const duration = Date.now() - startTime;
+            const summary = {
+                totalModules: total,
+                successful: modules.filter((m) => m.status === 'success').length,
+                failed: modules.filter((m) => m.status === 'failed').length,
+                skipped: modules.filter((m) => m.status === 'skipped').length,
+                degraded: modules.filter((m) => m.status === 'degraded').length,
+                duration,
+                modules,
+            };
+            // 纯文本摘要，无 ANSI 控制码
+            process.stdout.write('\n--- 批处理完成 ---\n');
+            process.stdout.write(`总计: ${total} 模块\n`);
+            process.stdout.write(`成功: ${summary.successful}\n`);
+            process.stdout.write(`失败: ${summary.failed}\n`);
+            process.stdout.write(`跳过: ${summary.skipped}\n`);
+            process.stdout.write(`降级: ${summary.degraded}\n`);
+            process.stdout.write(`耗时: ${(duration / 1000).toFixed(1)}s\n`);
+            return summary;
+        },
+    };
+}
+/**
+ * 写入批处理摘要日志（FR-015）
+ *
+ * @param summary - 批处理摘要
+ * @param outputPath - 输出路径（specs/ 目录下）
+ * @param costSummary - 可选的 LLM 成本汇总（Feature 127 FR-008），存在时追加 "LLM 成本汇总" 节
+ * @param failedModules - 可选的失败模块详情（Bug 142），含 reason / retryCount / error；
+ *                         传入时追加 "## 失败详情" 节，让用户能直接看到失败原因
+ *                         （如 retry-budget-exceeded），不必再翻 checkpoint 文件
+ */
+export function writeSummaryLog(summary, outputPath, costSummary, failedModules) {
+    const lines = [
+        '# 批处理摘要日志',
+        '',
+        `生成时间: ${new Date().toISOString()}`,
+        `总耗时: ${(summary.duration / 1000).toFixed(1)}s`,
+        '',
+        '## 统计',
+        '',
+        `| 指标 | 数值 |`,
+        `|------|------|`,
+        `| 总模块数 | ${summary.totalModules} |`,
+        `| 成功 | ${summary.successful} |`,
+        `| 失败 | ${summary.failed} |`,
+        `| 跳过 | ${summary.skipped} |`,
+        `| 降级 | ${summary.degraded} |`,
+        '',
+        '## 详情',
+        '',
+        '| 模块 | 状态 | 耗时 |',
+        '|------|------|------|',
+    ];
+    for (const mod of summary.modules) {
+        const duration = mod.duration ? `${mod.duration}ms` : '-';
+        lines.push(`| ${mod.path} | ${mod.status} | ${duration} |`);
+    }
+    // Bug 142：追加失败详情节，输出 reason / retryCount / error
+    if (failedModules && failedModules.length > 0) {
+        lines.push('');
+        lines.push('## 失败详情');
+        lines.push('');
+        lines.push('| 模块 | 原因 | 重试次数 | 错误 |');
+        lines.push('|------|------|---------|------|');
+        for (const fm of failedModules) {
+            const reason = fm.reason ?? '-';
+            // 错误消息可能包含管道符 / 换行，转义后截断到合理长度
+            const errorEscaped = fm.error
+                .replace(/\r?\n/g, ' ')
+                .replace(/\|/g, '\\|')
+                .slice(0, 500);
+            lines.push(`| ${fm.path} | ${reason} | ${fm.retryCount} | ${errorEscaped} |`);
+        }
+    }
+    // Feature 127：追加 LLM 成本汇总节
+    if (costSummary) {
+        lines.push('');
+        lines.push(renderSummaryCostSection(costSummary));
+    }
+    fs.writeFileSync(outputPath, lines.join('\n'), 'utf-8');
+}
+//# sourceMappingURL=progress-reporter.js.map