@opensip-tools/fitness 1.0.4

package/src/framework/directive-inventory.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Directive Inventory - shared parsing logic for
+ * fitness-ignore directives.
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** A single fitness-ignore directive found in a source file. */
+export interface DirectiveEntry {
+  filePath: string
+  lineNumber: number
+  type: 'file' | 'next-line'
+  checkId: string
+  group: string
+  reason: string | null
+  weakReason: boolean
+}
+
+// =============================================================================
+// Shared Constants
+// =============================================================================
+
+/** Patterns that indicate a weak or generic ignore reason. */
+const WEAK_REASON_PATTERNS = Object.freeze<readonly RegExp[]>([
+  /^ignore$/i,
+  /^skip$/i,
+  /^todo$/i,
+  /^fixme$/i,
+  /^temporary$/i,
+  /^temp$/i,
+  /^wip$/i,
+  /^disable$/i,
+  /^suppress$/i,
+  /^\s*$/,
+])
+
+// =============================================================================
+// Shared Parsing
+// =============================================================================
+
+/**
+ * Parse a file-level or next-line directive from a comment line.
+ * Accepts both `//` and `/*`-style comments for consistency with the
+ * suppression parser in directive-parsing.ts — otherwise block-comment
+ * directives suppress findings but vanish from inventory counts.
+ */
+export function parseDirectiveLine(line: string): {
+  type: 'file' | 'next-line'
+  checkId: string
+  reason: string | null
+} | null {
+  const trimmed = line.trimStart()
+  if (!trimmed.startsWith('// ') && !trimmed.startsWith('/* ')) return null
+
+  const afterComment = trimmed.slice(3).trimStart()
+
+  if (afterComment.startsWith('@fitness-ignore-file ')) {
+    const rest = afterComment.slice('@fitness-ignore-file '.length)
+    return parseDirectiveRest(rest, 'file')
+  }
+
+  if (afterComment.startsWith('@fitness-ignore-next-line ')) {
+    const rest = afterComment.slice('@fitness-ignore-next-line '.length)
+    return parseDirectiveRest(rest, 'next-line')
+  }
+
+  return null
+}
+
+function parseDirectiveRest(
+  rest: string,
+  type: 'file' | 'next-line',
+): { type: 'file' | 'next-line'; checkId: string; reason: string | null } | null {
+  // Strip trailing `*/` from block-comment directives (e.g. `foo */` → `foo`).
+  // eslint-disable-next-line sonarjs/slow-regex -- anchored at end-of-string, bounded \s* runs; no ReDoS exposure
+  const normalized = rest.replace(/\s*\*\/\s*$/, '').trimEnd()
+
+  const separatorIndex = normalized.indexOf(' -- ')
+
+  if (separatorIndex === -1) {
+    const checkId = normalized.trim()
+    if (!checkId || checkId.includes(' ')) return null
+    return { type, checkId, reason: null }
+  }
+
+  const checkId = normalized.slice(0, separatorIndex).trim()
+  const reason = normalized.slice(separatorIndex + 4).trim()
+
+  if (!checkId || checkId.includes(' ')) return null
+  return { type, checkId, reason: reason || null }
+}
+
+/**
+ * Check if a reason is weak/generic. Missing reason (null) is considered weak.
+ */
+export function isWeakReason(reason: string | null): boolean {
+  if (reason === null) return true
+  return WEAK_REASON_PATTERNS.some((pattern) => pattern.test(reason.trim()))
+}
+
+/**
+ * Extract the group prefix from a check ID (the directory name).
+ */
+export function extractGroup(checkId: string): string {
+  const slashIndex = checkId.indexOf('/')
+  return slashIndex > 0 ? checkId.slice(0, slashIndex) : 'other'
+}
+

package/src/framework/directive-parsing.ts

