/**
 * @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 { PathMatcher } from './path-matcher.js';
import type { ResolvedScope } from './check-config.js';
import type { FileCache } from './file-cache.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-run FileCache instance. On the production path the recipe service passes
     * the resolved `scope.fitness.fileCache` here. Optional only for the no-scope
     * direct `run()` / unit-test path; when omitted, `createExecutionContext`
     * resolves `currentScope()?.fitness?.fileCache` and throws
     * `SYSTEM.FITNESS.NO_FILE_CACHE` if neither is present on a file-reading path
     * (no module-singleton fallback — parallel-tool-invocations Phase 1).
     */
    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