/**
 * @fileoverview Lint rules for the declarative `errors[]` contract on tool and
 * resource definitions. Validates structure (codes, reasons), uniqueness,
 * and (when a contract is present) cross-checks handler bodies for thrown
 * codes that aren't declared.
 * @module src/linter/rules/error-contract-rules
 */
import type { LintDefinitionType, LintDiagnostic } from '../types.js';
/**
 * Validates the `errors[]` contract on a tool/resource definition.
 * Checks:
 *   - `errors` is an array
 *   - each entry is an object with required `code`, `reason`, `when`, `recovery`
 *   - `code` is a real `JsonRpcErrorCode` value
 *   - `reason` is snake_case and unique within the contract
 *   - `recovery` is non-empty and ≥ 5 words (forcing function for thoughtful
 *     agent guidance — placeholders like "Try again." get flagged)
 *   - `retryable` (when present) is a boolean
 */
export declare function lintErrorContract(errors: unknown, definitionType: LintDefinitionType, definitionName: string): LintDiagnostic[];
/**
 * Cross-checks a definition's declared `errors[]` contract against the codes
 * that appear textually in its `handler` body. Fires only when a contract is
 * present — definitions without an `errors[]` field are silently skipped.
 *
 * **Two distinct findings:**
 *
 * - `error-contract-conformance` — handler throws a non-baseline code that
 *   isn't in the contract. Suggests adding it to `errors[]`.
 * - `error-contract-prefer-fail` — handler throws a code that IS in the
 *   contract directly (via factory or `new McpError`) instead of via
 *   `ctx.fail(reason, …)`. Encourages routing through the typed helper so
 *   observers see consistent `data.reason` values.
 *
 * **Baseline codes** (`InternalError`, `ServiceUnavailable`, `Timeout`,
 * `ValidationError`, `SerializationError`) are skipped — they bubble from
 * anywhere and don't need to be enumerated per-tool.
 *
 * Heuristic only: scans handler source text for `new McpError(JsonRpcErrorCode.X)`
 * constructions and `throw factory()` calls — comparisons (`=== JsonRpcErrorCode.X`)
 * and `case JsonRpcErrorCode.X:` labels that merely reference a code are not counted.
 * Codes thrown from called services are invisible — so this is always a warning,
 * never an error.
 */
export declare function lintErrorContractConformance(def: {
    handler?: unknown;
    errors?: unknown;
}, definitionType: LintDefinitionType, definitionName: string): LintDiagnostic[];
//# sourceMappingURL=error-contract-rules.d.ts.map