import type { MonographDb } from '../storage/db.js';
/**
 * Explicit index freshness. A boolean cannot distinguish "proven up to date"
 * from "we could not check", and reporting the latter as the former is how a
 * confident-but-baseless "fresh" answer reaches a caller.
 *
 * - `fresh`    — index matches HEAD, worktree is clean, no recorded warnings.
 * - `stale`    — index is behind HEAD, or the worktree has uncommitted edits.
 * - `building` — a build lock is held by a live process right now.
 * - `partial`  — index matches HEAD but is known incomplete (parser warnings
 *                or a recorded refresh error).
 * - `unknown`  — freshness could not be determined (git unavailable, no
 *                recorded revision, or the dirty-worktree probe failed).
 */
export type IndexFreshnessState = 'fresh' | 'stale' | 'building' | 'partial' | 'unknown';
export interface StalenessReport {
    /**
     * Commit-divergence only: true when the indexed commit is known to differ
     * from HEAD (or no commit was recorded). Deliberately unchanged — the
     * pipeline's skip-when-fresh guard reads it together with `currentCommit`.
     * It is NOT a freshness verdict: a clean-commit / dirty-worktree index has
     * `isStale: false` and `state: 'stale'`. New callers should read `state`.
     */
    isStale: boolean;
    /** Timestamp of the last build, from `index_meta.indexed_at`. */
    indexedAt: string | null;
    /** Short (7-char) SHA of the indexed revision. */
    indexedCommit: string | null;
    /** Short (7-char) SHA of current HEAD. */
    currentCommit: string | null;
    changedSince: string[];
    staleSince: string | null;
    /** Explicit freshness state — prefer this over `isStale`. */
    state: IndexFreshnessState;
    /** One sentence explaining why `state` has this value; safe to show a user. */
    reason: string;
    /** Full SHA of the revision the index was built from, null when unrecorded. */
    indexedRevision: string | null;
    /** Source scope the index was built with (e.g. 'code-only'), null when unrecorded. */
    sourceScope: string | null;
    /** true/false when git could be consulted, null when the probe failed. */
    dirtyWorktree: boolean | null;
    /** Sample of uncommitted paths, capped at {@link DIRTY_PATH_CAP}. */
    dirtyPaths: string[];
    /** True number of uncommitted paths, null when undetermined. */
    dirtyFileCount: number | null;
    /** Parser warnings recorded by the last build, null when none recorded. */
    parserWarnings: string[] | null;
    /** Error recorded by the last refresh attempt, null when none recorded. */
    lastRefreshError: string | null;
    /** A build lock is currently held by a live process. */
    buildInProgress: boolean;
    /** True whenever `state !== 'fresh'`: graph answers may be incomplete. */
    mayBeIncomplete: boolean;
}
export declare function checkStaleness(db: MonographDb, repoPath: string): StalenessReport;
//# sourceMappingURL=git-staleness.d.ts.map