@opensip-tools/fitness 1.0.4

package/src/framework/file-cache.ts

@@ -0,0 +1,220 @@
+// @fitness-ignore-file public-api-jsdoc -- internal framework module; public API documented at package level
+/**
+ * @fileoverview In-memory file cache for fitness checks
+ *
+ * Simple file content cache with optional prewarming.
+ * Used by all checks during a run for efficient file access.
+ */
+
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+
+import { ValidationError } from '@opensip-tools/core'
+import { glob } from 'glob'
+
+/**
+ * Prewarm statistics.
+ */
+interface PrewarmStats {
+  /** Number of files loaded */
+  readonly filesLoaded: number
+  /** Duration in milliseconds */
+  readonly durationMs: number
+  /** Total bytes loaded */
+  readonly totalBytes: number
+}
+
+/**
+ * Simple in-memory file cache.
+ *
+ * Usage:
+ * 1. Call prewarm() before running checks (loads file contents)
+ * 2. Use get() to read file contents (falls back to disk if not cached)
+ * 3. Call clear() after checks complete
+ */
+const PREWARM_BATCH_SIZE = 100
+
+class FileCache {
+  private readonly cache = new Map<string, string>()
+  private _prewarmed = false
+  private _cleared = false
+  private _autoClearTimer: ReturnType<typeof setTimeout> | null = null
+
+  /**
+   * Prewarm the cache by loading all files matching patterns.
+   * @param cwd - Working directory for file resolution
+   * @param patterns - Glob patterns to prewarm file contents for
+   * @returns Prewarm statistics
+   */
+  async prewarm(cwd: string, patterns: readonly string[]): Promise<PrewarmStats> {
+    const start = Date.now()
+    let totalBytes = 0
+
+    // Find all matching files for content caching
+    const allFiles = new Set<string>()
+    for (const pattern of patterns) {
+      // @fitness-ignore-next-line performance-anti-patterns -- sequential glob calls: each pattern must resolve before deduplication
+      const files = await glob(pattern, {
+        cwd,
+        absolute: true,
+        nodir: true,
+        ignore: ['**/node_modules/**', '**/dist/**', '**/.git/**'],
+      })
+      for (const file of files) {
+        allFiles.add(file)
+      }
+    }
+
+    // Load file contents in parallel batches
+    const files = [...allFiles]
+
+    for (let i = 0; i < files.length; i += PREWARM_BATCH_SIZE) {
+      const batch = files.slice(i, i + PREWARM_BATCH_SIZE)
+      // @fitness-ignore-next-line performance-anti-patterns -- intentional batching: limits concurrent file reads to control memory pressure
+      const results = await Promise.allSettled(
+        batch.map(async (filePath) => {
+          const stats = await fs.stat(filePath)
+          if (stats.isDirectory()) {
+            return null
+          }
+          const content = await fs.readFile(filePath, 'utf8')
+          return { filePath, content }
+        }),
+      )
+
+      for (const result of results) {
+        if (result.status === 'fulfilled' && result.value !== null) {
+          this.cache.set(result.value.filePath, result.value.content)
+          totalBytes += result.value.content.length
+        }
+      }
+    }
+
+    this._prewarmed = true
+    this._cleared = false
+    this.scheduleAutoClear()
+    const durationMs = Date.now() - start
+
+    return {
+      filesLoaded: this.cache.size,
+      durationMs,
+      totalBytes,
+    }
+  }
+
+  /**
+   * Get file content from cache, falling back to disk if not cached.
+   * @throws {Error} If the path is a directory instead of a file
+   */
+  /** Synchronously check if a file is in cache. Returns content or undefined. */
+  getCached(filePath: string): string | undefined {
+    const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(filePath)
+    return this.cache.get(absolutePath)
+  }
+
+  async get(filePath: string): Promise<string> {
+    const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(filePath)
+
+    const cached = this.cache.get(absolutePath)
+    if (cached !== undefined) {
+      return cached
+    }
+
+    const stats = await fs.stat(absolutePath)
+    if (stats.isDirectory()) {
+      // @fitness-ignore-next-line result-pattern-consistency -- internal method, exceptions propagate to public Result boundary
+      throw new ValidationError(`Cannot read directory as file: ${absolutePath}`, { code: 'VALIDATION.FITNESS.DIRECTORY_AS_FILE' })
+    }
+    const content = await fs.readFile(absolutePath, 'utf8')
+
+    this.cache.set(absolutePath, content)
+
+    return content
+  }
+
+  /**
+   * Check if a file exists (in cache or on disk).
+   */
+  async exists(filePath: string): Promise<boolean> {
+    const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(filePath)
+
+    if (this.cache.has(absolutePath)) {
+      return true
+    }
+
+    try {
+      await fs.access(absolutePath)
+      return true
+    } catch {
+      // @swallow-ok File access check failed — treat as not accessible
+      return false
+    }
+  }
+
+  /**
+   * Clear the cache. Must be called after checks complete.
+   */
+  clear(): void {
+    this.cache.clear()
+    this._prewarmed = false
+    this._cleared = true
+    if (this._autoClearTimer) {
+      clearTimeout(this._autoClearTimer)
+      this._autoClearTimer = null
+    }
+  }
+
+  /**
+   * Get all cached file paths.
+   * Returns the paths of all files loaded during prewarm or on-demand reads.
+   */
+  paths(): readonly string[] {
+    return [...this.cache.keys()].sort()
+  }
+
+  /**
+   * Get cache statistics.
+   */
+  /** Auto-clear after timeout to prevent memory leaks from missed lifecycle cleanup */
+  private scheduleAutoClear(): void {
+    if (this._autoClearTimer) {
+      clearTimeout(this._autoClearTimer)
+    }
+    this._autoClearTimer = setTimeout(() => {
+      if (this.cache.size > 0) {
+        this.clear()
+      }
+    }, 10 * 60 * 1000) // 10 minutes
+    // Unref so the timer doesn't keep the process alive
+    this._autoClearTimer.unref()
+  }
+
+  get stats(): {
+    size: number
+    prewarmed: boolean
+    cleared: boolean
+  } {
+    return {
+      size: this.cache.size,
+      prewarmed: this._prewarmed,
+      cleared: this._cleared,
+    }
+  }
+}
+
+/**
+ * Shared file cache instance.
+ */
+export const fileCache = new FileCache()
+
+/**
+ * Default patterns to prewarm for fitness checks.
+ */
+export const DEFAULT_PREWARM_PATTERNS = [
+  '**/*.ts',
+  '**/*.tsx',
+  '**/*.js',
+  '**/*.jsx',
+  '**/*.json',
+  '**/*.md',
+] as const

