@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

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

@@ -6,7 +6,6 @@ import { heavyDir, runExclusive } from '../../../framework/hooks/shared/heavy-sl
 
 const DOTNET_ACTIVE = /\bdotnet(?:\.exe)?["']?\s+(?:build|test|publish|pack|msbuild|restore|run|watch|vstest)\b/i;
 const IDLE_WORKER = /\/nodemode:\d|vbcscompiler|razorserver/i;
-const SHUTDOWN_SCOPES = new Set(['feature', 'e2e-down', 'prune']);
 const SHUTDOWN_TIMEOUT_MS = 30_000;
 const TAIL_CHARS = 400;
 
@@ -15,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 {
@@ -33,16 +32,13 @@ export function dotnetBusy(procs) {
   });
 }
 
-export function afterHeavyRun({ projectPath, config, scope, env = process.env, deps = {} }) {
+export function afterHeavyRun({ projectPath, config, env = process.env, deps = {} }) {
   const {
     exec = defaultProcExec, list = listProcesses, dotnet = hasDotnet, exclusive = runExclusive,
   } = deps;
 
   if (!config.enabled) return { status: 'skipped', reason: 'semáforo desligado: sem ele nada prova que outra sessão não está compilando' };
   if (!config.shutdownBuildServer) return { status: 'skipped', reason: 'desligado em heavy.shutdownBuildServer' };
-  if (!SHUTDOWN_SCOPES.has(scope)) {
-    return { status: 'skipped', reason: 'escopo de task: o servidor de compilação segue quente para a próxima task' };
-  }
   if (!dotnet(projectPath)) return { status: 'skipped', reason: 'projeto sem .NET' };
 
   const guarded = exclusive({

package/src/lib/installers/effects.js

@@ -1,70 +1,12 @@
-/**
- * effects.js — o coletor de efeitos ÚNICO do caminho de instalação/atualização.
- *
- * A propriedade que faz o `--dry-run` ser honesto está numa frase:
- *
- *   > **o caminho real também emite.**
- *
- * Em modo normal cada verbo EXECUTA e registra; em `dryRun`, só registra. O
- * resumo impresso ao fim de uma execução real sai de `list()`, não de
- * contadores paralelos. A consequência é o ponto: um ponto de emissão
- * esquecido some das DUAS saídas ao mesmo tempo, e o resumo de uma execução
- * real fica visivelmente incompleto — o defeito aparece sem sequer usar o
- * `--dry-run`.
- *
- * **Não há segunda travessia.** Nenhum filtro, walker ou lista de payload é
- * reimplementado aqui. Os filtros que decidem o que instalar
- * (`shouldInstallSkill`, `agentEligible`, `shouldInstall`) já são puros e
- * continuam sendo os únicos. O anti-exemplar tem nome e mora neste
- * repositório: `checkAgentsDrift` funciona como preditor porque re-deriva o
- * conjunto elegível por conta própria e porque os dois lados chamam o mesmo
- * renderer puro. Estender essa forma para 9 payloads + hooks + merge de
- * settings + gitignore + índice do git é reimplementar o instalador inteiro e
- * depender de disciplina humana para mantê-los sincronizados.
- *
- * **Os verbos são SÍNCRONOS de propósito.** Metade dos instaladores que eles
- * atravessam (`installSkills`, `installAgents`, `installRulesForStack`) é
- * síncrona; um coletor assíncrono obrigaria a tornar `installRulesForStack`
- * async e a mudar a assinatura que `setup-infra`, `init` e os testes já usam.
- *
- * **O registro é a IDENTIDADE do efeito, nunca o conteúdo.** `writeFile` grava
- * `{ verb, target }`, não os bytes: `installClaudeHooks` carimba um
- * `generated_at` a cada execução, e comparar conteúdo faria o canário de
- * igualdade dry × real reprovar por causa do relógio.
- */
+// O caminho real também emite: o resumo de uma execução real sai de `list()`, então um ponto de
+// emissão esquecido some das duas saídas. Registra-se a identidade do efeito, nunca o conteúdo:
+// `installClaudeHooks` carimba `generated_at`, e comparar bytes reprovaria a igualdade dry × real.
 
 import fs from 'fs-extra';
 import { spawnSync } from 'node:child_process';
 import { dirname } from 'node:path';
 
-/**
- * @typedef {Object} Effect
- * @property {string} verb   - ensureDir | remove | copyDir | copyFile | writeFile | writeJson | mergeJson | spawn | gitIndex
- * @property {string} target - o caminho (ou comando) sobre o qual o efeito age
- * @property {string} [from] - origem, para os verbos de cópia
- * @property {string} [detail] - qualificador estável (argumentos do spawn, operação do git)
- */
-
-/**
- * Cria um coletor de efeitos.
- *
- * @param {{ dryRun?: boolean }} [options]
- * @returns {{
- *   dryRun: boolean,
- *   ensureDir: (path: string) => void,
- *   remove: (path: string) => void,
- *   copyDir: (from: string, to: string) => void,
- *   copyFile: (from: string, to: string) => void,
- *   writeFile: (path: string, content: string) => void,
- *   writeJson: (path: string, data: object) => void,
- *   mergeJson: (path: string, patch: object) => void,
- *   spawn: (cmd: string, args: string[], options?: object) => object|null,
- *   gitIndex: (op: string, path: string, options?: object) => boolean,
- *   list: () => Effect[],
- * }}
- */
 export function createEffects({ dryRun = false } = {}) {
-  /** @type {Effect[]} */
   const effects = [];
 
   const record = (verb, target, extra = {}) => {
@@ -118,13 +60,7 @@ export function createEffects({ dryRun = false } = {}) {
       }
     },
 
-    /**
-     * Leitura + fusão rasa + escrita, como UM efeito.
-     *
-     * A leitura acontece nos dois modos (ler não muda nada); só a escrita é
-     * suprimida em dry. É assim que `~/.claude/settings.json` — um arquivo do
-     * usuário, FORA do projeto — é atualizado sem que o dry o toque.
-     */
+    // A leitura acontece nos dois modos; só a escrita é suprimida em dry.
     mergeJson(path, patch) {
       record('mergeJson', path);
       if (dryRun) return;
@@ -138,21 +74,9 @@ export function createEffects({ dryRun = false } = {}) {
       fs.writeJsonSync(path, { ...current, ...patch }, { spaces: 2 });
     },
 
-    /**
-     * @param {string} cmd
-     * @param {string[]} args
-     * @param {{ cwd?: string, dryRunArgs?: string[] }} [options]
-     *   `dryRunArgs` é a variante SÓ-LEITURA do mesmo comando (por exemplo
-     *   `--check`). Em dry ela é executada no lugar; sem ela, nada roda.
-     *   O REGISTRO é o mesmo nos dois modos: o efeito previsto é o comando
-     *   real, não a sua sonda.
-     */
+    // `dryRunArgs`: variante só-leitura do comando, executada no lugar em dry; o registro é o comando real.
     spawn(cmd, args = [], options = {}) {
-      // `args` viaja no registro ALÉM do `detail` legível. O `detail` é para
-      // humano; quebrá-lo por espaço para descobrir onde o spawn escreve é o
-      // bug que um caminho como `R:\Polymorphism Tech\...` produz em silêncio,
-      // e que o relatório mostrou pondo um efeito do PACOTE da CLI no grupo
-      // "no projeto".
+      // `args` viaja além do `detail`: quebrar o `detail` por espaço erra caminhos com espaço.
       record('spawn', cmd, { detail: args.join(' '), args: [...args] });
       const { cwd, dryRunArgs } = options;
       if (dryRun) {
@@ -162,11 +86,7 @@ export function createEffects({ dryRun = false } = {}) {
       return spawnSync(cmd, args, { cwd, encoding: 'utf8' });
     },
 
-    /**
-     * Mutação do índice do git (`git rm --cached`, etc.). A SONDA que decide
-     * se há o que fazer fica fora daqui de propósito: sondar é ler, e ler
-     * acontece nos dois modos.
-     */
+    // A sonda que decide se há o que fazer fica fora daqui: sondar é ler, e ler acontece nos dois modos.
     gitIndex(op, path, options = {}) {
       record('gitIndex', path, { detail: op });
       if (dryRun) return true;
@@ -182,12 +102,7 @@ export function createEffects({ dryRun = false } = {}) {
   };
 }
 
-/**
- * Coletor no-op-de-registro para chamadores que não passam um: executa
- * normalmente e registra numa lista descartada. Existe para que assinaturas
- * novas de `installSkills`/`installAgents`/`installRulesForStack` continuem
- * funcionando para `setup-infra` e `init` sem mudança de comportamento.
- */
+// Executa e registra numa lista descartada, para chamadores que não passam um coletor.
 export function realEffects() {
   return createEffects({ dryRun: false });
 }