@guilz-dev/belay 0.8.0 → 0.9.0

package/dist/corpus/{must-allow-commands.js → benign-probe-cores.js}

@@ -1,9 +1,9 @@
 /**
- * Structural-suite MUST-ALLOW CI expectations.
+ * Structural-suite benign probe cores.
  * These commands guard classifier availability in tests and never grant runtime authority.
  * @see src/__tests__/verdict/structural-suite.test.ts
  */
-export const MUST_ALLOW_SHELL_COMMANDS = [
+export const BENIGN_PROBE_CORES = [
     'npm test',
     'npm run build',
     'pnpm test',
@@ -11,4 +11,10 @@ export const MUST_ALLOW_SHELL_COMMANDS = [
     'pnpm vitest run src/example.test.ts',
     "bash -lc 'git status'",
     'belay approve belay_deadbeef1234',
+    'bundle -v',
+    'ruby -v',
+    'yarn --version',
+    'make -n test',
+    'bin/rails routes',
+    'bundle exec rubocop --version',
 ];

package/dist/corpus/coverage-compare.d.ts

@@ -0,0 +1,36 @@
+import type { CoverageContextId } from './coverage-matrix.js';
+import type { CoverageProbeReport } from './coverage-probe.js';
+export declare class CoverageCompareError extends Error {
+    constructor(message: string);
+}
+export type CoverageCompareKind = 'fixture_change' | 'classifier_drift' | 'added' | 'removed';
+export interface CoverageCompareEntry {
+    caseId: string;
+    context: CoverageContextId;
+    kind: CoverageCompareKind;
+    beforeVerdict?: string;
+    afterVerdict?: string;
+    beforeReason?: string;
+    afterReason?: string;
+    beforeCommandHash?: string;
+    afterCommandHash?: string;
+    beforeExpectationHash?: string | null;
+    afterExpectationHash?: string | null;
+}
+export interface CoverageContextConfigDrift {
+    context: CoverageContextId;
+    beforeHash: string;
+    afterHash: string;
+}
+export interface CoverageCompareReport {
+    schemaVersion: 1;
+    matrixHashChanged: boolean;
+    beforeMatrixHash: string;
+    afterMatrixHash: string;
+    configDrift: CoverageContextConfigDrift[];
+    entries: CoverageCompareEntry[];
+}
+export declare function parseCoverageProbeReportForCompare(raw: unknown): CoverageProbeReport;
+export declare function compareBaselineWarnings(baseline: CoverageProbeReport, current: CoverageProbeReport): string[];
+export declare function compareCoverageReports(baseline: CoverageProbeReport, current: CoverageProbeReport): CoverageCompareReport;
+export declare function formatCoverageCompareReport(report: CoverageCompareReport): string;

package/dist/corpus/coverage-compare.js

@@ -0,0 +1,197 @@
+const SUPPORTED_COMPARE_REPORT_SCHEMA_VERSIONS = [1, 2];
+export class CoverageCompareError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CoverageCompareError';
+    }
+}
+function resultKey(caseId, context) {
+    return `${caseId}::${context}`;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeCaseResult(raw) {
+    if (!isRecord(raw)) {
+        throw new CoverageCompareError('--compare baseline result row is invalid');
+    }
+    if (typeof raw.caseId !== 'string' || typeof raw.context !== 'string') {
+        throw new CoverageCompareError('--compare baseline result row is missing caseId or context');
+    }
+    if (!isRecord(raw.actual)) {
+        throw new CoverageCompareError('--compare baseline result row is missing actual verdict');
+    }
+    const expectationHash = raw.expectationHash === undefined || raw.expectationHash === null
+        ? null
+        : String(raw.expectationHash);
+    const verdict = String(raw.actual.verdict);
+    return {
+        ...raw,
+        expectationHash,
+        actual: {
+            verdict,
+            reason: String(raw.actual.reason ?? ''),
+            fingerprint: String(raw.actual.fingerprint ?? ''),
+        },
+    };
+}
+export function parseCoverageProbeReportForCompare(raw) {
+    if (!isRecord(raw)) {
+        throw new CoverageCompareError('--compare baseline must be a JSON object');
+    }
+    if (!Array.isArray(raw.results)) {
+        throw new CoverageCompareError('--compare baseline is missing results[]');
+    }
+    const schemaVersion = raw.reportSchemaVersion ?? 1;
+    if (typeof schemaVersion !== 'number' ||
+        !SUPPORTED_COMPARE_REPORT_SCHEMA_VERSIONS.includes(schemaVersion)) {
+        throw new CoverageCompareError(`--compare baseline reportSchemaVersion is unsupported: ${JSON.stringify(raw.reportSchemaVersion)}`);
+    }
+    if (!Array.isArray(raw.contexts)) {
+        throw new CoverageCompareError('--compare baseline is missing contexts[]');
+    }
+    return {
+        ...raw,
+        reportSchemaVersion: schemaVersion,
+        results: raw.results.map(normalizeCaseResult),
+    };
+}
+export function compareBaselineWarnings(baseline, current) {
+    const warnings = [];
+    if (baseline.reportSchemaVersion !== current.reportSchemaVersion) {
+        warnings.push(`baseline schema v${baseline.reportSchemaVersion} differs from current v${current.reportSchemaVersion}`);
+    }
+    const baselineContexts = new Set(baseline.contexts.map((context) => context.id));
+    const currentContexts = new Set(current.contexts.map((context) => context.id));
+    const onlyBaseline = [...baselineContexts].filter((context) => !currentContexts.has(context));
+    const onlyCurrent = [...currentContexts].filter((context) => !baselineContexts.has(context));
+    if (onlyBaseline.length > 0 || onlyCurrent.length > 0) {
+        warnings.push(`context set differs (baseline-only: ${onlyBaseline.join(', ') || '-'}; current-only: ${onlyCurrent.join(', ') || '-'})`);
+    }
+    return warnings;
+}
+function indexResults(report) {
+    const map = new Map();
+    for (const result of report.results) {
+        map.set(resultKey(result.caseId, result.context), result);
+    }
+    return map;
+}
+function classifierOutputChanged(before, after) {
+    return (before.actual.verdict !== after.actual.verdict ||
+        before.actual.reason !== after.actual.reason ||
+        before.actual.fingerprint !== after.actual.fingerprint);
+}
+export function compareCoverageReports(baseline, current) {
+    const beforeMatrixHash = baseline.matrixHash;
+    const afterMatrixHash = current.matrixHash;
+    const matrixHashChanged = beforeMatrixHash !== afterMatrixHash;
+    const beforeContextHashes = new Map(baseline.contexts.map((context) => [context.id, context.resolvedConfigHash]));
+    const afterContextHashes = new Map(current.contexts.map((context) => [context.id, context.resolvedConfigHash]));
+    const configDrift = [];
+    const sharedContexts = new Set([...beforeContextHashes.keys(), ...afterContextHashes.keys()]);
+    for (const context of sharedContexts) {
+        const beforeHash = beforeContextHashes.get(context);
+        const afterHash = afterContextHashes.get(context);
+        if (beforeHash !== undefined && afterHash !== undefined && beforeHash !== afterHash) {
+            configDrift.push({ context, beforeHash, afterHash });
+        }
+    }
+    const beforeResults = indexResults(baseline);
+    const afterResults = indexResults(current);
+    const keys = new Set([...beforeResults.keys(), ...afterResults.keys()]);
+    const entries = [];
+    for (const key of [...keys].sort()) {
+        const before = beforeResults.get(key);
+        const after = afterResults.get(key);
+        if (!before && after) {
+            entries.push({
+                caseId: after.caseId,
+                context: after.context,
+                kind: 'added',
+                afterVerdict: after.actual.verdict,
+                afterReason: after.actual.reason,
+                afterCommandHash: after.commandHash,
+                afterExpectationHash: after.expectationHash ?? null,
+            });
+            continue;
+        }
+        if (before && !after) {
+            entries.push({
+                caseId: before.caseId,
+                context: before.context,
+                kind: 'removed',
+                beforeVerdict: before.actual.verdict,
+                beforeReason: before.actual.reason,
+                beforeCommandHash: before.commandHash,
+                beforeExpectationHash: before.expectationHash ?? null,
+            });
+            continue;
+        }
+        if (!before || !after) {
+            continue;
+        }
+        const fixtureChanged = before.commandHash !== after.commandHash ||
+            (before.expectationHash ?? null) !== (after.expectationHash ?? null);
+        const classifierChanged = classifierOutputChanged(before, after);
+        if (fixtureChanged) {
+            entries.push({
+                caseId: after.caseId,
+                context: after.context,
+                kind: 'fixture_change',
+                beforeVerdict: before.actual.verdict,
+                afterVerdict: after.actual.verdict,
+                beforeReason: before.actual.reason,
+                afterReason: after.actual.reason,
+                beforeCommandHash: before.commandHash,
+                afterCommandHash: after.commandHash,
+                beforeExpectationHash: before.expectationHash ?? null,
+                afterExpectationHash: after.expectationHash ?? null,
+            });
+            continue;
+        }
+        if (classifierChanged) {
+            entries.push({
+                caseId: after.caseId,
+                context: after.context,
+                kind: 'classifier_drift',
+                beforeVerdict: before.actual.verdict,
+                afterVerdict: after.actual.verdict,
+                beforeReason: before.actual.reason,
+                afterReason: after.actual.reason,
+                beforeCommandHash: before.commandHash,
+                afterCommandHash: after.commandHash,
+                beforeExpectationHash: before.expectationHash ?? null,
+                afterExpectationHash: after.expectationHash ?? null,
+            });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        matrixHashChanged,
+        beforeMatrixHash,
+        afterMatrixHash,
+        configDrift,
+        entries,
+    };
+}
+export function formatCoverageCompareReport(report) {
+    const lines = [];
+    lines.push('Coverage probe compare');
+    lines.push(`matrix hash changed: ${report.matrixHashChanged ? 'yes' : 'no'}`);
+    if (report.configDrift.length > 0) {
+        lines.push('config drift (warning only):');
+        for (const drift of report.configDrift) {
+            lines.push(`  - ${drift.context}: ${drift.beforeHash.slice(0, 8)} -> ${drift.afterHash.slice(0, 8)}`);
+        }
+    }
+    if (report.entries.length === 0) {
+        lines.push('no fixture or classifier differences');
+        return lines.join('\n');
+    }
+    lines.push(`differences: ${report.entries.length}`);
+    for (const entry of report.entries) {
+        lines.push(`  - [${entry.kind}] ${entry.caseId} (${entry.context}) ${entry.beforeVerdict ?? '-'} -> ${entry.afterVerdict ?? '-'}`);
+    }
+    return lines.join('\n');
+}

package/dist/corpus/coverage-contexts.d.ts

@@ -0,0 +1,17 @@
+import { type BelayConfigV4 } from '../core/config.js';
+import type { ConfigProvenanceEntry } from '../core/config-layers.js';
+import type { ClassifierOptions } from '../core/types.js';
+import type { CoverageContextId } from './coverage-matrix.js';
+export interface CoverageEvalContext {
+    id: CoverageContextId;
+    config: BelayConfigV4;
+    cwd: string;
+    repoRoot: string;
+    options: ClassifierOptions;
+    configProvenance?: ConfigProvenanceEntry[];
+}
+export declare function structuralCoverageConfig(): BelayConfigV4;
+export declare function buildCoverageEvalContexts(contextIds: CoverageContextId[], repoRoot: string): Promise<CoverageEvalContext[]>;
+export declare function stableJsonStringify(value: unknown): string;
+export declare function hashStableJson(value: unknown): string;
+export declare function resolvedConfigHash(context: CoverageEvalContext): string;

package/dist/corpus/coverage-contexts.js

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { loadLayeredConfig } from '../config-io.js';
+import { DEFAULT_CONFIG_V3, DEFAULT_CONFIG_V4, mergeConfig, } from '../core/config.js';
+import { DEFAULT_CORPUS_REPO_ROOT } from './runtime-match.js';
+import { structuralFixtureRoot } from './structural-fixture-root.js';
+export function structuralCoverageConfig() {
+    return mergeConfig({
+        mode: 'enforce',
+        policy: {
+            unknownLocalEffect: 'deny',
+            unparseableShell: 'deny',
+        },
+    }, DEFAULT_CONFIG_V4);
+}
+export async function buildCoverageEvalContexts(contextIds, repoRoot) {
+    const resolvedRepoRoot = path.resolve(repoRoot);
+    const fixtureRoot = structuralFixtureRoot(resolvedRepoRoot);
+    const contexts = [];
+    for (const contextId of contextIds) {
+        if (contextId === 'default') {
+            contexts.push({
+                id: 'default',
+                config: DEFAULT_CONFIG_V3,
+                cwd: `${DEFAULT_CORPUS_REPO_ROOT}/src`,
+                repoRoot: DEFAULT_CORPUS_REPO_ROOT,
+                options: {},
+            });
+            continue;
+        }
+        if (contextId === 'structural') {
+            contexts.push({
+                id: 'structural',
+                config: structuralCoverageConfig(),
+                cwd: fixtureRoot,
+                repoRoot: fixtureRoot,
+                options: {
+                    unknownLocalEffect: 'deny',
+                    unparseableShell: 'deny',
+                    trustedCwd: true,
+                },
+            });
+            continue;
+        }
+        if (contextId === 'audit') {
+            const layered = await loadLayeredConfig(resolvedRepoRoot);
+            contexts.push({
+                id: 'audit',
+                config: layered.config,
+                cwd: resolvedRepoRoot,
+                repoRoot: resolvedRepoRoot,
+                options: {},
+                configProvenance: layered.provenance,
+            });
+        }
+    }
+    return contexts;
+}
+export function stableJsonStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableJsonStringify(entry)).join(',')}]`;
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableJsonStringify(record[key])}`).join(',')}}`;
+}
+export function hashStableJson(value) {
+    return createHash('sha256').update(stableJsonStringify(value)).digest('hex');
+}
+export function resolvedConfigHash(context) {
+    return hashStableJson({
+        mode: context.config.mode,
+        policy: context.config.policy,
+        gates: context.config.gates,
+        classifier: context.config.classifier,
+        options: {
+            unknownLocalEffect: context.options.unknownLocalEffect,
+            unparseableShell: context.options.unparseableShell,
+            trustedCwd: context.options.trustedCwd,
+        },
+        cwd: context.cwd,
+        repoRoot: context.repoRoot,
+        configProvenance: context.configProvenance,
+    });
+}

package/dist/corpus/coverage-matrix.d.ts

@@ -0,0 +1,37 @@
+import type { HookVerdict } from '../core/types.js';
+export declare const COVERAGE_MATRIX_VERSION: 1;
+export declare const COVERAGE_CONTEXT_IDS: readonly ["default", "structural", "audit"];
+export type CoverageContextId = (typeof COVERAGE_CONTEXT_IDS)[number];
+/** Default probe run excludes opt-in `audit`. */
+export declare const DEFAULT_PROBE_CONTEXT_IDS: readonly ["default", "structural"];
+export interface CoverageExpectation {
+    verdict: HookVerdict;
+    reason?: string;
+}
+export interface CoverageMatrixCase {
+    id: string;
+    command: string;
+    tags: string[];
+    expectations?: Partial<Record<CoverageContextId, CoverageExpectation>>;
+    notes?: string;
+}
+export interface CoverageMatrixGroup {
+    id: string;
+    label: string;
+    cases: CoverageMatrixCase[];
+}
+export interface CoverageMatrix {
+    version: typeof COVERAGE_MATRIX_VERSION;
+    groups: CoverageMatrixGroup[];
+}
+export declare class CoverageMatrixSchemaError extends Error {
+    constructor(message: string);
+}
+export declare function parseCoverageMatrix(raw: unknown): CoverageMatrix;
+export declare function loadCoverageMatrix(matrixPath: string): Promise<CoverageMatrix>;
+export declare function flattenCoverageCases(matrix: CoverageMatrix): Array<CoverageMatrixCase & {
+    groupId: string;
+    groupLabel: string;
+}>;
+export declare function defaultCoverageMatrixPath(repoRoot: string): string;
+export declare function assertKnownContextIds(contextIds: string[]): CoverageContextId[];

package/dist/corpus/coverage-matrix.js

@@ -0,0 +1,159 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+export const COVERAGE_MATRIX_VERSION = 1;
+export const COVERAGE_CONTEXT_IDS = ['default', 'structural', 'audit'];
+/** Default probe run excludes opt-in `audit`. */
+export const DEFAULT_PROBE_CONTEXT_IDS = ['default', 'structural'];
+export class CoverageMatrixSchemaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CoverageMatrixSchemaError';
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseVerdict(value, pathLabel) {
+    if (value !== 'allow' && value !== 'allow_flagged' && value !== 'deny_pending_approval') {
+        throw new CoverageMatrixSchemaError(`${pathLabel}.verdict is invalid: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function parseExpectation(value, pathLabel) {
+    if (!isRecord(value)) {
+        throw new CoverageMatrixSchemaError(`${pathLabel} must be an object`);
+    }
+    const expectation = {
+        verdict: parseVerdict(value.verdict, pathLabel),
+    };
+    if (value.reason !== undefined) {
+        if (typeof value.reason !== 'string' || value.reason.trim() === '') {
+            throw new CoverageMatrixSchemaError(`${pathLabel}.reason must be a non-empty string`);
+        }
+        expectation.reason = value.reason;
+    }
+    return expectation;
+}
+function parseCase(raw, groupId, index) {
+    const pathLabel = `group[${groupId}].cases[${index}]`;
+    if (!isRecord(raw)) {
+        throw new CoverageMatrixSchemaError(`${pathLabel} must be an object`);
+    }
+    if (typeof raw.id !== 'string' || raw.id.trim() === '') {
+        throw new CoverageMatrixSchemaError(`${pathLabel}.id must be a non-empty string`);
+    }
+    if (typeof raw.command !== 'string' || raw.command.trim() === '') {
+        throw new CoverageMatrixSchemaError(`${pathLabel}.command must be a non-empty string`);
+    }
+    if (!Array.isArray(raw.tags) || raw.tags.length === 0) {
+        throw new CoverageMatrixSchemaError(`${pathLabel}.tags must be a non-empty array`);
+    }
+    for (const tag of raw.tags) {
+        if (typeof tag !== 'string' || tag.trim() === '') {
+            throw new CoverageMatrixSchemaError(`${pathLabel}.tags entries must be non-empty strings`);
+        }
+    }
+    let expectations;
+    if (raw.expectations !== undefined) {
+        if (!isRecord(raw.expectations)) {
+            throw new CoverageMatrixSchemaError(`${pathLabel}.expectations must be an object`);
+        }
+        expectations = {};
+        for (const [contextId, expectationRaw] of Object.entries(raw.expectations)) {
+            if (!COVERAGE_CONTEXT_IDS.includes(contextId)) {
+                throw new CoverageMatrixSchemaError(`${pathLabel}.expectations.${contextId} is unknown (allowed: ${COVERAGE_CONTEXT_IDS.join(', ')})`);
+            }
+            expectations[contextId] = parseExpectation(expectationRaw, `${pathLabel}.expectations.${contextId}`);
+        }
+    }
+    if (raw.notes !== undefined && typeof raw.notes !== 'string') {
+        throw new CoverageMatrixSchemaError(`${pathLabel}.notes must be a string`);
+    }
+    return {
+        id: raw.id,
+        command: raw.command,
+        tags: raw.tags,
+        expectations,
+        notes: raw.notes,
+    };
+}
+export function parseCoverageMatrix(raw) {
+    if (!isRecord(raw)) {
+        throw new CoverageMatrixSchemaError('coverage matrix root must be an object');
+    }
+    if (raw.version !== COVERAGE_MATRIX_VERSION) {
+        throw new CoverageMatrixSchemaError(`coverage matrix version must be ${COVERAGE_MATRIX_VERSION} (got ${JSON.stringify(raw.version)})`);
+    }
+    if (!Array.isArray(raw.groups) || raw.groups.length === 0) {
+        throw new CoverageMatrixSchemaError('coverage matrix groups must be a non-empty array');
+    }
+    const groupIds = new Set();
+    const caseIds = new Set();
+    const groups = [];
+    for (let groupIndex = 0; groupIndex < raw.groups.length; groupIndex += 1) {
+        const groupRaw = raw.groups[groupIndex];
+        if (!isRecord(groupRaw)) {
+            throw new CoverageMatrixSchemaError(`groups[${groupIndex}] must be an object`);
+        }
+        if (typeof groupRaw.id !== 'string' || groupRaw.id.trim() === '') {
+            throw new CoverageMatrixSchemaError(`groups[${groupIndex}].id must be a non-empty string`);
+        }
+        if (groupIds.has(groupRaw.id)) {
+            throw new CoverageMatrixSchemaError(`duplicate group id: ${groupRaw.id}`);
+        }
+        groupIds.add(groupRaw.id);
+        if (typeof groupRaw.label !== 'string' || groupRaw.label.trim() === '') {
+            throw new CoverageMatrixSchemaError(`groups[${groupIndex}].label must be a non-empty string`);
+        }
+        if (!Array.isArray(groupRaw.cases) || groupRaw.cases.length === 0) {
+            throw new CoverageMatrixSchemaError(`group[${groupRaw.id}].cases must be a non-empty array`);
+        }
+        const cases = [];
+        for (let caseIndex = 0; caseIndex < groupRaw.cases.length; caseIndex += 1) {
+            const testCase = parseCase(groupRaw.cases[caseIndex], groupRaw.id, caseIndex);
+            if (caseIds.has(testCase.id)) {
+                throw new CoverageMatrixSchemaError(`duplicate case id: ${testCase.id}`);
+            }
+            caseIds.add(testCase.id);
+            cases.push(testCase);
+        }
+        groups.push({
+            id: groupRaw.id,
+            label: groupRaw.label,
+            cases,
+        });
+    }
+    return {
+        version: COVERAGE_MATRIX_VERSION,
+        groups,
+    };
+}
+export async function loadCoverageMatrix(matrixPath) {
+    const raw = JSON.parse(await readFile(matrixPath, 'utf8'));
+    return parseCoverageMatrix(raw);
+}
+export function flattenCoverageCases(matrix) {
+    const flat = [];
+    for (const group of matrix.groups) {
+        for (const testCase of group.cases) {
+            flat.push({ ...testCase, groupId: group.id, groupLabel: group.label });
+        }
+    }
+    return flat;
+}
+export function defaultCoverageMatrixPath(repoRoot) {
+    return path.join(repoRoot, 'corpus', 'coverage-matrix.json');
+}
+export function assertKnownContextIds(contextIds) {
+    if (contextIds.length === 0) {
+        throw new CoverageMatrixSchemaError('at least one context is required');
+    }
+    const parsed = [];
+    for (const contextId of contextIds) {
+        if (!COVERAGE_CONTEXT_IDS.includes(contextId)) {
+            throw new CoverageMatrixSchemaError(`unknown context ${JSON.stringify(contextId)} (allowed: ${COVERAGE_CONTEXT_IDS.join(', ')})`);
+        }
+        parsed.push(contextId);
+    }
+    return parsed;
+}

