@polymorphism-tech/morph-spec 8.29.0 → 8.32.0

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

@@ -0,0 +1,89 @@
+/**
+ * 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.
+ */
+
+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.
+ */
+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.
+ */
+export function pendingPrFeatures(root, opts = {}) {
+  const index = opts.index !== undefined ? opts.index : buildPrIndex(root);
+  if (!index) return null;
+
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  const out = [];
+  for (const [branch, pr] of index) {
+    const m = branch.match(MORPH_BRANCH_RE);
+    if (!m) continue;
+    if (pr.state !== 'OPEN') continue;
+    const feature = m[1];
+    if (hasLocalFolder(root, feature)) continue;
+
+    let ageDays = null;
+    if (pr.createdAt) {
+      const t = Date.parse(pr.createdAt);
+      if (!Number.isNaN(t)) ageDays = Math.floor((now.getTime() - t) / DAY_MS);
+    }
+    out.push({
+      feature,
+      branch,
+      number: pr.number,
+      state: pr.state,
+      url: pr.url ?? null,
+      createdAt: pr.createdAt ?? null,
+      ageDays,
+    });
+  }
+  out.sort((a, b) => a.feature.localeCompare(b.feature));
+  return out;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * 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]
+ * @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"
+ */
+export function buildPrIndex(root, opts = {}) {
+  const limit = String(opts.limit ?? 200);
+  const timeout = opts.timeout ?? 8000;
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: root, stdio: 'pipe' }).toString();
+    if (!/github\.com/i.test(url)) return null;
+    const { bin, prefix } = resolveGh();
+    const out = execFileSync(
+      bin,
+      [...prefix, 'pr', 'list', '--state', 'all', '--limit', limit,
+        '--json', 'number,state,headRefName,mergedAt,url,createdAt'],
+      { cwd: root, stdio: 'pipe', timeout },
+    ).toString();
+    const map = new Map();
+    for (const pr of JSON.parse(out)) {
+      if (pr?.headRefName && !map.has(pr.headRefName)) {
+        map.set(pr.headRefName, {
+          number: pr.number,
+          state: pr.state,
+          mergedAt: pr.mergedAt ?? null,
+          url: pr.url ?? null,
+          createdAt: pr.createdAt ?? null,
+        });
+      }
+    }
+    return map;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ *
+ * @module god-nodes
+ */
+import { loadGraph } from './graph-loader.js';
+import { buildIndex, resolveEdgeTarget } 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;
+
+  const loaded = loadGraph(projectPath);
+  if (!loaded.ok) return { available: false, godNodes: [], communities: [] };
+
+  const { graph } = loaded;
+  const index = buildIndex(graph);
+
+  // Grau depois do saneamento: a coalescência muda quem é central, porque as
+  // arestas que apontavam para stub passam a contar no nó real.
+  const degree = new Map();
+  const bump = (id) => {
+    if (id) degree.set(id, (degree.get(id) ?? 0) + 1);
+  };
+  for (const link of graph.links ?? []) {
+    bump(link.source);
+    bump(resolveEdgeTarget(index, link).id);
+  }
+
+  const godNodes = [...degree.entries()]
+    .map(([id, d]) => ({ node: index.byId.get(id), degree: d }))
+    .filter(({ node }) => node?.source_file)
+    .sort((a, b) => b.degree - a.degree || a.node.label.localeCompare(b.node.label))
+    .slice(0, top)
+    .map(({ node, degree: d }) => ({
+      label: node.label,
+      source_file: node.source_file,
+      degree: d,
+    }));
+
+  const sizes = new Map();
+  const labels = new Map();
+  for (const node of graph.nodes ?? []) {
+    if (node.community === undefined || node.community === null) continue;
+    sizes.set(node.community, (sizes.get(node.community) ?? 0) + 1);
+    if (node.community_label && !labels.has(node.community)) {
+      labels.set(node.community, node.community_label);
+    }
+  }
+
+  const communities = [...sizes.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0] - b[0])
+    .slice(0, topCommunities)
+    .map(([id, size]) => {
+      const label = labels.get(id) ?? `Community_${id}`;
+      return { id, label, size, labeled: !PLACEHOLDER_LABEL.test(label) };
+    });
+
+  return { available: true, godNodes, communities };
+}

package/src/lib/graph/graph-health.js

