@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/framework/hooks/shared/git-paths.js

@@ -1,47 +1,10 @@
-/**
- * git-paths.js — pure-filesystem git common-dir resolution (no subprocess).
- *
- * `telemetry-log.js`'s claim heartbeat used to pay `execSync('git rev-parse
- * --git-common-dir')` on every tool call to learn where `claims.json` lives —
- * a ~34ms subprocess spawn, wasted on ~99% of calls because the heartbeat
- * write itself is throttled (see `claim-registry.js`'s `shouldHeartbeat`).
- * This module answers the SAME question — mirroring `git rev-parse
- * --git-common-dir` — by reading the two on-disk shapes git itself uses,
- * without spawning `git` at all:
- *
- *   1. PRIMARY checkout: `<root>/.git` is a DIRECTORY. That directory IS the
- *      common dir. (A directory `.git` is never a linked worktree's own —
- *      git always represents a worktree's `.git` as a FILE — so this case is
- *      unambiguous.)
- *   2. LINKED WORKTREE (`git worktree add`): `<root>/.git` is a FILE
- *      containing `gitdir: <path>`, pointing at this worktree's PRIVATE
- *      gitdir (normally `<primary>/.git/worktrees/<name>`). Inside that
- *      private gitdir, a `commondir` file holds a path — relative to the
- *      private gitdir, or absolute — to the real common dir (normally
- *      `../..`, i.e. back up to `<primary>/.git`).
- *
- * Verified against a real `git worktree add` fixture: `commondir` held
- * `../..`, `.git`'s `gitdir:` line held an absolute path, and the resolved
- * result matched `git rev-parse --git-common-dir` exactly (see
- * `test/hooks/git-paths.test.js`, which asserts that parity directly rather
- * than against a hand-computed path).
- *
- * Fail-open: any missing file, unreadable path, or shape that doesn't match
- * either case above resolves to `null`. Callers must treat `null` as "not
- * resolvable right now" and skip whatever git-dependent step they were
- * guarding — never throw.
- */
+// Answers `git rev-parse` questions from the on-disk shapes git uses, without spawning git:
+// a primary checkout's `.git` is a DIRECTORY, a linked worktree's is a FILE holding `gitdir:`.
+// Every unreadable or unknown shape resolves to `null`, never a throw.
 
 import { readFileSync, statSync } from 'fs';
 import { dirname, isAbsolute, join, resolve } from 'path';
 
-/**
- * Find the nearest `.git` entry (file or directory) at or above `startDir`,
- * climbing exactly like git itself does to find the repo root.
- *
- * @param {string} startDir
- * @returns {{ path: string, isDirectory: boolean }|null}
- */
 function findDotGit(startDir) {
   let dir = resolve(startDir);
   for (;;) {
@@ -50,21 +13,13 @@ function findDotGit(startDir) {
       const st = statSync(candidate);
       return { path: candidate, isDirectory: st.isDirectory() };
     } catch {
-      // not here — keep climbing
     }
     const parent = dirname(dir);
-    if (parent === dir) return null; // reached the filesystem root
+    if (parent === dir) return null;
     dir = parent;
   }
 }
 
