@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

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

@@ -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);

package/src/lib/git/tree-fingerprint.js

@@ -1,9 +1,5 @@
-/**
- * A hash of what a verify run reads: the committed tree, the uncommitted changes and the
- * untracked files, plus `config.json` without `expectedCount` (it names the test commands).
- * The rest of `.morph/` stays out, as in `treeMovedSince`: committing verify's own
- * bookkeeping must not make the same code look different.
- */
+// `.morph/` stays out except `config.json` minus `expectedCount`, as in `treeMovedSince`:
+// committing verify's own bookkeeping must not make the same code look different.
 
 import { execFileSync } from 'child_process';
 import { createHash } from 'crypto';
@@ -11,33 +7,25 @@ import { existsSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
 import { withoutBaseline } from './evidence-staleness.js';
 
-/** Pathspec for "the project minus its `.morph/` bookkeeping". */
 export const OUTSIDE_MORPH = ['--', '.', ':(exclude).morph'];
 const MAX_OUTPUT = 64 * 1024 * 1024;
 
-/** git output as a Buffer; stderr dropped, throws on a non-zero exit. */
 export function git(projectPath, args, input) {
   return execFileSync('git', args, {
     cwd: projectPath, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'ignore'], maxBuffer: MAX_OUTPUT, input,
   });
 }
 
