@optave/codegraph 3.1.3 → 3.1.5

package/src/{viewer.js → presentation/viewer.js}

@@ -1,49 +1,25 @@
+/**
+ * Interactive HTML viewer — presentation layer.
+ *
+ * Exports two concerns:
+ * - renderPlotHTML(): pure data → HTML transform (no I/O) that receives
+ *   prepared graph data and config, returns a self-contained HTML string
+ *   with vis-network. All graph data must be pre-loaded via prepareGraphData().
+ * - loadPlotConfig(): reads .plotDotCfg / .plotDotCfg.json files from disk
+ *   and merges them with defaults. This performs filesystem I/O.
+ *
+ * Color constants are defined in ./colors.js and re-exported here for
+ * backward compatibility.
+ */
+
 import fs from 'node:fs';
 import path from 'node:path';
-import Graph from 'graphology';
-import louvain from 'graphology-communities-louvain';
-import { isTestFile } from './infrastructure/test-filter.js';
-
-const DEFAULT_MIN_CONFIDENCE = 0.5;
-
-const DEFAULT_NODE_COLORS = {
-  function: '#4CAF50',
-  method: '#66BB6A',
-  class: '#2196F3',
-  interface: '#42A5F5',
-  type: '#7E57C2',
-  struct: '#FF7043',
-  enum: '#FFA726',
-  trait: '#26A69A',
-  record: '#EC407A',
-  module: '#78909C',
-  file: '#90A4AE',
-};
+import { COMMUNITY_COLORS, DEFAULT_NODE_COLORS, DEFAULT_ROLE_COLORS } from './colors.js';
 
-const DEFAULT_ROLE_COLORS = {
-  entry: '#e8f5e9',
-  core: '#e3f2fd',
-  utility: '#f5f5f5',
-  dead: '#ffebee',
-  leaf: '#fffde7',
-};
+// Re-export color constants so existing consumers are unaffected
+export { COMMUNITY_COLORS, DEFAULT_NODE_COLORS, DEFAULT_ROLE_COLORS };
 
