import { type Stats } from "node:fs";
export declare const FRONTEND_COMPONENT_EXTENSIONS: readonly string[];
/** Matches package-private source/build internals after path normalization. */
export declare const PACKAGE_INTERNAL_RE: RegExp;
export type CtxReadGuardrailKind = "file" | "directory" | "missing" | "packageInternal" | "frontendFallback" | "invalid";
export interface CtxReadGuardrailOutcome {
    ok: boolean;
    kind: CtxReadGuardrailKind;
    normalizedPath?: string;
    reason: string;
    fallbackHint?: string;
}
export interface GuardCtxReadOptions {
    cwd: string;
    allowDirectory?: boolean;
    allowPackageInternals?: boolean;
    frontendExtensions?: readonly string[];
    /** Component file extensions for frontend fallback (e.g. [".tsx", ".jsx"]). */
    componentExtensions?: readonly string[];
    /** Barrel/index file extensions (e.g. [".ts", ".tsx", ".js", ".jsx"]). */
    indexExtensions?: readonly string[];
    /** When true, emit dir/stem/stem.ext directory-module self-file candidates. */
    directoryModuleSelfFile?: boolean;
    /** Glob-ish path prefixes that gate frontend fallback (e.g. ["components/ui/"]). */
    frontendPathTriggers?: readonly string[];
    /** Injectable filesystem hooks for tests. */
    exists?: (path: string) => boolean;
    stat?: (path: string) => Pick<Stats, "isDirectory" | "isFile">;
    realpath?: (path: string) => string;
}
/**
 * Validate and normalize a path before attempting an expensive ctx_read /
 * lean-ctx bridge read. The returned outcome is intentionally concise so a
 * caller can show it directly as a fallback hint instead of surfacing noisy
 * bridge errors like "Is a directory" or package-internal file-not-found traces.
 */
export declare function guardCtxReadPath(rawPath: string, opts: GuardCtxReadOptions): CtxReadGuardrailOutcome;