@lumenflow/core 1.0.0

package/dist/retry-strategy.js

@@ -0,0 +1,283 @@
+/**
+ * WU-1747: Retry Strategy Module
+ *
+ * Provides exponential backoff retry mechanism with configurable parameters
+ * for wu:done concurrent load resilience.
+ *
+ * Features:
+ * - Configurable max attempts, base delay, multiplier
+ * - Exponential backoff with optional jitter
+ * - Presets for common scenarios (wu_done, recovery)
+ * - Callback hooks for retry events
+ * - Conditional retry based on error type
+ *
+ * @module retry-strategy
+ */
+import { LOG_PREFIX, EMOJI } from './wu-constants.js';
+/**
+ * Error message patterns that are considered retryable for wu:done operations
+ * Exported for test consistency
+ */
+export const RETRYABLE_ERROR_PATTERNS = Object.freeze({
+    FAST_FORWARD: 'fast-forward',
+    NOT_POSSIBLE: 'not possible',
+    CANNOT_LOCK_REF: 'Cannot lock ref',
+    FETCH: 'fetch',
+    PUSH: 'push',
+    ETIMEDOUT: 'ETIMEDOUT',
+    ECONNRESET: 'ECONNRESET',
+});
+/**
+ * @typedef {Object} RetryConfig
+ * @property {number} maxAttempts - Maximum number of attempts (default: 5)
+ * @property {number} baseDelayMs - Base delay in milliseconds (default: 1000)
+ * @property {number} maxDelayMs - Maximum delay cap in milliseconds (default: 30000)
+ * @property {number} multiplier - Exponential multiplier (default: 2)
+ * @property {number} jitter - Jitter factor 0-1 (default: 0.1 for 10%)
+ * @property {function} [shouldRetry] - Optional function(error) => boolean to determine if error is retryable
+ * @property {function} [onRetry] - Optional callback(attempt, error, delay) before each retry
+ */
+/**
+ * Default retry configuration
+ * Balanced for typical wu:done operations
+ */
+export const DEFAULT_RETRY_CONFIG = Object.freeze({
+    maxAttempts: 5,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    multiplier: 2,
+    jitter: 0.1,
+    shouldRetry: (_error) => true,
+    onRetry: null,
+});
+/**
+ * Pre-configured retry presets for common scenarios
+ */
+export const RETRY_PRESETS = Object.freeze({
+    /**
+     * Preset for wu:done merge operations
+     * Higher attempts and longer delays for handling concurrent load
+     */
+    wu_done: Object.freeze({
+        maxAttempts: 6,
+        baseDelayMs: 2000,
+        maxDelayMs: 60000,
+        multiplier: 2,
+        jitter: 0.15, // 15% jitter to spread concurrent retries
+        shouldRetry: (error) => {
+            // Retry fast-forward failures and network errors using defined patterns
+            const message = error.message || '';
+            return Object.values(RETRYABLE_ERROR_PATTERNS).some((pattern) => message.includes(pattern));
+        },
+        onRetry: null,
+    }),
+    /**
+     * Preset for zombie state recovery
+     * More attempts with shorter delays
+     */
+    recovery: Object.freeze({
+        maxAttempts: 4,
+        baseDelayMs: 500,
+        maxDelayMs: 10000,
+        multiplier: 2,
+        jitter: 0.1,
+        shouldRetry: () => true,
+        onRetry: null,
+    }),
+    /**
+     * Preset for quick operations (file I/O, local git)
+     * Fast retries for transient errors
+     */
+    quick: Object.freeze({
+        maxAttempts: 3,
+        baseDelayMs: 100,
+        maxDelayMs: 2000,
+        multiplier: 2,
+        jitter: 0.05,
+        shouldRetry: () => true,
+        onRetry: null,
+    }),
+});
+/**
+ * Create a retry configuration by merging defaults with custom options
+ *
+ * @param {string|Object} [presetOrOptions] - Preset name or custom options
+ * @param {Object} [options] - Additional options to merge (when first arg is preset name)
+ * @returns {RetryConfig} Complete retry configuration
+ *
+ * @example
+ * // Use defaults
+ * const config = createRetryConfig();
+ *
+ * @example
+ * // Customize defaults
+ * const config = createRetryConfig({ maxAttempts: 10 });
+ *
+ * @example
+ * // Use preset
+ * const config = createRetryConfig('wu_done');
+ *
+ * @example
+ * // Customize preset
+ * const config = createRetryConfig('wu_done', { maxAttempts: 10 });
+ */
+export function createRetryConfig(presetOrOptions, options) {
+    // Determine base config
+    let baseConfig;
+    let customOptions;
+    if (typeof presetOrOptions === 'string') {
+        // First arg is preset name
+        if (!(presetOrOptions in RETRY_PRESETS)) {
+            throw new Error(`Unknown retry preset: ${presetOrOptions}`);
+        }
+        baseConfig = RETRY_PRESETS[presetOrOptions];
+        customOptions = options || {};
+    }
+    else {
+        // First arg is options (or undefined)
+        baseConfig = DEFAULT_RETRY_CONFIG;
+        customOptions = presetOrOptions || {};
+    }
+    // Merge and return
+    // Avoid overriding preset/default values with `undefined` (WU-1756):
+    // callers often pass option keys conditionally, and spreading `undefined`
+    // clobbers required defaults (e.g., maxAttempts) leading to zero-attempt retries.
+    const definedOptions = Object.fromEntries(Object.entries(customOptions).filter(([, value]) => value !== undefined));
+    return {
+        ...baseConfig,
+        ...definedOptions,
+    };
+}
+/**
+ * Calculate the backoff delay for a given attempt number
+ *
+ * Uses exponential backoff formula: baseDelay * (multiplier ^ attempt)
+ * with optional jitter to spread concurrent retry attempts
+ *
+ * @param {number} attempt - Zero-based attempt number (0 = first attempt)
+ * @param {RetryConfig} config - Retry configuration
+ * @returns {number} Delay in milliseconds
+ */
+export function calculateBackoffDelay(attempt, config) {
+    const { baseDelayMs, multiplier, maxDelayMs, jitter } = config;
+    // Exponential backoff: base * multiplier^attempt
+    let delay = baseDelayMs * Math.pow(multiplier, attempt);
+    // Cap at max delay
+    delay = Math.min(delay, maxDelayMs);
+    // Add jitter if enabled (spreads concurrent retries)
+    if (jitter > 0) {
+        // Jitter adds/subtracts random percentage
+        const jitterRange = delay * jitter;
+        const jitterOffset = (Math.random() * 2 - 1) * jitterRange;
+        delay = delay + jitterOffset;
+    }
+    return Math.round(delay);
+}
+/**
+ * Sleep for specified milliseconds
+ *
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Execute a function with retry logic and exponential backoff
+ *
+ * @template T
+ * @param {function(): Promise<T>} fn - Async function to execute
+ * @param {RetryConfig} [config] - Retry configuration (uses defaults if not provided)
+ * @returns {Promise<T>} Result of successful execution
+ * @throws {Error} Last error if all attempts fail
+ *
+ * @example
+ * const result = await withRetry(
+ *   async () => await mergeBranch(),
+ *   createRetryConfig('wu_done')
+ * );
+ */
+export async function withRetry(fn, config = DEFAULT_RETRY_CONFIG) {
+    const { maxAttempts, shouldRetry, onRetry } = config;
+    let lastError;
+    let attempt = 0;
+    while (attempt < maxAttempts) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            attempt++;
+            // Check if we should retry
+            if (attempt >= maxAttempts) {
+                break; // Max attempts reached
+            }
+            if (!shouldRetry(error)) {
+                break; // Error not retryable
+            }
+            // Calculate delay for next retry
+            const delay = calculateBackoffDelay(attempt - 1, config);
+            // Call onRetry callback if provided
+            if (typeof onRetry === 'function') {
+                onRetry(attempt, error, delay);
+            }
+            // Log retry info
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Attempt ${attempt}/${maxAttempts} failed: ${error.message}`);
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Retrying in ${delay}ms...`);
+            // Wait before retry
+            await sleep(delay);
+        }
+    }
+    // All attempts failed
+    // Defensive: if a caller passes an invalid config, ensure we throw a useful error.
+    if (!lastError) {
+        throw new Error(`Operation failed: invalid retry configuration (maxAttempts=${maxAttempts})`);
+    }
+    throw new Error(`Operation failed after ${attempt} attempt(s): ${lastError.message}\n` +
+        `Original error: ${lastError.stack || lastError.message}`);
+}
+/**
+ * Higher-order function to wrap a function with retry logic
+ *
+ * @template T
+ * @param {function(...args): Promise<T>} fn - Function to wrap
+ * @param {RetryConfig} [config] - Retry configuration
+ * @returns {function(...args): Promise<T>} Wrapped function with retry logic
+ *
+ * @example
+ * const retryableMerge = withRetryWrapper(mergeBranch, createRetryConfig('wu_done'));
+ * await retryableMerge(branch);
+ */
+export function withRetryWrapper(fn, config = DEFAULT_RETRY_CONFIG) {
+    return async (...args) => {
+        return withRetry(() => fn(...args), config);
+    };
+}
+/**
+ * Determine if an error is a git conflict error (non-retryable)
+ *
+ * @param {Error} error - Error to check
+ * @returns {boolean} True if conflict error
+ */
+export function isConflictError(error) {
+    const message = error.message || '';
+    return (message.includes('conflict') ||
+        message.includes('CONFLICT') ||
+        message.includes('<<<<<<<') ||
+        message.includes('not possible to fast-forward'));
+}
+/**
+ * Determine if an error is a network/transient error (retryable)
+ *
+ * @param {Error} error - Error to check
+ * @returns {boolean} True if likely transient
+ */
+export function isTransientError(error) {
+    const message = error.message || '';
+    return (message.includes('ETIMEDOUT') ||
+        message.includes('ECONNRESET') ||
+        message.includes('ECONNREFUSED') ||
+        message.includes('fetch failed') ||
+        message.includes('network') ||
+        message.includes('timeout'));
+}

