feat: CLI composability helpers and universal output formatter

src/cli/commands/ast.js

@@ -16,11 +16,7 @@ export const command = {
     astQuery(pattern, opts.db, {
       kind: opts.kind,
       file: opts.file,
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
-      ndjson: opts.ndjson,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };

src/cli/commands/audit.js

@@ -1,6 +1,7 @@
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 import { audit } from '../../presentation/audit.js';
 import { explain } from '../../presentation/queries-cli.js';
+import { config } from '../shared/options.js';
 
 export const command = {
   name: 'audit <target>',
@@ -24,24 +25,21 @@ export const command = {
     }
   },
   execute([target], opts, ctx) {
+    const qOpts = ctx.resolveQueryOpts(opts);
     if (opts.quick) {
       explain(target, opts.db, {
         depth: parseInt(opts.depth, 10),
-        noTests: ctx.resolveNoTests(opts),
-        json: opts.json,
-        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-        ndjson: opts.ndjson,
+        ...qOpts,
       });
       return;
     }
     audit(target, opts.db, {
       depth: parseInt(opts.depth, 10),
       file: opts.file,
       kind: opts.kind,
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
-      config: ctx.config,
+      noTests: qOpts.noTests,
+      json: qOpts.json,
+      config,
     });
   },
 };

src/cli/commands/cfg.js

@@ -20,11 +20,7 @@ export const command = {
       format: opts.format,
       file: opts.file,
       kind: opts.kind,
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
-      ndjson: opts.ndjson,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };

src/cli/commands/check.js

@@ -1,5 +1,6 @@
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 import { ConfigError } from '../../shared/errors.js';
+import { config } from '../shared/options.js';
 
 export const command = {
   name: 'check [ref]',
@@ -25,6 +26,7 @@ export const command = {
   ],
   async execute([ref], opts, ctx) {
     const isDiffMode = ref || opts.staged;
+    const qOpts = ctx.resolveQueryOpts(opts);
 
     if (!isDiffMode && !opts.rules) {
       if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
@@ -36,12 +38,7 @@ export const command = {
       manifesto(opts.db, {
         file: opts.file,
         kind: opts.kind,
-        noTests: ctx.resolveNoTests(opts),
-        json: opts.json,
-        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-        ndjson: opts.ndjson,
-        config: ctx.config,
+        ...qOpts,
       });
       return;
     }
@@ -55,9 +52,9 @@ export const command = {
       signatures: opts.signatures || undefined,
       boundaries: opts.boundaries || undefined,
       depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
-      config: ctx.config,
+      noTests: qOpts.noTests,
+      json: qOpts.json,
+      config,
     });
 
     if (opts.rules) {
@@ -70,12 +67,7 @@ export const command = {
       manifesto(opts.db, {
         file: opts.file,
         kind: opts.kind,
-        noTests: ctx.resolveNoTests(opts),
-        json: opts.json,
-        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-        ndjson: opts.ndjson,
-        config: ctx.config,
+        ...qOpts,
       });
     }
   },

src/cli/commands/children.js

@@ -22,10 +22,7 @@ export const command = {
     children(name, opts.db, {
       file: opts.file,
       kind: opts.kind,
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };

src/cli/commands/communities.js

@@ -13,11 +13,7 @@ export const command = {
       functions: opts.functions,
       resolution: parseFloat(opts.resolution),
       drift: opts.drift,
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-      ndjson: opts.ndjson,
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };

src/cli/commands/context.js

@@ -23,12 +23,8 @@ export const command = {
       file: opts.file,
       kind: opts.kind,
       noSource: !opts.source,
-      noTests: ctx.resolveNoTests(opts),
       includeTests: opts.withTestSource,
-      json: opts.json,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-      ndjson: opts.ndjson,
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };

src/cli/commands/cycles.js

@@ -1,5 +1,5 @@
-import { openReadonlyOrFail } from '../../db/index.js';
 import { findCycles, formatCycles } from '../../domain/graph/cycles.js';
+import { openGraph } from '../shared/open-graph.js';
 
 export const command = {
   name: 'cycles',
@@ -12,12 +12,16 @@ export const command = {
     ['-j, --json', 'Output as JSON'],
   ],
   execute(_args, opts, ctx) {
-    const db = openReadonlyOrFail(opts.db);
-    const cycles = findCycles(db, {
-      fileLevel: !opts.functions,
-      noTests: ctx.resolveNoTests(opts),
-    });
-    db.close();
+    const { db, close } = openGraph(opts);
+    let cycles;
+    try {
+      cycles = findCycles(db, {
+        fileLevel: !opts.functions,
+        noTests: ctx.resolveNoTests(opts),
+      });
+    } finally {
+      close();
+    }
 
     if (opts.json) {
       console.log(JSON.stringify({ cycles, count: cycles.length }, null, 2));

src/cli/commands/dataflow.js

@@ -20,13 +20,9 @@ export const command = {
     dataflow(name, opts.db, {
       file: opts.file,
       kind: opts.kind,
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
-      ndjson: opts.ndjson,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
       impact: opts.impact,
       depth: parseInt(opts.depth, 10),
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };

src/cli/commands/deps.js

@@ -6,11 +6,7 @@ export const command = {
   queryOpts: true,
   execute([file], opts, ctx) {
     fileDeps(file, opts.db, {
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-      ndjson: opts.ndjson,
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };

src/cli/commands/diff-impact.js

@@ -19,13 +19,8 @@ export const command = {
       ref,
       staged: opts.staged,
       depth: parseInt(opts.depth, 10),
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
       format: opts.format,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-      ndjson: opts.ndjson,
-      config: ctx.config,
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };

src/cli/commands/export.js

@@ -1,5 +1,4 @@
 import fs from 'node:fs';
-import { openReadonlyOrFail } from '../../db/index.js';
 import {
   exportDOT,
   exportGraphML,
@@ -8,6 +7,7 @@ import {
   exportMermaid,
   exportNeo4jCSV,
 } from '../../features/export.js';
+import { openGraph } from '../shared/open-graph.js';
 
 export const command = {
   name: 'export',
@@ -23,7 +23,7 @@ export const command = {
     ['-o, --output <file>', 'Write to file instead of stdout'],
   ],
   execute(_args, opts, ctx) {
-    const db = openReadonlyOrFail(opts.db);
+    const { db, close } = openGraph(opts);
     const exportOpts = {
       fileLevel: !opts.functions,
       noTests: ctx.resolveNoTests(opts),
@@ -32,38 +32,41 @@ export const command = {
     };
 
     let output;
-    switch (opts.format) {
-      case 'mermaid':
-        output = exportMermaid(db, exportOpts);
-        break;
-      case 'json':
-        output = JSON.stringify(exportJSON(db, exportOpts), null, 2);
-        break;
-      case 'graphml':
-        output = exportGraphML(db, exportOpts);
-        break;
-      case 'graphson':
-        output = JSON.stringify(exportGraphSON(db, exportOpts), null, 2);
-        break;
-      case 'neo4j': {
-        const csv = exportNeo4jCSV(db, exportOpts);
-        if (opts.output) {
-          const base = opts.output.replace(/\.[^.]+$/, '') || opts.output;
-          fs.writeFileSync(`${base}-nodes.csv`, csv.nodes, 'utf-8');
-          fs.writeFileSync(`${base}-relationships.csv`, csv.relationships, 'utf-8');
-          db.close();
-          console.log(`Exported to ${base}-nodes.csv and ${base}-relationships.csv`);
-          return;
+    try {
+      switch (opts.format) {
+        case 'mermaid':
+          output = exportMermaid(db, exportOpts);
+          break;
+        case 'json':
+          output = JSON.stringify(exportJSON(db, exportOpts), null, 2);
+          break;
+        case 'graphml':
+          output = exportGraphML(db, exportOpts);
+          break;
+        case 'graphson':
+          output = JSON.stringify(exportGraphSON(db, exportOpts), null, 2);
+          break;
+        case 'neo4j': {
+          const csv = exportNeo4jCSV(db, exportOpts);
+          if (opts.output) {
+            const base = opts.output.replace(/\.[^.]+$/, '') || opts.output;
+            fs.writeFileSync(`${base}-nodes.csv`, csv.nodes, 'utf-8');
+            fs.writeFileSync(`${base}-relationships.csv`, csv.relationships, 'utf-8');
+            console.log(`Exported to ${base}-nodes.csv and ${base}-relationships.csv`);
+          } else {
+            output = `--- nodes.csv ---\n${csv.nodes}\n\n--- relationships.csv ---\n${csv.relationships}`;
+          }
+          break;
         }
-        output = `--- nodes.csv ---\n${csv.nodes}\n\n--- relationships.csv ---\n${csv.relationships}`;
-        break;
+        default:
+          output = exportDOT(db, exportOpts);
+          break;
       }
-      default:
-        output = exportDOT(db, exportOpts);
-        break;
+    } finally {
+      close();
     }
 
-    db.close();
+    if (output === undefined) return;
 
     if (opts.output) {
       fs.writeFileSync(opts.output, output, 'utf-8');

src/cli/commands/exports.js

@@ -7,12 +7,8 @@ export const command = {
   options: [['--unused', 'Show only exports with zero consumers (dead exports)']],
   execute([file], opts, ctx) {
     fileExports(file, opts.db, {
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
       unused: opts.unused || false,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-      ndjson: opts.ndjson,
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };

src/cli/commands/flow.js

@@ -26,11 +26,7 @@ export const command = {
       depth: parseInt(opts.depth, 10),
       file: opts.file,
       kind: opts.kind,
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-      ndjson: opts.ndjson,
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };

src/cli/commands/fn-impact.js

@@ -20,11 +20,7 @@ export const command = {
       depth: parseInt(opts.depth, 10),
       file: opts.file,
       kind: opts.kind,
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-      ndjson: opts.ndjson,
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };

src/cli/commands/impact.js

@@ -6,11 +6,7 @@ export const command = {
   queryOpts: true,
   execute([file], opts, ctx) {
     impactAnalysis(file, opts.db, {
-      noTests: ctx.resolveNoTests(opts),
-      json: opts.json,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-      ndjson: opts.ndjson,
+      ...ctx.resolveQueryOpts(opts),
     });
   },
 };