@opensip-tools/fitness 1.0.4

package/src/framework/content-filter.ts

@@ -0,0 +1,288 @@
+// @fitness-ignore-file file-length-limits -- framework/content-filter complexity requires single-file cohesion
+/**
+ * @fileoverview TypeScript scanner-based content filtering
+ *
+ * Uses the TypeScript scanner (not full AST parser) to identify string literal
+ * and comment regions. String content is replaced with spaces of equal length,
+ * preserving line/column positions for accurate violation reporting.
+ */
+
+import { logger } from '@opensip-tools/core'
+import ts from 'typescript'
+
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Content processed by the TypeScript scanner with string/comment region tracking */
+export interface FilteredContent {
+  /** Content with string literals replaced by whitespace of equal length */
+  readonly code: string
+  /**
+   * Content with both string literals AND comments replaced by whitespace
+   * of equal length. Use when a check pattern-matches identifiers via regex
+   * and would otherwise false-positive on banned-call references that
+   * appear in JSDoc / line / block comments documenting the rule
+   * (e.g. ``"Replace getDatabase() with the constructor StoreDeps"`` inside
+   * a doc string).
+   */
+  readonly codeNoComments: string
+  /** Original content (unchanged) */
+  readonly raw: string
+  /** Set of line numbers (1-based) that are entirely inside comments */
+  readonly commentLines: ReadonlySet<number>
+  /** Check if a (1-based line, 0-based column) position is inside a string literal */
+  readonly isInString: (line: number, column: number) => boolean
+  /** Check if a (1-based line, 0-based column) position is inside a comment */
+  readonly isInComment: (line: number, column: number) => boolean
+}
+
+/** A region in the source text defined by byte offsets */
+interface Region {
+  readonly start: number
+  readonly end: number
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+/** Build an array of byte offsets where each line starts. */
+function buildLineStarts(content: string): number[] {
+  const lineStarts: number[] = [0]
+  // eslint-disable-next-line unicorn/no-for-loop -- offset-bearing scan: stores UTF-16 indexes
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === '\n') lineStarts.push(i + 1)
+  }
+  return lineStarts
+}
+
+/**
+ * Build a set of 1-based line numbers from a list of regions.
+ * A line is included if any part of it falls within a region.
+ */
+function linesToSet(content: string, regions: readonly Region[]): ReadonlySet<number> {
+  if (regions.length === 0) return new Set()
+
+  const lineStarts = buildLineStarts(content)
+
+  const result = new Set<number>()
+  for (const region of regions) {
+    for (let lineIdx = 0; lineIdx < lineStarts.length; lineIdx++) {
+      const lineStart = lineStarts[lineIdx]
+      const lineEnd = lineIdx + 1 < lineStarts.length ? lineStarts[lineIdx + 1] - 1 : content.length
+      if (lineStart > region.end) break
+      if (lineEnd >= region.start) {
+        result.add(lineIdx + 1) // 1-based
+      }
+    }
+  }
+  return result
+}
+
+/**
+ * Check if a (1-based line, 0-based column) offset falls within any region.
+ */
+function isInRegions(content: string, regions: readonly Region[], line: number, column: number): boolean {
+  if (regions.length === 0) return false
+
+  // Convert line/column to byte offset
+  let currentLine = 1
+  let lineStart = 0
+  // eslint-disable-next-line unicorn/no-for-loop -- offset-bearing scan: captures UTF-16 line start
+  for (let i = 0; i < content.length; i++) {
+    if (currentLine === line) {
+      lineStart = i
+      break
+    }
+    if (content[i] === '\n') currentLine++
+  }
+  if (currentLine !== line) return false
+
+  const offset = lineStart + column
+  for (const region of regions) {
+    if (offset >= region.start && offset < region.end) return true
+  }
+  return false
+}
+
+/**
+ * Replace characters in the given range with spaces, preserving newlines.
+ * Records the range as a string region.
+ */
+function replaceCharsInRange(chars: string[], start: number, end: number, stringRegions: Region[]): void {
+  stringRegions.push({ start, end })
+  for (let i = start; i < end; i++) {
+    if (chars[i] !== '\n') chars[i] = ' '
+  }
+}
+
+// =============================================================================
+// MAIN
+// =============================================================================
+
+/**
+ * Scan content using TypeScript's scanner to identify string and comment regions.
+ *
+ * String literals are replaced with spaces of equal length, preserving
+ * line/column positions. Comments are tracked but not removed (directives
+ * live in comments and must be preserved).
+ */
+// Module-level cache to avoid re-running the TS scanner on the same content.
+// Bounded by an idle timer (10 min, matching parse-cache.ts) so long-lived
+// embedders don't accumulate cached filter results across runs forever. The
+// timer resets each time filterContent runs, so an active session never
+// loses its cache.
+const FILTER_CACHE_IDLE_TIMEOUT_MS = 10 * 60 * 1000
+const filterCache = new Map<string, FilteredContent>()
+let filterCacheIdleTimer: ReturnType<typeof setTimeout> | null = null
+
+function scheduleFilterCacheClear(): void {
+  if (filterCacheIdleTimer) clearTimeout(filterCacheIdleTimer)
+  filterCacheIdleTimer = setTimeout(() => {
+    filterCache.clear()
+    filterCacheIdleTimer = null
+  }, FILTER_CACHE_IDLE_TIMEOUT_MS)
+  filterCacheIdleTimer.unref()
+}
+
+/** Clear the filter cache (call between runs or on memory pressure) */
+export function clearFilterCache(): void {
+  filterCache.clear()
+  if (filterCacheIdleTimer) {
+    clearTimeout(filterCacheIdleTimer)
+    filterCacheIdleTimer = null
+  }
+}
+
+export function filterContent(content: string): FilteredContent {
+  const cached = filterCache.get(content)
+  if (cached) {
+    scheduleFilterCacheClear()
+    return cached
+  }
+
+  try {
+    const result = filterContentImpl(content)
+    filterCache.set(content, result)
+    scheduleFilterCacheClear()
+    return result
+  } catch {
+    // Graceful degradation — return raw content if scanner fails
+    logger.debug('Content filter fell back to raw content', { evt: 'fitness.content_filter.fallback', module: 'fitness:framework' })
+    const fallback: FilteredContent = {
+      code: content,
+      codeNoComments: content,
+      raw: content,
+      commentLines: new Set(),
+      isInString: () => false,
+      isInComment: () => false,
+    }
+    filterCache.set(content, fallback)
+    return fallback
+  }
+}
+
+// eslint-disable-next-line sonarjs/cognitive-complexity -- TS scanner driver: token-by-token loop with per-kind handling; flatter shape would scatter token classification
+function filterContentImpl(content: string): FilteredContent {
+  const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.Standard, content)
+
+  const stringRegions: Region[] = []
+  const commentRegions: Region[] = []
+  const chars = [...content]
+
+  // Depth counter, not a boolean — a `${ `inner` }` construct nests two templates
+  // and each `}` that closes a template-expression must be rescanned. A plain
+  // boolean flipped off by the inner TemplateTail would leave the outer unrescanned
+  // and desync the scanner for the rest of the file (which silently wipes real
+  // code to whitespace). Incremented at TemplateHead, decremented at TemplateTail.
+  let templateDepth = 0
+
+   
+  while (true) {
+    let token = scanner.scan()
+    // @fitness-ignore-next-line unsafe-secret-comparison -- comparing TypeScript SyntaxKind enum, not a secret
+    if (token === ts.SyntaxKind.EndOfFileToken) break
+
+    // After a CloseBraceToken inside ANY template expression, rescan to get TemplateMiddle/TemplateTail
+    // @fitness-ignore-next-line unsafe-secret-comparison -- comparing TypeScript SyntaxKind enum, not a secret
+    if (token === ts.SyntaxKind.CloseBraceToken && templateDepth > 0) {
+      token = scanner.reScanTemplateToken(false)
+    }
+
+    const start = scanner.getTokenStart()
+    const end = scanner.getTokenEnd()
+
+    switch (token) {
+      case ts.SyntaxKind.StringLiteral:
+      case ts.SyntaxKind.NoSubstitutionTemplateLiteral: {
+        // Replace content inside quotes/backticks (keep delimiters)
+        replaceCharsInRange(chars, start + 1, end - 1, stringRegions)
+        break
+      }
+
+      case ts.SyntaxKind.TemplateHead: {
+        // `text ${ — replace text between ` and ${
+        templateDepth++
+        replaceCharsInRange(chars, start + 1, end - 2, stringRegions)
+        break
+      }
+
+      case ts.SyntaxKind.TemplateMiddle: {
+        // }text ${ — replace text between } and ${
+        replaceCharsInRange(chars, start + 1, end - 2, stringRegions)
+        break
+      }
+
+      case ts.SyntaxKind.TemplateTail: {
+        // }text` — replace text between } and `
+        templateDepth--
+        replaceCharsInRange(chars, start + 1, end - 1, stringRegions)
+        break
+      }
+
+      case ts.SyntaxKind.SingleLineCommentTrivia:
+      case ts.SyntaxKind.MultiLineCommentTrivia: {
+        // Track comment regions but don't modify content
+        commentRegions.push({ start, end })
+        break
+      }
+
+      // RegularExpressionLiteral — leave unchanged, regex is code
+      default: {
+        break
+      }
+    }
+  }
+
+  const code = chars.join('')
+  const commentLines = linesToSet(content, commentRegions)
+
+  // Compute `codeNoComments` by additionally replacing comment regions
+  // with whitespace. Done as a second pass on a fresh array so `code`
+  // (strings-stripped only) and `codeNoComments` (strings + comments
+  // stripped) remain available — most checks want one or the other,
+  // not both.
+  const charsNoComments = [...content]
+  for (const region of stringRegions) {
+    for (let i = region.start; i < region.end; i++) {
+      if (charsNoComments[i] !== '\n') charsNoComments[i] = ' '
+    }
+  }
+  for (const region of commentRegions) {
+    for (let i = region.start; i < region.end; i++) {
+      if (charsNoComments[i] !== '\n') charsNoComments[i] = ' '
+    }
+  }
+  const codeNoComments = charsNoComments.join('')
+
+  return {
+    code,
+    codeNoComments,
+    raw: content,
+    commentLines,
+    isInString: (line, column) => isInRegions(content, stringRegions, line, column),
+    isInComment: (line, column) => isInRegions(content, commentRegions, line, column),
+  }
+}

