@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

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

@@ -1,11 +1,4 @@
-/**
- * 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
- */
+// Nunca devolve erro: o grafo é opcional e não pode pintar de vermelho o doctor de quem não o usa.
 import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
@@ -16,17 +9,8 @@ import { GRAPHIFY_VERSION, detectGraphifyVersion } from './graphify-runtime.js';
 
 const GRAPHIFY_HOOK_MARKER = /# graphify-(?:checkout-)?hook-start/;
 
-/**
- * O hook git do próprio graphify (`graphify hook install`, que o setup-infra
- * instalava até a 8.37) está no repositório? Ele é danoso aqui: num commit
- * depois de um fast-forward carimba o HEAD num grafo SEM os arquivos que o
- * merge trouxe — "fresh" falso — e disputa o graph.json com o refresh do
- * morph-spec. Lê o diretório de hooks que o git usa (`core.hooksPath`
- * incluído).
- *
- * @param {string} projectPath
- * @returns {boolean}
- */
+// O hook git do próprio graphify é danoso: depois de um fast-forward carimba o HEAD num grafo sem os
+// arquivos do merge ("fresh" falso) e disputa o graph.json com o refresh. Respeita `core.hooksPath`.
 export function graphifyGitHookInstalled(projectPath) {
   let dir;
   try {
@@ -46,11 +30,6 @@ export function graphifyGitHookInstalled(projectPath) {
   });
 }
 
