/**
 * Ref-based baseline gather — produces a `CurrentScan` for a git
 * ref by checking it out into a temporary worktree and running the
 * analyzer pipeline there.
 *
 * # When this runs
 *
 * `mode === 'ref-based'` (see `./modes.ts`). The guardrail check
 * needs a "prior side" to diff against; in committed modes the
 * prior side comes from `.dxkit/baselines/<name>.json`, but in
 * ref-based mode no file is committed — the prior side is
 * recomputed on the fly from a git ref (default
 * `origin/<default-branch>`).
 *
 * # Mechanics
 *
 * 1. Resolve `ref` to a commit SHA. Failure here surfaces a
 *    `RefBaselineError` with one of three actionable hints:
 *      - Shallow clone → `git fetch --unshallow` / CI fetch-depth
 *      - Ref doesn't exist → `git fetch origin` or fix policy
 *      - Local-only ref → push it or use a remote-tracking ref
 * 2. `git worktree add --detach <tempDir> <sha>`. The worktree is a
 *    full checkout of the source tree at that SHA — but NOT a
 *    package-manager install, so dep-vuln scanners that read
 *    `node_modules` directly will see degraded results. The
 *    dxkit dep scanners use lockfiles (`package-lock.json`,
 *    `Pipfile.lock`, etc.) which ARE in the worktree, so coverage
 *    survives the gap.
 * 3. Run `gatherCurrentScan` against the worktree directory. Same
 *    pipeline as the live current scan — same producer registry,
 *    same envelope shape — so the matcher diffs apples-to-apples.
 * 4. Clean up the worktree on the way out (try/finally).
 *
 * # Why a generic `withRefWorktree` helper
 *
 * The worktree setup + cleanup pattern is reusable. Future modes-
 * aware tooling (e.g., a `vyuh-dxkit baseline diff <refA> <refB>`
 * subcommand) can compose `withRefWorktree` directly instead of
 * re-deriving the temp-dir + cleanup dance. `gatherFromRef` is a
 * thin specialization for the guardrail-check use case.
 *
 * # Failure semantics
 *
 * Recoverable failures (ref unreachable, worktree-add fails) throw
 * `RefBaselineError` with a `hint` field the CLI renders in plain
 * prose. Unrecoverable failures (the gather pipeline itself
 * crashes) propagate up the original Error subclass — they're not
 * specific to ref-based mode and live with the existing error
 * handling in the orchestrator.
 */
import type { CurrentScan } from './create';
/**
 * Recoverable error from the ref-based gather path. Carries an
 * actionable `hint` the CLI surfaces verbatim so customers don't
 * have to interpret raw git output. Inherits from `Error` so
 * existing catch-by-Error code keeps working.
 */
export declare class RefBaselineError extends Error {
    readonly hint: string;
    constructor(message: string, hint: string);
}
export interface RefWorktreeOptions {
    readonly cwd: string;
    readonly ref: string;
}
/**
 * Resolve a ref to a commit SHA via `git rev-parse --verify
 * <ref>^{commit}`. Returns null when the ref isn't reachable (the
 * caller surfaces the appropriate hint based on shallow-clone /
 * remote-only state).
 */
export declare function resolveRefToSha(cwd: string, ref: string): string | null;
/**
 * Whether the current working tree was cloned shallowly. Drives
 * the hint surfaced when a ref isn't reachable: a CI clone with
 * `fetch-depth: 1` won't have the baseline ref's history, and the
 * fix is `fetch-depth: 0`, not pushing the missing ref.
 */
export declare function isShallowRepo(cwd: string): boolean;
/**
 * Check out `ref` into a temporary worktree, run `fn` with the
 * worktree path, and tear down the worktree on the way out.
 *
 * Always cleans up — even when `fn` throws. The cleanup tolerates
 * `git worktree remove` failures (e.g., dirty worktree from a
 * partial gather) by falling back to `rm -rf` on the temp dir.
 */
export declare function withRefWorktree<T>(opts: RefWorktreeOptions, fn: (worktreePath: string) => Promise<T>): Promise<T>;
/**
 * Copy `.dxkit/salt` from `srcCwd` into `dstCwd` when present.
 * Public for testing — production callers reach this through
 * `withRefWorktree`. The directory is created on demand; absent
 * source files are silently skipped (env-var + deterministic salt
 * modes both work without the file).
 */
export declare function mirrorSaltFile(srcCwd: string, dstCwd: string): void;
/**
 * Run `gatherCurrentScan` against a temporary worktree checked out
 * to `ref`. Returns the same shape as a live gather — the matcher
 * doesn't care which side was the worktree, only that both sides
 * are `CurrentScan` envelopes.
 *
 * Per-tool degradation note: dep-vuln scanners may report less
 * coverage in the worktree because `node_modules` (and analogous
 * install artifacts) are typically gitignored and so don't exist
 * in the worktree. The lockfile-driven scanners dxkit prefers
 * survive the gap; `npm audit`-style probes do not.
 */
export declare function gatherFromRef(opts: {
    readonly cwd: string;
    readonly ref: string;
    readonly verbose?: boolean;
}): Promise<CurrentScan>;
//# sourceMappingURL=ref-baseline.d.ts.map