optave-codegraph 3.13.0

package/src/presentation/result-formatter.ts

@@ -0,0 +1,161 @@
+import { loadConfig } from '../infrastructure/config.js';
+import type { PaginationMeta } from '../shared/paginate.js';
+import { formatTable, truncEnd } from './table.js';
+
+/**
+ * Print data as newline-delimited JSON (NDJSON).
+ *
+ * Emits a `_meta` line with pagination info (if present), then one JSON
+ * line per item in the named array field.
+ */
+export function printNdjson(
+  data: Record<string, unknown> & { _pagination?: PaginationMeta },
+  field: string,
+): void {
+  if (data._pagination) console.log(JSON.stringify({ _meta: data._pagination }));
+  const items = data[field];
+  if (Array.isArray(items)) {
+    // console.log is intentional: NDJSON serialisation must go to stdout, not the structured logger
+    for (const item of items) console.log(JSON.stringify(item));
+  }
+}
+
+function flattenObject(obj: Record<string, unknown>, prefix = ''): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (
+      value !== null &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      Object.getPrototypeOf(value) === Object.prototype
+    ) {
+      Object.assign(result, flattenObject(value as Record<string, unknown>, fullKey));
+    } else if (Array.isArray(value)) {
+      result[fullKey] = JSON.stringify(value);
+    } else {
+      result[fullKey] = value;
+    }
+  }
+  return result;
+}
+
+function prepareFlatItems(
+  data: Record<string, unknown>,
+  field: string | null,
+): { flatItems: Record<string, unknown>[]; columns: string[] } | null {
+  const items = field ? (data[field] as unknown) : data;
+  if (!Array.isArray(items)) return null;
+
+  const flatItems = items.map((item: unknown) =>
+    typeof item === 'object' && item !== null && !Array.isArray(item)
+      ? flattenObject(item as Record<string, unknown>)
+      : { value: item },
+  );
+  const columns = (() => {
+    const keys = new Set<string>();
+    for (const item of flatItems) for (const key of Object.keys(item)) keys.add(key);
+    return [...keys];
+  })();
+  if (columns.length === 0) columns.push('value');
+
+  return { flatItems, columns };
+}
+
+function escapeCsv(val: unknown): string {
+  const str = val == null ? '' : String(val);
+  if (str.includes(',') || str.includes('"') || str.includes('\n') || str.includes('\r')) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+function printCsv(data: Record<string, unknown>, field: string | null): boolean {
+  const prepared = prepareFlatItems(data, field);
+  if (!prepared) return false;
+  const { flatItems, columns } = prepared;
+
+  console.log(columns.map(escapeCsv).join(','));
+  for (const row of flatItems) {
+    console.log(columns.map((col) => escapeCsv(row[col])).join(','));
+  }
+  return true;
+}
+
+const MAX_COL_WIDTH = 40;
+
+interface DisplayOpts {
+  maxColWidth?: number;
+}
+
+function printAutoTable(
+  data: Record<string, unknown>,
+  field: string | null,
+  displayOpts: DisplayOpts = {},
+): boolean {
+  const prepared = prepareFlatItems(data, field);
+  if (!prepared) return false;
+  const { flatItems, columns } = prepared;
+  const colWidth = displayOpts.maxColWidth ?? MAX_COL_WIDTH;
+
+  const colDefs = columns.map((col) => {
+    const maxLen = flatItems.reduce(
+      (max, item) => Math.max(max, String(item[col] ?? '').length),
+      col.length,
+    );
+    const isNumeric =
+      flatItems.length > 0 &&
+      flatItems.every((item) => {
+        const v = item[col];
+        return v == null || v === '' || (typeof v !== 'boolean' && Number.isFinite(Number(v)));
+      });
+    return {
+      header: col,
+      width: Math.min(maxLen, colWidth),
+      align: isNumeric ? ('right' as const) : ('left' as const),
+    };
+  });
+
+  const rows = flatItems.map((item) =>
+    columns.map((col) => truncEnd(String(item[col] ?? ''), colWidth)),
+  );
+
+  console.log(formatTable({ columns: colDefs, rows }));
+  return true;
+}
+
+export interface OutputOpts {
+  json?: boolean;
+  ndjson?: boolean;
+  table?: boolean;
+  csv?: boolean;
+  display?: DisplayOpts;
+}
+
+export function outputResult(
+  data: Record<string, any>,
+  field: string | null,
+  opts: OutputOpts,
+): boolean {
+  if (opts.ndjson) {
+    if (field === null) {
+      // No field key — emit the whole object as a single NDJSON line
+      console.log(JSON.stringify(data));
+    } else {
+      printNdjson(data, field);
+    }
+    return true;
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return true;
+  }
+  if (opts.csv) {
+    return printCsv(data, field) !== false;
+  }
+  if (opts.table) {
+    const displayOpts = opts.display ?? (loadConfig() as { display: DisplayOpts }).display;
+    return printAutoTable(data, field, displayOpts) !== false;
+  }
+  return false;
+}

package/src/presentation/sequence-renderer.ts

@@ -0,0 +1,46 @@
+interface Participant {
+  id: string;
+  label: string;
+}
+
+interface SequenceMessage {
+  from: string;
+  to: string;
+  type: string;
+  label: string;
+}
+
+interface SequenceRenderData {
+  participants: Participant[];
+  messages: SequenceMessage[];
+  truncated: boolean;
+  depth: number;
+}
+
+function escapeMermaid(str: string): string {
+  return str
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/:/g, '#colon;')
+    .replace(/"/g, '#quot;');
+}
+
+export function sequenceToMermaid(seqResult: SequenceRenderData): string {
+  const lines = ['sequenceDiagram'];
+
+  for (const p of seqResult.participants) {
+    lines.push(`    participant ${p.id} as ${escapeMermaid(p.label)}`);
+  }
+
+  for (const msg of seqResult.messages) {
+    const arrow = msg.type === 'return' ? '-->>' : '->>';
+    lines.push(`    ${msg.from}${arrow}${msg.to}: ${escapeMermaid(msg.label)}`);
+  }
+
+  if (seqResult.truncated && seqResult.participants.length > 0) {
+    const firstParticipant = seqResult.participants[0]!;
+    lines.push(`    note right of ${firstParticipant.id}: Truncated at depth ${seqResult.depth}`);
+  }
+
+  return lines.join('\n');
+}

package/src/presentation/sequence.ts

@@ -0,0 +1,43 @@
+import { kindIcon } from '../domain/queries.js';
+import { sequenceData, sequenceToMermaid } from '../features/sequence.js';
+import { outputResult } from '../infrastructure/result-formatter.js';
+
+interface SequenceOpts {
+  json?: boolean;
+  ndjson?: boolean;
+  table?: boolean;
+  csv?: boolean;
+  depth?: number;
+  noTests?: boolean;
+  file?: string;
+  kind?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export function sequence(name: string, dbPath: string | undefined, opts: SequenceOpts = {}): void {
+  const data = sequenceData(name, dbPath, opts) as any;
+
+  if (outputResult(data, 'messages', opts)) return;
+
+  // Default: mermaid format
+  if (!data.entry) {
+    console.log(`No matching function found for "${name}".`);
+    return;
+  }
+
+  const e = data.entry;
+  console.log(`\nSequence from: [${kindIcon(e.kind)}] ${e.name}  ${e.file}:${e.line}`);
+  console.log(`Participants: ${data.participants.length}  Messages: ${data.totalMessages}`);
+  if (data.truncated) {
+    console.log(`  (truncated at depth ${data.depth})`);
+  }
+  console.log();
+
+  if (data.messages.length === 0) {
+    console.log('  (leaf node — no callees)');
+    return;
+  }
+
+  console.log(sequenceToMermaid(data));
+}

package/src/presentation/structure.ts

@@ -0,0 +1,109 @@
+import path from 'node:path';
+import { hotspotsData, moduleBoundariesData, structureData } from '../features/structure.js';
+
+export { hotspotsData, moduleBoundariesData, structureData };
+
+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`];
+  for (const d of data.directories) {
+    const cohStr = d.cohesion !== null ? ` cohesion=${d.cohesion.toFixed(2)}` : '';
+    const depth = d.directory.split('/').length - 1;
+    const indent = '  '.repeat(depth);
+    lines.push(
+      `${indent}${d.directory}/  (${d.fileCount} files, ${d.symbolCount} symbols, <-${d.fanIn} ->${d.fanOut}${cohStr})`,
+    );
+    for (const f of d.files) {
+      lines.push(
+        `${indent}  ${path.basename(f.file)}  ${f.lineCount}L ${f.symbolCount}sym <-${f.fanIn} ->${f.fanOut}`,
+      );
+    }
+  }
+  if (data.warning) {
+    lines.push('');
+    lines.push(`\u26A0 ${data.warning}`);
+  }
+  return lines.join('\n');
+}
+
+interface HotspotsResult {
+  metric: string;
+  level: string;
+  limit: number;
+  items: any[];
+}
+
+export function formatHotspots(data: HotspotsResult): string {
+  if (data.items.length === 0) return 'No hotspots found. Run "codegraph build" first.';
+
+  const lines = [`\nHotspots by ${data.metric} (${data.level}-level, top ${data.limit}):\n`];
+  let rank = 1;
+  for (const h of data.items) {
+    const extra =
+      h.kind === 'directory'
+        ? `${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})`,
+    );
+  }
+  return lines.join('\n');
+}
+
+interface ModuleBoundaryEntry {
+  directory: string;
+  cohesion: number | null;
+  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`];
+  for (const m of data.modules) {
+    lines.push(
+      `  ${m.directory}/  cohesion=${m.cohesion !== null ? m.cohesion.toFixed(2) : 'n/a'}  (${m.fileCount} files, ${m.symbolCount} symbols)`,
+    );
+    lines.push(`    Incoming: ${m.fanIn} edges    Outgoing: ${m.fanOut} edges`);
+    if (m.files.length > 0) {
+      lines.push(
+        `    Files: ${m.files.slice(0, 5).join(', ')}${m.files.length > 5 ? ` ... +${m.files.length - 5}` : ''}`,
+      );
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/src/presentation/table.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared table formatting utilities for CLI output.
+ *
+ * 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.
+ */
+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)))
+    .join(' ');
+  const separator = columns.map((c) => '\u2500'.repeat(c.width)).join(' ');
+  const lines = [`${prefix}${header}`, `${prefix}${separator}`];
+  for (const row of rows) {
+    const cells = columns.map((c, i) => {
+      const val = row[i] ?? '';
+      return c.align === 'right' ? val.padStart(c.width) : val.padEnd(c.width);
+    });
+    lines.push(`${prefix}${cells.join(' ')}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Truncate a string from the end, appending '\u2026' if truncated.
+ */
+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.ts

@@ -0,0 +1,84 @@
+import { triageData } from '../features/triage.js';
+import { outputResult } from '../infrastructure/result-formatter.js';
+
+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 {
+  const data = triageData(customDbPath, opts as any) as {
+    items: TriageItem[];
+    summary: TriageSummary;
+  };
+
+  if (outputResult(data as unknown as Record<string, unknown>, 'items', opts)) return;
+
+  if (data.items.length === 0) {
+    if (data.summary.total === 0) {
+      console.log('\nNo symbols found. Run "codegraph build" first.\n');
+    } else {
+      console.log('\nNo symbols match the given filters.\n');
+    }
+    return;
+  }
+
+  console.log('\n# Risk Audit Queue\n');
+
+  console.log(
+    `  ${'Symbol'.padEnd(35)} ${'File'.padEnd(28)} ${'Role'.padEnd(8)} ${'Score'.padStart(6)} ${'Fan-In'.padStart(7)} ${'Cog'.padStart(4)} ${'Churn'.padStart(6)} ${'MI'.padStart(5)}`,
+  );
+  console.log(
+    `  ${'─'.repeat(35)} ${'─'.repeat(28)} ${'─'.repeat(8)} ${'─'.repeat(6)} ${'─'.repeat(7)} ${'─'.repeat(4)} ${'─'.repeat(6)} ${'─'.repeat(5)}`,
+  );
+
+  for (const it of data.items) {
+    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);
+    const cog = String(it.cognitive).padStart(4);
+    const churn = String(it.churn).padStart(6);
+    const mi = it.maintainabilityIndex > 0 ? String(it.maintainabilityIndex).padStart(5) : '    -';
+    console.log(
+      `  ${name.padEnd(35)} ${file.padEnd(28)} ${role} ${score} ${fanIn} ${cog} ${churn} ${mi}`,
+    );
+  }
+
+  const s = data.summary;
+  console.log(
+    `\n  ${s.analyzed} symbols scored (of ${s.total} total) | avg: ${s.avgScore.toFixed(2)} | max: ${s.maxScore.toFixed(2)} | sort: ${opts.sort || 'risk'}`,
+  );
+  console.log();
+}