/**
 * API Contract Parser Types and Interfaces
 * Provides data structures for parsing and managing API contract documentation
 *
 * This module defines TypeScript interfaces for:
 * - Individual API endpoints with method, path, schemas, examples
 * - Complete API contracts (collection of endpoints per feature)
 * - Error responses with status codes
 * - Validation reports comparing docs vs implementation
 */
/**
 * Represents a single API endpoint within a contract
 */
export interface ApiEndpoint {
    /** HTTP method (GET, POST, PUT, PATCH, DELETE) */
    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
    /** API path (e.g., "/api/profile" or "/api/budget/:id") */
    path: string;
    /** Brief description of what this endpoint does */
    description: string;
    /** Feature name this endpoint belongs to (e.g., "user-profile", "rbac") */
    feature: string;
    /** Whether authentication is required for this endpoint */
    authentication: boolean;
    /** TypeScript interface or JSON schema for request body (optional) */
    requestSchema?: string;
    /** TypeScript interface or JSON schema for response body (optional) */
    responseSchema?: string;
    /** Example request (bash, curl, or JSON format) (optional) */
    requestExample?: string;
    /** Example response (JSON format) (optional) */
    responseExample?: string;
    /** Array of possible error responses */
    errorResponses?: ErrorResponse[];
    /** Description of path parameters if any */
    pathParameters?: PathParameter[];
    /** Description of query parameters if any */
    queryParameters?: QueryParameter[];
}
/**
 * Represents an error response that can be returned by an endpoint
 */
export interface ErrorResponse {
    /** HTTP status code (401, 403, 404, 500, etc.) */
    statusCode: number;
    /** Human-readable description of the error */
    description: string;
    /** Example error response in JSON format (optional) */
    example?: string;
}
/**
 * Describes a path parameter in an endpoint path
 */
export interface PathParameter {
    /** Parameter name (e.g., "id", "featureId") */
    name: string;
    /** Parameter type (string, number, uuid, etc.) */
    type: string;
    /** Description of what this parameter represents */
    description: string;
    /** Whether this parameter is required */
    required: boolean;
}
/**
 * Describes a query parameter accepted by an endpoint
 */
export interface QueryParameter {
    /** Parameter name (e.g., "limit", "offset", "sort") */
    name: string;
    /** Parameter type (string, number, boolean, etc.) */
    type: string;
    /** Description of what this parameter does */
    description: string;
    /** Whether this parameter is required */
    required: boolean;
    /** Default value if not provided (optional) */
    default?: string;
}
/**
 * Represents a complete API contract for a feature
 * Contains all endpoints and metadata for a specific feature's API
 */
export interface ApiContract {
    /** Feature name (derived from directory name) */
    feature: string;
    /** Base URL prefix for all endpoints in this contract (e.g., "/api/profile") */
    baseUrl: string;
    /** Description of authentication requirements */
    authentication: string;
    /** Expected Content-Type header (application/json, etc.) */
    contentType: string;
    /** All API endpoints in this contract */
    endpoints: ApiEndpoint[];
    /** File path to the source contract file */
    filePath: string;
    /** Timestamp when this contract was last parsed */
    parsedAt?: Date;
}
/**
 * Represents the result of validating documented contracts against actual implementations
 */
export interface ValidationReport {
    /** Feature name being validated */
    feature: string;
    /** Number of endpoints that have matching implementations */
    matched: number;
    /** Endpoints documented but missing implementations */
    missing: MissingEndpoint[];
    /** Endpoints implemented but not documented */
    undocumented: UndocumentedEndpoint[];
    /** Endpoints with method mismatches between docs and code */
    methodMismatches: MethodMismatch[];
    /** Timestamp when validation was performed */
    validatedAt?: Date;
}
/**
 * Represents an endpoint that is documented but not implemented
 */
export interface MissingEndpoint {
    /** HTTP method specified in documentation */
    method: string;
    /** API path specified in documentation */
    path: string;
    /** Expected location where this endpoint should be implemented */
    expectedFile: string;
}
/**
 * Represents an endpoint that is implemented but not documented
 */
