@dotsetlabs/bellwether 0.10.0

package/dist/baseline/deprecation-tracker.js

@@ -0,0 +1,322 @@
+/**
+ * Deprecation Lifecycle Management
+ *
+ * Tracks tool deprecation status and warns consumers about deprecated tools.
+ * Supports grace periods, replacement suggestions, and removal date enforcement.
+ */
+import { DEPRECATION } from '../constants.js';
+// Re-export centralized constant for backwards compatibility
+export { DEPRECATION } from '../constants.js';
+/**
+ * Default deprecation configuration.
+ * Uses values from centralized constants.
+ */
+export const DEPRECATION_DEFAULTS = {
+    warnOnUsage: DEPRECATION.DEFAULTS.warnOnUsage,
+    failOnExpired: DEPRECATION.DEFAULTS.failOnExpired,
+    gracePeriodDays: DEPRECATION.DEFAULTS.gracePeriodDays,
+    deprecatedSeverity: 'warning',
+    expiredSeverity: 'breaking',
+};
+/**
+ * Days thresholds for warning levels.
+ * Uses values from centralized constants.
+ */
+export const DEPRECATION_THRESHOLDS = {
+    /** Warn about upcoming removal within this many days */
+    UPCOMING_REMOVAL_DAYS: DEPRECATION.THRESHOLDS.upcomingRemovalDays,
+    /** Critical warning within this many days */
+    CRITICAL_REMOVAL_DAYS: DEPRECATION.THRESHOLDS.criticalRemovalDays,
+};
+/**
+ * Check all tools in a baseline for deprecation issues.
+ */
+export function checkDeprecations(baseline, config = {}) {
+    const fullConfig = { ...DEPRECATION_DEFAULTS, ...config };
+    const warnings = [];
+    let deprecatedCount = 0;
+    let expiredCount = 0;
+    let gracePeriodCount = 0;
+    const now = new Date();
+    for (const tool of baseline.tools) {
+        const warning = checkToolDeprecation(tool, now, fullConfig);
+        if (warning) {
+            warnings.push(warning);
+            if (warning.status === 'removed' || warning.isPastRemoval) {
+                expiredCount++;
+            }
+            else if (warning.status === 'deprecated') {
+                deprecatedCount++;
+            }
+            if (warning.isInGracePeriod) {
+                gracePeriodCount++;
+            }
+        }
+    }
+    // Determine overall severity
+    const overallSeverity = determineOverallSeverity(warnings);
+    // Generate summary
+    const summary = generateDeprecationSummary(warnings, deprecatedCount, expiredCount, gracePeriodCount);
+    return {
+        warnings,
+        deprecatedCount,
+        expiredCount,
+        gracePeriodCount,
+        overallSeverity,
+        summary,
+        hasCriticalIssues: expiredCount > 0,
+    };
+}
+/**
+ * Check a single tool for deprecation issues.
+ */
+export function checkToolDeprecation(tool, now = new Date(), config = DEPRECATION_DEFAULTS) {
+    // Not deprecated - no warning
+    if (!tool.deprecated) {
+        return null;
+    }
+    // Calculate days until removal (if removal date is set)
+    let daysUntilRemoval;
+    let isPastRemoval = false;
+    let isInGracePeriod = false;
+    if (tool.removalDate) {
+        const removalDate = new Date(tool.removalDate);
+        const diffMs = removalDate.getTime() - now.getTime();
+        daysUntilRemoval = Math.ceil(diffMs / (1000 * 60 * 60 * 24));
+        isPastRemoval = daysUntilRemoval < 0;
+        // Check grace period
+        if (isPastRemoval) {
+            const daysPastRemoval = Math.abs(daysUntilRemoval);
+            isInGracePeriod = daysPastRemoval <= config.gracePeriodDays;
+        }
+    }
+    // Determine status
+    let status = 'deprecated';
+    if (isPastRemoval && !isInGracePeriod) {
+        status = 'removed';
+    }
+    else if (isPastRemoval && isInGracePeriod) {
+        status = 'sunset';
+    }
+    // Determine severity
+    let severity = config.deprecatedSeverity;
+    if (status === 'removed') {
+        severity = config.expiredSeverity;
+    }
+    else if (status === 'sunset') {
+        severity = 'warning';
+    }
+    else if (daysUntilRemoval !== undefined && daysUntilRemoval <= DEPRECATION_THRESHOLDS.CRITICAL_REMOVAL_DAYS) {
+        severity = 'breaking';
+    }
+    // Generate message
+    const message = generateDeprecationMessage(tool, status, daysUntilRemoval);
+    return {
+        toolName: tool.name,
+        status,
+        severity,
+        message,
+        deprecatedAt: tool.deprecatedAt ? new Date(tool.deprecatedAt) : undefined,
+        removalDate: tool.removalDate ? new Date(tool.removalDate) : undefined,
+        daysUntilRemoval,
+        replacementTool: tool.replacementTool,
+        deprecationNotice: tool.deprecationNotice,
+        isPastRemoval,
+        isInGracePeriod,
+    };
+}
+/**
+ * Mark a tool as deprecated.
+ */
+export function markAsDeprecated(tool, options = {}) {
+    return {
+        ...tool,
+        deprecated: true,
+        deprecatedAt: new Date(),
+        deprecationNotice: options.notice,
+        removalDate: options.removalDate,
+        replacementTool: options.replacementTool,
+    };
+}
+/**
+ * Clear deprecation status from a tool.
+ */
+export function clearDeprecation(tool) {
+    const { deprecated: _, deprecatedAt: _1, deprecationNotice: _2, removalDate: _3, replacementTool: _4, ...rest } = tool;
+    void [_, _1, _2, _3, _4]; // Explicitly discard unused variables
+    return rest;
+}
+/**
+ * Generate deprecation message for a tool.
+ */
+function generateDeprecationMessage(tool, status, daysUntilRemoval) {
+    const parts = [];
+    switch (status) {
+        case 'removed':
+            parts.push(`Tool "${tool.name}" has been REMOVED and is past its removal date.`);
+            break;
+        case 'sunset':
+            parts.push(`Tool "${tool.name}" is in SUNSET phase (grace period).`);
+            if (daysUntilRemoval !== undefined) {
+                parts.push(`Removal date was ${Math.abs(daysUntilRemoval)} day(s) ago.`);
+            }
+            break;
+        case 'deprecated':
+            parts.push(`Tool "${tool.name}" is DEPRECATED.`);
+            if (daysUntilRemoval !== undefined) {
+                if (daysUntilRemoval <= DEPRECATION_THRESHOLDS.CRITICAL_REMOVAL_DAYS) {
+                    parts.push(`CRITICAL: Will be removed in ${daysUntilRemoval} day(s)!`);
+                }
+                else if (daysUntilRemoval <= DEPRECATION_THRESHOLDS.UPCOMING_REMOVAL_DAYS) {
+                    parts.push(`Will be removed in ${daysUntilRemoval} day(s).`);
+                }
+                else {
+                    parts.push(`Scheduled for removal on ${tool.removalDate}.`);
+                }
+            }
+            break;
+    }
+    // Add notice if available
+    if (tool.deprecationNotice) {
+        parts.push(`Notice: ${tool.deprecationNotice}`);
+    }
+    // Add replacement suggestion
+    if (tool.replacementTool) {
+        parts.push(`Use "${tool.replacementTool}" instead.`);
+    }
+    return parts.join(' ');
+}
+/**
+ * Determine overall severity from warnings.
+ */
+function determineOverallSeverity(warnings) {
+    if (warnings.length === 0) {
+        return 'none';
+    }
+    // Check for any critical issues (removed tools)
+    if (warnings.some(w => w.status === 'removed')) {
+        return 'breaking';
+    }
+    // Check for sunset tools
+    if (warnings.some(w => w.status === 'sunset')) {
+        return 'warning';
+    }
+    // Check for upcoming critical removals
+    if (warnings.some(w => w.daysUntilRemoval !== undefined && w.daysUntilRemoval <= DEPRECATION_THRESHOLDS.CRITICAL_REMOVAL_DAYS)) {
+        return 'breaking';
+    }
+    // All deprecated tools
+    return 'warning';
+}
+/**
+ * Generate summary message for deprecation report.
+ */
+function generateDeprecationSummary(warnings, deprecatedCount, expiredCount, gracePeriodCount) {
+    if (warnings.length === 0) {
+        return 'No deprecated tools found.';
+    }
+    const parts = [];
+    if (expiredCount > 0) {
+        parts.push(`${expiredCount} tool(s) past removal date`);
+    }
+    if (gracePeriodCount > 0) {
+        parts.push(`${gracePeriodCount} tool(s) in grace period`);
+    }
+    if (deprecatedCount > 0) {
+        parts.push(`${deprecatedCount} deprecated tool(s)`);
+    }
+    // Add critical warnings
+    const criticalTools = warnings.filter(w => w.daysUntilRemoval !== undefined && w.daysUntilRemoval <= DEPRECATION_THRESHOLDS.CRITICAL_REMOVAL_DAYS && w.daysUntilRemoval >= 0);
+    if (criticalTools.length > 0) {
+        parts.push(`${criticalTools.length} tool(s) will be removed within ${DEPRECATION_THRESHOLDS.CRITICAL_REMOVAL_DAYS} days`);
+    }
+    return parts.join(', ') + '.';
+}
+/**
+ * Get all deprecated tools from a baseline.
+ */
+export function getDeprecatedTools(baseline) {
+    return baseline.tools.filter(t => t.deprecated);
+}
+/**
+ * Get tools that are past their removal date.
+ */
+export function getExpiredTools(baseline, now = new Date()) {
+    return baseline.tools.filter(t => {
+        if (!t.deprecated || !t.removalDate) {
+            return false;
+        }
+        const removalDate = new Date(t.removalDate);
+        return now > removalDate;
+    });
+}
+/**
+ * Get tools that will be removed within a specified number of days.
+ */
+export function getUpcomingRemovals(baseline, withinDays = DEPRECATION_THRESHOLDS.UPCOMING_REMOVAL_DAYS, now = new Date()) {
+    return baseline.tools.filter(t => {
+        if (!t.deprecated || !t.removalDate) {
+            return false;
+        }
+        const removalDate = new Date(t.removalDate);
+        const diffMs = removalDate.getTime() - now.getTime();
+        const daysUntil = Math.ceil(diffMs / (1000 * 60 * 60 * 24));
+        return daysUntil >= 0 && daysUntil <= withinDays;
+    });
+}
+/**
+ * Format deprecation warning for display.
+ */
+export function formatDeprecationWarning(warning) {
+    const lines = [];
+    const icon = warning.isPastRemoval ? '❌' : warning.isInGracePeriod ? '⚠️' : '🕐';
+    lines.push(`${icon} ${warning.toolName} [${warning.status.toUpperCase()}]`);
+    lines.push(`   ${warning.message}`);
+    if (warning.replacementTool) {
+        lines.push(`   Replacement: ${warning.replacementTool}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Format deprecation report for console output.
+ */
+export function formatDeprecationReport(report) {
+    const lines = ['Deprecation Report', '═'.repeat(50), ''];
+    if (report.warnings.length === 0) {
+        lines.push('✓ No deprecated tools found.');
+        return lines.join('\n');
+    }
+    lines.push(report.summary);
+    lines.push('');
+    // Group by status
+    const byStatus = new Map();
+    for (const warning of report.warnings) {
+        const existing = byStatus.get(warning.status) || [];
+        existing.push(warning);
+        byStatus.set(warning.status, existing);
+    }
+    // Show removed first
+    const statusOrder = ['removed', 'sunset', 'deprecated'];
+    for (const status of statusOrder) {
+        const warnings = byStatus.get(status);
+        if (warnings && warnings.length > 0) {
+            lines.push(`─── ${status.toUpperCase()} ───`);
+            for (const warning of warnings) {
+                lines.push(formatDeprecationWarning(warning));
+                lines.push('');
+            }
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Check if deprecation report should cause failure.
+ */
+export function shouldFailOnDeprecation(report, config = {}) {
+    const fullConfig = { ...DEPRECATION_DEFAULTS, ...config };
+    if (!fullConfig.failOnExpired) {
+        return false;
+    }
+    return report.expiredCount > 0;
+}
+//# sourceMappingURL=deprecation-tracker.js.map

package/dist/baseline/diff.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Diff output formatting for human and machine consumption.
+ */
+import type { BehavioralDiff } from './types.js';
+import type { SecurityDiff } from '../security/types.js';
+/**
+ * Format diff for human-readable console output.
+ */
+export declare function formatDiffText(diff: BehavioralDiff, useColors?: boolean): string;
+/**
+ * Format diff as JSON.
+ */
+export declare function formatDiffJson(diff: BehavioralDiff): string;
+/**
+ * Format diff in a compact single-line format for CI logs.
+ */
+export declare function formatDiffCompact(diff: BehavioralDiff): string;
+/**
+ * Format diff for GitHub Actions annotations.
+ */
+export declare function formatDiffGitHubActions(diff: BehavioralDiff): string;
+/**
+ * Format diff as markdown.
+ */
+export declare function formatDiffMarkdown(diff: BehavioralDiff): string;
+/**
+ * Format diff as JUnit XML for CI dashboard integration.
+ *
+ * JUnit XML is widely supported by CI/CD systems (Jenkins, GitLab CI,
+ * CircleCI, Azure DevOps, etc.) for test result visualization.
+ *
+ * @param diff - The behavioral diff to format
+ * @param suiteName - Name for the test suite (default: 'bellwether')
+ * @returns JUnit XML string
+ */
+export declare function formatDiffJUnit(diff: BehavioralDiff, suiteName?: string): string;
+/**
+ * Format diff as SARIF (Static Analysis Results Interchange Format) for GitHub Code Scanning.
+ *
+ * SARIF is the standard format for GitHub's code scanning feature and can be
+ * uploaded to show drift detection results in pull request reviews.
+ *
+ * @see https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+ *
+ * @param diff - The behavioral diff to format
+ * @param baselinePath - Path to the baseline file (for location references)
+ * @returns SARIF JSON string
+ */
+export declare function formatDiffSarif(diff: BehavioralDiff, baselinePath?: string): string;
+/**
+ * Format a standalone security report for display.
+ * Used when only security data is available (not a full diff).
+ */
+export declare function formatSecurityReport(report: SecurityDiff, useColors?: boolean): string;
+//# sourceMappingURL=diff.d.ts.map