package/src/framework/file-type-filter.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview File type filtering for per-check file extension matching
+ *
+ * Filters matched files by extension based on a check's declared fileTypes.
+ */
+
+import * as path from 'node:path'
+
+/**
+ * Filter files by extension based on a check's declared fileTypes.
+ * If fileTypes is undefined or empty, returns all files (universal).
+ */
+export function filterFilesByType(
+  files: readonly string[],
+  fileTypes: readonly string[] | undefined,
+): string[] {
+  if (!fileTypes || fileTypes.length === 0) {
+    return [...files]
+  }
+  const extensions = new Set(fileTypes)
+  return files.filter((f) => {
+    const ext = path.extname(f).slice(1) // remove leading dot
+    return extensions.has(ext)
+  })
+}

package/src/framework/ignore-processing.ts

@@ -0,0 +1,350 @@
+// @fitness-ignore-file batch-operation-limits -- iterates bounded collections (config entries, registry items, or small analysis results)
+// @fitness-ignore-file concurrency-safety -- Single-threaded Node.js; Map-based caches are safe without synchronization
+/**
+ * @fileoverview Ignore directive processing for fitness checks
+ *
+ * Filters signals based on file-level and line-level ignore directives.
+ * Signals pointing at lines that contain @fitness-ignore directives are
+ * never suppressed — this prevents recursive suppression loops where
+ * directive-auditing checks would otherwise flag their own suppressions.
+ */
+
+import { logger } from '@opensip-tools/core'
+
+
+import { countErrors, countWarnings } from '../types/severity.js'
+
+import { extractGroup, isWeakReason, parseDirectiveLine } from './directive-inventory.js'
+import { parseFileIgnoreDirective, parseIgnoreDirectives } from './directive-parsing.js'
+import { fileCache } from './file-cache.js'
+
+import type { DirectiveEntry } from './directive-inventory.js'
+import type { CheckResult } from '../types/findings.js'
+import type { Signal } from '@opensip-tools/core'
+
+// =============================================================================
+// DIRECTIVE LINE DETECTION
+// =============================================================================
+
+/**
+ * Scan file content and return the set of 1-based line numbers that contain
+ * @fitness-ignore directives. These lines are framework infrastructure and
+ * must never be suppressed by other directives (prevents recursive loops).
+ */
+function findDirectiveLines(content: string): Set<number> {
+  const directiveLines = new Set<number>()
+  const lines = content.split('\n')
+  for (const [i, line] of lines.entries()) {
+    const trimmed = (line ?? '').trimStart()
+    if (
+      (trimmed.startsWith('//') || trimmed.startsWith('/*')) &&
+      trimmed.includes('@fitness-ignore')
+    ) {
+      directiveLines.add(i + 1)
+    }
+  }
+  return directiveLines
+}
+
+// =============================================================================
+// FILE IGNORE STATUS PROCESSING
+// =============================================================================
+
+/** Cached per-file results from directive scanning. */
+interface FileIgnoreInfo {
+  fileIgnored: boolean
+  ignoredLines: Set<number> | null
+  directiveLines: Set<number>
+}
+
+/**
+ * Processes file ignore status and caches the result.
+ */
+async function processFileIgnoreStatus(
+  filePath: string,
+  checkId: string,
+  fileIgnoreCache: Map<string, boolean>,
+  lineIgnoreCache: Map<string, Set<number>>,
+  directiveLineCache?: Map<string, Set<number>>,
+): Promise<FileIgnoreInfo> {
+  // in-memory: single-threaded Node.js access pattern
+  const fileIgnored = fileIgnoreCache.get(filePath)
+
+  if (fileIgnored !== undefined) {
+    return {
+      fileIgnored,
+      ignoredLines: lineIgnoreCache.get(filePath) ?? null,
+      directiveLines: directiveLineCache?.get(filePath) ?? new Set(),
+    }
+  }
+
+  try {
+    const content = await fileCache.get(filePath)
+    const isIgnored = parseFileIgnoreDirective(content, checkId)
+    fileIgnoreCache.set(filePath, isIgnored)
+
+    // Always scan for directive lines (needed for recursive loop prevention)
+    const dirLines = findDirectiveLines(content)
+    directiveLineCache?.set(filePath, dirLines)
+
+    let ignoredLines: Set<number> | null = null
+    if (!isIgnored) {
+      ignoredLines = parseIgnoreDirectives(content, checkId)
+      lineIgnoreCache.set(filePath, ignoredLines)
+    }
+
+    return { fileIgnored: isIgnored, ignoredLines, directiveLines: dirLines }
+  } catch (error) {
+    logger.warn('fitness.ignore.file_read.failed', { evt: 'fitness.ignore.file_read.failed', module: 'fitness:ignore-processing', filePath, err: error });
+    fileIgnoreCache.set(filePath, false)
+    return { fileIgnored: false, ignoredLines: null, directiveLines: new Set() }
+  }
+}
+
+// =============================================================================
+// SIGNAL FILTERING
+// =============================================================================
+
+/**
+ * Filters signals based on ignore directives.
+ *
+ * Signals pointing at lines that contain `@fitness-ignore` directives are
+ * never suppressed. This is a structural guarantee that prevents recursive
+ * loops: a check that audits directives cannot have its findings suppressed
+ * by the very directives it reports on.
+ */
+interface FilterResult {
+  filteredSignals: Signal[]
+  ignoredCount: number
+  appliedFileIgnores: Set<string>
+  appliedLineIgnores: Map<string, Set<number>>
+}
+
+function classifySignals(
+  signals: readonly Signal[],
+  initialIgnoredCount: number,
+  fileIgnoreCache: Map<string, boolean>,
+  lineIgnoreCache: Map<string, Set<number>>,
+  directiveLineCache: Map<string, Set<number>>,
+): FilterResult {
+  const filteredSignals: Signal[] = []
+  let ignoredCount = initialIgnoredCount
+  const appliedFileIgnores = new Set<string>()
+  const appliedLineIgnores = new Map<string, Set<number>>()
+
+  for (const signal of signals) {
+    if (!isSignalIgnored(signal, fileIgnoreCache, lineIgnoreCache, directiveLineCache)) {
+      filteredSignals.push(signal)
+      continue
+    }
+    ignoredCount++
+    const filePath = signal.code?.file
+    if (!filePath) continue
+
+    if (fileIgnoreCache.get(filePath)) {
+      appliedFileIgnores.add(filePath)
+    } else {
+      const line = signal.code?.line
+      if (line) {
+        let lineSet = appliedLineIgnores.get(filePath)
+        if (!lineSet) {
+          lineSet = new Set()
+          appliedLineIgnores.set(filePath, lineSet)
+        }
+        lineSet.add(line)
+      }
+    }
+  }
+
+  return { filteredSignals, ignoredCount, appliedFileIgnores, appliedLineIgnores }
+}
+
+/** Filter signals based on file-level and line-level @fitness-ignore directives */
+export async function filterSignalsByDirectives(
+  signals: readonly Signal[],
+  checkId: string,
+  initialIgnoredCount: number,
+): Promise<{ filteredSignals: Signal[]; ignoredCount: number; appliedDirectives: DirectiveEntry[] }> {
+  const fileIgnoreCache = new Map<string, boolean>()
+  const lineIgnoreCache = new Map<string, Set<number>>()
+  const directiveLineCache = new Map<string, Set<number>>()
+
+  // Pre-populate file ignore status for all unique file paths in parallel
+  const uniqueFiles = new Set<string>()
+  for (const signal of signals) {
+    const filePath = signal.code?.file
+    if (filePath) uniqueFiles.add(filePath)
+  }
+  await Promise.all(
+    [...uniqueFiles].map((filePath) =>
+      processFileIgnoreStatus(filePath, checkId, fileIgnoreCache, lineIgnoreCache, directiveLineCache),
+    ),
+  )
+
+  const { filteredSignals, ignoredCount, appliedFileIgnores, appliedLineIgnores } =
+    classifySignals(signals, initialIgnoredCount, fileIgnoreCache, lineIgnoreCache, directiveLineCache)
+
+  const appliedDirectives = await collectAppliedDirectives(checkId, appliedFileIgnores, appliedLineIgnores)
+
+  return { filteredSignals, ignoredCount, appliedDirectives }
+}
+
+/**
+ * Determines whether a single signal should be ignored based on cached directive data.
+ *
+ * File-level ignores always apply (the entire file is suppressed).
+ * Line-level ignores apply unless the signal points at a directive line itself
+ * (prevents recursive loops where directive-auditing checks suppress their own findings).
+ */
+function isSignalIgnored(
+  signal: Signal,
+  fileIgnoreCache: Map<string, boolean>,
+  lineIgnoreCache: Map<string, Set<number>>,
+  directiveLineCache: Map<string, Set<number>>,
+): boolean {
+  const filePath = signal.code?.file
+  if (!filePath) return false
+
+  // File-level ignores always apply — no anti-recursion needed
+  if (fileIgnoreCache.get(filePath)) return true
+
+  const signalLine = signal.code?.line
+  const dirLines = directiveLineCache.get(filePath)
+  // For line-level ignores: never suppress signals pointing at directive lines (anti-recursion)
+  if (signalLine && dirLines?.has(signalLine)) return false
+
+  const ignoredLines = lineIgnoreCache.get(filePath)
+  if (signalLine && ignoredLines?.has(signalLine)) return true
+
+  return false
+}
+
+// =============================================================================
+// APPLIED DIRECTIVE COLLECTION
+// =============================================================================
+
+function toDirectiveEntry(
+  filePath: string,
+  lineNumber: number,
+  parsed: { type: 'file' | 'next-line'; checkId: string; reason: string | null },
+): DirectiveEntry {
+  return {
+    filePath,
+    lineNumber,
+    type: parsed.type,
+    checkId: parsed.checkId,
+    group: extractGroup(parsed.checkId),
+    reason: parsed.reason,
+    weakReason: isWeakReason(parsed.reason),
+  }
+}
+
+async function collectFileIgnoreDirectives(
+  checkId: string,
+  appliedFileIgnores: Set<string>,
+): Promise<DirectiveEntry[]> {
+  const results = await Promise.all(
+    [...appliedFileIgnores].map(async (filePath): Promise<DirectiveEntry | null> => {
+      try {
+        const content = await fileCache.get(filePath)
+        const lines = content.split('\n')
+        for (let i = 0; i < Math.min(lines.length, 50); i++) {
+          const parsed = parseDirectiveLine(lines[i] ?? '')
+          if (parsed?.type === 'file' && parsed.checkId === checkId) {
+            return toDirectiveEntry(filePath, i + 1, parsed)
+          }
+        }
+      } catch (error) {
+        logger.warn('fitness.ignore.directive_read.failed', { evt: 'fitness.ignore.directive_read.failed', module: 'fitness:ignore-processing', err: error });
+      }
+      return null
+    }),
+  )
+  return results.filter((d): d is DirectiveEntry => d !== null)
+}
+
+async function collectLineIgnoreDirectives(
+  checkId: string,
+  appliedLineIgnores: Map<string, Set<number>>,
+): Promise<DirectiveEntry[]> {
+  const results = await Promise.all(
+    [...appliedLineIgnores.entries()].map(async ([filePath, suppressedLines]): Promise<DirectiveEntry[]> => {
+      const found: DirectiveEntry[] = []
+      try {
+        const content = await fileCache.get(filePath)
+        const lines = content.split('\n')
+        for (let i = 0; i < lines.length; i++) {
+          const parsed = parseDirectiveLine(lines[i] ?? '')
+          if (parsed?.type !== 'next-line' || parsed.checkId !== checkId) continue
+          let targetLine = i + 1
+          while (targetLine < lines.length && (lines[targetLine] ?? '').trimStart().startsWith('//')) {
+            targetLine++
+          }
+          if (suppressedLines.has(targetLine + 1)) {
+            found.push(toDirectiveEntry(filePath, i + 1, parsed))
+          }
+        }
+      } catch (error) {
+        logger.warn('fitness.ignore.directive_read.failed', { evt: 'fitness.ignore.directive_read.failed', module: 'fitness:ignore-processing', err: error });
+      }
+      return found
+    }),
+  )
+  const directives: DirectiveEntry[] = []
+  for (const batch of results) {
+    for (const d of batch) {
+      directives.push(d)
+    }
+  }
+  return directives
+}
+
+async function collectAppliedDirectives(
+  checkId: string,
+  appliedFileIgnores: Set<string>,
+  appliedLineIgnores: Map<string, Set<number>>,
+): Promise<DirectiveEntry[]> {
+  const [fileDirectives, lineDirectives] = await Promise.all([
+    collectFileIgnoreDirectives(checkId, appliedFileIgnores),
+    collectLineIgnoreDirectives(checkId, appliedLineIgnores),
+  ])
+  return [...fileDirectives, ...lineDirectives]
+}
+
+// =============================================================================
+// RESULT BUILDING
+// =============================================================================
+
+/**
+ * Builds the filtered result from the original result and filtered signals.
+ */
+export function buildFilteredResult(
+  result: CheckResult,
+  filteredSignals: Signal[],
+  ignoredCount: number,
+  start: number,
+): CheckResult {
+  if (!Array.isArray(filteredSignals)) {
+    return result
+  }
+
+  const durationMs = result.metadata.durationMs ?? Date.now() - start
+  const filteredErrors = countErrors(filteredSignals)
+  const filteredWarnings = countWarnings(filteredSignals)
+
+  const filteredResult: CheckResult = {
+    ...result,
+    passed: filteredErrors === 0,
+    errors: filteredErrors,
+    warnings: filteredWarnings,
+    signals: filteredSignals,
+    metadata: {
+      ...result.metadata,
+      durationMs,
+      signals: filteredSignals,
+    },
+    ...(ignoredCount > 0 ? { ignoredCount } : {}),
+  }
+
+  return filteredResult
+}