agentic-qe 3.8.13 → 3.9.0

package/dist/shared/retry-engine.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Agentic QE v3 - Unified Retry Engine
+ * IMP-03: Retry Engine with Exponential Backoff
+ *
+ * Provides a single, well-tested retry loop with exponential backoff,
+ * jitter, abort signal support, and retryable-error classification.
+ *
+ * The circuit breaker (circuit-breaker.ts) is a separate concern that
+ * receives success/failure signals from callers — this engine does NOT
+ * import or depend on it. Integration is planned for a later phase.
+ */
+export interface RetryOptions {
+    /** Maximum number of attempts (including the first). Default: 5 */
+    maxAttempts: number;
+    /** Base delay in milliseconds before the first retry. Default: 1000 */
+    baseDelayMs: number;
+    /** Upper cap for the computed delay. Default: 32000 */
+    maxDelayMs: number;
+    /** Fraction of the exponential value added as random jitter (0–1). Default: 0.25 */
+    jitterFraction: number;
+    /** Optional predicate to override the built-in retryable-error check. */
+    retryableErrors?: (error: unknown) => boolean;
+    /** Called before each retry sleep — useful for logging / metrics. */
+    onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
+    /** If the signal fires, the retry loop is cancelled immediately. */
+    abortSignal?: AbortSignal;
+}
+export interface RetryResult<T> {
+    /** The successful return value. */
+    result: T;
+    /** Total number of attempts made (1 = succeeded on first try). */
+    attempts: number;
+    /** Sum of all actual delays waited (ms). */
+    totalDelayMs: number;
+    /** Record of each retried error (does NOT include the successful attempt). */
+    retriedErrors: Array<{
+        attempt: number;
+        error: string;
+        delayMs: number;
+    }>;
+}
+/**
+ * Compute the delay for a given attempt using exponential backoff + jitter.
+ *
+ * Formula: `min(baseMs * 2^attempt, maxMs) + random(0, jitterFraction * exponential)`
+ *
+ * The jitter component is based on the *capped* exponential value so it
+ * stays proportional regardless of the cap.
+ */
+export declare function computeBackoff(attempt: number, baseMs: number, maxMs: number, jitterFraction: number): number;
+/**
+ * Determine whether an error is transient and therefore worth retrying.
+ *
+ * Checks — in order:
+ * 1. Error `code` property against known errno strings.
+ * 2. `status` / `statusCode` property against HTTP status sets.
+ * 3. Error message substrings for common transient phrases.
+ *
+ * Returns `false` for recognised non-retryable client errors (4xx).
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Execute `fn` with automatic retries on transient errors.
+ *
+ * On each failure the engine:
+ * 1. Checks whether the error is retryable (via `options.retryableErrors`
+ *    or the built-in `isRetryableError`).
+ * 2. If not retryable, throws immediately.
+ * 3. If retryable and attempts remain, computes an exponential-backoff
+ *    delay with jitter, calls `onRetry`, then sleeps.
+ * 4. If all attempts are exhausted, throws the last error.
+ *
+ * Supports `AbortSignal` — if the signal fires during a delay the
+ * promise rejects with an `AbortError`.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: Partial<RetryOptions>): Promise<RetryResult<T>>;
+//# sourceMappingURL=retry-engine.d.ts.map

package/dist/shared/retry-engine.js

@@ -0,0 +1,194 @@
+/**
+ * Agentic QE v3 - Unified Retry Engine
+ * IMP-03: Retry Engine with Exponential Backoff
+ *
+ * Provides a single, well-tested retry loop with exponential backoff,
+ * jitter, abort signal support, and retryable-error classification.
+ *
+ * The circuit breaker (circuit-breaker.ts) is a separate concern that
+ * receives success/failure signals from callers — this engine does NOT
+ * import or depend on it. Integration is planned for a later phase.
+ */
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_OPTIONS = {
+    maxAttempts: 5,
+    baseDelayMs: 1000,
+    maxDelayMs: 32_000,
+    jitterFraction: 0.25,
+};
+// ---------------------------------------------------------------------------
+// Backoff computation
+// ---------------------------------------------------------------------------
+/**
+ * Compute the delay for a given attempt using exponential backoff + jitter.
+ *
+ * Formula: `min(baseMs * 2^attempt, maxMs) + random(0, jitterFraction * exponential)`
+ *
+ * The jitter component is based on the *capped* exponential value so it
+ * stays proportional regardless of the cap.
+ */
+export function computeBackoff(attempt, baseMs, maxMs, jitterFraction) {
+    const exponential = Math.min(baseMs * Math.pow(2, attempt), maxMs);
+    const jitter = Math.random() * jitterFraction * exponential;
+    return exponential + jitter;
+}
+// ---------------------------------------------------------------------------
+// Error classification
+// ---------------------------------------------------------------------------
+/** Errno codes that indicate a transient network / OS-level problem. */
+const RETRYABLE_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'EPIPE',
+]);
+/** HTTP status codes that are safe to retry. */
+const RETRYABLE_HTTP_STATUSES = new Set([429, 500, 503, 529]);
+/** HTTP status codes that should NOT be retried (client errors). */
+const NON_RETRYABLE_HTTP_STATUSES = new Set([400, 401, 403, 404, 422]);
+/**
+ * Determine whether an error is transient and therefore worth retrying.
+ *
+ * Checks — in order:
+ * 1. Error `code` property against known errno strings.
+ * 2. `status` / `statusCode` property against HTTP status sets.
+ * 3. Error message substrings for common transient phrases.
+ *
+ * Returns `false` for recognised non-retryable client errors (4xx).
+ */
+export function isRetryableError(error) {
+    if (error == null)
+        return false;
+    // --- code property (errno) -------------------------------------------
+    const code = error.code;
+    if (typeof code === 'string' && RETRYABLE_CODES.has(code)) {
+        return true;
+    }
+    // --- HTTP status -----------------------------------------------------
+    const status = error.status ??
+        error.statusCode;
+    if (typeof status === 'number') {
+        if (NON_RETRYABLE_HTTP_STATUSES.has(status))
+            return false;
+        if (RETRYABLE_HTTP_STATUSES.has(status))
+            return true;
+    }
+    // --- message-based heuristic -----------------------------------------
+    const message = error instanceof Error
+        ? error.message
+        : typeof error.message === 'string'
+            ? error.message
+            : '';
+    if (message) {
+        const lower = message.toLowerCase();
+        if (lower.includes('econnreset') ||
+            lower.includes('econnrefused') ||
+            lower.includes('etimedout') ||
+            lower.includes('epipe') ||
+            lower.includes('rate limit') ||
+            lower.includes('too many requests') ||
+            lower.includes('service unavailable') ||
+            lower.includes('internal server error')) {
+            return true;
+        }
+    }
+    // Default: treat unknown errors as retryable to avoid silent failures.
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Delay helper
+// ---------------------------------------------------------------------------
+/**
+ * Sleep for `ms` milliseconds, but reject immediately if `signal` fires.
+ */
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+            return;
+        }
+        const timer = setTimeout(() => {
+            if (signal) {
+                signal.removeEventListener('abort', onAbort);
+            }
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+        }
+        if (signal) {
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Core retry loop
+// ---------------------------------------------------------------------------
+/**
+ * Execute `fn` with automatic retries on transient errors.
+ *
+ * On each failure the engine:
+ * 1. Checks whether the error is retryable (via `options.retryableErrors`
+ *    or the built-in `isRetryableError`).
+ * 2. If not retryable, throws immediately.
+ * 3. If retryable and attempts remain, computes an exponential-backoff
+ *    delay with jitter, calls `onRetry`, then sleeps.
+ * 4. If all attempts are exhausted, throws the last error.
+ *
+ * Supports `AbortSignal` — if the signal fires during a delay the
+ * promise rejects with an `AbortError`.
+ */
+export async function withRetry(fn, options) {
+    // Kill switch: bypass retry entirely when disabled
+    if (process.env.AQE_RETRY_DISABLED === 'true') {
+        const result = await fn();
+        return { result, attempts: 1, totalDelayMs: 0, retriedErrors: [] };
+    }
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const isRetryable = opts.retryableErrors ?? isRetryableError;
+    const retriedErrors = [];
+    let totalDelayMs = 0;
+    let lastError;
+    for (let attempt = 0; attempt < opts.maxAttempts; attempt++) {
+        // Check abort before each attempt.
+        if (opts.abortSignal?.aborted) {
+            throw opts.abortSignal.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+        }
+        try {
+            const result = await fn();
+            return {
+                result,
+                attempts: attempt + 1,
+                totalDelayMs,
+                retriedErrors,
+            };
+        }
+        catch (error) {
+            lastError = error;
+            // Last attempt — don't bother checking retryability, just throw.
+            if (attempt === opts.maxAttempts - 1) {
+                break;
+            }
+            // Non-retryable errors bubble immediately.
+            if (!isRetryable(error)) {
+                throw error;
+            }
+            const backoff = computeBackoff(attempt, opts.baseDelayMs, opts.maxDelayMs, opts.jitterFraction);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            retriedErrors.push({
+                attempt: attempt + 1,
+                error: errorMessage,
+                delayMs: backoff,
+            });
+            opts.onRetry?.(attempt + 1, error, backoff);
+            totalDelayMs += backoff;
+            await delay(backoff, opts.abortSignal);
+        }
+    }
+    // All attempts exhausted — throw last error.
+    throw lastError;
+}
+//# sourceMappingURL=retry-engine.js.map

package/dist/workers/daemon.d.ts

@@ -6,6 +6,7 @@
  * Provides start/stop/restart functionality and health monitoring.
  */
 import { Daemon as IDaemon, DaemonStatus, WorkerManager } from './interfaces';
+import { QualityDaemon, type QualityDaemonConfig } from './quality-daemon';
 /**
  * Daemon configuration
  */
@@ -28,6 +29,7 @@ export declare class QEDaemon implements IDaemon {
     private _healthCheckTimer?;
     private workerManager;
     private config;
+    private _qualityDaemon?;
     constructor(config?: DaemonConfig);
     get running(): boolean;
     get uptime(): number;
@@ -51,6 +53,12 @@ export declare class QEDaemon implements IDaemon {
      * Get the worker manager for direct access
      */
     getWorkerManager(): WorkerManager;
+    /**
+     * Get or create the quality daemon (IMP-10).
+     * The quality daemon provides proactive quality monitoring:
+     * git watching, coverage delta, CI health, test suggestions, nightly consolidation.
+     */
+    getQualityDaemon(config?: QualityDaemonConfig): QualityDaemon;
     /**
      * Run a specific worker immediately
      */

package/dist/workers/daemon.js

@@ -8,6 +8,7 @@
 import { WorkerManagerImpl } from './worker-manager';
 // Import all QE workers (ADR-014)
 import { TestHealthWorker, CoverageTrackerWorker, FlakyDetectorWorker, SecurityScanWorker, QualityGateWorker, LearningConsolidationWorker, DefectPredictorWorker, RegressionMonitorWorker, PerformanceBaselineWorker, ComplianceCheckerWorker, HeartbeatSchedulerWorker, } from './workers';
+import { QualityDaemon } from './quality-daemon';
 /**
  * Default daemon configuration
  */
@@ -26,6 +27,7 @@ export class QEDaemon {
     _healthCheckTimer;
     workerManager;
     config;
+    _qualityDaemon;
     constructor(config) {
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.workerManager = new WorkerManagerImpl();
@@ -112,6 +114,17 @@ export class QEDaemon {
     getWorkerManager() {
         return this.workerManager;
     }
+    /**
+     * Get or create the quality daemon (IMP-10).
+     * The quality daemon provides proactive quality monitoring:
+     * git watching, coverage delta, CI health, test suggestions, nightly consolidation.
+     */
+    getQualityDaemon(config) {
+        if (!this._qualityDaemon) {
+            this._qualityDaemon = new QualityDaemon(config);
+        }
+        return this._qualityDaemon;
+    }
     /**
      * Run a specific worker immediately
      */

package/dist/workers/quality-daemon/ci-monitor.d.ts

@@ -0,0 +1,55 @@
+/**
+ * IMP-10: QE Quality Daemon — CI/CD Health Monitor
+ *
+ * Polls GitHub Actions workflow status via the `gh` CLI.
+ * Detects failure patterns (same test failing N times) and
+ * enqueues 'now' priority notifications for quality gate failures.
+ */
+import type { PriorityQueue } from './priority-queue';
+export interface CIMonitorOptions {
+    /** How many recent runs to fetch per workflow */
+    runsPerWorkflow?: number;
+    /** Consecutive failure count to trigger flaky detection */
+    flakyThreshold?: number;
+    /** Repository in owner/repo format (auto-detected if omitted) */
+    repo?: string;
+}
+export interface WorkflowRun {
+    readonly name: string;
+    readonly status: string;
+    readonly conclusion: string;
+    readonly headBranch: string;
+    readonly runNumber: number;
+    readonly databaseId: number;
+    readonly createdAt: string;
+}
+export interface CIHealthReport {
+    readonly timestamp: number;
+    readonly workflows: WorkflowStatus[];
+    readonly failingWorkflows: number;
+    readonly flakyWorkflows: string[];
+    readonly healthScore: number;
+}
+export interface WorkflowStatus {
+    readonly name: string;
+    readonly recentRuns: number;
+    readonly failedRuns: number;
+    readonly successRate: number;
+    readonly lastConclusion: string;
+    readonly consecutiveFailures: number;
+}
+export declare class CIMonitor {
+    private readonly queue;
+    private options;
+    constructor(queue: PriorityQueue, options?: CIMonitorOptions);
+    /**
+     * Poll GitHub Actions and produce a health report.
+     */
+    check(): Promise<CIHealthReport>;
+    private fetchRecentRuns;
+    private groupByWorkflow;
+    private countConsecutiveFailures;
+    private calculateHealthScore;
+    private enqueueFailureAlert;
+}
+//# sourceMappingURL=ci-monitor.d.ts.map

package/dist/workers/quality-daemon/ci-monitor.js

@@ -0,0 +1,147 @@
+/**
+ * IMP-10: QE Quality Daemon — CI/CD Health Monitor
+ *
+ * Polls GitHub Actions workflow status via the `gh` CLI.
+ * Detects failure patterns (same test failing N times) and
+ * enqueues 'now' priority notifications for quality gate failures.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+const DEFAULTS = {
+    runsPerWorkflow: 10,
+    flakyThreshold: 3,
+    repo: '',
+};
+export class CIMonitor {
+    queue;
+    options;
+    constructor(queue, options) {
+        this.queue = queue;
+        this.options = { ...DEFAULTS, ...options };
+    }
+    /**
+     * Poll GitHub Actions and produce a health report.
+     */
+    async check() {
+        const runs = await this.fetchRecentRuns();
+        const grouped = this.groupByWorkflow(runs);
+        const workflows = [];
+        const flakyWorkflows = [];
+        let failingCount = 0;
+        for (const [name, workflowRuns] of Object.entries(grouped)) {
+            const failedRuns = workflowRuns.filter((r) => r.conclusion === 'failure').length;
+            const successRate = workflowRuns.length > 0
+                ? ((workflowRuns.length - failedRuns) / workflowRuns.length) * 100
+                : 100;
+            const consecutiveFailures = this.countConsecutiveFailures(workflowRuns);
+            const lastConclusion = workflowRuns[0]?.conclusion ?? 'unknown';
+            if (lastConclusion === 'failure') {
+                failingCount++;
+            }
+            if (consecutiveFailures >= this.options.flakyThreshold) {
+                flakyWorkflows.push(name);
+                // Enqueue 'now' alert for persistent failures
+                this.enqueueFailureAlert(name, workflowRuns[0]);
+            }
+            workflows.push({
+                name,
+                recentRuns: workflowRuns.length,
+                failedRuns,
+                successRate: Math.round(successRate * 10) / 10,
+                lastConclusion,
+                consecutiveFailures,
+            });
+        }
+        const healthScore = this.calculateHealthScore(workflows);
+        return {
+            timestamp: Date.now(),
+            workflows,
+            failingWorkflows: failingCount,
+            flakyWorkflows,
+            healthScore,
+        };
+    }
+    // ============================================================================
+    // Private
+    // ============================================================================
+    async fetchRecentRuns() {
+        try {
+            const args = [
+                'run', 'list',
+                '--limit', String(this.options.runsPerWorkflow * 5), // fetch extra to cover multiple workflows
+                '--json', 'name,status,conclusion,headBranch,number,databaseId,createdAt',
+            ];
+            if (this.options.repo) {
+                args.push('--repo', this.options.repo);
+            }
+            const { stdout } = await execFileAsync('gh', args, {
+                timeout: 15000,
+            });
+            const parsed = JSON.parse(stdout);
+            return parsed.map((r) => ({
+                name: r.name,
+                status: r.status,
+                conclusion: r.conclusion ?? 'pending',
+                headBranch: r.headBranch,
+                runNumber: r.number,
+                databaseId: r.databaseId,
+                createdAt: r.createdAt,
+            }));
+        }
+        catch {
+            // gh CLI not available or not authenticated
+            return [];
+        }
+    }
+    groupByWorkflow(runs) {
+        const grouped = {};
+        for (const run of runs) {
+            if (!grouped[run.name]) {
+                grouped[run.name] = [];
+            }
+            grouped[run.name].push(run);
+        }
+        // Limit per workflow
+        for (const name of Object.keys(grouped)) {
+            grouped[name] = grouped[name].slice(0, this.options.runsPerWorkflow);
+        }
+        return grouped;
+    }
+    countConsecutiveFailures(runs) {
+        let count = 0;
+        for (const run of runs) {
+            if (run.conclusion === 'failure') {
+                count++;
+            }
+            else {
+                break;
+            }
+        }
+        return count;
+    }
+    calculateHealthScore(workflows) {
+        if (workflows.length === 0)
+            return 100;
+        const avgSuccess = workflows.reduce((sum, w) => sum + w.successRate, 0) / workflows.length;
+        return Math.round(avgSuccess);
+    }
+    enqueueFailureAlert(name, run) {
+        const payload = {
+            type: 'ci_failure',
+            workflowName: name,
+            runId: run.databaseId,
+            conclusion: run.conclusion,
+        };
+        const item = {
+            id: `ci-failure-${name}-${Date.now()}`,
+            priority: 'now',
+            payload,
+            createdAt: Date.now(),
+            source: 'ci-monitor',
+            ttlMs: 30 * 60 * 1000, // 30 min TTL
+        };
+        this.queue.enqueue(item);
+    }
+}
+//# sourceMappingURL=ci-monitor.js.map

package/dist/workers/quality-daemon/coverage-delta.d.ts

@@ -0,0 +1,72 @@
+/**
+ * IMP-10: QE Quality Daemon — Coverage Delta Analysis
+ *
+ * Compares current coverage with previous snapshot to identify:
+ * - Newly uncovered lines in changed files
+ * - Coverage regressions
+ * - Coverage gaps exceeding configurable thresholds
+ *
+ * Enqueues test suggestion tasks when gaps exceed threshold.
+ */
+import type { WorkerMemory } from '../interfaces';
+import type { PriorityQueue } from './priority-queue';
+export interface CoverageSnapshot {
+    readonly timestamp: number;
+    readonly overall: CoverageMetrics;
+    readonly files: Record<string, FileCoverage>;
+}
+export interface CoverageMetrics {
+    readonly line: number;
+    readonly branch: number;
+    readonly function: number;
+    readonly statement: number;
+}
+export interface FileCoverage {
+    readonly line: number;
+    readonly branch: number;
+    readonly uncoveredLines: number[];
+    readonly totalLines: number;
+}
+export interface CoverageDeltaResult {
+    readonly regressionDetected: boolean;
+    readonly overallDelta: CoverageMetrics;
+    readonly affectedFiles: FileDelta[];
+    readonly newGaps: CoverageGap[];
+}
+export interface FileDelta {
+    readonly file: string;
+    readonly lineDelta: number;
+    readonly branchDelta: number;
+    readonly newUncoveredLines: number[];
+}
+export interface CoverageGap {
+    readonly file: string;
+    readonly uncoveredLines: number[];
+    readonly currentCoverage: number;
+    readonly riskScore: number;
+}
+export interface CoverageDeltaOptions {
+    /** Line coverage drop threshold to flag as regression (percentage points) */
+    regressionThreshold?: number;
+    /** Minimum file coverage to avoid flagging as a gap */
+    gapThreshold?: number;
+    /** Key prefix in worker memory for snapshots */
+    memoryPrefix?: string;
+}
+export declare class CoverageDeltaAnalyzer {
+    private readonly queue;
+    private options;
+    constructor(queue: PriorityQueue, options?: CoverageDeltaOptions);
+    /**
+     * Analyze coverage delta between the current and previous snapshot.
+     * Stores the current snapshot and enqueues test suggestions if needed.
+     */
+    analyze(current: CoverageSnapshot, memory: WorkerMemory, changedFiles?: string[]): Promise<CoverageDeltaResult>;
+    /**
+     * Build a CoverageSnapshot from raw lcov/istanbul data stored in memory.
+     */
+    buildSnapshot(memory: WorkerMemory): Promise<CoverageSnapshot | undefined>;
+    private computeRiskScore;
+    private enqueueTestSuggestion;
+}
+//# sourceMappingURL=coverage-delta.d.ts.map