-/**
- * @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);

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

@@ -1,15 +1,4 @@
-/**
- * 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
- */
+// A única porta de leitura do grafo, e nada aqui lança: ausência de grafo é um estado válido do projeto.
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import {
@@ -21,18 +10,10 @@ import {
 import { isSecondaryWorktree, workTreeTop } from '../../../framework/hooks/shared/git-paths.js';
 import { GRAPHIFY_PACKAGE, GRAPHIFY_VERSION } from './graphify-runtime.js';
 
-/**
- * @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 };
@@ -57,18 +38,7 @@ export function loadGraph(projectPath) {
   }
 }
 
-/**
- * O frescor do grafo, pela regra única (framework/hooks/shared/graph-freshness.js):
- * o carimbo e o registro da última rodada contra o HEAD, e as regras do
- * `.graphifyignore` por conteúdo. Um grafo velho diz "não existe" sobre o que
- * o último commit trouxe — quem consome precisa saber, ou conclui "ninguém usa
- * isso" a partir dele.
- *
- * @param {string} projectPath
- * @param {object} graph - o graph.json já parseado (o carimbo sai dele)
- * @param {{_head?: (projectPath: string) => string|null}} [deps]
- * @returns {{builtAtCommit: string|null, headCommit: string|null, state: 'fresh'|'stale'|'unknown', reason?: 'ignore-changed'|'rules-unknown'}}
- */
+// Um grafo velho diz "não existe" sobre o que o último commit trouxe: quem consome precisa saber.
 export function getFreshness(projectPath, graph, deps = {}) {
   const f = graphFreshness(projectPath, {
     graph,
@@ -84,12 +54,6 @@ export function getFreshness(projectPath, graph, deps = {}) {
 
 const short = (sha) => (sha ? String(sha).slice(0, 8) : '?');
 
-/**
- * O porquê de um grafo stale, em uma linha — carimbo antigo ou regras.
- *
- * @param {{builtAtCommit: string|null, headCommit: string|null, reason?: string}} freshness
- * @returns {string}
- */
 export function staleCause(freshness) {
   if (freshness.reason === 'ignore-changed') {
     return 'as regras do .graphifyignore mudaram depois da extração';
@@ -100,15 +64,8 @@ export function staleCause(freshness) {
   return `construído em ${short(freshness.builtAtCommit)}, HEAD é ${short(freshness.headCommit)}`;
 }
 
-/**
- * O que o refresh automático faz por esta árvore. Ele cobre só a árvore
- * principal (`auto`); numa worktree, `running` é sempre false — um lock vivo
- * ali seria o refresh da raiz. `last` é a última rodada registrada para esta
- * árvore: em background, manual ou a semeadura.
- *
- * @param {string} projectPath
- * @returns {{auto: boolean, running: boolean, since: string|null, pid: number|null, last: {ok: boolean, exit: number|null, head: string|null, ts: string, unavailable?: boolean, seeded?: boolean}|null}}
- */
+// O refresh automático cobre só a árvore principal; numa worktree `running` é sempre false, porque um
+// lock vivo ali seria o refresh da raiz.
 export function refreshState(projectPath) {
   const auto = isPrimaryTree(projectPath);
   const lock = auto ? readRefreshLock(projectPath) : null;
@@ -129,15 +86,7 @@ export function refreshState(projectPath) {
   };
 }
 
-/**
- * A frase de grafo stale — a mesma no status, no explain, no affected e no
- * doctor, e verdadeira sobre o mecanismo: o refresh em background só cobre a
- * raiz, disparado pelos hooks do morph-spec; a worktree só anda à mão.
- *
- * @param {string} projectPath
- * @param {{builtAtCommit?: string|null, headCommit?: string|null}} [freshness]
- * @returns {string}
- */
+/** A frase única de grafo stale do status, explain, affected e doctor. */
 export function describeStale(projectPath, freshness = {}) {
   const tree = workTreeTop(projectPath) ?? projectPath;
   const state = refreshState(projectPath);

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

@@ -1,23 +1,9 @@
-/**
- * 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
- */
+// O binário é `graphify` (e `graphify-mcp`). NUNCA `python -m graphify.serve`, como manda o README oficial:
+// com `uv tool install` o pacote vive num venv isolado que o Python do sistema não enxerga.
 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.
- */
+// Pin exato: o graphify é pré-1.0 com release quase diária e semver não garante nada; subir é decisão
+// consciente, com o fixture de regressão regerado.
 export const GRAPHIFY_VERSION = '0.9.50';
 export const GRAPHIFY_PACKAGE = 'graphifyy';
 export const GRAPHIFY_BIN = 'graphify';
@@ -38,14 +24,7 @@ function whichSync(bin) {
   }
 }
 
-/**
- * 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}}
- */
+// `kind: null` é "sem Python": o setup registra e segue, e o framework continua funcionando por grep.
 export function detectInstaller(deps = {}) {
   const which = deps._which ?? whichSync;
   for (const kind of PREFERENCE) {
@@ -60,13 +39,7 @@ export function detectInstaller(deps = {}) {
   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[]}}
- */
+// Sem o extra `[sql]` os arquivos .sql são ignorados em silêncio.
 export function installArgs(kind, { withSql }) {
   const spec = `${GRAPHIFY_PACKAGE}${withSql ? '[sql]' : ''}==${GRAPHIFY_VERSION}`;
   switch (kind) {
@@ -82,10 +55,7 @@ export function installArgs(kind, { withSql }) {
   }
 }
 
-/**
- * @param {{_run?: () => string}} [deps]
- * @returns {string|null} versão instalada, ou null se o binário não responde
- */
+/** 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',

package/src/lib/graph/graphifyignore.js

@@ -1,32 +1,6 @@
-/**
- * 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ê. 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.
- *
- * Mas dublê, fixture e helper de teste precisam ser ACHÁVEIS: são o que um
- * teste novo deveria reusar, e fora do grafo `graph explain FakeX` dá
- * not-found. Por isso o conteúdo dos projetos de teste sai e esses arquivos
- * voltam. A forma é ditada pela regra do gitignore que o graphify 0.9.50 segue
- * (detect.py `_is_ignored`): um `!` não reinclui nada sob um diretório já
- * excluído. Medido num fixture: `**\/*.Tests/` + `!**\/Fakes/` não traz nada de
- * volta; excluir o CONTEÚDO (`**\/*.Tests/**`), reincluir os diretórios
- * (`!**\/*.Tests/**\/`) e então os helpers traz. `bin/`/`obj/` vêm DEPOIS das
- * reinclusões — antes, a reinclusão de diretório os devolveria (`obj/` tem
- * `.cs` gerado). No MORPH_GHLBrain: +9,6% de nós (11.591 → 12.706), 94
- * arquivos de teste, nenhum de bin/obj.
- *
- * Os dublês quebram o guard de "implementador único" do `dispatches_to` do
- * graphify (de 122 para 5 arestas no GHLBrain); o saneamento as recupera
- * (sanitize.js `recoverDispatch`) e tira o teste dos god nodes.
- *
- * 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
- */
+// Teste sai do grafo, mas dublês e helpers voltam: são o que um teste novo reusa. Pela regra do gitignore
+// um `!` não reinclui nada sob diretório excluído, então exclui-se o conteúdo, reincluem-se os diretórios e
+// então os helpers; `bin/`/`obj/` vêm depois, senão a reinclusão os devolveria.
 import { writeFileSync, existsSync, readFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
@@ -60,10 +34,7 @@ const WEB_IGNORED = [
 
 const HEADER = '# Gerado por morph-spec (ADR-004). Editável: um arquivo editado nunca é sobrescrito.';
 
-/**
- * O que a versão anterior gerava — os testes .NET inteiros fora. Só existe
- * para reconhecer um arquivo que ninguém editou e trocá-lo pelo atual.
- */
+// O que a geração anterior escrevia: só reconhece um arquivo que ninguém editou, para trocá-lo.
 const PREVIOUS = {
   header: '# Gerado por morph-spec (ADR-004). Editável: o CLI não sobrescreve.',
   dotnetTitle: '# .NET — testes em qualquer nível (tests/ genérico não serve)',
@@ -99,11 +70,6 @@ function render(projectTags, { header, dotnetTitle, dotnet }) {
   return `${lines.join('\n')}\n`;
 }
 
-/**
- * @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 = []) {
   return render(projectTags, {
     header: HEADER,
@@ -114,28 +80,8 @@ export function buildGraphifyignore(projectTags = []) {
 
 const normalize = (text) => String(text).replace(/^/, '').replace(/\r\n/g, '\n');
 
-/**
- * Escreve ou migra o .graphifyignore.
- *
- *   ausente                                → escreve o atual
- *   idêntico ao que a versão anterior
- *   gerava para as mesmas tags             → troca pelo atual (`migrated`) —
- *                                            só se as REGRAS mudam (em
- *                                            projeto sem .NET a diferença é
- *                                            só o cabeçalho, e reescrever
- *                                            seria um diff à toa num arquivo
- *                                            versionado)
- *   qualquer outra coisa                   → é do usuário: não toca, e em
- *                                            projeto .NET que ainda exclui os
- *                                            testes inteiros devolve em
- *                                            `outdated` a troca a fazer
- *
- * @param {string} projectPath
- * @param {string[]} [projectTags]
- * @param {{fx?: {writeFile: (path: string, content: string) => void}}} [opts]
- *   coletor de efeitos do `update` — com ele, o `--dry-run` prevê a escrita
- * @returns {{written: boolean, migrated?: boolean, outdated?: {remove: string[], add: string[]}, path: string}}
- */
+// Ausente → escreve. Idêntico ao que a geração anterior escrevia → migra, só se as regras mudam.
+// Qualquer outra coisa é do usuário: não toca, e em .NET devolve em `outdated` a troca a fazer.
 export function writeGraphifyignore(projectPath, projectTags = [], { fx } = {}) {
   const path = join(projectPath, '.graphifyignore');
   const current = buildGraphifyignore(projectTags);
@@ -172,26 +118,14 @@ export function writeGraphifyignore(projectPath, projectTags = [], { fx } = {})
   return { written: false, path };
 }
 
-/**
- * A frase que todo chamador imprime para um `outdated` — uma só.
- *
- * @param {{remove: string[], add: string[]}} outdated
- * @returns {string}
- */
+/** A frase única que todo chamador imprime para um `outdated`. */
 export function describeOutdatedIgnore(outdated) {
   return `.graphifyignore editado mantém os testes .NET inteiros fora do grafo ` +
     `(dublês e fixtures dão not-found). Troque ${outdated.remove.join(' ')} por, nesta ordem e ` +
     `antes de bin/ e obj/: ${outdated.add.join(' ')} — depois, morph-spec graph refresh`;
 }
 
-/**
- * O `.graphifyignore` é versionado? Então uma migração só chega às worktrees
- * e ao resto do time depois de commitada — cada checkout lê o seu. Fail-open:
- * sem git, false.
- *
- * @param {string} projectPath
- * @returns {boolean}
- */
+// Versionado, uma migração só chega às worktrees depois de commitada. Fail-open: sem git, false.
 export function graphifyignoreTracked(projectPath) {
   try {
     execFileSync('git', ['ls-files', '--error-unmatch', '--', '.graphifyignore'], {

package/src/lib/graph/sanitize.js

@@ -1,26 +1,6 @@
-/**
- * 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
- */
+// O graphify não resolve escopo hierárquico de namespace em C#: tipo do namespace pai vira stub por arquivo.
+// Label com 1 nó real coalesce; 0 reais é externo; 2+ reais é ambíguo e são símbolos do projeto, por isso
+// externo é `real.length === 0`, nunca "o que sobrou".
 
 /** Arestas que contam como dependência para blast radius. */
 export const USE_RELATIONS = new Set([
@@ -28,10 +8,7 @@ export const USE_RELATIONS = new Set([
   '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.
- */
+/** Herança não é uso: uma interface muito implementada tem poucos usos reais. */
 export const INHERITANCE_RELATIONS = new Set(['inherits', 'implements', 'extends']);
 
 const LANG_BY_EXT = {
@@ -40,31 +17,15 @@ const LANG_BY_EXT = {
   sql: 'sql', py: 'python', go: 'go', rs: 'rust', java: 'jvm', kt: 'jvm',
 };
 
-/**
- * Código de teste — o predicado ÚNICO de "isto é teste" do grafo e do
- * validador de reuso. Pasta de projeto de teste em qualquer nível, em 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/)
- * mais o teste colocado ao lado do código em JS/TS: `__tests__/`,
- * `*.test.*` e `*.spec.*`.
- */
+// O predicado único de teste do grafo e do validador de reuso. Só três formas de pasta, porque
+// `[^/]*[Tt]ests?/` genérico também casaria `latest/` e `contests/`.
 const TEST_PATH = /(^|\/)__tests__\/|\.(test|spec)\.[jt]sx?$|(^|\/)(?:[Tt]ests?|[^/]*\.[Tt]ests?|[^/]*[a-z0-9_]Tests?)\//;
 
-/**
- * @param {string} sourceFile
- * @returns {boolean} o arquivo é código de teste (dublê, fixture ou o teste em si)
- */
 export function isTestPath(sourceFile) {
   return TEST_PATH.test(String(sourceFile || '').replace(/\\/g, '/'));
 }
 
-/**
- * @param {string} sourceFile
- * @returns {string} família de linguagem do arquivo, ou '' quando desconhecida
- */
+/** Família de linguagem do arquivo, ou '' quando desconhecida. */
 export function languageOf(sourceFile) {
   const m = /\.([a-z0-9]+)$/i.exec(sourceFile || '');
   if (!m) return '';
@@ -73,29 +34,9 @@ export function languageOf(sourceFile) {
 
 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.
- */
+// O graphify rotula função como `tchau()` em JS/TS, mas quem consulta digita `tchau`, e em C# não há parênteses.
 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
- * @property {object[]} recovered `dispatches_to` recuperados (ver recoverDispatch)
- */
-
-/**
- * Í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();
@@ -121,7 +62,7 @@ export function buildIndex(graph) {
     }
     if (entry.real.length === 0) continue;
     const base = baseOf(key);
-    if (base === key) continue; // já consultável pelo caminho exato
+    if (base === key) continue;
     const bucket = byBaseLabel.get(base);
     if (bucket) bucket.push(...entry.real);
     else byBaseLabel.set(base, [...entry.real]);
@@ -137,21 +78,8 @@ const isCsharp = (node) => Boolean(node?.source_file) && /\.cs$/i.test(node.sour
 /** Nome do método sem o ponto inicial e sem a assinatura, como o graphify casa. */
 const methodName = (node) => String(node.label ?? '').trim().replace(/^\./, '').split('(')[0];
 
-/**
- * `dispatches_to` que o graphify deixou de emitir por causa de um dublê de
- * teste. O resolvedor dele (graphify/csharp_dispatch.py) liga o método da
- * interface ao da implementação só quando há EXATAMENTE um implementador — e
- * um `FakeX : IX` no grafo é o segundo. Este é o mesmo algoritmo, com o guard
- * contando só implementadores de produção. Medido no MORPH_GHLBrain: com os
- * dublês no grafo o graphify cai de 122 para 5 arestas, e esta função devolve
- * as 122 do grafo sem testes, nenhuma a mais.
- *
- * Aditivo: um par que o graphify já emitiu não é repetido.
- *
- * @param {GraphIndex} index
- * @param {{links?: object[]}} graph
- * @returns {object[]} arestas sintéticas, marcadas `_recovered: true`
- */
+// O resolvedor do graphify liga interface a implementação só com EXATAMENTE um implementador, e um
+// dublê `FakeX : IX` é o segundo. Mesmo algoritmo contando só produção; aditivo, nunca repete um par.
 function recoverDispatch(index, graph) {
   const implementers = new Map();
   const methodsOf = new Map();
@@ -204,24 +132,12 @@ function recoverDispatch(index, graph) {
   return recovered;
 }
 
-/**
- * As arestas do grafo mais as recuperadas pelo saneamento — o conjunto que
- * todo consumidor deve percorrer.
- *
- * @param {GraphIndex} index
- * @param {{links?: object[]}} graph
- * @returns {object[]}
- */
+/** As arestas do grafo mais as recuperadas pelo saneamento: o conjunto que todo consumidor percorre. */
 export function linksOf(index, graph) {
   const own = graph.links ?? [];
   return index.recovered?.length ? own.concat(index.recovered) : own;
 }
 
-/**
- * @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';
@@ -230,13 +146,6 @@ export function classifyLabel(index, normLabel) {
   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' };
@@ -248,10 +157,8 @@ export function resolveEdgeTarget(index, link) {
   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.
+  // Uma aresta nascida num .cs só pode apontar para o candidato .cs: desambigua sem heurística de grau,
+  // que erra justamente nas interfaces muito referenciadas.
   const originLang = languageOf(link.source_file);
   if (originLang) {
     const matches = entry.real.filter((n) => languageOf(n.source_file) === originLang);
@@ -261,13 +168,7 @@ export function resolveEdgeTarget(index, link) {
   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}>}}
- */
+/** Empate real devolve as opções em vez de escolher. */
 export function resolveLabel(index, label) {
   const key = String(label).toLowerCase();
   const exact = index.byLabel.get(key);
@@ -290,19 +191,6 @@ export function resolveLabel(index, label) {
   };
 }
 
-/**
- * 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, test: boolean}>}
- */
 export function affected(index, graph, id, opts = {}) {
   const seen = new Set();
   const out = [];
@@ -334,15 +222,7 @@ export function affected(index, graph, id, opts = {}) {
   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, e `test` diz se a
- * outra ponta é código de teste.
- *
- * @param {GraphIndex} index
- * @param {{links: object[]}} graph
- * @param {string} id
- */
+/** Cada aresta carrega a procedência (`via`); `test` diz se a outra ponta é código de teste. */
 export function neighborhood(index, graph, id) {
   const incoming = [];
   const outgoing = [];

package/src/lib/heavy/cleanup.js

@@ -14,7 +14,7 @@ function hasDotnet(projectPath) {
   const stack = config?.project?.stack;
   try {
     if (stack && getBuildSteps(stack, { cwd: projectPath }).some((s) => /\bdotnet\b/.test(s.command))) return true;
-  } catch { /* stack sem passo de build */ }
+  } catch {}
   try {
     return readdirSync(projectPath).some((n) => /\.(sln|slnx|csproj)$/i.test(n));
   } catch {