package/src/framework/define-check.ts

@@ -0,0 +1,336 @@
+// @fitness-ignore-file module-coupling-metrics -- central orchestration module with necessary coupling
+// @fitness-ignore-file null-safety -- ResultBuilder.create() returns a fluent builder; .totalItems().filesScanned() chain is always safe
+/**
+ * @fileoverview defineCheck - Unified check definition API
+ *
+ * The main API for creating fitness checks. Supports three modes:
+ * - analyze: Per-file analysis with content and path
+ * - analyzeAll: Multi-file analysis with lazy loading FileAccessor
+ * - command: External tool execution with output parsing
+ *
+ * Check authors return CheckViolation[]. The framework converts each
+ * CheckViolation into a universal Signal via createSignal().
+ */
+
+import { logger , SystemError , createSignal , applyContentFilter } from '@opensip-tools/core'
+
+
+
+import {
+  getAnalysisMode,
+  isAnalyzeConfig,
+  isAnalyzeAllConfig,
+  isCommandConfig,
+  validateCheckConfig,
+} from './check-config.js'
+import { executeCommand } from './command-executor.js'
+import { CheckAbortedError, createExecutionContext } from './execution-context.js'
+import { createFileAccessor } from './file-accessor.js'
+import { filterFilesByType } from './file-type-filter.js'
+import { filterSignalsByDirectives, buildFilteredResult } from './ignore-processing.js'
+import { PathMatcher } from './path-matcher.js'
+import { ResultBuilder } from './result-builder.js'
+import { mapFindingSeverity, mapTagsToSignalCategory } from './severity-mapping.js'
+
+import type {
+  UnifiedCheckConfig,
+  CheckViolation,
+  AnalyzeCheckConfig,
+  AnalyzeAllCheckConfig,
+  CommandCheckConfig,
+} from './check-config.js'
+import type { Check } from './check-types.js'
+import type { ExecutionContext, RunOptions } from './execution-context.js'
+import type { CheckResult } from '../types/findings.js'
+import type { Signal } from '@opensip-tools/core'
+
+// =============================================================================
+// VIOLATION → SIGNAL CONVERSION
+// =============================================================================
+
+function toSignal(
+  violation: CheckViolation,
+  checkSlug: string,
+  checkTags: readonly string[],
+  defaultFilePath?: string,
+  provider = 'opensip',
+): Signal {
+  const filePath = violation.filePath ?? defaultFilePath ?? ''
+  return createSignal({
+    source: 'fitness',
+    provider,
+    severity: mapFindingSeverity(violation.severity),
+    category: mapTagsToSignalCategory(checkTags),
+    ruleId: `fit:${checkSlug}`,
+    message: violation.message,
+    suggestion: violation.suggestion,
+    code: { file: filePath, line: violation.line, column: violation.column },
+    fix: violation.fix
+      ?? (violation.suggestion ? { action: 'refactor' as const, confidence: 0.5 } : undefined),
+    metadata: Object.fromEntries(
+      Object.entries({
+        match: violation.match,
+        type: violation.type,
+        checkSlug,
+        checkTags: checkTags.length > 0 ? checkTags.join(',') : undefined,
+      }).filter(([, v]) => v != null && v !== ''),
+    ),
+  })
+}
+
+// =============================================================================
+// ANALYSIS MODE EXECUTORS
+// =============================================================================
+
+/** @throws {CheckAbortedError} When the check is aborted via AbortSignal */
+async function executeAnalyzeMode(
+  config: AnalyzeCheckConfig,
+  files: readonly string[],
+  ctx: ExecutionContext,
+): Promise<CheckResult> {
+  const builder = ResultBuilder.create({
+    checkId: config.id,
+    itemType: config.itemType ?? 'files',
+  })
+    .totalItems(files.length)
+    .filesScanned(files.length)
+
+  for (const filePath of files) {
+    if (ctx.signal?.aborted) {
+      throw new CheckAbortedError(config.slug)
+    }
+
+    try {
+      const rawContent = await ctx.readFile(filePath)
+      // Dispatch the content filter through the LanguageAdapter for the
+      // file's extension. Falls back to raw content when no adapter is
+      // registered. See languages/content-filter-dispatch.ts.
+      const content = applyContentFilter(filePath, rawContent, config.contentFilter ?? 'none')
+      const violations = config.analyze(content, filePath)
+
+      for (const violation of violations) {
+        void builder.addSignal(toSignal(violation, config.slug, config.tags ?? [], filePath, config.provider))
+      }
+    } catch (error) {
+      if (error instanceof CheckAbortedError) throw error
+      logger.debug('Skipping unreadable file', { evt: 'fitness.check.file.skip', module: 'fitness:framework', filePath, checkSlug: config.slug })
+    }
+  }
+
+  return builder.build()
+}
+
+/** @throws {CheckAbortedError} When the check is aborted via AbortSignal */
+async function executeAnalyzeAllMode(
+  config: AnalyzeAllCheckConfig,
+  files: readonly string[],
+  ctx: ExecutionContext,
+): Promise<CheckResult> {
+  if (ctx.signal?.aborted) {
+    throw new CheckAbortedError(config.slug)
+  }
+
+  const fileAccessor = createFileAccessor(files, { signal: ctx.signal, contentFilter: config.contentFilter })
+  const violations = await config.analyzeAll(fileAccessor)
+
+  if (ctx.signal?.aborted) {
+    throw new CheckAbortedError(config.slug)
+  }
+
+  const builder = ResultBuilder.create({
+    checkId: config.id,
+    itemType: config.itemType ?? 'files',
+  })
+    .totalItems(files.length)
+    .filesScanned(files.length)
+
+  for (const violation of violations) {
+    if (!violation.filePath) {
+      ctx.log(`Warning: violation missing filePath in analyzeAll mode`)
+    }
+    void builder.addSignal(toSignal(violation, config.slug, config.tags ?? [], undefined, config.provider))
+  }
+
+  return builder.build()
+}
+
+/** @throws {CheckAbortedError} When the check is aborted via AbortSignal */
+async function executeCommandMode(
+  config: CommandCheckConfig,
+  files: readonly string[],
+  ctx: ExecutionContext,
+): Promise<CheckResult> {
+  const result = await executeCommand(config.command, files, {
+    cwd: ctx.cwd,
+    signal: ctx.signal,
+    timeout: config.timeout,
+  })
+
+  if (result.aborted) {
+    throw new CheckAbortedError(config.slug)
+  }
+
+  const builder = ResultBuilder.create({
+    checkId: config.id,
+    itemType: config.itemType ?? 'files',
+  })
+    .totalItems(files.length)
+    .filesScanned(0)
+
+  if (result.error) {
+    return builder.buildError(result.error)
+  }
+
+  for (const violation of result.violations) {
+    void builder.addSignal(toSignal(violation, config.slug, config.tags ?? [], undefined, config.provider))
+  }
+
+  return builder.build()
+}
+
+// =============================================================================
+// MAIN EXPORT
+// =============================================================================
+
+/**
+ * Define a fitness check using the unified API.
+ *
+ * @example
+ * ```typescript
+ * export const noConsoleLog = defineCheck({
+ *   id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+ *   slug: 'no-console-log',
+ *   category: 'quality',
+ *   description: 'Disallow console.log in production code',
+ *   analyze: (content, filePath) => {
+ *     const violations: CheckViolation[] = [];
+ *     content.split('\n').forEach((line, idx) => {
+ *       if (line.includes('console.log')) {
+ *         violations.push({ line: idx + 1, message: 'No console.log', severity: 'error' });
+ *       }
+ *     });
+ *     return violations;
+ *   },
+ * });
+ * ```
+ * @throws {ValidationError} When the check config is invalid
+ */
+export function defineCheck(config: UnifiedCheckConfig): Check {
+  validateCheckConfig(config)
+
+  const check: Check = {
+    config: {
+      id: config.id,
+      slug: config.slug,
+      tags: config.tags ? [...config.tags] : [],
+      description: config.description,
+      longDescription: config.longDescription,
+      analysisMode: getAnalysisMode(config),
+      scope: { include: [], exclude: [], description: '' },
+      itemType: config.itemType ?? 'files',
+      docs: config.docs,
+      disabled: config.disabled,
+      confidence: config.confidence,
+      timeout: config.timeout,
+      scansFiles: !isCommandConfig(config),
+      fileTypes: config.fileTypes ? [...config.fileTypes] : undefined,
+      checkScope: config.scope ? { languages: [...config.scope.languages], concerns: [...config.scope.concerns] } : undefined,
+      // @fitness-ignore-next-line concurrency-safety -- async arrow delegates to executeUnifiedCheck which is async; needed for type compatibility
+      execute: async (ctx) => executeUnifiedCheck(config, ctx),
+    },
+
+    getScope() {
+      return { include: [], exclude: [], description: 'target-based scope' }
+    },
+
+    getMatcher(cwd: string): PathMatcher {
+      return PathMatcher.create({
+        include: [],
+        exclude: [],
+        cwd,
+      })
+    },
+
+    async run(cwd: string, options?: RunOptions): Promise<CheckResult> {
+      const start = Date.now()
+
+      const matcher = PathMatcher.create({
+        include: [],
+        exclude: [],
+        cwd,
+      })
+
+      const legacyConfig = {
+        id: config.id,
+        slug: config.slug,
+        tags: config.tags ? [...config.tags] : [],
+        description: config.description,
+        scope: { include: [] as readonly string[], exclude: [] as readonly string[], description: '' },
+        itemType: (config.itemType ?? 'files'),
+        docs: config.docs,
+        disabled: config.disabled,
+        timeout: config.timeout,
+        scansFiles: !isCommandConfig(config),
+        // @fitness-ignore-next-line concurrency-safety -- async arrow delegates to executeUnifiedCheck which is async; needed for type compatibility
+        execute: async (ctx: ExecutionContext) => executeUnifiedCheck(config, ctx),
+      }
+
+      const ctx = createExecutionContext(legacyConfig, cwd, matcher, options)
+
+      try {
+        const result = await executeUnifiedCheck(config, ctx)
+
+        const { filteredSignals, ignoredCount, appliedDirectives } = await filterSignalsByDirectives(
+          result.signals,
+          config.slug,
+          result.ignoredCount ?? 0,
+        )
+
+        const filtered = buildFilteredResult(result, filteredSignals, ignoredCount, start)
+        return appliedDirectives.length > 0 ? { ...filtered, appliedDirectives } : filtered
+      } catch (error) {
+        if (error instanceof CheckAbortedError) throw error
+
+        const builder = ResultBuilder.create({
+          checkId: config.id,
+          itemType: config.itemType ?? 'files',
+        })
+        return builder.buildError(
+          `Check ${config.slug} threw an error: ${error instanceof Error ? error.message : String(error)}`,
+          error instanceof Error ? error : undefined,
+        )
+      }
+    },
+  }
+
+  return check
+}
+
+/**
+ * Internal: Execute a check based on its analysis mode (analyze /
+ * analyzeAll / command).
+ * @throws {CheckAbortedError} When the check is aborted via AbortSignal
+ * @throws {SystemError} When an unknown analysis mode is encountered
+ */
+async function executeUnifiedCheck(
+  config: UnifiedCheckConfig,
+  ctx: ExecutionContext,
+): Promise<CheckResult> {
+  const matchedFiles = await ctx.matchFiles()
+
+  // Filter by check's declared file types
+  const files = filterFilesByType(matchedFiles, config.fileTypes)
+
+  ctx.log(`Matched ${files.length} files`)
+
+  if (isAnalyzeConfig(config)) {
+    return executeAnalyzeMode(config, files, ctx)
+  } else if (isAnalyzeAllConfig(config)) {
+    return executeAnalyzeAllMode(config, files, ctx)
+  } else if (isCommandConfig(config)) {
+    return executeCommandMode(config, files, ctx)
+  }
+
+  const _exhaustiveCheck: never = config
+  throw new SystemError(`Unknown analysis mode: ${JSON.stringify(_exhaustiveCheck)}`, { code: 'SYSTEM.FITNESS.UNKNOWN_MODE' })
+}