@opensip-tools/fitness 1.0.4

package/src/framework/import-graph.ts

@@ -0,0 +1,280 @@
+/**
+ * @fileoverview Project-wide import graph builder.
+ *
+ * Builds a file-level dependency graph from a set of TypeScript/JavaScript
+ * source files, plus a Tarjan's strongly-connected-components implementation
+ * for cycle detection. Used by structural-drift checks like
+ * circular-import-detection and module-coupling-fan-out.
+ *
+ * Module resolution is deliberately a heuristic: relative imports are
+ * resolved by trying common extension/index.ts suffixes; bare specifiers
+ * (npm packages) are dropped; tsconfig path aliases are NOT resolved
+ * (treated as unresolved — they simply don't appear as edges in the graph).
+ *
+ * This matches the heuristic the existing `phantom-dependency-detection`
+ * check uses, which has been shipping reliably. Adding tsconfig-aware
+ * resolution is a follow-up plan.
+ */
+
+import * as path from 'node:path'
+
+import ts from 'typescript'
+
+import { getSharedSourceFile } from './parse-cache.js'
+
+// =============================================================================
+// PUBLIC TYPES
+// =============================================================================
+
+/** A file-level import graph for a project. */
+export interface ImportGraph {
+  /** All node file paths (absolute, as supplied by the caller). */
+  readonly nodes: ReadonlySet<string>
+  /** Adjacency: file → set of files it imports (intra-project edges only). */
+  readonly outbound: ReadonlyMap<string, ReadonlySet<string>>
+  /** Reverse adjacency: file → set of files that import it. */
+  readonly inbound: ReadonlyMap<string, ReadonlySet<string>>
+}
+
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+
+/**
+ * Build an import graph from a collection of file paths and their content.
+ *
+ * Each file's TS AST is walked for top-level `import` and `export ... from`
+ * declarations. Relative specifiers (`./foo`, `../bar/baz.js`) are resolved
+ * against the importing file's directory using the heuristic in
+ * `resolveRelativeSpecifier`. Bare specifiers (`react`, `lodash`) are
+ * dropped — they don't represent intra-project edges.
+ *
+ * Files that fail to parse are still added as nodes (with no edges) so the
+ * graph remains complete.
+ */
+export function buildImportGraph(files: ReadonlyMap<string, string>): ImportGraph {
+  const nodes = new Set<string>(files.keys())
+  const outbound = new Map<string, Set<string>>()
+  const inbound = new Map<string, Set<string>>()
+
+  // Initialize empty edge sets for every node so callers can safely
+  // outbound.get(file) without checking for undefined.
+  for (const node of nodes) {
+    outbound.set(node, new Set())
+    inbound.set(node, new Set())
+  }
+
+  for (const [filePath, content] of files) {
+    const specifiers = extractImportSpecifiers(filePath, content)
+    for (const spec of specifiers) {
+      const resolved = resolveRelativeSpecifier(filePath, spec, nodes)
+      if (resolved !== null) {
+        outbound.get(filePath)!.add(resolved)
+        inbound.get(resolved)!.add(filePath)
+      }
+    }
+  }
+
+  return { nodes, outbound, inbound }
+}
+
+/**
+ * Find strongly-connected components in the graph using Tarjan's algorithm.
+ *
+ * Returns an array of SCCs, each represented as an array of node names. SCCs
+ * of size 1 represent a node with no cycle (or a self-loop, which is rare in
+ * import graphs). Cycle-detection callers typically filter to `scc.length > 1`
+ * to get only real multi-file cycles.
+ *
+ * Algorithm: standard iterative Tarjan's SCC. O(V + E), single pass.
+ */
+export function findStronglyConnectedComponents(
+  graph: ImportGraph,
+): readonly (readonly string[])[] {
+  const indexOf = new Map<string, number>()
+  const lowlinkOf = new Map<string, number>()
+  const onStack = new Set<string>()
+  const stack: string[] = []
+  const sccs: string[][] = []
+  let nextIndex = 0
+
+  // Iterative Tarjan's — recursive form blows the stack on large graphs.
+  // State machine: we replay each node's adjacency from where we left off.
+  interface Frame {
+    node: string
+    neighbors: string[]
+    next: number
+  }
+
+  // eslint-disable-next-line sonarjs/cognitive-complexity -- iterative Tarjan SCC: explicit stack to avoid recursion; the algorithm is canonical and reads cleanest as a single function
+  function strongConnect(start: string): void {
+    const callStack: Frame[] = []
+
+    indexOf.set(start, nextIndex)
+    lowlinkOf.set(start, nextIndex)
+    nextIndex++
+    stack.push(start)
+    onStack.add(start)
+    callStack.push({
+      node: start,
+      neighbors: [...(graph.outbound.get(start) ?? [])],
+      next: 0,
+    })
+
+    while (callStack.length > 0) {
+      const frame = callStack.at(-1)!
+
+      if (frame.next < frame.neighbors.length) {
+        const w = frame.neighbors[frame.next]
+        frame.next++
+
+        if (!indexOf.has(w)) {
+          // Recurse into w.
+          indexOf.set(w, nextIndex)
+          lowlinkOf.set(w, nextIndex)
+          nextIndex++
+          stack.push(w)
+          onStack.add(w)
+          callStack.push({
+            node: w,
+            neighbors: [...(graph.outbound.get(w) ?? [])],
+            next: 0,
+          })
+          continue
+        }
+
+        if (onStack.has(w)) {
+          // Back edge — update v's lowlink.
+          const vLow = lowlinkOf.get(frame.node)!
+          const wIdx = indexOf.get(w)!
+          if (wIdx < vLow) lowlinkOf.set(frame.node, wIdx)
+        }
+        continue
+      }
+
+      // All neighbors processed — finalize this node.
+      const v = frame.node
+      const vLow = lowlinkOf.get(v)!
+      const vIdx = indexOf.get(v)!
+
+      if (vLow === vIdx) {
+        // v is the root of an SCC — pop until v is removed.
+        const scc: string[] = []
+        let w: string
+        do {
+          w = stack.pop()!
+          onStack.delete(w)
+          scc.push(w)
+        } while (w !== v)
+        sccs.push(scc)
+      }
+
+      callStack.pop()
+
+      // Propagate lowlink up to the parent frame.
+      if (callStack.length > 0) {
+        const parent = callStack.at(-1)!
+        const parentLow = lowlinkOf.get(parent.node)!
+        if (vLow < parentLow) lowlinkOf.set(parent.node, vLow)
+      }
+    }
+  }
+
+  for (const node of graph.nodes) {
+    if (!indexOf.has(node)) {
+      strongConnect(node)
+    }
+  }
+
+  return sccs
+}
+
+// =============================================================================
+// INTERNAL HELPERS
+// =============================================================================
+
+/** Walk the AST and collect top-level import / export-from specifiers. */
+function extractImportSpecifiers(filePath: string, content: string): string[] {
+  const sourceFile = getSharedSourceFile(filePath, content)
+  if (sourceFile === null) return []
+
+  const specifiers: string[] = []
+  for (const stmt of sourceFile.statements) {
+    // import foo from './bar';  import './side-effect';  import * as ns from './m';
+    if (ts.isImportDeclaration(stmt) && ts.isStringLiteral(stmt.moduleSpecifier)) {
+      specifiers.push(stmt.moduleSpecifier.text)
+      continue
+    }
+    // export * from './foo';   export { x } from './foo';
+    if (
+      ts.isExportDeclaration(stmt) &&
+      stmt.moduleSpecifier !== undefined &&
+      ts.isStringLiteral(stmt.moduleSpecifier)
+    ) {
+      specifiers.push(stmt.moduleSpecifier.text)
+    }
+  }
+  return specifiers
+}
+
+/**
+ * Resolve a module specifier to an actual file path in the project, or
+ * return null if the specifier is non-relative (npm package, path alias) or
+ * doesn't resolve to a known project file.
+ *
+ * Supports:
+ *   - `./foo` → `<dir>/foo.ts`, `.tsx`, `/index.ts`, `/index.tsx`
+ *   - `./foo.js` → `<dir>/foo.ts` (ESM extension swap, common in TS+ESM)
+ *   - `./foo.ts` → `<dir>/foo.ts` (literal)
+ *   - `../bar/baz` → resolved relative to importer's directory
+ *
+ * Does NOT support:
+ *   - tsconfig `paths` aliases (deferred per plan)
+ *   - npm packages (correctly dropped — out of scope for intra-project graph)
+ */
+function resolveRelativeSpecifier(
+  importerPath: string,
+  specifier: string,
+  knownPaths: ReadonlySet<string>,
+): string | null {
+  // Only relative specifiers participate in the intra-project graph.
+  if (!specifier.startsWith('.')) return null
+
+  const importerDir = path.dirname(importerPath)
+  const base = path.resolve(importerDir, specifier)
+
+  // Try the candidate paths in priority order. The first one that exists in
+  // the project's file set wins.
+  const candidates: string[] = [ base]
+
+  // 1. Literal path (specifier already includes extension).
+
+  // 2. ESM extension swap: `.js` → `.ts` / `.tsx` (TypeScript ESM convention).
+  if (base.endsWith('.js')) {
+    candidates.push(base.slice(0, -3) + '.ts', base.slice(0, -3) + '.tsx')
+  }
+  if (base.endsWith('.jsx')) {
+    candidates.push(base.slice(0, -4) + '.tsx')
+  }
+
+  // 3. Append common extensions if the specifier was extension-less.
+  const hasExt = path.extname(base) !== ''
+  if (!hasExt) {
+    // Direct extensions and index resolution.
+    candidates.push(
+      base + '.ts',
+      base + '.tsx',
+      base + '.js',
+      base + '.jsx',
+      path.join(base, 'index.ts'),
+      path.join(base, 'index.tsx'),
+      path.join(base, 'index.js'),
+      path.join(base, 'index.jsx'),
+    )
+  }
+
+  for (const candidate of candidates) {
+    if (knownPaths.has(candidate)) return candidate
+  }
+  return null
+}