-/**
- * A linked worktree's `.git` FILE holds `gitdir: <path>` (absolute or relative
- * to the file) pointing at its private gitdir. `null` when the line is absent.
- *
- * @param {string} dotGitFile
- * @returns {string|null}
- */
 function privateGitDirOf(dotGitFile) {
   const match = readFileSync(dotGitFile, 'utf8').match(/^gitdir:\s*(.+?)\s*$/m);
   if (!match) return null;
@@ -73,15 +28,7 @@ function privateGitDirOf(dotGitFile) {
 
 const MORPH_BRANCH = /^ref:\s*refs\/heads\/morph\/([A-Za-z0-9._-]+)\s*$/;
 
-/**
- * The feature a checkout is bound to by its branch `morph/<feature>`, read from
- * `<root>/.git` exactly (no climbing) — the primary's `.git/HEAD` or, for a
- * linked worktree, `<gitdir>/HEAD`. `null` for any other branch (`morph-task/*`
- * included), a detached HEAD, or no `.git` at `root`.
- *
- * @param {string} root
- * @returns {string|null}
- */
+/** Reads `<root>/.git` exactly, without climbing; `null` for any branch other than `morph/<feature>`. */
 export function morphBranchFeature(root) {
   try {
     const dotGit = join(root, '.git');
@@ -94,22 +41,7 @@ export function morphBranchFeature(root) {
   }
 }
 
-/**
- * Is `startDir` inside a LINKED (secondary) worktree?
- *
- * Same on-disk fact `resolveGitCommonDir` reads: git represents a linked
- * worktree's `.git` as a FILE holding a `gitdir:` pointer, and a primary
- * checkout's `.git` as a DIRECTORY. The e2e isolation rule keys on this —
- * a compose that cannot be isolated is a hard failure only where a second
- * stack could actually collide with the primary's (see e2e-check.js
- * `decideIsolation`).
- *
- * Fail-open: outside any repo, or on an unreadable path, answers `false` —
- * the lenient direction (warn instead of fail).
- *
- * @param {string} startDir
- * @returns {boolean}
- */
+/** Outside any repo or on an unreadable path, answers `false`: the lenient direction for e2e isolation. */
 export function isSecondaryWorktree(startDir) {
   try {
     const found = findDotGit(startDir);
@@ -119,14 +51,6 @@ export function isSecondaryWorktree(startDir) {
   }
 }
 
-/**
- * Top of the working tree that contains `startDir` — the directory holding the
- * nearest `.git` (file or directory), which is what `git rev-parse
- * --show-toplevel` answers, without the subprocess. `null` outside any repo.
- *
- * @param {string} startDir
- * @returns {string|null}
- */
 export function workTreeTop(startDir) {
   try {
     const found = findDotGit(startDir);
@@ -136,16 +60,7 @@ export function workTreeTop(startDir) {
   }
 }
 
-/**
- * Resolve the git COMMON dir for `startDir` — pure filesystem, no subprocess.
- * Always returns an absolute path (unlike `git rev-parse --git-common-dir`,
- * which returns a path relative to the CALLER's cwd when run from the
- * primary checkout — callers of this function never need their own
- * `resolve(cwd, ...)` step afterward).
- *
- * @param {string} startDir
- * @returns {string|null}
- */
+/** Always absolute, unlike `git rev-parse --git-common-dir`, which is relative to the caller's cwd in the primary. */
 export function resolveGitCommonDir(startDir) {
   try {
     const found = findDotGit(startDir);
@@ -158,8 +73,6 @@ export function resolveGitCommonDir(startDir) {
     const privateGitDir = privateGitDirOf(found.path);
     if (!privateGitDir) return null;
 
-    // Inside the private gitdir, `commondir` points (relative to itself, or
-    // absolute) at the real common dir.
     const commonRaw = readFileSync(join(privateGitDir, 'commondir'), 'utf8').trim();
     if (!commonRaw) return null;
     return isAbsolute(commonRaw) ? commonRaw : resolve(privateGitDir, commonRaw);
@@ -170,15 +83,7 @@ export function resolveGitCommonDir(startDir) {
 
 const SHA = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
 
-/**
- * The commit HEAD points at in the PRIMARY checkout `root`, read from disk —
- * `git rev-parse HEAD` without the subprocess: a detached SHA, or the branch's
- * loose ref, then `packed-refs`. `null` for every shape it does not read (a
- * linked worktree, reftable, a branch with no commit yet): the caller asks git.
- *
- * @param {string} root
- * @returns {string|null}
- */
+/** `null` for every shape it does not read (linked worktree, reftable, unborn branch): the caller asks git. */
 export function readPrimaryHead(root) {
   try {
     const gitDir = join(root, '.git');
@@ -191,7 +96,6 @@ export function readPrimaryHead(root) {
       const loose = readFileSync(join(gitDir, ref), 'utf8').trim();
       if (SHA.test(loose)) return loose;
     } catch {
-      // not loose — packed
     }
     for (const line of readFileSync(join(gitDir, 'packed-refs'), 'utf8').split(/\r?\n/)) {
       const [sha, name] = line.split(' ');

package/framework/hooks/shared/graph-freshness.js

@@ -1,41 +1,6 @@
-/**
- * graph-freshness.js — a regra ÚNICA de "o grafo desta árvore está em dia".
- *
- * Todo mundo que pergunta lê daqui: o refresh em background
- * (graph-refresh.js, decide se roda), o `graph status|explain|affected` e o
- * `doctor` (via src/lib/graph/graph-loader.js `getFreshness`) e o
- * `graph build|refresh` (grava o resultado). Mora em hooks/shared porque hook
- * não importa `src/`. Uma segunda cópia da regra é como o status dizia
- * "fresco" enquanto o refresh achava "velho", ou o contrário.
- *
- * Duas fontes, nesta ordem:
- *   1. o carimbo `built_at_commit` do graph.json contra o HEAD;
- *   2. o REGISTRO da última rodada, por árvore, em
- *      `<git-common-dir>/morph-spec/graph-refresh-state.json`:
- *      `{ [árvore]: { head, exit, ignoreHash?, at, unavailable?, seeded? } }`.
- *
- * O registro existe porque o `graphify update` do 0.9.50 NÃO recarimba quando
- * a topologia não muda — "No code-graph topology changes detected; outputs
- * left untouched" (watch.py): commit só de `.morph/`, corpo de método editado,
- * commit num arquivo excluído. O carimbo fica no commit antigo e, sem o
- * registro, o grafo parecia velho para sempre e cada disparo rodava o graphify
- * de novo (~80 s no MORPH_GHLBrain). Rodada com exit 0 no HEAD H vale como
- * grafo em dia em H: o 0.9.50 sai 1 quando recusa escrever (`_check_shrink`,
- * grafo ilegível), e "untouched" sai 0.
- *
- * As regras do `.graphifyignore` entram por CONTEÚDO, nunca pelo relógio: o
- * registro guarda o hash das regras sob as quais o grafo EM DISCO foi
- * extraído (uma rodada que falhou não o muda), e um hash diferente do das
- * regras que valem hoje é grafo velho — numa worktree sem arquivo próprio,
- * as da raiz, que são as que o `graph refresh` usa ali. Comentário, linha
- * em branco, BOM e CRLF não contam — trocar o cabeçalho não pede refresh.
- * Grafo sem registro das regras (anterior a este estado) com regras valendo é
- * `rules-unknown`: um refresh grava o registro e encerra.
- *
- * Fail-open: nada aqui lança.
- *
- * @module graph-freshness
- */
+// Regra ÚNICA de "grafo em dia". O registro da rodada existe porque o `graphify
+// update` não recarimba `built_at_commit` quando a topologia não muda; as regras
+// do ignore entram por CONTEÚDO, nunca pelo relógio. Fail-open: nada aqui lança.
 
 import { createHash } from 'crypto';
 import { execFileSync } from 'child_process';
@@ -50,19 +15,12 @@ export const GRAPH_DIR = 'graphify-out';
 export const GRAPHIFY_IGNORE = '.graphifyignore';
 const STATE_FILE = 'graph-refresh-state.json';
 
-/** @param {string} tree */
 export function graphFile(tree) {
   return join(tree, GRAPH_DIR, 'graph.json');
 }
 
-/**
- * `built_at_commit` do graph.json. O graphify o grava como a ÚLTIMA chave, então
- * a leitura do fim do arquivo evita parsear 18 MB; a leitura inteira fica de
- * reserva para qualquer outra forma.
- *
- * @param {string} tree
- * @returns {string|null}
- */
+// O graphify grava `built_at_commit` como a ÚLTIMA chave: ler o fim evita parsear
+// o grafo inteiro, que fica de reserva para outra forma.
 export function readBuiltAtCommit(tree) {
   const file = graphFile(tree);
   let fd;
@@ -86,10 +44,6 @@ export function readBuiltAtCommit(tree) {
   }
 }
 
-/**
- * @param {string} tree
- * @returns {string|null}
- */
 export function readHead(tree) {
   try {
     return execFileSync('git', ['rev-parse', 'HEAD'], {
@@ -100,14 +54,7 @@ export function readHead(tree) {
   }
 }
 
-/**
- * As REGRAS de um `.graphifyignore`, sem o que o graphify não lê: comentário,
- * linha em branco, espaço no fim, BOM e CRLF. A ordem fica — no gitignore ela
- * muda o resultado.
- *
- * @param {string} text
- * @returns {string}
- */
+// A ordem fica: no gitignore ela muda o resultado.
 export function ignoreRules(text) {
   return String(text ?? '')
     .replace(/^\uFEFF/, '')
@@ -117,37 +64,22 @@ export function ignoreRules(text) {
     .join('\n');
 }
 
-/**
- * @param {string|null} text
- * @returns {string|null} null quando não há arquivo
- */
 export function rulesHash(text) {
   if (text === null || text === undefined) return null;
   return createHash('sha256').update(ignoreRules(text)).digest('hex').slice(0, 16);
 }
 
-/**
- * A árvore principal do repositório — a única que o refresh em background
- * toca. `null` fora de um repositório e quando o common dir não é o `.git` de
- * uma árvore (repositório bare, `--separate-git-dir`): aí não há raiz.
- *
- * @param {string} dir - qualquer diretório do repositório, raiz ou worktree
- * @returns {string|null}
- */
+/** `null` também quando o common dir não é o `.git` de uma árvore (bare, `--separate-git-dir`). */
 export function primaryTree(dir) {
   const common = dir ? resolveGitCommonDir(dir) : null;
   if (!common || basename(common) !== '.git') return null;
   return dirname(common);
 }
 
-/**
- * 1ª linha do `.graphifyignore` que o `graph refresh` põe numa worktree só
- * durante a rodada. Comentário não muda as regras nem o hash, e é por ele que a
- * sobra de uma rodada cujo processo morreu no meio é reconhecida.
- */
+// 1ª linha da cópia temporária: reconhece a sobra de uma rodada que morreu no
+// meio sem mudar as regras nem o hash.
 export const TEMP_IGNORE_MARKER = '# morph-spec: cópia temporária do graph refresh, apagada ao fim da rodada';
 
-/** @param {string|null} text */
 export function isTemporaryIgnore(text) {
   return String(text ?? '').replace(/^/, '').split(/\r?\n/, 1)[0] === TEMP_IGNORE_MARKER;
 }
@@ -160,14 +92,8 @@ function readText(path) {
   }
 }
 
-/**
- * O `.graphifyignore` com que o graphify roda nesta árvore: o do checkout;
- * numa worktree sem um (ou só com a sobra temporária), o da raiz, que é o que o
- * `graph refresh` põe no lugar durante a rodada.
- *
- * @param {string} tree
- * @returns {string|null} null quando nenhum arquivo vale
- */
+// Numa worktree sem arquivo próprio valem as regras da raiz: é o que o
+// `graph refresh` põe no lugar durante a rodada.
 export function ignoreTextOf(tree) {
   const own = readText(join(tree, GRAPHIFY_IGNORE));
   if (own !== null && !isTemporaryIgnore(own)) return own;
@@ -177,37 +103,18 @@ export function ignoreTextOf(tree) {
   return inherited !== null && !isTemporaryIgnore(inherited) ? inherited : null;
 }
 
-/**
- * @param {string} tree
- * @returns {string|null} null quando nenhum `.graphifyignore` vale para a árvore
- */
 export function ignoreRulesHash(tree) {
   return rulesHash(ignoreTextOf(tree));
 }
 
-/**
- * As linhas de `git status --porcelain` de `tree` sem a da sobra do
- * `.graphifyignore` temporário: ela é só uma cópia das regras da raiz, e o
- * `?? .graphifyignore` que deixa fazia o `finish` e o
- * `worktree remove --if-clean` recusarem. Só lê — quem confere a árvore chama
- * isto antes das recusas, e `dropLeftoverIgnore` só depois delas.
- *
- * @param {string} tree
- * @param {string[]} lines
- * @returns {string[]}
- */
+// Só lê: quem confere a árvore chama isto antes das recusas, e
+// `dropLeftoverIgnore` só depois delas.
 export function withoutLeftoverIgnore(tree, lines) {
   const leftover = `?? ${GRAPHIFY_IGNORE}`;
   if (!lines.includes(leftover) || !isTemporaryIgnore(readText(join(tree, GRAPHIFY_IGNORE)))) return lines;
   return lines.filter((line) => line !== leftover);
 }
 
-/**
- * Apaga a sobra do `.graphifyignore` temporário, reconhecida pelo marcador.
- *
- * @param {string} tree
- * @returns {boolean} apagou
- */
 export function dropLeftoverIgnore(tree) {
   const path = join(tree, GRAPHIFY_IGNORE);
   if (!isTemporaryIgnore(readText(path))) return false;
@@ -219,21 +126,12 @@ export function dropLeftoverIgnore(tree) {
   }
 }
 
-/**
- * Chave de uma árvore no registro. No win32 o caminho não distingue caixa, e
- * `R:\x` e `r:\x` são a mesma árvore.
- *
- * @param {string} tree
- */
+// No win32 o caminho não distingue caixa.
 export function treeKey(tree) {
   const path = resolve(tree);
   return process.platform === 'win32' ? path.toLowerCase() : path;
 }
 
-/**
- * @param {string} dir - qualquer diretório do repositório
- * @returns {string|null}
- */
 export function refreshStatePath(dir) {
   const common = dir ? resolveGitCommonDir(dir) : null;
   return common ? join(common, 'morph-spec', STATE_FILE) : null;
@@ -248,10 +146,7 @@ function readState(path) {
   }
 }
 
-/**
- * @param {string} tree
- * @returns {{head: string|null, exit: number|null, ignoreHash?: string|null, at: string, unavailable?: boolean, seeded?: boolean}|null}
- */
+/** @returns {{head: string|null, exit: number|null, ignoreHash?: string|null, at: string, unavailable?: boolean, seeded?: boolean}|null} */
 export function readRefreshRecord(tree) {
   const path = refreshStatePath(tree);
   if (!path) return null;
@@ -263,15 +158,7 @@ function pause(ms) {
   try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* sem espera */ }
 }
 
-/**
- * Grava o registro de `tree` (substitui o anterior). Por tmp + rename: quem lê
- * no meio vê o arquivo velho ou o novo, nunca meio. As árvores que não existem
- * mais saem na mesma escrita — uma worktree removida não deixa lixo.
- *
- * @param {string} tree
- * @param {object} record
- * @returns {object|null} o registro gravado, ou null (sem git, disco)
- */
+// As árvores que não existem mais saem na mesma escrita.
 export function writeRefreshRecord(tree, record) {
   const path = refreshStatePath(tree);
   if (!path) return null;
@@ -286,8 +173,7 @@ export function writeRefreshRecord(tree, record) {
     }
     state[key] = entry;
     writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
-    // No win32 o rename sobre um arquivo aberto por outro leitor falha por um
-    // instante (EPERM/EBUSY); o registro vale umas tentativas.
+    // No win32 o rename sobre um arquivo aberto por outro leitor falha por um instante.
     for (let attempt = 0; ; attempt++) {
       try {
         renameSync(tmp, path);
@@ -303,15 +189,8 @@ export function writeRefreshRecord(tree, record) {
   }
 }
 
-/**
- * Registra uma rodada do graphify sobre `tree`. As regras só mudam com exit 0:
- * uma rodada que falhou não mexeu no grafo, e o hash descreve o grafo em
- * disco, não a tentativa.
- *
- * @param {string} tree
- * @param {{head: string|null, exit: number|null, ignoreHash: string|null, unavailable?: boolean}} run
- *   `head` e `ignoreHash` lidos ANTES da rodada — é o que o graphify leu
- */
+// O hash das regras só muda com exit 0: descreve o grafo em disco, não a
+// tentativa. `head` e `ignoreHash` são lidos ANTES da rodada.
 export function recordRefreshRun(tree, { head, exit, ignoreHash, unavailable = false }) {
   const previous = readRefreshRecord(tree);
   let rules = {};
@@ -325,23 +204,7 @@ export function recordRefreshRun(tree, { head, exit, ignoreHash, unavailable = f
   });
 }
 
-/**
- * O frescor do grafo de `tree`.
- *
- *   missing  sem graph.json
- *   unknown  sem git, ou sem carimbo nem registro que diga o commit
- *   stale    atrás do HEAD (`reason` ausente), ou em dia no commit mas com as
- *            regras do ignore mudadas (`ignore-changed`) ou desconhecidas
- *            (`rules-unknown`)
- *   fresh    carimbo = HEAD, ou rodada com exit 0 neste HEAD — e as regras
- *            que valem para a árvore são as do grafo (`ignoreTextOf`; nenhum
- *            arquivo valendo não afirma nada)
- *
- * @param {string} tree - o diretório que contém `graphify-out/`
- * @param {{graph?: object, head?: string|null}} [known] o que o chamador já
- *   leu: o grafo parseado (o carimbo sai dele) e o HEAD
- * @returns {{state: 'missing'|'unknown'|'stale'|'fresh', built: string|null, head: string|null, reason?: 'ignore-changed'|'rules-unknown', record: object|null}}
- */
+/** @returns {{state: 'missing'|'unknown'|'stale'|'fresh', built: string|null, head: string|null, reason?: 'ignore-changed'|'rules-unknown', record: object|null}} */
 export function graphFreshness(tree, { graph, head } = {}) {
   if (!graph && !existsSync(graphFile(tree))) {
     return { state: 'missing', built: null, head: null, record: null };
@@ -363,15 +226,8 @@ export function graphFreshness(tree, { graph, head } = {}) {
   return { state: 'fresh', ...base };
 }
 
-/**
- * Um refresh em background resolveria? Grafo velho, e sem uma rodada que já
- * FALHOU neste mesmo HEAD — essa só se repete quando o HEAD andar (ou por
- * `morph-spec graph refresh`, que é explícito). "graphify ausente" não conta
- * como falha: instalado, ele roda no próximo disparo.
- *
- * @param {{state: string, head: string|null, record: object|null}} freshness
- * @returns {boolean}
- */
+// Uma rodada que FALHOU neste HEAD só se repete quando o HEAD andar;
+// "graphify ausente" não conta como falha.
 export function refreshPending(freshness) {
   if (freshness?.state !== 'stale') return false;
   const r = freshness.record;