@polymorphism-tech/morph-spec 8.28.0 → 8.31.0

package/src/lib/generators/settings-generator.js

@@ -1,209 +1,209 @@
-/**
- * Settings Generator
- *
- * Generates .claude/settings.local.json for projects based on detected
- * stack, MCPs, and morph-spec configuration. Uses _morph_managed marker
- * to track managed entries for safe reset.
- */
-
-import { join } from 'path';
-import { existsSync } from 'fs';
-import { readFile, writeFile, mkdir } from 'fs/promises';
-
-const MORPH_MANAGED_KEY = '_morph_managed';
-
-/**
- * Generate and merge settings for a project
- * @param {string} targetPath - Project root directory
- * @param {Object} detectedConfig - Output from detectClaudeConfig()
- * @param {Object} morphConfig - morph-spec config (from .morph/config/config.json)
- * @returns {Promise<Object>} Generated settings summary
- */
-export async function generateSettings(targetPath, detectedConfig, morphConfig = {}) {
-  const claudeDir = join(targetPath, '.claude');
-  const settingsPath = join(claudeDir, 'settings.local.json');
-
-  // Read existing settings
-  const existing = await readSettingsSafe(settingsPath);
-
-  // Build stack-based permissions
-  const stack = morphConfig?.project?.architecture || 'unknown';
-  const permissions = buildPermissions(stack, detectedConfig);
-
-  // Build generated settings
-  const generated = {};
-
-  if (permissions.length > 0) {
-    generated.permissions = permissions;
-  }
-
-  // Track what we manage
-  const managed = {
-    permissions_added: permissions,
-    mcps_detected: detectedConfig.mcpServers.map(s => s.name),
-    plugins_detected: detectedConfig.plugins.map(p => p.name),
-    generated_at: new Date().toISOString()
-  };
-
-  // Merge without overwriting user config
-  const merged = mergeSettings(existing, generated);
-  merged[MORPH_MANAGED_KEY] = managed;
-
-  // Ensure directory exists
-  if (!existsSync(claudeDir)) {
-    await mkdir(claudeDir, { recursive: true });
-  }
-
-  await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
-
-  return {
-    settingsPath,
-    permissionsAdded: permissions.length,
-    managed
-  };
-}
-
-/**
- * Build permission rules based on detected stack
- * @param {string} stack - Detected project stack
- * @param {Object} detectedConfig - Detected Claude config
- * @returns {Array<string>} Permission patterns
- */
-export function buildPermissions(stack, detectedConfig = {}) {
-  const permissions = [];
-
-  // Stack-based permissions
-  const stackPermissions = {
-    nodejs: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
-    typescript: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)', 'Bash(tsc:*)'],
-    nextjs: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
-    react: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
-    vue: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
-    dotnet: ['Bash(dotnet:*)', 'Bash(nuget:*)'],
-    python: ['Bash(python:*)', 'Bash(pip:*)', 'Bash(pytest:*)'],
-    go: ['Bash(go:*)']
-  };
-
-  if (stackPermissions[stack]) {
-    permissions.push(...stackPermissions[stack]);
-  }
-
-  // morph-spec CLI always needs node/npx
-  if (!permissions.includes('Bash(npx:*)')) {
-    permissions.push('Bash(npx:*)');
-  }
-
-  return permissions;
-}
-
-/**
- * Deep merge settings without overwriting user entries
- * @param {Object} existing - Current settings.local.json
- * @param {Object} generated - Generated settings to merge
- * @returns {Object} Merged settings
- */
-export function mergeSettings(existing, generated) {
-  const result = { ...existing };
-
-  for (const [key, value] of Object.entries(generated)) {
-    if (key === MORPH_MANAGED_KEY) continue;
-
-    if (Array.isArray(value) && Array.isArray(result[key])) {
-      // Merge arrays without duplicates
-      const set = new Set(result[key]);
-      for (const item of value) {
-        set.add(item);
-      }
-      result[key] = [...set];
-    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-      // Recursively merge objects
-      result[key] = mergeSettings(result[key] || {}, value);
-    } else if (!(key in result)) {
-      // Only add new keys, never overwrite existing
-      result[key] = value;
-    }
-  }
-
-  return result;
-}
-
-/**
- * Remove only morph-spec managed entries from settings
- * @param {string} settingsPath - Path to settings.local.json
- * @returns {Promise<Object>} Summary of what was removed
- */
-export async function resetMorphSettings(settingsPath) {
-  if (!existsSync(settingsPath)) {
-    return { removed: false, reason: 'file not found' };
-  }
-
-  const settings = await readSettingsSafe(settingsPath);
-  const managed = settings[MORPH_MANAGED_KEY];
-
-  if (!managed) {
-    return { removed: false, reason: 'no _morph_managed section found' };
-  }
-
-  // Remove managed permissions
-  if (managed.permissions_added && Array.isArray(settings.permissions)) {
-    settings.permissions = settings.permissions.filter(
-      p => !managed.permissions_added.includes(p)
-    );
-    if (settings.permissions.length === 0) {
-      delete settings.permissions;
-    }
-  }
-
-  // Remove the managed marker itself
-  delete settings[MORPH_MANAGED_KEY];
-
-  // Write back
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-
-  return {
-    removed: true,
-    permissionsRemoved: managed.permissions_added || [],
-    previouslyGenerated: managed.generated_at
-  };
-}
-
-/**
- * Save integrations.json with detected config
- * @param {string} targetPath - Project root directory
- * @param {Object} detectedConfig - Output from detectClaudeConfig()
- */
-export async function saveIntegrations(targetPath, detectedConfig) {
-  const integrationsPath = join(targetPath, '.morph', 'config', 'integrations.json');
-  const integrationsDir = join(targetPath, '.morph', 'config');
-
-  if (!existsSync(integrationsDir)) {
-    await mkdir(integrationsDir, { recursive: true });
-  }
-
-  const integrations = {
-    version: '1.0.0',
-    detectedAt: new Date().toISOString(),
-    plugins: detectedConfig.plugins,
-    mcpServers: detectedConfig.mcpServers,
-    superpowers: detectedConfig.superpowers,
-    customSkills: detectedConfig.customSkills.length,
-    customCommands: detectedConfig.customCommands.length,
-    hooks: detectedConfig.hooks.length
-  };
-
-  await writeFile(integrationsPath, JSON.stringify(integrations, null, 2) + '\n', 'utf-8');
-  return integrationsPath;
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-async function readSettingsSafe(settingsPath) {
-  try {
-    if (!existsSync(settingsPath)) return {};
-    return JSON.parse(await readFile(settingsPath, 'utf-8'));
-  } catch {
-    return {};
-  }
-}
+/**
+ * Settings Generator
+ *
+ * Generates .claude/settings.local.json for projects based on detected
+ * stack, MCPs, and morph-spec configuration. Uses _morph_managed marker
+ * to track managed entries for safe reset.
+ */
+
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+
+const MORPH_MANAGED_KEY = '_morph_managed';
+
+/**
+ * Generate and merge settings for a project
+ * @param {string} targetPath - Project root directory
+ * @param {Object} detectedConfig - Output from detectClaudeConfig()
+ * @param {Object} morphConfig - morph-spec config (from .morph/config/config.json)
+ * @returns {Promise<Object>} Generated settings summary
+ */
+export async function generateSettings(targetPath, detectedConfig, morphConfig = {}) {
+  const claudeDir = join(targetPath, '.claude');
+  const settingsPath = join(claudeDir, 'settings.local.json');
+
+  // Read existing settings
+  const existing = await readSettingsSafe(settingsPath);
+
+  // Build stack-based permissions
+  const stack = morphConfig?.project?.architecture || 'unknown';
+  const permissions = buildPermissions(stack, detectedConfig);
+
+  // Build generated settings
+  const generated = {};
+
+  if (permissions.length > 0) {
+    generated.permissions = permissions;
+  }
+
+  // Track what we manage
+  const managed = {
+    permissions_added: permissions,
+    mcps_detected: detectedConfig.mcpServers.map(s => s.name),
+    plugins_detected: detectedConfig.plugins.map(p => p.name),
+    generated_at: new Date().toISOString()
+  };
+
+  // Merge without overwriting user config
+  const merged = mergeSettings(existing, generated);
+  merged[MORPH_MANAGED_KEY] = managed;
+
+  // Ensure directory exists
+  if (!existsSync(claudeDir)) {
+    await mkdir(claudeDir, { recursive: true });
+  }
+
+  await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+
+  return {
+    settingsPath,
+    permissionsAdded: permissions.length,
+    managed
+  };
+}
+
+/**
+ * Build permission rules based on detected stack
+ * @param {string} stack - Detected project stack
+ * @param {Object} detectedConfig - Detected Claude config
+ * @returns {Array<string>} Permission patterns
+ */
+export function buildPermissions(stack, detectedConfig = {}) {
+  const permissions = [];
+
+  // Stack-based permissions
+  const stackPermissions = {
+    nodejs: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    typescript: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)', 'Bash(tsc:*)'],
+    nextjs: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    react: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    vue: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    dotnet: ['Bash(dotnet:*)', 'Bash(nuget:*)'],
+    python: ['Bash(python:*)', 'Bash(pip:*)', 'Bash(pytest:*)'],
+    go: ['Bash(go:*)']
+  };
+
+  if (stackPermissions[stack]) {
+    permissions.push(...stackPermissions[stack]);
+  }
+
+  // morph-spec CLI always needs node/npx
+  if (!permissions.includes('Bash(npx:*)')) {
+    permissions.push('Bash(npx:*)');
+  }
+
+  return permissions;
+}
+
+/**
+ * Deep merge settings without overwriting user entries
+ * @param {Object} existing - Current settings.local.json
+ * @param {Object} generated - Generated settings to merge
+ * @returns {Object} Merged settings
+ */
+export function mergeSettings(existing, generated) {
+  const result = { ...existing };
+
+  for (const [key, value] of Object.entries(generated)) {
+    if (key === MORPH_MANAGED_KEY) continue;
+
+    if (Array.isArray(value) && Array.isArray(result[key])) {
+      // Merge arrays without duplicates
+      const set = new Set(result[key]);
+      for (const item of value) {
+        set.add(item);
+      }
+      result[key] = [...set];
+    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      // Recursively merge objects
+      result[key] = mergeSettings(result[key] || {}, value);
+    } else if (!(key in result)) {
+      // Only add new keys, never overwrite existing
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Remove only morph-spec managed entries from settings
+ * @param {string} settingsPath - Path to settings.local.json
+ * @returns {Promise<Object>} Summary of what was removed
+ */
+export async function resetMorphSettings(settingsPath) {
+  if (!existsSync(settingsPath)) {
+    return { removed: false, reason: 'file not found' };
+  }
+
+  const settings = await readSettingsSafe(settingsPath);
+  const managed = settings[MORPH_MANAGED_KEY];
+
+  if (!managed) {
+    return { removed: false, reason: 'no _morph_managed section found' };
+  }
+
+  // Remove managed permissions
+  if (managed.permissions_added && Array.isArray(settings.permissions)) {
+    settings.permissions = settings.permissions.filter(
+      p => !managed.permissions_added.includes(p)
+    );
+    if (settings.permissions.length === 0) {
+      delete settings.permissions;
+    }
+  }
+
+  // Remove the managed marker itself
+  delete settings[MORPH_MANAGED_KEY];
+
+  // Write back
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+
+  return {
+    removed: true,
+    permissionsRemoved: managed.permissions_added || [],
+    previouslyGenerated: managed.generated_at
+  };
+}
+
+/**
+ * Save integrations.json with detected config
+ * @param {string} targetPath - Project root directory
+ * @param {Object} detectedConfig - Output from detectClaudeConfig()
+ */
+export async function saveIntegrations(targetPath, detectedConfig) {
+  const integrationsPath = join(targetPath, '.morph', 'config', 'integrations.json');
+  const integrationsDir = join(targetPath, '.morph', 'config');
+
+  if (!existsSync(integrationsDir)) {
+    await mkdir(integrationsDir, { recursive: true });
+  }
+
+  const integrations = {
+    version: '1.0.0',
+    detectedAt: new Date().toISOString(),
+    plugins: detectedConfig.plugins,
+    mcpServers: detectedConfig.mcpServers,
+    superpowers: detectedConfig.superpowers,
+    customSkills: detectedConfig.customSkills.length,
+    customCommands: detectedConfig.customCommands.length,
+    hooks: detectedConfig.hooks.length
+  };
+
+  await writeFile(integrationsPath, JSON.stringify(integrations, null, 2) + '\n', 'utf-8');
+  return integrationsPath;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+async function readSettingsSafe(settingsPath) {
+  try {
+    if (!existsSync(settingsPath)) return {};
+    return JSON.parse(await readFile(settingsPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}

package/src/lib/graph/god-nodes.js

@@ -0,0 +1,75 @@
+/**
+ * God nodes e comunidades para o contexto de arquitetura.
+ *
+ * O inventário do architecture-scanner diz o que EXISTE; os god nodes dizem o
+ * que é CENTRAL. No ProspectPRO, seis linhas (`Result` 223, `Abstractions` 217,
+ * `Repository` 156, `cn()` 141) orientam melhor que 665 de inventário — sem
+ * substituí-lo, porque exaustividade é um valor que o grafo não tem.
+ *
+ * Só entram nós COM source_file: um god node sem arquivo não orienta ninguém.
+ *
+ * @module god-nodes
+ */
+import { loadGraph } from './graph-loader.js';
+import { buildIndex, resolveEdgeTarget } from './sanitize.js';
+
+/** Sem `graphify label`, as comunidades se chamam Community_N — ruído puro. */
+const PLACEHOLDER_LABEL = /^Community[_ ]?\d+$/i;
+
+/**
+ * @param {string} projectPath
+ * @param {{top?: number, topCommunities?: number}} [opts]
+ * @returns {Promise<{available: boolean, godNodes: Array<{label: string, source_file: string, degree: number}>, communities: Array<{id: number, label: string, size: number, labeled: boolean}>}>}
+ */
+export async function scanGraph(projectPath, opts = {}) {
+  const top = opts.top ?? 10;
+  const topCommunities = opts.topCommunities ?? 10;
+
+  const loaded = loadGraph(projectPath);
+  if (!loaded.ok) return { available: false, godNodes: [], communities: [] };
+
+  const { graph } = loaded;
+  const index = buildIndex(graph);
+
+  // Grau depois do saneamento: a coalescência muda quem é central, porque as
+  // arestas que apontavam para stub passam a contar no nó real.
+  const degree = new Map();
+  const bump = (id) => {
+    if (id) degree.set(id, (degree.get(id) ?? 0) + 1);
+  };
+  for (const link of graph.links ?? []) {
+    bump(link.source);
+    bump(resolveEdgeTarget(index, link).id);
+  }
+
+  const godNodes = [...degree.entries()]
+    .map(([id, d]) => ({ node: index.byId.get(id), degree: d }))
+    .filter(({ node }) => node?.source_file)
+    .sort((a, b) => b.degree - a.degree || a.node.label.localeCompare(b.node.label))
+    .slice(0, top)
+    .map(({ node, degree: d }) => ({
+      label: node.label,
+      source_file: node.source_file,
+      degree: d,
+    }));
+
+  const sizes = new Map();
+  const labels = new Map();
+  for (const node of graph.nodes ?? []) {
+    if (node.community === undefined || node.community === null) continue;
+    sizes.set(node.community, (sizes.get(node.community) ?? 0) + 1);
+    if (node.community_label && !labels.has(node.community)) {
+      labels.set(node.community, node.community_label);
+    }
+  }
+
+  const communities = [...sizes.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0] - b[0])
+    .slice(0, topCommunities)
+    .map(([id, size]) => {
+      const label = labels.get(id) ?? `Community_${id}`;
+      return { id, label, size, labeled: !PLACEHOLDER_LABEL.test(label) };
+    });
+
+  return { available: true, godNodes, communities };
+}

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

@@ -0,0 +1,61 @@
+/**
+ * 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
+ */
+import { loadGraph, getFreshness } from './graph-loader.js';
+import { GRAPHIFY_VERSION, detectGraphifyVersion } from './graphify-runtime.js';
+
+/**
+ * @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);
+
+  if (!loaded.ok && loaded.reason === 'missing') {
+    return {
+      status: 'absent',
+      msg: 'opcional, não gerado — morph-spec graph build',
+      details: [],
+    };
+  }
+  if (!loaded.ok) {
+    return {
+      status: 'warn',
+      msg: `graph.json ${loaded.reason} — regenere com: morph-spec graph build`,
+      details: [loaded.path],
+    };
+  }
+
+  const { graph } = loaded;
+  const details = [`${graph.nodes.length} nós, ${graph.links.length} arestas`];
+  let status = 'ok';
+
+  const freshness = getFreshness(projectPath, graph);
+  if (freshness.state === 'stale') {
+    status = 'warn';
+    details.push(
+      `stale: construído em ${freshness.builtAtCommit.slice(0, 8)}, HEAD é ${freshness.headCommit.slice(0, 8)} — morph-spec graph refresh`,
+    );
+  }
+
+  if (!installed) {
+    status = 'warn';
+    details.push(`graphify não está no PATH (pinado: ${GRAPHIFY_VERSION})`);
+  } else if (installed !== GRAPHIFY_VERSION) {
+    status = 'warn';
+    details.push(`graphify ${installed} instalado; ${GRAPHIFY_VERSION} é a versão pinada e medida`);
+  }
+
+  return {
+    status,
+    msg: status === 'ok' ? details[0] : details[details.length - 1],
+    details,
+  };
+}

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

@@ -0,0 +1,86 @@
+/**
+ * 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
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/**
+ * @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 };
+
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch {
+    return { ok: false, reason: 'unreadable', path };
+  }
+
+  try {
+    const graph = JSON.parse(raw.replace(/^/, ''));
+    // A chave das arestas é `links`, não `edges`. Um JSON válido sem uma das
+    // duas listas não é um grafo utilizável.
+    if (!graph || !Array.isArray(graph.nodes) || !Array.isArray(graph.links)) {
+      return { ok: false, reason: 'malformed', path };
+    }
+    return { ok: true, graph, path };
+  } catch {
+    return { ok: false, reason: 'malformed', path };
+  }
+}
+
+function readHead(projectPath) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: projectPath,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * O hook post-commit do graphify rebuilda em BACKGROUND: logo depois de um
+ * commit o grafo ainda é o do commit anterior. Quem consome precisa saber, ou
+ * conclui "ninguém usa isso" a partir de um grafo velho.
+ *
+ * @param {string} projectPath
+ * @param {object} graph
+ * @param {{_head?: (projectPath: string) => string|null}} [deps]
+ * @returns {{builtAtCommit: string|null, headCommit: string|null, state: 'fresh'|'stale'|'unknown'}}
+ */
+export function getFreshness(projectPath, graph, deps = {}) {
+  const headCommit = (deps._head ?? readHead)(projectPath);
+  const builtAtCommit = graph?.built_at_commit ?? null;
+  if (!headCommit || !builtAtCommit) {
+    return { builtAtCommit, headCommit, state: 'unknown' };
+  }
+  return {
+    builtAtCommit,
+    headCommit,
+    state: builtAtCommit === headCommit ? 'fresh' : 'stale',
+  };
+}