spectra-cli 4.1.1

package/dist/core/grammar-manager.d.ts

@@ -0,0 +1,79 @@
+/**
+ * GrammarManager — web-tree-sitter grammar WASM 文件的按需加载与单例缓存管理器
+ *
+ * 职责：
+ * 1. 全局唯一 Parser.init()，通过 locateFile 定位 tree-sitter.wasm
+ * 2. 按语言名称按需加载 grammar WASM，并发请求去重
+ * 3. 加载前进行 SHA256 校验（比对 grammars/manifest.json）
+ * 4. 提供 dispose / resetInstance 等生命周期方法
+ */
+import Parser from 'web-tree-sitter';
+/** 单条 grammar 条目 */
+export interface GrammarManifestEntry {
+    wasmFile: string;
+    sha256: string;
+}
+/** grammars/manifest.json 的完整结构 */
+export interface GrammarManifest {
+    abiVersion: number;
+    webTreeSitterVersion: string;
+    grammars: Record<string, GrammarManifestEntry>;
+}
+export declare class GrammarManager {
+    private static instance;
+    /** 获取全局唯一实例 */
+    static getInstance(): GrammarManager;
+    /** 重置单例（仅供测试使用） */
+    static resetInstance(): void;
+    /** Parser.init() 全局去重 Promise */
+    private initPromise;
+    /** grammar 按语言缓存（含并发去重） */
+    private grammarCache;
+    /** manifest 缓存 */
+    private manifest;
+    /** 项目根目录 */
+    private readonly projectRoot;
+    /** grammars/ 目录绝对路径 */
+    private readonly grammarsDir;
+    /** web-tree-sitter 运行时 WASM 所在目录 */
+    private readonly webTreeSitterDir;
+    private constructor();
+    /**
+     * 按语言名称获取 grammar（按需加载 + 并发去重 + SHA256 校验）
+     *
+     * @param language - 语言标识，如 'typescript', 'python'
+     * @returns Parser.Language 实例
+     * @throws 语言不在 manifest / WASM 文件缺失 / SHA256 校验失败
+     */
+    getGrammar(language: string): Promise<Parser.Language>;
+    /**
+     * 检查 manifest 中是否包含指定语言
+     */
+    hasGrammar(language: string): boolean;
+    /**
+     * 返回所有受支持的语言列表
+     */
+    getSupportedLanguages(): string[];
+    /**
+     * 释放所有缓存的 grammar Promise
+     */
+    dispose(): Promise<void>;
+    /**
+     * 确保 Parser.init() 只执行一次（全局去重）
+     */
+    private ensureInit;
+    /**
+     * 异步加载 manifest（带缓存）
+     */
+    private loadManifest;
+    /**
+     * 同步加载 manifest（用于 hasGrammar / getSupportedLanguages 等同步方法）
+     * manifest.json 很小，同步读取不会有性能问题
+     */
+    private loadManifestSync;
+    /**
+     * 加载 WASM 文件并进行 SHA256 校验，然后调用 Parser.Language.load()
+     */
+    private loadAndVerifyGrammar;
+}
+//# sourceMappingURL=grammar-manager.d.ts.map

package/dist/core/grammar-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar-manager.d.ts","sourceRoot":"","sources":["../../src/core/grammar-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,MAAM,MAAM,iBAAiB,CAAC;AAIrC,oBAAoB;AACpB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CAChD;AA0BD,qBAAa,cAAc;IAEzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA+B;IAEtD,eAAe;IACf,MAAM,CAAC,WAAW,IAAI,cAAc;IAOpC,mBAAmB;IACnB,MAAM,CAAC,aAAa,IAAI,IAAI;IAM5B,iCAAiC;IACjC,OAAO,CAAC,WAAW,CAA8B;IAEjD,2BAA2B;IAC3B,OAAO,CAAC,YAAY,CAA+C;IAEnE,kBAAkB;IAClB,OAAO,CAAC,QAAQ,CAAgC;IAEhD,YAAY;IACZ,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,uBAAuB;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,oCAAoC;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C,OAAO;IAaP;;;;;;OAMG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;IA+B5D;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAOrC;;OAEG;IACH,qBAAqB,IAAI,MAAM,EAAE;IAOjC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B;;OAEG;IACH,OAAO,CAAC,UAAU;IAclB;;OAEG;YACW,YAAY;IAU1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;OAEG;YACW,oBAAoB;CA6BnC"}

