@polymorphism-tech/morph-spec 8.28.0 → 8.31.0

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 };
+}

package/src/lib/graph/sanitize.js

@@ -0,0 +1,280 @@
+/**
+ * Saneamento determinístico do grafo, sem LLM (ADR-003 + errata D2/D3).
+ *
+ * O graphify 0.9.50 não implementa escopo hierárquico de namespace em C#
+ * (graphify/extractors/csharp.py:322-335): um filho que usa um tipo do
+ * namespace pai sem `using` explícito vira um STUB por arquivo, e o blast
+ * radius do nó real devolve zero consumidores onde existem dois. É falso
+ * negativo silencioso — o pior modo de falha possível antes de um hotfix.
+ *
+ * Três categorias de stub, medidas no MORPH_GHLBrain em 2026-08-27:
+ *
+ *   label com  1 nó real   (60 labels,   226 arestas) => coalesce no real
+ *   label com  0 nós reais (126 labels, 2.479 arestas) => externo (BCL/NuGet)
+ *   label com 2+ nós reais (22 labels,    93 arestas) => AMBÍGUO
+ *
+ * O terceiro grupo são símbolos REAIS do projeto (CatalogSchema, CatalogItem,
+ * Result, Error, KillSwitch — declarados em CatalogContracts.cs e vizinhos),
+ * não BCL. Filtrar "o que sobrou depois de coalescer" os descartaria em
+ * silêncio, reintroduzindo o falso negativo que este módulo existe para matar.
+ * Por isso o critério de externo é `real.length === 0`, nunca "remanescente".
+ *
+ * @module graph-sanitize
+ */
+
+/** Arestas que contam como dependência para blast radius. */
+export const USE_RELATIONS = new Set([
+  'calls', 'references', 'uses', 'imports', 'imports_from',
+  'inherits', 'implements', 'extends', 'dispatches_to', 'indirect_call',
+]);
+
+/**
+ * Herança não é uso. No ProspectPRO, `IHandler` aparece em 193 arquivos no
+ * grep e tem 2 usos reais: é implementada por 98.
+ */
+export const INHERITANCE_RELATIONS = new Set(['inherits', 'implements', 'extends']);
+
+const LANG_BY_EXT = {
+  cs: 'dotnet', csproj: 'dotnet', razor: 'dotnet', cshtml: 'dotnet',
+  ts: 'web', tsx: 'web', js: 'web', jsx: 'web', mjs: 'web', cjs: 'web',
+  sql: 'sql', py: 'python', go: 'go', rs: 'rust', java: 'jvm', kt: 'jvm',
+};
+
+/**
+ * Projeto de teste em qualquer nível. Três formas, e só três, porque
+ * `[^/]*[Tt]ests?/` genérico também casaria `latest/` e `contests/`:
+ *   - o segmento inteiro é `test`/`tests` (qualquer caixa)
+ *   - termina em `.Test`/`.Tests` — a convenção .NET (ProspectPRO.Tests/)
+ *   - termina em `Test`/`Tests` com T maiúsculo — PascalCase (AlvoTests/)
+ */
+const TEST_PATH = /(^|\/)(?:[Tt]ests?|[^/]*\.[Tt]ests?|[^/]*[a-z0-9_]Tests?)\//;
+
+/**
+ * @param {string} sourceFile
+ * @returns {string} família de linguagem do arquivo, ou '' quando desconhecida
+ */
+export function languageOf(sourceFile) {
+  const m = /\.([a-z0-9]+)$/i.exec(sourceFile || '');
+  if (!m) return '';
+  return LANG_BY_EXT[m[1].toLowerCase()] ?? m[1].toLowerCase();
+}
+
+const normOf = (node) => node.norm_label ?? String(node.label ?? '').toLowerCase();
+
+/**
+ * Label sem os parênteses de chamada. O graphify rotula função como `tchau()`
+ * em JS/TS, mas quem consulta digita `tchau` — e em C# o mesmo símbolo aparece
+ * sem parênteses. Sem esta normalização, `graph affected tchau` devolve
+ * not-found num grafo que tem o símbolo.
+ */
+const baseOf = (norm) => norm.replace(/\(\s*\)$/, '');
+
+/**
+ * @typedef {object} GraphIndex
+ * @property {Map<string, object>} byId
+ * @property {Map<string, {real: object[], stub: object[]}>} byLabel
+ * @property {Map<string, object[]>} byBaseLabel label sem `()` -> nós reais
+ * @property {Map<string, string>} coalesce stubId -> id do nó real
+ */
+
+/**
+ * Índice por id e por label + mapa de coalescência. Uma passada pelos nós.
+ *
+ * @param {{nodes: object[], links: object[]}} graph
+ * @returns {GraphIndex}
+ */
+export function buildIndex(graph) {
+  const byId = new Map();
+  const byLabel = new Map();
+
+  for (const node of graph.nodes ?? []) {
+    byId.set(node.id, node);
+    const key = normOf(node);
+    let entry = byLabel.get(key);
+    if (!entry) {
+      entry = { real: [], stub: [] };
+      byLabel.set(key, entry);
+    }
+    // Nó não resolvido tem source_file: "" (string vazia), não campo ausente.
+    (node.source_file ? entry.real : entry.stub).push(node);
+  }
+
+  const coalesce = new Map();
+  const byBaseLabel = new Map();
+  for (const [key, entry] of byLabel) {
+    // 0 real => externo; 2+ reais => ambíguo. Só o caso de 1 é seguro.
+    if (entry.real.length === 1) {
+      for (const stub of entry.stub) coalesce.set(stub.id, entry.real[0].id);
+    }
+    if (entry.real.length === 0) continue;
+    const base = baseOf(key);
+    if (base === key) continue; // já consultável pelo caminho exato
+    const bucket = byBaseLabel.get(base);
+    if (bucket) bucket.push(...entry.real);
+    else byBaseLabel.set(base, [...entry.real]);
+  }
+
+  return { byId, byLabel, byBaseLabel, coalesce };
+}
+
+/**
+ * @param {GraphIndex} index
+ * @param {string} normLabel label já normalizado (minúsculo)
+ * @returns {'resolved'|'coalescible'|'external'|'ambiguous'|'unknown'}
+ */
+export function classifyLabel(index, normLabel) {
+  const entry = index.byLabel.get(normLabel);
+  if (!entry) return 'unknown';
+  if (entry.real.length === 0) return 'external';
+  if (entry.real.length >= 2) return 'ambiguous';
+  return entry.stub.length > 0 ? 'coalescible' : 'resolved';
+}
+
+/**
+ * Para onde uma aresta REALMENTE aponta depois do saneamento.
+ *
+ * @param {GraphIndex} index
+ * @param {object} link
+ * @returns {{id: string|null, kind: 'direct'|'coalesced'|'language-disambiguated'|'external'|'ambiguous'|'unknown'}}
+ */
+export function resolveEdgeTarget(index, link) {
+  const target = index.byId.get(link.target);
+  if (!target) return { id: null, kind: 'unknown' };
+  if (target.source_file) return { id: target.id, kind: 'direct' };
+
+  const coalesced = index.coalesce.get(target.id);
+  if (coalesced) return { id: coalesced, kind: 'coalesced' };
+
+  const entry = index.byLabel.get(normOf(target));
+  if (!entry || entry.real.length === 0) return { id: null, kind: 'external' };
+
+  // D3: uma aresta nascida num .cs só pode apontar para o candidato .cs.
+  // Recupera 54% dos casos ambíguos sem LLM e sem heurística de grau — que é
+  // a alternativa (b) rejeitada na ADR-003 por errar justamente nas interfaces
+  // muito referenciadas.
+  const originLang = languageOf(link.source_file);
+  if (originLang) {
+    const matches = entry.real.filter((n) => languageOf(n.source_file) === originLang);
+    if (matches.length === 1) return { id: matches[0].id, kind: 'language-disambiguated' };
+  }
+
+  return { id: null, kind: 'ambiguous' };
+}
+
+/**
+ * label -> id. Empate real devolve as opções em vez de escolher (ADR-003).
+ *
+ * @param {GraphIndex} index
+ * @param {string} label
+ * @returns {{ok: true, id: string, node: object}|{ok: false, reason: 'not-found'|'ambiguous', options: Array<{id: string, source_file: string}>}}
+ */
+export function resolveLabel(index, label) {
+  const key = String(label).toLowerCase();
+  const exact = index.byLabel.get(key);
+
+  // Match exato primeiro; só depois o label sem `()`, para que quem digitar
+  // `tchau()` e quem digitar `tchau` cheguem no mesmo nó.
+  let candidates = exact && exact.real.length > 0 ? exact.real : null;
+  if (!candidates) candidates = index.byBaseLabel?.get(baseOf(key)) ?? null;
+
+  if (!candidates || candidates.length === 0) {
+    return { ok: false, reason: 'not-found', options: [] };
+  }
+  if (candidates.length === 1) {
+    return { ok: true, id: candidates[0].id, node: candidates[0] };
+  }
+  return {
+    ok: false,
+    reason: 'ambiguous',
+    options: candidates.map((n) => ({ id: n.id, source_file: n.source_file })),
+  };
+}
+
+/**
+ * Blast radius saneado: quem depende de `id`.
+ *
+ * O valor medido não é recall — contra o grep, o grafo achou ZERO arquivos a
+ * mais. É precisão: 58% menos ruído em 12 símbolos do ProspectPRO (1.092
+ * arquivos no grep, 266 usos reais) e a classificação da relação.
+ *
+ * @param {GraphIndex} index
+ * @param {{links: object[]}} graph
+ * @param {string} id
+ * @param {{prod?: boolean, excludeInheritance?: boolean}} [opts]
+ * @returns {Array<{id: string, label: string, source_file: string, source_location: string, relation: string}>}
+ */
+export function affected(index, graph, id, opts = {}) {
+  const seen = new Set();
+  const out = [];
+
+  for (const link of graph.links ?? []) {
+    if (!USE_RELATIONS.has(link.relation)) continue;
+    if (opts.excludeInheritance && INHERITANCE_RELATIONS.has(link.relation)) continue;
+    if (resolveEdgeTarget(index, link).id !== id) continue;
+
+    const source = index.byId.get(link.source);
+    if (!source || !source.source_file) continue;
+    if (opts.prod && TEST_PATH.test(source.source_file)) continue;
+
+    const key = `${source.id}|${link.relation}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    out.push({
+      id: source.id,
+      label: source.label,
+      source_file: source.source_file,
+      source_location: source.source_location ?? '',
+      relation: link.relation,
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Vizinhança de um nó, para `graph explain`. Cada aresta carrega a procedência
+ * (`via`), então dá para ver o que o saneamento recuperou.
+ *
+ * @param {GraphIndex} index
+ * @param {{links: object[]}} graph
+ * @param {string} id
+ */
+export function neighborhood(index, graph, id) {
+  const incoming = [];
+  const outgoing = [];
+
+  for (const link of graph.links ?? []) {
+    const resolved = resolveEdgeTarget(index, link);
+
+    if (resolved.id === id) {
+      const source = index.byId.get(link.source);
+      if (source) {
+        incoming.push({
+          id: source.id,
+          label: source.label,
+          relation: link.relation,
+          source_file: link.source_file || source.source_file,
+          source_location: link.source_location || source.source_location || '',
+          via: resolved.kind,
+        });
+      }
+    }
+
+    if (link.source === id && resolved.id) {
+      const target = index.byId.get(resolved.id);
+      if (target) {
+        outgoing.push({
+          id: target.id,
+          label: target.label,
+          relation: link.relation,
+          source_file: link.source_file || target.source_file,
+          source_location: link.source_location || '',
+          via: resolved.kind,
+        });
+      }
+    }
+  }
+
+  return { node: index.byId.get(id) ?? null, incoming, outgoing };
+}