package/dist/risk-detector.d.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Risk Detector
+ *
+ * WU-2062: Implement tiered test execution for faster wu:done
+ *
+ * Detects risk tier based on changed files to enable tiered test execution:
+ * - docs-only: Skip tests, run lint/typecheck only
+ * - standard: Run changed tests
+ * - high-risk: Run integration tests in addition to unit tests
+ *
+ * Safety-critical tests (red-flag, PHI, escalation) always run regardless of tier.
+ *
+ * Note: This is project-specific risk detection logic for PatientPath's
+ * healthcare domain (PHI, RLS, auth). No standard library exists for this
+ * domain-specific classification.
+ *
+ * @see {@link tools/gates.mjs} - Consumer of risk detection
+ * @see {@link tools/lib/file-classifiers.mjs} - File classification utilities
+ */
+/**
+ * Risk tier constants
+ * @readonly
+ * @enum {string}
+ */
+export declare const RISK_TIERS: Readonly<{
+    /** Documentation-only changes - skip tests, run lint/typecheck only */
+    DOCS_ONLY: "docs-only";
+    /** Standard code changes - run incremental tests */
+    STANDARD: "standard";
+    /** Safety-critical tests need to run - always include safety test patterns */
+    SAFETY_CRITICAL: "safety-critical";
+    /** High-risk changes (auth, PHI, RLS, migrations) - run integration tests */
+    HIGH_RISK: "high-risk";
+}>;
+/**
+ * Test patterns that should ALWAYS run regardless of which files changed.
+ * These are safety-critical tests that verify red-flag detection, PHI protection,
+ * escalation triggers, and constitutional enforcement.
+ *
+ * @type {string[]}
+ */
+export declare const SAFETY_CRITICAL_TEST_PATTERNS: readonly string[];
+/**
+ * Path patterns that indicate high-risk code changes.
+ * Changes to these paths should trigger integration tests.
+ *
+ * WU-2242: Added authentication/ pattern
+ *
+ * @type {string[]}
+ */
+export declare const HIGH_RISK_PATH_PATTERNS: readonly string[];
+/**
+ * Check if a test file path matches safety-critical patterns.
+ *
+ * @param {string} testPath - Path to test file
+ * @returns {boolean} True if test is safety-critical
+ */
+export declare function isSafetyCriticalTest(testPath: any): boolean;
+/**
+ * Check if a migration file contains RLS or policy changes.
+ *
+ * @param {string} filePath - Migration file path
+ * @returns {boolean} True if migration is high-risk
+ */
+export declare function isHighRiskMigration(filePath: any): boolean;
+/**
+ * Check if a file path represents a high-risk code change.
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if path is high-risk
+ */
+export declare function isHighRiskPath(filePath: any): boolean;
+/**
+ * Detect the risk tier for a set of changed files.
+ *
+ * Returns a result object containing:
+ * - tier: The detected risk tier
+ * - safetyCriticalPatterns: Patterns to filter safety-critical tests
+ * - highRiskPaths: List of high-risk paths found in changes
+ * - isDocsOnly: Whether this is a docs-only change
+ * - shouldRunIntegration: Whether integration tests should run
+ *
+ * @param {object} options - Detection options
+ * @param {string[]} [options.changedFiles=[]] - List of changed file paths
+ * @returns {object} Risk detection result
+ *
+ * @example
+ * const result = detectRiskTier({ changedFiles: ['src/lib/auth/getUser.ts'] });
+ * // result.tier === 'high-risk'
+ * // result.shouldRunIntegration === true
+ *
+ * @example
+ * const result = detectRiskTier({ changedFiles: ['docs/guide.md'] });
+ * // result.tier === 'docs-only'
+ * // result.isDocsOnly === true
+ */
+export interface DetectRiskTierOptions {
+    /** Array of changed file paths to analyze */
+    changedFiles?: string[];
+}
+export declare function detectRiskTier(options?: DetectRiskTierOptions): {
+    tier: any;
+    safetyCriticalPatterns: string[];
+    highRiskPaths: any;
+    isDocsOnly: any;
+    shouldRunIntegration: boolean;
+};

