@opensip-tools/fitness 1.0.4

package/src/recipes/retry.ts

@@ -0,0 +1,69 @@
+// @fitness-ignore-file error-handling-suite -- catch blocks delegate errors through established patterns
+/**
+ * @fileoverview Retry logic for fitness check execution
+ *
+ * Provides exponential backoff retry wrapper for transient check failures.
+ */
+
+import { CheckAbortedError } from '../framework/execution-context.js'
+
+const BACKOFF_DELAYS_MS = [1000, 2000] as const
+
+/** Configuration for retry behavior */
+export interface RetryOptions {
+  readonly enabled: boolean
+  readonly maxRetries: number
+  readonly checkId: string
+  readonly checkSlug: string
+}
+
+/** Result of a retry-wrapped function execution */
+export interface RetryResult<T> {
+  readonly result: T | undefined
+  readonly lastError: unknown
+  readonly retryCount: number
+  readonly wasRetried: boolean
+}
+
+function backoff(attempt: number): Promise<void> {
+  const delay = BACKOFF_DELAYS_MS[attempt] ?? BACKOFF_DELAYS_MS.at(-1) ?? 2000
+  return new Promise((resolve) => setTimeout(resolve, delay))
+}
+
+/**
+ * Execute a function with retry logic.
+ * Only retries when the function throws. CheckAbortedError is never retried.
+ */
+export async function executeWithRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions,
+): Promise<RetryResult<T>> {
+  try {
+    const result = await fn()
+    return { result, lastError: undefined, retryCount: 0, wasRetried: false }
+  } catch (firstError) {
+    if (firstError instanceof CheckAbortedError) {
+      return { result: undefined, lastError: firstError, retryCount: 0, wasRetried: false }
+    }
+
+    if (!options.enabled || options.maxRetries <= 0) {
+      return { result: undefined, lastError: firstError, retryCount: 0, wasRetried: false }
+    }
+
+    let lastError: unknown = firstError
+
+    for (let attempt = 0; attempt < options.maxRetries; attempt++) {
+      // @fitness-ignore-next-line performance-anti-patterns -- sequential retry with backoff is inherently serial
+      await backoff(attempt)
+
+      try {
+        const result = await fn()
+        return { result, lastError: undefined, retryCount: attempt + 1, wasRetried: true }
+      } catch (retryError) {
+        lastError = retryError
+      }
+    }
+
+    return { result: undefined, lastError, retryCount: options.maxRetries, wasRetried: true }
+  }
+}

package/src/recipes/sequential-execution.ts

@@ -0,0 +1,139 @@
+/**
+ * @fileoverview Sequential execution engine for fitness recipe checks
+ *
+ * Runs fitness checks one at a time with per-check timeouts,
+ * abort support, and retry logic.
+ */
+
+import { TimeoutError } from '@opensip-tools/core'
+
+import { memoryProfiler } from '../framework/memory-profiler.js'
+
+import {
+  processSuccessResult,
+  processErrorResult,
+  type ProcessorContext,
+} from './check-result-processor.js'
+import { executeWithRetry } from './retry.js'
+
+import type { ExecutionOptions, ExecutionServiceContext } from './parallel-execution.js'
+
+// =============================================================================
+// SEQUENTIAL EXECUTION
+// =============================================================================
+
+/** Execute fitness checks sequentially with per-check timeouts and retry support */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- Inherent complexity: sequential check execution with per-check timeouts, abort signal handling, file matching, error recovery, and progress callbacks
+export async function executeSequential(ctx: ExecutionServiceContext, opts: ExecutionOptions): Promise<void> {
+  const { checks, cwd, recipe, checkTargetFiles, globalExcludes } = opts
+  const { session, callbacks, abortController } = ctx
+  const recipeTimeout = recipe.execution.timeout ?? 30_000
+  const totalChecks = checks.length
+
+  const processorCtx: ProcessorContext = { session, callbacks, recipe, includeViolations: ctx.includeViolations ?? false }
+
+  // @fitness-ignore-next-line file-length-limits -- Sequential check execution loop: orchestrates check lifecycle (start, run, retry, complete) callbacks
+  for (const [i, check] of checks.entries()) {
+    if (abortController?.signal.aborted) break
+
+    if (!check) continue
+
+    const checkId = check.config.id
+    const checkSlug = check.config.slug
+    const timeout = check.config.timeout ?? recipeTimeout
+
+    void callbacks.onCheckStart?.(checkSlug, i + 1, totalChecks)
+
+    const checkAbortController = new AbortController()
+    const memoryBeforeMB = memoryProfiler.recordCheckStart()
+    const startTime = Date.now()
+    let timedOut = false
+
+    const timeoutId = setTimeout(() => {
+      timedOut = true
+      checkAbortController.abort()
+    }, timeout)
+
+    try {
+      const retryResult = await executeWithRetry(
+        () => {
+          const targetFiles = checkTargetFiles?.get(check.config.slug)
+          return check.run(cwd, {
+            signal: checkAbortController.signal,
+            ...(targetFiles ? { targetFiles } : {}),
+            ...(globalExcludes ? { globalExcludes } : {}),
+          })
+        },
+        {
+          enabled: recipe.execution.retryOnFailure ?? false,
+          maxRetries: recipe.execution.maxRetries ?? 2,
+          checkId,
+          checkSlug,
+        },
+      )
+      clearTimeout(timeoutId)
+
+      if (checkAbortController.signal.aborted) {
+        const durationMs = Date.now() - startTime
+        const output = processErrorResult(processorCtx, {
+          checkId,
+          checkSlug,
+          checkIndex: i + 1,
+          totalChecks,
+          error: new TimeoutError(`Check ${checkId} timed out after ${timeout}ms`, timeout),
+          durationMs,
+          memoryBeforeMB,
+          timedOut: true,
+          timeoutMs: timeout,
+        })
+        if (output.shouldStop) break
+        continue
+      }
+
+      if (retryResult.result === undefined) {
+        const durationMs = Date.now() - startTime
+        const output = processErrorResult(processorCtx, {
+          checkId,
+          checkSlug,
+          checkIndex: i + 1,
+          totalChecks,
+          error: retryResult.lastError,
+          durationMs,
+          memoryBeforeMB,
+          timedOut: false,
+        })
+        if (output.shouldStop) break
+        continue
+      }
+
+      const durationMs = Date.now() - startTime
+      const output = processSuccessResult(processorCtx, {
+        checkId,
+        checkSlug,
+        tags: check.config.tags ?? [],
+        checkIndex: i + 1,
+        totalChecks,
+        result: retryResult.result,
+        durationMs,
+        memoryBeforeMB,
+      })
+      if (output.shouldStop) break
+    } catch (error) {
+      clearTimeout(timeoutId)
+      const durationMs = Date.now() - startTime
+      const isTimeout = timedOut || checkAbortController.signal.aborted
+      const output = processErrorResult(processorCtx, {
+        checkId,
+        checkSlug,
+        checkIndex: i + 1,
+        totalChecks,
+        error,
+        durationMs,
+        memoryBeforeMB,
+        timedOut: isTimeout,
+        ...(isTimeout ? { timeoutMs: timeout } : {}),
+      })
+      if (output.shouldStop) break
+    }
+  }
+}

