@opensip-tools/fitness 1.0.4

package/src/recipes/check-result-processor.ts

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview Check result processor for fitness recipe execution
+ *
+ * Processes individual check results (success or error), updates session state,
+ * builds check summaries, and determines whether execution should stop.
+ */
+
+import { logger , SystemError } from '@opensip-tools/core'
+
+import { memoryProfiler, type CheckMemoryProfile } from '../framework/memory-profiler.js'
+import { countErrors, countWarnings } from '../types/severity.js'
+
+import type { CheckSummary, FitnessRecipeServiceCallbacks, FitnessRecipeSession } from './service-types.js'
+import type { FitnessRecipe, RecipeCheckResult } from './types.js'
+import type { CheckResult } from '../types/findings.js'
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Input data for processing a successful check result */
+export interface ProcessSuccessInput {
+  checkId: string
+  checkSlug: string
+  tags: readonly string[]
+  checkIndex: number
+  totalChecks: number
+  result: CheckResult
+  durationMs: number
+  memoryBeforeMB: number
+}
+
+/** Input data for processing a failed or timed-out check result */
+export interface ProcessErrorInput {
+  checkId: string
+  checkSlug: string
+  checkIndex: number
+  totalChecks: number
+  error: unknown
+  durationMs: number
+  memoryBeforeMB: number
+  timedOut: boolean
+  timeoutMs?: number
+}
+
+/** Context required by the result processor (session, callbacks, recipe) */
+export interface ProcessorContext {
+  session: FitnessRecipeSession
+  callbacks: FitnessRecipeServiceCallbacks
+  recipe: FitnessRecipe
+  includeViolations: boolean
+}
+
+/** Output from processing a check result, including whether execution should stop */
+export interface ProcessResultOutput {
+  checkResult: RecipeCheckResult
+  memoryProfile: CheckMemoryProfile
+  shouldStop: boolean
+}
+
+// =============================================================================
+// CHECK SUMMARY BUILDERS
+// =============================================================================
+
+/** Build a CheckSummary from a successful check execution */
+function createCheckSummary(
+  checkId: string,
+  checkSlug: string,
+  passed: boolean,
+  errorCount: number,
+  warningCount: number,
+  durationMs: number,
+  memoryProfile: CheckMemoryProfile,
+  ignoredCount = 0,
+  filesScanned = 0,
+): CheckSummary {
+  return {
+    checkId,
+    checkSlug,
+    passed,
+    errors: errorCount,
+    warnings: warningCount,
+    durationMs,
+    filesScanned,
+    ignoredCount,
+    memoryProfile,
+  }
+}
+
+/** Build a CheckSummary from a failed or errored check execution */
+function createErrorSummary(
+  checkId: string,
+  checkSlug: string,
+  durationMs: number,
+  memoryProfile: CheckMemoryProfile,
+  timedOut: boolean,
+  errorMessage: string,
+): CheckSummary {
+  return {
+    checkId,
+    checkSlug,
+    passed: false,
+    errors: 1,
+    warnings: 0,
+    durationMs,
+    filesScanned: 0,
+    ignoredCount: 0,
+    memoryProfile,
+    timedOut,
+    errorMessage,
+  }
+}
+
+// =============================================================================
+// SESSION UPDATES
+// =============================================================================
+
+function updateSessionForSuccess(
+  session: FitnessRecipeSession,
+  checkResult: RecipeCheckResult,
+  tags: readonly string[],
+): void {
+  session.checkResults.push(checkResult)
+  session.completedChecks++
+
+  if (checkResult.passed) {
+    session.passedChecks++
+  } else {
+    session.failedChecks++
+  }
+
+  session.totalErrors += checkResult.errorCount
+  session.totalWarnings += checkResult.warningCount
+  session.totalIgnored += checkResult.ignoredCount
+  for (const tag of tags) {
+    session.ignoresByTag.set(tag, (session.ignoresByTag.get(tag) ?? 0) + checkResult.ignoredCount)
+  }
+}
+
+function updateSessionForError(session: FitnessRecipeSession, checkResult: RecipeCheckResult): void {
+  session.checkResults.push(checkResult)
+  session.completedChecks++
+  session.failedChecks++
+  session.totalErrors++
+}
+
+// =============================================================================
+// MAIN PROCESSORS
+// =============================================================================
+
+/** Process a successful check result: update session, invoke callbacks, and determine stop condition */
+export function processSuccessResult(
+  ctx: ProcessorContext,
+  input: ProcessSuccessInput,
+): ProcessResultOutput {
+  const { checkId, checkSlug, tags, checkIndex, totalChecks, result, durationMs, memoryBeforeMB } =
+    input
+  const { session, callbacks, recipe } = ctx
+
+  // Apply file filter if set
+  let effectiveSignals = result.signals
+  if (recipe.fileFilter) {
+    effectiveSignals = result.signals.filter(
+      (s) => s.code?.file === recipe.fileFilter,
+    )
+  }
+  const signalCount = effectiveSignals.length
+  const errorCount = recipe.fileFilter
+    ? countErrors(effectiveSignals)
+    : result.errors
+  const warningCount = recipe.fileFilter
+    ? countWarnings(effectiveSignals)
+    : result.warnings
+  const ignoredCount = result.ignoredCount ?? 0
+  const passed = recipe.fileFilter ? errorCount === 0 : result.passed
+
+  const memoryProfile = memoryProfiler.recordCheckComplete(checkId, memoryBeforeMB, signalCount, durationMs)
+
+  if (memoryProfiler.exceedsThreshold(memoryProfile.memoryDeltaMB)) {
+    logger.warn('Check exceeded memory threshold', { evt: 'fitness.check.memory.exceeded', module: 'fitness:recipes', checkId, checkSlug, memoryDeltaMB: memoryProfile.memoryDeltaMB })
+    callbacks.onMemoryWarning?.(checkId, memoryProfile)
+  }
+
+  const checkResult: RecipeCheckResult = {
+    checkId,
+    checkSlug,
+    passed,
+    violationCount: signalCount,
+    errorCount,
+    warningCount,
+    ignoredCount,
+    durationMs,
+    totalItems: result.metadata.totalItems,
+    itemType: result.metadata.itemType,
+    skipped: false,
+    ...(result.appliedDirectives && result.appliedDirectives.length > 0
+      ? { appliedDirectives: result.appliedDirectives }
+      : {}),
+    ...(ctx.includeViolations ? {
+      violations: effectiveSignals.map((s) => ({
+        file: s.code?.file ?? 'unknown',
+        line: s.code?.line ?? 0,
+        column: s.code?.column,
+        message: s.message,
+        severity: s.severity === 'high' ? 'error' as const : 'warning' as const,
+        suggestion: s.suggestion,
+      })),
+    } : {}),
+  }
+
+  updateSessionForSuccess(session, checkResult, tags)
+
+  const summary = createCheckSummary(checkId, checkSlug, passed, errorCount, warningCount, durationMs, memoryProfile, ignoredCount, result.metadata.filesScanned ?? 0)
+  callbacks.onCheckComplete?.(checkSlug, summary, checkIndex, totalChecks)
+
+  const shouldStop = recipe.execution.stopOnFirstFailure && !passed
+
+  return { checkResult, memoryProfile, shouldStop }
+}
+
+/** Process a failed check result: update session, invoke callbacks, and determine stop condition */
+export function processErrorResult(ctx: ProcessorContext, input: ProcessErrorInput): ProcessResultOutput {
+  const { checkId, checkSlug, checkIndex, totalChecks, error, durationMs, memoryBeforeMB, timedOut, timeoutMs } = input
+  const { session, callbacks, recipe } = ctx
+
+  let errMsg: string
+  if (timedOut && timeoutMs) {
+    errMsg = `Check ${checkSlug} timed out after ${timeoutMs}ms`
+  } else {
+    errMsg = error instanceof Error ? error.message : String(error)
+  }
+
+  const memoryProfile = memoryProfiler.recordCheckComplete(checkId, memoryBeforeMB, 0, durationMs)
+
+  const checkResult: RecipeCheckResult = {
+    checkId,
+    checkSlug,
+    passed: false,
+    violationCount: 0,
+    errorCount: 1,
+    warningCount: 0,
+    ignoredCount: 0,
+    durationMs,
+    skipped: false,
+    error: errMsg,
+    timedOut,
+  }
+
+  updateSessionForError(session, checkResult)
+
+  const summary = createErrorSummary(checkId, checkSlug, durationMs, memoryProfile, timedOut, errMsg)
+  callbacks.onError?.(checkSlug, error instanceof Error ? error : new SystemError(errMsg, { code: 'SYSTEM.FITNESS.CHECK_ERROR' }))
+  callbacks.onCheckComplete?.(checkSlug, summary, checkIndex, totalChecks)
+
+  const shouldStop = recipe.execution.stopOnFirstFailure
+
+  return { checkResult, memoryProfile, shouldStop }
+}

