/**
 * @module tools/repo/api-surface
 * @packageBoundary @qulib/core
 *
 * Evidence-only API surface discovery. Three tiers of confidence:
 *   Tier1 — OpenAPI / Swagger spec files (YAML or JSON). Only reads `summary` and
 *            `parameters` from a real spec; never fabricates endpoints.
 *   Tier2 — Framework route files: Next.js App-Router `route.ts` exports,
 *            Next.js Pages `pages/api/`, Express router calls from RepoAnalysis.routes,
 *            Fastify `fastify.{method}`, Hono `app.{method}`, NestJS decorators.
 *   Tier3 — Opt-in heuristics. Currently: tRPC router definition files.
 *            Only activated when `options.enableTier3 === true`.
 *
 * Every endpoint carries:
 *   sourceFile  — repo-relative file path that evidence was read from
 *   sourceTier  — 'openapi' | 'framework' | 'heuristic'
 *   confidence  — 'high' | 'medium' | 'low'
 *
 * NEVER invents endpoints or parameters. When a spec file cannot be parsed,
 * or a file pattern does not clearly indicate a route, the file is skipped.
 */
import type { RepoAnalysis } from '../../schemas/repo-analysis.schema.js';
export interface DiscoveredEndpoint {
    /** HTTP method inferred from the source — 'unknown' when ambiguous */
    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'unknown';
    /** Path as extracted from source — may contain framework-specific params like [id] or :id */
    path: string;
    /** Repo-relative file path the evidence was read from */
    sourceFile: string;
    /** Discovery tier */
    sourceTier: 'openapi' | 'framework' | 'heuristic';
    /** Evidence confidence */
    confidence: 'high' | 'medium' | 'low';
    /** Human-readable summary from spec, if available (Tier1 only) */
    summary?: string;
    /** Parameter names extracted from spec (Tier1 only; never fabricated) */
    parameterNames?: string[];
}
export interface ApiSurface {
    discoveredAt: string;
    repoPath: string;
    endpoints: DiscoveredEndpoint[];
    /** Number of OpenAPI/Swagger spec files found and successfully parsed */
    openApiSpecsFound: number;
    /** Tier3 heuristics were enabled */
    tier3Enabled: boolean;
}
export interface DiscoverApiSurfaceOptions {
    /** Enable Tier3 heuristic discovery (default false — opt-in) */
    enableTier3?: boolean;
}
export declare function discoverApiSurface(repoPath: string, options?: DiscoverApiSurfaceOptions): Promise<ApiSurface>;
/**
 * Variant that also incorporates RepoAnalysis.routes (Express routes already
 * extracted by scanRepo). Use this when you already have a RepoAnalysis to avoid
 * double-reading files.
 */
export declare function discoverApiSurfaceWithRepo(repoPath: string, repo: RepoAnalysis, options?: DiscoverApiSurfaceOptions): Promise<ApiSurface>;
//# sourceMappingURL=api-surface.d.ts.map