@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/lib/git/branch-classifier.js

@@ -1,36 +1,6 @@
-/**
- * branch-classifier.js — answer "is this branch's work already in the default
- * branch?" for a repository that squash-merges.
- *
- * WHY THIS EXISTS: a squash-merge puts the WORK in `origin/master` while
- * leaving none of the branch's own commits reachable from it. So
- * `git branch --merged origin/master` does not list the branch, and
- * `git branch -d` refuses it as unmerged. The only remaining command is
- * `git branch -D`, which is byte-identical to the command that discards real,
- * never-integrated work — the tool gives the user no way to tell the two apart,
- * and after enough of these the habit becomes "just -D it", which is how work
- * gets lost.
- *
- * Every branch lands in exactly one class, and only the two MERGED ones are
- * ever deletable:
- *
- *   merged-ancestral — git itself proves it: the branch tip is an ancestor of
- *                      the default. A plain merge, or a fast-forward.
- *   merged-squash    — git cannot see it, but the evidence is positive: either
- *                      GitHub reports the PR as MERGED, or the branch's tree is
- *                      IDENTICAL to the default's (every change it carries is
- *                      already there under a different commit).
- *   open             — a PR is OPEN for it. Never deleted: the PR is the whole
- *                      reason the branch must survive.
- *   in-worktree      — checked out by a live worktree. Never deleted.
- *   unmerged         — none of the above could be PROVEN. This is the fail-safe
- *                      default and covers "no `gh`", "no origin", and "genuinely
- *                      unintegrated work" alike, because from here they are the
- *                      same thing: not proven integrated.
- *
- * Nothing here mutates. `pruneBranches` in commands/project/branch.js does the
- * deleting, and it deletes ONLY what this file classified as merged.
- */
+// A squash-merge leaves the work in the default branch but none of the branch's commits,
+// so `branch -d` refuses it and `-D` looks like discarding real work. Only the two
+// `merged-*` classes are deletable; anything not PROVEN integrated is `unmerged`.
 
 import { execFileSync } from 'child_process';
 
@@ -38,11 +8,7 @@ function git(args, cwd) {
   return execFileSync('git', args, { cwd, stdio: 'pipe' }).toString();
 }
 
