@optave/codegraph 3.1.0 → 3.1.2

package/src/structure.js

@@ -1,9 +1,9 @@
 import path from 'node:path';
 import { normalizePath } from './constants.js';
-import { openReadonlyOrFail } from './db.js';
+import { getNodeId, openReadonlyOrFail, testFilterSQL } from './db.js';
+import { isTestFile } from './infrastructure/test-filter.js';
 import { debug } from './logger.js';
 import { paginateResult } from './paginate.js';
-import { isTestFile } from './queries.js';
 
 // ─── Build-time: insert directory nodes, contains edges, and metrics ────
 
@@ -21,9 +21,12 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
   const insertNode = db.prepare(
     'INSERT OR IGNORE INTO nodes (name, kind, file, line, end_line) VALUES (?, ?, ?, ?, ?)',
   );
-  const getNodeId = db.prepare(
-    'SELECT id FROM nodes WHERE name = ? AND kind = ? AND file = ? AND line = ?',
-  );
+  const getNodeIdStmt = {
+    get: (name, kind, file, line) => {
+      const id = getNodeId(db, name, kind, file, line);
+      return id != null ? { id } : undefined;
+    },
+  };
   const insertEdge = db.prepare(
     'INSERT INTO edges (source_id, target_id, kind, confidence, dynamic) VALUES (?, ?, ?, ?, ?)',
   );
@@ -56,12 +59,12 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
       }
       // Delete metrics for changed files
       for (const f of changedFiles) {
-        const fileRow = getNodeId.get(f, 'file', f, 0);
+        const fileRow = getNodeIdStmt.get(f, 'file', f, 0);
         if (fileRow) deleteMetricForNode.run(fileRow.id);
       }
       // Delete metrics for affected directories
       for (const dir of affectedDirs) {
-        const dirRow = getNodeId.get(dir, 'directory', dir, 0);
+        const dirRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
         if (dirRow) deleteMetricForNode.run(dirRow.id);
       }
     })();
@@ -126,8 +129,8 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
       if (!dir || dir === '.') continue;
       // On incremental, skip dirs whose contains edges are intact
       if (affectedDirs && !affectedDirs.has(dir)) continue;
-      const dirRow = getNodeId.get(dir, 'directory', dir, 0);
-      const fileRow = getNodeId.get(relPath, 'file', relPath, 0);
+      const dirRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
+      const fileRow = getNodeIdStmt.get(relPath, 'file', relPath, 0);
       if (dirRow && fileRow) {
         insertEdge.run(dirRow.id, fileRow.id, 'contains', 1.0, 0);
       }
@@ -138,8 +141,8 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
       if (!parent || parent === '.' || parent === dir) continue;
       // On incremental, skip parent dirs whose contains edges are intact
       if (affectedDirs && !affectedDirs.has(parent)) continue;
-      const parentRow = getNodeId.get(parent, 'directory', parent, 0);
-      const childRow = getNodeId.get(dir, 'directory', dir, 0);
+      const parentRow = getNodeIdStmt.get(parent, 'directory', parent, 0);
+      const childRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
       if (parentRow && childRow) {
         insertEdge.run(parentRow.id, childRow.id, 'contains', 1.0, 0);
       }
