@opensip-tools/fitness 1.0.4

package/dist/framework/define-check.js

@@ -0,0 +1,252 @@
+// @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';
+// =============================================================================
+// VIOLATION → SIGNAL CONVERSION
+// =============================================================================
+function toSignal(violation, checkSlug, checkTags, defaultFilePath, provider = 'opensip') {
+    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', 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, files, ctx) {
+    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, files, ctx) {
+    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, files, ctx) {
+    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) {
+    validateCheckConfig(config);
+    const 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) {
+            return PathMatcher.create({
+                include: [],
+                exclude: [],
+                cwd,
+            });
+        },
+        async run(cwd, options) {
+            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: [], exclude: [], 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) => 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, ctx) {
+    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 = config;
+    throw new SystemError(`Unknown analysis mode: ${JSON.stringify(_exhaustiveCheck)}`, { code: 'SYSTEM.FITNESS.UNKNOWN_MODE' });
+}
+//# sourceMappingURL=define-check.js.map

package/dist/framework/define-check.js.map

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

package/dist/framework/directive-inventory.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Directive Inventory - shared parsing logic for
+ * fitness-ignore directives.
+ */
+/** 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;
+}
+/**
+ * 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 declare function parseDirectiveLine(line: string): {
+    type: 'file' | 'next-line';
+    checkId: string;
+    reason: string | null;
+} | null;
+/**
+ * Check if a reason is weak/generic. Missing reason (null) is considered weak.
+ */
+export declare function isWeakReason(reason: string | null): boolean;
+/**
+ * Extract the group prefix from a check ID (the directory name).
+ */
+export declare function extractGroup(checkId: string): string;
+//# sourceMappingURL=directive-inventory.d.ts.map

package/dist/framework/directive-inventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive-inventory.d.ts","sourceRoot":"","sources":["../../src/framework/directive-inventory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,UAAU,EAAE,OAAO,CAAA;CACpB;AAwBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;IAChD,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB,GAAG,IAAI,CAiBP;AAyBD;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAG3D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpD"}

package/dist/framework/directive-inventory.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Directive Inventory - shared parsing logic for
+ * fitness-ignore directives.
+ */
+// =============================================================================
+// Shared Constants
+// =============================================================================
+/** Patterns that indicate a weak or generic ignore reason. */
+const WEAK_REASON_PATTERNS = Object.freeze([
+    /^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) {
+    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, type) {
+    // 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) {
+    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) {
+    const slashIndex = checkId.indexOf('/');
+    return slashIndex > 0 ? checkId.slice(0, slashIndex) : 'other';
+}
+//# sourceMappingURL=directive-inventory.js.map

package/dist/framework/directive-inventory.js.map

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

package/dist/framework/directive-parsing.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @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
+ */
+/**
+ * Parse file-level ignore directive from file content.
+ * Returns true if the file should be entirely ignored for that check.
+ */
+export declare function parseFileIgnoreDirective(content: string, checkId: string | readonly string[]): boolean;
+/**
+ * Parse next-line ignore directives from file content.
+ * Returns a set of line numbers that should be ignored.
+ */
+export declare function parseIgnoreDirectives(content: string, checkId: string | readonly string[]): Set<number>;
+//# sourceMappingURL=directive-parsing.d.ts.map

package/dist/framework/directive-parsing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive-parsing.d.ts","sourceRoot":"","sources":["../../src/framework/directive-parsing.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAsFH;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAClC,OAAO,CAYT;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAClC,GAAG,CAAC,MAAM,CAAC,CAyBb"}

package/dist/framework/directive-parsing.js

@@ -0,0 +1,121 @@
+// @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',
+];
+const MAX_DIRECTIVE_SKIP = 3;
+// =============================================================================
+// INTERNAL HELPERS
+// =============================================================================
+function isKnownDirectiveLine(line) {
+    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) {
+    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, directiveKeyword) {
+    // 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, checkId) {
+    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, checkId) {
+    const ignoredLines = new Set();
+    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;
+}
+//# sourceMappingURL=directive-parsing.js.map

package/dist/framework/directive-parsing.js.map

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

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

@@ -0,0 +1,95 @@
+/**
+ * @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-tools/core';
+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[];
+}
+/**
+ * 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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"}