-const COMMUNITY_COLORS = [
-  '#4CAF50',
-  '#2196F3',
-  '#FF9800',
-  '#9C27B0',
-  '#F44336',
-  '#00BCD4',
-  '#CDDC39',
-  '#E91E63',
-  '#3F51B5',
-  '#FF5722',
-  '#009688',
-  '#795548',
-];
-
-const DEFAULT_CONFIG = {
+export const DEFAULT_CONFIG = {
   layout: { algorithm: 'hierarchical', direction: 'LR' },
   physics: { enabled: true, nodeDistance: 150 },
   nodeColors: DEFAULT_NODE_COLORS,
@@ -60,6 +36,8 @@ const DEFAULT_CONFIG = {
   riskThresholds: { highBlastRadius: 10, lowMI: 40 },
 };
 
+// ─── Config Loading ──────────────────────────────────────────────────
+
 /**
  * Load .plotDotCfg or .plotDotCfg.json from given directory.
  * Returns merged config with defaults.
@@ -105,310 +83,66 @@ export function loadPlotConfig(dir) {
   return { ...DEFAULT_CONFIG };
 }
 
-// ─── Data Preparation ─────────────────────────────────────────────────
-
-/**
- * Prepare enriched graph data for the HTML viewer.
- */
-export function prepareGraphData(db, opts = {}) {
-  const fileLevel = opts.fileLevel !== false;
-  const noTests = opts.noTests || false;
-  const minConf = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
-  const cfg = opts.config || DEFAULT_CONFIG;
-
-  return fileLevel
-    ? prepareFileLevelData(db, noTests, minConf, cfg)
-    : prepareFunctionLevelData(db, noTests, minConf, cfg);
-}
-
-function prepareFunctionLevelData(db, noTests, minConf, cfg) {
-  let edges = db
-    .prepare(
-      `
-      SELECT n1.id AS source_id, n1.name AS source_name, n1.kind AS source_kind,
-             n1.file AS source_file, n1.line AS source_line, n1.role AS source_role,
-             n2.id AS target_id, n2.name AS target_name, n2.kind AS target_kind,
-             n2.file AS target_file, n2.line AS target_line, n2.role AS target_role,
-             e.kind AS edge_kind
-      FROM edges e
-      JOIN nodes n1 ON e.source_id = n1.id
-      JOIN nodes n2 ON e.target_id = n2.id
-      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
-        AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
-        AND e.kind = 'calls'
-        AND e.confidence >= ?
-    `,
-    )
-    .all(minConf);
-  if (noTests)
-    edges = edges.filter((e) => !isTestFile(e.source_file) && !isTestFile(e.target_file));
-
-  if (cfg.filter.kinds) {
-    const kinds = new Set(cfg.filter.kinds);
-    edges = edges.filter((e) => kinds.has(e.source_kind) && kinds.has(e.target_kind));
-  }
-  if (cfg.filter.files) {
-    const patterns = cfg.filter.files;
-    edges = edges.filter(
-      (e) =>
-        patterns.some((p) => e.source_file.includes(p)) &&
-        patterns.some((p) => e.target_file.includes(p)),
-    );
-  }
-
-  const nodeMap = new Map();
-  for (const e of edges) {
-    if (!nodeMap.has(e.source_id)) {
-      nodeMap.set(e.source_id, {
-        id: e.source_id,
-        name: e.source_name,
-        kind: e.source_kind,
-        file: e.source_file,
-        line: e.source_line,
-        role: e.source_role,
-      });
-    }
-    if (!nodeMap.has(e.target_id)) {
-      nodeMap.set(e.target_id, {
-        id: e.target_id,
-        name: e.target_name,
-        kind: e.target_kind,
-        file: e.target_file,
-        line: e.target_line,
-        role: e.target_role,
-      });
-    }
-  }
-
-  if (cfg.filter.roles) {
-    const roles = new Set(cfg.filter.roles);
-    for (const [id, n] of nodeMap) {
-      if (!roles.has(n.role)) nodeMap.delete(id);
-    }
-    const nodeIds = new Set(nodeMap.keys());
-    edges = edges.filter((e) => nodeIds.has(e.source_id) && nodeIds.has(e.target_id));
-  }
-
-  // Complexity data
-  const complexityMap = new Map();
-  try {
-    const rows = db
-      .prepare(
-        'SELECT node_id, cognitive, cyclomatic, max_nesting, maintainability_index FROM function_complexity',
-      )
-      .all();
-    for (const r of rows) {
-      complexityMap.set(r.node_id, {
-        cognitive: r.cognitive,
-        cyclomatic: r.cyclomatic,
-        maintainabilityIndex: r.maintainability_index,
-      });
-    }
-  } catch {
-    // table may not exist in old DBs
-  }
-
-  // Fan-in / fan-out
-  const fanInMap = new Map();
-  const fanOutMap = new Map();
-  const fanInRows = db
-    .prepare(
-      "SELECT target_id AS node_id, COUNT(*) AS fan_in FROM edges WHERE kind = 'calls' GROUP BY target_id",
-    )
-    .all();
-  for (const r of fanInRows) fanInMap.set(r.node_id, r.fan_in);
-
-  const fanOutRows = db
-    .prepare(
-      "SELECT source_id AS node_id, COUNT(*) AS fan_out FROM edges WHERE kind = 'calls' GROUP BY source_id",
-    )
-    .all();
-  for (const r of fanOutRows) fanOutMap.set(r.node_id, r.fan_out);
-
-  // Communities (Louvain)
-  const communityMap = new Map();
-  if (nodeMap.size > 0) {
-    try {
-      const graph = new Graph({ type: 'undirected' });
-      for (const [id] of nodeMap) graph.addNode(String(id));
-      for (const e of edges) {
-        const src = String(e.source_id);
-        const tgt = String(e.target_id);
-        if (src !== tgt && !graph.hasEdge(src, tgt)) graph.addEdge(src, tgt);
-      }
-      const communities = louvain(graph);
-      for (const [nid, cid] of Object.entries(communities)) communityMap.set(Number(nid), cid);
-    } catch {
-      // louvain can fail on disconnected graphs
-    }
-  }
-
-  // Build enriched nodes
-  const visNodes = [...nodeMap.values()].map((n) => {
-    const cx = complexityMap.get(n.id) || null;
-    const fanIn = fanInMap.get(n.id) || 0;
-    const fanOut = fanOutMap.get(n.id) || 0;
-    const community = communityMap.get(n.id) ?? null;
-    const directory = path.dirname(n.file);
-    const risk = [];
-    if (n.role === 'dead') risk.push('dead-code');
-    if (fanIn >= (cfg.riskThresholds?.highBlastRadius ?? 10)) risk.push('high-blast-radius');
-    if (cx && cx.maintainabilityIndex < (cfg.riskThresholds?.lowMI ?? 40)) risk.push('low-mi');
-
-    const color =
-      cfg.colorBy === 'role' && n.role
-        ? cfg.roleColors[n.role] || DEFAULT_ROLE_COLORS[n.role] || '#ccc'
-        : cfg.colorBy === 'community' && community !== null
-          ? COMMUNITY_COLORS[community % COMMUNITY_COLORS.length]
-          : cfg.nodeColors[n.kind] || DEFAULT_NODE_COLORS[n.kind] || '#ccc';
-
-    return {
-      id: n.id,
-      label: n.name,
-      title: `${n.file}:${n.line} (${n.kind}${n.role ? `, ${n.role}` : ''})`,
-      color,
-      kind: n.kind,
-      role: n.role || '',
-      file: n.file,
-      line: n.line,
-      community,
-      cognitive: cx?.cognitive ?? null,
-      cyclomatic: cx?.cyclomatic ?? null,
-      maintainabilityIndex: cx?.maintainabilityIndex ?? null,
-      fanIn,
-      fanOut,
-      directory,
-      risk,
-    };
-  });
-
-  const visEdges = edges.map((e, i) => ({
-    id: `e${i}`,
-    from: e.source_id,
-    to: e.target_id,
-  }));
-
-  // Seed strategy
-  let seedNodeIds;
-  if (cfg.seedStrategy === 'top-fanin') {
-    const sorted = [...visNodes].sort((a, b) => b.fanIn - a.fanIn);
-    seedNodeIds = sorted.slice(0, cfg.seedCount || 30).map((n) => n.id);
-  } else if (cfg.seedStrategy === 'entry') {
-    seedNodeIds = visNodes.filter((n) => n.role === 'entry').map((n) => n.id);
-  } else {
-    seedNodeIds = visNodes.map((n) => n.id);
-  }
+// ─── Internal Helpers ────────────────────────────────────────────────
 
-  return { nodes: visNodes, edges: visEdges, seedNodeIds };
+export function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
 }
 
-function prepareFileLevelData(db, noTests, minConf, cfg) {
-  let edges = db
-    .prepare(
-      `
-      SELECT DISTINCT n1.file AS source, n2.file AS target
-      FROM edges e
-      JOIN nodes n1 ON e.source_id = n1.id
-      JOIN nodes n2 ON e.target_id = n2.id
-      WHERE n1.file != n2.file AND e.kind IN ('imports', 'imports-type', 'calls')
-        AND e.confidence >= ?
-    `,
-    )
-    .all(minConf);
-  if (noTests) edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
-
-  const files = new Set();
-  for (const { source, target } of edges) {
-    files.add(source);
-    files.add(target);
-  }
-
-  const fileIds = new Map();
-  let idx = 0;
-  for (const f of files) fileIds.set(f, idx++);
-
-  // Fan-in/fan-out
-  const fanInCount = new Map();
-  const fanOutCount = new Map();
-  for (const { source, target } of edges) {
-    fanOutCount.set(source, (fanOutCount.get(source) || 0) + 1);
-    fanInCount.set(target, (fanInCount.get(target) || 0) + 1);
-  }
-
-  // Communities
-  const communityMap = new Map();
-  if (files.size > 0) {
-    try {
-      const graph = new Graph({ type: 'undirected' });
-      for (const f of files) graph.addNode(f);
-      for (const { source, target } of edges) {
-        if (source !== target && !graph.hasEdge(source, target)) graph.addEdge(source, target);
-      }
-      const communities = louvain(graph);
-      for (const [file, cid] of Object.entries(communities)) communityMap.set(file, cid);
-    } catch {
-      // ignore
-    }
-  }
+export function buildLayoutOptions(cfg) {
+  const opts = {
+    nodes: {
+      shape: 'box',
+      font: { face: 'monospace', size: 12 },
+    },
+    edges: {
+      arrows: 'to',
+      color: cfg.edgeStyle.color || '#666',
+      smooth: cfg.edgeStyle.smooth !== false,
+    },
+    physics: {
+      enabled: cfg.physics.enabled !== false,
+      barnesHut: {
+        gravitationalConstant: -3000,
+        springLength: cfg.physics.nodeDistance || 150,
+      },
+    },
+    interaction: {
+      tooltipDelay: 200,
+      hover: true,
+    },
+  };
 
-  const visNodes = [...files].map((f) => {
-    const id = fileIds.get(f);
-    const community = communityMap.get(f) ?? null;
-    const fanIn = fanInCount.get(f) || 0;
-    const fanOut = fanOutCount.get(f) || 0;
-    const directory = path.dirname(f);
-    const color =
-      cfg.colorBy === 'community' && community !== null
-        ? COMMUNITY_COLORS[community % COMMUNITY_COLORS.length]
-        : cfg.nodeColors.file || DEFAULT_NODE_COLORS.file;
-
-    return {
-      id,
-      label: path.basename(f),
-      title: f,
-      color,
-      kind: 'file',
-      role: '',
-      file: f,
-      line: 0,
-      community,
-      cognitive: null,
-      cyclomatic: null,
-      maintainabilityIndex: null,
-      fanIn,
-      fanOut,
-      directory,
-      risk: [],
+  if (cfg.layout.algorithm === 'hierarchical') {
+    opts.layout = {
+      hierarchical: {
+        enabled: true,
+        direction: cfg.layout.direction || 'LR',
+        sortMethod: 'directed',
+        nodeSpacing: cfg.physics.nodeDistance || 150,
+      },
     };
-  });
-
-  const visEdges = edges.map(({ source, target }, i) => ({
-    id: `e${i}`,
-    from: fileIds.get(source),
-    to: fileIds.get(target),
-  }));
-
-  let seedNodeIds;
-  if (cfg.seedStrategy === 'top-fanin') {
-    const sorted = [...visNodes].sort((a, b) => b.fanIn - a.fanIn);
-    seedNodeIds = sorted.slice(0, cfg.seedCount || 30).map((n) => n.id);
-  } else if (cfg.seedStrategy === 'entry') {
-    seedNodeIds = visNodes.map((n) => n.id);
-  } else {
-    seedNodeIds = visNodes.map((n) => n.id);
   }
 
-  return { nodes: visNodes, edges: visEdges, seedNodeIds };
+  return opts;
 }
 
-// ─── HTML Generation ──────────────────────────────────────────────────
+// ─── HTML Renderer ───────────────────────────────────────────────────
 
 /**
- * Generate a self-contained interactive HTML file with vis-network.
+ * Render a self-contained interactive HTML file with vis-network.
+ *
+ * Pure transform: prepared graph data + config → HTML string.
+ *
+ * @param {{ nodes: Array, edges: Array, seedNodeIds: Array }} data - From prepareGraphData()
+ * @param {object} cfg - Viewer config (from loadPlotConfig or DEFAULT_CONFIG)
+ * @returns {string} Complete HTML document
  */
-export function generatePlotHTML(db, opts = {}) {
-  const cfg = opts.config || DEFAULT_CONFIG;
-  const data = prepareGraphData(db, opts);
+export function renderPlotHTML(data, cfg) {
   const layoutOpts = buildLayoutOptions(cfg);
   const title = cfg.title || 'Codegraph';
 
@@ -898,51 +632,3 @@ ${(cfg.clusterBy || 'none') !== 'none' ? `applyClusterBy(${JSON.stringify(cfg.cl
 </body>
 </html>`;
 }
-
-// ─── Internal Helpers ─────────────────────────────────────────────────
-
-function escapeHtml(s) {
-  return String(s)
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
-
-function buildLayoutOptions(cfg) {
-  const opts = {
-    nodes: {
-      shape: 'box',
-      font: { face: 'monospace', size: 12 },
-    },
-    edges: {
-      arrows: 'to',
-      color: cfg.edgeStyle.color || '#666',
-      smooth: cfg.edgeStyle.smooth !== false,
-    },
-    physics: {
-      enabled: cfg.physics.enabled !== false,
-      barnesHut: {
-        gravitationalConstant: -3000,
-        springLength: cfg.physics.nodeDistance || 150,
-      },
-    },
-    interaction: {
-      tooltipDelay: 200,
-      hover: true,
-    },
-  };
-
-  if (cfg.layout.algorithm === 'hierarchical') {
-    opts.layout = {
-      hierarchical: {
-        enabled: true,
-        direction: cfg.layout.direction || 'LR',
-        sortMethod: 'directed',
-        nodeSpacing: cfg.physics.nodeDistance || 150,
-      },
-    };
-  }
-
-  return opts;
-}

package/src/{constants.js → shared/constants.js}

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { SUPPORTED_EXTENSIONS } from './parser.js';
+import { SUPPORTED_EXTENSIONS } from '../domain/parser.js';
 
 export const IGNORE_DIRS = new Set([
   'node_modules',

package/src/shared/errors.js

@@ -0,0 +1,78 @@
+/**
+ * Domain error hierarchy for codegraph.
+ *
+ * Library code throws these instead of calling process.exit() or throwing
+ * bare Error instances. The CLI top-level catch formats them for humans;
+ * MCP returns structured { isError, code } responses.
+ */
+
+export class CodegraphError extends Error {
+  /** @type {string} */
+  code;
+
+  /** @type {string|undefined} */
+  file;
+
+  /**
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {string} [opts.code]
+   * @param {string} [opts.file]  - Related file path, if applicable
+   * @param {Error}  [opts.cause] - Original error that triggered this one
+   */
+  constructor(message, { code = 'CODEGRAPH_ERROR', file, cause } = {}) {
+    super(message, { cause });
+    this.name = 'CodegraphError';
+    this.code = code;
+    this.file = file;
+  }
+}
+
+export class ParseError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'PARSE_FAILED', ...opts });
+    this.name = 'ParseError';
+  }
+}
+
+export class DbError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'DB_ERROR', ...opts });
+    this.name = 'DbError';
+  }
+}
+
+export class ConfigError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'CONFIG_INVALID', ...opts });
+    this.name = 'ConfigError';
+  }
+}
+
+export class ResolutionError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'RESOLUTION_FAILED', ...opts });
+    this.name = 'ResolutionError';
+  }
+}
+
+export class EngineError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'ENGINE_UNAVAILABLE', ...opts });
+    this.name = 'EngineError';
+  }
+}
+
+export class AnalysisError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'ANALYSIS_FAILED', ...opts });
+    this.name = 'AnalysisError';
+  }
+}
+
+export class BoundaryError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'BOUNDARY_VIOLATION', ...opts });
+    this.name = 'BoundaryError';
+  }
+}