/**
 * S1 / rid=api-diff-report — the three RECORDED sources for `peaks scan api-diff`,
 * plus the candidate name-grep.
 *
 *   1. `.peaks/_runtime/<sid>/rd/mock-plan.md`  (most recent by mtime)
 *   3. the `## API Migration` endpoint list in `.peaks/_runtime/<sid>/txt/*.md`
 *
 * All three are OPTIONAL: absence is reported in the report's `notes`, never
 * silently. `typescript` is a devDependency and is NOT available at runtime, so
 * recorded interfaces are read by the line-based extractor below — its limits
 * are documented on the function and exercised by tests.
 */
import { type CandidateMention, type DocOperation, type InterfaceRole, type RecordedEndpoint, type RecordedInterface } from './api-diff-types.js';
export declare const MAX_CANDIDATE_NAMES = 100;
/**
 * Line-based extractor for recorded `*-api.types.ts` interfaces.
 *
 * INVERTED DEFAULT (QA round 2): a line-based reader cannot tell "this line is
 * not a member" from "I failed to read this member", so the model is not
 * "exact unless I found a reason to suppress". It is the opposite — **an
 * interface is COMPLETE only while every depth-1 line in its body is
 * classified**. The first line the extractor cannot classify makes the whole
 * interface INCOMPLETE, which suppresses every exact line for it and emits one
 * note naming it and the reason.
 *
 * That is what catches, without needing to enumerate them in advance: quoted
 * keys, index signatures, multi-line unions (the continuation line is the
 * unclassifiable one), intersections and mapped types (which never reach a body
 * at all — see `DECLARATION_LIKE`), and nested inline objects.
 *
 * KNOWN LIMITS, stated rather than papered over:
 *   - members are matched at depth 1 only; a nested shape is `object` and makes
 *     the interface incomplete rather than being half-read;
 *   - `extends` is unresolvable without a compiler, so such an interface is
 *     incomplete by construction;
 *   - a regex literal containing a brace would still mis-count (`braceBalance`).
 */
export declare function parseRecordedInterfaces(source: string, file: string): RecordedInterface[];
/**
 * Which half of an operation an interface describes, from the suffix its name
 * carries. `unknown` is a refusal, not a default: diffing an interface against
 * a location it does not describe is how a request field got reported at a
 * response location, and how a response-shaped `*Dto` got reported at the
 * requestBody.
 *
 * Only suffixes that actually name a side are accepted. `Dto` names neither
 * side (a `UserDto` is as likely to be a response), and a bare `Body` does not
 * say which side it belongs to either — `GetThingResponseBody` ends in `Body`.
 * `...RequestBody` still classifies as a request via the `request` suffix. A
 * suffix that carries no information must not receive LESS caution than no
 * suffix at all, so both become `unknown` and are refused with a note.
 */
export declare function roleOf(name: string): InterfaceRole;
/** Locations of `operation` that `role` is allowed to describe. */
export declare function locationsForRole(operation: DocOperation, role: InterfaceRole): string[];
/** Source 1: the most recent `.peaks/_runtime/<sid>/rd/mock-plan.md`. */
export declare function findMockPlan(projectRoot: string): string | null;
/** Pulls the file paths a mock plan records (backticked or whitespace-delimited). */
export declare function extractMockPlanPaths(source: string): string[];
/** Source 2: recorded interface files — mock-plan-named plus the prescribed `src/services/types/*-api.types.ts` layout. */
export declare function findRecordedInterfaceFiles(projectRoot: string, mockPlan: string | null): string[];
/** Source 3: the newest TXT handoff that actually carries an `## API Migration` section. */
export declare function findHandoffWithApiMigration(projectRoot: string): string | null;
/** Parses the `## API Migration` body for `<METHOD> <path>` pairs. */
export declare function parseHandoffEndpoints(source: string): RecordedEndpoint[];
/**
 * Key used to pair a document operation with a recorded interface. Deliberately
 * conservative: only lowercasing, punctuation removal, and one trailing
 * `Response`/`Request`/`Dto`/`Payload`/`Body` strip. Verb stripping (`getUser`
 * -> `user`) was considered and rejected — a false pairing produces a
 * confidently wrong diff, which is worse than the visible false negative of an
 * unpaired interface (design §2.3).
 */
export declare function pairingKey(name: string): string;
export declare function operationKey(operation: DocOperation): string;
/**
 * Greps every candidate name across the consumer's source and non-TS assets.
 * Over-reports (test fixtures, unrelated identifiers) and under-reports (i18n
 * keys, AntD `columns` arrays, monorepo barrels) — the report says so.
 *
 * `exclude` carries the OpenAPI document itself: it is the input, not a change
 * site, and every field name would otherwise match on its own definition line.
 */
export declare function grepCandidateMentions(projectRoot: string, names: readonly string[], exclude?: readonly string[]): {
    mentions: CandidateMention[];
    truncated: boolean;
    hitsTruncated: boolean;
};
/**
 * Canonical endpoint path for comparison: `{id}` and `:id` are the same
 * endpoint spelled two ways, and raw equality reported them as an exact
 * ADDED + REMOVED pair. Parameter NAMES are collapsed too — `/users/{id}` and
 * `/users/{userId}` are one endpoint.
 */
export declare function normalizeEndpointPath(path: string): string;