export interface UndocumentedEndpoint {
    /** HTTP method found in code */
    method: string;
    /** API path found in code */
    path: string;
    /** File path where this endpoint is implemented */
    foundIn: string;
}
/**
 * Represents a mismatch between documented and implemented endpoint methods
 */
export interface MethodMismatch {
    /** API path */
    path: string;
    /** HTTP method specified in documentation */
    documentedMethod: string;
    /** HTTP method found in actual implementation */
    implementedMethod: string;
    /** File path where the implementation is located */
    file: string;
}
/**
 * Represents a collection of API contracts, typically all contracts in the system
 */
export interface ApiContractCollection {
    /** Array of all API contracts */
    contracts: ApiContract[];
    /** Total count of endpoints across all contracts */
    totalEndpoints: number;
    /** List of unique features found */
    features: string[];
    /** Timestamp when this collection was assembled */
    collectedAt?: Date;
}
/**
 * Represents the result of a search operation across API endpoints
 */
export interface SearchResult {
    /** Array of matching endpoints */
    endpoints: Array<ApiEndpoint & {
        matchScore: number;
    }>;
    /** Number of results found */
    count: number;
    /** Search query that was executed */
    query: string;
    /** Optional feature filter that was applied */
    feature?: string;
}
/**
 * Represents a cache entry for parsed contracts
 */
export interface CacheEntry<T> {
    /** The cached data */
    data: T;
    /** Timestamp when this data was cached */
    cachedAt: Date;
    /** Time-to-live in milliseconds */
    ttl: number;
}
/**
 * Options for parsing API contracts
 */
export interface ParseOptions {
    /** Whether to extract examples from code blocks */
    includeExamples?: boolean;
    /** Whether to extract error responses */
    includeErrors?: boolean;
    /** Whether to extract parameter descriptions */
    includeParameters?: boolean;
    /** Custom path resolver for relative paths */
    basePath?: string;
}
/**
 * Options for searching endpoints
 */
export interface SearchOptions {
    /** Feature to filter by (optional) */
    feature?: string;
    /** HTTP method to filter by (optional) */
    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
    /** Whether search should be case-sensitive */
    caseSensitive?: boolean;
    /** Maximum number of results to return */
    limit?: number;
    /** Whether to apply relevance ranking */
    ranked?: boolean;
}
/**
 * Options for validation operations
 */
export interface ValidationOptions {
    /** Feature to validate (optional - if not provided, validates all) */
    feature?: string;
    /** Root path of the codebase to search for implementations */
    codebaseRoot: string;
    /** File patterns to search for route implementations */
    routePatterns?: string[];
    /** Whether to check for method mismatches */
    checkMethodMismatches?: boolean;
}
/**
 * Represents a parsing error that occurred while processing a contract file
 */
export interface ParsingError {
    /** File path that had the error */
    filePath: string;
    /** Error message */
    message: string;
    /** Line number where error occurred (optional) */
    lineNumber?: number;
    /** Severity level (warn, error) */
    severity: 'warn' | 'error';
}
/**
 * Represents the result of parsing a single contract file
 */
export interface ParseResult {
    /** Successfully parsed contract (if parsing succeeded) */
    contract?: ApiContract;
    /** Array of errors encountered during parsing */
    errors: ParsingError[];
    /** Whether parsing completed successfully */
    success: boolean;
    /** Number of endpoints extracted */
    endpointCount: number;
}
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
export type ValidationSeverity = 'warn' | 'error';
/**
 * Generic cache manager interface
 */
export interface CacheManager<T> {
    get(key: string): T | null;
    set(key: string, value: T, ttl?: number): void;
    clear(): void;
    has(key: string): boolean;
    size(): number;
}
/**
 * Recursively discover all api-contracts.md files under a given directory
 * @param docsPath - Root path to search (typically docs/features)
 * @param useCache - Whether to use cached results (default: true)
 * @returns Array of absolute file paths to api-contracts.md files
 */
export declare function discoverContractFiles(docsPath: string, useCache?: boolean): Promise<string[]>;
/**
 * Read contract file content asynchronously
 * Uses cache to avoid re-reading the same file
 * @param filePath - Path to the contract file
 * @param useCache - Whether to use cached results (default: true)
 * @returns File content as string, or null if file cannot be read
 */
