/**
 * HTTP Route Parser
 *
 * Extracts two complementary sets of data:
 *   1. HTTP CALLS  — fetch/axios/ky/got calls in JS/TS frontend files
 *   2. ROUTE DEFS  — FastAPI / Flask / Django route declarations in Python files
 *
 * These are then matched by `buildHttpEdges()` to create cross-language edges
 * between the frontend files that call an endpoint and the Python handlers that
 * serve it — filling the gap that static import analysis cannot reach.
 *
 * Matching strategy
 * -----------------
 * Routes are normalised to a canonical form before comparison:
 *   - Path parameters are replaced with a placeholder: /items/{id} → /items/:param
 *   - Leading slashes are normalised
 *   - Query strings are stripped from call-site URLs
 *   - Common API prefixes (/api, /api/v1, /v1, …) are tried both with and
 *     without the prefix so that a frontend call to /api/v1/search still matches
 *     a FastAPI router mounted at /search.
 *
 * Confidence levels
 * -----------------
 *   exact   — method + full path match
 *   path    — path matches, method unknown on one side (e.g. bare fetch)
 *   fuzzy   — normalised path matches after prefix stripping
 */
/** An HTTP call found in a JS/TS source file */
export interface HttpCall {
    /** Absolute path of the file containing the call */
    file: string;
    /** HTTP method, upper-cased. 'UNKNOWN' when it cannot be determined. */
    method: string;
    /** URL as written in source — may be a template literal or variable ref */
    url: string;
    /** Normalised, static portion of the URL (params stripped, prefix removed) */
    normalizedUrl: string;
    /** 1-based source line */
    line: number;
    /** axios / fetch / ky / got / custom */
    client: string;
}
/** A route handler found in a Python source file */
export interface RouteDefinition {
    /** Absolute path of the file containing the handler */
    file: string;
    /** HTTP method, upper-cased */
    method: string;
    /** Path pattern as declared (may contain {param} or <param> placeholders) */
    path: string;
    /** Normalised path for matching */
    normalizedPath: string;
    /** Name of the handler function */
    handlerName: string;
    /** fastapi / flask / django / starlette / express / nestjs / nextjs-app etc. */
    framework: string;
    /** 1-based source line */
    line: number;
    /** Request body type extracted from handler signature, e.g. "CreateUserDto" or "z.infer<typeof schema>" */
    requestBodyType?: string;
    /** Response body type extracted from handler return type annotation, e.g. "User[]" or "void" */
    responseType?: string;
    /** How the contract was sourced */
    contractSource: 'annotation' | 'validator' | 'none';
}
/** A resolved cross-language edge */
export interface HttpEdge {
    /** Absolute path of the JS/TS caller file */
    callerFile: string;
    /** Absolute path of the Python handler file */
    handlerFile: string;
    method: string;
    /** Normalised path used for the match */
    path: string;
    call: HttpCall;
    route: RouteDefinition;
    /** How confident the match is */
    confidence: 'exact' | 'path' | 'fuzzy';
}
/**
 * Reduce a URL/path to a comparable canonical form:
 *   - Strip protocol + host if present  (https://example.com/foo → /foo)
 *   - Strip query string and fragment
 *   - Replace path parameters with :param
 *     {id}, :id, <int:id>, <id>  →  :param
 *   - Collapse duplicate slashes
 *   - Remove trailing slash (except root)
 */
export declare function normalizeUrl(raw: string): string;
/**
 * Extract all HTTP calls from a JavaScript or TypeScript source file.
 */
export declare function extractHttpCalls(filePath: string): Promise<HttpCall[]>;
/**
 * Extract all route definitions from a Python source file.
 * Supports FastAPI, Starlette, Flask, and Django (urls.py path/re_path).
 */
export declare function extractRouteDefinitions(filePath: string): Promise<RouteDefinition[]>;
/**
 * Extract all HTTP route definitions from a Java source file.
 * Supports Spring MVC (@RestController / @Controller + @RequestMapping and the
 * shorthand @GetMapping / @PostMapping / …) and JAX-RS (@Path + @GET / @POST).
 */
export declare function extractJavaRouteDefinitions(filePath: string): Promise<RouteDefinition[]>;
/**
 * Match HTTP calls from JS/TS files against route definitions from Python files
 * and return cross-language edges.
 *
 * Pass in pre-extracted calls and routes (so callers can cache them across
 * multiple graph builds without re-parsing).
 */
export declare function buildHttpEdges(calls: HttpCall[], routes: RouteDefinition[]): HttpEdge[];
/**
 * Parse all files in a mixed JS+Python codebase and return HTTP edges.
 * Intended to be called once per graph build and its result merged into
 * the DependencyGraphResult edges.
 */
export declare function extractAllHttpEdges(filePaths: string[]): Promise<{
    calls: HttpCall[];
    routes: RouteDefinition[];
    edges: HttpEdge[];
}>;
/**
 * Extract HTTP route definitions from a TypeScript/JavaScript server file.
 * Handles Express-style, NestJS decorators, and Next.js App Router.
 */
export declare function extractTsRouteDefinitions(filePath: string): Promise<RouteDefinition[]>;
export interface RouteInventory {
    total: number;
    byMethod: Record<string, number>;
    byFramework: Record<string, number>;
    routes: Array<{
        method: string;
        path: string;
        framework: string;
        file: string;
        handler: string;
        requestBodyType?: string;
        responseType?: string;
        contractSource: 'annotation' | 'validator' | 'none';
    }>;
}
/**
 * Build a complete route inventory from all source files.
 * Combines Python routes (extractRouteDefinitions) and TS/JS routes
 * (extractTsRouteDefinitions) into a single summary.
 *
 * @param filePaths - Absolute paths to all source files in the project
 * @param rootDir   - Project root for computing relative paths
 */
export declare function buildRouteInventory(filePaths: string[], rootDir: string): Promise<RouteInventory>;
//# sourceMappingURL=http-route-parser.d.ts.map