package/dist/core/grammar-manager.js

@@ -0,0 +1,188 @@
+/**
+ * GrammarManager — web-tree-sitter grammar WASM 文件的按需加载与单例缓存管理器
+ *
+ * 职责：
+ * 1. 全局唯一 Parser.init()，通过 locateFile 定位 tree-sitter.wasm
+ * 2. 按语言名称按需加载 grammar WASM，并发请求去重
+ * 3. 加载前进行 SHA256 校验（比对 grammars/manifest.json）
+ * 4. 提供 dispose / resetInstance 等生命周期方法
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Parser from 'web-tree-sitter';
+// ─────────────────── 内部工具：定位项目根目录 ───────────────────
+/**
+ * 从当前模块位置向上查找 package.json，以此确定项目根目录。
+ * 无论从 src/ (ts-node / vitest) 还是 dist/ (编译后) 执行均可正确定位。
+ */
+function findProjectRoot() {
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    let dir = currentDir;
+    // 最多向上查找 10 层，防止无限循环
+    for (let i = 0; i < 10; i++) {
+        if (existsSync(join(dir, 'package.json'))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // 到达文件系统根
+        dir = parent;
+    }
+    // 降级：假设 src/core/ 或 dist/core/ 两层上即为项目根
+    return resolve(currentDir, '..', '..');
+}
+// ──────────────────────── GrammarManager ────────────────────────
+export class GrammarManager {
+    // ── 单例 ──
+    static instance = null;
+    /** 获取全局唯一实例 */
+    static getInstance() {
+        if (!GrammarManager.instance) {
+            GrammarManager.instance = new GrammarManager();
+        }
+        return GrammarManager.instance;
+    }
+    /** 重置单例（仅供测试使用） */
+    static resetInstance() {
+        GrammarManager.instance = null;
+    }
+    // ── 内部状态 ──
+    /** Parser.init() 全局去重 Promise */
+    initPromise = null;
+    /** grammar 按语言缓存（含并发去重） */
+    grammarCache = new Map();
+    /** manifest 缓存 */
+    manifest = null;
+    /** 项目根目录 */
+    projectRoot;
+    /** grammars/ 目录绝对路径 */
+    grammarsDir;
+    /** web-tree-sitter 运行时 WASM 所在目录 */
+    webTreeSitterDir;
+    constructor() {
+        this.projectRoot = findProjectRoot();
+        this.grammarsDir = join(this.projectRoot, 'grammars');
+        // node_modules/web-tree-sitter/ 下存放 tree-sitter.wasm
+        this.webTreeSitterDir = join(this.projectRoot, 'node_modules', 'web-tree-sitter');
+    }
+    // ── 公开 API ──
+    /**
+     * 按语言名称获取 grammar（按需加载 + 并发去重 + SHA256 校验）
+     *
+     * @param language - 语言标识，如 'typescript', 'python'
+     * @returns Parser.Language 实例
+     * @throws 语言不在 manifest / WASM 文件缺失 / SHA256 校验失败
+     */
+    async getGrammar(language) {
+        // 确保 Parser 已初始化
+        await this.ensureInit();
+        // 加载 manifest（懒加载）
+        const manifest = await this.loadManifest();
+        const entry = manifest.grammars[language];
+        if (!entry) {
+            const supported = Object.keys(manifest.grammars).join(', ');
+            throw new Error(`不支持的语言: "${language}"。支持的语言: ${supported}`);
+        }
+        // 并发去重：同一语言的并发请求共享同一个 Promise
+        const cached = this.grammarCache.get(language);
+        if (cached) {
+            return cached;
+        }
+        const loadPromise = this.loadAndVerifyGrammar(language, entry);
+        this.grammarCache.set(language, loadPromise);
+        // 如果加载失败，从缓存中移除，以便下次可以重试
+        loadPromise.catch(() => {
+            this.grammarCache.delete(language);
+        });
+        return loadPromise;
+    }
+    /**
+     * 检查 manifest 中是否包含指定语言
+     */
+    hasGrammar(language) {
+        if (!this.manifest) {
+            this.manifest = this.loadManifestSync();
+        }
+        return language in this.manifest.grammars;
+    }
+    /**
+     * 返回所有受支持的语言列表
+     */
+    getSupportedLanguages() {
+        if (!this.manifest) {
+            this.manifest = this.loadManifestSync();
+        }
+        return Object.keys(this.manifest.grammars);
+    }
+    /**
+     * 释放所有缓存的 grammar Promise
+     */
+    async dispose() {
+        this.grammarCache.clear();
+        this.manifest = null;
+        this.initPromise = null;
+    }
+    // ── 内部方法 ──
+    /**
+     * 确保 Parser.init() 只执行一次（全局去重）
+     */
+    ensureInit() {
+        if (!this.initPromise) {
+            const wasmDir = this.webTreeSitterDir;
+            this.initPromise = Parser.init({
+                locateFile(scriptName) {
+                    // web-tree-sitter 内部会请求 'tree-sitter.wasm'，
+                    // 通过 locateFile 将其指向正确的绝对路径
+                    return join(wasmDir, scriptName);
+                },
+            });
+        }
+        return this.initPromise;
+    }
+    /**
+     * 异步加载 manifest（带缓存）
+     */
+    async loadManifest() {
+        if (this.manifest) {
+            return this.manifest;
+        }
+        const manifestPath = join(this.grammarsDir, 'manifest.json');
+        const raw = await readFile(manifestPath, 'utf-8');
+        this.manifest = JSON.parse(raw);
+        return this.manifest;
+    }
+    /**
+     * 同步加载 manifest（用于 hasGrammar / getSupportedLanguages 等同步方法）
+     * manifest.json 很小，同步读取不会有性能问题
+     */
+    loadManifestSync() {
+        const manifestPath = join(this.grammarsDir, 'manifest.json');
+        const raw = readFileSync(manifestPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    /**
+     * 加载 WASM 文件并进行 SHA256 校验，然后调用 Parser.Language.load()
+     */
+    async loadAndVerifyGrammar(language, entry) {
+        const wasmPath = join(this.grammarsDir, entry.wasmFile);
+        // 检查文件是否存在
+        if (!existsSync(wasmPath)) {
+            throw new Error(`Grammar WASM 文件不存在: 语言="${language}", 预期路径="${wasmPath}"`);
+        }
+        // 读取 WASM 文件并计算 SHA256
+        const wasmBuffer = await readFile(wasmPath);
+        const actualSha256 = createHash('sha256')
+            .update(wasmBuffer)
+            .digest('hex');
+        if (actualSha256 !== entry.sha256) {
+            throw new Error(`Grammar WASM SHA256 校验失败: 语言="${language}", ` +
+                `预期="${entry.sha256}", 实际="${actualSha256}"`);
+        }
+        // 加载 grammar
+        return Parser.Language.load(wasmPath);
+    }
+}
+//# sourceMappingURL=grammar-manager.js.map

package/dist/core/grammar-manager.js.map

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

package/dist/core/llm-client.d.ts

@@ -0,0 +1,120 @@
+import type { SpecSections } from '../models/module-spec.js';
+import type { LanguageTerminology } from '../adapters/language-adapter.js';
+import type { AssembledContext } from './context-assembler.js';
+export interface LLMConfig {
+    /** 模型 ID（优先级: REVERSE_SPEC_MODEL > spec-driver.config.yaml > 默认值） */
+    model: string;
+    /** API Key（默认从 ANTHROPIC_API_KEY 环境变量获取） */
+    apiKey?: string;
+    /** 响应最大 token 数（默认 8192） */
+    maxTokensResponse: number;
+    /** 温度（默认 0.3，低温用于事实性提取） */
+    temperature: number;
+    /** 超时时间（毫秒，默认根据模型动态计算：Sonnet 120s, Opus 300s, Haiku 60s） */
+    timeout: number;
+    /** Codex 推理强度（仅 Codex CLI provider 使用） */
+    reasoningEffort?: 'low' | 'medium' | 'high' | 'xhigh';
+    /** Codex 服务层级（仅 Codex CLI provider 使用） */
+    serviceTier?: string;
+    /** 目标语言术语（可选，用于参数化 LLM prompt） */
+    languageTerminology?: LanguageTerminology;
+}
+export interface LLMResponse {
+    /** LLM 原始文本响应 */
+    content: string;
+    /** 实际使用的模型 */
+    model: string;
+    /** 发送的 token 数 */
+    inputTokens: number;
+    /** 接收的 token 数 */
+    outputTokens: number;
+    /** 请求耗时（毫秒） */
+    duration: number;
+}
+export interface UncertaintyMarker {
+    type: '推断' | '不明确' | 'SYNTAX ERROR';
+    section: string;
+    rationale: string;
+}
+export interface ParsedSpecSections {
+    sections: SpecSections;
+    uncertaintyMarkers: UncertaintyMarker[];
+    parseWarnings: string[];
+}
+export declare class LLMUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare class LLMRateLimitError extends Error {
+    constructor(message: string);
+}
+export declare class LLMResponseError extends Error {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+export declare class LLMTimeoutError extends Error {
+    constructor(message: string);
+}
+/** LLM 重试事件 */
+export interface RetryEvent {
+    /** 当前尝试次数（从 1 开始） */
+    attempt: number;
+    /** 最大尝试次数 */
+    maxAttempts: number;
+    /** 触发重试的错误类型 */
+    errorType: 'timeout' | 'rate-limit' | 'server-error';
+    /** 下一次尝试前的等待时间（毫秒） */
+    delay: number;
+}
+/** 重试事件回调 */
+export type RetryCallback = (event: RetryEvent) => void;
+/**
+ * 根据模型名称返回合理的超时时间
+ *
+ * 基于实测数据：
+ * - Opus: spec 生成通常 >120s，需要更长超时
+ * - GPT-5 / Codex: 中大型模块 spec 生成实测可超过 180s
+ * - Sonnet: 大模块 spec 生成可能超过 4 分钟，给 10 分钟裕量
+ * - Haiku: 响应极快
+ * - 未知模型: 保守默认值
+ */
+export declare function getTimeoutForModel(model: string): number;
+/**
+ * 为 spec 生成按上下文体积扩展超时窗口。
+ *
+ * 质量优先策略：
+ * - 小上下文保持原模型默认超时，避免日常请求变慢
+ * - 超过 40k token 后，每额外 15k token 增加 2 分钟窗口
+ * - 上限控制在 15 分钟，避免无限等待
+ */
+export declare function getTimeoutForSpecGeneration(model: string, contextTokenCount: number): number;
+/**
+ * 将组装好的上下文发送至 Claude API
+ *
+ * 策略模式：根据认证检测结果自动选择调用方式
+ * - API Key 可用 → 通过 Anthropic SDK 直接调用
+ * - Claude CLI 可用 → 通过 spawn Claude CLI 子进程间接调用
+ * - Codex CLI 可用 → 通过 spawn Codex CLI 子进程间接调用
+ *
+ * @param context - assembleContext() 的输出
+ * @param config - 可选的配置覆盖
+ * @param onRetry - 可选的重试事件回调
+ * @returns LLM 响应
+ * @throws LLMUnavailableError, LLMRateLimitError, LLMResponseError, LLMTimeoutError
+ */
+export declare function callLLM(context: AssembledContext, config?: Partial<LLMConfig>, onRetry?: RetryCallback): Promise<LLMResponse>;
+/**
+ * 解析 LLM 原始响应为结构化的规格章节
+ *
+ * @param raw - LLM 原始响应文本
+ * @returns 解析后的结构化章节
+ */
+export declare function parseLLMResponse(raw: string): ParsedSpecSections;
+/**
+ * 返回给定操作模式的系统提示词
+ *
+ * @param mode - 操作模式
+ * @param terminology - 可选的语言术语映射，用于参数化 prompt
+ * @returns 系统提示词文本
+ */
+export declare function buildSystemPrompt(mode: 'spec-generation' | 'semantic-diff', terminology?: LanguageTerminology): string;
+//# sourceMappingURL=llm-client.d.ts.map

package/dist/core/llm-client.d.ts.map

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