/**
 * 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 a configured excluded prefix (the database or cache directory). */
 | '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;
/** 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 directory entry and an explicitly requested path
 * ({@link classifyRequestedPath}) are judged by exactly the same rules instead of
 * by two implementations that can drift.
 *
 * Evaluation order is part of the contract and matches the walk: a symbolic link
 * is reported as a link even under an excluded prefix, and a directory is
 * accepted without any extension test.
 *
 * `platform` is a parameter rather than a direct `process.platform` read — the
 * same reason `toSyncPathKey` takes one: the Windows exclusion semantics
 * ({@link isUnderExcludedPrefix}) must be provable on a macOS/Linux machine. The
 * default leaves every call site unchanged.
 *
 * Both `Dirent` (from `readdir`) and `Stats` (from `lstat`) satisfy
 * {@link EntryTypeFacts} structurally.
 */
export declare function classifyScanEntry(fullPath: string, entry: EntryTypeFacts, excludePaths: readonly string[], 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, excludePaths: readonly string[], 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;
}
/**
 * Bounded BFS scan of a single root, collecting every supported file up to
 * `maxDepth` levels deep, counted from `rootPath` itself. Symlinks are skipped
 * (never followed) and recorded in `skippedSymlinks`; paths under any
 * `excludePaths` prefix are filtered out. A per-directory `readdir` failure is
 * captured into `unreadableDirs` and does not abort the scan (best-effort per
 * directory); a branch pruned at `maxDepth` is captured into `depthLimitedDirs`.
 *
 * When `scope` is provided (non-empty), the predicate is pushed into the
 * traversal: a directory is visited only if it is in-scope or an ancestor of
 * some scope prefix, and a file is collected only if it is in-scope. A root that
 * intersects no prefix is skipped without any `readdir`. An absent/empty `scope`
 * leaves traversal and collection byte-for-byte unchanged.
 *
 * `platform` only selects how the exclusion comparison treats case (see
 * {@link classifyScanEntry}); it defaults to the host, so every existing call is
 * unchanged.
 *
 * Does not sort, dedupe, or emit warnings — callers handle those so their
 * existing output contracts are preserved.
 */
export declare function bfsCollectSupportedFiles(rootPath: string, excludePaths: readonly string[], maxDepth?: number, scope?: string[], platform?: NodeJS.Platform): Promise<DirScanResult>;
export {};
//# sourceMappingURL=scan.d.ts.map