-/**
- * Local branches with their tips. Excludes nothing — the caller decides.
- *
- * @returns {Array<{ name: string, sha: string, current: boolean, worktreePath: string|null }>}
- */
+/** @returns {Array<{ name: string, sha: string, current: boolean, worktreePath: string|null }>} */
 export function listLocalBranches(cwd) {
   try {
     const out = git(['for-each-ref', '--format=%(refname:short)%09%(objectname)%09%(HEAD)%09%(worktreepath)', 'refs/heads/'], cwd);
@@ -55,7 +21,6 @@ export function listLocalBranches(cwd) {
   }
 }
 
-/** Is `ancestor` reachable from `descendant`? False on any git error. */
 function isAncestor(ancestor, descendant, cwd) {
   try {
     git(['merge-base', '--is-ancestor', ancestor, descendant], cwd);
@@ -65,19 +30,8 @@ function isAncestor(ancestor, descendant, cwd) {
   }
 }
 
-/**
- * Does the branch introduce NOTHING the base does not already have?
- *
- * `git diff --quiet <base> <branch>` compares the two TREES: an empty diff
- * means every file the branch touched already reads exactly as the branch left
- * it in the base. That is precisely the state a squash-merge produces, and it
- * is a positive proof rather than an inference from history shape.
- *
- * Deliberately NOT `base...branch` (the three-dot form diffs against the merge
- * base, which for a squash-merged branch still shows the branch's own changes).
- *
- * Fail-CLOSED: any git error reads as "introduces something", never as merged.
- */
+// Two-dot tree diff, never `base...branch`: the three-dot form still shows a squash-merged
+// branch's own changes. Fail-closed: a git error never reads as merged.
 function treeIsIdentical(base, branch, cwd) {
   try {
     execFileSync('git', ['diff', '--quiet', base, branch], { cwd, stdio: 'pipe' });
@@ -87,13 +41,7 @@ function treeIsIdentical(base, branch, cwd) {
   }
 }
 
-/**
- * How many commits the branch carries that the base does not. Used only for
- * REPORTING — the classification never turns on it, because a squash-merged
- * branch legitimately has commits ahead while carrying no unintegrated work.
- *
- * @returns {number|null} null when it cannot be computed
- */
+/** Reporting only: a squash-merged branch legitimately has commits ahead. @returns {number|null} */
 export function commitsAhead(base, branch, cwd) {
   try {
     const out = git(['rev-list', '--count', `${base}..${branch}`], cwd).trim();
@@ -105,12 +53,8 @@ export function commitsAhead(base, branch, cwd) {
 }
 
 /**
- * Resolve the ref to compare against: `origin/<default>` when the remote-tracking
- * ref exists (the authority on what has actually landed), else the local branch.
- *
- * @returns {string|null} null when neither resolves — the caller must then
- *   classify everything as `unmerged`, because there is no baseline to prove
- *   integration against.
+ * `origin/<default>` when it exists, else the local branch.
+ * @returns {string|null} null = no baseline, so everything is `unmerged`.
  */
 export function resolveBaseRef(defaultBranch, cwd) {
   if (!defaultBranch) return null;
@@ -123,19 +67,8 @@ export function resolveBaseRef(defaultBranch, cwd) {
   return null;
 }
 
-/**
- * Classify one branch. Pure decision logic over already-gathered facts, so the
- * table above is testable without a GitHub account.
- *
- * ORDER IS THE POLICY, and the two protective classes come FIRST: a branch that
- * is checked out, or that carries an OPEN PR, is never deleted even if its tree
- * happens to match the base — a PR being open means a human still has business
- * with it.
- *
- * @param {object} b - from listLocalBranches
- * @param {{ baseRef: string|null, cwd: string, pr: {number:number,state:string}|null|undefined }} ctx
- * @returns {{ name: string, kind: string, reason: string, pr: number|null, ahead: number|null, deletable: boolean }}
- */
+// Order is the policy: checked-out and open-PR branches are protected before any
+// merged check, even when the tree matches the base.
 export function classifyBranch(b, { baseRef, cwd, pr }) {
   const prNum = pr?.number ?? null;
   const mk = (kind, reason, deletable) => ({
@@ -163,12 +96,6 @@ export function classifyBranch(b, { baseRef, cwd, pr }) {
   return mk('unmerged', `carrega mudanças que não estão em ${baseRef} e nenhum PR MERGED comprova o contrário`, false);
 }
 
-/**
- * Classify every local branch except the default itself.
- *
- * @param {{ cwd: string, defaultBranch: string|null, prIndex: Map|null }} ctx
- * @returns {Array} one entry per branch, in `for-each-ref` order
- */
 export function classifyBranches({ cwd, defaultBranch, prIndex }) {
   const baseRef = resolveBaseRef(defaultBranch, cwd);
   return listLocalBranches(cwd)

package/src/lib/git/default-branch.js

@@ -1,21 +1,5 @@
 import { execFileSync } from 'child_process';
 
-/**
- * Git helpers shared by `create` (which branches `morph/{f}` off the default)
- * and `finish` (which merges/PRs back into it). Kept tiny and pure so both
- * call sites read the same source of truth for "what is the default branch"
- * and "is there a remote to push to".
- */
-
-/**
- * Does a local branch exist? execFile (argv, never a cmd.exe string) so the
- * name reaches git as one token — the same anti-injection discipline the rest
- * of the worktree/finish path uses.
- *
- * @param {string} branch
- * @param {string} cwd
- * @returns {boolean}
- */
 function localBranchExists(branch, cwd) {
   try {
     execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd, stdio: 'pipe' });
@@ -26,26 +10,14 @@ function localBranchExists(branch, cwd) {
 }
 
 /**
- * Resolve the repository's default branch NAME (e.g. `main`), never assuming
- * `master`. Strategy, in order:
- *   1. `refs/remotes/origin/HEAD` symbolic ref — the remote's declared default,
- *      the authoritative answer when a remote is configured.
- *   2. A local `main`, then `master` — the fallback for a repo with no remote
- *      (or one whose `origin/HEAD` was never set).
- *
- * Returns `null` when none of these resolve (a repo whose default is some other
- * name, with no `origin/HEAD` set) — the caller decides: `create` fails open
- * (no branch), `finish` refuses with a clear message.
- *
- * @param {string} [cwd]
- * @returns {string|null} the default branch name, or null if undeterminable
+ * `origin/HEAD` first, then a local `main`, then `master`.
+ * @returns {string|null} null when none resolves; the caller decides.
  */
 export function detectDefaultBranch(cwd = process.cwd()) {
   try {
     const ref = execFileSync('git', ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'], { cwd, stdio: 'pipe' })
       .toString()
       .trim();
-    // e.g. "refs/remotes/origin/main" → "main"
     const m = ref.match(/^refs\/remotes\/origin\/(.+)$/);
     if (m && m[1]) return m[1];
   } catch { /* no origin/HEAD — fall back to a local default */ }
@@ -56,13 +28,6 @@ export function detectDefaultBranch(cwd = process.cwd()) {
   return null;
 }
 
-/**
- * Is an `origin` remote configured? `--pr` needs one to push the feature branch;
- * `--merge` is purely local and never calls this.
- *
- * @param {string} [cwd]
- * @returns {boolean}
- */
 export function hasOriginRemote(cwd = process.cwd()) {
   try {
     const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd, stdio: 'pipe' }).toString().trim();
@@ -72,18 +37,7 @@ export function hasOriginRemote(cwd = process.cwd()) {
   }
 }
 
-/**
- * Resolve HEAD's full commit SHA. Fail-open: null when cwd isn't a git repo,
- * or the repo has no commits yet (unborn HEAD) — never throws.
- *
- * Shared by `morph-spec verify` (the `verification` stamp) and
- * `morph-spec gate-check` (signals + staleness-vs-code checks) — both need
- * the exact commit a result covers, mirroring the same fail-open pattern
- * `reviewStaleness()` in approve.js uses for the same `git rev-parse HEAD` call.
- *
- * @param {string} [cwd]
- * @returns {string|null}
- */
+/** @returns {string|null} null outside a repo or on an unborn HEAD; never throws. */
 export function getHeadSha(cwd = process.cwd()) {
   try {
     return execFileSync('git', ['rev-parse', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
@@ -92,15 +46,6 @@ export function getHeadSha(cwd = process.cwd()) {
   }
 }
 
-/**
- * Parse `git diff --shortstat` output ("3 files changed, 45 insertions(+), 2
- * deletions(-)") into counts. Any line missing (e.g. only insertions, no
- * deletions) contributes 0 for that field. Empty input (no diff) is all-zero,
- * not an error.
- *
- * @param {string} text
- * @returns {{ filesChanged: number, insertions: number, deletions: number }}
- */
 function parseShortstat(text) {
   const files = /(\d+) files? changed/.exec(text || '');
   const ins = /(\d+) insertions?\(\+\)/.exec(text || '');
@@ -112,33 +57,10 @@ function parseShortstat(text) {
   };
 }
 
-/**
- * Count brand-new UNTRACKED files (never `git add`-ed) — the gap plain
- * `git diff --shortstat` never sees, tracked-edits-only by design. Fail-open:
- * any error (not a repo, git missing) reads as 0 untracked, never throws —
- * this must not take down the whole `getDiffStat` result over a probe that
- * is secondary to the diff itself.
- *
- * `--exclude-standard` matches gitignore the same way `git status` does, so
- * scratch/build output never inflates the count.
- *
- * @param {string} cwd
- * @returns {number}
- */
 function countUntrackedFiles(cwd) {
   return listUntrackedFiles(cwd).length;
 }
 
-/**
- * Split git's stdout into clean, forward-slashed, non-empty path lines.
- *
- * One helper for both probes because the two disagreeing about what a "line" is
- * — a stray `\r` on Windows, a trailing empty line — would make the count and
- * the listing describe different sets from the same output.
- *
- * @param {string} text
- * @returns {string[]}
- */
 function splitLines(text) {
   return String(text)
     .split('\n')
@@ -146,25 +68,8 @@ function splitLines(text) {
     .filter(Boolean);
 }
 
-/**
- * The brand-new UNTRACKED files, by NAME — the listing behind
- * {@link countUntrackedFiles}, and the second half of {@link changedPathsAgainst}.
- *
- * The two callers need the same fact at different resolutions, and this is the
- * ONLY place the probe is spelled: `git diff` never shows a file that was never
- * `git add`-ed, regardless of ref or working-tree mode, so anything that answers
- * "what changed" has to ask twice. A second copy of this command is exactly how
- * the invisible-new-file bug would come back on one caller and not the other.
- *
- * `--exclude-standard` honours gitignore the way `git status` does, so build
- * output never inflates either answer.
- *
- * Fail-open to `[]`: this probe is secondary to the diff and must never take the
- * whole result down.
- *
- * @param {string} cwd
- * @returns {string[]}
- */
+// `git diff` never shows a file that was never `git add`-ed, so every "what changed"
+// answer asks here too. The only spelling of this probe: a copy is how one caller goes blind.
 function listUntrackedFiles(cwd) {
   try {
     return splitLines(
@@ -176,29 +81,8 @@ function listUntrackedFiles(cwd) {
 }
 
 /**
- * `git diff --shortstat <baseRef>` against the CURRENT WORKING TREE (tracked
- * edits — staged, unstaged, and everything committed since baseRef —
- * deliberately not `baseRef...HEAD`, so a gate-check mid-implement still sees
- * uncommitted work), PLUS a count of brand-new UNTRACKED files (never
- * `git add`-ed) that plain `git diff` never shows regardless of commit vs
- * working tree. `filesChanged` is the combined total (tracked-changed +
- * untracked) so a caller reading just that one number gets the true scope of
- * what changed; `untrackedFiles` is broken out separately so a caller that
- * cares CAN tell diff-vs-new apart instead of the two being silently fused.
- *
- * Both git calls run with the same `cwd` — every current caller passes a
- * feature/worktree root there, so `git diff`'s repo-wide default and
- * `git ls-files`'s cwd-relative listing agree; a caller passing a
- * sub-directory as `cwd` would see `untrackedFiles` scoped to that
- * sub-directory while `insertions`/`deletions` stay repo-wide — not a
- * concern today, but worth knowing if that assumption ever changes.
- *
- * Fail-open: null when `baseRef` is falsy, cwd isn't a git repo, or the diff
- * itself fails (e.g. baseRef doesn't resolve). The untracked probe fails open
- * on its own (see countUntrackedFiles) and never turns a good diff into null.
- *
- * @param {string|null} baseRef - typically `detectDefaultBranch(cwd)`
- * @param {string} [cwd]
+ * Diff against the WORKING TREE (not `baseRef...HEAD`), so uncommitted work counts.
+ * `filesChanged` includes untracked files; `untrackedFiles` breaks them out.
  * @returns {{ filesChanged: number, insertions: number, deletions: number, untrackedFiles: number }|null}
  */
 export function getDiffStat(baseRef, cwd = process.cwd()) {
@@ -214,35 +98,9 @@ export function getDiffStat(baseRef, cwd = process.cwd()) {
 }
 
 /**
- * Every path this working tree CHANGED against `baseRef` — tracked edits plus
- * brand-new untracked files.
- *
- * WHY IT LIVES BESIDE getDiffStat, AND REUSES ITS UNTRACKED PROBE
- *
- * The two answer the same question at different resolutions ("how much changed"
- * versus "what changed"), and both depend on the SAME fragile fact: `git diff`
- * is tracked-edits-only, so a brand-new file is invisible to it no matter which
- * ref is named. `getDiffStat`'s docblock has documented that for a while; a
- * second copy of the probe here is precisely how the "new file is invisible"
- * bug comes back on one of the two call sites and not the other. So
- * `countUntrackedFiles`'s command is not retyped — the listing is.
- *
- * `git diff --name-only <baseRef>` against the WORKING TREE, deliberately not
- * `baseRef...HEAD`: a gate-check in the middle of implement must see work that
- * is not committed yet. Someone who has only staged the prompt change has still
- * changed the prompt.
- *
- * FAIL-OPEN, and the caller must know what that means. `[]` comes back both for
- * "nothing changed" and for "the ref did not resolve", exactly like
- * `getDiffStat` returning null. The distinction that MATTERS to the caller is a
- * different one — "the project declares no watched path" versus "it declares
- * some and none were touched" — and that one is answered by the caller's own
- * `declared` flag, never by the emptiness of this array.
- *
- * @param {string|null} baseRef - typically `detectDefaultBranch(cwd)`
- * @param {string} [cwd]
- * @returns {string[]} Repo-relative paths with forward slashes, deduplicated,
- *   sorted. Empty when `baseRef` is falsy, cwd is not a repo, or the diff fails.
+ * Paths changed in the working tree against `baseRef`, untracked included, sorted.
+ * `[]` means both "nothing changed" and "ref did not resolve".
+ * @returns {string[]}
  */
 export function changedPathsAgainst(baseRef, cwd = process.cwd()) {
   if (!baseRef) return [];
@@ -253,8 +111,6 @@ export function changedPathsAgainst(baseRef, cwd = process.cwd()) {
       execFileSync('git', ['diff', '--name-only', baseRef], { cwd, stdio: 'pipe' }).toString()
     );
   } catch {
-    // A baseRef that does not resolve is not a reason to claim "nothing
-    // changed" loudly — the caller's policy is written to be inert on `[]`.
     return [];
   }
 
@@ -262,21 +118,10 @@ export function changedPathsAgainst(baseRef, cwd = process.cwd()) {
 }
 
 /**
- * The lines this working tree ADDED against `baseRef`, per file: the new-side
- * line numbers of `git diff -U0`, plus every brand-new untracked file whole
- * (the same probe as {@link changedPathsAgainst}).
- *
- * Measured from the merge-base, not the tip: a default branch that moved on
- * after the feature branched must not lend its edits to the feature. `-M`
- * keeps a moved file from reading as added. `--relative` gives paths relative
- * to `cwd` and drops what lies outside it, the same base as the untracked
- * listing: a project in a subfolder of the repo reads its own files.
- *
- * @param {string|null} baseRef - typically `detectDefaultBranch(cwd)`
- * @param {string} [cwd]
- * @returns {Map<string, number[]|null>|null} path → added line numbers, or
- *   `null` for a whole untracked file. `null` (not an empty map) when it cannot
- *   tell: falsy or unresolvable ref, not a repo, diff failed.
+ * Added lines per file, measured from the merge-base so a moved-on default branch
+ * lends nothing; paths relative to `cwd` (`--relative`), like the untracked listing.
+ * @returns {Map<string, number[]|null>|null} `null` value = whole untracked file;
+ *   `null` result = cannot tell.
  */
 export function addedLinesAgainst(baseRef, cwd = process.cwd()) {
   if (!baseRef) return null;

package/src/lib/git/evidence-staleness.js

@@ -7,7 +7,7 @@ const CONFIG_PATH = '.morph/config/config.json';
 
 const gitOut = (cwd, args) => execFileSync('git', args, { cwd, stdio: 'pipe', maxBuffer: 64 * 1024 * 1024 }).toString();
 
-function withoutBaseline(text) {
+export function withoutBaseline(text) {
   const config = JSON.parse(text);
   if (Array.isArray(config?.project?.tests)) {
     for (const node of config.project.tests) delete node?.expectedCount;
@@ -31,6 +31,7 @@ export function treeMovedSince(cwd, sha, head = getHeadSha(cwd)) {
   if (!sha || !head || sha === head) return false;
   let changed;
   try {
+    // Without --no-renames a file moved into .morph/ shows only its new path and the deletion outside is lost.
     changed = gitOut(cwd, ['diff', '--name-only', '--no-renames', '-z', sha, head]).split('\0').filter(Boolean);
   } catch {
     return true;

package/src/lib/git/gh.js

@@ -1,21 +1,6 @@
 /**
- * gh.js — como o `gh` é invocado, num lugar só.
- *
- * Extraído de `finish.js`, onde nasceu, porque o `pr-index.js` chamava `'gh'`
- * cru: o caminho de SUCESSO do índice era intestável, já que não havia por
- * onde injetar um stub. Duas formas de chamar o mesmo binário também são duas
- * formas de discordar sobre qual binário é.
- */
-
-/**
- * Resolve a invocação do `gh`. Por padrão, o `gh` do PATH. Sobrescrevível via
- * MORPH_GH_BIN: uma string simples nomeia outro binário (um wrapper corporativo,
- * `hub`, …); um array JSON é um prefixo de argv COMPLETO — por exemplo
- * `["/path/to/node","/path/to/gh-shim.js"]` — que é como os testes injetam um
- * stub cross-platform que o execFileSync consegue spawnar (Node ≥20 recusa
- * rodar shims `.cmd`/`.bat` sem `shell:true`, e `shell:true` reabriria o buraco
- * de injeção de argumento que estes caminhos evitam).
- *
+ * MORPH_GH_BIN: string = outro binário; array JSON = prefixo de argv completo
+ * (Node ≥20 recusa shim `.cmd` sem `shell:true`, e `shell:true` reabre injeção de argumento).
  * @returns {{ bin: string, prefix: string[] }}
  */
 export function resolveGh() {

package/src/lib/git/pending-prs.js

@@ -1,60 +1,29 @@
-/**
- * pending-prs.js — as features que existem SÓ como PR aberto.
- *
- * `finish --pr` deixa o root primário sem vestígio da feature: o
- * `shedRootFeatureScope` apaga `.morph/features/{f}` e o archive foi commitado
- * na branch `morph/{f}`, chegando na default apenas no merge. Entre abrir e
- * mergear, portanto, nenhuma superfície local sabe que aquela branch tem dono —
- * foi assim que uma branch com PR #51 aberto quase foi varrida.
- *
- * Este módulo devolve o dono. Não há estado persistido a consultar, e é de
- * propósito: o PR aberto no GitHub É o registro, a branch é sempre
- * `morph/{feature}`, e o `pr-index.js` já é o leitor único desse fato. Lembrar
- * o número numa segunda cópia só criaria como divergir dele.
- *
- * `null` (do índice ou daqui) significa DESCONHECIDO e jamais "não há
- * pendência" — a mesma regra que torna seguros os caminhos destrutivos que
- * leem o índice.
- */
+// Depois do `finish --pr` a raiz não guarda nada da feature até o merge: o PR aberto
+// é o único registro de que a branch tem dono. `null` = DESCONHECIDO, nunca "sem pendência".
 
 import { existsSync } from 'fs';
 import { join } from 'path';
 import { buildPrIndex } from './pr-index.js';
 
-/** As branches que o framework cria por feature. */
 export const MORPH_BRANCH_RE = /^morph\/(.+)$/;
 
 const DAY_MS = 86400000;
 
-/**
- * O PR da branch canônica de uma feature.
- *
- * @param {Map<string,object>|null} index - de buildPrIndex
- * @param {string} feature
- * @returns {{number:number,state:string,mergedAt:string|null,url:string|null,createdAt:string|null}|null}
- *   null = desconhecido OU sem PR; quem precisa distinguir os dois olha o índice.
- */
+/** @returns {object|null} null = desconhecido OU sem PR; quem precisa distinguir olha o índice. */
 export function prForFeature(index, feature) {
   if (!index) return null;
   return index.get(`morph/${feature}`) || null;
 }
 
-/** A feature tem pasta (ativa ou arquivada) nesta árvore? */
 function hasLocalFolder(root, feature) {
   return existsSync(join(root, '.morph', 'features', feature))
     || existsSync(join(root, '.morph', 'archive', feature));
 }
 
 /**
- * As features aguardando merge: PR OPEN numa branch `morph/*` cujo slug não
- * tem pasta nesta árvore.
- *
- * @param {string} root - a raiz a inspecionar (e de onde o `gh` roda)
- * @param {{ index?: Map<string,object>|null, now?: Date }} [opts]
- *   `index` injeta um índice já construído (o `list`/`fleet` constroem um por
- *   processo e reaproveitam; os testes passam um sintético). Ausente = constrói.
- * @returns {Array<{feature:string,branch:string,number:number,state:string,url:string|null,createdAt:string|null,ageDays:number|null}>|null}
- *   null = DESCONHECIDO. Nunca lista vazia por falta de informação.
+ * PR OPEN numa branch `morph/*` cujo slug não tem pasta nesta árvore.
+ * @param {{ index?: Map<string,object>|null, now?: Date }} [opts] `index` ausente = constrói.
+ * @returns {Array<object>|null} null = DESCONHECIDO, nunca lista vazia por falta de informação.
  */
 export function pendingPrFeatures(root, opts = {}) {
   const index = opts.index !== undefined ? opts.index : buildPrIndex(root);

package/src/lib/git/pr-files.js

@@ -1,37 +1,12 @@
-/**
- * pr-files.js — o diff de um PR carregou uma feature morph-spec?
- *
- * `morph/{f}` é a convenção de nome das branches que o framework cria, não
- * prova de que a branch carregou uma feature: nada impede um PR só de docs
- * numa `morph/x`. O `doctor` lia o nome como prova e acusava
- * `pr-merged-not-landed` para sempre sobre PRs que nunca tiveram archive para
- * pousar (medido no MORPH_GHLBrain: #5, um único `docs/*.md`, e #23, a onda 2
- * de outra feature — nenhum caminho `.morph/` no diff de nenhum dos dois).
- *
- * A pergunta é feita ao diff, e só para o candidato: o `doctor` chama isto
- * depois de já saber que o PR mergeou e que `archive/{f}` falta aqui, então o
- * custo (~650 ms por `gh pr view`) não recai sobre quem não tem pendência. O
- * índice (`pr-index.js`) segue sem o campo de propósito: pedir `mergeCommit` no
- * `pr list` custou ~400 ms a mais em CADA chamada, paga pelos quatro leitores.
- *
- * Três respostas, nunca duas: `true` (o diff tocou `.morph/{features,archive}/{f}/`),
- * `false` (o diff foi lido inteiro e não tocou) e `null` (DESCONHECIDO — sem
- * `gh`, falha, JSON ilegível, ou o diff bateu no teto de arquivos do `gh` sem
- * achar). Só `false` autoriza calar um aviso.
- */
-
 import { execFileSync } from 'child_process';
 import { resolveGh } from './gh.js';
 
-/** Quantos arquivos o `gh pr view --json files` devolve, no máximo. */
 export const GH_FILES_CAP = 100;
 
 /**
- * @param {string} root - de onde o `gh` roda (resolve o repositório pelo origin)
- * @param {number} number - número do PR
- * @param {string} feature - o `{f}` de `morph/{f}`
- * @param {{ timeout?: number }} [opts]
- * @returns {boolean|null} null = DESCONHECIDO, nunca "não carregou"
+ * Uma branch `morph/{f}` não prova que o PR carregou a feature: só o diff tocando
+ * `.morph/{features,archive}/{f}/` prova.
+ * @returns {boolean|null} null = DESCONHECIDO; só `false` autoriza calar um aviso.
  */
 export function prCarriesFeature(root, number, feature, opts = {}) {
   const timeout = opts.timeout ?? 8000;

package/src/lib/git/pr-index.js

@@ -1,42 +1,11 @@
-/**
- * pr-index.js — one `gh pr list` per process, shared by every caller that needs
- * to answer "does a branch have a PR, and in what state".
- *
- * Extracted from `fleet-scanner.js` because three independent leaders now ask
- * the SAME question and must get the SAME answer:
- *
- *   • `morph-spec fleet`        — the PR column
- *   • `morph-spec branch prune` — a branch with an OPEN PR is never deleted,
- *                                 and a MERGED one is deletable even when git
- *                                 cannot see the merge (squash-merge)
- *   • `morph-spec doctor --worktrees` — a worktree whose branch carries an open
- *                                 PR must NOT be offered up for removal
- *
- * Fail-open by construction: no `gh`, not authenticated, not GitHub, or a
- * timeout all yield `null`. `null` means "unknown", NEVER "no PR" — every
- * caller must treat the two differently, because the destructive paths
- * (prune, remove) are only safe when the answer is a positive fact.
- */
-
 import { execFileSync } from 'child_process';
 import { resolveGh } from './gh.js';
 
 /**
- * Build the branch → PR index for a repository.
- *
- * Gated on the origin URL actually pointing at github.com: `gh` against any
- * other host is a guaranteed error, and paying its start-up cost to learn that
- * on every call is pure latency.
- *
- * `--state all` on purpose: a MERGED PR is exactly the evidence a squash-merge
- * erases from git history, and it is the whole reason `branch prune` exists.
- * First wins — `gh` lists newest-first, so an OPEN PR shadows an older closed
- * one on the same branch.
- *
- * @param {string} root - repository root to run `gh` from
- * @param {{ limit?: number, timeout?: number }} [opts]
+ * Branch → PR. `--state all`: a MERGED PR is the evidence a squash-merge erases from git.
+ * `gh` lists newest-first, so the first entry per branch wins.
  * @returns {Map<string,{number:number,state:string,mergedAt:string|null,url:string|null,createdAt:string|null}>|null}
- *   null = DESCONHECIDO (sem gh / não é GitHub / falhou), não "sem PRs"
+ *   null = unknown, NEVER "no PR": destructive callers act only on a positive fact.
  */
 export function buildPrIndex(root, opts = {}) {
   const limit = String(opts.limit ?? 200);