package/dist/risk-detector.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * Risk Detector
+ *
+ * WU-2062: Implement tiered test execution for faster wu:done
+ *
+ * Detects risk tier based on changed files to enable tiered test execution:
+ * - docs-only: Skip tests, run lint/typecheck only
+ * - standard: Run changed tests
+ * - high-risk: Run integration tests in addition to unit tests
+ *
+ * Safety-critical tests (red-flag, PHI, escalation) always run regardless of tier.
+ *
+ * Note: This is project-specific risk detection logic for PatientPath's
+ * healthcare domain (PHI, RLS, auth). No standard library exists for this
+ * domain-specific classification.
+ *
+ * @see {@link tools/gates.mjs} - Consumer of risk detection
+ * @see {@link tools/lib/file-classifiers.mjs} - File classification utilities
+ */
+import path from 'node:path';
+import { isDocumentationPath } from './file-classifiers.js';
+/**
+ * Risk tier constants
+ * @readonly
+ * @enum {string}
+ */
+export const RISK_TIERS = Object.freeze({
+    /** Documentation-only changes - skip tests, run lint/typecheck only */
+    DOCS_ONLY: 'docs-only',
+    /** Standard code changes - run incremental tests */
+    STANDARD: 'standard',
+    /** Safety-critical tests need to run - always include safety test patterns */
+    SAFETY_CRITICAL: 'safety-critical',
+    /** High-risk changes (auth, PHI, RLS, migrations) - run integration tests */
+    HIGH_RISK: 'high-risk',
+});
+/**
+ * Test patterns that should ALWAYS run regardless of which files changed.
+ * These are safety-critical tests that verify red-flag detection, PHI protection,
+ * escalation triggers, and constitutional enforcement.
+ *
+ * @type {string[]}
+ */
+export const SAFETY_CRITICAL_TEST_PATTERNS = Object.freeze([
+    // Red-flag detection tests
+    'red-flag',
+    'redflag',
+    'RedFlag',
+    // PHI protection tests
+    'phi',
+    'PHI',
+    'PHIGuard',
+    // Escalation trigger tests
+    'escalation',
+    'Escalation',
+    // Privacy detection tests
+    'privacy',
+    'Privacy',
+    'privacyDetector',
+    // Constitutional enforcement tests
+    'constitutional',
+    'Constitutional',
+    // Safe prompt wrapper tests
+    'safePrompt',
+    'SafePrompt',
+    // Crisis/emergency handling tests
+    'crisis',
+    'Crisis',
+    // Policy enforcement tests
+    'policyReferee',
+    'PolicyReferee',
+]);
+/**
+ * Path patterns that indicate high-risk code changes.
+ * Changes to these paths should trigger integration tests.
+ *
+ * WU-2242: Added authentication/ pattern
+ *
+ * @type {string[]}
+ */
+// constants: HIGH_RISK_PATH_PATTERNS (skip hardcoded string detection)
+export const HIGH_RISK_PATH_PATTERNS = Object.freeze([
+    // Authentication (WU-2242: include both auth/ and authentication/)
+    '/auth/', // constants
+    '/auth.', // constants
+    '/authentication/', // constants
+    '/authentication.', // constants
+    // PHI (Protected Health Information)
+    '/phi/',
+    '/phi.',
+    // Row Level Security
+    '/rls/',
+    '/rls.',
+    'rls.sql',
+    // Security policies
+    '/policy/',
+    '/policy.',
+    // Supabase configuration
+    'supabase/config',
+    // API routes (potential attack surface)
+    '/api/',
+]);
+/**
+ * Supabase migrations directory (relative to repo root).
+ * @type {string}
+ */
+const SUPABASE_MIGRATIONS_DIR = 'supabase/supabase/migrations/';
+/**
+ * Filename patterns that indicate RLS or policy changes in migrations.
+ * @type {RegExp[]}
+ */
+const RLS_MIGRATION_PATTERNS = Object.freeze([
+    /policy/i,
+    /rls/i,
+    /row[_-]?level[_-]?security/i,
+    /enable[_-]?rls/i,
+]);
+/**
+ * Check if a test file path matches safety-critical patterns.
+ *
+ * @param {string} testPath - Path to test file
+ * @returns {boolean} True if test is safety-critical
+ */
+export function isSafetyCriticalTest(testPath) {
+    if (!testPath || typeof testPath !== 'string') {
+        return false;
+    }
+    // Normalise Windows paths
+    const normalized = testPath.replace(/\\/g, '/');
+    // Check if any safety-critical pattern matches
+    for (const pattern of SAFETY_CRITICAL_TEST_PATTERNS) {
+        if (normalized.includes(pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check whether a path refers to a Supabase migration file.
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is a migration SQL
+ */
+function isMigrationPath(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    const normalized = filePath.replace(/\\/g, '/');
+    return normalized.includes(SUPABASE_MIGRATIONS_DIR) && normalized.endsWith('.sql');
+}
+/**
+ * Check if a migration file contains RLS or policy changes.
+ *
+ * @param {string} filePath - Migration file path
+ * @returns {boolean} True if migration is high-risk
+ */
+export function isHighRiskMigration(filePath) {
+    if (!isMigrationPath(filePath)) {
+        return false;
+    }
+    const normalized = filePath.replace(/\\/g, '/');
+    const filename = path.basename(normalized);
+    return RLS_MIGRATION_PATTERNS.some((pattern) => pattern.test(filename));
+}
+/**
+ * Check if a file path represents a high-risk code change.
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if path is high-risk
+ */
+export function isHighRiskPath(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    if (isMigrationPath(filePath)) {
+        return false;
+    }
+    // Normalise Windows paths
+    const normalized = filePath.replace(/\\/g, '/');
+    // Check if any high-risk pattern matches
+    for (const pattern of HIGH_RISK_PATH_PATTERNS) {
+        if (normalized.includes(pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if all changed files are documentation-only.
+ *
+ * @param {string[]} changedFiles - List of changed file paths
+ * @returns {boolean} True if all files are documentation
+ */
+function areAllDocsOnly(changedFiles) {
+    if (!changedFiles || changedFiles.length === 0) {
+        return true;
+    }
+    return changedFiles.every((file) => {
+        // Normalise Windows paths
+        const normalized = file.replace(/\\/g, '/');
+        return isDocumentationPath(normalized);
+    });
+}
+/**
+ * Find high-risk paths in changed files.
+ *
+ * @param {string[]} changedFiles - List of changed file paths
+ * @returns {string[]} List of high-risk paths found
+ */
+function findHighRiskPaths(changedFiles) {
+    if (!changedFiles || changedFiles.length === 0) {
+        return [];
+    }
+    return changedFiles.filter((file) => {
+        // Normalise Windows paths
+        const normalized = file.replace(/\\/g, '/');
+        if (isMigrationPath(normalized)) {
+            return isHighRiskMigration(normalized);
+        }
+        return isHighRiskPath(normalized);
+    });
+}
+export function detectRiskTier(options = {}) {
+    const { changedFiles = [] } = options;
+    // Normalise all paths
+    const normalizedFiles = changedFiles.map((f) => (f ? f.replace(/\\/g, '/') : ''));
+    // Check if all files are documentation-only
+    const isDocsOnly = areAllDocsOnly(normalizedFiles);
+    // Find any high-risk paths
+    const highRiskPaths = findHighRiskPaths(normalizedFiles);
+    // Determine tier
+    let tier;
+    if (isDocsOnly) {
+        tier = RISK_TIERS.DOCS_ONLY;
+    }
+    else if (highRiskPaths.length > 0) {
+        tier = RISK_TIERS.HIGH_RISK;
+    }
+    else {
+        tier = RISK_TIERS.STANDARD;
+    }
+    // Safety-critical patterns always apply (for test filtering)
+    const safetyCriticalPatterns = [...SAFETY_CRITICAL_TEST_PATTERNS];
+    return {
+        tier,
+        safetyCriticalPatterns,
+        highRiskPaths,
+        isDocsOnly,
+        shouldRunIntegration: tier === RISK_TIERS.HIGH_RISK,
+    };
+}