@@ -0,0 +1,61 @@
+/**
+ * Auditoria do grafo para o `morph-spec doctor`.
+ *
+ * Nunca devolve estado de erro: o grafo é opcional (ADR-002) e não pode pintar
+ * de vermelho o doctor de um projeto que não o usa. O pior veredito é `warn`.
+ *
+ * @module graph-health
+ */
+import { loadGraph, getFreshness } from './graph-loader.js';
+import { GRAPHIFY_VERSION, detectGraphifyVersion } from './graphify-runtime.js';
+
+/**
+ * @param {string} projectPath
+ * @param {{_version?: () => string|null}} [deps]
+ * @returns {{status: 'ok'|'warn'|'absent', msg: string, details: string[]}}
+ */
+export function auditGraph(projectPath, deps = {}) {
+  const installed = (deps._version ?? detectGraphifyVersion)();
+  const loaded = loadGraph(projectPath);
+
+  if (!loaded.ok && loaded.reason === 'missing') {
+    return {
+      status: 'absent',
+      msg: 'opcional, não gerado — morph-spec graph build',
+      details: [],
+    };
+  }
+  if (!loaded.ok) {
+    return {
+      status: 'warn',
+      msg: `graph.json ${loaded.reason} — regenere com: morph-spec graph build`,
+      details: [loaded.path],
+    };
+  }
+
+  const { graph } = loaded;
+  const details = [`${graph.nodes.length} nós, ${graph.links.length} arestas`];
+  let status = 'ok';
+
+  const freshness = getFreshness(projectPath, graph);
+  if (freshness.state === 'stale') {
+    status = 'warn';
+    details.push(
+      `stale: construído em ${freshness.builtAtCommit.slice(0, 8)}, HEAD é ${freshness.headCommit.slice(0, 8)} — morph-spec graph refresh`,
+    );
+  }
+
+  if (!installed) {
+    status = 'warn';
+    details.push(`graphify não está no PATH (pinado: ${GRAPHIFY_VERSION})`);
+  } else if (installed !== GRAPHIFY_VERSION) {
+    status = 'warn';
+    details.push(`graphify ${installed} instalado; ${GRAPHIFY_VERSION} é a versão pinada e medida`);
+  }
+
+  return {
+    status,
+    msg: status === 'ok' ? details[0] : details[details.length - 1],
+    details,
+  };
+}

package/src/lib/graph/graph-loader.js

@@ -0,0 +1,86 @@
+/**
+ * Leitura fail-open do graph.json produzido pelo graphify.
+ *
+ * Medido em 2026-08-27 sobre o MORPH_GHLBrain (11,46 MB, 6.829 nós, 15.668
+ * arestas): JSON.parse leva 52 ms e 28 MB de heap. Streaming e cache são
+ * desnecessários nesse porte — se um dia deixarem de ser, a troca acontece só
+ * aqui, porque este módulo é a única porta de leitura do grafo.
+ *
+ * Nada aqui lança: ausência de grafo é um estado válido do projeto (ADR-002).
+ *
+ * @module graph-loader
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/**
+ * @param {string} projectPath
+ * @returns {string} caminho canônico do graph.json do projeto
+ */
+export function resolveGraphPath(projectPath) {
+  return join(projectPath, 'graphify-out', 'graph.json');
+}
+
+/**
+ * @param {string} projectPath
+ * @returns {{ok: boolean, reason?: 'missing'|'unreadable'|'malformed', graph?: object, path: string}}
+ */
+export function loadGraph(projectPath) {
+  const path = resolveGraphPath(projectPath);
+  if (!existsSync(path)) return { ok: false, reason: 'missing', path };
+
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch {
+    return { ok: false, reason: 'unreadable', path };
+  }
+
+  try {
+    const graph = JSON.parse(raw.replace(/^/, ''));
+    // A chave das arestas é `links`, não `edges`. Um JSON válido sem uma das
+    // duas listas não é um grafo utilizável.
+    if (!graph || !Array.isArray(graph.nodes) || !Array.isArray(graph.links)) {
+      return { ok: false, reason: 'malformed', path };
+    }
+    return { ok: true, graph, path };
+  } catch {
+    return { ok: false, reason: 'malformed', path };
+  }
+}
+
+function readHead(projectPath) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: projectPath,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * O hook post-commit do graphify rebuilda em BACKGROUND: logo depois de um
+ * commit o grafo ainda é o do commit anterior. Quem consome precisa saber, ou
+ * conclui "ninguém usa isso" a partir de um grafo velho.
+ *
+ * @param {string} projectPath
+ * @param {object} graph
+ * @param {{_head?: (projectPath: string) => string|null}} [deps]
+ * @returns {{builtAtCommit: string|null, headCommit: string|null, state: 'fresh'|'stale'|'unknown'}}
+ */
+export function getFreshness(projectPath, graph, deps = {}) {
+  const headCommit = (deps._head ?? readHead)(projectPath);
+  const builtAtCommit = graph?.built_at_commit ?? null;
+  if (!headCommit || !builtAtCommit) {
+    return { builtAtCommit, headCommit, state: 'unknown' };
+  }
+  return {
+    builtAtCommit,
+    headCommit,
+    state: builtAtCommit === headCommit ? 'fresh' : 'stale',
+  };
+}

