@opensip-cli/fitness 0.1.0

package/dist/framework/execution-context.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @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 { SystemError } from '@opensip-cli/core';
+import { type FileCache } from './file-cache.js';
+import { PathMatcher } from './path-matcher.js';
+import type { ResolvedScope } from './check-config.js';
+/**
+ * Check identifier (UUID format).
+ */
+type CheckId = string;
+/**
+ * Error thrown when a check is aborted via AbortSignal.
+ */
+export declare class CheckAbortedError extends SystemError {
+    readonly name: "CheckAbortedError";
+    readonly checkId: string;
+    constructor(checkId: string, message?: string);
+}
+/**
+ * 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[];
+    /** Per-service FileCache instance (for SaaS isolation; falls back to global). */
+    readonly fileCache?: FileCache;
+}
+/**
+ * Configuration needed to create execution context.
+ */
+export interface ExecutionContextConfig {
+    readonly id: CheckId;
+    readonly slug: string;
+    readonly itemType: string;
+    readonly unit?: string | undefined;
+}
+/**
+ * Creates the execution context for a check.
+ */
+export declare function createExecutionContext(config: ExecutionContextConfig, cwd: string, matcher: PathMatcher, options?: RunOptions): ExecutionContext;
+export {};
+//# sourceMappingURL=execution-context.d.ts.map

package/dist/framework/execution-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-context.d.ts","sourceRoot":"","sources":["../../src/framework/execution-context.ts"],"names":[],"mappings":"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"}

package/dist/framework/execution-context.js

@@ -0,0 +1,145 @@
+// @fitness-ignore-file concurrency-safety -- single-threaded execution context
+// @fitness-ignore-file error-handling-suite -- catch blocks delegate errors through established patterns
+// @fitness-ignore-file unbounded-memory -- readFile IS the size-validating wrapper: fs.stat guard + post-read content.length guard both throw FILE_TOO_LARGE (>10MB)
+/**
+ * @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 { SystemError, currentScope, logger as defaultLogger } from '@opensip-cli/core';
+import { applyGlobalExcludes } from '../targets/index.js';
+import { DEFAULT_EXCLUSION_PATTERNS } from './constants.js';
+import { fileCache as globalFileCache } from './file-cache.js';
+import { PathMatcher } from './path-matcher.js';
+import { extractSnippet } from './result-builder.js';
+/**
+ * Error thrown when a check is aborted via AbortSignal.
+ */
+export class CheckAbortedError extends SystemError {
+    name = 'CheckAbortedError';
+    checkId;
+    constructor(checkId, message) {
+        super(message ?? `Check ${checkId} was aborted`, { code: 'SYSTEM.FITNESS.CHECK_ABORTED' });
+        this.checkId = checkId;
+        Object.setPrototypeOf(this, CheckAbortedError.prototype);
+    }
+}
+/**
+ * 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`. The fileCache-fallback exclusion routes
+ * through the substrate `applyGlobalExcludes` (ADR-0037) — the SAME
+ * single implementation the scope-resolution path uses, so globalExcludes
+ * is single-sourced on both paths (no separate Minimatch path in fitness).
+ */
+function createMatchFilesFunction(cwd, matcher, targetFiles, globalExcludes, fileCacheInstance) {
+    const fc = fileCacheInstance ?? globalFileCache;
+    return async (patterns, options) => {
+        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(fc.paths(), cwd, globalExcludes ?? []);
+        }
+        return matcher.files();
+    };
+}
+/**
+ * Creates the execution context for a check.
+ */
+export function createExecutionContext(config, cwd, matcher, options) {
+    const fc = options?.fileCache ?? globalFileCache;
+    return {
+        cwd,
+        checkId: config.id,
+        checkSlug: config.slug,
+        verbose: options?.verbose ?? false,
+        /** @throws {SystemError} When the file exceeds 10MB */
+        async readFile(filePath) {
+            // Fast-fail on obvious on-disk size before pulling content (optimization).
+            // The authoritative check is performed on the *actual* bytes returned
+            // (closes TOCTOU between stat and read, and protects against a cache
+            // entry that grew or was prewarmed with a larger version).
+            try {
+                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',
+                    });
+                }
+            }
+            catch (error) {
+                // If stat itself fails, let the subsequent get() surface the real FS error
+                // (directory, permission, etc.). Only swallow the size error we just threw.
+                if (error instanceof SystemError && error.code === 'SYSTEM.FITNESS.FILE_TOO_LARGE')
+                    throw error;
+            }
+            const content = await fc.get(filePath);
+            if (content.length > 10_000_000) {
+                throw new SystemError(`File too large (${content.length} bytes, max 10MB): ${filePath}`, {
+                    code: 'SYSTEM.FITNESS.FILE_TOO_LARGE',
+                });
+            }
+            return content;
+        },
+        fileExists(filePath) {
+            return fc.exists(filePath);
+        },
+        matchFiles: createMatchFilesFunction(cwd, matcher, options?.targetFiles, options?.globalExcludes, fc),
+        getMatcher() {
+            return matcher;
+        },
+        log(message) {
+            if (!options?.verbose)
+                return;
+            // Route through the structured logger from RunScope so future
+            // --json / --quiet modes that reconfigure the logger can suppress
+            // check-level debug output uniformly. Falls back to the module
+            // default logger when no scope is active (e.g. test harnesses
+            // that exercise an ExecutionContext directly). Audit-round-2
+            // Finding D: this was previously `console.log` which bypassed
+            // the structured channel and could not be suppressed.
+            const log = currentScope()?.logger ?? defaultLogger;
+            log.info({
+                evt: 'fitness.check.verbose',
+                module: 'fitness:framework',
+                checkSlug: config.slug,
+                message,
+            });
+        },
+        extractSnippet(content, line, contextLines = 2) {
+            return extractSnippet(content, line, contextLines);
+        },
+        ...(options?.signal ? { signal: options.signal } : {}),
+        /** @throws {CheckAbortedError} When the check has been aborted */
+        checkAborted() {
+            if (options?.signal?.aborted) {
+                throw new CheckAbortedError(config.slug);
+            }
+        },
+    };
+}
+//# sourceMappingURL=execution-context.js.map

