@yuaone/core 0.1.0

package/dist/speculative-executor.d.ts

@@ -0,0 +1,210 @@
+/**
+ * @module speculative-executor
+ * @description Speculative Execution — 2~3개의 서로 다른 접근법을 병렬로 시도하여
+ * 최적의 결과를 선택하는 모듈.
+ *
+ * conservative(안전/최소 변경), aggressive(대담한 리팩토링),
+ * creative(새로운 패러다임) 전략을 동시에 실행하고, 빌드·테스트·품질 점수로 승자를 결정한다.
+ */
+import { EventEmitter } from "node:events";
+import type { BYOKConfig, ToolExecutor } from "./types.js";
+/** Speculative Execution 설정 */
+export interface SpeculativeConfig {
+    /** 최대 병렬 접근법 수 (기본 3) */
+    maxApproaches: number;
+    /** 접근법별 타임아웃 ms (기본 120_000) */
+    approachTimeout: number;
+    /** 최소 품질 점수 (0–100, 기본 60) */
+    minQualityThreshold: number;
+    /** BYOK 설정 (LLM 호출용) */
+    byokConfig: BYOKConfig;
+    /** 프로젝트 루트 경로 */
+    projectPath: string;
+}
+/** 접근법 전략 유형 */
+export type ApproachStrategy = "conservative" | "aggressive" | "creative";
+/** 개별 접근법 */
+export interface Approach {
+    /** 고유 ID */
+    id: string;
+    /** 전략 유형 */
+    strategy: ApproachStrategy;
+    /** 접근법 설명 */
+    description: string;
+    /** 시스템 프롬프트에 추가할 델타 */
+    systemPromptDelta: string;
+}
+/** 접근법 실행 결과 */
+export interface ApproachResult {
+    /** 해당 접근법 */
+    approach: Approach;
+    /** 성공 여부 */
+    success: boolean;
+    /** 변경된 파일 맵 (path → newContent) */
+    changes: Map<string, string>;
+    /** 빌드 통과 여부 */
+    buildPassed: boolean;
+    /** 테스트 통과 여부 */
+    testPassed: boolean;
+    /** 품질 점수 (0–100) */
+    qualityScore: number;
+    /** 사용된 토큰 수 */
+    tokensUsed: number;
+    /** 소요 시간 ms */
+    durationMs: number;
+    /** 실패 시 에러 메시지 */
+    error?: string;
+}
+/** Speculative Execution 최종 결과 */
+export interface SpeculativeResult {
+    /** 선택된 최적 접근법 (없으면 null) */
+    winner: ApproachResult | null;
+    /** 모든 접근법 결과 */
+    allResults: ApproachResult[];
+    /** 승자 선택 사유 */
+    selectionReason: string;
+    /** 전체 접근법 합산 토큰 사용량 */
+    totalTokensUsed: number;
+    /** 실패한 접근법에서 얻은 학습 */
+    learnings: string[];
+}
+export interface SpeculativeExecutorEvents {
+    "speculative:start": [payload: {
+        goal: string;
+        approachCount: number;
+    }];
+    "speculative:approach:start": [payload: {
+        approach: Approach;
+    }];
+    "speculative:approach:complete": [payload: {
+        result: ApproachResult;
+    }];
+    "speculative:evaluation": [payload: {
+        allResults: ApproachResult[];
+        winner: ApproachResult | null;
+    }];
+    "speculative:complete": [payload: {
+        result: SpeculativeResult;
+    }];
+}
+/**
+ * Speculative Execution 엔진.
+ *
+ * 2~3개의 서로 다른 접근법을 병렬로 시도하고,
+ * 빌드/테스트/품질 점수를 기반으로 최적의 결과를 선택한다.
+ *
+ * @example
+ * ```ts
+ * const executor = new SpeculativeExecutor({
+ *   maxApproaches: 3,
+ *   approachTimeout: 120_000,
+ *   minQualityThreshold: 60,
+ *   byokConfig: { provider: "anthropic", apiKey: "sk-..." },
+ *   projectPath: "/path/to/project",
+ * });
+ *
+ * executor.on("speculative:complete", ({ result }) => {
+ *   console.log("Winner:", result.winner?.approach.strategy);
+ * });
+ *
+ * const result = await executor.execute("Add error handling to all API routes", toolExecutor);
+ * ```
+ */
+export declare class SpeculativeExecutor extends EventEmitter<SpeculativeExecutorEvents> {
+    private readonly config;
+    private readonly llmClient;
+    constructor(config: SpeculativeConfig);
+    /**
+     * 리소스 정리. 내부 LLM 클라이언트를 해제하고 이벤트 리스너를 제거한다.
+     */
+    destroy(): void;
+    /**
+     * LLM을 사용하여 2~3개의 접근법을 생성한다.
+     * @param goal 달성할 목표
+     * @param codebaseContext 프로젝트 컨텍스트 (파일 구조, 기존 패턴 등)
+     * @returns 생성된 접근법 목록
+     */
+    generateApproaches(goal: string, codebaseContext: string): Promise<Approach[]>;
+    /**
+     * 단일 접근법을 실행한다.
+     * ToolExecutor를 사용하여 도구 호출을 수행하고, 변경 사항을 추적한다.
+     * @param approach 실행할 접근법
+     * @param goal 달성할 목표
+     * @param toolExecutor 도구 실행기
+     * @returns 접근법 실행 결과
+     */
+    executeApproach(approach: Approach, goal: string, toolExecutor: ToolExecutor): Promise<ApproachResult>;
+    /**
+     * 모든 접근법 결과를 평가하여 최적의 결과를 선택한다.
+     *
+     * 평가 기준 (가중치 순서):
+     * 1. buildPassed (+40점)
+     * 2. testPassed (+30점)
+     * 3. 변경 파일 수가 적을수록 (+10점)
+     * 4. 토큰 사용량이 적을수록 (+10점)
+     * 5. LLM 품질 평가 (+10점)
+     *
+     * @param results 모든 접근법 결과
+     * @returns 최적 결과 (모두 기준 미달이면 null)
+     */
+    evaluateResults(results: ApproachResult[]): ApproachResult | null;
+    /**
+     * 메인 실행 메서드. 접근법 생성 → 병렬 실행 → 평가 → 최적 결과 반환.
+     * @param goal 달성할 목표
+     * @param toolExecutor 도구 실행기
+     * @param codebaseContext 프로젝트 컨텍스트 (선택)
+     * @returns Speculative Execution 결과
+     */
+    execute(goal: string, toolExecutor: ToolExecutor, codebaseContext?: string): Promise<SpeculativeResult>;
+    /**
+     * 도구 호출에서 파일 변경을 추적한다.
+     */
+    private trackFileChanges;
+    /**
+     * 빌드 검증 — shell_exec로 tsc --noEmit 실행.
+     */
+    private verifyBuild;
+    /**
+     * 테스트 검증 — shell_exec로 테스트 실행.
+     */
+    private verifyTests;
+    /**
+     * 품질 점수 계산 (0–100).
+     *
+     * - buildPassed: +40
+     * - testPassed: +30
+     * - 변경 파일 수 적을수록: +10
+     * - 토큰 효율: +10
+     * - LLM 품질 평가: +10
+     */
+    private calculateQualityScore;
+    /**
+     * LLM에 코드 변경 품질 평가 요청 (0–10점 → 0–10 범위).
+     */
+    private llmQualityAssessment;
+    /**
+     * 복합 점수 계산 (평가 정렬용).
+     */
+    private compositeScore;
+    /**
+     * 실패한 접근법에서 학습 포인트를 추출한다.
+     */
+    private extractLearnings;
+    /**
+     * 승자 선택 이유를 생성한다.
+     */
+    private buildSelectionReason;
+    /**
+     * Promise에 타임아웃을 적용한다.
+     */
+    private withTimeout;
+    /**
+     * LLM이 유효한 접근법을 생성하지 못했을 때 사용하는 기본 접근법.
+     */
+    private getDefaultApproaches;
+    /**
+     * 안전한 JSON 파싱 (실패 시 null 반환).
+     */
+    private safeParseJSON;
+}
+//# sourceMappingURL=speculative-executor.d.ts.map

package/dist/speculative-executor.d.ts.map

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