package/src/lib/graph/graphify-runtime.js

@@ -0,0 +1,100 @@
+/**
+ * Descoberta do runtime Python e argv de instalação do graphify.
+ *
+ * O binário instalado chama-se `graphify` (e `graphify-mcp` para o servidor
+ * MCP). NUNCA use `python -m graphify.serve`, que é o que o README oficial
+ * manda: com `uv tool install` o pacote vive num venv isolado e o Python do
+ * sistema não o enxerga (ModuleNotFoundError) — medido no eval, Eixo 2.
+ *
+ * Toda descoberta é injetável (`_which`, `_run`) para que o teste cubra Windows
+ * e POSIX sem depender do PATH da máquina que roda o CI.
+ *
+ * @module graphify-runtime
+ */
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Pin exato: 0.9.50 é a única versão medida no eval e a base do fixture de
+ * regressão. O graphify é pré-1.0 com release quase diária, então semver não
+ * garante nada — bump é decisão consciente, com re-run do fixture.
+ */
+export const GRAPHIFY_VERSION = '0.9.50';
+export const GRAPHIFY_PACKAGE = 'graphifyy';
+export const GRAPHIFY_BIN = 'graphify';
+export const GRAPHIFY_MCP_BIN = 'graphify-mcp';
+
+const PREFERENCE = ['uv', 'pipx', 'python3', 'python'];
+
+function whichSync(bin) {
+  const cmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const out = execFileSync(cmd, [bin], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).split(/\r?\n/)[0].trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * uv > pipx > python3 > python. `kind: null` significa "sem Python": o step do
+ * setup-infra registra e segue, e o framework continua funcionando por grep
+ * (ADR-002).
+ *
+ * @param {{_which?: (bin: string) => string|null}} [deps]
+ * @returns {{kind: 'uv'|'pipx'|'python3'|'python'|null, bin: string|null}}
+ */
+export function detectInstaller(deps = {}) {
+  const which = deps._which ?? whichSync;
+  for (const kind of PREFERENCE) {
+    let bin = null;
+    try {
+      bin = which(kind);
+    } catch {
+      bin = null;
+    }
+    if (bin) return { kind, bin };
+  }
+  return { kind: null, bin: null };
+}
+
+/**
+ * @param {'uv'|'pipx'|'python3'|'python'} kind
+ * @param {{withSql: boolean}} opts sem o extra `[sql]` os arquivos .sql são
+ *   ignorados em silêncio (92 no ProspectPRO) — só um aviso no meio do output
+ *   denuncia
+ * @returns {{cmd: string, args: string[]}}
+ */
+export function installArgs(kind, { withSql }) {
+  const spec = `${GRAPHIFY_PACKAGE}${withSql ? '[sql]' : ''}==${GRAPHIFY_VERSION}`;
+  switch (kind) {
+    case 'uv':
+      return { cmd: 'uv', args: ['tool', 'install', spec] };
+    case 'pipx':
+      return { cmd: 'pipx', args: ['install', spec] };
+    case 'python3':
+    case 'python':
+      return { cmd: kind, args: ['-m', 'pip', 'install', '--user', spec] };
+    default:
+      throw new Error(`installArgs: gerenciador desconhecido "${kind}"`);
+  }
+}
+
+/**
+ * @param {{_run?: () => string}} [deps]
+ * @returns {string|null} versão instalada, ou null se o binário não responde
+ */
+export function detectGraphifyVersion(deps = {}) {
+  const run = deps._run ?? (() => execFileSync(GRAPHIFY_BIN, ['--version'], {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }));
+  try {
+    const m = /(\d+\.\d+\.\d+)/.exec(run());
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/graph/graphifyignore.js

@@ -0,0 +1,86 @@
+/**
+ * Geração stack-aware do .graphifyignore (ADR-004).
+ *
+ * Filtrar teste não é cosmético: sem isso o god node #1 do MORPH_GHLBrain é
+ * `FakeGhlToolbelt`, um dublê. Pior, os dublês criam um segundo implementador e
+ * quebram o guard de "implementador único" do `dispatches_to` — a aresta que
+ * atravessa a injeção de dependência cai de 109 para 1.
+ *
+ * E o padrão genérico `tests/` NÃO serve em .NET: no ProspectPRO os testes
+ * vivem em `src/backend/ProspectPRO.Tests/`. Com `**\/*.Tests/` o grafo caiu de
+ * 10.450 para 7.384 nós — 30% era ruído de teste.
+ *
+ * Em Next.js o problema é outro: metade dos nós vinha de JSON de configuração,
+ * e os god nodes viravam `dependencies` e `compilerOptions`.
+ *
+ * @module graphifyignore
+ */
+import { writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const ALWAYS_IGNORED = [
+  '.git/', '.morph/', 'artifacts/', 'worktrees/', '.worktrees/',
+  'coverage/', 'graphify-out/', 'dist/', 'out/',
+];
+
+const DOTNET_IGNORED = [
+  '**/*.Tests/', '**/*Tests/', '**/*.Test/', 'bin/', 'obj/', 'TestResults/',
+];
+
+const WEB_IGNORED = [
+  'node_modules/', '.next/', '.turbo/', 'build/',
+  // Só os JSON da RAIZ, para não esconder JSON que seja dado do projeto.
+  '/package.json', '/package-lock.json', '/pnpm-lock.yaml', '/tsconfig.json',
+  '/next.config.js', '/next.config.mjs', '/tailwind.config.js', '/tailwind.config.ts',
+];
+
+const DOTNET_TAGS = new Set(['dotnet', 'aspnet']);
+const WEB_TAGS = new Set([
+  'nextjs', 'next', 'next.js', 'react', 'vue', 'nodejs', 'nodejs-cli', 'node-cli',
+]);
+
+/**
+ * @param {string[]} [projectTags] saída de `getProjectTags(config)` — stack
+ *   splitado por `-`/`+` mais as integrations
+ * @returns {string} conteúdo completo do .graphifyignore
+ */
+export function buildGraphifyignore(projectTags = []) {
+  const tags = new Set(projectTags);
+  const hasDotnet = [...tags].some((t) => DOTNET_TAGS.has(t));
+  const hasWeb = [...tags].some((t) => WEB_TAGS.has(t));
+
+  const sections = [
+    ['# Gerado por morph-spec (ADR-004). Editável: o CLI não sobrescreve.', ''],
+    ['# Sempre', ...ALWAYS_IGNORED],
+  ];
+  if (hasDotnet) {
+    sections.push(['', '# .NET — testes em qualquer nível (tests/ genérico não serve)', ...DOTNET_IGNORED]);
+  }
+  if (hasWeb) {
+    sections.push(['', '# Web — dependências e JSON de configuração de raiz', ...WEB_IGNORED]);
+  }
+
+  const seen = new Set();
+  const lines = [];
+  for (const line of sections.flat()) {
+    const isPattern = line && !line.startsWith('#');
+    if (isPattern && seen.has(line)) continue;
+    if (isPattern) seen.add(line);
+    lines.push(line);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Escreve o .graphifyignore. Arquivo já existente é do usuário: não é tocado.
+ *
+ * @param {string} projectPath
+ * @param {string[]} [projectTags]
+ * @returns {{written: boolean, path: string}}
+ */
+export function writeGraphifyignore(projectPath, projectTags = []) {
+  const path = join(projectPath, '.graphifyignore');
+  if (existsSync(path)) return { written: false, path };
+  writeFileSync(path, buildGraphifyignore(projectTags), 'utf-8');
+  return { written: true, path };
+}