package/src/recipes/parallel-execution.ts

@@ -0,0 +1,220 @@
+/**
+ * @fileoverview Parallel execution engine for fitness recipe checks
+ *
+ * Runs fitness checks concurrently with configurable parallelism,
+ * per-check timeouts, abort support, and retry logic.
+ */
+
+import { TimeoutError , logger } 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 { getEffectiveMaxParallel } from './types.js'
+
+import type { FitnessRecipeServiceCallbacks, FitnessRecipeSession } from './service-types.js'
+import type { FitnessRecipe } from './types.js'
+import type { Check } from '../framework/check-types.js'
+import type { CheckResult } from '../types/findings.js'
+
+/** Logger module tag used by every event emitted from the parallel execution engine. */
+const MODULE_TAG = 'fitness:execution'
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Options for executing a set of fitness checks */
+export interface ExecutionOptions {
+  checks: Check[]
+  cwd: string
+  recipe: FitnessRecipe
+  /** Per-check pre-resolved file paths from target overrides */
+  checkTargetFiles?: ReadonlyMap<string, readonly string[]>
+  /**
+   * Run-wide globalExcludes from project config. Forwarded into each
+   * check's RunOptions so scope-empty checks honor exclusions instead
+   * of scanning every file in the prewarmed cache.
+   */
+  globalExcludes?: readonly string[]
+}
+
+/** Service context providing session state, callbacks, and abort control */
+export interface ExecutionServiceContext {
+  session: FitnessRecipeSession
+  callbacks: FitnessRecipeServiceCallbacks
+  abortController?: AbortController
+  includeViolations?: boolean
+}
+
+// =============================================================================
+// PARALLEL EXECUTION
+// =============================================================================
+
+/** Execute fitness checks concurrently with configurable parallelism and per-check timeouts */
+export async function executeParallel(ctx: ExecutionServiceContext, opts: ExecutionOptions): Promise<void> {
+  // in-memory: single-threaded Node.js access pattern
+  const { checks, cwd, recipe, checkTargetFiles, globalExcludes } = opts
+  const { session, callbacks, abortController } = ctx
+  const recipeTimeout = recipe.execution.timeout ?? 30_000
+  const maxParallel = getEffectiveMaxParallel(recipe)
+  const totalChecks = checks.length
+
+  const memoryBeforeMap = new Map<string, number>()
+  let nextCheckIndex = 0
+  let activeCount = 0
+  let shouldStopExecution = false
+
+  const processorCtx: ProcessorContext = { session, callbacks, recipe, includeViolations: ctx.includeViolations ?? false }
+
+  // @fitness-ignore-next-line concurrency-safety -- async arrow provides Promise<void> return type for consistency; single-threaded Node.js access pattern
+  /* eslint-disable @typescript-eslint/require-await -- callers `await` this; preserving async signature in case future processors become async */
+  const processCheckResult = async (
+    checkIndex: number,
+    checkId: string,
+    checkSlug: string,
+    checkTags: readonly string[],
+    result: CheckResult,
+    durationMs: number,
+  ): Promise<void> => {
+    // in-memory: single-threaded Node.js access pattern
+    const memoryBeforeMB = memoryBeforeMap.get(checkId) ?? 0
+    const output = processSuccessResult(processorCtx, {
+      checkId,
+      checkSlug,
+      tags: checkTags,
+      checkIndex,
+      totalChecks,
+      result,
+      durationMs,
+      memoryBeforeMB,
+    })
+    if (output.shouldStop) shouldStopExecution = true
+  }
+  /* eslint-enable @typescript-eslint/require-await */
+
+  const processCheckError = (
+    checkIndex: number,
+    checkId: string,
+    checkSlug: string,
+    error: unknown,
+    durationMs: number,
+    timedOut = false,
+    timeoutMs?: number,
+  ): void => {
+    const memoryBeforeMB = memoryBeforeMap.get(checkId) ?? 0
+    const errorInput = {
+      checkId,
+      checkSlug,
+      checkIndex,
+      totalChecks,
+      error,
+      durationMs,
+      memoryBeforeMB,
+      timedOut,
+      ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    }
+    const output = processErrorResult(processorCtx, errorInput)
+    if (output.shouldStop) shouldStopExecution = true
+  }
+
+  await new Promise<void>((resolve) => {
+    const advanceWindow = () => {
+      activeCount--
+
+      if (!shouldStopExecution && nextCheckIndex < checks.length && !abortController?.signal.aborted) {
+        const nextCheck = checks[nextCheckIndex]
+        if (nextCheck) {
+          nextCheckIndex++
+          startCheck(nextCheck, nextCheckIndex)
+        }
+      }
+
+      if (activeCount === 0 && (nextCheckIndex >= checks.length || shouldStopExecution)) {
+        resolve()
+      }
+    }
+
+    // @fitness-ignore-next-line file-length-limits -- Parallel check launcher: orchestrates timeout, retry, result processing, and window advancement in a single cohesive unit
+    const startCheck = (check: Check, displayIndex: number) => {
+      // in-memory: single-threaded Node.js access pattern
+      const checkId = check.config.id
+      activeCount++
+
+      const checkTimeout = check.config.timeout ?? recipeTimeout
+      memoryBeforeMap.set(checkId, memoryProfiler.recordCheckStart())
+      callbacks.onCheckStart?.(check.config.slug, displayIndex, totalChecks)
+      logger.info({ evt: 'fitness.check.start', module: MODULE_TAG, checkSlug: check.config.slug, index: displayIndex, total: totalChecks, timeoutMs: checkTimeout })
+
+      const startTime = Date.now()
+      const checkAbortController = new AbortController()
+      const timeoutId = setTimeout(() => checkAbortController.abort(), checkTimeout)
+
+      const targetFiles = checkTargetFiles?.get(check.config.slug)
+      void executeWithRetry(() => check.run(cwd, {
+        signal: checkAbortController.signal,
+        ...(targetFiles ? { targetFiles } : {}),
+        ...(globalExcludes ? { globalExcludes } : {}),
+      }), {
+        enabled: recipe.execution.retryOnFailure ?? false,
+        maxRetries: recipe.execution.maxRetries ?? 2,
+        checkId,
+        checkSlug: check.config.slug,
+      })
+        .then(async (retryResult) => {
+          const durationMs = Date.now() - startTime
+
+          if (retryResult.result === undefined) {
+            clearTimeout(timeoutId)
+            const isTimeout = checkAbortController.signal.aborted
+            logger.info({ evt: 'fitness.check.error', module: MODULE_TAG, checkSlug: check.config.slug, durationMs, timedOut: isTimeout, error: retryResult.lastError instanceof Error ? retryResult.lastError.message : String(retryResult.lastError) })
+            void processCheckError(
+              displayIndex,
+              checkId,
+              check.config.slug,
+              retryResult.lastError,
+              durationMs,
+              isTimeout,
+              isTimeout ? checkTimeout : undefined,
+            )
+          } else if (checkAbortController.signal.aborted) {
+            clearTimeout(timeoutId)
+            logger.info({ evt: 'fitness.check.timeout', module: MODULE_TAG, checkSlug: check.config.slug, durationMs, timeoutMs: checkTimeout })
+            void processCheckError(
+              displayIndex,
+              checkId,
+              check.config.slug,
+              new TimeoutError(`Check ${checkId} timed out after ${checkTimeout}ms`, checkTimeout),
+              durationMs,
+              true,
+              checkTimeout,
+            )
+          } else {
+            clearTimeout(timeoutId)
+            logger.info({ evt: 'fitness.check.done', module: MODULE_TAG, checkSlug: check.config.slug, durationMs, signals: retryResult.result.signals.length })
+            await processCheckResult(displayIndex, checkId, check.config.slug, check.config.tags ?? [], retryResult.result, durationMs)
+          }
+        })
+        .catch((error: unknown) => {
+          clearTimeout(timeoutId)
+          const durationMs = Date.now() - startTime
+          logger.info({ evt: 'fitness.check.error', module: MODULE_TAG, checkSlug: check.config.slug, durationMs, error: error instanceof Error ? error.message : String(error) })
+          void processCheckError(displayIndex, checkId, check.config.slug, error, durationMs)
+        })
+        .finally(() => advanceWindow())
+    }
+
+    const initialBatchSize = Math.min(maxParallel, checks.length)
+    for (let i = 0; i < initialBatchSize; i++) {
+      const check = checks[i]
+      if (check) {
+        nextCheckIndex = i + 1
+        startCheck(check, i + 1)
+      }
+    }
+
+    if (checks.length === 0) resolve()
+  })
+}