@@ -169,7 +172,7 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
 
   const computeFileMetrics = db.transaction(() => {
     for (const [relPath, symbols] of fileSymbols) {
-      const fileRow = getNodeId.get(relPath, 'file', relPath, 0);
+      const fileRow = getNodeIdStmt.get(relPath, 'file', relPath, 0);
       if (!fileRow) continue;
 
       const lineCount = lineCountMap.get(relPath) || 0;
@@ -263,7 +266,7 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
 
   const computeDirMetrics = db.transaction(() => {
     for (const [dir, files] of dirFiles) {
-      const dirRow = getNodeId.get(dir, 'directory', dir, 0);
+      const dirRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
       if (!dirRow) continue;
 
       const fileCount = files.length;
@@ -413,115 +416,117 @@ export function classifyNodeRoles(db) {
  */
 export function structureData(customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
-  const rawDir = opts.directory || null;
-  const filterDir = rawDir && normalizePath(rawDir) !== '.' ? rawDir : null;
-  const maxDepth = opts.depth || null;
-  const sortBy = opts.sort || 'files';
-  const noTests = opts.noTests || false;
-  const full = opts.full || false;
-  const fileLimit = opts.fileLimit || 25;
-
-  // Get all directory nodes with their metrics
-  let dirs = db
-    .prepare(`
-      SELECT n.id, n.name, n.file, nm.symbol_count, nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
-      FROM nodes n
-      LEFT JOIN node_metrics nm ON n.id = nm.node_id
-      WHERE n.kind = 'directory'
-    `)
-    .all();
-
-  if (filterDir) {
-    const norm = normalizePath(filterDir);
-    dirs = dirs.filter((d) => d.name === norm || d.name.startsWith(`${norm}/`));
-  }
-
-  if (maxDepth) {
-    const baseDepth = filterDir ? normalizePath(filterDir).split('/').length : 0;
-    dirs = dirs.filter((d) => {
-      const depth = d.name.split('/').length - baseDepth;
-      return depth <= maxDepth;
-    });
-  }
-
-  // Sort
-  const sortFn = getSortFn(sortBy);
-  dirs.sort(sortFn);
-
-  // Get file metrics for each directory
-  const result = dirs.map((d) => {
-    let files = db
+  try {
+    const rawDir = opts.directory || null;
+    const filterDir = rawDir && normalizePath(rawDir) !== '.' ? rawDir : null;
+    const maxDepth = opts.depth || null;
+    const sortBy = opts.sort || 'files';
+    const noTests = opts.noTests || false;
+    const full = opts.full || false;
+    const fileLimit = opts.fileLimit || 25;
+
+    // Get all directory nodes with their metrics
+    let dirs = db
       .prepare(`
-        SELECT n.name, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count, nm.fan_in, nm.fan_out
-        FROM edges e
-        JOIN nodes n ON e.target_id = n.id
+        SELECT n.id, n.name, n.file, nm.symbol_count, nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
+        FROM nodes n
         LEFT JOIN node_metrics nm ON n.id = nm.node_id
-        WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
+        WHERE n.kind = 'directory'
       `)
-      .all(d.id);
-    if (noTests) files = files.filter((f) => !isTestFile(f.name));
+      .all();
 
-    const subdirs = db
-      .prepare(`
-        SELECT n.name
-        FROM edges e
-        JOIN nodes n ON e.target_id = n.id
-        WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'directory'
-      `)
-      .all(d.id);
-
-    const fileCount = noTests ? files.length : d.file_count || 0;
-    return {
-      directory: d.name,
-      fileCount,
-      symbolCount: d.symbol_count || 0,
-      fanIn: d.fan_in || 0,
-      fanOut: d.fan_out || 0,
-      cohesion: d.cohesion,
-      density: fileCount > 0 ? (d.symbol_count || 0) / fileCount : 0,
-      files: files.map((f) => ({
-        file: f.name,
-        lineCount: f.line_count || 0,
-        symbolCount: f.symbol_count || 0,
-        importCount: f.import_count || 0,
-        exportCount: f.export_count || 0,
-        fanIn: f.fan_in || 0,
-        fanOut: f.fan_out || 0,
-      })),
-      subdirectories: subdirs.map((s) => s.name),
-    };
-  });
+    if (filterDir) {
+      const norm = normalizePath(filterDir);
+      dirs = dirs.filter((d) => d.name === norm || d.name.startsWith(`${norm}/`));
+    }
 
-  db.close();
-
-  // Apply global file limit unless full mode
-  if (!full) {
-    const totalFiles = result.reduce((sum, d) => sum + d.files.length, 0);
-    if (totalFiles > fileLimit) {
-      let shown = 0;
-      for (const d of result) {
-        const remaining = fileLimit - shown;
-        if (remaining <= 0) {
-          d.files = [];
-        } else if (d.files.length > remaining) {
-          d.files = d.files.slice(0, remaining);
-          shown = fileLimit;
-        } else {
-          shown += d.files.length;
-        }
-      }
-      const suppressed = totalFiles - fileLimit;
+    if (maxDepth) {
+      const baseDepth = filterDir ? normalizePath(filterDir).split('/').length : 0;
+      dirs = dirs.filter((d) => {
+        const depth = d.name.split('/').length - baseDepth;
+        return depth <= maxDepth;
+      });
+    }
+
+    // Sort
+    const sortFn = getSortFn(sortBy);
+    dirs.sort(sortFn);
+
+    // Get file metrics for each directory
+    const result = dirs.map((d) => {
+      let files = db
+        .prepare(`
+          SELECT n.name, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count, nm.fan_in, nm.fan_out
+          FROM edges e
+          JOIN nodes n ON e.target_id = n.id
+          LEFT JOIN node_metrics nm ON n.id = nm.node_id
+          WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
+        `)
+        .all(d.id);
+      if (noTests) files = files.filter((f) => !isTestFile(f.name));
+
+      const subdirs = db
+        .prepare(`
+          SELECT n.name
+          FROM edges e
+          JOIN nodes n ON e.target_id = n.id
+          WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'directory'
+        `)
+        .all(d.id);
+
+      const fileCount = noTests ? files.length : d.file_count || 0;
       return {
-        directories: result,
-        count: result.length,
-        suppressed,
-        warning: `${suppressed} files omitted (showing ${fileLimit}/${totalFiles}). Use --full to show all files, or narrow with --directory.`,
+        directory: d.name,
+        fileCount,
+        symbolCount: d.symbol_count || 0,
+        fanIn: d.fan_in || 0,
+        fanOut: d.fan_out || 0,
+        cohesion: d.cohesion,
+        density: fileCount > 0 ? (d.symbol_count || 0) / fileCount : 0,
+        files: files.map((f) => ({
+          file: f.name,
+          lineCount: f.line_count || 0,
+          symbolCount: f.symbol_count || 0,
+          importCount: f.import_count || 0,
+          exportCount: f.export_count || 0,
+          fanIn: f.fan_in || 0,
+          fanOut: f.fan_out || 0,
+        })),
+        subdirectories: subdirs.map((s) => s.name),
       };
+    });
+
+    // Apply global file limit unless full mode
+    if (!full) {
+      const totalFiles = result.reduce((sum, d) => sum + d.files.length, 0);
+      if (totalFiles > fileLimit) {
+        let shown = 0;
+        for (const d of result) {
+          const remaining = fileLimit - shown;
+          if (remaining <= 0) {
+            d.files = [];
+          } else if (d.files.length > remaining) {
+            d.files = d.files.slice(0, remaining);
+            shown = fileLimit;
+          } else {
+            shown += d.files.length;
+          }
+        }
+        const suppressed = totalFiles - fileLimit;
+        return {
+          directories: result,
+          count: result.length,
+          suppressed,
+          warning: `${suppressed} files omitted (showing ${fileLimit}/${totalFiles}). Use --full to show all files, or narrow with --directory.`,
+        };
+      }
     }
-  }
 
-  const base = { directories: result, count: result.length };
-  return paginateResult(base, 'directories', { limit: opts.limit, offset: opts.offset });
+    const base = { directories: result, count: result.length };
+    return paginateResult(base, 'directories', { limit: opts.limit, offset: opts.offset });
+  } finally {
+    db.close();
+  }
 }
 
 /**
@@ -529,71 +534,67 @@ export function structureData(customDbPath, opts = {}) {
  */
 export function hotspotsData(customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
-  const metric = opts.metric || 'fan-in';
-  const level = opts.level || 'file';
-  const limit = opts.limit || 10;
-  const noTests = opts.noTests || false;
-
-  const kind = level === 'directory' ? 'directory' : 'file';
-
-  const testFilter =
-    noTests && kind === 'file'
-      ? `AND n.name NOT LIKE '%.test.%'
-         AND n.name NOT LIKE '%.spec.%'
-         AND n.name NOT LIKE '%__test__%'
-         AND n.name NOT LIKE '%__tests__%'
-         AND n.name NOT LIKE '%.stories.%'`
-      : '';
-
-  const HOTSPOT_QUERIES = {
-    'fan-in': db.prepare(`
-      SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
-             nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
-      FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
-      WHERE n.kind = ? ${testFilter} ORDER BY nm.fan_in DESC NULLS LAST LIMIT ?`),
-    'fan-out': db.prepare(`
-      SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
-             nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
-      FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
-      WHERE n.kind = ? ${testFilter} ORDER BY nm.fan_out DESC NULLS LAST LIMIT ?`),
-    density: db.prepare(`
-      SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
-             nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
-      FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
-      WHERE n.kind = ? ${testFilter} ORDER BY nm.symbol_count DESC NULLS LAST LIMIT ?`),
-    coupling: db.prepare(`
-      SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
-             nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
-      FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
-      WHERE n.kind = ? ${testFilter} ORDER BY (COALESCE(nm.fan_in, 0) + COALESCE(nm.fan_out, 0)) DESC NULLS LAST LIMIT ?`),
-  };
+  try {
+    const metric = opts.metric || 'fan-in';
+    const level = opts.level || 'file';
+    const limit = opts.limit || 10;
+    const noTests = opts.noTests || false;
+
+    const kind = level === 'directory' ? 'directory' : 'file';
+
+    const testFilter = testFilterSQL('n.name', noTests && kind === 'file');
+
+    const HOTSPOT_QUERIES = {
+      'fan-in': db.prepare(`
+        SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
+               nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
+        FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
+        WHERE n.kind = ? ${testFilter} ORDER BY nm.fan_in DESC NULLS LAST LIMIT ?`),
+      'fan-out': db.prepare(`
+        SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
+               nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
+        FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
+        WHERE n.kind = ? ${testFilter} ORDER BY nm.fan_out DESC NULLS LAST LIMIT ?`),
+      density: db.prepare(`
+        SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
+               nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
+        FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
+        WHERE n.kind = ? ${testFilter} ORDER BY nm.symbol_count DESC NULLS LAST LIMIT ?`),
+      coupling: db.prepare(`
+        SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
+               nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
+        FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
+        WHERE n.kind = ? ${testFilter} ORDER BY (COALESCE(nm.fan_in, 0) + COALESCE(nm.fan_out, 0)) DESC NULLS LAST LIMIT ?`),
+    };
 
-  const stmt = HOTSPOT_QUERIES[metric] || HOTSPOT_QUERIES['fan-in'];
-  const rows = stmt.all(kind, limit);
-
-  const hotspots = rows.map((r) => ({
-    name: r.name,
-    kind: r.kind,
-    lineCount: r.line_count,
-    symbolCount: r.symbol_count,
-    importCount: r.import_count,
-    exportCount: r.export_count,
-    fanIn: r.fan_in,
-    fanOut: r.fan_out,
-    cohesion: r.cohesion,
-    fileCount: r.file_count,
-    density:
-      r.file_count > 0
-        ? (r.symbol_count || 0) / r.file_count
-        : r.line_count > 0
-          ? (r.symbol_count || 0) / r.line_count
-          : 0,
-    coupling: (r.fan_in || 0) + (r.fan_out || 0),
-  }));
-
-  db.close();
-  const base = { metric, level, limit, hotspots };
-  return paginateResult(base, 'hotspots', { limit: opts.limit, offset: opts.offset });
+    const stmt = HOTSPOT_QUERIES[metric] || HOTSPOT_QUERIES['fan-in'];
+    const rows = stmt.all(kind, limit);
+
+    const hotspots = rows.map((r) => ({
+      name: r.name,
+      kind: r.kind,
+      lineCount: r.line_count,
+      symbolCount: r.symbol_count,
+      importCount: r.import_count,
+      exportCount: r.export_count,
+      fanIn: r.fan_in,
+      fanOut: r.fan_out,
+      cohesion: r.cohesion,
+      fileCount: r.file_count,
+      density:
+        r.file_count > 0
+          ? (r.symbol_count || 0) / r.file_count
+          : r.line_count > 0
+            ? (r.symbol_count || 0) / r.line_count
+            : 0,
+      coupling: (r.fan_in || 0) + (r.fan_out || 0),
+    }));
+
+    const base = { metric, level, limit, hotspots };
+    return paginateResult(base, 'hotspots', { limit: opts.limit, offset: opts.offset });
+  } finally {
+    db.close();
+  }
 }
 
 /**
@@ -601,104 +602,45 @@ export function hotspotsData(customDbPath, opts = {}) {
  */
 export function moduleBoundariesData(customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
-  const threshold = opts.threshold || 0.3;
-
-  const dirs = db
-    .prepare(`
-      SELECT n.id, n.name, nm.symbol_count, nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
-      FROM nodes n
-      JOIN node_metrics nm ON n.id = nm.node_id
-      WHERE n.kind = 'directory' AND nm.cohesion IS NOT NULL AND nm.cohesion >= ?
-      ORDER BY nm.cohesion DESC
-    `)
-    .all(threshold);
+  try {
+    const threshold = opts.threshold || 0.3;
 
-  const modules = dirs.map((d) => {
-    // Get files inside this directory
-    const files = db
+    const dirs = db
       .prepare(`
-        SELECT n.name FROM edges e
-        JOIN nodes n ON e.target_id = n.id
-        WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
+        SELECT n.id, n.name, nm.symbol_count, nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
+        FROM nodes n
+        JOIN node_metrics nm ON n.id = nm.node_id
+        WHERE n.kind = 'directory' AND nm.cohesion IS NOT NULL AND nm.cohesion >= ?
+        ORDER BY nm.cohesion DESC
       `)
-      .all(d.id)
-      .map((f) => f.name);
-
-    return {
-      directory: d.name,
-      cohesion: d.cohesion,
-      fileCount: d.file_count || 0,
-      symbolCount: d.symbol_count || 0,
-      fanIn: d.fan_in || 0,
-      fanOut: d.fan_out || 0,
-      files,
-    };
-  });
-
-  db.close();
-  return { threshold, modules, count: modules.length };
-}
+      .all(threshold);
+
+    const modules = dirs.map((d) => {
+      // Get files inside this directory
+      const files = db
+        .prepare(`
+          SELECT n.name FROM edges e
+          JOIN nodes n ON e.target_id = n.id
+          WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
+        `)
+        .all(d.id)
+        .map((f) => f.name);
 
-// ─── Formatters ───────────────────────────────────────────────────────
-
-export function formatStructure(data) {
-  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(`⚠ ${data.warning}`);
-  }
-  return lines.join('\n');
-}
-
-export function formatHotspots(data) {
-  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`];
-  let rank = 1;
-  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.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');
-}
-
-export function formatModuleBoundaries(data) {
-  if (data.count === 0) return `No modules found with cohesion >= ${data.threshold}.`;
+      return {
+        directory: d.name,
+        cohesion: d.cohesion,
+        fileCount: d.file_count || 0,
+        symbolCount: d.symbol_count || 0,
+        fanIn: d.fan_in || 0,
+        fanOut: d.fan_out || 0,
+        files,
+      };
+    });
 
-  const lines = [`\nModule boundaries (cohesion >= ${data.threshold}, ${data.count} modules):\n`];
-  for (const m of data.modules) {
-    lines.push(
-      `  ${m.directory}/  cohesion=${m.cohesion.toFixed(2)}  (${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 { threshold, modules, count: modules.length };
+  } finally {
+    db.close();
   }
-  return lines.join('\n');
 }
 
 // ─── Helpers ──────────────────────────────────────────────────────────