/**
 * Canonical identity key for the `list`/`list_files` cross-reference: a file's
 * realpath, falling back to the input path when realpath fails (orphaned or
 * raw-data entries). Matching ingested DB entries against scanned files by this
 * key recognizes the same physical file across symlinked spellings (prefix or
 * alias). Storage, lookup, and display still use the normal resolve() path —
 * realpath here is the file-identity comparison, not a user-facing value.
 */
export declare function realpathForMatch(filePath: string): Promise<string>;
/**
 * Canonical form of one explicitly requested path: its parent chain resolved
 * through symbolic links, with the final component appended verbatim. `null` when
 * the parent chain cannot be resolved at all — absent, or a directory this
 * process may not traverse — which a caller must treat as "not contained",
 * because telling those cases apart would report the state of paths outside its
 * configured roots.
 *
 * Only the parent chain is resolved, because the requested entry itself is judged
 * by {@link classifyRequestedPath}'s `lstat`: a symbolic link named directly
 * inside a root is an in-root entry that is refused as a link, not a path to be
 * reported by whatever it points at.
 *
 * `realpath` here is the containment (security) boundary, the same role it plays
 * in `DocumentParser.validateFilePath` — never a spelling anything is stored,
 * looked up, or displayed under. Those stay `resolve()`-only.
 */
export declare function canonicalizeRequestedPath(path: string): Promise<string | null>;
/** Why the collect predicates below refuse a path. */
export type ScanRejection = 
/** A symbolic link, which is never followed. */
'symlink'
/** Under the database or cache directory, or a file matching an `IGNORE_PATHS` pattern. */
 | 'excluded'
/** A regular file whose extension is not a supported document type. */
 | 'unsupported'
/** Neither a regular file nor a directory (socket, FIFO, device, …). */
 | 'irregular';
/** What a path is, once the collect predicates have judged it. */
export type ScanEntryKind = 'file' | 'directory' | ScanRejection;
/** What the collect predicates refuse as `'excluded'`. */
export interface ScanExclusion {
    /** Database and cache directories, each with a trailing separator. */
    prefixes: readonly string[];
    ignore?: {
        /** Configured roots in both spellings, which `patterns` are relative to. */
        roots: readonly string[];
        patterns: readonly string[];
    };
}
export declare function buildScanExclusion(input: {
    dbPath: string;
    cacheDir: string;
    roots: {
        baseDirs: readonly string[];
        rawBaseDirs: readonly string[];
    };
    ignorePatterns: readonly string[] | undefined;
}): ScanExclusion;
/** The `Dirent` / `Stats` subset the collect predicates read. */
interface EntryTypeFacts {
    isSymbolicLink(): boolean;
    isDirectory(): boolean;
    isFile(): boolean;
}
/**
 * The collect predicates of {@link bfsCollectSupportedFiles} as one decision,
 * so a discovered entry and an explicitly requested path are judged by the same
 * rules rather than by two implementations that drift.
 *
 * Evaluation order is part of the contract: a symbolic link is reported as a
 * link even under an excluded prefix, a directory needs no extension test, and
 * ignore patterns apply to supported files only.
 *
 * `platform` is a parameter so the Windows exclusion semantics are provable on
 * a POSIX host. Both `Dirent` and `Stats` satisfy {@link EntryTypeFacts}.
 */
export declare function classifyScanEntry(fullPath: string, entry: EntryTypeFacts, exclusion: ScanExclusion, platform?: NodeJS.Platform): ScanEntryKind;
/**
 * Classify one explicitly requested path with {@link classifyScanEntry}, so a
 * path a caller names is subject to the same predicates as a path the walker
 * discovers.
 *
 * `lstat` rather than `stat`, so a symbolic link is reported as a link instead of
 * as whatever it points at; and `lstat` rather than any read, so a caller can
 * refuse the path before its bytes cost anything — reading a FIFO blocks forever,
 * and reading through a link reaches outside the configured roots.
 *
 * Any stat failure is `'missing'`: an unreachable path and an absent one are the
 * same non-answer to "what is here".
 */
export declare function classifyRequestedPath(path: string, exclusion: ScanExclusion, platform?: NodeJS.Platform): Promise<ScanEntryKind | 'missing'>;
/** A directory that could not be read during the scan. */
export interface UnreadableDir {
    dirPath: string;
    /** Node error `code` (e.g. `EACCES`), or `'UNKNOWN'` when unavailable. */
    code: string;
}
/** Structured result of a bounded directory scan. */
export interface DirScanResult {
    /** Supported files found under the root, in BFS-discovery order (unsorted). */
    files: string[];
    /** Directories skipped because `readdir` failed (caller decides how to warn). */
    unreadableDirs: UnreadableDir[];
    /**
     * Each entry is the first unvisited directory of a branch pruned for
     * exceeding `maxDepth` — the directory that was reached but never read. That
     * path and every descendant of it is unobserved by this scan; its ancestors
     * and fully visited siblings are not listed.
     */
    depthLimitedDirs: string[];
    /** Full paths of directory entries skipped because they are symbolic links. */
    skippedSymlinks: string[];
    /** True if any branch was pruned for exceeding `maxDepth`. */
    depthLimited: boolean;
}
export interface BfsCollectOptions {
    /** Traversal bound; defaults to {@link MAX_SCAN_DEPTH}. */
    maxDepth?: number;
    /** Absolute prefixes to restrict traversal and collection to. */
    scope?: string[] | undefined;
    /** Selects case sensitivity of the exclusion comparison; defaults to the host. */
    platform?: NodeJS.Platform;
}
/**
 * Bounded BFS scan of a single root, depth counted from `rootPath` itself.
 * Symlinks are never followed. An unreadable directory is recorded and does
 * not abort the scan.
 *
 * Does not sort, dedupe, or emit warnings — each caller owns its own output
 * contract for those.
 */
export declare function bfsCollectSupportedFiles(rootPath: string, exclusion: ScanExclusion, options?: BfsCollectOptions): Promise<DirScanResult>;
export {};
//# sourceMappingURL=scan.d.ts.map