package/src/recipes/registry.ts

@@ -0,0 +1,192 @@
+// @fitness-ignore-file batch-operation-limits -- iterates bounded collections (config entries, registry items, or small analysis results)
+// @fitness-ignore-file no-console-log -- User recipe warnings/summary output before CLI framework is initialized
+// @fitness-ignore-file logging-standards -- User recipe warnings/summary output before structured logger is available
+/**
+ * @fileoverview Fitness recipe registry
+ *
+ * Manages registration and lookup of fitness recipes (built-in and user-defined).
+ */
+
+import { ValidationError } from '@opensip-tools/core'
+
+import { builtInRecipes, isBuiltInRecipe } from './built-in-recipes.js'
+
+import type { FitnessRecipe } from './types.js'
+
+/** Stub for user recipe loading (not ported to opensip-tools) */
+interface UserFitnessRecipesResult {
+  recipes: FitnessRecipe[]
+  warnings: string[]
+  loadedFrom?: string
+}
+
+/** Options for constructing a FitnessRecipeRegistry */
+export interface FitnessRecipeRegistryOptions {
+  readonly basePath?: string
+  readonly loadUserRecipes?: boolean
+  readonly logWarnings?: boolean
+  readonly logSummary?: boolean
+}
+
+/** Display-friendly info about a registered recipe */
+export interface RecipeDisplayInfo {
+  readonly name: string
+  readonly displayName: string
+  readonly description: string
+  readonly tags: readonly string[]
+  readonly isBuiltIn: boolean
+  readonly isUserDefined: boolean
+  readonly overridesBuiltIn: boolean
+}
+
+/** Registry for fitness recipes, loading built-in and user-defined recipes */
+export class FitnessRecipeRegistry {
+  private readonly byId = new Map<string, FitnessRecipe>()
+  private readonly byName = new Map<string, FitnessRecipe>()
+  private _userRecipesLoadResult: UserFitnessRecipesResult | undefined
+  private readonly _overriddenBuiltIns = new Set<string>()
+
+  constructor(options: FitnessRecipeRegistryOptions = {}) {
+    const {
+      basePath,
+      loadUserRecipes: shouldLoadUserRecipes = true,
+      logWarnings = true,
+      logSummary = false,
+    } = options
+
+    this.registerBuiltInRecipes()
+
+    if (shouldLoadUserRecipes) {
+      this.loadAndRegisterUserRecipes(basePath, logWarnings, logSummary)
+    }
+  }
+
+  private registerBuiltInRecipes(): void {
+    for (const recipe of builtInRecipes) {
+      this.byId.set(recipe.id, recipe)
+      this.byName.set(recipe.name, recipe)
+    }
+  }
+
+  private loadAndRegisterUserRecipes(
+    _basePath: string | undefined,
+    _logWarnings: boolean,
+    _logSummary: boolean,
+  ): void {
+    // User recipe loading not ported to opensip-tools — stub
+    this._userRecipesLoadResult = { recipes: [], warnings: [] }
+  }
+
+  /** Return the result of loading user-defined recipes, if attempted */
+  getUserRecipesLoadResult(): UserFitnessRecipesResult | undefined {
+    return this._userRecipesLoadResult
+  }
+
+  /** Check whether a built-in recipe has been overridden by a user recipe */
+  isOverridden(name: string): boolean {
+    return this._overriddenBuiltIns.has(name)
+  }
+
+  /** Return the names of all built-in recipes overridden by user recipes */
+  getOverriddenBuiltIns(): readonly string[] {
+    return [...this._overriddenBuiltIns]
+  }
+
+  /** Look up a recipe by name or ID */
+  loadRecipe(nameOrId: string): FitnessRecipe | undefined {
+    return this.byName.get(nameOrId) ?? this.byId.get(nameOrId)
+  }
+
+  /** Retrieve a recipe by its name */
+  getByName(name: string): FitnessRecipe | undefined {
+    return this.byName.get(name)
+  }
+
+  /** Retrieve a recipe by its ID */
+  getById(id: string): FitnessRecipe | undefined {
+    return this.byId.get(id)
+  }
+
+  /** Check whether a recipe exists by name or ID */
+  has(nameOrId: string): boolean {
+    return this.byName.has(nameOrId) || this.byId.has(nameOrId)
+  }
+
+  /** Return all registered recipes */
+  getAllRecipes(): readonly FitnessRecipe[] {
+    return [...this.byId.values()]
+  }
+
+  /** Return all registered recipe names */
+  getNames(): readonly string[] {
+    return [...this.byName.keys()]
+  }
+
+  /** Return all recipes matching a given tag */
+  getByTag(tag: string): readonly FitnessRecipe[] {
+    return [...this.byId.values()].filter((r) => r.tags?.includes(tag))
+  }
+
+  /** Number of registered recipes */
+  get size(): number {
+    return this.byId.size
+  }
+
+  /** Register a recipe. Throws if already registered unless allowOverwrite is true. */
+  register(recipe: FitnessRecipe, options?: { allowOverwrite?: boolean }): void {
+    const allowOverwrite = options?.allowOverwrite ?? false
+    if (!allowOverwrite && (this.byId.has(recipe.id) || this.byName.has(recipe.name))) {
+      // @fitness-ignore-next-line result-pattern-consistency -- internal registration guard, throw is appropriate
+      throw new ValidationError(`Recipe '${recipe.name}' (${recipe.id}) already registered`, { code: 'VALIDATION.FITNESS.DUPLICATE_RECIPE' })
+    }
+    this.byId.set(recipe.id, recipe)
+    this.byName.set(recipe.name, recipe)
+  }
+
+  /** Register multiple recipes at once */
+  registerAll(recipes: readonly FitnessRecipe[], options?: { allowOverwrite?: boolean }): void {
+    for (const recipe of recipes) {
+      this.register(recipe, options)
+    }
+  }
+
+  /** Remove a recipe by ID. Returns true if the recipe was found and removed. */
+  remove(id: string): boolean {
+    const recipe = this.byId.get(id)
+    if (!recipe) return false
+    this.byId.delete(id)
+    this.byName.delete(recipe.name)
+    return true
+  }
+
+  /** Remove all registered recipes */
+  clear(): void {
+    this.byId.clear()
+    this.byName.clear()
+  }
+
+  /** Clear all recipes and re-register built-in recipes */
+  reset(): void {
+    this.clear()
+    this.registerBuiltInRecipes()
+  }
+
+  /** Return display-friendly info for all registered recipes */
+  listForDisplay(): readonly RecipeDisplayInfo[] {
+    return [...this.byId.values()].map((recipe) => {
+      const isUserRecipe = recipe.id.startsWith('URCP_')
+      return {
+        name: recipe.name,
+        displayName: recipe.displayName,
+        description: recipe.description,
+        tags: recipe.tags ?? [],
+        isBuiltIn: !isUserRecipe && isBuiltInRecipe(recipe.name),
+        isUserDefined: isUserRecipe,
+        overridesBuiltIn: this._overriddenBuiltIns.has(recipe.name),
+      }
+    })
+  }
+}
+
+/** Shared singleton recipe registry with built-in recipes pre-loaded */
+export const defaultRecipeRegistry = new FitnessRecipeRegistry({ logWarnings: false })