@polymorphism-tech/morph-spec 8.28.0 → 8.31.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';