@@ -0,0 +1,152 @@
+// @fitness-ignore-file semgrep-justifications -- References nosemgrep patterns for directive parsing
+/**
+ * @fileoverview Ignore directive parsing utilities for fitness checks
+ *
+ * Provides utilities for parsing suppression directives:
+ * - @fitness-ignore-file, @fitness-ignore-next-line
+ * - eslint-disable-next-line, eslint-disable-line
+ * - @ts-expect-error, @ts-ignore
+ * - nosemgrep
+ */
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const KNOWN_DIRECTIVE_KEYWORDS = [
+  'eslint-disable-next-line',
+  'eslint-disable-line',
+  '@ts-expect-error',
+  '@ts-ignore',
+  '@ts-nocheck',
+  'prettier-ignore',
+  'biome-ignore',
+  '@fitness-ignore-next-line',
+  '@fitness-ignore-file',
+] as const
+
+const MAX_DIRECTIVE_SKIP = 3
+
+// =============================================================================
+// INTERNAL HELPERS
+// =============================================================================
+
+function isKnownDirectiveLine(line: string): boolean {
+  const trimmed = line.trimStart()
+
+  if (!trimmed.startsWith('//') && !trimmed.startsWith('/*')) {
+    return false
+  }
+
+  const commentContent = trimmed.slice(2).trimStart()
+
+  return KNOWN_DIRECTIVE_KEYWORDS.some((keyword) => {
+    if (!commentContent.startsWith(keyword)) return false
+    const nextChar = commentContent[keyword.length]
+    return nextChar === undefined || nextChar === ' ' || nextChar === '\t' || nextChar === ':'
+  })
+}
+
+function isCheckIdChar(char: string): boolean {
+  const code = char.codePointAt(0) ?? 0
+  const isLowerCase = code >= 97 && code <= 122
+  const isUpperCase = code >= 65 && code <= 90
+  const isDigit = code >= 48 && code <= 57
+  const isSpecialChar = code === 95 || code === 45 || code === 47
+  return isLowerCase || isUpperCase || isDigit || isSpecialChar
+}
+
+function extractCheckIdFromDirective(line: string, directiveKeyword: string): string | null {
+  // Both `//` and `/*` are 2-char prefixes; sliceLen is fixed.
+  const sliceLen = 2
+  let commentIndex = line.indexOf('//')
+  if (commentIndex === -1) {
+    commentIndex = line.indexOf('/*')
+    if (commentIndex === -1) return null
+  }
+
+  const afterComment = line.slice(commentIndex + sliceLen).trimStart()
+  if (!afterComment.startsWith(directiveKeyword)) return null
+
+  const afterDirective = afterComment.slice(directiveKeyword.length)
+  if (
+    afterDirective.length === 0 ||
+    (!afterDirective.startsWith(' ') && !afterDirective.startsWith('\t'))
+  ) {
+    return null
+  }
+
+  const checkIdStart = afterDirective.trimStart()
+  let checkId = ''
+  for (const char of checkIdStart) {
+    if (isCheckIdChar(char)) {
+      checkId += char
+    } else {
+      break
+    }
+  }
+
+  return checkId.length > 0 ? checkId : null
+}
+
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+
+/**
+ * Parse file-level ignore directive from file content.
+ * Returns true if the file should be entirely ignored for that check.
+ */
+export function parseFileIgnoreDirective(
+  content: string,
+  checkId: string | readonly string[],
+): boolean {
+  const lines = content.split('\n').slice(0, 50)
+  const checkIds = Array.isArray(checkId) ? checkId : [checkId]
+
+  for (const line of lines) {
+    const extractedId = extractCheckIdFromDirective(line, '@fitness-ignore-file')
+    if (extractedId !== null && checkIds.includes(extractedId)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Parse next-line ignore directives from file content.
+ * Returns a set of line numbers that should be ignored.
+ */
+export function parseIgnoreDirectives(
+  content: string,
+  checkId: string | readonly string[],
+): Set<number> {
+  const ignoredLines = new Set<number>()
+  const lines = content.split('\n')
+  const checkIds = Array.isArray(checkId) ? checkId : [checkId]
+
+  for (let i = 0; i < lines.length; i++) {
+    const extractedId = extractCheckIdFromDirective(lines[i] ?? '', '@fitness-ignore-next-line')
+    if (extractedId !== null && checkIds.includes(extractedId)) {
+      let targetLine = i + 1
+      let skipped = 0
+
+      while (
+        targetLine < lines.length &&
+        skipped < MAX_DIRECTIVE_SKIP &&
+        isKnownDirectiveLine(lines[targetLine] ?? '')
+      ) {
+        targetLine++
+        skipped++
+      }
+
+      ignoredLines.add(targetLine + 1)
+    }
+  }
+
+  return ignoredLines
+}
+
+
+

package/src/framework/execution-context.ts

@@ -0,0 +1,247 @@
+// @fitness-ignore-file concurrency-safety -- single-threaded execution context
+// @fitness-ignore-file error-handling-suite -- catch blocks delegate errors through established patterns
+/**
+ * @fileoverview Execution context creation for fitness checks
+ *
+ * Provides the runtime context available to check execute functions,
+ * including file access, pattern matching, and abort support.
+ */
+
+import * as fs from 'node:fs/promises'
+import { relative } from 'node:path'
+
+
+import { SystemError } from '@opensip-tools/core'
+import { Minimatch } from 'minimatch'
+
+import { DEFAULT_EXCLUSION_PATTERNS } from './constants.js'
+import { fileCache } from './file-cache.js'
+import { PathMatcher } from './path-matcher.js'
+import { extractSnippet } from './result-builder.js'
+
+import type { ResolvedScope } from './check-config.js'
+
+/**
+ * Check identifier (UUID format).
+ */
+// eslint-disable-next-line sonarjs/redundant-type-aliases -- semantic alias for UUID-shaped check identifier
+type CheckId = string
+
+/**
+ * Error thrown when a check is aborted via AbortSignal.
+ */
+export class CheckAbortedError extends SystemError {
+  readonly name = 'CheckAbortedError' as const
+  readonly checkId: string
+
+  constructor(checkId: string, message?: string) {
+    super(message ?? `Check ${checkId} was aborted`, { code: 'SYSTEM.FITNESS.CHECK_ABORTED' })
+    this.checkId = checkId
+    Object.setPrototypeOf(this, CheckAbortedError.prototype)
+  }
+}
+
+/**
+ * Result of extracting a code snippet.
+ */
+interface ExtractSnippetResult {
+  readonly snippet: string
+  readonly contextLines: number
+}
+
+/**
+ * Execution context provided to check execute function.
+ */
+export interface ExecutionContext {
+  /** Repository root directory */
+  readonly cwd: string
+  /** Read a file's contents */
+  readonly readFile: (path: string) => Promise<string>
+  /** Check if file exists */
+  readonly fileExists: (path: string) => Promise<boolean>
+  /** The check's stable ID (UUID) */
+  readonly checkId: CheckId
+  /** The check's human-readable slug (kebab-case) */
+  readonly checkSlug: string
+  /** Match files using the check's scope or custom patterns */
+  readonly matchFiles: (
+    patterns?: readonly string[],
+    options?: { ignore?: readonly string[] },
+  ) => Promise<readonly string[]>
+  /** Get a PathMatcher for the check's scope */
+  readonly getMatcher: () => PathMatcher
+  /** Verbose logging enabled */
+  readonly verbose: boolean
+  /** Log a message (only in verbose mode) */
+  readonly log: (message: string) => void
+  /** Extract a code snippet with context lines */
+  readonly extractSnippet: (
+    content: string,
+    line: number,
+    contextLines?: number,
+  ) => ExtractSnippetResult
+  /** AbortSignal for cancellation support */
+  readonly signal?: AbortSignal
+  /** Throws if the check has been aborted */
+  readonly checkAborted: () => void
+}
+
+/**
+ * Options for running a check.
+ */
+export interface RunOptions {
+  readonly verbose?: boolean
+  readonly scopeOverride?: string | ResolvedScope
+  readonly additionalExcludes?: readonly string[]
+  readonly signal?: AbortSignal
+  /** Pre-resolved file paths from per-check target overrides. When set, matchFiles() returns these instead of cache paths. */
+  readonly targetFiles?: readonly string[]
+  /**
+   * Run-wide file exclusion patterns from the project config's
+   * `globalExcludes`. Applied to the fileCache fallback path used by
+   * scope-empty checks (e.g. `file-length-limit`). Without this filter,
+   * a check that declares `scope: { languages: [], concerns: [] }`
+   * would scan every prewarmed file regardless of whether the project
+   * told us to exclude it — surfacing findings inside `docs/`,
+   * `tests/fixtures/`, etc., contrary to user intent.
+   */
+  readonly globalExcludes?: readonly string[]
+}
+
+/**
+ * Configuration needed to create execution context.
+ */
+export interface ExecutionContextConfig {
+  readonly id: CheckId
+  readonly slug: string
+  readonly itemType: string
+  readonly unit?: string | undefined
+}
+
+/**
+ * Creates the matchFiles function for the execution context.
+ *
+ * `globalExcludes` come from the project config's top-level
+ * `globalExcludes` array. They are applied ONLY to the fileCache
+ * fallback path — the path taken by scope-empty checks. Custom
+ * `patterns` arguments are honored as-is (the caller knows what they
+ * want), and `targetFiles` from per-check overrides are pre-filtered
+ * by `preResolveAllTargets`. Pre-compiled to Minimatch matchers so
+ * we don't pay regex compilation per filter call.
+ */
+function createMatchFilesFunction(
+  cwd: string,
+  matcher: PathMatcher,
+  targetFiles?: readonly string[],
+  globalExcludes?: readonly string[],
+): (
+  patterns?: readonly string[],
+  options?: { ignore?: readonly string[] },
+) => Promise<readonly string[]> {
+  const compiledGlobalExcludes = globalExcludes && globalExcludes.length > 0
+    ? globalExcludes.map((pattern) => new Minimatch(pattern, { dot: true }))
+    : undefined
+
+  const applyGlobalExcludes = (files: readonly string[]): readonly string[] => {
+    if (!compiledGlobalExcludes) return files
+    return files.filter((filePath) => {
+      const rel = relative(cwd, filePath)
+      return !compiledGlobalExcludes.some((m) => m.match(rel))
+    })
+  }
+
+  return async (
+    patterns?: readonly string[],
+    options?: { ignore?: readonly string[] },
+  ): Promise<readonly string[]> => {
+    if (patterns && patterns.length > 0) {
+      const customMatcher = PathMatcher.create({
+        cwd,
+        include: [...patterns],
+        exclude: [...(options?.ignore ?? []), ...DEFAULT_EXCLUSION_PATTERNS],
+      })
+      return customMatcher.files()
+    }
+
+    // Per-check target files take priority over cache.
+    // These are already filtered by globalExcludes during target
+    // pre-resolution (scope-resolver.ts), so don't re-filter.
+    if (targetFiles) {
+      return targetFiles
+    }
+
+    // When the matcher has no include patterns (checks without targets),
+    // fall back to the prewarmed file cache paths. The cache itself
+    // honors no exclusion config — that's the layer where globalExcludes
+    // must be applied, otherwise scope-empty checks scan every prewarmed
+    // file regardless of project intent.
+    if (matcher.includePatterns.length === 0) {
+      return applyGlobalExcludes(fileCache.paths())
+    }
+
+    return matcher.files()
+  }
+}
+
+/**
+ * Creates the execution context for a check.
+ */
+export function createExecutionContext(
+  config: ExecutionContextConfig,
+  cwd: string,
+  matcher: PathMatcher,
+  options?: RunOptions,
+): ExecutionContext {
+  return {
+    cwd,
+    checkId: config.id,
+    checkSlug: config.slug,
+    verbose: options?.verbose ?? false,
+
+    // @fitness-ignore-next-line unbounded-memory -- size validation via fs.stat() is on the next line; false positive on method name
+    /** @throws {SystemError} When the file exceeds 10MB */
+    async readFile(filePath: string): Promise<string> {
+      const fileStats = await fs.stat(filePath)
+      if (fileStats.size > 10_000_000) {
+        throw new SystemError(`File too large (${fileStats.size} bytes, max 10MB): ${filePath}`, { code: 'SYSTEM.FITNESS.FILE_TOO_LARGE' })
+      }
+      return fileCache.get(filePath)
+    },
+
+    fileExists(filePath: string): Promise<boolean> {
+      return fileCache.exists(filePath)
+    },
+
+    matchFiles: createMatchFilesFunction(cwd, matcher, options?.targetFiles, options?.globalExcludes),
+
+    getMatcher(): PathMatcher {
+      return matcher
+    },
+
+    log(message: string): void {
+      if (options?.verbose) {
+        // @fitness-ignore-next-line no-console-log -- Verbose check-level debug output bypasses structured logger for immediate CLI feedback
+        // @fitness-ignore-next-line logging-standards -- Verbose check-level debug output bypasses structured logger for immediate CLI feedback
+         
+        console.log(`[${config.slug}] ${message}`)
+      }
+    },
+
+    extractSnippet(
+      content: string,
+      line: number,
+      contextLines = 2,
+    ): ExtractSnippetResult {
+      return extractSnippet(content, line, contextLines)
+    },
+
+    ...(options?.signal ? { signal: options.signal } : {}),
+
+    /** @throws {CheckAbortedError} When the check has been aborted */
+    checkAborted(): void {
+      if (options?.signal?.aborted) {
+        throw new CheckAbortedError(config.slug)
+      }
+    },
+  }
+}

package/src/framework/file-accessor.ts

@@ -0,0 +1,171 @@
+/**
+ * @fileoverview FileAccessor implementation for lazy file loading
+ *
+ * Provides lazy-loading file access with LRU caching for
+ * analyzeAll mode checks that need to correlate across files.
+ */
+
+import * as fs from 'node:fs/promises'
+
+import { ValidationError , applyContentFilter } from '@opensip-tools/core'
+
+
+import { fileCache } from './file-cache.js'
+
+import type { FileAccessor } from './check-config.js'
+
+// =============================================================================
+// LRU CACHE
+// =============================================================================
+
+class LRUCache<K, V> {
+  private readonly cache: Map<K, V>
+  private readonly capacity: number
+
+  constructor(capacity: number) {
+    this.cache = new Map()
+    this.capacity = capacity
+  }
+
+  get(key: K): V | undefined {
+    // in-memory: single-threaded Node.js access pattern
+    const value = this.cache.get(key)
+    if (value !== undefined) {
+      this.cache.delete(key)
+      this.cache.set(key, value)
+    }
+    return value
+  }
+
+  set(key: K, value: V): void {
+    if (this.cache.has(key)) {
+      this.cache.delete(key)
+    } else if (this.cache.size >= this.capacity) {
+      const firstKey = this.cache.keys().next().value
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey)
+      }
+    }
+    this.cache.set(key, value)
+  }
+
+  get size(): number {
+    return this.cache.size
+  }
+
+  clear(): void {
+    this.cache.clear()
+  }
+}
+
+// =============================================================================
+// FILE ACCESSOR IMPLEMENTATION
+// =============================================================================
+
+/** Options for creating a FileAccessor instance. */
+export interface FileAccessorOptions {
+  readonly cacheCapacity?: number
+  readonly signal?: AbortSignal
+  /**
+   * Content filtering applied before returning file content. See
+   * BaseCheckConfig.contentFilter for the canonical doc.
+   */
+  readonly contentFilter?: 'raw' | 'strip-strings' | 'strip-strings-and-comments'
+}
+
+const DEFAULT_CACHE_CAPACITY = 100
+
+/** FileAccessor implementation with LRU caching and abort signal support. */
+class FileAccessorImpl implements FileAccessor {
+  readonly paths: readonly string[]
+  private readonly cache: LRUCache<string, string>
+  private readonly pathSet: Set<string>
+  private readonly signal?: AbortSignal
+  private readonly contentFilterMode?: FileAccessorOptions['contentFilter']
+
+  constructor(filePaths: readonly string[], options: FileAccessorOptions = {}) {
+    this.paths = filePaths
+    this.pathSet = new Set(filePaths)
+    this.cache = new LRUCache(options.cacheCapacity ?? DEFAULT_CACHE_CAPACITY)
+    this.signal = options.signal
+    this.contentFilterMode = options.contentFilter
+  }
+
+  async read(filePath: string): Promise<string> {
+    // in-memory: single-threaded Node.js access pattern
+    // @fitness-ignore-next-line detached-promises -- throwIfAborted() is synchronous, optional chaining is not a detached promise
+    this.signal?.throwIfAborted()
+
+    if (!this.pathSet.has(filePath)) {
+      // @fitness-ignore-next-line result-pattern-consistency -- internal method, exceptions propagate to public Result boundary
+      throw new ValidationError(
+        `File path not in matched set: ${filePath}. ` +
+          `Only paths from the 'paths' property can be read.`,
+        { code: 'VALIDATION.FITNESS.PATH_NOT_IN_SET' },
+      )
+    }
+
+    const cached = this.cache.get(filePath)
+    if (cached !== undefined) {
+      return cached
+    }
+
+    // Try global file cache first (populated by prewarm or previous checks)
+    let content = fileCache.getCached(filePath)
+    if (content === undefined) {
+      const fileStats = await fs.stat(filePath)
+      if (fileStats.size > 10_000_000) {
+        // @fitness-ignore-next-line result-pattern-consistency -- infrastructure boundary guard, not domain logic
+        throw new ValidationError(
+          `File too large (${fileStats.size} bytes, max 10MB): ${filePath}`,
+          { code: 'VALIDATION.FITNESS.FILE_TOO_LARGE' },
+        )
+      }
+      content = await fs.readFile(filePath, 'utf8')
+    }
+    // Dispatch through the LanguageAdapter for the file's extension.
+    // See languages/content-filter-dispatch.ts.
+    content = applyContentFilter(filePath, content, this.contentFilterMode ?? 'none')
+    this.cache.set(filePath, content)
+    return content
+  }
+
+  async readMany(filePaths: readonly string[]): Promise<Map<string, string>> {
+    // in-memory: single-threaded Node.js access pattern
+    const results = new Map<string, string>()
+    // @fitness-ignore-next-line no-unbounded-concurrency -- bounded by FileAccessor path set; LRU cache limits memory
+    const entries = await Promise.all(
+      filePaths.map(async (filePath) => {
+        const content = await this.read(filePath)
+        return [filePath, content] as const
+      }),
+    )
+    for (const [filePath, content] of entries) {
+      results.set(filePath, content)
+    }
+    return results
+  }
+
+  async readAll(): Promise<Map<string, string>> {
+    return this.readMany(this.paths)
+  }
+
+  /** Number of files currently held in the LRU cache. */
+  get cachedCount(): number {
+    return this.cache.size
+  }
+
+  /** Evict all entries from the file cache. */
+  clearCache(): void {
+    this.cache.clear()
+  }
+}
+
+/** Create a FileAccessor for lazy-loading files with LRU caching. */
+// @fitness-ignore-next-line result-pattern-consistency -- factory function, cannot fail in domain-meaningful ways
+export function createFileAccessor(
+  filePaths: readonly string[],
+  options: FileAccessorOptions = {},
+): FileAccessor {
+  return new FileAccessorImpl(filePaths, options)
+}