package/src/framework/memory-profiler.ts

@@ -0,0 +1,145 @@
+/**
+ * @fileoverview Memory profiler for fitness checks
+ *
+ * Always-on, low-overhead memory tracking for check execution.
+ * Collects per-check profiles for trending analysis.
+ */
+
+/** Point-in-time snapshot of Node.js memory usage */
+interface MemorySnapshot {
+  readonly heapUsed: number
+  readonly heapTotal: number
+  readonly external: number
+  readonly arrayBuffers: number
+  readonly rss: number
+}
+
+/** Memory usage profile recorded for a single check execution */
+export interface CheckMemoryProfile {
+  readonly checkId: string
+  readonly memoryBeforeMB: number
+  readonly memoryAfterMB: number
+  readonly memoryDeltaMB: number
+  readonly violationCount: number
+  readonly durationMs: number
+}
+
+/** Aggregated memory profiling summary across all check executions */
+interface MemoryProfileSummary {
+  readonly prewarmMemoryMB: number
+  readonly peakMemoryMB: number
+  readonly checksExceedingThreshold: number
+  readonly topConsumers: readonly CheckMemoryProfile[]
+  readonly allProfiles: readonly CheckMemoryProfile[]
+}
+
+const DEFAULT_MEMORY_WARNING_THRESHOLD_MB = 200
+
+/** Low-overhead memory profiler that tracks per-check heap usage during fitness runs */
+class MemoryProfiler {
+  private readonly profiles: CheckMemoryProfile[] = []
+  private prewarmMemoryMB = 0
+  private peakMemoryMB = 0
+  private readonly warningThresholdMB: number
+
+  constructor(warningThresholdMB = DEFAULT_MEMORY_WARNING_THRESHOLD_MB) {
+    this.warningThresholdMB = warningThresholdMB
+  }
+
+  private takeSnapshot(): MemorySnapshot {
+    const mem = process.memoryUsage()
+    return {
+      heapUsed: mem.heapUsed,
+      heapTotal: mem.heapTotal,
+      external: mem.external,
+      arrayBuffers: mem.arrayBuffers,
+      rss: mem.rss,
+    }
+  }
+
+  private bytesToMB(bytes: number): number {
+    return bytes / 1024 / 1024
+  }
+
+  /** Record memory baseline after cache prewarm completes */
+  recordPrewarmComplete(): void {
+    const snapshot = this.takeSnapshot()
+    this.prewarmMemoryMB = this.bytesToMB(snapshot.heapUsed)
+    this.peakMemoryMB = this.prewarmMemoryMB
+  }
+
+  /** Return current heap usage in megabytes */
+  getCurrentMemoryMB(): number {
+    const snapshot = this.takeSnapshot()
+    return this.bytesToMB(snapshot.heapUsed)
+  }
+
+  /** Record memory before a check starts; returns the pre-check heap in MB */
+  recordCheckStart(): number {
+    return this.getCurrentMemoryMB()
+  }
+
+  /** Record memory after a check completes and return the check's memory profile */
+  recordCheckComplete(
+    checkId: string,
+    memoryBeforeMB: number,
+    violationCount: number,
+    durationMs: number,
+  ): CheckMemoryProfile {
+    const memoryAfterMB = this.getCurrentMemoryMB()
+    const memoryDeltaMB = memoryAfterMB - memoryBeforeMB
+
+    if (memoryAfterMB > this.peakMemoryMB) {
+      this.peakMemoryMB = memoryAfterMB
+    }
+
+    const profile: CheckMemoryProfile = {
+      checkId,
+      memoryBeforeMB: Math.round(memoryBeforeMB * 100) / 100,
+      memoryAfterMB: Math.round(memoryAfterMB * 100) / 100,
+      memoryDeltaMB: Math.round(memoryDeltaMB * 100) / 100,
+      violationCount,
+      durationMs,
+    }
+
+    this.profiles.push(profile)
+    return profile
+  }
+
+  /** Check whether a memory delta exceeds the configured warning threshold */
+  exceedsThreshold(deltaMB: number): boolean {
+    return deltaMB > this.warningThresholdMB
+  }
+
+  /** Return the configured warning threshold in megabytes */
+  getWarningThresholdMB(): number {
+    return this.warningThresholdMB
+  }
+
+  /** Build and return an aggregated summary of all recorded check profiles */
+  getSummary(): MemoryProfileSummary {
+    const sortedProfiles = [...this.profiles].sort((a, b) => b.memoryDeltaMB - a.memoryDeltaMB)
+
+    const checksExceedingThreshold = this.profiles.filter(
+      (p) => p.memoryDeltaMB > this.warningThresholdMB,
+    ).length
+
+    return {
+      prewarmMemoryMB: Math.round(this.prewarmMemoryMB * 100) / 100,
+      peakMemoryMB: Math.round(this.peakMemoryMB * 100) / 100,
+      checksExceedingThreshold,
+      topConsumers: sortedProfiles.slice(0, 10),
+      allProfiles: this.profiles,
+    }
+  }
+
+  /** Reset all recorded profiles and counters */
+  reset(): void {
+    this.profiles.length = 0
+    this.prewarmMemoryMB = 0
+    this.peakMemoryMB = 0
+  }
+}
+
+/** Shared singleton memory profiler instance used across fitness check runs */
+export const memoryProfiler = new MemoryProfiler()