package/dist/corpus/coverage-probe.d.ts

@@ -0,0 +1,91 @@
+import type { ConfigProvenanceEntry } from '../core/config-layers.js';
+import type { ClassifyResult, HookVerdict } from '../core/types.js';
+import { type CoverageEvalContext } from './coverage-contexts.js';
+import { type CoverageContextId, type CoverageExpectation, type CoverageMatrix } from './coverage-matrix.js';
+export declare class CoverageProbeCliError extends Error {
+    constructor(message: string);
+}
+export declare const COVERAGE_PROBE_REPORT_SCHEMA_VERSION: 2;
+export type ClassifyFn = (command: string, evalContext: CoverageEvalContext) => Promise<ClassifyResult>;
+export interface CoverageProbeOptions {
+    repoRoot?: string;
+    matrixPath?: string;
+    contextIds?: CoverageContextId[];
+    filters?: string[];
+    repeat?: number;
+    outputDir?: string;
+    json?: boolean;
+    classifyFn?: ClassifyFn;
+    evalContexts?: CoverageEvalContext[];
+}
+export interface CoverageCaseResult {
+    caseId: string;
+    groupId: string;
+    command: string;
+    commandHash: string;
+    context: CoverageContextId;
+    tags: string[];
+    observeOnly: boolean;
+    expectation?: CoverageExpectation;
+    expectationHash: string | null;
+    actual: {
+        verdict: HookVerdict;
+        reason: string;
+        fingerprint: string;
+    };
+    match: boolean | null;
+}
+export interface CoverageProbeReport {
+    reportSchemaVersion: typeof COVERAGE_PROBE_REPORT_SCHEMA_VERSION;
+    generatedAt: string;
+    packageVersion: string | null;
+    gitSha: string | null;
+    matrixPath: string;
+    matrixHash: string;
+    repeat: number;
+    driftRuns: number;
+    contexts: Array<{
+        id: CoverageContextId;
+        cwd: string;
+        repoRoot: string;
+        resolvedConfigHash: string;
+        configProvenance?: ConfigProvenanceEntry[];
+    }>;
+    summary: {
+        total: number;
+        observeOnly: number;
+        matched: number;
+        mismatched: number;
+        filteredEmpty: boolean;
+        byGroup: Record<string, {
+            total: number;
+            matched: number;
+            mismatched: number;
+            observeOnly: number;
+        }>;
+        byTag: Record<string, {
+            total: number;
+            matched: number;
+            mismatched: number;
+            observeOnly: number;
+        }>;
+    };
+    results: CoverageCaseResult[];
+    mismatches: CoverageCaseResult[];
+}
+export declare const defaultClassifyFn: ClassifyFn;
+export declare function evaluateCoverageMatrix(matrix: CoverageMatrix, options?: CoverageProbeOptions): Promise<CoverageCaseResult[]>;
+export declare function runCoverageProbe(options?: CoverageProbeOptions): Promise<CoverageProbeReport>;
+export declare function formatCoverageProbeSummary(report: CoverageProbeReport): string;
+export declare function parseCoverageProbeCliArgs(argv: string[]): {
+    repoRoot?: string;
+    matrixPath?: string;
+    contextIds?: CoverageContextId[];
+    filters: string[];
+    repeat: number;
+    strict: boolean;
+    outputDir?: string;
+    comparePath?: string;
+    json: boolean;
+};
+export declare function main(argv?: string[]): Promise<number>;