spectra-cli 4.1.1

package/dist/auth/codex-proxy.js

@@ -0,0 +1,199 @@
+/**
+ * Codex CLI 代理
+ * 通过 spawn Codex CLI 子进程间接调用 LLM
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { LLMRateLimitError, LLMResponseError, LLMTimeoutError, LLMUnavailableError, getTimeoutForModel, } from '../core/llm-client.js';
+import { resolveCodexExecutionConfig } from '../core/model-selection.js';
+export function getDefaultCodexCLIProxyConfig() {
+    const resolved = resolveCodexExecutionConfig();
+    return {
+        model: resolved.model,
+        timeout: getTimeoutForModel(resolved.model),
+        reasoningEffort: resolved.reasoningEffort,
+        serviceTier: resolved.serviceTier,
+        cwd: process.cwd(),
+    };
+}
+export function callLLMviaCodex(prompt, config = {}) {
+    const cfg = { ...getDefaultCodexCLIProxyConfig(), ...config };
+    const cliPath = cfg.cliPath ?? 'codex';
+    const outputLastMessagePath = path.join(os.tmpdir(), `spectra-codex-${Date.now()}-${Math.random().toString(16).slice(2)}.txt`);
+    return new Promise((resolve, reject) => {
+        const startTime = Date.now();
+        let stdoutData = '';
+        let stderrData = '';
+        let timedOut = false;
+        let settled = false;
+        const childEnv = { ...process.env };
+        delete childEnv['ANTHROPIC_API_KEY'];
+        const args = [
+            'exec',
+            '--json',
+            '--ephemeral',
+            '--skip-git-repo-check',
+            '--sandbox', 'read-only',
+            '--color', 'never',
+            '--output-last-message', outputLastMessagePath,
+            '--model', cfg.model,
+        ];
+        if (cfg.reasoningEffort) {
+            args.push('-c', `model_reasoning_effort=${JSON.stringify(cfg.reasoningEffort)}`);
+        }
+        if (cfg.serviceTier) {
+            args.push('-c', `service_tier=${JSON.stringify(cfg.serviceTier)}`);
+        }
+        args.push('-C', cfg.cwd ?? process.cwd(), '-');
+        let child;
+        try {
+            child = spawn(cliPath, args, {
+                env: childEnv,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            cleanupOutputFile(outputLastMessagePath);
+            const msg = err instanceof Error ? err.message : String(err);
+            reject(new LLMUnavailableError(`无法启动 Codex CLI: ${msg}`));
+            return;
+        }
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            timedOut = true;
+            child.kill('SIGTERM');
+            setTimeout(() => {
+                if (!settled) {
+                    child.kill('SIGKILL');
+                }
+            }, 3_000);
+        }, cfg.timeout);
+        child.stdout.on('data', (chunk) => {
+            stdoutData += chunk.toString();
+        });
+        child.stderr.on('data', (chunk) => {
+            stderrData += chunk.toString();
+        });
+        child.stdin.write(prompt);
+        child.stdin.end();
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            cleanupOutputFile(outputLastMessagePath);
+            reject(new LLMUnavailableError(`Codex CLI 进程错误: ${err.message}`));
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const duration = Date.now() - startTime;
+            if (timedOut) {
+                cleanupOutputFile(outputLastMessagePath);
+                reject(new LLMTimeoutError(`Codex CLI 超时 (${cfg.timeout}ms)`));
+                return;
+            }
+            try {
+                const parsed = parseCodexExecOutput(stdoutData, cfg.model, outputLastMessagePath);
+                cleanupOutputFile(outputLastMessagePath);
+                if (parsed.isError) {
+                    const message = parsed.errorMessage || parsed.content || stderrData.trim() || 'Codex CLI 返回错误';
+                    if (/rate limit|extra usage|quota|credits/i.test(message)) {
+                        reject(new LLMRateLimitError(message));
+                        return;
+                    }
+                    reject(new LLMResponseError(message, code ?? undefined));
+                    return;
+                }
+                if (code !== 0) {
+                    const errorMsg = stderrData.trim() || parsed.errorMessage || `退出码 ${code}`;
+                    reject(new LLMResponseError(`Codex CLI 错误 (exit ${code}): ${errorMsg}`, code ?? undefined));
+                    return;
+                }
+                resolve({
+                    content: parsed.content,
+                    model: cfg.model,
+                    inputTokens: parsed.inputTokens,
+                    outputTokens: parsed.outputTokens,
+                    duration,
+                });
+            }
+            catch (err) {
+                cleanupOutputFile(outputLastMessagePath);
+                const msg = err instanceof Error ? err.message : String(err);
+                reject(new LLMResponseError(`解析 Codex CLI 输出失败: ${msg}`, code ?? undefined));
+            }
+        });
+    });
+}
+function parseCodexExecOutput(raw, fallbackModel, outputLastMessagePath) {
+    const lines = raw.split('\n').filter((line) => line.trim());
+    let content = '';
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let isError = false;
+    let errorMessage = '';
+    for (const line of lines) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (event.type === 'item.completed' && event.item?.type === 'agent_message' && event.item.text) {
+            content = event.item.text;
+            continue;
+        }
+        if (event.type === 'turn.completed' && event.usage) {
+            inputTokens = event.usage.input_tokens ?? inputTokens;
+            outputTokens = event.usage.output_tokens ?? outputTokens;
+            continue;
+        }
+        if (event.type === 'result') {
+            isError = event.is_error === true;
+            if (event.result) {
+                errorMessage = event.result;
+            }
+        }
+    }
+    const outputLastMessage = readOutputLastMessage(outputLastMessagePath);
+    if (outputLastMessage) {
+        content = outputLastMessage;
+    }
+    if (!content && !errorMessage) {
+        throw new Error(`Codex CLI 输出为空 (${fallbackModel})`);
+    }
+    return {
+        content,
+        inputTokens,
+        outputTokens,
+        isError,
+        errorMessage: errorMessage || undefined,
+    };
+}
+function readOutputLastMessage(filePath) {
+    try {
+        if (!fs.existsSync(filePath)) {
+            return '';
+        }
+        return fs.readFileSync(filePath, 'utf-8').trim();
+    }
+    catch {
+        return '';
+    }
+}
+function cleanupOutputFile(filePath) {
+    try {
+        fs.rmSync(filePath, { force: true });
+    }
+    catch {
+        // ignore cleanup failure
+    }
+}
+//# sourceMappingURL=codex-proxy.js.map

package/dist/auth/codex-proxy.js.map

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

package/dist/batch/batch-orchestrator.d.ts

@@ -0,0 +1,214 @@
+import { type ProgressMode } from './progress-reporter.js';
+import { type CostSummary } from './cost-summary.js';
+import { type BudgetPolicy, type BudgetGateAttempt } from './budget-gate.js';
+import { type GroupingOptions } from './module-grouper.js';
+import { type LanguageGroup } from './language-grouper.js';
+import { type LanguageFileStat } from '../utils/file-scanner.js';
+import type { DependencyGraph } from '../models/dependency-graph.js';
+import type { FailedModule } from '../models/module-spec.js';
+import { type DebtPipelineResult } from '../panoramic/pipelines/debt-intelligence-pipeline.js';
+import type { SimpleLLMClient as DebtSimpleLLMClient } from '../debt-scanner/design-docs/llm-topic-inferrer.js';
+import type { DocsBundleProfileSummary } from '../panoramic/models/docs-bundle-types.js';
+import type { BatchMode } from '../panoramic/qa/types.js';
+export interface BatchOptions {
+    /** 即使 spec 已存在也重新生成 */
+    force?: boolean;
+    /** 仅重生成受影响的 spec */
+    incremental?: boolean;
+    /** 输出目录（默认 'specs'，相对路径基于 projectRoot） */
+    outputDir?: string;
+    /** 进度回调 */
+    onProgress?: (completed: number, total: number) => void;
+    /** 每个模块的 LLM 最大重试次数（默认 3） */
+    maxRetries?: number;
+    /**
+     * 并发处理的模块数上限（默认 3，顺序处理请传 1）。
+     *
+     * Feature 146：默认值从 1 提升到 3。理由：Sonnet 单次调用 15-30s，
+     * concurrency=3 时吞吐量显著提升且 429 风险可控（Anthropic RPM ~50-60）。
+     *
+     * 双层重试语义（FR-016）：
+     * - SDK 层：maxRetries=2（含退避），处理单次请求级 429/529
+     * - 应用层：maxRetries=3（模块级），处理更高层次的模块失败
+     * - 理论最差情况：每模块 3×3=9 次 HTTP 请求（9N 放大）
+     * - concurrency 作为速率总闸，限制总体并发流量
+     *
+     * 边界规范化（FR-002，在 runBatch 内执行）：
+     * - <=0 → 静默修正为 1 并输出 warn
+     * - 非整数 → Math.floor 向下取整
+     *
+     * 优先级链（CLI 层和 runBatch 层共同保证）：
+     * CLI flag --concurrency=N > spec-driver.config.yaml batch.concurrency > 默认值 3
+     */
+    concurrency?: number;
+    /** 检查点文件路径 */
+    checkpointPath?: string;
+    /** 模块分组选项 */
+    grouping?: GroupingOptions;
+    /** 语言过滤（如 ['typescript', 'python']），仅处理指定语言的模块 */
+    languages?: string[];
+    /** 进度报告输出模式（默认根据 process.stdout.isTTY 自动检测） */
+    progressMode?: ProgressMode;
+    /** 启用 Markdown 文档 + OpenAPI/AsyncAPI 规范提取（--include-docs），默认 false — Feature 107 */
+    includeDocs?: boolean;
+    /** 启用图像/图表 Vision 提取（--include-images），默认 false — Feature 107 */
+    includeImages?: boolean;
+    /** Feature 127：仅预估模式，跳过所有 LLM 调用，产出 dry-run 报告 */
+    dryRun?: boolean;
+    /** Feature 127：预算上限（input+output tokens 总数），超出触发 gate */
+    budget?: number;
+    /** Feature 127：超预算时的非交互策略（CI 场景） */
+    onOverBudget?: BudgetPolicy;
+    /** Feature 130：是否生成 technical-debt.md（默认 true） */
+    enableDebtIntelligence?: boolean;
+    /** Feature 130：debt-intelligence 的 LLM 客户端注入（未注入则降级为 no-llm-client） */
+    debtLlmClient?: DebtSimpleLLMClient;
+    /** F5：批处理运行模式（full | reading | code-only，默认 full） */
+    mode?: BatchMode;
+    /**
+     * 是否在知识图谱写盘后生成 graph.html 可视化文件。
+     *
+     * **Feature 140 FR-011 行为变更**：默认从 `false` 改为 `true`，graph.html 始终生成
+     * （之前需要 `--html` flag opt-in；现在 batch 末尾无条件生成）。
+     * 调用方仍可显式传 `generateHtml: false` 跳过（如 CI 资源紧张场景）。
+     * 极小图（节点数 < 3）会在生成的 HTML 中注入说明 banner（T19）。
+     */
+    generateHtml?: boolean;
+    /**
+     * Feature 133 P1-1（adversarial-review post-fix）：是否启用 hyperedge LLM 提取
+     * 默认 false，需要显式 opt-in（CLI `--hyperedges` 或 env `SPECTRA_HYPEREDGES_ENABLED=true`）。
+     * 同样要求 mode === 'full' 且未触发 budget gate skip-enrichment 降级。
+     */
+    hyperedgesEnabled?: boolean;
+    /**
+     * Feature 135 Bug 1：是否显式启用 ADR pipeline。
+     * v4.0.1 临时禁用（默认 false），evidence-binding 重构完成后（v4.1）恢复默认。
+     * 需用 CLI `--enable-adr` 显式开启。
+     */
+    enableAdr?: boolean;
+}
+export interface BatchResult {
+    totalModules: number;
+    successful: string[];
+    failed: FailedModule[];
+    skipped: string[];
+    degraded: string[];
+    duration: number;
+    indexGenerated: boolean;
+    summaryLogPath: string;
+    /** 检测到的语言列表 */
+    detectedLanguages?: string[];
+    /** 语言统计信息 */
+    languageStats?: Map<string, LanguageFileStat>;
+    /** 044 输出的文档图谱调试文件 */
+    docGraphPath?: string;
+    /** 046 输出的覆盖率审计 Markdown */
+    coverageReportPath?: string;
+    /** 049 输出的差量分析 Markdown */
+    deltaReportPath?: string;
+    /** 053 输出的项目级文档 Markdown 列表 */
+    projectDocs?: string[];
+    /** 055 输出的 bundle manifest 路径 */
+    docsBundleManifestPath?: string;
+    /** 055 输出的 profile 摘要 */
+    docsBundleProfiles?: DocsBundleProfileSummary[];
+    /** 127 输出的 LLM 成本汇总 */
+    costSummary?: CostSummary;
+    /** 127 dry-run 模式输出的预估报告路径 */
+    dryRunReportPath?: string;
+    /** 127 预算决策结果（超预算场景） */
+    budgetDecision?: {
+        policy: BudgetPolicy;
+        message: string;
+        interactive: boolean;
+        /** Codex review 修复：每轮 gate 的审计记录 */
+        attempts?: BudgetGateAttempt[];
+        /** 是否采纳了 skip-enrichment 降级 */
+        skipEnrichmentApplied?: boolean;
+        /** 是否采纳了 cheaper-model 降级 */
+        cheaperModelApplied?: boolean;
+    };
+    /** 130 debt-intelligence pipeline 结果 */
+    debt?: DebtPipelineResult;
+    /** F5 Story 3：生成的 graph.html 路径（--html flag 触发时写入） */
+    graphHtmlPath?: string;
+}
+/**
+ * 合并多个语言的 DependencyGraph 用于全局拓扑排序
+ * 仅合并 modules 和 edges，SCC/Mermaid 按语言独立保留（TD-002 选项 C）
+ */
+export declare function mergeGraphsForTopologicalSort(graphs: DependencyGraph[], projectRoot: string): DependencyGraph;
+/**
+ * 检测跨语言引用
+ * 扫描模块 imports 是否引用了其他语言组的路径
+ */
+export declare function detectCrossLanguageRefs(moduleFiles: string[], languageGroups: LanguageGroup[], graph: DependencyGraph): string[];
+/**
+ * Feature 146 FR-002 — 并发数边界规范化
+ *
+ * 规则：
+ * - 非整数（含小数、非数字、Infinity、NaN）→ Math.floor 向下取整
+ * - 取整后 <= 0 → 修正为 1（顺序处理）并通过 onWarn 上报
+ *
+ * 提取为独立纯函数便于单元测试（不需要启动完整 pipeline）。
+ *
+ * @param raw  原始 concurrency 值（已合并 CLI / config / 默认值之后传入）
+ * @param onWarn 修正发生时的告警回调（用于注入 logger.warn 或测试中的 spy）
+ */
+export declare function normalizeConcurrency(raw: number, onWarn?: (message: string) => void): number;
+/**
+ * 生成跨语言调用提示文本（CQ-001）
+ */
+export declare function generateCrossLanguageHint(languageNames: string[]): string;
+/**
+ * 按模块级拓扑顺序编排全项目 Spec 生成
+ *
+ * @param projectRoot - 项目根目录
+ * @param options - 批量选项
+ * @returns 批量结果
+ */
+export declare function runBatch(projectRoot: string, options?: BatchOptions): Promise<BatchResult>;
+/**
+ * 构建 hyperedge/anchor 集成所需的设计文档绝对路径列表
+ *
+ * **Feature 145 合并策略**（基线，向后兼容）：
+ * 1. fromDocs：本轮 generateBatchProjectDocs 写出的文件（来自 writtenFiles）
+ * 2. fromDisk：主动扫描 outputDir/project/ 目录下已存在的 .md 文件（磁盘优先）
+ *
+ * **Feature 140 T27 扩展**（spec FR-007 — 扩展 design doc 来源）：
+ * 通过 `extraOptions` 启用以下额外来源（默认全部启用，给 caller 显式 opt-out 的能力）：
+ * 3. fromReadme: 根目录 README.md（最高语义价值，作为顶层叙述）
+ * 4. fromDocsDir: `docs/` 目录下递归扫描的 .md（仅 `--include-docs=true` 时启用）
+ * 5. fromModuleSpecs: `<modulesDir>/*.spec.md`（当前 batch 产物，每次 batch 后存在）
+ * 6. fromProjectContext: `.specify/project-context.{yaml,md}`
+ *
+ * 解决 spec FR-007 的"hyperedge 在新项目首次 batch 后产出 0 条 hyperedge"问题：
+ * 之前 designDocAbsPaths 仅依赖 outputDir/project/，对从未 batch 过的新项目结果为空。
+ * 扩展后即使新项目，仅有 README.md 也能产出 ≥ 1 条 hyperedge。
+ *
+ * @param projectDocs 本轮 generator 输出的相对路径列表
+ * @param resolvedRoot 项目根目录绝对路径
+ * @param resolvedOutputDir 输出目录绝对路径（含 `project/` 子目录）
+ * @param extraOptions Feature 140 T27 扩展配置；不传时只走基线行为（向后兼容）
+ * @returns paths 列表 + 各来源 count + 检测到的嵌套子目录
+ */
+export declare function buildDesignDocAbsPaths(projectDocs: string[], resolvedRoot: string, resolvedOutputDir: string, extraOptions?: {
+    /** 是否包含根 README.md（默认 true）*/
+    includeReadme?: boolean;
+    /** 是否包含 docs/ 下递归 .md（默认 false；仅 --include-docs=true 时设为 true）*/
+    includeDocs?: boolean;
+    /** module specs 目录（包含 *.spec.md）；不传则跳过该来源 */
+    modulesDir?: string;
+    /** 是否包含 .specify/project-context.{yaml,md}（默认 true）*/
+    includeProjectContext?: boolean;
+}): {
+    paths: string[];
+    fromDocsCount: number;
+    fromDiskCount: number;
+    fromReadmeCount: number;
+    fromDocsDirCount: number;
+    fromModuleSpecsCount: number;
+    fromProjectContextCount: number;
+    nestedDirsDetected: string[];
+};
+//# sourceMappingURL=batch-orchestrator.d.ts.map

package/dist/batch/batch-orchestrator.d.ts.map

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