package/src/framework/parse-cache.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Re-export from the language-aware parse cache.
+ *
+ * The init/clear lifecycle and getParseTree API live in
+ * core/src/languages/parse-cache.ts. This file forwards those calls
+ * for backward compatibility with code that imported from this path.
+ *
+ * getSharedSourceFile remains as a TS-specific convenience wrapper
+ * that resolves the TypeScript adapter from the language registry.
+ * Phase 2 moved the canonical TS AST helpers to
+ * @opensip-tools/lang-typescript; this shim is retained for the
+ * core framework/import-graph.ts internal use case.
+ */
+
+
+import { getParseTree, defaultLanguageRegistry } from '@opensip-tools/core'
+import ts from 'typescript'
+
+/**
+ * Get a TypeScript SourceFile via the language-aware cache when the TS
+ * adapter is registered, falling back to a direct parse otherwise.
+ *
+ * @internal Used by framework/import-graph.ts. New TS check authors
+ * should import getSharedSourceFile from @opensip-tools/lang-typescript.
+ */
+export function getSharedSourceFile(filePath: string, content: string): ts.SourceFile | null {
+  const adapter = defaultLanguageRegistry.get('typescript')
+  if (adapter) {
+    return getParseTree(adapter, filePath, content) as ts.SourceFile | null
+  }
+  // No adapter registered yet (e.g. unit tests that run without CLI bootstrap).
+  // Fall back to direct parse — preserves prior behavior.
+  try {
+    return ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+  } catch {
+    return null
+  }
+}

