import { HttpMethod } from '../types';
/**
 * API route segment types for file-system convention
 */
export type ApiSegmentType = 'static' | 'dynamic' | 'catchAll' | 'optional' | 'group' | 'private';
/**
 * Parsed API segment from filename or directory
 */
export interface ParsedApiSegment {
    /** Type of segment */
    readonly type: ApiSegmentType;
    /** Segment name for URL path */
    readonly name: string;
    /** Parameter name for dynamic segments */
    readonly paramName?: string;
    /** Whether this segment is optional */
    readonly isOptional: boolean;
    /** Original filename/dirname before parsing */
    readonly original: string;
    /** Group modifier details (for group type) */
    readonly groupModifier?: GroupModifier;
}
/**
 * Group modifier extracted from (name) folders
 */
export interface GroupModifier {
    /** Original group name */
    readonly name: string;
    /** Modifier type */
    readonly type: GroupModifierType;
    /** Associated value (e.g., role name for 'role' type) */
    readonly value?: string;
}
/**
 * Types of group modifiers
 */
export type GroupModifierType = 'public' | 'auth' | 'role' | 'permission' | 'scope' | 'custom';
/**
 * File type classification for API files
 */
export type ApiFileType = 'collection' | 'resource' | 'action' | 'schema' | 'middleware' | 'access' | 'ignored';
/**
 * Scanned API route from file system
 */
export interface ScannedApiRoute {
    /** Absolute file path */
    readonly filePath: string;
    /** Path relative to scan root */
    readonly relativePath: string;
    /** Generated URL path (e.g., /api/users/:id) */
    readonly urlPath: string;
    /** Parsed path segments */
    readonly segments: readonly ParsedApiSegment[];
    /** Supported HTTP methods */
    readonly httpMethods: readonly HttpMethod[];
    /** File type classification */
    readonly fileType: ApiFileType;
    /** Extracted parameter names */
    readonly paramNames: readonly string[];
    /** Primary resource name */
    readonly resourceName: string;
    /** Parent resource names (for nested routes) */
    readonly parentResources: readonly string[];
    /** Group modifiers from parent folders */
    readonly groupModifiers: readonly GroupModifier[];
    /** Whether this route has a schema file */
    readonly hasSchema: boolean;
    /** Whether this route has middleware */
    readonly hasMiddleware: boolean;
    /** Whether this route has access override */
    readonly hasAccessOverride: boolean;
    /** Nesting depth */
    readonly depth: number;
}
/**
 * Scanner configuration options
 */
export interface ApiScannerConfig {
    /** File extensions to consider as API routes */
    readonly extensions: readonly string[];
    /** Glob patterns to ignore */
    readonly ignorePatterns: readonly string[];
    /** Base URL prefix (default: /api) */
    readonly baseUrl: string;
    /** Enable parallel scanning */
    readonly parallel: boolean;
    /** Cache discovery results */
    readonly cacheResults: boolean;
    /** Custom file type classifier */
    readonly classifyFile?: (filename: string) => ApiFileType;
    /** Custom group modifier parser */
    readonly parseGroupModifier?: (name: string) => GroupModifier;
}
/**
 * Default scanner configuration
 */
export declare const DEFAULT_API_SCANNER_CONFIG: ApiScannerConfig;
/**
 * Parse a filename or directory name into an API segment
 */
export declare function parseApiSegment(name: string): ParsedApiSegment;
/**
 * Parse a group modifier from a group name
 */
export declare function parseGroupModifier(name: string): GroupModifier;
/**
 * Classify a file based on its name
 */
export declare function classifyApiFile(filename: string): ApiFileType;
/**
 * Get HTTP methods for a file type and filename
 */
export declare function getHttpMethods(fileType: ApiFileType, filename: string): readonly HttpMethod[];
/**
 * Parse a directory path into API segments
 */
export declare function parseDirectoryPath(dirPath: string): readonly ParsedApiSegment[];
/**
 * Convert parsed segments to URL path
 */
export declare function segmentsToUrlPath(segments: readonly ParsedApiSegment[], baseUrl?: string): string;
/**
 * Extract parameter names from segments
 */
export declare function extractParamNames(segments: readonly ParsedApiSegment[]): readonly string[];
/**
 * Extract resource name from path segments
 */
export declare function extractResourceName(segments: readonly ParsedApiSegment[]): string;
/**
 * Extract parent resource names from nested path
 */
export declare function extractParentResources(segments: readonly ParsedApiSegment[]): readonly string[];
/**
 * Extract group modifiers from segments
 */
export declare function extractGroupModifiers(segments: readonly ParsedApiSegment[]): readonly GroupModifier[];
/**
 * Scan API routes from file system
 *
 * @param rootDir - Root directory to scan
 * @param config - Scanner configuration
 * @returns Array of scanned API routes
 */
export declare function scanApiRoutes(rootDir: string, config?: Partial<ApiScannerConfig>): Promise<ScannedApiRoute[]>;
/**
 * Scan API routes with caching
 */
export declare function scanApiRoutesCached(rootDir: string, config?: Partial<ApiScannerConfig>, maxAge?: number): Promise<ScannedApiRoute[]>;
/**
 * Clear scanner cache
 */
export declare function clearApiScannerCache(): void;
/**
 * Invalidate cache for specific directory
 */
export declare function invalidateApiScannerCache(rootDir: string): void;
/**
 * Scanner statistics
 */
export interface ApiScannerStats {
    /** Total routes discovered */
    readonly totalRoutes: number;
    /** Routes by HTTP method */
    readonly routesByMethod: Record<HttpMethod, number>;
    /** Routes by file type */
    readonly routesByFileType: Record<ApiFileType, number>;
    /** Routes with schema files */
    readonly routesWithSchema: number;
    /** Routes with middleware */
    readonly routesWithMiddleware: number;
    /** Routes with access override */
    readonly routesWithAccessOverride: number;
    /** Maximum depth */
    readonly maxDepth: number;
    /** Unique resources */
    readonly uniqueResources: readonly string[];
    /** Group modifiers used */
    readonly groupModifiers: readonly string[];
}
/**
 * Calculate statistics for scanned routes
 */
export declare function calculateApiScannerStats(routes: ScannedApiRoute[]): ApiScannerStats;
/**
 * Type guard for ScannedApiRoute
 */
export declare function isScannedApiRoute(value: unknown): value is ScannedApiRoute;
/**
 * Type guard for GroupModifier
 */
export declare function isGroupModifier(value: unknown): value is GroupModifier;