@polymorphism-tech/morph-spec 8.29.0 → 8.32.0

package/src/commands/graph/build.js

@@ -0,0 +1,94 @@
+/**
+ * `morph-spec graph build` (extração completa) e `graph refresh` (incremental).
+ *
+ * Fail-open: sem graphify no PATH, explica o que fazer e sai 1 — sem stack
+ * trace. Um projeto sem grafo continua funcionando por grep.
+ *
+ * @module graph-build
+ */
+import chalk from 'chalk';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { GRAPHIFY_BIN, GRAPHIFY_VERSION, detectGraphifyVersion } from '../../lib/graph/graphify-runtime.js';
+import { getProjectTags } from '../../lib/stack-filter.js';
+import { writeGraphifyignore } from '../../lib/graph/graphifyignore.js';
+import { resolveGraphPath } from '../../lib/graph/graph-loader.js';
+
+function readProjectTags(projectPath) {
+  const configPath = join(projectPath, '.morph', 'config', 'config.json');
+  if (!existsSync(configPath)) return [];
+  try {
+    return getProjectTags(JSON.parse(readFileSync(configPath, 'utf-8').replace(/^/, '')));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {{path?: string, json?: boolean, refresh?: boolean}} [options]
+ */
+export async function graphBuildCommand(options = {}) {
+  const projectPath = options.path || process.cwd();
+  const refresh = options.refresh === true;
+
+  if (!detectGraphifyVersion()) {
+    const hint = `graphify não está no PATH. Instale com: uv tool install ${'graphifyy'}==${GRAPHIFY_VERSION}`;
+    const payload = { ok: false, reason: 'graphify-unavailable', hint };
+    if (options.json) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      console.error(chalk.yellow('\n○ graphify não encontrado no PATH.'));
+      console.error(chalk.gray(`   ${hint}`));
+      console.error(chalk.gray('   Sem grafo o framework segue funcionando por grep.\n'));
+    }
+    process.exit(1);
+  }
+
+  // O ignore precisa existir ANTES da extração, senão o grafo nasce com o
+  // ruído que a ADR-004 existe para tirar.
+  writeGraphifyignore(projectPath, readProjectTags(projectPath));
+
+  const args = refresh
+    ? ['update', projectPath]
+    : ['extract', projectPath, '--code-only'];
+
+  // Capturamos o output em vez de herdar o terminal porque precisamos
+  // inspecioná-lo: o graphify sai 1 tanto quando quebra quanto quando não há
+  // código para indexar, e essas duas coisas não podem virar a mesma mensagem.
+  const run = spawnSync(GRAPHIFY_BIN, args, {
+    cwd: projectPath,
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  const output = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+  const ok = run.status === 0;
+  // Projeto sem código é o estado normal logo depois de um `init`, não uma
+  // falha: o graphify diz "found 0 code" / "graph is empty", sai 1 e não
+  // escreve graph.json. Tratar isso como erro faria todo init greenfield
+  // terminar em vermelho.
+  const empty = !ok && (/found 0 code/i.test(output) || /graph is empty/i.test(output));
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      ok: ok || empty,
+      empty,
+      mode: refresh ? 'refresh' : 'build',
+      path: resolveGraphPath(projectPath),
+      exitCode: run.status,
+    }, null, 2));
+  } else {
+    if (!empty && output.trim()) process.stdout.write(`${output.trimEnd()}\n`);
+    if (ok) {
+      console.log(chalk.green(`\n✅ Grafo ${refresh ? 'atualizado' : 'construído'} — confira com: morph-spec graph status\n`));
+    } else if (empty) {
+      console.log(chalk.yellow('\n○ Nenhum arquivo de código para indexar — grafo não gerado.'));
+      console.log(chalk.gray('   É o esperado em projeto novo. Rode de novo quando houver código.\n'));
+    } else {
+      console.error(chalk.red(`\n❌ graphify saiu com código ${run.status}\n`));
+    }
+  }
+
+  if (!ok && !empty) process.exit(1);
+}

