@polymorphism-tech/morph-spec 8.29.0 → 8.32.0

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

package/src/lib/hooks/hook-executor.js

@@ -1,167 +1,167 @@
-/**
- * Hook Executor — Agent Teams hook validation
- *
- * Executes validation hooks triggered by Claude Code agent-teams events:
- *   TeammateIdle, TaskCompleted, PhaseAdvanced
- *
- * Reads agents.json to find validators with matching hook_triggers,
- * then runs each validator's checks against the current project state.
- *
- * @module hook-executor
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-// ============================================================================
-// Loaders
-// ============================================================================
-
-function loadAgents(projectPath) {
-  const agentPaths = [
-    join(projectPath, '.morph/framework/agents.json'),
-  ];
-
-  const allAgents = {};
-  for (const agentPath of agentPaths) {
-    if (existsSync(agentPath)) {
-      try {
-        const data = JSON.parse(readFileSync(agentPath, 'utf8'));
-        Object.assign(allAgents, data.agents || {});
-      } catch (e) { /* skip malformed files */ }
-    }
-  }
-  return allAgents;
-}
-
-function loadStateFeature(projectPath, featureName) {
-  const statePath = join(projectPath, '.morph/state.json');
-  if (!existsSync(statePath)) return null;
-
-  const state = JSON.parse(readFileSync(statePath, 'utf8'));
-  const features = state.features;
-
-  // Support both object format { featureName: {...} } and array format [{name, ...}]
-  if (Array.isArray(features)) {
-    return features.find(f => f.name === featureName) || null;
-  }
-  return features[featureName] || null;
-}
-
-// ============================================================================
-// Main Executor
-// ============================================================================
-
-/**
- * Execute agent-teams hook validation
- * @param {string} projectPath - Absolute path to project root
- * @param {string} featureName - Feature to validate
- * @param {string} hookEvent - Event name (TeammateIdle, TaskCompleted, PhaseAdvanced)
- * @param {Object} [opts]
- * @param {boolean} [opts.dryRun=false] - Identify validators without running them
- * @param {boolean} [opts.verbose=true] - Print results to console
- * @returns {Promise<Object>} { passed, blocked, errors, warnings }
- */
-export async function executeHook(projectPath, featureName, hookEvent, opts = {}) {
-  const { dryRun = false } = opts;
-
-  // Load feature state
-  const feature = loadStateFeature(projectPath, featureName);
-  if (!feature) {
-    return {
-      passed: false,
-      blocked: true,
-      errors: [`Feature not found: ${featureName}`],
-      warnings: []
-    };
-  }
-
-  // Load all available agents
-  const agents = loadAgents(projectPath);
-
-  // Filter: agents that run in hooks AND trigger on this event
-  const hookValidators = Object.entries(agents)
-    .filter(([, agent]) =>
-      agent.relationships?.runs_in === 'hooks' &&
-      Array.isArray(agent.relationships?.hook_triggers) &&
-      agent.relationships.hook_triggers.includes(hookEvent)
-    )
-    .map(([agentId, agent]) => ({ agentId, ...agent }));
-
-  // No validators configured for this event, or dry run — pass immediately
-  if (hookValidators.length === 0 || dryRun) {
-    return { passed: true, blocked: false, errors: [], warnings: [] };
-  }
-
-  // Run validators
-  // In production, each validator would execute its actual checks.
-  // This implementation returns pass since real validation requires external tooling.
-  const errors = [];
-  const warnings = [];
-
-  const passed = errors.length === 0;
-  const blocked = errors.some(e => typeof e === 'object' && e.blocksOnFail !== false);
-
-  return { passed, blocked, errors, warnings };
-}
-
-// ============================================================================
-// Formatter
-// ============================================================================
-
-/**
- * Format hook execution results as a human-readable string
- * @param {Object} results - Result from executeHook
- * @param {string} hookEvent - Event name
- * @returns {string} Formatted output
- */
-export function formatHookResults(results, hookEvent) {
-  const { passed, blocked, errors = [], warnings = [] } = results;
-  const lines = [];
-
-  if (!passed && errors.length > 0) {
-    lines.push(`❌ Hook: ${hookEvent}`);
-    lines.push('FAILED');
-    lines.push('ERRORS (blocking):');
-
-    for (const err of errors) {
-      if (err.issues && Array.isArray(err.issues)) {
-        for (const issue of err.issues) {
-          lines.push(`  ${issue.message}`);
-          if (issue.file && issue.line !== undefined) {
-            lines.push(`  ${issue.file}:${issue.line}`);
-          }
-        }
-      } else if (err.error) {
-        lines.push(`  Error: ${err.error}`);
-      } else if (typeof err === 'string') {
-        lines.push(`  ${err}`);
-      }
-    }
-
-    if (blocked) {
-      lines.push('BLOCKED');
-    }
-  } else if (warnings.length === 0) {
-    lines.push(`✅ Hook: ${hookEvent}`);
-    lines.push('All validators passed');
-  }
-
-  if (warnings.length > 0) {
-    lines.push(`⚠️ Hook: ${hookEvent}`);
-    lines.push('WARNINGS (non-blocking):');
-
-    for (const warn of warnings) {
-      if (warn.issues && Array.isArray(warn.issues)) {
-        for (const issue of warn.issues) {
-          lines.push(`  ${issue.message}`);
-          if (issue.file && issue.line !== undefined) {
-            lines.push(`  ${issue.file}:${issue.line}`);
-          }
-        }
-      }
-    }
-  }
-
-  return lines.join('\n');
-}
+/**
+ * Hook Executor — Agent Teams hook validation
+ *
+ * Executes validation hooks triggered by Claude Code agent-teams events:
+ *   TeammateIdle, TaskCompleted, PhaseAdvanced
+ *
+ * Reads agents.json to find validators with matching hook_triggers,
+ * then runs each validator's checks against the current project state.
+ *
+ * @module hook-executor
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// ============================================================================
+// Loaders
+// ============================================================================
+
+function loadAgents(projectPath) {
+  const agentPaths = [
+    join(projectPath, '.morph/framework/agents.json'),
+  ];
+
+  const allAgents = {};
+  for (const agentPath of agentPaths) {
+    if (existsSync(agentPath)) {
+      try {
+        const data = JSON.parse(readFileSync(agentPath, 'utf8'));
+        Object.assign(allAgents, data.agents || {});
+      } catch (e) { /* skip malformed files */ }
+    }
+  }
+  return allAgents;
+}
+
+function loadStateFeature(projectPath, featureName) {
+  const statePath = join(projectPath, '.morph/state.json');
+  if (!existsSync(statePath)) return null;
+
+  const state = JSON.parse(readFileSync(statePath, 'utf8'));
+  const features = state.features;
+
+  // Support both object format { featureName: {...} } and array format [{name, ...}]
+  if (Array.isArray(features)) {
+    return features.find(f => f.name === featureName) || null;
+  }
+  return features[featureName] || null;
+}
+
+// ============================================================================
+// Main Executor
+// ============================================================================
+
+/**
+ * Execute agent-teams hook validation
+ * @param {string} projectPath - Absolute path to project root
+ * @param {string} featureName - Feature to validate
+ * @param {string} hookEvent - Event name (TeammateIdle, TaskCompleted, PhaseAdvanced)
+ * @param {Object} [opts]
+ * @param {boolean} [opts.dryRun=false] - Identify validators without running them
+ * @param {boolean} [opts.verbose=true] - Print results to console
+ * @returns {Promise<Object>} { passed, blocked, errors, warnings }
+ */
+export async function executeHook(projectPath, featureName, hookEvent, opts = {}) {
+  const { dryRun = false } = opts;
+
+  // Load feature state
+  const feature = loadStateFeature(projectPath, featureName);
+  if (!feature) {
+    return {
+      passed: false,
+      blocked: true,
+      errors: [`Feature not found: ${featureName}`],
+      warnings: []
+    };
+  }
+
+  // Load all available agents
+  const agents = loadAgents(projectPath);
+
+  // Filter: agents that run in hooks AND trigger on this event
+  const hookValidators = Object.entries(agents)
+    .filter(([, agent]) =>
+      agent.relationships?.runs_in === 'hooks' &&
+      Array.isArray(agent.relationships?.hook_triggers) &&
+      agent.relationships.hook_triggers.includes(hookEvent)
+    )
+    .map(([agentId, agent]) => ({ agentId, ...agent }));
+
+  // No validators configured for this event, or dry run — pass immediately
+  if (hookValidators.length === 0 || dryRun) {
+    return { passed: true, blocked: false, errors: [], warnings: [] };
+  }
+
+  // Run validators
+  // In production, each validator would execute its actual checks.
+  // This implementation returns pass since real validation requires external tooling.
+  const errors = [];
+  const warnings = [];
+
+  const passed = errors.length === 0;
+  const blocked = errors.some(e => typeof e === 'object' && e.blocksOnFail !== false);
+
+  return { passed, blocked, errors, warnings };
+}
+
+// ============================================================================
+// Formatter
+// ============================================================================
+
+/**
+ * Format hook execution results as a human-readable string
+ * @param {Object} results - Result from executeHook
+ * @param {string} hookEvent - Event name
+ * @returns {string} Formatted output
+ */
+export function formatHookResults(results, hookEvent) {
+  const { passed, blocked, errors = [], warnings = [] } = results;
+  const lines = [];
+
+  if (!passed && errors.length > 0) {
+    lines.push(`❌ Hook: ${hookEvent}`);
+    lines.push('FAILED');
+    lines.push('ERRORS (blocking):');
+
+    for (const err of errors) {
+      if (err.issues && Array.isArray(err.issues)) {
+        for (const issue of err.issues) {
+          lines.push(`  ${issue.message}`);
+          if (issue.file && issue.line !== undefined) {
+            lines.push(`  ${issue.file}:${issue.line}`);
+          }
+        }
+      } else if (err.error) {
+        lines.push(`  Error: ${err.error}`);
+      } else if (typeof err === 'string') {
+        lines.push(`  ${err}`);
+      }
+    }
+
+    if (blocked) {
+      lines.push('BLOCKED');
+    }
+  } else if (warnings.length === 0) {
+    lines.push(`✅ Hook: ${hookEvent}`);
+    lines.push('All validators passed');
+  }
+
+  if (warnings.length > 0) {
+    lines.push(`⚠️ Hook: ${hookEvent}`);
+    lines.push('WARNINGS (non-blocking):');
+
+    for (const warn of warnings) {
+      if (warn.issues && Array.isArray(warn.issues)) {
+        for (const issue of warn.issues) {
+          lines.push(`  ${issue.message}`);
+          if (issue.file && issue.line !== undefined) {
+            lines.push(`  ${issue.file}:${issue.line}`);
+          }
+        }
+      }
+    }
+  }
+
+  return lines.join('\n');
+}