@webpieces/repo-workflow-core 0.0.1

package/src/merged-branches.d.ts

@@ -0,0 +1,140 @@
+import { AtomicFile } from '@webpieces/tooling-common';
+import { DotWebpieces } from '@webpieces/tooling-common';
+import { WorktreeService } from './worktrees';
+import { WorktreeLockVerdicts } from './worktree-lock-verdicts';
+import { CacheFreshness, MergedBranchesCache } from './merged-branch-verdicts';
+export { MergedBranch, DeletableBranch, DeletableWorktree, MergedBranchesCache, CacheFreshness, CACHE_STALE_AFTER_MS, CLASSIFICATION_MERGED_PR, CLASSIFICATION_BACKUP_OF_MERGED, CLASSIFICATION_BACKUP_OF_LIVE, CLASSIFICATION_NO_COMMITS, CLASSIFICATION_SUPERSEDED, CLASSIFICATION_CONTENT_IN_MAIN, CLASSIFICATION_NEVER_PROPOSED, CLASSIFICATION_IN_USE, CLASSIFICATION_PRUNABLE, CLASSIFICATION_LOCKED, CLASSIFICATION_CURRENT, CLASSIFICATION_DETACHED, ADJUDICATED_CLASSIFICATIONS, } from './merged-branch-verdicts';
+export declare class MergedBranchesService {
+    private readonly worktrees;
+    private readonly dotDir;
+    private readonly atomicFile;
+    private readonly locks;
+    constructor(worktrees?: WorktreeService, dotDir?: DotWebpieces, atomicFile?: AtomicFile, locks?: WorktreeLockVerdicts);
+    /**
+     * SHARED scope — one per repo, in the primary clone, NOT one per worktree. This file's contents
+     * describe every branch AND every worktree in the repo, so a per-worktree copy was a repo-wide fact
+     * stored N times and therefore N times wrong: branch-creation-guard reported "8 parked local
+     * branches" against an actual 1, reading a copy that predated deletions made from another worktree.
+     */
+    mergedBranchesPath(repoRoot: string): string;
+    readMergedBranches(repoRoot: string): MergedBranchesCache | null;
+    /**
+     * How old is this cache, and may its numbers be quoted as fact?
+     *
+     * `now` is a parameter purely so the specs can pin it; every caller passes nothing.
+     */
+    freshness(cache: MergedBranchesCache, now?: number): CacheFreshness;
+    /**
+     * Drop every cached verdict whose subject no longer exists, using only LOCAL, instant git reads.
+     *
+     * The verdicts themselves are NOT re-derived here — that is the detached refresher's job and it
+     * needs the network. This answers a different and much cheaper question: does this branch / this
+     * worktree still exist at all? A cache written before a `git branch -D` or a `git worktree remove`
+     * keeps naming things that are gone, and a reader that counts those entries reports a repo that
+     * does not exist (observed: 8 parked branches asserted against an actual 1) and then blocks on it.
+     *
+     * Fails toward the cache: if git cannot answer (empty branch list), the cache is returned untouched
+     * rather than emptied, since "git failed" must never read as "everything was deleted".
+     */
+    reconcile(repoRoot: string, cache: MergedBranchesCache): MergedBranchesCache;
+    /**
+     * ATOMIC write. Now that this file is shared by every worktree it has N concurrent writers (one
+     * detached refresher per agent), and its readers are the guards' BLOCKING path. A plain
+     * `writeFileSync` truncates before it writes, so a reader landing in that window gets a torn
+     * document — the reader-side retry added in PR #526 cannot rescue a syntactically valid PREFIX.
+     * Fixed where it belongs: temp file + `rename()`, which POSIX makes atomic. See AtomicFile.
+     *
+     * This buys ATOMIC READS, not lost-update protection: two read-modify-write cycles still end
+     * last-writer-wins. That is acceptable and deliberate — this is a DERIVED cache, recomputed from
+     * `gh` + git by the refresher, and wp-cleanup recomputes rather than trusting it before deleting
+     * anything. Nothing here is transactional and no caller may assume it is.
+     */
+    writeMergedBranches(repoRoot: string, cache: MergedBranchesCache): void;
+    /**
+     * Every local branch except `main`. Uses `git for-each-ref`, NOT `git branch` — the latter is a
+     * porcelain command whose output the branch-creation-guard's own regex mistakes for a branch
+     * CREATION, so the guard would block the cleanup it just demanded.
+     */
+    localBranches(repoRoot: string): string[];
+    /**
+     * The SLOW path, run only inside the detached refresher. ONE bulk `gh` call, then a purely local
+     * classification. Never run on the hook's blocking path.
+     */
+    computeMergedBranches(repoRoot: string, ignoreStaleAgentLocks: boolean): MergedBranchesCache;
+    /**
+     * Verdicts for the worktree budget. The main worktree is excluded outright — it is the primary
+     * clone and is not a thing you can remove.
+     *
+     * A worktree is deletable when its directory is already gone (`prunable`), or when its branch is
+     * dead by the very same proof the branch cap uses — a MERGED PR, its own or that of the branch it
+     * snapshots. Nothing else. It is spared when its LOCK still stands (see WorktreeLockVerdicts for
+     * what makes one stand), when it is the worktree we are standing in right now (removing your own
+     * cwd is not a thing to suggest to an agent), or when its branch is anything short of provably
+     * merged — INCLUDING a branch with no commits yet, which is what every worktree looks like while
+     * an agent is working in it. `deletable` means PROVABLY dead and nothing weaker; wp-cleanup reaps
+     * the zero-commit ones on top of that, but only after checking on disk whether anybody is holding
+     * them (see CLASSIFICATION_NO_COMMITS), which is a question these verdicts do not answer.
+     *
+     * THE BRANCH VERDICT IS COMPUTED BEFORE THE LOCK IS RULED ON, which is new and is the point: one
+     * of the four things that can override an agent lock is the branch already being provably dead,
+     * and that cannot be weighed until it is known. Two extra local git calls per locked worktree, on
+     * a path that only ever runs in the detached refresher and in wp-cleanup itself.
+     */
+    private classifyWorktrees;
+    private lockDecision;
+    /**
+     * Verdict for one branch: its own merged PR, else the base it was backed up from, else empty.
+     *
+     * The verdict itself is unchanged. What is new is that EVERY entry now carries its tip SHA, its
+     * unique-commit count and its PR state, so a `keep` can be shown to a human as a delete candidate
+     * rather than just counted. This runs only in the detached refresher, so the two extra local git
+     * calls per branch cost the blocking hook path nothing.
+     */
+    private classify;
+    /**
+     * The three genuinely different reasons a branch survives the deletable proofs, ordered by how
+     * confidently a human can say yes to deleting it.
+     *
+     * The safety posture is UNCHANGED: all three are still SPARED, never auto-deleted. The only thing
+     * that changed is that wp-cleanup can now ask a question whose answer is knowable.
+     */
+    private classifySpared;
+    /**
+     * True when EVERY commit on the branch has a patch-equivalent already in origin/main.
+     *
+     * `git cherry origin/main <branch>` prints one line per commit: `+ <sha>` = not upstream,
+     * `- <sha>` = an equivalent change IS upstream. All-minus means the content landed (typically by
+     * cherry-pick or rebase-merge) even though the SHAs differ. Any failure returns false — "cannot
+     * prove the content is in main" must never read as "safe".
+     */
+    private contentAlreadyInMain;
+    /**
+     * Does this local branch exist? Used to prove a snapshot is not the last copy of its work — the
+     * base branch being present is that proof. Verifies it is a BRANCH (`refs/heads/`), not just any
+     * resolvable rev, so a tag or a stray SHA sharing the name cannot stand in for the base.
+     */
+    private branchExists;
+    private tipSha;
+    /**
+     * Commits on `branch` that are not on origin/main. Returns -1 ("assume it has work") whenever the
+     * count cannot be established — an unresolvable origin/main must never read as "empty branch".
+     */
+    private commitsAheadOfMain;
+    /**
+     * The ONE bulk network call. Every merged PR's head branch in a single round trip — no per-branch
+     * lookups. Fails SOFT: if `gh` is missing, unauthenticated, or offline we return [], which makes
+     * every branch a `keep`. The guard then deletes nothing rather than guessing.
+     */
+    private fetchMergedPrs;
+    /**
+     * The DISPLAY-only second lookup: every PR (any state) keyed by head branch, so a spared branch can
+     * be shown to a human as "PR #12 CLOSED (not merged)" or "no PR" instead of an opaque name. Kept
+     * SEPARATE from fetchMergedPrs on purpose — folding both into one `--state all` call would let a
+     * flood of open/closed PRs push older MERGED ones out of the limit and silently stop reaping real
+     * dead branches. Fails soft to an empty map: the verdicts do not depend on it.
+     */
+    private fetchPrStates;
+    private reviveList;
+    private reviveWorktrees;
+    private capture;
+}