package/dist/framework/execution-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-context.js","sourceRoot":"","sources":["../../src/framework/execution-context.ts"],"names":[],"mappings":"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"}

package/dist/framework/file-accessor.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @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 type { FileAccessor } from './check-config.js';
+/** 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';
+}
+/** Create a FileAccessor for lazy-loading files with LRU caching. */
+export declare function createFileAccessor(filePaths: readonly string[], options?: FileAccessorOptions): FileAccessor;
+//# sourceMappingURL=file-accessor.d.ts.map

package/dist/framework/file-accessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-accessor.d.ts","sourceRoot":"","sources":["../../src/framework/file-accessor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAkDtD,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,KAAK,GAAG,eAAe,GAAG,4BAA4B,CAAC;CACjF;AA0FD,qEAAqE;AAErE,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,OAAO,GAAE,mBAAwB,GAChC,YAAY,CAEd"}

package/dist/framework/file-accessor.js

@@ -0,0 +1,122 @@
+/**
+ * @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-cli/core';
+import { fileCache } from './file-cache.js';
+// =============================================================================
+// LRU CACHE
+// =============================================================================
+class LRUCache {
+    cache;
+    capacity;
+    constructor(capacity) {
+        this.cache = new Map();
+        this.capacity = capacity;
+    }
+    get(key) {
+        // 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, value) {
+        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() {
+        return this.cache.size;
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+const DEFAULT_CACHE_CAPACITY = 100;
+/** FileAccessor implementation with LRU caching and abort signal support. */
+class FileAccessorImpl {
+    paths;
+    cache;
+    pathSet;
+    signal;
+    contentFilterMode;
+    constructor(filePaths, options = {}) {
+        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) {
+        // 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) {
+        // in-memory: single-threaded Node.js access pattern
+        const results = new Map();
+        // @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];
+        }));
+        for (const [filePath, content] of entries) {
+            results.set(filePath, content);
+        }
+        return results;
+    }
+    async readAll() {
+        return this.readMany(this.paths);
+    }
+    /** Number of files currently held in the LRU cache. */
+    get cachedCount() {
+        return this.cache.size;
+    }
+    /** Evict all entries from the file cache. */
+    clearCache() {
+        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, options = {}) {
+    return new FileAccessorImpl(filePaths, options);
+}
+//# sourceMappingURL=file-accessor.js.map

package/dist/framework/file-accessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-accessor.js","sourceRoot":"","sources":["../../src/framework/file-accessor.ts"],"names":[],"mappings":"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"}

package/dist/framework/file-cache.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @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.
+ */
+/**
+ * Prewarm statistics.
+ */
+interface PrewarmStats {
+    /** Number of files loaded */
+    readonly filesLoaded: number;
+    /** Duration in milliseconds */
+    readonly durationMs: number;
+    /** Total bytes loaded */
+    readonly totalBytes: number;
+}
+export declare class FileCache {
+    private readonly cache;
+    private _prewarmed;
+    private _cleared;
+    private _autoClearTimer;
+    /**
+     * 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
+     */
+    prewarm(cwd: string, patterns: readonly string[]): Promise<PrewarmStats>;
+    /**
+     * 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;
+    get(filePath: string): Promise<string>;
+    /**
+     * Check if a file exists (in cache or on disk).
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * Clear the cache. Must be called after checks complete.
+     */
+    clear(): void;
+    /**
+     * Get all cached file paths.
+     * Returns the paths of all files loaded during prewarm or on-demand reads.
+     */
+    paths(): readonly string[];
+    /**
+     * Get cache statistics.
+     */
+    /** Auto-clear after timeout to prevent memory leaks from missed lifecycle cleanup */
+    private scheduleAutoClear;
+    get stats(): {
+        size: number;
+        prewarmed: boolean;
+        cleared: boolean;
+    };
+}
+/**
+ * Shared file cache instance.
+ */
+export declare const fileCache: FileCache;
+/**
+ * Default patterns to prewarm for fitness checks.
+ */
+export declare const DEFAULT_PREWARM_PATTERNS: readonly ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.json", "**/*.md"];
+export {};
+//# sourceMappingURL=file-cache.d.ts.map

package/dist/framework/file-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.d.ts","sourceRoot":"","sources":["../../src/framework/file-cache.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAQH;;GAEG;AACH,UAAU,YAAY;IACpB,6BAA6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAYD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,eAAe,CAA8C;IAErE;;;;;OAKG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAiE9E;;;OAGG;IACH,+EAA+E;IAC/E,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKzC,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA+B5C;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBhD;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;;OAGG;IACH,KAAK,IAAI,SAAS,MAAM,EAAE;IAI1B;;OAEG;IACH,qFAAqF;IACrF,OAAO,CAAC,iBAAiB;IAkBzB,IAAI,KAAK,IAAI;QACX,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,OAAO,CAAC;QACnB,OAAO,EAAE,OAAO,CAAC;KAClB,CAMA;CACF;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,WAAkB,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,wBAAwB,iFAO3B,CAAC"}