@polymorphism-tech/morph-spec 8.37.0 → 8.38.0

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

@@ -0,0 +1,380 @@
+/**
+ * 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
+ */
+
+import { createHash } from 'crypto';
+import { execFileSync } from 'child_process';
+import {
+  closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync,
+  renameSync, unlinkSync, writeFileSync,
+} from 'fs';
+import { basename, dirname, join, resolve } from 'path';
+import { resolveGitCommonDir } from './git-paths.js';
+
+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}
+ */
+export function readBuiltAtCommit(tree) {
+  const file = graphFile(tree);
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+    const size = fstatSync(fd).size;
+    const len = Math.min(size, 4096);
+    const buf = Buffer.alloc(len);
+    readSync(fd, buf, 0, len, size - len);
+    const m = /"built_at_commit"\s*:\s*"([0-9a-f]{7,64})"/.exec(buf.toString('utf8'));
+    if (m) return m[1];
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) try { closeSync(fd); } catch { /* já fechado */ }
+  }
+  try {
+    return JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, ''))?.built_at_commit ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} tree
+ * @returns {string|null}
+ */
+export function readHead(tree) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: tree, encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000,
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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}
+ */
+export function ignoreRules(text) {
+  return String(text ?? '')
+    .replace(/^\uFEFF/, '')
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line && !line.startsWith('#'))
+    .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}
+ */
+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.
+ */
+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;
+}
+
+function readText(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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
+ */
+export function ignoreTextOf(tree) {
+  const own = readText(join(tree, GRAPHIFY_IGNORE));
+  if (own !== null && !isTemporaryIgnore(own)) return own;
+  const root = primaryTree(tree);
+  if (!root || treeKey(root) === treeKey(tree)) return null;
+  const inherited = readText(join(root, GRAPHIFY_IGNORE));
+  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[]}
+ */
+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;
+  try {
+    unlinkSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 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
+ */
+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;
+}
+
+function readState(path) {
+  try {
+    const state = JSON.parse(readFileSync(path, 'utf8'));
+    return state && typeof state === 'object' && !Array.isArray(state) ? state : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * @param {string} tree
+ * @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;
+  const record = readState(path)[treeKey(tree)];
+  return record && typeof record === 'object' ? record : null;
+}
+
+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)
+ */
+export function writeRefreshRecord(tree, record) {
+  const path = refreshStatePath(tree);
+  if (!path) return null;
+  const key = treeKey(tree);
+  const entry = { ...record, at: new Date().toISOString() };
+  const tmp = `${path}.tmp.${process.pid}`;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const state = readState(path);
+    for (const other of Object.keys(state)) {
+      if (other !== key && !existsSync(other)) delete state[other];
+    }
+    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.
+    for (let attempt = 0; ; attempt++) {
+      try {
+        renameSync(tmp, path);
+        return entry;
+      } catch (err) {
+        if (attempt >= 4 || !['EPERM', 'EBUSY', 'EACCES'].includes(err?.code)) throw err;
+        pause(25);
+      }
+    }
+  } catch {
+    try { unlinkSync(tmp); } catch { /* nunca criado */ }
+    return null;
+  }
+}
+
+/**
+ * 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
+ */
+export function recordRefreshRun(tree, { head, exit, ignoreHash, unavailable = false }) {
+  const previous = readRefreshRecord(tree);
+  let rules = {};
+  if (exit === 0) rules = { ignoreHash };
+  else if (previous && 'ignoreHash' in previous) rules = { ignoreHash: previous.ignoreHash };
+  return writeRefreshRecord(tree, {
+    head: head ?? null,
+    exit: exit ?? null,
+    ...rules,
+    ...(unavailable ? { unavailable: true } : {}),
+  });
+}
+
+/**
+ * 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}}
+ */
+export function graphFreshness(tree, { graph, head } = {}) {
+  if (!graph && !existsSync(graphFile(tree))) {
+    return { state: 'missing', built: null, head: null, record: null };
+  }
+  const built = graph ? (graph.built_at_commit ?? null) : readBuiltAtCommit(tree);
+  const current = head !== undefined ? head : readHead(tree);
+  const record = readRefreshRecord(tree);
+  const base = { built, head: current, record };
+  if (!current) return { state: 'unknown', ...base };
+
+  const atHead = built === current || (record?.exit === 0 && record.head === current);
+  if (!atHead) return { state: built ? 'stale' : 'unknown', ...base };
+
+  const rules = ignoreRulesHash(tree);
+  if (rules !== null) {
+    if (!record || !('ignoreHash' in record)) return { state: 'stale', reason: 'rules-unknown', ...base };
+    if (record.ignoreHash !== rules) return { state: 'stale', reason: 'ignore-changed', ...base };
+  }
+  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}
+ */
+export function refreshPending(freshness) {
+  if (freshness?.state !== 'stale') return false;
+  const r = freshness.record;
+  const failedHere = r && r.head === freshness.head && r.exit !== 0 && !r.unavailable;
+  return !failedHere;
+}