package/src/commands/graph/explain.js

@@ -0,0 +1,96 @@
+/**
+ * `morph-spec graph explain <símbolo>` — vizinhança com citação arquivo:linha.
+ *
+ * É o comando preferido nas personas: no eval, `explain` foi consistentemente
+ * mais preciso que `query`, que trunca por budget e traz ruído.
+ *
+ * Cada aresta carrega a procedência (`via`), então dá para ver o que o
+ * saneamento recuperou — `coalesced` são exatamente as arestas que o graphify
+ * cru perde.
+ *
+ * @module graph-explain
+ */
+import chalk from 'chalk';
+import { loadGraph, getFreshness } from '../../lib/graph/graph-loader.js';
+import { buildIndex, resolveLabel, neighborhood } from '../../lib/graph/sanitize.js';
+
+const FALLBACK_HINT = 'Sem resposta do grafo, caia para grep/Glob.';
+
+/**
+ * @param {string} symbol
+ * @param {{path?: string, json?: boolean}} [options]
+ */
+export async function graphExplainCommand(symbol, options = {}) {
+  const projectPath = options.path || process.cwd();
+  const loaded = loadGraph(projectPath);
+
+  if (!loaded.ok) {
+    const payload = {
+      ok: false, reason: 'no-graph', detail: loaded.reason, hint: FALLBACK_HINT,
+    };
+    if (options.json) console.log(JSON.stringify(payload, null, 2));
+    else console.error(chalk.yellow(`\n○ Sem grafo (${loaded.reason}). ${FALLBACK_HINT}\n`));
+    process.exit(1);
+  }
+
+  const { graph } = loaded;
+  const index = buildIndex(graph);
+  const resolved = resolveLabel(index, symbol);
+
+  if (!resolved.ok) {
+    const payload = {
+      ok: false, reason: resolved.reason, symbol,
+      options: resolved.options, hint: FALLBACK_HINT,
+    };
+    if (options.json) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      console.error(chalk.yellow(`\n○ "${symbol}": ${resolved.reason}`));
+      for (const o of resolved.options) console.error(chalk.gray(`   ${o.source_file}  (${o.id})`));
+      console.error('');
+    }
+    process.exit(1);
+  }
+
+  const { node, incoming, outgoing } = neighborhood(index, graph, resolved.id);
+  const freshness = getFreshness(projectPath, graph);
+  const payload = {
+    ok: true,
+    symbol,
+    node: {
+      id: node.id,
+      label: node.label,
+      source_file: node.source_file,
+      source_location: node.source_location ?? '',
+    },
+    incoming,
+    outgoing,
+    freshness,
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  const nodeLoc = node.source_location ? `:${node.source_location}` : '';
+  console.log(chalk.green(`\n${node.label}`) + chalk.gray(`  ${node.source_file}${nodeLoc}`));
+  if (freshness.state === 'stale') {
+    console.log(chalk.yellow('  ⚠ grafo stale — o rebuild do hook é assíncrono'));
+  }
+
+  console.log(chalk.bold('\n  quem depende dele:'));
+  for (const e of incoming) {
+    const loc = e.source_location ? `:${e.source_location}` : '';
+    const via = e.via === 'direct' ? '' : chalk.gray(` [${e.via}]`);
+    console.log(`   ${chalk.cyan(e.relation.padEnd(14))} ${e.source_file}${loc}${via}`);
+  }
+  if (incoming.length === 0) console.log(chalk.gray('   (nenhum)'));
+
+  console.log(chalk.bold('\n  do que ele depende:'));
+  for (const e of outgoing) {
+    console.log(`   ${chalk.cyan(e.relation.padEnd(14))} ${e.label} ${chalk.gray(e.source_file || '')}`);
+  }
+  if (outgoing.length === 0) console.log(chalk.gray('   (nenhum)'));
+  console.log('');
+}

package/src/commands/graph/status.js

