/**
 * Golden Output Testing - Capture and compare expected tool outputs.
 *
 * Golden outputs provide a reference for expected tool behavior,
 * enabling detection of semantic changes that schema validation
 * might miss (e.g., different category names, changed formats).
 */
import type { MCPToolCallResult } from '../transport/types.js';
/**
 * Comparison modes for golden output validation.
 */
export type GoldenComparisonMode = 'exact' | 'structural' | 'semantic';
/**
 * Content type of the golden output.
 */
export type GoldenContentType = 'json' | 'markdown' | 'text';
/**
 * Severity of golden output drift.
 */
export type GoldenDriftSeverity = 'none' | 'info' | 'warning' | 'breaking';
/**
 * A captured golden output for a tool.
 */
export interface GoldenOutput {
    /** Tool name this golden output is for */
    toolName: string;
    /** When the golden output was captured */
    capturedAt: string;
    /** Input arguments used to generate this output */
    inputArgs: Record<string, unknown>;
    /** The captured output */
    output: {
        /** Raw output string */
        raw: string;
        /** Detected content type */
        contentType: GoldenContentType;
        /** Hash of the raw content for quick comparison */
        contentHash: string;
        /** Inferred JSON structure (if JSON content) */
        structure?: Record<string, unknown>;
        /** Extracted key-value pairs for semantic comparison */
        keyValues?: Record<string, unknown>;
    };
    /** Tolerance configuration for comparisons */
    tolerance: {
        /** Comparison mode to use */
        mode: GoldenComparisonMode;
        /** JSONPath patterns for values that are allowed to change */
        allowedDrift: string[];
        /** Whether to normalize timestamps before comparison */
        normalizeTimestamps?: boolean;
        /** Whether to normalize UUIDs before comparison */
        normalizeUuids?: boolean;
    };
    /** Optional description of what this golden output represents */
    description?: string;
    /** Schema version for future compatibility */
    version: number;
}
/**
 * Result of comparing current output against golden.
 */
export interface GoldenComparisonResult {
    /** Tool name */
    toolName: string;
    /** Whether the comparison passed */
    passed: boolean;
    /** Drift severity (if any) */
    severity: GoldenDriftSeverity;
    /** Comparison mode used */
    mode: GoldenComparisonMode;
    /** When the golden was captured */
    goldenCapturedAt: string;
    /** Detected differences */
    differences: GoldenDifference[];
    /** Summary of the comparison */
    summary: string;
}
/**
 * A single difference between golden and current output.
 */
export interface GoldenDifference {
    /** Type of difference */
    type: 'added' | 'removed' | 'changed' | 'type_changed' | 'value_changed';
    /** JSONPath or location of the difference */
    path: string;
    /** Expected value (from golden) */
    expected?: unknown;
    /** Actual value (from current) */
    actual?: unknown;
    /** Whether this difference is allowed by tolerance config */
    allowed: boolean;
    /** Description of the change */
    description: string;
}
/**
 * Options for saving a golden output.
 */
export interface GoldenSaveOptions {
    /** Comparison mode to use for this golden */
    mode?: GoldenComparisonMode;
    /** JSONPath patterns for allowed drift */
    allowedDrift?: string[];
    /** Whether to normalize timestamps */
    normalizeTimestamps?: boolean;
    /** Whether to normalize UUIDs */
    normalizeUuids?: boolean;
    /** Description of the golden output */
    description?: string;
}
/**
 * Golden output storage/file structure.
 */
export interface GoldenOutputStore {
    /** Schema version */
    version: number;
    /** All stored golden outputs */
    outputs: GoldenOutput[];
    /** When the store was last updated */
    lastUpdated: string;
}
/**
 * Get the path to the golden output store file.
 */
export declare function getGoldenStorePath(outputDir?: string): string;
/**
 * Load the golden output store from disk.
 */
export declare function loadGoldenStore(storePath: string): GoldenOutputStore;
/**
 * Save the golden output store to disk.
 */
export declare function saveGoldenStore(store: GoldenOutputStore, storePath: string): void;
/**
 * Create a golden output from a tool response.
 */
export declare function createGoldenOutput(toolName: string, inputArgs: Record<string, unknown>, response: MCPToolCallResult, options?: GoldenSaveOptions): GoldenOutput;
/**
 * Save a golden output to the store.
 */
export declare function saveGoldenOutput(golden: GoldenOutput, storePath: string): void;
/**
 * Get a golden output for a specific tool.
 */
export declare function getGoldenOutput(toolName: string, storePath: string, inputArgs?: Record<string, unknown>): GoldenOutput | undefined;
/**
 * List all golden outputs in the store.
 */
export declare function listGoldenOutputs(storePath: string): GoldenOutput[];
/**
 * Delete a golden output from the store.
 */
export declare function deleteGoldenOutput(toolName: string, storePath: string, inputArgs?: Record<string, unknown>): boolean;
/**
 * Compare current output against a golden output.
 */
export declare function compareWithGolden(golden: GoldenOutput, currentResponse: MCPToolCallResult): GoldenComparisonResult;
//# sourceMappingURL=golden-output.d.ts.map