@yasserkhanorg/impact-gate 2.0.0

package/dist/anthropic_provider.js

@@ -0,0 +1,334 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnthropicProvider = void 0;
+exports.checkAnthropicSetup = checkAnthropicSetup;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const provider_interface_js_1 = require("./provider_interface.js");
+const provider_utils_js_1 = require("./provider_utils.js");
+const base_provider_js_1 = require("./base_provider.js");
+const logger_js_1 = require("./logger.js");
+/**
+ * Anthropic Provider - Claude AI models
+ *
+ * Features:
+ * - Highest quality AI (98% accuracy in testing)
+ * - Vision support (analyze screenshots, compare UI)
+ * - Fast response times (<1 second)
+ * - 200K token context window
+ * - Prompt caching (reduces costs by 90% on repeated prompts)
+ *
+ * Costs (Claude Sonnet 4.5):
+ * - Input: $3 per 1M tokens
+ * - Output: $15 per 1M tokens
+ * - Cached input: $0.30 per 1M tokens
+ * - Estimated: ~$30-80/month for autonomous testing
+ *
+ * Use cases:
+ * - Vision tasks (screenshot comparison)
+ * - Complex failure diagnosis
+ * - High-stakes production testing
+ * - When quality is paramount
+ *
+ * Models:
+ * - claude-sonnet-4-5-20250929 (recommended - best balance)
+ * - claude-opus-4-5-20251101 (highest quality, slower, more expensive)
+ * - claude-haiku-4-0-20250430 (fastest, cheapest, lower quality)
+ */
+class AnthropicProvider extends base_provider_js_1.BaseProvider {
+    constructor(config) {
+        super();
+        this.name = 'anthropic';
+        this.capabilities = {
+            vision: true, // Full vision support
+            streaming: true,
+            maxTokens: 200000, // 200K context window
+            costPer1MInputTokens: 3, // $3 per 1M input tokens
+            costPer1MOutputTokens: 15, // $15 per 1M output tokens
+            supportsTools: true, // Function calling support
+            supportsPromptCaching: true, // Reduces costs by 90%
+            typicalResponseTimeMs: 800, // ~0.8 seconds
+        };
+        // SECURITY: Validate API key format
+        if (!provider_utils_js_1.API_KEY_PATTERNS.anthropic.test(config.apiKey)) {
+            throw new Error('Invalid API key format. Expected sk-ant-* format.');
+        }
+        // SECURITY: Validate and enforce HTTPS for remote connections
+        if (config.baseUrl) {
+            const validation = (0, provider_utils_js_1.validateAndSanitizeUrl)(config.baseUrl);
+            if (!validation.valid) {
+                throw new Error(`Invalid base URL: ${validation.warning}`);
+            }
+            if (validation.warning) {
+                logger_js_1.logger.warn(`HTTPS required for remote URLs: ${validation.warning}`);
+            }
+        }
+        this.client = new sdk_1.default({
+            apiKey: config.apiKey,
+            baseURL: config.baseUrl,
+            maxRetries: 0,
+        });
+        this.model = config.model || 'claude-sonnet-4-5-20250929';
+    }
+    async generateText(prompt, options) {
+        this.checkBudget();
+        const startTime = Date.now();
+        try {
+            // SECURITY: Validate prompt length to prevent resource exhaustion
+            if (prompt.length > 10 * 1024 * 1024) {
+                throw new Error('Prompt exceeds maximum size (10MB)');
+            }
+            const response = await (0, provider_utils_js_1.withTimeout)(this.client.messages.create({
+                model: this.model,
+                max_tokens: options?.maxTokens || 4000,
+                temperature: options?.temperature,
+                top_p: options?.topP,
+                stop_sequences: options?.stopSequences,
+                system: options?.systemPrompt,
+                messages: [
+                    {
+                        role: 'user',
+                        content: prompt,
+                    },
+                ],
+            }), options?.timeout, 'generateText');
+            const responseTime = Date.now() - startTime;
+            const text = this.extractTextFromResponse(response);
+            // SECURITY: Type-safe usage extraction
+            const usage = this.extractUsageFromResponse(response.usage);
+            const cost = this.calculateCost(usage, this.capabilities.costPer1MInputTokens, this.capabilities.costPer1MOutputTokens);
+            // Update stats
+            this.updateStats(usage, responseTime, cost);
+            return {
+                text,
+                usage,
+                cost,
+                metadata: {
+                    model: this.model,
+                    responseTimeMs: responseTime,
+                    stopReason: response.stop_reason,
+                    stopSequence: response.stop_sequence,
+                },
+            };
+        }
+        catch (error) {
+            this.stats.failedRequests++;
+            throw new provider_interface_js_1.LLMProviderError((0, provider_utils_js_1.sanitizeErrorMessage)(error, 'generateText'), this.name, this.extractStatusCode(error), error);
+        }
+    }
+    async analyzeImage(images, prompt, options) {
+        const startTime = Date.now();
+        try {
+            // SECURITY: Validate image array size
+            if (images.length === 0 || images.length > 20) {
+                throw new Error('Image count must be between 1 and 20');
+            }
+            // SECURITY: Validate prompt length
+            if (prompt.length > 10 * 1024 * 1024) {
+                throw new Error('Prompt exceeds maximum size (10MB)');
+            }
+            // Build content array with text and images
+            const content = [];
+            // Add prompt text first
+            content.push({
+                type: 'text',
+                text: prompt,
+            });
+            // Add each image
+            for (const image of images) {
+                // Validate media type
+                const mediaType = (image.mimeType || image.mediaType || 'image/png');
+                if (!['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(mediaType)) {
+                    throw new Error(`Unsupported image type: ${mediaType}`);
+                }
+                const data = image.data || image.base64 || '';
+                // SECURITY: Validate base64 data size (limit to 20MB per image)
+                if (data.length > 20 * 1024 * 1024) {
+                    throw new Error('Image data exceeds maximum size (20MB)');
+                }
+                content.push({
+                    type: 'image',
+                    source: {
+                        type: 'base64',
+                        media_type: mediaType,
+                        data: data,
+                    },
+                });
+                // Add description if provided
+                if (image.description) {
+                    content.push({
+                        type: 'text',
+                        text: `[Image: ${image.description}]`,
+                    });
+                }
+            }
+            const response = await (0, provider_utils_js_1.withTimeout)(this.client.messages.create({
+                model: this.model,
+                max_tokens: options?.maxTokens || 4000,
+                temperature: options?.temperature,
+                top_p: options?.topP,
+                stop_sequences: options?.stopSequences,
+                system: options?.systemPrompt,
+                messages: [
+                    {
+                        role: 'user',
+                        content,
+                    },
+                ],
+            }), options?.timeout, 'analyzeImage');
+            const responseTime = Date.now() - startTime;
+            const text = this.extractTextFromResponse(response);
+            // SECURITY: Type-safe usage extraction
+            const usage = this.extractUsageFromResponse(response.usage);
+            const cost = this.calculateCost(usage, this.capabilities.costPer1MInputTokens, this.capabilities.costPer1MOutputTokens);
+            // Update stats
+            this.updateStats(usage, responseTime, cost);
+            return {
+                text,
+                usage,
+                cost,
+                metadata: {
+                    model: this.model,
+                    responseTimeMs: responseTime,
+                    stopReason: response.stop_reason,
+                    imageCount: images.length,
+                },
+            };
+        }
+        catch (error) {
+            this.stats.failedRequests++;
+            throw new provider_interface_js_1.LLMProviderError((0, provider_utils_js_1.sanitizeErrorMessage)(error, 'analyzeImage'), this.name, this.extractStatusCode(error), error);
+        }
+    }
+    async *streamText(prompt, options) {
+        try {
+            // SECURITY: Validate prompt length
+            if (prompt.length > 10 * 1024 * 1024) {
+                throw new Error('Prompt exceeds maximum size (10MB)');
+            }
+            const stream = await (0, provider_utils_js_1.withTimeout)(this.client.messages.create({
+                model: this.model,
+                max_tokens: options?.maxTokens || 4000,
+                temperature: options?.temperature,
+                top_p: options?.topP,
+                stop_sequences: options?.stopSequences,
+                system: options?.systemPrompt,
+                messages: [
+                    {
+                        role: 'user',
+                        content: prompt,
+                    },
+                ],
+                stream: true,
+            }), options?.timeout, 'streamText');
+            for await (const event of stream) {
+                if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
+                    yield event.delta.text;
+                }
+            }
+            // Note: Streaming doesn't provide detailed usage stats
+            // We increment request count but can't track exact tokens/cost
+            this.stats.requestCount++;
+            this.stats.lastUpdated = new Date();
+        }
+        catch (error) {
+            this.stats.failedRequests++;
+            throw new provider_interface_js_1.LLMProviderError((0, provider_utils_js_1.sanitizeErrorMessage)(error, 'streamText'), this.name, this.extractStatusCode(error), error);
+        }
+    }
+    extractTextFromResponse(response) {
+        const textBlocks = response.content.filter((block) => block.type === 'text');
+        return textBlocks.map((block) => {
+            if (block.type === 'text') {
+                return block.text;
+            }
+            return '';
+        }).join('\n');
+    }
+    /**
+     * SECURITY: Type-safe usage extraction
+     * Avoids unsafe `as any` casts
+     */
+    extractUsageFromResponse(usage) {
+        return {
+            inputTokens: usage.input_tokens || 0,
+            outputTokens: usage.output_tokens || 0,
+            totalTokens: (usage.input_tokens || 0) + (usage.output_tokens || 0),
+            cachedTokens: usage.cache_read_input_tokens ?? undefined,
+        };
+    }
+    /**
+     * SECURITY: Extract status code safely
+     */
+    extractStatusCode(error) {
+        if (error && typeof error === 'object') {
+            const err = error;
+            const status = err.status;
+            if (typeof status === 'number') {
+                return status;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Check if API key is valid and service is accessible
+     */
+    async checkHealth() {
+        try {
+            // Try a minimal request to verify API key
+            await (0, provider_utils_js_1.withTimeout)(this.client.messages.create({
+                model: this.model,
+                max_tokens: 10,
+                messages: [
+                    {
+                        role: 'user',
+                        content: 'Hi',
+                    },
+                ],
+            }), 5000, 'health check');
+            return {
+                healthy: true,
+                message: `Anthropic API is accessible`,
+            };
+        }
+        catch (error) {
+            return {
+                healthy: false,
+                message: `Anthropic API error: ${(0, provider_utils_js_1.sanitizeErrorMessage)(error, 'health check')}`,
+            };
+        }
+    }
+}
+exports.AnthropicProvider = AnthropicProvider;
+/**
+ * Helper to check Anthropic setup
+ */
+async function checkAnthropicSetup(apiKey) {
+    if (!apiKey) {
+        return {
+            valid: false,
+            message: 'No API key provided',
+            estimatedMonthlyCost: 'N/A',
+        };
+    }
+    try {
+        const provider = new AnthropicProvider({ apiKey });
+        const health = await provider.checkHealth();
+        return {
+            valid: health.healthy,
+            message: health.message,
+            estimatedMonthlyCost: '$30-80 for autonomous testing (24 cycles/day)',
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            message: `Setup check failed: ${(0, provider_utils_js_1.sanitizeErrorMessage)(error, 'setup check')}`,
+            estimatedMonthlyCost: 'N/A',
+        };
+    }
+}

package/dist/api.d.ts

@@ -0,0 +1,48 @@
+import { type ConfigOverrides } from './agent/config.js';
+import { type PlanReport } from './agent/plan.js';
+import { type ImpactResult } from './engine/impact_engine.js';
+import { type AIEnrichmentResult } from './engine/ai_enrichment.js';
+import { type FinalizeGeneratedTestsOptions, type FinalizeGeneratedTestsResult } from './agent/handoff.js';
+import { type TraceabilityIngestOptions, type TraceabilityIngestResult } from './agent/traceability_ingest.js';
+import { type TraceabilityCaptureResult } from './agent/traceability_capture.js';
+export interface AgentApiOptions extends Omit<ConfigOverrides, 'mode'> {
+    cwd?: string;
+    configPath?: string;
+    apply?: boolean;
+    allowFallback?: boolean;
+}
+export interface TraceabilityIngestApiOptions {
+    cwd?: string;
+    configPath?: string;
+    path?: string;
+    testsRoot?: string;
+    payload: unknown;
+    options?: TraceabilityIngestOptions;
+}
+export interface TraceabilityCaptureApiOptions {
+    cwd?: string;
+    configPath?: string;
+    path?: string;
+    testsRoot?: string;
+    reportPath: string;
+    sinceRef?: string;
+    outputPath?: string;
+    coverageMapPath?: string;
+    changedFilesPath?: string;
+}
+export declare function handoffGeneratedTests(options: FinalizeGeneratedTestsOptions): FinalizeGeneratedTestsResult;
+export declare function ingestTraceability(options: TraceabilityIngestApiOptions): TraceabilityIngestResult;
+export interface RecommendTestsV2Result {
+    impact: ImpactResult;
+    plan: PlanReport;
+    planPath: string;
+    ciSummaryMarkdown: string;
+    ciSummaryPath: string;
+}
+export declare function analyzeImpactDeterministic(options?: AgentApiOptions): ImpactResult;
+export declare function recommendTestsDeterministic(options?: AgentApiOptions): RecommendTestsV2Result;
+export declare function recommendTestsAI(options?: AgentApiOptions): Promise<RecommendTestsV2Result & {
+    aiEnrichment?: AIEnrichmentResult;
+}>;
+export declare function captureTraceability(options: TraceabilityCaptureApiOptions): TraceabilityCaptureResult;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,eAAe,EAAC,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAEH,KAAK,UAAU,EAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAmC,KAAK,YAAY,EAAC,MAAM,2BAA2B,CAAC;AAU9F,OAAO,EAAqB,KAAK,kBAAkB,EAAC,MAAM,2BAA2B,CAAC;AAEtF,OAAO,EAAyB,KAAK,6BAA6B,EAAE,KAAK,4BAA4B,EAAC,MAAM,oBAAoB,CAAC;AACjI,OAAO,EAEH,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAChC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAGH,KAAK,yBAAyB,EACjC,MAAM,iCAAiC,CAAC;AAEzC,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,yBAAyB,CAAC;CACvC;AAED,MAAM,WAAW,6BAA6B;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAcD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,6BAA6B,GAAG,4BAA4B,CAE1G;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,4BAA4B,GAAG,wBAAwB,CASlG;AAED,MAAM,WAAW,sBAAsB;IACnC,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,eAAoB,GAAG,YAAY,CAStF;AAED,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,eAAoB,GAAG,sBAAsB,CAgBjG;AAED,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,sBAAsB,GAAG;IAAE,YAAY,CAAC,EAAE,kBAAkB,CAAA;CAAE,CAAC,CA+D7I;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,6BAA6B,GAAG,yBAAyB,CAkBrG"}

package/dist/api.js

@@ -0,0 +1,151 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handoffGeneratedTests = handoffGeneratedTests;
+exports.ingestTraceability = ingestTraceability;
+exports.analyzeImpactDeterministic = analyzeImpactDeterministic;
+exports.recommendTestsDeterministic = recommendTestsDeterministic;
+exports.recommendTestsAI = recommendTestsAI;
+exports.captureTraceability = captureTraceability;
+const config_js_1 = require("./agent/config.js");
+const plan_js_1 = require("./agent/plan.js");
+const impact_engine_js_1 = require("./engine/impact_engine.js");
+const plan_builder_js_1 = require("./engine/plan_builder.js");
+const git_js_1 = require("./agent/git.js");
+const feedback_js_1 = require("./agent/feedback.js");
+const diff_loader_js_1 = require("./engine/diff_loader.js");
+const ai_enrichment_js_1 = require("./engine/ai_enrichment.js");
+const provider_factory_js_1 = require("./provider_factory.js");
+const handoff_js_1 = require("./agent/handoff.js");
+const traceability_ingest_js_1 = require("./agent/traceability_ingest.js");
+const traceability_capture_js_1 = require("./agent/traceability_capture.js");
+function resolveAgent(options, mode) {
+    const cwd = options.cwd || process.cwd();
+    const { config } = (0, config_js_1.resolveConfig)(cwd, options.configPath, {
+        ...options,
+        mode,
+    });
+    if (options.allowFallback) {
+        config.impact.allowFallback = true;
+    }
+    return config;
+}
+function handoffGeneratedTests(options) {
+    return (0, handoff_js_1.finalizeGeneratedTests)(options);
+}
+function ingestTraceability(options) {
+    const cwd = options.cwd || process.cwd();
+    const { config } = (0, config_js_1.resolveConfig)(cwd, options.configPath, {
+        path: options.path,
+        testsRoot: options.testsRoot,
+        mode: 'impact',
+    });
+    const reportRoot = config.testsRoot || config.path;
+    return (0, traceability_ingest_js_1.ingestTraceabilityInput)(reportRoot, config.impact.traceability, options.payload, options.options);
+}
+function analyzeImpactDeterministic(options = {}) {
+    const config = resolveAgent(options, 'impact');
+    const reportRoot = config.testsRoot || config.path;
+    const gitResult = (0, git_js_1.getChangedFiles)(config.path, config.git.since, { includeUncommitted: config.git.includeUncommitted });
+    return (0, impact_engine_js_1.analyzeImpact)(gitResult.files, {
+        testsRoot: reportRoot,
+        routeFamilies: config.routeFamilies,
+        filteredTestFiles: gitResult.filteredTestFiles,
+    });
+}
+function recommendTestsDeterministic(options = {}) {
+    const config = resolveAgent(options, 'impact');
+    const reportRoot = config.testsRoot || config.path;
+    const gitResult = (0, git_js_1.getChangedFiles)(config.path, config.git.since, { includeUncommitted: config.git.includeUncommitted });
+    const impact = (0, impact_engine_js_1.analyzeImpact)(gitResult.files, {
+        testsRoot: reportRoot,
+        routeFamilies: config.routeFamilies,
+        filteredTestFiles: gitResult.filteredTestFiles,
+    });
+    const adaptive = (0, feedback_js_1.getAdaptiveThresholds)(reportRoot);
+    const plan = (0, plan_builder_js_1.buildPlanFromImpact)(impact, config.policy, undefined, adaptive);
+    const planPath = (0, plan_builder_js_1.writePlanReport)(reportRoot, plan);
+    const ciSummaryMarkdown = (0, plan_builder_js_1.renderCiSummaryMarkdown)(plan);
+    const ciSummaryPath = (0, plan_builder_js_1.writeCiSummary)(reportRoot, ciSummaryMarkdown);
+    (0, plan_js_1.appendPlanMetrics)(reportRoot, plan);
+    return { impact, plan, planPath, ciSummaryMarkdown, ciSummaryPath };
+}
+async function recommendTestsAI(options = {}) {
+    const config = resolveAgent(options, 'impact');
+    const reportRoot = config.testsRoot || config.path;
+    const gitResult = (0, git_js_1.getChangedFiles)(config.path, config.git.since, { includeUncommitted: config.git.includeUncommitted });
+    const impact = (0, impact_engine_js_1.analyzeImpact)(gitResult.files, {
+        testsRoot: reportRoot,
+        routeFamilies: config.routeFamilies,
+        filteredTestFiles: gitResult.filteredTestFiles,
+    });
+    let aiEnrichment;
+    let provider;
+    try {
+        provider = await provider_factory_js_1.LLMProviderFactory.createFromPreference(config.llm.provider);
+    }
+    catch (error) {
+        const configuredProvider = config.llm.provider?.trim().toLowerCase();
+        const envProvider = process.env.LLM_PROVIDER?.trim().toLowerCase();
+        const shouldThrow = Boolean((configuredProvider && configuredProvider !== 'auto') ||
+            (envProvider && envProvider !== 'auto'));
+        if (shouldThrow) {
+            throw error;
+        }
+    }
+    if (provider) {
+        const diffs = (0, diff_loader_js_1.loadDiffs)(config.path, config.git.since, gitResult.files);
+        // Collect all known spec paths and scenario details from impacted features
+        const specSet = new Set();
+        const specDetailsMap = new Map();
+        for (const feature of impact.impactedFeatures) {
+            for (const s of feature.playwrightSpecs) {
+                specSet.add(s);
+            }
+            for (const detail of feature.playwrightSpecDetails) {
+                if (!specDetailsMap.has(detail.file)) {
+                    specDetailsMap.set(detail.file, detail);
+                }
+            }
+            for (const detail of feature.cypressSpecDetails) {
+                if (!specDetailsMap.has(detail.file)) {
+                    specDetailsMap.set(detail.file, detail);
+                }
+            }
+        }
+        aiEnrichment = await (0, ai_enrichment_js_1.enrichImpactWithAI)({
+            deterministicImpact: impact,
+            diffs,
+            provider,
+            specList: [...specSet],
+            specDetails: [...specDetailsMap.values()],
+        });
+    }
+    const adaptive = (0, feedback_js_1.getAdaptiveThresholds)(reportRoot);
+    const plan = (0, plan_builder_js_1.buildPlanFromImpact)(impact, config.policy, aiEnrichment, adaptive);
+    const planPath = (0, plan_builder_js_1.writePlanReport)(reportRoot, plan);
+    const ciSummaryMarkdown = (0, plan_builder_js_1.renderCiSummaryMarkdown)(plan);
+    const ciSummaryPath = (0, plan_builder_js_1.writeCiSummary)(reportRoot, ciSummaryMarkdown);
+    (0, plan_js_1.appendPlanMetrics)(reportRoot, plan);
+    return { impact, plan, planPath, ciSummaryMarkdown, ciSummaryPath, aiEnrichment };
+}
+function captureTraceability(options) {
+    const cwd = options.cwd || process.cwd();
+    const { config } = (0, config_js_1.resolveConfig)(cwd, options.configPath, {
+        path: options.path,
+        testsRoot: options.testsRoot,
+        mode: 'impact',
+    });
+    const reportRoot = config.testsRoot || config.path;
+    const captureOptions = {
+        appPath: config.path,
+        testsRoot: reportRoot,
+        reportPath: options.reportPath,
+        sinceRef: options.sinceRef || config.git.since,
+        outputPath: options.outputPath,
+        coverageMapPath: options.coverageMapPath,
+        changedFilesPath: options.changedFilesPath,
+    };
+    return (0, traceability_capture_js_1.captureTraceabilityInput)(captureOptions);
+}

package/dist/base_provider.d.ts

@@ -0,0 +1,109 @@
+import type { GenerateOptions, ImageInput, LLMProvider, LLMResponse, ProviderCapabilities, ProviderUsageStats } from './provider_interface.js';
+import { CircuitBreaker } from './resilience/circuit_breaker.js';
+import type { BudgetLedger } from './budget_ledger.js';
+/**
+ * Abstract base class for all LLM providers
+ * Eliminates 240+ lines of duplicate stats management code
+ * Provides common functionality for token tracking, cost calculation, and stats management
+ */
+export declare class BudgetExceededError extends Error {
+    currentCost: number;
+    budgetUSD: number;
+    constructor(currentCost: number, budgetUSD: number);
+}
+export declare abstract class BaseProvider implements LLMProvider {
+    abstract name: string;
+    abstract capabilities: ProviderCapabilities;
+    /**
+     * Shared circuit breakers keyed by provider name (e.g., "anthropic", "openai").
+     * All instances of the same provider type share one breaker, so if Anthropic is
+     * down, ALL agents discover it after 3 total failures instead of 3 × N.
+     */
+    private static readonly _sharedBreakers;
+    protected stats: ProviderUsageStats;
+    private _budgetUSD;
+    private _ledger;
+    /** Tracks the current in-flight budget reservation for this provider instance. */
+    private _activeReservation;
+    constructor();
+    /** Lazily get-or-create a circuit breaker shared across all instances of this provider type. */
+    protected get circuitBreaker(): CircuitBreaker;
+    /**
+     * Set a hard budget limit. Once totalCost reaches this value,
+     * subsequent calls will throw BudgetExceededError.
+     */
+    setBudget(usd: number | undefined): void;
+    get budgetUSD(): number | undefined;
+    /**
+     * Attach a shared budget ledger so aggregate cost across all providers
+     * in a crew run is checked before each LLM call.
+     */
+    setBudgetLedger(ledger: BudgetLedger | undefined): void;
+    /**
+     * Check budget and pre-reserve estimated cost for the upcoming LLM call.
+     *
+     * When a shared ledger exists, reserves an estimate derived from the provider's
+     * output token cost × maxTokens (default 4096). This blocks parallel agents from
+     * spending into the same headroom — like a credit card authorization hold.
+     *
+     * Self-healing: if a prior call failed without reaching updateStats(), the stale
+     * reservation is released here before placing the new one.
+     */
+    protected checkBudget(): void;
+    /**
+     * Conservative cost estimate for the upcoming call.
+     * Uses maxTokens (or 4096 default) × output cost rate.
+     * Overestimating is safe — the reservation is replaced with actual cost in updateStats.
+     */
+    private estimateCallCost;
+    /**
+     * Initialize stats object with default values
+     */
+    protected initializeStats(): void;
+    /**
+     * Update stats with new usage data
+     * Maintains rolling average for response time
+     */
+    protected updateStats(usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    }, responseTime: number, cost: number): void;
+    /**
+     * Get a copy of current usage stats
+     */
+    getUsageStats(): ProviderUsageStats;
+    /**
+     * Reset all usage stats to initial state
+     */
+    resetUsageStats(): void;
+    /**
+     * Wrap an async call with circuit breaker + retry logic.
+     * Circuit breaker protects against cascading failures from a down provider;
+     * retry handles transient failures within a healthy circuit.
+     *
+     * Non-transient errors (budget, auth, validation) are thrown directly and
+     * bypass the circuit breaker so they don't incorrectly trip it.
+     */
+    protected retryCall<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Abstract methods that must be implemented by subclasses
+     */
+    abstract generateText(prompt: string, options?: GenerateOptions): Promise<LLMResponse>;
+    abstract analyzeImage(images: ImageInput[], prompt: string, options?: GenerateOptions): Promise<LLMResponse>;
+    abstract streamText(prompt: string, options?: GenerateOptions): AsyncGenerator<string, void, unknown>;
+    abstract checkHealth(): Promise<{
+        healthy: boolean;
+        message: string;
+    }>;
+    /**
+     * Calculate cost for token usage, accounting for prompt caching discounts
+     * Cached tokens cost 90% less than regular tokens
+     */
+    protected calculateCost(usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cachedTokens?: number;
+    }, costPer1MInputTokens: number, costPer1MOutputTokens: number): number;
+}
+//# sourceMappingURL=base_provider.d.ts.map

package/dist/base_provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base_provider.d.ts","sourceRoot":"","sources":["../src/base_provider.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACR,eAAe,EACf,UAAU,EACV,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,kBAAkB,EACrB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,cAAc,EAAC,MAAM,iCAAiC,CAAC;AAC/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAErD;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IACvB,WAAW,EAAE,MAAM;IAAS,SAAS,EAAE,MAAM;gBAA7C,WAAW,EAAE,MAAM,EAAS,SAAS,EAAE,MAAM;CAInE;AAED,8BAAsB,YAAa,YAAW,WAAW;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAE5C;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAqC;IAE5E,SAAS,CAAC,KAAK,EAAG,kBAAkB,CAAC;IACrC,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,OAAO,CAA2B;IAC1C,kFAAkF;IAClF,OAAO,CAAC,kBAAkB,CAAK;;IAM/B,gGAAgG;IAChG,SAAS,KAAK,cAAc,IAAI,cAAc,CAiB7C;IAED;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAIxC,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAED;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI;IAIvD;;;;;;;;;OASG;IACH,SAAS,CAAC,WAAW,IAAI,IAAI;IA4B7B;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;OAEG;IACH,SAAS,CAAC,eAAe,IAAI,IAAI;IAcjC;;;OAGG;IACH,SAAS,CAAC,WAAW,CACjB,KAAK,EAAE;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,EACvE,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACb,IAAI;IAuBP;;OAEG;IACH,aAAa,IAAI,kBAAkB;IAInC;;OAEG;IACH,eAAe,IAAI,IAAI;IAIvB;;;;;;;OAOG;IACH,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAOxD;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC;IACtF,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC;IAC5G,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC;IACrG,QAAQ,CAAC,WAAW,IAAI,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC;IAEpE;;;OAGG;IACH,SAAS,CAAC,aAAa,CACnB,KAAK,EAAE;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAC,EACzE,oBAAoB,EAAE,MAAM,EAC5B,qBAAqB,EAAE,MAAM,GAC9B,MAAM;CAmBZ"}