import { AppError } from './errors.js';
/**
 * Effective document roots, in two index-aligned forms. This is the canonical
 * statement of the path policy; other sites reference it.
 *
 * - `baseDirs`: realpath-resolved — the containment boundary for
 *   `DocumentParser`, and the ONLY place realpath is used.
 * - `rawBaseDirs`: the same roots, resolve()-only. Everything user-facing
 *   scans and displays in this space so paths match the resolve()-stored DB
 *   keys; otherwise a symlinked prefix (macOS /tmp → /private/tmp) would make
 *   ingested files look un-ingested.
 */
export interface BaseDirsConfig {
    baseDirs: string[];
    rawBaseDirs: string[];
}
/**
 * Discriminated union of configuration warnings surfaced by helpers in this
 * module. Both CLI (stderr) and MCP (tool response content block) paths
 * consume these — the consumer decides how to render them.
 */
export type BaseDirsConfigWarning = {
    kind: 'nested-root-pruned';
    message: string;
    parent: string;
    pruned: string;
} | {
    kind: 'base-dirs-overrides-base-dir';
    message: string;
};
/**
 * Configuration error raised by parsers and the realpath helper. Modeled as
 * a dedicated subclass so consumers can distinguish configuration problems
 * from other I/O errors (e.g. `ValidationError` from `DocumentParser`).
 */
export declare class BaseDirsConfigError extends AppError {
    constructor(message: string, options?: {
        cause?: Error;
    });
}
/**
 * Result of {@link parseBaseDirsEnv}. A discriminated union avoids forcing
 * callers to use `try/catch` for what is a routine configuration-validation
 * branch (invalid input → structured error → user-facing message).
 */
export type ParseBaseDirsResult = {
    ok: true;
    value: string[];
} | {
    ok: false;
    error: BaseDirsConfigError;
};
/**
 * Substitute `$HOME` with `~` for a user-visible path, so a warning flowing
 * out through MCP does not leak the OS username. `$HOME` is read at call time,
 * never cached.
 */
export declare function displayPath(path: string): string;
/** Parse `BASE_DIRS`. Syntax only — existence is {@link normalizeRealpath}'s job. */
export declare function parseBaseDirsEnv(raw: string): ParseBaseDirsResult;
/** Parse `IGNORE_PATHS`; unset or empty means no patterns. */
export declare function parseIgnorePathsEnv(raw: string | undefined): {
    ok: true;
    value: string[];
} | {
    ok: false;
    message: string;
};
/**
 * Append a trailing path separator if the input does not already end with
 * one. This is the prefix-safety pattern used throughout the parser
 * (`/foo/bar` must not match `/foo/barista`).
 */
export declare function withTrailingSeparator(path: string): string;
/**
 * Resolve a directory to its realpath and append a trailing separator, so the
 * result works directly as a prefix in a containment check.
 *
 * Throws when the path is not an existing directory: a root must point at one.
 */
export declare function normalizeRealpath(path: string): Promise<string>;
/**
 * Output of {@link dedupAndPruneRoots}.
 */
export interface DedupAndPruneResult {
    /** Effective roots in input order, after exact dedup and nested pruning. */
    roots: string[];
    /** Warnings describing pruned nested roots, in pruning order. */
    warnings: BaseDirsConfigWarning[];
}
/**
 * Reduce realpath-normalized roots to the effective set.
 *
 * Exact duplicates are dropped silently — that is convenience, not a mistake.
 * A nested root is pruned in favour of its parent with a warning, which keeps
 * scan output free of duplicates without widening the boundary past the parent
 * the user already configured. Surviving order is preserved so the first
 * element stays a meaningful legacy `baseDir`.
 *
 * Every input MUST already end with a separator — that is what makes the
 * `startsWith` check safe against a sibling like `/foo/barista`.
 */
export declare function dedupAndPruneRoots(inputs: string[]): DedupAndPruneResult;
/**
 * Input to {@link resolveBaseDirs}, in precedence order: `cliRoots` (highest),
 * `envBaseDirs`, `envBaseDir`, `cwd`.
 *
 * The resolver reads no process state, so both entry points can share it and
 * tests can drive it deterministically.
 */
export interface ResolveBaseDirsInput {
    cliRoots?: string[] | undefined;
    envBaseDirs?: string | undefined;
    envBaseDir?: string | undefined;
    cwd: string;
}
/**
 * Result of {@link resolveBaseDirs}, discriminated by `ok` — invalid
 * `BASE_DIRS` is a routine user-facing path, not an exception.
 *
 * `warnings` is in display order: the precedence note first, then one entry
 * per pruned root.
 */
export type ResolveBaseDirsResult = {
    ok: true;
    config: BaseDirsConfig;
    warnings: BaseDirsConfigWarning[];
} | {
    ok: false;
    error: BaseDirsConfigError;
};
/**
 * Resolve effective base directories from CLI / env / cwd.
 *
 * `cliRoots` REPLACES the env roots rather than merging with them; otherwise
 * precedence falls through `BASE_DIRS`, `BASE_DIR`, `cwd`. The
 * `BASE_DIRS > BASE_DIR` warning therefore fires only on an env-driven run.
 *
 * An invalid `BASE_DIRS`, or a root that is not a readable directory, returns
 * `{ ok: false }`. The resolver never falls back to `BASE_DIR` or `cwd` — each
 * caller surfaces the error per its own UI contract.
 */
export declare function resolveBaseDirs(input: ResolveBaseDirsInput): Promise<ResolveBaseDirsResult>;
//# sourceMappingURL=base-dirs.d.ts.map