@dotsetlabs/bellwether 0.10.0

package/dist/baseline/performance-tracker.js

@@ -0,0 +1,577 @@
+/**
+ * Performance Regression Detection
+ *
+ * Tracks response times across tool executions and detects performance regressions.
+ * Provides percentile-based metrics (p50, p95, p99) for comprehensive latency analysis.
+ */
+import { PERFORMANCE_TRACKING, PERFORMANCE_CONFIDENCE } from '../constants.js';
+// Re-export centralized constant for backwards compatibility
+export { PERFORMANCE_TRACKING as PERFORMANCE } from '../constants.js';
+/**
+ * Calculate statistical confidence for performance metrics.
+ *
+ * Confidence is determined by:
+ * 1. Sample count - more samples = higher confidence
+ * 2. Coefficient of variation (CV) - lower variability = higher confidence
+ *
+ * Key insight: For confidence calculation, we only count happy_path tests that
+ * expect success. Validation tests (expectedOutcome: 'error') are tracked
+ * separately because their failure doesn't indicate tool problems.
+ *
+ * Note: The first sample is excluded from variance calculation because it includes
+ * cold-start overhead (JIT compilation, connection establishment, cache warming).
+ * This gives more accurate confidence scores for steady-state performance.
+ *
+ * @param samples - The latency samples to analyze
+ * @param options - Optional configuration
+ * @returns Performance confidence metrics
+ */
+export function calculatePerformanceConfidence(samples, options = {}) {
+    const { excludeWarmup = true } = options;
+    const totalTests = samples.length;
+    // Handle no samples case
+    if (totalTests === 0) {
+        return {
+            sampleCount: 0,
+            successfulSamples: 0,
+            validationSamples: 0,
+            totalTests: 0,
+            standardDeviation: 0,
+            coefficientOfVariation: 0,
+            confidenceLevel: 'low',
+            recommendation: PERFORMANCE_CONFIDENCE.RECOMMENDATIONS.NO_SAMPLES,
+        };
+    }
+    // Categorize samples by expected outcome
+    // Happy path tests: expectedOutcome === 'success' or undefined (backward compat)
+    const happyPathSamples = samples.filter(s => s.expectedOutcome === 'success' || s.expectedOutcome === undefined);
+    // Validation tests: expectedOutcome === 'error'
+    const validationTestSamples = samples.filter(s => s.expectedOutcome === 'error');
+    // Count validation samples that correctly rejected (error as expected = success)
+    const validationSuccesses = validationTestSamples.filter(s => !s.success && (s.outcomeCorrect === undefined || s.outcomeCorrect === true)).length;
+    // For confidence, only use happy path samples that succeeded
+    const successfulHappyPath = happyPathSamples.filter(s => s.success);
+    const allDurations = successfulHappyPath.map(s => s.durationMs);
+    // Handle all failures case
+    if (allDurations.length === 0) {
+        return {
+            sampleCount: 0,
+            successfulSamples: 0,
+            validationSamples: validationTestSamples.length,
+            totalTests,
+            standardDeviation: 0,
+            coefficientOfVariation: 0,
+            confidenceLevel: 'low',
+            recommendation: 'No successful happy path samples; cannot calculate performance confidence',
+        };
+    }
+    // For variance calculation, exclude the first sample (cold start warmup)
+    // This prevents JIT compilation, connection setup, and cache warming from
+    // inflating the coefficient of variation and lowering confidence scores.
+    const durationsForVariance = excludeWarmup && allDurations.length > 1
+        ? allDurations.slice(1)
+        : allDurations;
+    // Calculate variance using post-warmup samples only
+    const meanForVariance = durationsForVariance.reduce((sum, d) => sum + d, 0) / durationsForVariance.length;
+    const squaredDiffs = durationsForVariance.map(d => Math.pow(d - meanForVariance, 2));
+    const variance = squaredDiffs.reduce((sum, d) => sum + d, 0) / durationsForVariance.length;
+    const standardDeviation = Math.sqrt(variance);
+    // Calculate coefficient of variation (CV = stdDev / mean)
+    // Use the post-warmup mean for consistency with variance calculation
+    // CV is undefined when mean is 0, treat as 0 (consistent)
+    const coefficientOfVariation = meanForVariance > 0 ? standardDeviation / meanForVariance : 0;
+    // Determine confidence level based on happy path sample count
+    // This fixes the bug where validation tests lowered confidence
+    const { confidenceLevel, recommendation } = determineConfidenceLevel(allDurations.length, coefficientOfVariation);
+    return {
+        sampleCount: allDurations.length, // Happy path successful samples only
+        successfulSamples: allDurations.length,
+        validationSamples: validationSuccesses, // Correctly rejected validation tests
+        totalTests,
+        standardDeviation,
+        coefficientOfVariation,
+        confidenceLevel,
+        recommendation,
+    };
+}
+/**
+ * Determine confidence level based on sample count and coefficient of variation.
+ */
+function determineConfidenceLevel(sampleCount, coefficientOfVariation) {
+    // Check for high confidence
+    if (sampleCount >= PERFORMANCE_CONFIDENCE.HIGH.MIN_SAMPLES &&
+        coefficientOfVariation <= PERFORMANCE_CONFIDENCE.HIGH.MAX_CV) {
+        return { confidenceLevel: 'high' };
+    }
+    // Check for medium confidence
+    if (sampleCount >= PERFORMANCE_CONFIDENCE.MEDIUM.MIN_SAMPLES &&
+        coefficientOfVariation <= PERFORMANCE_CONFIDENCE.MEDIUM.MAX_CV) {
+        return { confidenceLevel: 'medium' };
+    }
+    // Low confidence - generate recommendation
+    let recommendation;
+    if (sampleCount < PERFORMANCE_CONFIDENCE.HIGH.MIN_SAMPLES) {
+        recommendation = PERFORMANCE_CONFIDENCE.RECOMMENDATIONS.LOW_SAMPLES(sampleCount, PERFORMANCE_CONFIDENCE.HIGH.MIN_SAMPLES);
+    }
+    else {
+        recommendation = PERFORMANCE_CONFIDENCE.RECOMMENDATIONS.HIGH_VARIABILITY;
+    }
+    return { confidenceLevel: 'low', recommendation };
+}
+/**
+ * Calculate performance confidence from ToolPerformanceMetrics.
+ * Use this when you already have calculated metrics but need confidence.
+ *
+ * Note: This function assumes the metrics are from happy path tests only.
+ * For full validation/success separation, use calculatePerformanceConfidence with raw samples.
+ */
+export function calculateConfidenceFromMetrics(metrics, options) {
+    const { sampleCount, avgMs, stdDevMs } = metrics;
+    const validationSamples = options?.validationSamples ?? 0;
+    const totalTests = options?.totalTests ?? sampleCount;
+    // Handle edge cases
+    if (sampleCount === 0) {
+        return {
+            sampleCount: 0,
+            successfulSamples: 0,
+            validationSamples,
+            totalTests,
+            standardDeviation: 0,
+            coefficientOfVariation: 0,
+            confidenceLevel: 'low',
+            recommendation: PERFORMANCE_CONFIDENCE.RECOMMENDATIONS.NO_SAMPLES,
+        };
+    }
+    // Calculate coefficient of variation
+    const coefficientOfVariation = avgMs > 0 ? stdDevMs / avgMs : 0;
+    // Determine confidence level
+    const { confidenceLevel, recommendation } = determineConfidenceLevel(sampleCount, coefficientOfVariation);
+    return {
+        sampleCount,
+        successfulSamples: sampleCount, // Assumes all samples passed are successful happy path
+        validationSamples,
+        totalTests,
+        standardDeviation: stdDevMs,
+        coefficientOfVariation,
+        confidenceLevel,
+        recommendation,
+    };
+}
+/**
+ * Format confidence level for display.
+ */
+export function formatConfidenceLevel(confidence, includeIndicator = true) {
+    const label = PERFORMANCE_CONFIDENCE.LABELS[confidence.confidenceLevel];
+    const indicator = includeIndicator
+        ? PERFORMANCE_CONFIDENCE.INDICATORS[confidence.confidenceLevel]
+        : '';
+    const sampleInfo = `n=${confidence.sampleCount}`;
+    if (confidence.recommendation) {
+        return `${indicator} ${label} (${sampleInfo}) - ${confidence.recommendation}`;
+    }
+    return `${indicator} ${label} (${sampleInfo})`;
+}
+/**
+ * Check if performance data has sufficient confidence for reliable comparisons.
+ */
+export function hasReliableConfidence(confidence) {
+    return confidence.confidenceLevel === 'high' || confidence.confidenceLevel === 'medium';
+}
+/**
+ * Calculate performance metrics from raw latency samples.
+ */
+export function calculateMetrics(samples) {
+    if (samples.length === 0) {
+        return null;
+    }
+    const toolName = samples[0].toolName;
+    const successfulSamples = samples.filter(s => s.success);
+    const durations = successfulSamples.map(s => s.durationMs).sort((a, b) => a - b);
+    if (durations.length === 0) {
+        // All calls failed
+        const confidence = calculatePerformanceConfidence(samples);
+        return {
+            toolName,
+            p50Ms: 0,
+            p95Ms: 0,
+            p99Ms: 0,
+            successRate: 0,
+            sampleCount: samples.length,
+            avgMs: 0,
+            minMs: 0,
+            maxMs: 0,
+            stdDevMs: 0,
+            collectedAt: new Date(),
+            confidence,
+        };
+    }
+    const p50Ms = calculatePercentile(durations, 50);
+    const p95Ms = calculatePercentile(durations, 95);
+    const p99Ms = calculatePercentile(durations, 99);
+    const avgMs = durations.reduce((sum, d) => sum + d, 0) / durations.length;
+    const minMs = durations[0];
+    const maxMs = durations[durations.length - 1];
+    // Calculate standard deviation
+    const squaredDiffs = durations.map(d => Math.pow(d - avgMs, 2));
+    const avgSquaredDiff = squaredDiffs.reduce((sum, d) => sum + d, 0) / squaredDiffs.length;
+    const stdDevMs = Math.sqrt(avgSquaredDiff);
+    // Calculate confidence from samples
+    const confidence = calculatePerformanceConfidence(samples);
+    return {
+        toolName,
+        p50Ms,
+        p95Ms,
+        p99Ms,
+        successRate: successfulSamples.length / samples.length,
+        sampleCount: samples.length,
+        avgMs,
+        minMs,
+        maxMs,
+        stdDevMs,
+        collectedAt: new Date(),
+        confidence,
+    };
+}
+/**
+ * Calculate a specific percentile from sorted values.
+ */
+function calculatePercentile(sortedValues, percentile) {
+    if (sortedValues.length === 0) {
+        return 0;
+    }
+    if (sortedValues.length === 1) {
+        return sortedValues[0];
+    }
+    const index = (percentile / 100) * (sortedValues.length - 1);
+    const lower = Math.floor(index);
+    const upper = Math.ceil(index);
+    if (lower === upper) {
+        return sortedValues[lower];
+    }
+    // Linear interpolation
+    const fraction = index - lower;
+    return sortedValues[lower] + fraction * (sortedValues[upper] - sortedValues[lower]);
+}
+/**
+ * Create a performance baseline from metrics.
+ */
+export function createPerformanceBaseline(metrics, maxAllowedRegression = PERFORMANCE_TRACKING.DEFAULT_REGRESSION_THRESHOLD) {
+    return {
+        toolName: metrics.toolName,
+        baselineP50: metrics.p50Ms,
+        baselineP95: metrics.p95Ms,
+        baselineP99: metrics.p99Ms,
+        baselineSuccessRate: metrics.successRate,
+        maxAllowedRegression,
+        establishedAt: new Date(),
+    };
+}
+/**
+ * Extract performance baselines from a behavioral baseline.
+ * Uses the performance metrics stored in tool fingerprints.
+ */
+export function extractPerformanceBaselines(baseline, regressionThreshold = PERFORMANCE_TRACKING.DEFAULT_REGRESSION_THRESHOLD) {
+    const baselines = new Map();
+    for (const tool of baseline.tools) {
+        // Only create baseline if performance data exists
+        if (tool.baselineP50Ms !== undefined && tool.baselineP95Ms !== undefined) {
+            baselines.set(tool.name, {
+                toolName: tool.name,
+                baselineP50: tool.baselineP50Ms,
+                baselineP95: tool.baselineP95Ms,
+                baselineP99: tool.baselineP95Ms * 1.2, // Estimate p99 from p95 if not stored
+                baselineSuccessRate: tool.baselineSuccessRate ?? 1.0,
+                maxAllowedRegression: regressionThreshold,
+                establishedAt: baseline.createdAt,
+            });
+        }
+    }
+    return baselines;
+}
+/**
+ * Compare current metrics against baseline.
+ */
+export function comparePerformance(current, baseline, regressionThreshold = PERFORMANCE_TRACKING.DEFAULT_REGRESSION_THRESHOLD) {
+    // Get confidence from current metrics, or calculate if not present
+    const confidence = current.confidence ?? calculateConfidenceFromMetrics(current);
+    const isReliable = hasReliableConfidence(confidence);
+    // No baseline - can't compare
+    if (!baseline) {
+        return {
+            toolName: current.toolName,
+            current,
+            baseline: undefined,
+            trend: 'stable',
+            p50RegressionPercent: null,
+            p95RegressionPercent: null,
+            p99RegressionPercent: null,
+            hasRegression: false,
+            severity: 'none',
+            summary: `No baseline for "${current.toolName}" - metrics recorded for future comparison.`,
+            confidence,
+            isReliable,
+        };
+    }
+    // Calculate regression percentages
+    const p50Regression = calculateRegression(baseline.baselineP50, current.p50Ms);
+    const p95Regression = calculateRegression(baseline.baselineP95, current.p95Ms);
+    const p99Regression = calculateRegression(baseline.baselineP99, current.p99Ms);
+    // Determine trend (based on p50 as primary metric)
+    const trend = determineTrend(p50Regression);
+    // Check for regression
+    const maxRegression = baseline.maxAllowedRegression ?? regressionThreshold;
+    const hasRegression = p50Regression !== null && p50Regression > maxRegression ||
+        p95Regression !== null && p95Regression > maxRegression;
+    // Determine severity
+    const severity = determinePerformanceSeverity(p50Regression, p95Regression, maxRegression);
+    // Generate summary (include confidence note if low)
+    let summary = generateComparisonSummary(current.toolName, trend, p50Regression, p95Regression, hasRegression, maxRegression);
+    // Add confidence warning if low
+    if (!isReliable && confidence.recommendation) {
+        summary += ` (Low confidence: ${confidence.recommendation})`;
+    }
+    return {
+        toolName: current.toolName,
+        current,
+        baseline,
+        trend,
+        p50RegressionPercent: p50Regression,
+        p95RegressionPercent: p95Regression,
+        p99RegressionPercent: p99Regression,
+        hasRegression,
+        severity,
+        summary,
+        confidence,
+        isReliable,
+    };
+}
+/**
+ * Calculate regression percentage.
+ * Returns positive for slower (regression), negative for faster (improvement).
+ */
+function calculateRegression(baseline, current) {
+    if (baseline === 0) {
+        return null;
+    }
+    return (current - baseline) / baseline;
+}
+/**
+ * Determine latency trend from regression percentage.
+ */
+function determineTrend(regression) {
+    if (regression === null) {
+        return 'stable';
+    }
+    if (regression <= PERFORMANCE_TRACKING.TREND_THRESHOLDS.improving) {
+        return 'improving';
+    }
+    if (regression >= PERFORMANCE_TRACKING.TREND_THRESHOLDS.degrading) {
+        return 'degrading';
+    }
+    return 'stable';
+}
+/**
+ * Determine severity based on regression percentages.
+ */
+function determinePerformanceSeverity(p50Regression, p95Regression, threshold) {
+    // Check if any significant regression
+    const maxRegression = Math.max(p50Regression ?? 0, p95Regression ?? 0);
+    if (maxRegression > threshold) {
+        return 'breaking';
+    }
+    if (maxRegression > PERFORMANCE_TRACKING.WARNING_THRESHOLD) {
+        return 'warning';
+    }
+    if (maxRegression > 0) {
+        return 'info';
+    }
+    return 'none';
+}
+/**
+ * Generate human-readable comparison summary.
+ */
+function generateComparisonSummary(toolName, trend, p50Regression, p95Regression, hasRegression, threshold) {
+    if (p50Regression === null) {
+        return `No baseline performance data for "${toolName}".`;
+    }
+    const p50Percent = (p50Regression * 100).toFixed(1);
+    const p95Percent = p95Regression !== null ? (p95Regression * 100).toFixed(1) : 'N/A';
+    const thresholdPercent = (threshold * 100).toFixed(0);
+    if (hasRegression) {
+        return `"${toolName}" performance REGRESSION: p50 ${p50Percent}% slower, p95 ${p95Percent}% slower (threshold: ${thresholdPercent}%)`;
+    }
+    if (trend === 'improving') {
+        return `"${toolName}" performance improved: p50 ${Math.abs(parseFloat(p50Percent))}% faster`;
+    }
+    if (trend === 'degrading') {
+        return `"${toolName}" performance slightly degraded: p50 ${p50Percent}% slower (within threshold)`;
+    }
+    return `"${toolName}" performance stable: p50 ${p50Percent}% change`;
+}
+/**
+ * Generate a complete performance report comparing current and baseline.
+ */
+export function generatePerformanceReport(currentMetrics, baselines, regressionThreshold = PERFORMANCE_TRACKING.DEFAULT_REGRESSION_THRESHOLD) {
+    const comparisons = [];
+    let regressionCount = 0;
+    let improvementCount = 0;
+    let stableCount = 0;
+    let lowConfidenceCount = 0;
+    let reliableRegressionCount = 0;
+    const lowConfidenceTools = [];
+    // Compare each tool
+    for (const [toolName, metrics] of currentMetrics) {
+        const baseline = baselines.get(toolName);
+        const comparison = comparePerformance(metrics, baseline, regressionThreshold);
+        comparisons.push(comparison);
+        if (comparison.hasRegression) {
+            regressionCount++;
+            if (comparison.isReliable) {
+                reliableRegressionCount++;
+            }
+        }
+        else if (comparison.trend === 'improving') {
+            improvementCount++;
+        }
+        else {
+            stableCount++;
+        }
+        // Track low confidence tools
+        if (!comparison.isReliable) {
+            lowConfidenceCount++;
+            lowConfidenceTools.push(toolName);
+        }
+    }
+    // Determine overall trend
+    let overallTrend = 'stable';
+    if (regressionCount > 0) {
+        overallTrend = 'degrading';
+    }
+    else if (improvementCount > stableCount) {
+        overallTrend = 'improving';
+    }
+    // Determine overall severity
+    const overallSeverity = comparisons.reduce((max, c) => {
+        const severityOrder = ['none', 'info', 'warning', 'breaking'];
+        return severityOrder.indexOf(c.severity) > severityOrder.indexOf(max) ? c.severity : max;
+    }, 'none');
+    // Generate summary
+    let summary = generateReportSummary(regressionCount, improvementCount, stableCount, comparisons.length);
+    // Add confidence summary if there are low confidence tools
+    if (lowConfidenceCount > 0) {
+        summary += ` (${lowConfidenceCount} tool(s) with low confidence)`;
+    }
+    return {
+        toolComparisons: comparisons,
+        regressionCount,
+        improvementCount,
+        stableCount,
+        overallTrend,
+        overallSeverity,
+        summary,
+        lowConfidenceCount,
+        lowConfidenceTools,
+        reliableRegressionCount,
+    };
+}
+/**
+ * Generate report summary.
+ */
+function generateReportSummary(regressions, improvements, stable, total) {
+    const parts = [];
+    if (regressions > 0) {
+        parts.push(`${regressions} tool(s) with performance regression`);
+    }
+    if (improvements > 0) {
+        parts.push(`${improvements} tool(s) with improved performance`);
+    }
+    if (stable > 0) {
+        parts.push(`${stable} tool(s) with stable performance`);
+    }
+    if (parts.length === 0) {
+        return `No performance data for ${total} tool(s).`;
+    }
+    return parts.join(', ') + '.';
+}
+/**
+ * Format performance metrics for display.
+ */
+export function formatMetrics(metrics) {
+    const lines = [
+        `Tool: ${metrics.toolName}`,
+        `  p50: ${metrics.p50Ms.toFixed(1)}ms`,
+        `  p95: ${metrics.p95Ms.toFixed(1)}ms`,
+        `  p99: ${metrics.p99Ms.toFixed(1)}ms`,
+        `  avg: ${metrics.avgMs.toFixed(1)}ms`,
+        `  success: ${(metrics.successRate * 100).toFixed(1)}%`,
+        `  samples: ${metrics.sampleCount}`,
+    ];
+    // Add confidence if available
+    if (metrics.confidence) {
+        const confidenceLabel = formatConfidenceLevel(metrics.confidence, true);
+        lines.push(`  confidence: ${confidenceLabel}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Format performance comparison for display.
+ */
+export function formatComparison(comparison) {
+    const lines = [
+        `Tool: ${comparison.toolName}`,
+        `  Trend: ${comparison.trend.toUpperCase()}`,
+    ];
+    if (comparison.p50RegressionPercent !== null) {
+        const sign = comparison.p50RegressionPercent >= 0 ? '+' : '';
+        lines.push(`  p50 change: ${sign}${(comparison.p50RegressionPercent * 100).toFixed(1)}%`);
+    }
+    if (comparison.p95RegressionPercent !== null) {
+        const sign = comparison.p95RegressionPercent >= 0 ? '+' : '';
+        lines.push(`  p95 change: ${sign}${(comparison.p95RegressionPercent * 100).toFixed(1)}%`);
+    }
+    // Add confidence information
+    if (comparison.confidence) {
+        const confidenceLabel = formatConfidenceLevel(comparison.confidence, true);
+        lines.push(`  Confidence: ${confidenceLabel}`);
+    }
+    if (comparison.hasRegression) {
+        if (!comparison.isReliable) {
+            lines.push(`  ⚠️ REGRESSION DETECTED (low confidence - may not be reliable)`);
+        }
+        else {
+            lines.push(`  ⚠️ REGRESSION DETECTED`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Check if metrics indicate acceptable performance.
+ */
+export function isPerformanceAcceptable(comparison, failOnRegression = false) {
+    if (!failOnRegression) {
+        return true;
+    }
+    return !comparison.hasRegression;
+}
+/**
+ * Aggregate multiple samples into metrics grouped by tool.
+ */
+export function aggregateSamplesByTool(samples) {
+    const metrics = new Map();
+    // Group samples by tool
+    const groupedSamples = new Map();
+    for (const sample of samples) {
+        const existing = groupedSamples.get(sample.toolName) || [];
+        existing.push(sample);
+        groupedSamples.set(sample.toolName, existing);
+    }
+    // Calculate metrics for each tool
+    for (const [toolName, toolSamples] of groupedSamples) {
+        const toolMetrics = calculateMetrics(toolSamples);
+        if (toolMetrics) {
+            metrics.set(toolName, toolMetrics);
+        }
+    }
+    return metrics;
+}
+//# sourceMappingURL=performance-tracker.js.map

package/dist/baseline/pr-comment-generator.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Enhanced GitHub PR comment generation for schema changes.
+ *
+ * This module generates detailed, actionable PR comments that help reviewers
+ * understand the impact of schema changes on downstream consumers.
+ */
+import type { BehavioralDiff, ToolDiff, ChangeSeverity } from './types.js';
+import type { MigrationGuide } from './migration-generator.js';
+/**
+ * Severity badge configuration.
+ */
+export type BadgeColor = 'red' | 'orange' | 'blue' | 'green';
+/**
+ * A section in the PR comment.
+ */
+export interface CommentSection {
+    title: string;
+    content: string;
+    priority: number;
+    collapsed?: boolean;
+}
+/**
+ * Affected workflow information for PR comments.
+ */
+export interface AffectedWorkflow {
+    name: string;
+    description: string;
+    affectedTools: string[];
+    severity: ChangeSeverity;
+}
+/**
+ * Complete PR comment structure.
+ */
+export interface PRComment {
+    /** Main title/header */
+    title: string;
+    /** Summary of changes */
+    summary: string;
+    /** Severity badge */
+    badge: {
+        label: string;
+        color: BadgeColor;
+        message: string;
+    };
+    /** Detailed sections */
+    sections: CommentSection[];
+    /** Quick action items */
+    actionItems: string[];
+    /** Footer with metadata */
+    footer: string;
+    /** Full rendered markdown */
+    markdown: string;
+}
+/**
+ * Configuration for PR comment generation.
+ */
+export interface PRCommentConfig {
+    /** Maximum tools to show in detail */
+    maxDetailedTools?: number;
+    /** Maximum changes per tool */
+    maxChangesPerTool?: number;
+    /** Maximum affected workflows to show */
+    maxAffectedWorkflows?: number;
+    /** Include migration examples */
+    includeMigrationExamples?: boolean;
+    /** Maximum migration examples */
+    maxMigrationExamples?: number;
+    /** Include collapsible sections */
+    useCollapsibleSections?: boolean;
+    /** Repository URL for linking */
+    repositoryUrl?: string;
+    /** Base branch name */
+    baseBranch?: string;
+    /** Head branch name */
+    headBranch?: string;
+}
+/**
+ * Get badge color for severity level.
+ */
+export declare function getBadgeColor(severity: ChangeSeverity): BadgeColor;
+/**
+ * Generate a shields.io badge URL.
+ */
+export declare function generateBadgeUrl(label: string, message: string, color: BadgeColor): string;
+/**
+ * Generate a markdown badge.
+ */
+export declare function generateBadgeMarkdown(label: string, message: string, color: BadgeColor): string;
+/**
+ * Generate a complete PR comment for a behavioral diff.
+ */
+export declare function generatePRComment(diff: BehavioralDiff, config?: PRCommentConfig, migrationGuide?: MigrationGuide, affectedWorkflows?: AffectedWorkflow[]): PRComment;
+/**
+ * Generate a compact PR comment for simple diffs.
+ */
+export declare function generateCompactPRComment(diff: BehavioralDiff): string;
+/**
+ * Generate a status check summary for CI.
+ */
+export declare function generateCIStatusSummary(diff: BehavioralDiff): {
+    conclusion: 'success' | 'failure' | 'neutral';
+    title: string;
+    summary: string;
+};
+/**
+ * Generate diff visualization as a table.
+ */
+export declare function generateDiffTable(toolDiffs: ToolDiff[]): string;
+/**
+ * Determine if a PR comment should block merge.
+ */
+export declare function shouldBlockMerge(diff: BehavioralDiff, strictMode?: boolean): boolean;
+/**
+ * Get emoji for severity level.
+ */
+export declare function getSeverityEmoji(severity: ChangeSeverity): string;
+//# sourceMappingURL=pr-comment-generator.d.ts.map