@optave/codegraph 3.3.0 → 3.4.0

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

@@ -1,16 +1,8 @@
-/**
- * Graph export serializers — pure data → formatted string transforms.
- *
- * Each function receives pre-loaded graph data and returns a formatted string
- * (or structured object for CSV). No DB access — all data must be pre-loaded.
- */
-
 import path from 'node:path';
 
 // ─── Escape Helpers ──────────────────────────────────────────────────
 
-/** Escape special XML characters. */
-export function escapeXml(s) {
+export function escapeXml(s: string | number): string {
   return String(s)
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')
@@ -19,8 +11,7 @@ export function escapeXml(s) {
     .replace(/'/g, '&apos;');
 }
 
-/** RFC 4180 CSV field escaping — quote fields containing commas, quotes, or newlines. */
-export function escapeCsv(s) {
+export function escapeCsv(s: string | number): string {
   const str = String(s);
   if (str.includes(',') || str.includes('"') || str.includes('\n') || str.includes('\r')) {
     return `"${str.replace(/"/g, '""')}"`;
@@ -28,13 +19,11 @@ export function escapeCsv(s) {
   return str;
 }
 
-/** Escape double quotes for Mermaid labels. */
-export function escapeLabel(label) {
+export function escapeLabel(label: string): string {
   return label.replace(/"/g, '#quot;');
 }
 
-/** Map node kind to Mermaid shape wrapper. */
-export function mermaidShape(kind, label) {
+export function mermaidShape(kind: string, label: string): string {
   const escaped = escapeLabel(label);
   switch (kind) {
     case 'function':
@@ -55,8 +44,7 @@ export function mermaidShape(kind, label) {
   }
 }
 
-/** Map node role to Mermaid style colors. */
-export const ROLE_STYLES = {
+export const ROLE_STYLES: Record<string, string> = {
   entry: 'fill:#e8f5e9,stroke:#4caf50',
   core: 'fill:#e3f2fd,stroke:#2196f3',
   utility: 'fill:#f5f5f5,stroke:#9e9e9e',
@@ -66,13 +54,18 @@ export const ROLE_STYLES = {
 
 // ─── DOT Serializer ──────────────────────────────────────────────────
 
-/**
- * Render file-level graph data as DOT (Graphviz) format.
- *
- * @param {{ dirs: Array<{ name: string, files: Array<{ path: string, basename: string }>, cohesion: number|null }>, edges: Array<{ source: string, target: string }>, totalEdges: number, limit?: number }} data
- * @returns {string}
- */
-export function renderFileLevelDOT(data) {
+interface FileLevelDOTData {
+  dirs: Array<{
+    name: string;
+    files: Array<{ path: string; basename: string }>;
+    cohesion: number | null;
+  }>;
+  edges: Array<{ source: string; target: string }>;
+  totalEdges: number;
+  limit?: number;
+}
+
+export function renderFileLevelDOT(data: FileLevelDOTData): string {
   const lines = [
     'digraph codegraph {',
     '  rankdir=LR;',
@@ -106,13 +99,18 @@ export function renderFileLevelDOT(data) {
   return lines.join('\n');
 }
 
-/**
- * Render function-level graph data as DOT (Graphviz) format.
- *
- * @param {{ edges: Array<{ source_name: string, source_file: string, target_name: string, target_file: string }>, totalEdges: number, limit?: number }} data
- * @returns {string}
- */
-export function renderFunctionLevelDOT(data) {
+interface FunctionLevelDOTData {
+  edges: Array<{
+    source_name: string;
+    source_file: string;
+    target_name: string;
+    target_file: string;
+  }>;
+  totalEdges: number;
+  limit?: number;
+}
+
+export function renderFunctionLevelDOT(data: FunctionLevelDOTData): string {
   const lines = [
     'digraph codegraph {',
     '  rankdir=LR;',
@@ -121,7 +119,7 @@ export function renderFunctionLevelDOT(data) {
     '',
   ];
 
-  const emittedNodes = new Set();
+  const emittedNodes = new Set<string>();
   for (const e of data.edges) {
     const sId = `${e.source_file}:${e.source_name}`.replace(/[^a-zA-Z0-9_]/g, '_');
     const tId = `${e.target_file}:${e.target_name}`.replace(/[^a-zA-Z0-9_]/g, '_');
@@ -145,20 +143,22 @@ export function renderFunctionLevelDOT(data) {
 
 // ─── Mermaid Serializer ──────────────────────────────────────────────
 
-/**
- * Render file-level graph data as Mermaid flowchart format.
- *
- * @param {{ direction: string, dirs: Array<{ name: string, files: string[] }>, edges: Array<{ source: string, target: string, edge_kind: string }>, totalEdges: number, limit?: number }} data
- * @returns {string}
- */
-export function renderFileLevelMermaid(data) {
+interface FileLevelMermaidData {
+  direction: string;
+  dirs: Array<{ name: string; files: string[] }>;
+  edges: Array<{ source: string; target: string; edge_kind: string }>;
+  totalEdges: number;
+  limit?: number;
+}
+
+export function renderFileLevelMermaid(data: FileLevelMermaidData): string {
   const lines = [`flowchart ${data.direction || 'LR'}`];
 
   let nodeCounter = 0;
-  const nodeIdMap = new Map();
-  function nodeId(key) {
+  const nodeIdMap = new Map<string, string>();
+  function nodeId(key: string): string {
     if (!nodeIdMap.has(key)) nodeIdMap.set(key, `n${nodeCounter++}`);
-    return nodeIdMap.get(key);
+    return nodeIdMap.get(key)!;
   }
 
   // Emit subgraphs
@@ -173,12 +173,12 @@ export function renderFileLevelMermaid(data) {
   }
 
   // Deduplicate edges per source-target pair, collecting all distinct kinds
-  const edgeMap = new Map();
+  const edgeMap = new Map<string, { source: string; target: string; labels: Set<string> }>();
   for (const { source, target, edge_kind } of data.edges) {
     const key = `${source}|${target}`;
     const label = edge_kind === 'imports-type' ? 'imports' : edge_kind;
     if (!edgeMap.has(key)) edgeMap.set(key, { source, target, labels: new Set() });
-    edgeMap.get(key).labels.add(label);
+    edgeMap.get(key)!.labels.add(label);
   }
 
   for (const { source, target, labels } of edgeMap.values()) {
@@ -191,25 +191,37 @@ export function renderFileLevelMermaid(data) {
   return lines.join('\n');
 }
 
-/**
- * Render function-level graph data as Mermaid flowchart format.
- *
- * @param {{ direction: string, edges: Array, roles: Map<string, string>, totalEdges: number, limit?: number }} data
- * @returns {string}
- */
-export function renderFunctionLevelMermaid(data) {
+interface FunctionLevelMermaidEdge {
+  source_file: string;
+  source_name: string;
+  source_kind: string;
+  target_file: string;
+  target_name: string;
+  target_kind: string;
+  edge_kind: string;
+}
+
+interface FunctionLevelMermaidData {
+  direction: string;
+  edges: FunctionLevelMermaidEdge[];
+  roles?: Map<string, string>;
+  totalEdges: number;
+  limit?: number;
+}
+
+export function renderFunctionLevelMermaid(data: FunctionLevelMermaidData): string {
   const lines = [`flowchart ${data.direction || 'LR'}`];
 
   let nodeCounter = 0;
-  const nodeIdMap = new Map();
-  function nodeId(key) {
+  const nodeIdMap = new Map<string, string>();
+  function nodeId(key: string): string {
     if (!nodeIdMap.has(key)) nodeIdMap.set(key, `n${nodeCounter++}`);
-    return nodeIdMap.get(key);
+    return nodeIdMap.get(key)!;
   }
 
   // Group nodes by file for subgraphs
-  const fileNodes = new Map();
-  const nodeKinds = new Map();
+  const fileNodes = new Map<string, Map<string, string>>();
+  const nodeKinds = new Map<string, string>();
   for (const e of data.edges) {
     const sKey = `${e.source_file}::${e.source_name}`;
     const tKey = `${e.target_file}::${e.target_name}`;
@@ -219,10 +231,10 @@ export function renderFunctionLevelMermaid(data) {
     nodeKinds.set(tKey, e.target_kind);
 
     if (!fileNodes.has(e.source_file)) fileNodes.set(e.source_file, new Map());
-    fileNodes.get(e.source_file).set(sKey, e.source_name);
+    fileNodes.get(e.source_file)!.set(sKey, e.source_name);
 
     if (!fileNodes.has(e.target_file)) fileNodes.set(e.target_file, new Map());
-    fileNodes.get(e.target_file).set(tKey, e.target_name);
+    fileNodes.get(e.target_file)!.set(tKey, e.target_name);
   }
 
   // Emit subgraphs grouped by file
@@ -231,7 +243,7 @@ export function renderFunctionLevelMermaid(data) {
     lines.push(`  subgraph ${sgId}["${escapeLabel(file)}"]`);
     for (const [key, name] of nodes) {
       const kind = nodeKinds.get(key);
-      lines.push(`    ${nodeId(key)}${mermaidShape(kind, name)}`);
+      lines.push(`    ${nodeId(key)}${mermaidShape(kind!, name)}`);
     }
     lines.push('  end');
   }
@@ -247,7 +259,7 @@ export function renderFunctionLevelMermaid(data) {
   }
 
   // Role styling
-  const roleStyles = [];
+  const roleStyles: string[] = [];
   for (const [key, nid] of nodeIdMap) {
     const role = data.roles?.get(key);
     if (role && ROLE_STYLES[role]) {
@@ -261,13 +273,11 @@ export function renderFunctionLevelMermaid(data) {
 
 // ─── GraphML Serializer ──────────────────────────────────────────────
 
-/**
- * Render file-level graph data as GraphML (XML) format.
- *
- * @param {{ edges: Array<{ source: string, target: string }> }} data
- * @returns {string}
- */
-export function renderFileLevelGraphML(data) {
+interface FileLevelGraphMLData {
+  edges: Array<{ source: string; target: string }>;
+}
+
+export function renderFileLevelGraphML(data: FileLevelGraphMLData): string {
   const lines = [
     '<?xml version="1.0" encoding="UTF-8"?>',
     '<graphml xmlns="http://graphml.graphstruct.net/graphml">',
@@ -277,13 +287,13 @@ export function renderFileLevelGraphML(data) {
     '  <graph id="codegraph" edgedefault="directed">',
   ];
 
-  const files = new Set();
+  const files = new Set<string>();
   for (const { source, target } of data.edges) {
     files.add(source);
     files.add(target);
   }
 
-  const fileIds = new Map();
+  const fileIds = new Map<string, string>();
   let nIdx = 0;
   for (const f of files) {
     const id = `n${nIdx++}`;
@@ -308,13 +318,28 @@ export function renderFileLevelGraphML(data) {
   return lines.join('\n');
 }
 
-/**
- * Render function-level graph data as GraphML (XML) format.
- *
- * @param {{ edges: Array }} data
- * @returns {string}
- */
-export function renderFunctionLevelGraphML(data) {
+interface FunctionLevelGraphMLEdge {
+  source_id: number;
+  source_name: string;
+  source_kind: string;
+  source_file: string;
+  source_line: number;
+  source_role: string | null;
+  target_id: number;
+  target_name: string;
+  target_kind: string;
+  target_file: string;
+  target_line: number;
+  target_role: string | null;
+  edge_kind: string;
+  confidence: number;
+}
+
+interface FunctionLevelGraphMLData {
+  edges: FunctionLevelGraphMLEdge[];
+}
+
+export function renderFunctionLevelGraphML(data: FunctionLevelGraphMLData): string {
   const lines = [
     '<?xml version="1.0" encoding="UTF-8"?>',
     '<graphml xmlns="http://graphml.graphstruct.net/graphml">',
@@ -328,8 +353,15 @@ export function renderFunctionLevelGraphML(data) {
     '  <graph id="codegraph" edgedefault="directed">',
   ];
 
-  const emittedNodes = new Set();
-  function emitNode(id, name, kind, file, line, role) {
+  const emittedNodes = new Set<number>();
+  function emitNode(
+    id: number,
+    name: string,
+    kind: string,
+    file: string,
+    line: number,
+    role: string | null,
+  ): void {
     if (emittedNodes.has(id)) return;
     emittedNodes.add(id);
     lines.push(`    <node id="n${id}">`);
@@ -372,14 +404,22 @@ export function renderFunctionLevelGraphML(data) {
 
 // ─── Neo4j CSV Serializer ────────────────────────────────────────────
 
-/**
- * Render file-level graph data as Neo4j bulk-import CSV.
- *
- * @param {{ edges: Array<{ source: string, target: string, edge_kind: string, confidence: number }> }} data
- * @returns {{ nodes: string, relationships: string }}
- */
-export function renderFileLevelNeo4jCSV(data) {
-  const files = new Map();
+interface FileLevelNeo4jEdge {
+  source: string;
+  target: string;
+  edge_kind: string;
+  confidence: number;
+}
+
+interface FileLevelNeo4jData {
+  edges: FileLevelNeo4jEdge[];
+}
+
+export function renderFileLevelNeo4jCSV(data: FileLevelNeo4jData): {
+  nodes: string;
+  relationships: string;
+} {
+  const files = new Map<string, number>();
   let idx = 0;
   for (const { source, target } of data.edges) {
     if (!files.has(source)) files.set(source, idx++);
@@ -400,16 +440,41 @@ export function renderFileLevelNeo4jCSV(data) {
   return { nodes: nodeLines.join('\n'), relationships: relLines.join('\n') };
 }
 
-/**
- * Render function-level graph data as Neo4j bulk-import CSV.
- *
- * @param {{ edges: Array }} data
- * @returns {{ nodes: string, relationships: string }}
- */
-export function renderFunctionLevelNeo4jCSV(data) {
-  const emitted = new Set();
+interface FunctionLevelNeo4jEdge {
+  source_id: number;
+  source_name: string;
+  source_kind: string;
+  source_file: string;
+  source_line: number;
+  source_role: string | null;
+  target_id: number;
+  target_name: string;
+  target_kind: string;
+  target_file: string;
+  target_line: number;
+  target_role: string | null;
+  edge_kind: string;
+  confidence: number;
+}
+
+interface FunctionLevelNeo4jData {
+  edges: FunctionLevelNeo4jEdge[];
+}
+
+export function renderFunctionLevelNeo4jCSV(data: FunctionLevelNeo4jData): {
+  nodes: string;
+  relationships: string;
+} {
+  const emitted = new Set<number>();
   const nodeLines = ['nodeId:ID,name,kind,file:string,line:int,role,:LABEL'];
-  function emitNode(id, name, kind, file, line, role) {
+  function emitNode(
+    id: number,
+    name: string,
+    kind: string,
+    file: string,
+    line: number,
+    role: string | null,
+  ): void {
     if (emitted.has(id)) return;
     emitted.add(id);
     const label = kind.charAt(0).toUpperCase() + kind.slice(1);

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

@@ -2,23 +2,44 @@ import { kindIcon } from '../domain/queries.js';
 import { flowData, listEntryPointsData } from '../features/flow.js';
 import { outputResult } from '../infrastructure/result-formatter.js';
 
-/**
- * CLI formatter — text or JSON output.
- */
-export function flow(name, dbPath, opts = {}) {
+interface FlowOpts {
+  list?: boolean;
+  noTests?: boolean;
+  limit?: number;
+  offset?: number;
+  depth?: number;
+  file?: string;
+  kind?: string;
+  json?: boolean;
+  ndjson?: boolean;
+  table?: boolean;
+  csv?: boolean;
+}
+
+export function flow(
+  name: string | undefined,
+  dbPath: string | undefined,
+  opts: FlowOpts = {},
+): void {
   if (opts.list) {
     const data = listEntryPointsData(dbPath, {
       noTests: opts.noTests,
       limit: opts.limit,
       offset: opts.offset,
-    });
+      // biome-ignore lint/suspicious/noExplicitAny: dynamic shape from listEntryPointsData
+    }) as any;
     if (outputResult(data, 'entries', opts)) return;
     if (data.count === 0) {
       console.log('No entry points found. Run "codegraph build" first.');
       return;
     }
     console.log(`\nEntry points (${data.count} total):\n`);
-    for (const [type, entries] of Object.entries(data.byType)) {
+    for (const [type, entries] of Object.entries(
+      data.byType as Record<
+        string,
+        Array<{ kind: string; name: string; file: string; line: number }>
+      >,
+    )) {
       console.log(`  ${type} (${entries.length}):`);
       for (const e of entries) {
         console.log(`    [${kindIcon(e.kind)}] ${e.name}  ${e.file}:${e.line}`);
@@ -28,7 +49,15 @@ export function flow(name, dbPath, opts = {}) {
     return;
   }
 
-  const data = flowData(name, dbPath, opts);
+  if (!name) {
+    console.log(
+      'Please provide a function or entry-point name. Use --list to see available entry points.',
+    );
+    return;
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic shape from flowData
+  const data = flowData(name, dbPath, opts) as any;
   if (outputResult(data, 'steps', opts)) return;
 
   if (!data.entry) {
@@ -55,7 +84,9 @@ export function flow(name, dbPath, opts = {}) {
   for (const step of data.steps) {
     console.log(`  depth ${step.depth}:`);
     for (const n of step.nodes) {
-      const isLeaf = data.leaves.some((l) => l.name === n.name && l.file === n.file);
+      const isLeaf = data.leaves.some(
+        (l: { name: string; file: string }) => l.name === n.name && l.file === n.file,
+      );
       const leafTag = isLeaf ? ' [leaf]' : '';
       console.log(`    [${kindIcon(n.kind)}] ${n.name}  ${n.file}:${n.line}${leafTag}`);
     }

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

@@ -1,11 +1,30 @@
 import { manifestoData } from '../features/manifesto.js';
 import { outputResult } from '../infrastructure/result-formatter.js';
 
-/**
- * CLI formatter — prints manifesto results and sets exitCode 1 on failure.
- */
-export function manifesto(customDbPath, opts = {}) {
-  const data = manifestoData(customDbPath, opts);
+interface ManifestoOpts {
+  json?: boolean;
+  ndjson?: boolean;
+  table?: boolean;
+  csv?: boolean;
+  config?: unknown;
+  noTests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+interface ManifestoViolationRow {
+  rule: string;
+  level: string;
+  value: number;
+  threshold: number;
+  name?: string;
+  file?: string;
+  line?: number;
+}
+
+export function manifesto(customDbPath: string | undefined, opts: ManifestoOpts = {}): void {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic shape from manifestoData
+  const data = manifestoData(customDbPath, opts as any) as any;
 
   if (outputResult(data, 'violations', opts)) {
     if (!data.passed) process.exitCode = 1;
@@ -39,8 +58,8 @@ export function manifesto(customDbPath, opts = {}) {
 
   // Violations detail
   if (data.violations.length > 0) {
-    const failViolations = data.violations.filter((v) => v.level === 'fail');
-    const warnViolations = data.violations.filter((v) => v.level === 'warn');
+    const failViolations = data.violations.filter((v: ManifestoViolationRow) => v.level === 'fail');
+    const warnViolations = data.violations.filter((v: ManifestoViolationRow) => v.level === 'warn');
 
     if (failViolations.length > 0) {
       console.log(`\n## Failures (${failViolations.length})\n`);

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

@@ -1,12 +1,49 @@
 import { ownersData } from '../features/owners.js';
 import { outputResult } from '../infrastructure/result-formatter.js';
 
-/**
- * CLI display function for the `owners` command.
- */
-export function owners(customDbPath, opts = {}) {
-  const data = ownersData(customDbPath, opts);
-  if (outputResult(data, null, opts)) return;
+interface OwnersOpts {
+  json?: boolean;
+  ndjson?: boolean;
+  table?: boolean;
+  csv?: boolean;
+  owner?: string;
+  boundary?: string;
+  file?: string | string[];
+  kind?: string;
+  noTests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+interface OwnerEntry {
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  owners: string[];
+}
+
+interface OwnersResult {
+  codeownersFile: string | null;
+  files: Array<{ file: string; owners: string[] }>;
+  symbols: OwnerEntry[];
+  boundaries: Array<{
+    from: OwnerEntry;
+    to: OwnerEntry;
+    edgeKind: string;
+  }>;
+  summary: {
+    coveragePercent: number;
+    ownedFiles: number;
+    totalFiles: number;
+    ownerCount: number;
+    byOwner: Array<{ owner: string; fileCount: number }>;
+  };
+}
+
+export function owners(customDbPath: string | undefined, opts: OwnersOpts = {}): void {
+  const data = ownersData(customDbPath, opts as any) as OwnersResult;
+  if (outputResult(data as unknown as Record<string, unknown>, null, opts)) return;
 
   if (!data.codeownersFile) {
     console.log('No CODEOWNERS file found.');

package/src/presentation/queries-cli/{exports.js → exports.ts}

@@ -1,7 +1,48 @@
 import { exportsData, kindIcon } from '../../domain/queries.js';
 import { outputResult } from '../../infrastructure/result-formatter.js';
 
-function printExportHeader(data, opts) {
+interface ExportConsumer {
+  name: string;
+  file: string;
+  line: number;
+}
+
+interface ExportSymbol {
+  kind: string;
+  name: string;
+  line: number;
+  role?: string;
+  signature?: { params?: string };
+  consumers: ExportConsumer[];
+}
+
+interface ReexportedSymbol extends ExportSymbol {
+  originFile: string;
+}
+
+interface ExportsDataResult {
+  file: string;
+  totalExported: number;
+  totalInternal: number;
+  totalUnused: number;
+  totalReexported?: number;
+  totalReexportedUnused?: number;
+  results: ExportSymbol[];
+  reexportedSymbols: ReexportedSymbol[];
+  reexports: { file: string }[];
+}
+
+interface ExportsOpts {
+  json?: boolean;
+  ndjson?: boolean;
+  csv?: boolean;
+  table?: boolean;
+  noTests?: boolean;
+  unused?: boolean;
+  [key: string]: unknown;
+}
+
+function printExportHeader(data: ExportsDataResult, opts: ExportsOpts): void {
   if (opts.unused) {
     console.log(
       `\n# ${data.file} — ${data.totalUnused} unused export${data.totalUnused !== 1 ? 's' : ''} (of ${data.totalExported} exported)\n`,
@@ -14,7 +55,7 @@ function printExportHeader(data, opts) {
   }
 }
 
-function printExportSymbols(results) {
+function printExportSymbols(results: ExportSymbol[]): void {
   for (const sym of results) {
     const icon = kindIcon(sym.kind);
     const sig = sym.signature?.params ? `(${sym.signature.params})` : '';
@@ -30,12 +71,12 @@ function printExportSymbols(results) {
   }
 }
 
-function printReexportedSymbols(reexportedSymbols) {
+function printReexportedSymbols(reexportedSymbols: ReexportedSymbol[]): void {
   // Group by origin file
-  const byOrigin = new Map();
+  const byOrigin = new Map<string, ReexportedSymbol[]>();
   for (const sym of reexportedSymbols) {
     if (!byOrigin.has(sym.originFile)) byOrigin.set(sym.originFile, []);
-    byOrigin.get(sym.originFile).push(sym);
+    byOrigin.get(sym.originFile)!.push(sym);
   }
 
   for (const [originFile, syms] of byOrigin) {
@@ -56,9 +97,9 @@ function printReexportedSymbols(reexportedSymbols) {
   }
 }
 
-export function fileExports(file, customDbPath, opts = {}) {
-  const data = exportsData(file, customDbPath, opts);
-  if (outputResult(data, 'results', opts)) return;
+export function fileExports(file: string, customDbPath: string, opts: ExportsOpts = {}): void {
+  const data = exportsData(file, customDbPath, opts) as ExportsDataResult;
+  if (outputResult(data as unknown as Record<string, unknown>, 'results', opts)) return;
 
   const hasReexported = data.reexportedSymbols && data.reexportedSymbols.length > 0;