approval-md 0.1.0 → 0.3.0

package/dist/src/core/commit-guard.js

@@ -0,0 +1,424 @@
+/**
+ * The unit of judgment: one commit (APRV-375).
+ *
+ * ## What a grant binds
+ *
+ * A `policy.edit` grant binds ONE edit: a before-state, an after-state, and a
+ * human who was shown them. The protected-path guard of
+ * `core/protected-path-guard.ts` decides whether a change is made of such
+ * material, and everything it answers is relative to the pair of blobs the
+ * caller hands it. So the caller's choice of pair is the whole question, and
+ * until this module the CI guard chose the pull request's COMBINED diff: base
+ * tree against head tree, every commit's work replayed as one change.
+ *
+ * That pairing has no grant. PR #427 is the worked example (APRV-357's
+ * reproduction, PR #452): three lane commits, each granted, plus two merges of
+ * `origin/main` made while four other lanes were editing `SPEC.md`. Replayed as
+ * one change it failed `uncovered-hunk` with fourteen uncovered lines, twenty
+ * nine records naming the path and twenty seven covering part of it, because a
+ * grant binds a before-state that the combined base no longer carries once an
+ * earlier commit in the range has moved those bytes. Replayed per commit all
+ * three pass, in well under a second each.
+ *
+ * `approval doctor`'s dark-session arm A reached the same conclusion from the
+ * other side (APRV-369): it used to replay a whole window as one change and
+ * failed a change CI had passed, at every session start. It now replays per
+ * commit. This module is where the two meet, so the agreement is by
+ * construction rather than by two code paths kept in step.
+ *
+ * ## The security argument
+ *
+ * Judging per commit asks a SMALLER question than judging the combined diff, so
+ * it owes an argument that nothing escapes. It is this:
+ *
+ * 1. Every byte that differs between the base tree and the head tree was
+ *    written by some commit in `base..head`. Two-dot range semantics is what
+ *    makes that true: a commit reachable from base is excluded, and a commit
+ *    reachable from base changed nothing about the difference between the two
+ *    trees that its own history did not already carry.
+ * 2. A non-merge commit's whole contribution is its diff against its parent,
+ *    which is exactly what this module hands the guard.
+ * 3. A merge commit contributes only what it resolved: the bytes its result
+ *    carries that no parent carried. That is git's DENSE combined diff
+ *    (`--cc`), and a merge with a non-empty one on a guarded path is judged
+ *    against its first parent here. A merge whose result on a path is some
+ *    parent's bytes verbatim invented nothing and is listed as skipped.
+ *
+ * Together: every changed byte is inside some judged unit, and each unit is
+ * judged against the before-state a grant for it would have bound. The guard
+ * stops asking about the combined diff because the combined diff is a change
+ * nobody ever made and nobody could have approved.
+ *
+ * ## One thing is NOT per commit: whole-file evidence
+ *
+ * A grant binds a hunk, so it is evidence about one commit. A sign-off
+ * (APRV-338), an organ attestation (APRV-272) and the policy attestation say a
+ * human read the file AS IT NOW STANDS, so they are evidence about the bytes
+ * the range INSTALLS: every commit is offered the digests at the RANGE HEAD.
+ * {@link digestsAt} carries the reasoning, and it matters because matching them
+ * per commit would have repealed the escape hatch for every edit before the
+ * last one.
+ *
+ * ## What this does NOT do
+ *
+ * It does not re-judge work the branch absorbed by merging `origin/main`. Those
+ * commits are main's, they passed their own pull requests, and two-dot
+ * `base..head` excludes them by construction: CI computes base as `git
+ * merge-base origin/main HEAD`, so a branch that merged main has every absorbed
+ * commit reachable from base. Nothing is skipped by a rule about authorship or
+ * about who pushed what; the range is simply the commits this pull request is
+ * proposing to add.
+ *
+ * It also does not relax the exact-replay byte budget of
+ * `core/protected-path-guard.ts`. Per commit that budget is not reached in any
+ * case observed, which is why APRV-357 closes as superseded rather than fixed.
+ */
+import { createHash } from "node:crypto";
+import { evaluateProtectedPaths, isGuardedPath } from "./protected-path-guard.js";
+/** SHA-256 of a UTF-8 string, hex. */
+function sha256Hex(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/** Is this commit a merge? */
+export function isMerge(commit) {
+    return commit.parents.length > 1;
+}
+/**
+ * The revision a commit is judged AGAINST: its first parent.
+ *
+ * First parent and not the merge base of the parents, for a merge, because the
+ * first parent is the state the branch was in before the merge and the merge's
+ * own contribution is measured from there. `null` for a root commit, which has
+ * no before-state at all and whose every path is an add.
+ */
+export function baseRevOf(commit) {
+    return commit.parents.length === 0 ? null : `${commit.sha}^1`;
+}
+/**
+ * Record and field separators inside `git log --pretty`.
+ *
+ * ASCII 30 and 31, for the reason `core/dark-session.ts` states where it uses
+ * the same pair: git quotes any path containing a control character, so a
+ * filename engineered to carry one arrives escaped and cannot forge a commit
+ * boundary in output the guard parses.
+ */
+const RS = "";
+const FS = "";
+function datesOf(author, committer) {
+    const a = author === undefined || author.length === 0 ? null : author;
+    const c = committer === undefined || committer.length === 0 ? null : committer;
+    return { author: a, committer: c ?? a };
+}
+/**
+ * The commits of `base..head`, oldest first, each with the paths it is judged
+ * for.
+ *
+ * `judged` narrows the per-path work a MERGE costs: git's dense combined diff
+ * has to be asked for one path at a time (see below), and asking it about every
+ * file a large merge touched would be a git invocation per file for no verdict.
+ * A non-merge commit's path list is not narrowed at all, so the guard still
+ * reports exempt paths and still sees everything it might protect.
+ *
+ * The two-step merge question is not an optimization, it is correctness.
+ * `git log -c --name-only` lists the files "modified from all parents", which
+ * OVER-reports: at PR #427's merge `e66ba9e` it lists `SPEC.md`, whose result
+ * differs from both parents as a blob while every hunk of it came verbatim from
+ * one side. The dense (`--cc`) rendering is the one that drops hunks a parent
+ * already carried, and a path whose dense rendering is empty invented nothing.
+ * So each candidate is re-asked with a per-path `--cc` patch, and passing the
+ * path as a pathspec rather than parsing it out of a `diff --cc` header keeps
+ * quoted and unusual filenames out of the parser entirely.
+ */
+export function listCommits(read, base, head, judged) {
+    const log = read([
+        "log",
+        "--reverse",
+        `--pretty=format:${RS}%H${FS}%P${FS}%aI${FS}%cI`,
+        "--name-only",
+        `${base}..${head}`,
+    ]);
+    if (log === null) {
+        return { ok: false, message: `\`git log ${base}..${head}\` failed` };
+    }
+    const commits = [];
+    for (const chunk of log.split(RS)) {
+        const lines = chunk.split("\n").filter((line) => line.length > 0);
+        const header = lines.shift();
+        if (header === undefined)
+            continue;
+        const [sha, parents, authored, committed] = header.split(FS);
+        if (sha === undefined || sha.length === 0)
+            continue;
+        const parentList = (parents ?? "")
+            .split(" ")
+            .map((part) => part.trim())
+            .filter((part) => part.length > 0);
+        const commit = {
+            sha,
+            parents: parentList,
+            ts: datesOf(authored, committed),
+            // `--name-only` reports nothing for a merge; the dense pass below fills it.
+            changedPaths: parentList.length > 1 ? denseCombinedPaths(read, sha, judged) : lines,
+        };
+        commits.push(commit);
+    }
+    return { ok: true, commits };
+}
+/**
+ * The guarded paths a merge commit's result carries that no parent carried:
+ * the merge's own work, which is what an evil merge is made of.
+ *
+ * EXPORTED because arm A of `core/dark-session.ts` asks the same question of a
+ * merge it finds on main (APRV-374), and two implementations of "what did this
+ * merge invent" would be two things to keep in step — the disagreement APRV-369
+ * was filed about. The observer there lists a window rather than a range, so it
+ * cannot reuse {@link listCommits}; it reuses this.
+ *
+ * The two-step shape is the correctness (see {@link listCommits}): `-c
+ * --name-only` gives candidates and over-reports, and the per-path `--cc` patch
+ * is the discriminator, empty for every merge whose every hunk came from a
+ * parent verbatim.
+ */
+export function denseCombinedPaths(read, sha, judged) {
+    const listed = read(["log", "-1", "-c", "--name-only", "--pretty=format:", sha]);
+    if (listed === null)
+        return [];
+    const dense = [];
+    for (const line of listed.split("\n")) {
+        const path = line.trim();
+        if (path.length === 0 || !judged(path))
+            continue;
+        const patch = read(["log", "-1", "--cc", "--pretty=format:", sha, "--", path]);
+        if (patch !== null && patch.trim().length > 0)
+            dense.push(path);
+    }
+    return dense;
+}
+export function commitGuardInputParts(read, commit) {
+    const parents = commit.parents;
+    const baseRev = parents !== undefined && parents.length === 0 ? null : `${commit.sha}^1`;
+    const blobCache = new Map();
+    const digestCache = new Map();
+    const inTree = (rev, path) => {
+        const listed = read(["ls-tree", "--name-only", rev, "--", path]);
+        return listed !== null && listed.trim().length > 0;
+    };
+    const show = (rev, path) => read(["show", `${rev}:${path}`]);
+    return {
+        blobsFor: (path) => {
+            const cached = blobCache.get(path);
+            if (cached !== undefined)
+                return cached;
+            const baseHas = baseRev !== null && inTree(baseRev, path);
+            const headHas = inTree(commit.sha, path);
+            const baseText = baseHas && baseRev !== null ? show(baseRev, path) : null;
+            const headText = headHas ? show(commit.sha, path) : null;
+            // A blob git cannot show, or one with a NUL byte in it, answers null and
+            // the guard fails the path `change-unreadable` rather than falling back
+            // to the path-level rule. The fallback is the hole (APRV-202).
+            const unreadable = (baseHas && baseText === null) ||
+                (headHas && headText === null) ||
+                (baseText !== null && baseText.includes("")) ||
+                (headText !== null && headText.includes(""));
+            const value = unreadable ? null : { base: baseText, head: headText };
+            blobCache.set(path, value);
+            return value;
+        },
+        sha256At: (path) => {
+            const cached = digestCache.get(path);
+            if (cached !== undefined)
+                return cached;
+            const blob = show(commit.sha, path);
+            const value = blob === null ? null : sha256Hex(blob);
+            digestCache.set(path, value);
+            return value;
+        },
+        changeTsFor: () => commit.ts,
+        window: {
+            base: baseRev === null ? "(root)" : `${commit.sha.slice(0, 12)}^1`,
+            head: commit.sha.slice(0, 12),
+        },
+    };
+}
+/**
+ * SHA-256 of any path's bytes AT ONE REVISION, cached.
+ *
+ * ## Why whole-file evidence is matched at the range head and not per commit
+ *
+ * The two kinds of evidence answer different questions, so they are anchored to
+ * different things:
+ *
+ * - A GRANT binds a hunk — a before-state, an after-state, a human who was
+ *   shown them — so it is evidence about ONE COMMIT and is matched per commit,
+ *   which is what APRV-375 is about.
+ * - A SIGN-OFF (`gate.path.signed_off`, APRV-338), an ORGAN attestation
+ *   (`gate.organ.attested`, APRV-272) and the POLICY attestation
+ *   (`policy.updated`) are whole-file records: a human read the file AS IT NOW
+ *   STANDS and ratified those exact bytes. What they are about is the bytes the
+ *   pull request INSTALLS, which is the blob at the range head.
+ *
+ * Matching them per commit would have quietly repealed the escape hatch. A
+ * two-commit branch whose first commit has no grant could no longer be rescued
+ * by a sign-off at head, because the intermediate blob is not the ratified one;
+ * a policy amendment split over two commits would fail on the first. So every
+ * commit in a range is offered the digests at the range head, whatever its own
+ * blob hashes to. The ordering APRV-338 asked for is untouched: the evaluator
+ * reaches the sign-off only after every grant search has failed, so hunk
+ * evidence still leads the reasons wherever it exists.
+ */
+export function digestsAt(read, rev) {
+    const cache = new Map();
+    return (path) => {
+        const cached = cache.get(path);
+        if (cached !== undefined)
+            return cached;
+        const blob = read(["show", `${rev}:${path}`]);
+        const value = blob === null ? null : sha256Hex(blob);
+        cache.set(path, value);
+        return value;
+    };
+}
+/**
+ * Judge every commit of `base..head` on its own records, and report the
+ * conjunction.
+ *
+ * `evaluateProtectedPaths` is unchanged and is what decides each commit: this
+ * function chooses the unit and nothing else. A commit that changed no guarded
+ * path costs one evaluator call that finds nothing, and a clean merge costs no
+ * evaluator call at all.
+ */
+export function judgeCommits(options) {
+    const { read, base, head, shared } = options;
+    const empty = {
+        ok: false,
+        commits: [],
+        findings: [],
+        exempt: [],
+        window: shared.window,
+    };
+    const listed = listCommits(read, base, head, (path) => isJudgedPath(path, shared));
+    if (!listed.ok)
+        return { ...empty, unavailable: listed.message };
+    // Whole-file evidence is about the bytes this pull request INSTALLS, so it is
+    // matched at the RANGE head for every commit in the range. See {@link digestsAt}.
+    const atRangeHead = digestsAt(read, head);
+    const policySha256AtHead = atRangeHead(shared.policyPath);
+    const commits = [];
+    const findings = [];
+    const exempt = new Set();
+    for (const commit of listed.commits) {
+        const merge = isMerge(commit);
+        const baseRev = baseRevOf(commit);
+        if (commit.changedPaths.length === 0) {
+            commits.push({
+                sha: commit.sha,
+                base: baseRev,
+                merge,
+                judged: false,
+                skipped: merge ? "clean-merge" : "no-guarded-path",
+                ok: true,
+                findings: [],
+                exempt: [],
+                covered: [],
+            });
+            continue;
+        }
+        const parts = commitGuardInputParts(read, commit);
+        const report = evaluateProtectedPaths({
+            ...shared,
+            policySha256AtHead,
+            changedPaths: [...commit.changedPaths].sort(),
+            blobsFor: parts.blobsFor,
+            organSha256AtHead: atRangeHead,
+            pathSha256AtHead: atRangeHead,
+            changeTsFor: parts.changeTsFor,
+            window: { ...shared.window, base: parts.window.base, head: parts.window.head },
+        });
+        for (const path of report.exempt)
+            exempt.add(path);
+        for (const finding of report.findings)
+            findings.push({ ...finding, commit: commit.sha });
+        const covered = [];
+        for (const finding of report.findings) {
+            if (!finding.ok)
+                continue;
+            for (const seq of finding.coveredBy ?? (finding.seq === undefined ? [] : [finding.seq])) {
+                if (!covered.includes(seq))
+                    covered.push(seq);
+            }
+        }
+        const nothingToJudge = report.findings.length === 0 && report.exempt.length === 0;
+        commits.push({
+            sha: commit.sha,
+            base: baseRev,
+            merge,
+            judged: !nothingToJudge,
+            skipped: nothingToJudge ? (merge ? "clean-merge" : "no-guarded-path") : null,
+            ok: report.ok,
+            findings: report.findings,
+            exempt: report.exempt,
+            covered,
+        });
+    }
+    return {
+        ok: commits.every((commit) => commit.ok),
+        commits,
+        findings,
+        exempt: [...exempt],
+        window: shared.window,
+        unavailable: null,
+    };
+}
+/**
+ * Would the guard have an opinion about this path?
+ *
+ * Only used to keep the merge pass cheap, so it is deliberately the PERMISSIVE
+ * side of the question: the policy's widening entries plus the built-in set,
+ * which is what `isGuardedPath` asks. A path this answers `true` for still has
+ * to earn its verdict from the evaluator.
+ */
+function isJudgedPath(path, shared) {
+    return isGuardedPath(path, shared.policyProtectedPaths);
+}
+/** The report as the lines CI prints. Pure. */
+export function renderCommitGuardReport(report) {
+    const lines = [];
+    const judged = report.commits.filter((commit) => commit.judged);
+    lines.push(`protected-path guard: ${report.window.base}..${report.window.head}, judged one commit at a time (${String(report.commits.length)} commit(s) in the range, ${String(judged.length)} with a protected change)`);
+    if (report.unavailable !== null) {
+        lines.push(`  the guard could not look: ${report.unavailable}`);
+        return `${lines.join("\n")}\n`;
+    }
+    if (report.exempt.length > 0) {
+        lines.push(`  exempt (the daemon's own append surface, evidence rather than a protected write): ${report.exempt.join(", ")}`);
+    }
+    if (report.commits.length === 0) {
+        lines.push("  no commits in the range");
+        return `${lines.join("\n")}\n`;
+    }
+    for (const commit of report.commits) {
+        const sha = commit.sha.slice(0, 12);
+        const against = commit.base === null ? "a root commit" : `base ${sha}^1`;
+        if (!commit.judged) {
+            const why = commit.skipped === "clean-merge"
+                ? "merge, and its result on every guarded path is one parent's bytes verbatim"
+                : "no protected path changed";
+            lines.push(`  SKIP ${sha} (${against}): ${why}`);
+            continue;
+        }
+        const covered = commit.covered.length === 0
+            ? ""
+            : `, covered by seq ${commit.covered.slice(0, 8).join(", ")}${commit.covered.length > 8 ? ", …" : ""}`;
+        lines.push(`  ${commit.ok ? "PASS" : "FAIL"} ${sha} (${against})${commit.merge ? ", merge resolution" : ""}${covered}`);
+        for (const finding of commit.findings) {
+            lines.push(finding.ok
+                ? `    PASS ${finding.path} [${finding.evidence}]`
+                : `    FAIL ${finding.path} [${finding.code}]`);
+            lines.push(`         ${finding.detail}`);
+        }
+    }
+    if (judged.length === 0)
+        lines.push("  no protected paths changed");
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=commit-guard.js.map

package/dist/src/core/commit-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-guard.js","sourceRoot":"","sources":["../../../src/core/commit-guard.ts"],"names":[],"mappings":"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"}

package/dist/src/core/coverage-sources/adapter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The adapter coverage source (APRV-245).
+ *
+ * The other two sources read a repository. This one asks the PROVIDER what it
+ * recorded: AgentMail knows which messages an inbox actually sent, and that
+ * record is written by neither the agent nor this runtime. An adapter that
+ * implements the optional `observe` (see `adapters/contract.ts`) publishes that
+ * knowledge, and an adapter that does not is reported as offering none rather
+ * than as having seen nothing.
+ *
+ * ## What this source guarantees about the call
+ *
+ * - **Read-only, and outside any grant window.** `observe` is never handed a
+ *   token, never called from inside `executeThroughAdapter`, and is documented
+ *   in the contract as a read. A coverage report that could send would be a
+ *   report nobody dares run.
+ * - **The caller redacts.** An adapter's answer can quote whatever its far side
+ *   said, so every `detail` goes through {@link redactSecrets} against the
+ *   secrets the caller knows before it is returned. The adapter scrubs its own
+ *   strings too; this is the second pass, on the principle that redaction is
+ *   cheap and a leak is not (SPEC.md §11.1 invariant 3).
+ * - **A throw is a source failure, not a crash.** An adapter whose far side is
+ *   down makes its own source unavailable and leaves every other source's
+ *   answer intact.
+ */
+import { type Adapter, type CredentialProvider } from "../../adapters/contract.js";
+import type { ObservationWindow } from "../coverage.js";
+import type { SourceObservation } from "./git.js";
+export interface AdapterSourceOptions {
+    /** Values to scrub out of every returned detail. */
+    secrets?: readonly string[];
+}
+/**
+ * Ask one adapter what its provider recorded in `window`.
+ *
+ * An adapter with no `observe` is `available: false` with a reason that names
+ * the gap honestly: this adapter offers no observation, so the runtime cannot
+ * say whether effects of its class happened outside the gate.
+ */
+export declare function observeAdapter(adapter: Adapter, window: ObservationWindow, credentials: CredentialProvider, options?: AdapterSourceOptions): Promise<SourceObservation>;

package/dist/src/core/coverage-sources/gh.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The GitHub coverage source (APRV-245).
+ *
+ * A pull request is an effect with a witness this project does not write:
+ * GitHub recorded who opened it and when, and GitHub recorded the merge that
+ * moved the trunk. `gh pr list --json` reads both back, and neither number can
+ * be edited by an agent editing its own log.
+ *
+ * ## Absent is reported, never inferred
+ *
+ * `gh` is optional and unauthenticated checkouts are ordinary, so an absent or
+ * refusing `gh` produces `available: false` with the reason and NO effects. That
+ * distinction is the whole reliability of the report: "gh saw no pull requests"
+ * and "gh could not be asked" are different facts, and collapsing them into an
+ * empty list would let a broken CLI read as a clean bill of health.
+ *
+ * ## The class mapping
+ *
+ * - opening a pull request is `vcs.pr.open`, the class `core/command-class.ts`
+ *   gives `gh pr create`;
+ * - merging one is `vcs.push.main`, the class it gives `gh pr merge`, because
+ *   what a merge does is move the trunk.
+ *
+ * A pull request that was opened and merged inside the window produces TWO
+ * effects, because they are two decisions a policy answers separately and each
+ * needs its own evidence.
+ *
+ * Nothing here reads the clock: the window comes from the caller and every
+ * timestamp is GitHub's own.
+ */
+import { type SourceObservation } from "./git.js";
+/** How many pull requests one run asks for. `gh` caps at 1000; this is plenty. */
+export declare const GH_PR_LIMIT = 100;
+export interface GhSourceOptions {
+    /** Inclusive lower bound of the window, RFC 3339. */
+    since: string;
+    /** Inclusive upper bound, RFC 3339. */
+    until: string;
+    /** Override {@link GH_PR_LIMIT}. */
+    limit?: number;
+}
+/**
+ * What GitHub witnessed in the window.
+ *
+ * Never throws. `gh` that is not installed, not authenticated, or pointed at a
+ * directory with no remote all come back as `available: false`.
+ */
+export declare function observeGh(root: string, options: GhSourceOptions): SourceObservation;

package/dist/src/core/coverage-sources/git.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The git coverage source (APRV-245).
+ *
+ * Git history is the cheapest witness this project has that it does not write:
+ * a commit, a merge into the trunk and a tag are all effects an agent produced,
+ * all recorded by a tool with no idea approval.md exists, and all readable back
+ * long after the session that made them is gone.
+ *
+ * **Never the working tree.** Every fact here comes from `git log`, `git show`
+ * and `git for-each-ref` over committed objects. An uncommitted edit is not an
+ * effect yet — it is a file a person can still delete — and reading the tree
+ * would make the report depend on whatever happened to be lying around when it
+ * ran, which is the opposite of the determinism a witness needs.
+ *
+ * ## The class mapping
+ *
+ * The classes are SPEC.md §7's own, spelled as `core/command-class.ts` spells
+ * them, because a source that invented a class would produce effects no record
+ * could ever match:
+ *
+ * - a commit REACHABLE FROM `origin/main` is `vcs.push.main`. What the class
+ *   names is the trunk moving, and a commit on the trunk moved it however it
+ *   got there (a merge, a fast-forward, a direct push);
+ * - a commit the trunk does not reach but SOME remote-tracking ref does
+ *   (`refs/remotes/*`) is `vcs.push.branch`, which is the class the classifier
+ *   gives `git push origin <branch>`: the commit left the machine, and the
+ *   action a task declares for that is the push, never the commit;
+ * - any other commit in the range is `vcs.commit.branch`, which is the class the
+ *   classifier gives a bare `git commit`: it exists only here;
+ * - a tag is `release.publish`, which is the class the classifier gives
+ *   `git tag`;
+ * - a protected path a commit changed is `policy.edit`, reported as its own
+ *   effect carrying the `path`, so `core/coverage.ts` can put the
+ *   protected-path guard's byte-level verdict against it rather than the
+ *   class-and-window rule.
+ *
+ * A merge commit is a `vcs.push.main` like any other trunk commit and says so in
+ * its detail line; it is not given a class of its own, because the policy has
+ * none for it and an effect nobody can declare is an effect nothing can cover.
+ *
+ * Nothing here reads the clock: every timestamp is git's author date for the
+ * object being reported.
+ */
+import { type ProtectedPathEntry } from "../command-class.js";
+import type { ObservedEffect } from "../coverage.js";
+/** The result of asking one source what it saw. */
+export interface SourceObservation {
+    name: string;
+    available: boolean;
+    /** Why it is unavailable, or what qualifies an available answer. */
+    reason?: string;
+    effects: ObservedEffect[];
+}
+/** The default trunk ref. Overridable so a fork with another name still reports. */
+export declare const DEFAULT_TRUNK_REF = "origin/main";
+/**
+ * How many commits one run will describe.
+ *
+ * A bound rather than a stream, because each commit costs one `git show` for
+ * its changed paths and an unbounded range would turn a reporting verb into a
+ * repository walk. A truncated run says so in the source's `reason`, so the
+ * number is never quietly wrong.
+ */
+export declare const MAX_COMMITS = 200;
+export interface GitSourceOptions {
+    /** Exclusive lower bound of the commit range. */
+    base: string;
+    /** Inclusive upper bound. */
+    head: string;
+    /** The ref that decides `vcs.push.main`. Defaults to {@link DEFAULT_TRUNK_REF}. */
+    trunk?: string;
+    /** `policy.protected_paths` from the policy, widening the built-in set. */
+    policyProtectedPaths?: readonly ProtectedPathEntry[];
+    /** Override {@link MAX_COMMITS}. */
+    maxCommits?: number;
+}
+/** The first non-empty line of whatever a failed command printed. */
+export declare function firstLine(text: string): string;
+/**
+ * What git witnessed between `base` and `head`.
+ *
+ * Never throws: a directory that is not a repository, a ref that does not
+ * resolve and an absent git all come back as `available: false` with the reason
+ * git printed. A reporting verb that crashed on a checkout without a remote
+ * would be a verb people stop running.
+ */
+export declare function observeGit(root: string, options: GitSourceOptions): SourceObservation;
+/**
+ * The default commit range: `merge-base <trunk> HEAD`, falling back to `HEAD~20`.
+ *
+ * The fallback is announced rather than silent. A checkout with no `origin/main`
+ * (a fresh clone of a fork, a fixture repository, a detached CI checkout) has no
+ * merge base to take, and a range of "the last twenty commits" is a guess; a
+ * reader has to be able to see that the answer they are looking at came from a
+ * guess and not from the trunk.
+ */
+export declare function defaultRange(root: string, trunk?: string): {
+    base: string;
+    head: string;
+    note?: string;
+};