package/src/recipes/service-types.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Service-layer type definitions for fitness recipe execution
+ *
+ * Defines the configuration, session state, and callback types
+ * used by FitnessRecipeService and its execution engines.
+ */
+
+import type { FitnessRecipeRegistry } from './registry.js'
+import type {
+  FitnessRecipe,
+  FitnessRecipeResult,
+  RecipeCheckResult,
+  IgnoresByType,
+} from './types.js'
+import type { DirectiveEntry } from '../framework/directive-inventory.js'
+import type { CheckMemoryProfile } from '../framework/memory-profiler.js'
+import type { CheckRegistry } from '../framework/registry.js'
+
+
+// =============================================================================
+// CHECK SUMMARY (used for callbacks)
+// =============================================================================
+
+/** Summary of a single check execution for callback reporting */
+export interface CheckSummary {
+  readonly checkId: string
+  readonly checkSlug: string
+  readonly passed: boolean
+  readonly errors: number
+  readonly warnings: number
+  readonly durationMs: number
+  readonly filesScanned: number
+  readonly ignoredCount: number
+  readonly memoryProfile: CheckMemoryProfile
+  readonly timedOut?: boolean
+  readonly errorMessage?: string
+}
+
+// =============================================================================
+// SERVICE CALLBACKS
+// =============================================================================
+
+/** Callbacks invoked during recipe execution for progress and errors */
+export interface FitnessRecipeServiceCallbacks {
+  onCheckStart?: (checkSlug: string, index: number, total: number) => void
+  onCheckComplete?: (checkSlug: string, summary: CheckSummary, index: number, total: number) => void
+  onError?: (checkSlug: string, error: Error) => void
+  onMemoryWarning?: (checkId: string, profile: CheckMemoryProfile) => void
+  onComplete?: (result: FitnessRecipeResult) => void
+  /** Called before execution with all registered checks for catalog sync. */
+  onCatalogSync?: (entries: { id: string; slug: string; tags: readonly string[]; description: string }[]) => void
+}
+
+// =============================================================================
+// SERVICE CONFIGURATION
+// =============================================================================
+
+/** Configuration for the fitness recipe service */
+export interface FitnessRecipeServiceConfig {
+  cwd?: string
+  prewarmCache?: boolean
+  prewarmPatterns?: string[]
+  callbacks?: FitnessRecipeServiceCallbacks
+  /** Per-check pre-resolved file paths from target overrides. Map of check slug → absolute file paths. */
+  checkTargetFiles?: ReadonlyMap<string, readonly string[]>
+  /** Optional check registry (defaults to defaultRegistry). */
+  checkRegistry?: CheckRegistry
+  /** Optional recipe registry (defaults to defaultRecipeRegistry). */
+  recipeRegistry?: FitnessRecipeRegistry
+  /** Check slugs disabled via opensip.config.yml — these checks are skipped unless force-included by a recipe. */
+  disabledChecks?: readonly string[]
+  /** When true, carry violation details on RecipeCheckResult. */
+  includeViolations?: boolean
+  /**
+   * Run-wide file exclusion patterns from `opensip-tools.config.yml`'s
+   * top-level `globalExcludes`. Threaded into each check's RunOptions
+   * so the matchFiles() fallback honors them — without this, scope-empty
+   * checks scan every prewarmed file. Should be the same array passed
+   * to `loadTargetsConfig`.
+   */
+  globalExcludes?: readonly string[]
+}
+
+// =============================================================================
+// SESSION STATE
+// =============================================================================
+
+/** Mutable session state tracking progress during a recipe execution */
+export interface FitnessRecipeSession {
+  readonly sessionId: string
+  readonly recipe: FitnessRecipe
+  readonly startedAt: Date
+  status: 'running' | 'completed' | 'failed'
+  totalChecks: number
+  completedChecks: number
+  passedChecks: number
+  failedChecks: number
+  totalErrors: number
+  totalWarnings: number
+  totalIgnored: number
+  ignoresByTag: Map<string, number>
+  checkResults: RecipeCheckResult[]
+  ignoreCounts?: IgnoresByType | undefined
+  directives: DirectiveEntry[]
+}