package/src/framework/path-matcher.ts

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview PathMatcher - Strategy pattern for file matching
+ *
+ * Provides glob-based file matching with include/exclude patterns.
+ * Supports lazy evaluation and composition.
+ */
+
+import * as path from 'node:path'
+
+import { glob } from 'glob'
+import { minimatch } from 'minimatch'
+
+/**
+ * Options for PathMatcher.
+ */
+export interface PathMatcherOptions {
+  /** Root directory to search from */
+  readonly cwd: string
+  /** Glob patterns to include */
+  readonly include: readonly string[]
+  /** Glob patterns to exclude */
+  readonly exclude: readonly string[]
+  /** Additional exclusion patterns (combined with exclude) */
+  readonly additionalExcludes?: readonly string[]
+}
+
+/**
+ * Result of file matching operation.
+ */
+export interface MatchResult {
+  /** Matched files (absolute paths) */
+  readonly files: readonly string[]
+  /** Files that were excluded */
+  readonly excluded: readonly string[]
+  /** Time taken for glob operation in ms */
+  readonly durationMs: number
+}
+
+/**
+ * Strategy for matching files based on glob patterns.
+ * Supports both custom patterns and composition.
+ *
+ * @example
+ * ```typescript
+ * const matcher = PathMatcher.create({
+ *   cwd: '/path/to/repo',
+ *   include: ['src/**\/*.ts'],
+ *   exclude: ['**\/__tests__/**'],
+ * });
+ * const files = await matcher.files();
+ * ```
+ */
+export class PathMatcher {
+  private constructor(private readonly options: PathMatcherOptions) {}
+
+  /**
+   * Create a PathMatcher from options.
+   */
+  static create(options: PathMatcherOptions): PathMatcher {
+    return new PathMatcher(options)
+  }
+
+  /**
+   * Get all matching files.
+   * @returns Array of absolute file paths matching the patterns
+   */
+  async files(): Promise<readonly string[]> {
+    const result = await this.match()
+    return result.files
+  }
+
+  /**
+   * Get detailed match result including timing.
+   */
+  async match(): Promise<MatchResult> {
+    const start = Date.now()
+
+    const allExcludes = [...this.options.exclude, ...(this.options.additionalExcludes ?? [])]
+
+    // Run glob for all include patterns
+    const matchedSets = await Promise.all(
+      this.options.include.map((pattern) =>
+        glob(pattern, {
+          cwd: this.options.cwd,
+          absolute: true,
+          nodir: true,
+          ignore: allExcludes,
+        }),
+      ),
+    )
+
+    // Combine and deduplicate results
+    const allMatched = new Set<string>()
+    for (const matches of matchedSets) {
+      for (const file of matches) {
+        allMatched.add(path.normalize(file))
+      }
+    }
+
+    const files = [...allMatched].sort()
+    const durationMs = Date.now() - start
+
+    return {
+      files,
+      excluded: [],
+      durationMs,
+    }
+  }
+
+  /**
+   * Check if a file matches the patterns.
+   * @param filePath - Absolute path to check
+   * @returns True if file matches include patterns and is not excluded
+   */
+  matches(filePath: string): boolean {
+    const relativePath = path.relative(this.options.cwd, filePath)
+
+    const matchesInclude = this.options.include.some((pattern) =>
+      minimatch(relativePath, pattern, { dot: true }),
+    )
+
+    if (!matchesInclude) {
+      return false
+    }
+
+    const allExcludes = [...this.options.exclude, ...(this.options.additionalExcludes ?? [])]
+
+    const matchesExclude = allExcludes.some((pattern) =>
+      minimatch(relativePath, pattern, { dot: true }),
+    )
+
+    return !matchesExclude
+  }
+
+  /**
+   * Create a new PathMatcher with additional exclusions.
+   */
+  withExcludes(additionalExcludes: readonly string[]): PathMatcher {
+    return new PathMatcher({
+      ...this.options,
+      additionalExcludes: [...(this.options.additionalExcludes ?? []), ...additionalExcludes],
+    })
+  }
+
+  /**
+   * Create a new PathMatcher that only includes TypeScript files.
+   */
+  typescriptOnly(): PathMatcher {
+    return new PathMatcher({
+      ...this.options,
+      include: this.options.include.map((pattern) => {
+        if (pattern.endsWith('/*') || pattern.endsWith('/**/*')) {
+          const base = pattern.replace(/\/\*+$/, '')
+          return `${base}/**/*.{ts,tsx}`
+        }
+        if (!pattern.includes('.')) {
+          return `${pattern}/**/*.{ts,tsx}`
+        }
+        return pattern
+      }),
+    })
+  }
+
+  /**
+   * Create a new PathMatcher that excludes test files.
+   */
+  noTests(): PathMatcher {
+    return this.withExcludes([
+      '**/__tests__/**',
+      '**/*.test.ts',
+      '**/*.test.tsx',
+      '**/*.spec.ts',
+      '**/*.spec.tsx',
+    ])
+  }
+
+  /** Get the current working directory. */
+  get cwd(): string {
+    return this.options.cwd
+  }
+
+  /** Get the include patterns. */
+  get includePatterns(): readonly string[] {
+    return this.options.include
+  }
+
+  /** Get the exclude patterns. */
+  get excludePatterns(): readonly string[] {
+    return [...this.options.exclude, ...(this.options.additionalExcludes ?? [])]
+  }
+}

package/src/framework/register-helpers.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Helper for registering checks with a namespace
+ */
+
+import { defaultRegistry } from './registry.js';
+
+import type { Check } from './check-types.js';
+
+/**
+ * Register an array of checks with a namespace into the default registry.
+ * @returns The number of checks registered.
+ */
+export function registerChecks(checks: Check[], namespace: string): number {
+  let count = 0;
+  for (const check of checks) {
+    defaultRegistry.register(check, namespace);
+    count++;
+  }
+  return count;
+}