@optave/codegraph 3.3.0 → 3.4.0

package/src/presentation/{structure.js → structure.ts}

@@ -3,7 +3,29 @@ import { hotspotsData, moduleBoundariesData, structureData } from '../features/s
 
 export { hotspotsData, moduleBoundariesData, structureData };
 
-export function formatStructure(data) {
+interface DirectoryEntry {
+  directory: string;
+  cohesion: number | null;
+  fileCount: number;
+  symbolCount: number;
+  fanIn: number;
+  fanOut: number;
+  files: Array<{
+    file: string;
+    lineCount: number;
+    symbolCount: number;
+    fanIn: number;
+    fanOut: number;
+  }>;
+}
+
+interface StructureResult {
+  count: number;
+  directories: DirectoryEntry[];
+  warning?: string;
+}
+
+export function formatStructure(data: StructureResult): string {
   if (data.count === 0) return 'No directory structure found. Run "codegraph build" first.';
 
   const lines = [`\nProject structure (${data.count} directories):\n`];
@@ -22,12 +44,31 @@ export function formatStructure(data) {
   }
   if (data.warning) {
     lines.push('');
-    lines.push(`⚠ ${data.warning}`);
+    lines.push(`\u26A0 ${data.warning}`);
   }
   return lines.join('\n');
 }
 
-export function formatHotspots(data) {
+interface HotspotEntry {
+  name: string;
+  kind: string;
+  fileCount?: number;
+  cohesion?: number | null;
+  lineCount?: number;
+  symbolCount?: number;
+  fanIn?: number;
+  fanOut?: number;
+}
+
+interface HotspotsResult {
+  metric: string;
+  level: string;
+  limit: number;
+  // biome-ignore lint/suspicious/noExplicitAny: hotspots shape varies by level
+  hotspots: any[];
+}
+
+export function formatHotspots(data: HotspotsResult): string {
   if (data.hotspots.length === 0) return 'No hotspots found. Run "codegraph build" first.';
 
   const lines = [`\nHotspots by ${data.metric} (${data.level}-level, top ${data.limit}):\n`];
@@ -35,7 +76,7 @@ export function formatHotspots(data) {
   for (const h of data.hotspots) {
     const extra =
       h.kind === 'directory'
-        ? `${h.fileCount} files, cohesion=${h.cohesion !== null ? h.cohesion.toFixed(2) : 'n/a'}`
+        ? `${h.fileCount} files, cohesion=${h.cohesion !== null ? h.cohesion!.toFixed(2) : 'n/a'}`
         : `${h.lineCount || 0}L, ${h.symbolCount || 0} symbols`;
     lines.push(
       `  ${String(rank++).padStart(2)}. ${h.name}  <-${h.fanIn || 0} ->${h.fanOut || 0}  (${extra})`,
@@ -44,7 +85,23 @@ export function formatHotspots(data) {
   return lines.join('\n');
 }
 
-export function formatModuleBoundaries(data) {
+interface ModuleBoundaryEntry {
+  directory: string;
+  cohesion: number;
+  fileCount: number;
+  symbolCount: number;
+  fanIn: number;
+  fanOut: number;
+  files: string[];
+}
+
+interface ModuleBoundariesResult {
+  threshold: number;
+  count: number;
+  modules: ModuleBoundaryEntry[];
+}
+
+export function formatModuleBoundaries(data: ModuleBoundariesResult): string {
   if (data.count === 0) return `No modules found with cohesion >= ${data.threshold}.`;
 
   const lines = [`\nModule boundaries (cohesion >= ${data.threshold}, ${data.count} modules):\n`];

package/src/presentation/{table.js → table.ts}

@@ -4,16 +4,22 @@
  * Pure data → formatted string transforms. No I/O — callers handle printing.
  */
 
+export interface ColumnDef {
+  header: string;
+  width: number;
+  align?: 'left' | 'right';
+}
+
+export interface FormatTableOpts {
+  columns: ColumnDef[];
+  rows: string[][];
+  indent?: number;
+}
+
 /**
  * Format a table with aligned columns.
- *
- * @param {object} opts
- * @param {Array<{ header: string, width: number, align?: 'left'|'right' }>} opts.columns
- * @param {string[][]} opts.rows - Each row is an array of string cell values
- * @param {number} [opts.indent=2] - Leading spaces per line
- * @returns {string} Formatted table string (header + separator + data rows)
  */
-export function formatTable({ columns, rows, indent = 2 }) {
+export function formatTable({ columns, rows, indent = 2 }: FormatTableOpts): string {
   const prefix = ' '.repeat(indent);
   const header = columns
     .map((c) => (c.align === 'right' ? c.header.padStart(c.width) : c.header.padEnd(c.width)))
@@ -33,7 +39,7 @@ export function formatTable({ columns, rows, indent = 2 }) {
 /**
  * Truncate a string from the end, appending '\u2026' if truncated.
  */
-export function truncEnd(str, maxLen) {
+export function truncEnd(str: string, maxLen: number): string {
   if (str.length <= maxLen) return str;
   return `${str.slice(0, maxLen - 1)}\u2026`;
 }

package/src/presentation/{triage.js → triage.ts}

@@ -1,13 +1,49 @@
 import { triageData } from '../features/triage.js';
 import { outputResult } from '../infrastructure/result-formatter.js';
 
-/**
- * Print triage results to console.
- */
-export function triage(customDbPath, opts = {}) {
-  const data = triageData(customDbPath, opts);
+interface TriageOpts {
+  json?: boolean;
+  ndjson?: boolean;
+  table?: boolean;
+  csv?: boolean;
+  noTests?: boolean;
+  sort?: string;
+  kind?: string;
+  role?: string;
+  file?: string;
+  minScore?: number;
+  limit?: number;
+  offset?: number;
+  config?: unknown;
+  weights?: Record<string, number>;
+}
+
+interface TriageItem {
+  name: string;
+  file: string;
+  role: string | null;
+  riskScore: number;
+  fanIn: number;
+  cognitive: number;
+  churn: number;
+  maintainabilityIndex: number;
+}
+
+interface TriageSummary {
+  total: number;
+  analyzed: number;
+  avgScore: number;
+  maxScore: number;
+}
+
+export function triage(customDbPath: string | undefined, opts: TriageOpts = {}): void {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic shape from triageData
+  const data = triageData(customDbPath, opts as any) as {
+    items: TriageItem[];
+    summary: TriageSummary;
+  };
 
-  if (outputResult(data, 'items', opts)) return;
+  if (outputResult(data as unknown as Record<string, unknown>, 'items', opts)) return;
 
   if (data.items.length === 0) {
     if (data.summary.total === 0) {
@@ -28,8 +64,8 @@ export function triage(customDbPath, opts = {}) {
   );
 
   for (const it of data.items) {
-    const name = it.name.length > 33 ? `${it.name.slice(0, 32)}…` : it.name;
-    const file = it.file.length > 26 ? `…${it.file.slice(-25)}` : it.file;
+    const name = it.name.length > 33 ? `${it.name.slice(0, 32)}\u2026` : it.name;
+    const file = it.file.length > 26 ? `\u2026${it.file.slice(-25)}` : it.file;
     const role = (it.role || '-').padEnd(8);
     const score = it.riskScore.toFixed(2).padStart(6);
     const fanIn = String(it.fanIn).padStart(7);

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

@@ -1,17 +1,3 @@
-/**
- * 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 { COMMUNITY_COLORS, DEFAULT_NODE_COLORS, DEFAULT_ROLE_COLORS } from './colors.js';
@@ -19,7 +5,24 @@ import { COMMUNITY_COLORS, DEFAULT_NODE_COLORS, DEFAULT_ROLE_COLORS } from './co
 // Re-export color constants so existing consumers are unaffected
 export { COMMUNITY_COLORS, DEFAULT_NODE_COLORS, DEFAULT_ROLE_COLORS };
 
-export const DEFAULT_CONFIG = {
+export interface PlotConfig {
+  layout?: { algorithm?: string; direction?: string };
+  physics?: { enabled?: boolean; nodeDistance?: number };
+  nodeColors?: Record<string, string>;
+  roleColors?: Record<string, string>;
+  colorBy?: string;
+  edgeStyle?: { color?: string; smooth?: boolean };
+  filter?: { kinds?: string[] | null; roles?: string[] | null; files?: string[] | null };
+  title?: string;
+  seedStrategy?: string;
+  seedCount?: number;
+  clusterBy?: string;
+  sizeBy?: string;
+  overlays?: { complexity?: boolean; risk?: boolean };
+  riskThresholds?: { highBlastRadius?: number; lowMI?: number };
+}
+
+export const DEFAULT_CONFIG: PlotConfig = {
   layout: { algorithm: 'hierarchical', direction: 'LR' },
   physics: { enabled: true, nodeDistance: 150 },
   nodeColors: DEFAULT_NODE_COLORS,
@@ -38,16 +41,12 @@ export const DEFAULT_CONFIG = {
 
 // ─── Config Loading ──────────────────────────────────────────────────
 
-/**
- * Load .plotDotCfg or .plotDotCfg.json from given directory.
- * Returns merged config with defaults.
- */
-export function loadPlotConfig(dir) {
+export function loadPlotConfig(dir: string): PlotConfig {
   for (const name of ['.plotDotCfg', '.plotDotCfg.json']) {
     const p = path.join(dir, name);
     if (fs.existsSync(p)) {
       try {
-        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8')) as Partial<PlotConfig>;
         return {
           ...DEFAULT_CONFIG,
           ...raw,
@@ -85,7 +84,7 @@ export function loadPlotConfig(dir) {
 
 // ─── Internal Helpers ────────────────────────────────────────────────
 
-export function escapeHtml(s) {
+export function escapeHtml(s: string): string {
   return String(s)
     .replace(/&/g, '&amp;')
     .replace(/</g, '&lt;')
@@ -93,22 +92,40 @@ export function escapeHtml(s) {
     .replace(/"/g, '&quot;');
 }
 
-export function buildLayoutOptions(cfg) {
-  const opts = {
+interface LayoutOptions {
+  nodes: { shape: string; font: { face: string; size: number } };
+  edges: { arrows: string; color: string; smooth: boolean };
+  physics: {
+    enabled: boolean;
+    barnesHut: { gravitationalConstant: number; springLength: number };
+  };
+  interaction: { tooltipDelay: number; hover: boolean };
+  layout?: {
+    hierarchical: {
+      enabled: boolean;
+      direction: string;
+      sortMethod: string;
+      nodeSpacing: number;
+    };
+  };
+}
+
+export function buildLayoutOptions(cfg: PlotConfig): LayoutOptions {
+  const opts: LayoutOptions = {
     nodes: {
       shape: 'box',
       font: { face: 'monospace', size: 12 },
     },
     edges: {
       arrows: 'to',
-      color: cfg.edgeStyle.color || '#666',
-      smooth: cfg.edgeStyle.smooth !== false,
+      color: cfg.edgeStyle?.color || '#666',
+      smooth: cfg.edgeStyle?.smooth !== false,
     },
     physics: {
-      enabled: cfg.physics.enabled !== false,
+      enabled: cfg.physics?.enabled !== false,
       barnesHut: {
         gravitationalConstant: -3000,
-        springLength: cfg.physics.nodeDistance || 150,
+        springLength: cfg.physics?.nodeDistance || 150,
       },
     },
     interaction: {
@@ -117,13 +134,13 @@ export function buildLayoutOptions(cfg) {
     },
   };
 
-  if (cfg.layout.algorithm === 'hierarchical') {
+  if (cfg.layout?.algorithm === 'hierarchical') {
     opts.layout = {
       hierarchical: {
         enabled: true,
-        direction: cfg.layout.direction || 'LR',
+        direction: cfg.layout?.direction || 'LR',
         sortMethod: 'directed',
-        nodeSpacing: cfg.physics.nodeDistance || 150,
+        nodeSpacing: cfg.physics?.nodeDistance || 150,
       },
     };
   }
@@ -133,20 +150,45 @@ export function buildLayoutOptions(cfg) {
 
 // ─── HTML Renderer ───────────────────────────────────────────────────
 
-/**
- * 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 renderPlotHTML(data, cfg) {
+export interface ViewerNode {
+  id: number | string;
+  label: string;
+  kind: string;
+  file: string;
+  line: number;
+  role: string | null;
+  fanIn: number;
+  fanOut: number;
+  cognitive: number | null;
+  cyclomatic: number | null;
+  maintainabilityIndex: number | null;
+  community: number | null;
+  directory: string | null;
+  risk: string[];
+}
+
+export interface ViewerEdge {
+  id: number | string;
+  from: number | string;
+  to: number | string;
+}
+
+export interface ViewerData {
+  nodes: ViewerNode[];
+  edges: ViewerEdge[];
+  seedNodeIds: (number | string)[];
+}
+
+export function renderPlotHTML(data: ViewerData, cfg: PlotConfig): string {
   const layoutOpts = buildLayoutOptions(cfg);
   const title = cfg.title || 'Codegraph';
 
   // Resolve effective colorBy (overlays.complexity overrides)
+  const layoutAlgorithm = cfg.layout?.algorithm || 'hierarchical';
+  const layoutDirection = cfg.layout?.direction || 'LR';
+  const physicsEnabled = cfg.physics?.enabled !== false;
+  const sizeBy = cfg.sizeBy || 'uniform';
+  const clusterBy = cfg.clusterBy || 'none';
   const effectiveColorBy =
     cfg.overlays?.complexity && cfg.colorBy === 'kind' ? 'complexity' : cfg.colorBy || 'kind';
   const effectiveRisk = cfg.overlays?.risk || false;
@@ -192,12 +234,12 @@ export function renderPlotHTML(data, cfg) {
 <div id="controls">
   <label>Layout:
     <select id="layoutSelect">
-      <option value="hierarchical"${cfg.layout.algorithm === 'hierarchical' ? ' selected' : ''}>Hierarchical</option>
-      <option value="force"${cfg.layout.algorithm === 'force' ? ' selected' : ''}>Force</option>
-      <option value="radial"${cfg.layout.algorithm === 'radial' ? ' selected' : ''}>Radial</option>
+      <option value="hierarchical"${layoutAlgorithm === 'hierarchical' ? ' selected' : ''}>Hierarchical</option>
+      <option value="force"${layoutAlgorithm === 'force' ? ' selected' : ''}>Force</option>
+      <option value="radial"${layoutAlgorithm === 'radial' ? ' selected' : ''}>Radial</option>
     </select>
   </label>
-  <label>Physics: <input type="checkbox" id="physicsToggle"${cfg.physics.enabled ? ' checked' : ''}></label>
+  <label>Physics: <input type="checkbox" id="physicsToggle"${physicsEnabled ? ' checked' : ''}></label>
   <label>Search: <input type="text" id="searchInput" placeholder="Filter nodes..."></label>
   <label>Color by:
     <select id="colorBySelect">
@@ -209,17 +251,17 @@ export function renderPlotHTML(data, cfg) {
   </label>
   <label>Size by:
     <select id="sizeBySelect">
-      <option value="uniform"${(cfg.sizeBy || 'uniform') === 'uniform' ? ' selected' : ''}>Uniform</option>
-      <option value="fan-in"${cfg.sizeBy === 'fan-in' ? ' selected' : ''}>Fan-in</option>
-      <option value="fan-out"${cfg.sizeBy === 'fan-out' ? ' selected' : ''}>Fan-out</option>
-      <option value="complexity"${cfg.sizeBy === 'complexity' ? ' selected' : ''}>Complexity</option>
+      <option value="uniform"${sizeBy === 'uniform' ? ' selected' : ''}>Uniform</option>
+      <option value="fan-in"${sizeBy === 'fan-in' ? ' selected' : ''}>Fan-in</option>
+      <option value="fan-out"${sizeBy === 'fan-out' ? ' selected' : ''}>Fan-out</option>
+      <option value="complexity"${sizeBy === 'complexity' ? ' selected' : ''}>Complexity</option>
     </select>
   </label>
   <label>Cluster by:
     <select id="clusterBySelect">
-      <option value="none"${(cfg.clusterBy || 'none') === 'none' ? ' selected' : ''}>None</option>
-      <option value="community"${cfg.clusterBy === 'community' ? ' selected' : ''}>Community</option>
-      <option value="directory"${cfg.clusterBy === 'directory' ? ' selected' : ''}>Directory</option>
+      <option value="none"${clusterBy === 'none' ? ' selected' : ''}>None</option>
+      <option value="community"${clusterBy === 'community' ? ' selected' : ''}>Community</option>
+      <option value="directory"${clusterBy === 'directory' ? ' selected' : ''}>Directory</option>
     </select>
   </label>
   <label>Risk: <input type="checkbox" id="riskToggle"${effectiveRisk ? ' checked' : ''}></label>
@@ -581,7 +623,7 @@ network.on('doubleClick', function(params) {
 document.getElementById('layoutSelect').addEventListener('change', function(e) {
   var val = e.target.value;
   if (val === 'hierarchical') {
-    network.setOptions({ layout: { hierarchical: { enabled: true, direction: ${JSON.stringify(cfg.layout.direction || 'LR')} } }, physics: { enabled: document.getElementById('physicsToggle').checked } });
+    network.setOptions({ layout: { hierarchical: { enabled: true, direction: ${JSON.stringify(layoutDirection)} } }, physics: { enabled: document.getElementById('physicsToggle').checked } });
   } else if (val === 'radial') {
     network.setOptions({ layout: { hierarchical: false, improvedLayout: true }, physics: { enabled: true, solver: 'repulsion', repulsion: { nodeDistance: 200 } } });
   } else {
@@ -627,7 +669,7 @@ document.getElementById('detailClose').addEventListener('click', hideDetail);
 /* ── Init ──────────────────────────────────────────────────────────── */
 refreshNodeAppearance();
 updateLegend(${JSON.stringify(effectiveColorBy)});
-${(cfg.clusterBy || 'none') !== 'none' ? `applyClusterBy(${JSON.stringify(cfg.clusterBy)});` : ''}
+${clusterBy !== 'none' ? `applyClusterBy(${JSON.stringify(clusterBy)});` : ''}
 </script>
 </body>
 </html>`;

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

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { SUPPORTED_EXTENSIONS } from '../domain/parser.js';
 
-export const IGNORE_DIRS = new Set([
+export const IGNORE_DIRS: Set<string> = new Set([
   'node_modules',
   '.git',
   'dist',
@@ -22,11 +22,11 @@ export const IGNORE_DIRS = new Set([
 
 export { SUPPORTED_EXTENSIONS as EXTENSIONS };
 
-export function shouldIgnore(dirName) {
+export function shouldIgnore(dirName: string): boolean {
   return IGNORE_DIRS.has(dirName) || dirName.startsWith('.');
 }
 
-export function isSupportedFile(filePath) {
+export function isSupportedFile(filePath: string): boolean {
   return SUPPORTED_EXTENSIONS.has(path.extname(filePath));
 }
 
@@ -34,6 +34,6 @@ export function isSupportedFile(filePath) {
  * Normalize a file path to always use forward slashes.
  * Ensures cross-platform consistency in the SQLite database.
  */
-export function normalizePath(filePath) {
+export function normalizePath(filePath: string): string {
   return filePath.split(path.sep).join('/');
 }

package/src/shared/{errors.js → errors.ts}

@@ -6,21 +6,17 @@
  * MCP returns structured { isError, code } responses.
  */
 
-export class CodegraphError extends Error {
-  /** @type {string} */
-  code;
+export interface CodegraphErrorOpts {
+  code?: string;
+  file?: string;
+  cause?: Error;
+}
 
-  /** @type {string|undefined} */
-  file;
+export class CodegraphError extends Error {
+  code: string;
+  file: string | undefined;
 
-  /**
-   * @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 } = {}) {
+  constructor(message: string, { code = 'CODEGRAPH_ERROR', file, cause }: CodegraphErrorOpts = {}) {
     super(message, { cause });
     this.name = 'CodegraphError';
     this.code = code;
@@ -29,49 +25,49 @@ export class CodegraphError extends Error {
 }
 
 export class ParseError extends CodegraphError {
-  constructor(message, opts = {}) {
+  constructor(message: string, opts: CodegraphErrorOpts = {}) {
     super(message, { code: 'PARSE_FAILED', ...opts });
     this.name = 'ParseError';
   }
 }
 
 export class DbError extends CodegraphError {
-  constructor(message, opts = {}) {
+  constructor(message: string, opts: CodegraphErrorOpts = {}) {
     super(message, { code: 'DB_ERROR', ...opts });
     this.name = 'DbError';
   }
 }
 
 export class ConfigError extends CodegraphError {
-  constructor(message, opts = {}) {
+  constructor(message: string, opts: CodegraphErrorOpts = {}) {
     super(message, { code: 'CONFIG_INVALID', ...opts });
     this.name = 'ConfigError';
   }
 }
 
 export class ResolutionError extends CodegraphError {
-  constructor(message, opts = {}) {
+  constructor(message: string, opts: CodegraphErrorOpts = {}) {
     super(message, { code: 'RESOLUTION_FAILED', ...opts });
     this.name = 'ResolutionError';
   }
 }
 
 export class EngineError extends CodegraphError {
-  constructor(message, opts = {}) {
+  constructor(message: string, opts: CodegraphErrorOpts = {}) {
     super(message, { code: 'ENGINE_UNAVAILABLE', ...opts });
     this.name = 'EngineError';
   }
 }
 
 export class AnalysisError extends CodegraphError {
-  constructor(message, opts = {}) {
+  constructor(message: string, opts: CodegraphErrorOpts = {}) {
     super(message, { code: 'ANALYSIS_FAILED', ...opts });
     this.name = 'AnalysisError';
   }
 }
 
 export class BoundaryError extends CodegraphError {
-  constructor(message, opts = {}) {
+  constructor(message: string, opts: CodegraphErrorOpts = {}) {
     super(message, { code: 'BOUNDARY_VIOLATION', ...opts });
     this.name = 'BoundaryError';
   }