-/**
- * @param {string} projectPath
- * @returns {string|null} sha256 hex, or null outside a git repo / on any git error
- */
+/** @returns {string|null} sha256 hex, or null outside a git repo / on any git error */
 export function treeFingerprint(projectPath) {
   try {
     const hash = createHash('sha256');
     let head = null;
     try { head = git(projectPath, ['rev-parse', 'HEAD']).toString().trim(); } catch { /* no commit yet */ }
-    // Tree ids are content-addressed: the top-level entries minus .morph change only with code.
     const tree = head
       ? git(projectPath, ['ls-tree', '-z', 'HEAD']).toString().split('\0').filter((e) => e && e.split('\t')[1] !== '.morph')
       : ['no-commit'];
     hash.update(`tree\0${tree.join('\0')}\0`);
-    // Before the first commit there is no HEAD to diff against: every file is
-    // untracked, and the listing below covers them.
     if (head) hash.update(git(projectPath, ['diff', 'HEAD', '--binary', ...OUTSIDE_MORPH]));
     hash.update('\0untracked\0');
     const untracked = git(projectPath, ['ls-files', '--others', '--exclude-standard', '-z', ...OUTSIDE_MORPH])

package/src/lib/git/tree-state.js

@@ -1,17 +1,9 @@
-/**
- * The working tree as the orchestrator needs it when it takes control back
- * from a dispatch, in one call instead of `git status` + `git diff --stat` +
- * `git log` + a marker grep. Everything is read outside `.morph/`, the same
- * cut the tree fingerprint makes.
- */
-
 import { existsSync } from 'fs';
 import { join } from 'path';
 import { OUTSIDE_MORPH, treeFingerprint, git as gitBuffer } from './tree-fingerprint.js';
 import { detectDefaultBranch } from './default-branch.js';
 import { resolveBaseRef } from './branch-classifier.js';
 
-/** What the verifier writes next to a mutation it has not reverted yet. */
 export const MUTATION_MARKER = 'MUTACAO';
 const MAX_LISTED = 50;
 const MAX_COMMITS = 10;
@@ -24,13 +16,11 @@ function headSha(cwd) {
   try { return git(cwd, ['rev-parse', 'HEAD']).trim(); } catch { return null; }
 }
 
-/** Every file that differs from HEAD outside `.morph/`, untracked ones one by one. */
 function changedFiles(cwd) {
   return parsePorcelain(git(cwd, ['status', '--porcelain=v1', '-z', '--untracked-files=all', ...OUTSIDE_MORPH]))
     .map((e) => e.path);
 }
 
-/** Blob id of each file as it is on disk; null for a file that is gone. */
 function diskBlobs(cwd, paths) {
   const present = paths.filter((p) => existsSync(join(cwd, p)));
   const ids = present.length ? git(cwd, ['hash-object', '--stdin-paths'], present.join('\n')).split('\n') : [];
@@ -39,7 +29,6 @@ function diskBlobs(cwd, paths) {
   return out;
 }
 
-/** Blob id of each path in a commit; null where the commit does not have it. */
 function commitBlobs(cwd, commit, paths) {
   const out = Object.fromEntries(paths.map((p) => [p, null]));
   if (!commit || !paths.length) return out;
@@ -49,10 +38,8 @@ function commitBlobs(cwd, commit, paths) {
 }
 
 /**
- * What the tree is before a dispatch whose work must leave it unchanged (the
- * verifier mutates and reverts): HEAD plus the blob of every file that
- * differs from it. Kept on disk, so a session that resumes after the agent
- * died compares against the tree before the dispatch, not its own start.
+ * HEAD plus the blob of every file that differs from it, kept on disk so a resumed
+ * session compares against the tree before the dispatch, not its own start.
  * @returns {{ at: string, head: string|null, files: Object<string, string|null> }|null}
  */
 export function snapshotTree(cwd) {
@@ -64,9 +51,8 @@ export function snapshotTree(cwd) {
 }
 
 /**
- * Files whose content on disk is not what it was in the snapshot. Content,
- * not status: a mutation committed since shows up, and a file committed
- * unchanged does not.
+ * Compares content, not status: a mutation committed since shows up, and a file
+ * committed unchanged does not.
  * @returns {{ at: string, headChanged: boolean, changed: string[], changedCount: number }}
  */
 export function compareToSnapshot(cwd, snapshot) {
@@ -85,7 +71,7 @@ export function compareToSnapshot(cwd, snapshot) {
   return { at: snapshot.at, headChanged: snapshot.head !== head, changed: changed.slice(0, MAX_LISTED), changedCount: changed.length };
 }
 
-/** `git status --porcelain -z`: a rename carries its old path as an extra entry. */
+// With `-z`, a rename or copy carries its old path as an extra entry.
 function parsePorcelain(out) {
   const entries = [];
   const parts = out.split('\0');
@@ -118,7 +104,6 @@ function commitsOnTop(cwd) {
     .split('\n').filter(Boolean);
 }
 
-/** Untracked files count too; gitignored ones (build output) do not. */
 function markers(cwd) {
   try {
     const out = git(cwd, ['grep', '-n', '-I', '--untracked', '-F', '-e', MUTATION_MARKER, ...OUTSIDE_MORPH]);
@@ -132,19 +117,7 @@ function markers(cwd) {
   }
 }
 
-/**
- * @param {string} cwd
- * @param {{ snapshot?: object|null }} [opts] - a `snapshotTree()` to compare with
- * @returns {{ head: string|null, branch: string|null, fingerprint: string|null,
- *   dirty: {status: string, path: string}[], dirtyCount: number,
- *   diffstat: {files: number, insertions: number, deletions: number}|null,
- *   commits: string[]|null, markers: {file: string, line: number}[],
- *   sinceBeforeEval: ReturnType<typeof compareToSnapshot>|null }|null}
- *   null when git cannot answer (outside a repo, or an error): unknown, never
- *   a clean tree. `commits` is null when there is no default branch to count
- *   from; `diffstat` is null before the first commit; `sinceBeforeEval` is
- *   null without a snapshot.
- */
+/** @returns {object|null} null when git cannot answer: unknown, never a clean tree. */
 export function treeState(cwd, { snapshot = null } = {}) {
   try {
     const dirty = parsePorcelain(git(cwd, ['status', '--porcelain=v1', '-z', ...OUTSIDE_MORPH]));

package/src/lib/graph/god-nodes.js

@@ -1,31 +1,11 @@
-/**
- * God nodes e comunidades para o contexto de arquitetura.
- *
- * O inventário do architecture-scanner diz o que EXISTE; os god nodes dizem o
- * que é CENTRAL. No ProspectPRO, seis linhas (`Result` 223, `Abstractions` 217,
- * `Repository` 156, `cn()` 141) orientam melhor que 665 de inventário — sem
- * substituí-lo, porque exaustividade é um valor que o grafo não tem.
- *
- * Só entram nós COM source_file: um god node sem arquivo não orienta ninguém.
- * E nada de teste: dublês e fixtures estão no grafo para serem achados, não
- * para disputar centralidade — sem o filtro o `FakeGhlToolbelt` entra no top
- * 10 do MORPH_GHLBrain e as arestas vindas de teste inflam o grau de `Result`
- * de 380 para 443. Aresta com uma ponta em teste não conta para ninguém, e
- * comunidade só de teste some da lista.
- *
- * @module god-nodes
- */
+// Só nós com source_file, e nada de teste: dublês e fixtures estão no grafo para serem achados, não para
+// disputar centralidade. Aresta com uma ponta em teste não conta, e comunidade só de teste some.
 import { loadGraph } from './graph-loader.js';
 import { buildIndex, resolveEdgeTarget, linksOf, isTestPath } from './sanitize.js';
 
 /** Sem `graphify label`, as comunidades se chamam Community_N — ruído puro. */
 const PLACEHOLDER_LABEL = /^Community[_ ]?\d+$/i;
 
-/**
- * @param {string} projectPath
- * @param {{top?: number, topCommunities?: number}} [opts]
- * @returns {Promise<{available: boolean, godNodes: Array<{label: string, source_file: string, degree: number}>, communities: Array<{id: number, label: string, size: number, labeled: boolean}>}>}
- */
 export async function scanGraph(projectPath, opts = {}) {
   const top = opts.top ?? 10;
   const topCommunities = opts.topCommunities ?? 10;