@@ -0,0 +1,93 @@
+/**
+ * `morph-spec graph status` — existência, tamanho, frescor e saúde do
+ * saneamento.
+ *
+ * Ausência de grafo NÃO é erro (ADR-002): exit 0 com `available: false`. Um
+ * projeto sem grafo é um estado válido, e o framework segue por grep.
+ *
+ * @module graph-status
+ */
+import chalk from 'chalk';
+import { loadGraph, getFreshness } from '../../lib/graph/graph-loader.js';
+import { buildIndex, classifyLabel } from '../../lib/graph/sanitize.js';
+import { GRAPHIFY_VERSION, detectGraphifyVersion } from '../../lib/graph/graphify-runtime.js';
+
+function summarizeSanitize(index) {
+  const counts = {
+    resolved: 0, coalescible: 0, external: 0, ambiguous: 0, unknown: 0,
+  };
+  for (const label of index.byLabel.keys()) {
+    counts[classifyLabel(index, label)] += 1;
+  }
+  return counts;
+}
+
+/**
+ * @param {{path?: string, json?: boolean}} [options]
+ */
+export async function graphStatusCommand(options = {}) {
+  const projectPath = options.path || process.cwd();
+  const installed = detectGraphifyVersion();
+  const version = {
+    installed,
+    pinned: GRAPHIFY_VERSION,
+    matches: installed === GRAPHIFY_VERSION,
+  };
+  const loaded = loadGraph(projectPath);
+
+  if (!loaded.ok) {
+    const payload = {
+      available: false, reason: loaded.reason, path: loaded.path, version,
+    };
+    if (options.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+    console.log(chalk.yellow(`\n○ Sem grafo (${loaded.reason})`));
+    console.log(chalk.gray(`   ${loaded.path}`));
+    console.log(chalk.gray('   Gere com: morph-spec graph build'));
+    console.log(chalk.gray('   Sem grafo, scout e skills seguem por grep normalmente.\n'));
+    return;
+  }
+
+  const { graph } = loaded;
+  const freshness = getFreshness(projectPath, graph);
+  const sanitize = summarizeSanitize(buildIndex(graph));
+  const payload = {
+    available: true,
+    path: loaded.path,
+    nodes: graph.nodes.length,
+    links: graph.links.length,
+    freshness,
+    version,
+    sanitize,
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(chalk.green(`\n✅ Grafo disponível — ${graph.nodes.length} nós, ${graph.links.length} arestas`));
+  console.log(chalk.gray(`   ${loaded.path}`));
+
+  if (freshness.state === 'stale') {
+    // O hook post-commit rebuilda em BACKGROUND: logo após um commit o grafo
+    // ainda é o do commit anterior.
+    console.log(chalk.yellow(`   ⚠ stale — construído em ${freshness.builtAtCommit.slice(0, 8)}, HEAD é ${freshness.headCommit.slice(0, 8)}`));
+    console.log(chalk.gray('     Atualize com: morph-spec graph refresh'));
+  } else if (freshness.state === 'fresh') {
+    console.log(chalk.gray(`   fresco (${freshness.headCommit.slice(0, 8)})`));
+  } else {
+    console.log(chalk.gray('   frescor desconhecido (sem git ou sem built_at_commit)'));
+  }
+
+  if (!installed) {
+    console.log(chalk.gray(`   graphify não encontrado no PATH (pinado: ${GRAPHIFY_VERSION})`));
+  } else if (!version.matches) {
+    console.log(chalk.yellow(`   ⚠ graphify ${installed} instalado; ${GRAPHIFY_VERSION} é a versão pinada e medida`));
+  }
+
+  console.log(chalk.gray(`   saneamento: ${sanitize.coalescible} coalescível · ${sanitize.external} externo · ${sanitize.ambiguous} ambíguo`));
+  console.log('');
+}

package/src/commands/index.js

@@ -1,13 +1,13 @@
-/**
- * All Commands - Category Exports
- *
- * Commands organized by functional category.
- */
-
-export * from './state/index.js';
-export * from './validation/index.js';
-export * from './templates/index.js';
-export * from './project/index.js';
-export * from './tasks/index.js';
-export * from './agents/index.js';
-export * from './utils/index.js';
+/**
+ * All Commands - Category Exports
+ *
+ * Commands organized by functional category.
+ */
+
+export * from './state/index.js';
+export * from './validation/index.js';
+export * from './templates/index.js';
+export * from './project/index.js';
+export * from './tasks/index.js';
+export * from './agents/index.js';
+export * from './utils/index.js';

package/src/commands/project/branch.js

@@ -0,0 +1,170 @@
+/**
+ * branch.js — `morph-spec branch prune`.
+ *
+ * The gap this closes: after a few features close by squash-merge, the local
+ * repo accumulates branches git considers unmerged. `git branch --merged` lists
+ * none of them, `git branch -d` refuses each one, and the only command left is
+ * `git branch -D` — which is EXACTLY the command for throwing away real work.
+ * Once a user has typed `-D` on five safe branches, the sixth (an actual
+ * unintegrated feature) gets the same keystroke.
+ *
+ * So this command never asks the user to make that distinction: it makes it
+ * itself, prints the evidence for each branch, and deletes only what it PROVED
+ * is already integrated (see branch-classifier.js for the five classes and
+ * their order). Everything else is listed with the reason it survives.
+ *
+ * The remote is a separate decision: `--remote` is required to touch
+ * `origin/<branch>`, because a local branch is a local artifact while the remote
+ * one may be what someone else, or an open review, is looking at.
+ */
+
+import { execFileSync } from 'child_process';
+import chalk from 'chalk';
+import { isGitRepo, resolvePrimaryRoot } from './worktree.js';
+import { detectDefaultBranch } from '../../lib/git/default-branch.js';
+import { buildPrIndex } from '../../lib/git/pr-index.js';
+import { classifyBranches } from '../../lib/git/branch-classifier.js';
+
+/**
+ * Delete one local branch.
+ *
+ * `-D`, not `-d`, and that is the whole point of the classifier: `-d` refuses
+ * every squash-merged branch, so a command that used it would be unable to do
+ * its one job. The safety does not come from git's own check (which cannot see
+ * a squash-merge) — it comes from only ever reaching this function with a
+ * branch whose integration was positively proven.
+ */
+function deleteLocal(name, cwd) {
+  try {
+    execFileSync('git', ['branch', '-D', name], { cwd, stdio: 'pipe' });
+    return { deleted: true };
+  } catch (err) {
+    return { deleted: false, error: (err.stderr?.toString() || err.message || 'unknown').trim().slice(0, 200) };
+  }
+}
+
+function deleteRemote(name, cwd) {
+  try {
+    execFileSync('git', ['push', 'origin', '--delete', name], { cwd, stdio: 'pipe', timeout: 20000 });
+    return { deleted: true };
+  } catch (err) {
+    return { deleted: false, error: (err.stderr?.toString() || err.message || 'unknown').trim().slice(0, 200) };
+  }
+}
+
+/** Does `origin/<name>` exist locally as a remote-tracking ref? */
+function remoteRefExists(name, cwd) {
+  try {
+    execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/remotes/origin/${name}`], { cwd, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Command handler for `morph-spec branch prune [--remote] [--dry-run] [--json]`.
+ *
+ * Fail-open outside a git repo (exit 0, empty result) — the same discipline the
+ * rest of the worktree suite follows: a housekeeping command must never be the
+ * reason a script dies.
+ *
+ * @param {{ remote?: boolean, dryRun?: boolean, json?: boolean, cwd?: string }} [options]
+ */
+export function branchPruneCommand(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const emit = (payload, code = 0) => {
+    if (options.json) console.log(JSON.stringify(payload, null, 2));
+    else printReport(payload, options);
+    process.exitCode = code;
+    return payload;
+  };
+
+  if (!isGitRepo(cwd)) {
+    return emit({ pruned: [], kept: [], error: 'not-a-git-repo' });
+  }
+  const root = resolvePrimaryRoot(cwd);
+  const defaultBranch = detectDefaultBranch(root);
+  // null = UNKNOWN, never "no PR" — the classifier treats a branch with no
+  // positive evidence as unmerged, so a missing `gh` costs conservatism, not
+  // safety. Reported so the user can tell "no PR" from "could not ask".
+  const prIndex = buildPrIndex(root);
+
+  const classified = classifyBranches({ cwd: root, defaultBranch, prIndex });
+  const pruned = [];
+  const kept = [];
+
+  for (const b of classified) {
+    if (!b.deletable) { kept.push(b); continue; }
+    if (options.dryRun) {
+      pruned.push({ ...b, deleted: false, dryRun: true, remoteDeleted: false });
+      continue;
+    }
+    const local = deleteLocal(b.name, root);
+    let remoteDeleted = false;
+    let remoteError;
+    if (local.deleted && options.remote && remoteRefExists(b.name, root)) {
+      const r = deleteRemote(b.name, root);
+      remoteDeleted = r.deleted;
+      if (!r.deleted) remoteError = r.error;
+    }
+    if (local.deleted) pruned.push({ ...b, deleted: true, remoteDeleted, ...(remoteError ? { remoteError } : {}) });
+    else kept.push({ ...b, kind: 'delete-failed', reason: `git branch -D falhou: ${local.error}`, deletable: false });
+  }
+
+  return emit({
+    defaultBranch,
+    prIndexAvailable: prIndex !== null,
+    dryRun: options.dryRun === true,
+    remote: options.remote === true,
+    pruned,
+    kept,
+  });
+}
+
+const KIND_LABEL = {
+  'merged-ancestral': chalk.green('merged'),
+  'merged-squash': chalk.green('squash-merged'),
+  open: chalk.yellow('PR aberto'),
+  'in-worktree': chalk.cyan('em uso'),
+  unmerged: chalk.red('não integrada'),
+  'delete-failed': chalk.red('falhou'),
+};
+
+function printReport(payload, options) {
+  if (payload.error === 'not-a-git-repo') {
+    console.log(chalk.gray('não é um repositório git — nada a fazer'));
+    return;
+  }
+  const verb = payload.dryRun ? 'seriam apagadas' : 'apagadas';
+  console.log(chalk.bold(`\nbranch prune — default: ${payload.defaultBranch || chalk.red('não resolvida')}`));
+  if (!payload.prIndexAvailable) {
+    // Load-bearing caveat, not noise: without `gh` a squash-merge is only
+    // detectable by the tree comparison, so branches that WERE merged may
+    // legitimately show up as unmerged here.
+    console.log(chalk.gray('  (sem `gh`/GitHub: squash-merge só é detectado por árvore idêntica)'));
+  }
+
+  if (payload.pruned.length) {
+    console.log(chalk.bold(`\n  ${payload.pruned.length} ${verb}:`));
+    for (const b of payload.pruned) {
+      const remote = b.remoteDeleted ? chalk.gray(' + origin') : '';
+      console.log(`    ${KIND_LABEL[b.kind] || b.kind}  ${chalk.bold(b.name)}${remote}`);
+      console.log(chalk.gray(`      ${b.reason}`));
+      if (b.remoteError) console.log(chalk.yellow(`      origin não apagada: ${b.remoteError}`));
+    }
+  } else {
+    console.log(chalk.gray('\n  nada a apagar'));
+  }
+
+  if (payload.kept.length) {
+    console.log(chalk.bold(`\n  ${payload.kept.length} mantida(s):`));
+    for (const b of payload.kept) {
+      console.log(`    ${KIND_LABEL[b.kind] || b.kind}  ${chalk.bold(b.name)}${b.ahead ? chalk.gray(` (+${b.ahead})`) : ''}`);
+      console.log(chalk.gray(`      ${b.reason}`));
+    }
+  }
+  if (payload.dryRun) console.log(chalk.gray('\n  --dry-run: nada foi apagado'));
+  if (!options.remote && payload.pruned.length) console.log(chalk.gray('  branches remotas intactas (use --remote para apagá-las também)'));
+  console.log();
+}