export declare function readContractFile(filePath: string, useCache?: boolean): Promise<string | null>;
/**
 * Read multiple contract files in parallel
 * @param filePaths - Array of file paths to read
 * @param useCache - Whether to use cached results (default: true)
 * @returns Object mapping file paths to their contents
 */
export declare function readContractFiles(filePaths: string[], useCache?: boolean): Promise<Record<string, string | null>>;
/**
 * Clear the contract file cache
 * Useful for forcing a refresh of all cached data
 */
export declare function clearContractCache(): void;
/**
 * Invalidate cache for a specific file
 * Call this after a contract file has been updated
 * @param filePath - Path to the file to invalidate
 */
export declare function invalidateContractFileCache(filePath: string): void;
/**
 * Get information about current cache state
 * Useful for debugging and monitoring cache effectiveness
 * @returns Cache statistics
 */
export declare function getCacheStats(): {
    cachedFiles: number;
    hasDiscoveryCache: boolean;
    cacheSize: {
        files: number;
        discoveryCount: number;
    };
};
/**
 * Parse a complete API contract markdown file
 * @param filePath - Path to the contract file
 * @param content - Markdown content
 * @param options - Parsing options
 * @returns ParseResult with contract or errors
 */
export declare function parseContractFile(filePath: string, content?: string, options?: ParseOptions): Promise<ParseResult>;
/**
 * Parse all contract files in a directory
 * @param docsPath - Path to docs/features directory
 * @param options - Parsing options
 * @returns Array of parse results
 */
export declare function parseAllContracts(docsPath: string, options?: ParseOptions): Promise<ParseResult[]>;
/**
 * Get all successfully parsed contracts
 * @param docsPath - Path to docs/features directory
 * @param options - Parsing options
 * @returns Array of API contracts
 */
export declare function getAllContracts(docsPath: string, options?: ParseOptions): Promise<ApiContract[]>;
/**
 * Represents a scored search result for an endpoint
 */
interface ScoredEndpoint extends ApiEndpoint {
    matchScore: number;
}
/**
 * Search endpoints by keyword across path, method, description, and feature name
 * Search is case-insensitive and supports partial matching
 * Results are ranked by relevance (highest scores first)
 *
 * @param contracts - Array of API contracts to search
 * @param query - Search query string
 * @param options - Optional search options
 * @returns Array of matching endpoints sorted by relevance, empty if no matches
 */
export declare function searchEndpoints(contracts: ApiContract[], query: string, options?: SearchOptions): ScoredEndpoint[];
/**
 * Filter endpoints by feature name
 * Search is case-insensitive
 *
 * @param contracts - Array of API contracts to filter
 * @param feature - Feature name to filter by
 * @returns Array of endpoints from the specified feature, empty if not found
 */
export declare function filterByFeature(contracts: ApiContract[], feature: string): ApiEndpoint[];
/**
 * Find a specific endpoint by path and optional HTTP method
 * If method is not provided, returns the first endpoint matching the path
 * Search is case-insensitive for path comparison
 *
 * @param contracts - Array of API contracts to search
 * @param path - API path to find (e.g., "/api/profile")
 * @param method - Optional HTTP method to match
 * @returns Matching ApiEndpoint or null if not found
 */
export declare function findEndpoint(contracts: ApiContract[], path: string, method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'): ApiEndpoint | null;
/**
 * Validate API implementation against documentation
 * Compares documented contracts with actual route implementations
 *
 * @param contracts - Array of API contracts from documentation
 * @param feature - Feature name to validate (optional - validates all if not specified)
 * @param codebaseRoot - Root directory of the codebase
 * @returns Validation report with matched, missing, undocumented, and mismatched endpoints
 */
export declare function validateFeature(contracts: ApiContract[], feature: string | undefined, codebaseRoot: string): Promise<ValidationReport>;
/**
 * Validate all features in the codebase
 * Runs validation for each feature separately and returns individual reports
 *
 * @param contracts - Array of API contracts
 * @param codebaseRoot - Root directory of the codebase
 * @returns Array of validation reports, one per feature
 */
export declare function validateAllFeatures(contracts: ApiContract[], codebaseRoot: string): Promise<ValidationReport[]>;
export {};
//# sourceMappingURL=api-contracts-parser.d.ts.map