/**
 * @fileoverview Schema-aware fuzz testing utilities for MCP definitions.
 * Generates valid, near-miss, and adversarial inputs from Zod schemas,
 * then asserts handler invariants (no crashes, well-formed errors, etc.).
 *
 * Uses `fast-check` for property-based generation. Consumers use
 * `fuzzTool()`, `fuzzResource()`, and `fuzzPrompt()` in their Vitest suites.
 *
 * @module src/testing/fuzz
 */
import type fc from 'fast-check';
import type { ZodObject, ZodRawShape } from 'zod';
import type { AnyPromptDefinition } from '../mcp-server/prompts/utils/promptDefinition.js';
import type { AnyResourceDefinition } from '../mcp-server/resources/utils/resourceDefinition.js';
import type { AnyToolDefinition } from '../mcp-server/tools/utils/toolDefinition.js';
import { type MockContextOptions } from './index.js';
/** Eagerly loads the `fast-check` peer dependency. Called automatically by `fuzzTool`/`fuzzResource`/`fuzzPrompt`. Call manually before using `zodToArbitrary` or `adversarialArbitrary` standalone. */
export declare function loadFc(): Promise<typeof fc>;
/** Options for fuzz test runners. */
export interface FuzzOptions {
    /** Mock context options passed to `createMockContext()`. */
    ctx?: MockContextOptions;
    /** Number of adversarial-input runs. @default 30 */
    numAdversarial?: number;
    /** Number of valid-input runs. @default 50 */
    numRuns?: number;
    /** fast-check seed for reproducibility. */
    seed?: number;
    /** Timeout per individual handler call in ms. @default 5000 */
    timeout?: number;
}
/**
 * Converts a Zod schema to a fast-check `Arbitrary` that produces valid values.
 * Supports the JSON-Schema-serializable subset used by MCP tool/resource schemas.
 *
 * Requires `fast-check` to be loaded first — call from within a `fuzzTool()`/
 * `fuzzResource()`/`fuzzPrompt()` run, or call `loadFc()` before standalone use.
 */
export declare function zodToArbitrary(schema: unknown): fc.Arbitrary<unknown>;
/** Strings designed to trigger injection, encoding, or parsing vulnerabilities. */
export declare const ADVERSARIAL_STRINGS: readonly string[];
/** Generates adversarial values for object fields based on expected type. */
export declare function adversarialArbitrary(): fc.Arbitrary<unknown>;
/**
 * Generates an adversarial variant of a Zod object schema's input.
 * Produces objects that match the key structure but have wrong-type values.
 */
export declare function adversarialObjectArbitrary(schema: ZodObject<ZodRawShape>): fc.Arbitrary<Record<string, unknown>>;
/** Result of a fuzz run, useful for custom assertions. */
export interface FuzzReport {
    /** Inputs that caused the handler to crash (unhandled throw past framework). */
    crashes: Array<{
        input: unknown;
        error: unknown;
    }>;
    /** Responses that leaked stack traces or internal paths. */
    leaks: Array<{
        input: unknown;
        errorText: string;
    }>;
    /** Prototype pollution detected on global objects. */
    prototypePollution: boolean;
    /** Total inputs tested. */
    totalRuns: number;
}
/**
 * Fuzz-tests a tool definition's handler with valid and adversarial inputs.
 * Designed to be called inside a `describe()` / `it()` block.
 *
 * Checks:
 * 1. Valid inputs -> handler runs without crash, output matches schema
 * 2. Adversarial inputs -> Zod rejects or handler errors gracefully
 * 3. No prototype pollution on Object.prototype
 * 4. No stack trace / path leaks in error messages
 * 5. Aborted signals -> handler doesn't hang
 *
 * @returns FuzzReport for additional custom assertions.
 *
 * @example
 * ```ts
 * import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';
 *
 * describe('myTool fuzz', () => {
 *   it('survives fuzz testing', async () => {
 *     const report = await fuzzTool(myTool, { numRuns: 100 });
 *     expect(report.crashes).toHaveLength(0);
 *     expect(report.leaks).toHaveLength(0);
 *     expect(report.prototypePollution).toBe(false);
 *   });
 * });
 * ```
 */
export declare function fuzzTool(def: AnyToolDefinition, options?: FuzzOptions): Promise<FuzzReport>;
/**
 * Fuzz-tests a resource definition's handler with valid and adversarial params.
 *
 * @example
 * ```ts
 * const report = await fuzzResource(myResource, { numRuns: 50 });
 * expect(report.crashes).toHaveLength(0);
 * ```
 */
export declare function fuzzResource(def: AnyResourceDefinition, options?: FuzzOptions): Promise<FuzzReport>;
/**
 * Fuzz-tests a prompt definition's `generate()` with valid and adversarial args.
 *
 * @example
 * ```ts
 * const report = await fuzzPrompt(myPrompt, { numRuns: 50 });
 * expect(report.crashes).toHaveLength(0);
 * ```
 */
export declare function fuzzPrompt(def: AnyPromptDefinition, options?: FuzzOptions): Promise<FuzzReport>;
//# sourceMappingURL=fuzz.d.ts.map