feat: CLI composability helpers and universal output formatter (#461)

* feat: add cli composability helpers — openGraph helper, resolveQueryOpts, universal output formatter

Add openGraph(opts) helper to eliminate DB-open/close boilerplate in
cycles, export, and plot commands.

Add resolveQueryOpts(opts) to extract the 5 repeated option fields
(noTests, json, ndjson, limit, offset) plus new table/csv into one
call. Refactor 20 command files to use the spread pattern.

Extend outputResult() with --table (auto-column aligned table) and
--csv (RFC 4180 with nested object flattening) output formats. Add
--table and --csv options to applyQueryOpts().

Impact: 31 functions changed, 71 affected

* fix: escapeCsv RFC 4180 compliance and column detection from flattened items

Impact: 3 functions changed, 2 affected

* fix: use reduce instead of spread for column width to avoid stack overflow on large sets

Impact: 1 functions changed, 1 affected

* fix: remove redundant double-flattening and tone down RFC 4180 claim

Impact: 2 functions changed, 1 affected

* fix: guard flattenObject against non-POJO objects like Date and RegExp

Impact: 1 functions changed, 3 affected

* fix: exclude booleans from numeric column detection and add try/finally for close()

- result-formatter: skip boolean values in numeric column heuristic
  (Number(true) === 1 was misclassifying boolean columns as numeric)
- cycles/export/plot commands: wrap DB operations in try/finally to
  ensure close() is called even if an export function throws

Impact: 4 functions changed, 1 affected

* fix: guard top-level arrays in flattenObject and emit CSV header for empty sets

Impact: 2 functions changed, 1 affected

* fix: emit table header for empty result sets consistent with CSV path

Impact: 1 functions changed, 1 affected

* fix: address Greptile review feedback on PR #461

- Make printCsv/printAutoTable return false when items is not an array,
  and propagate that in outputResult so callers see the failure
- Remove config from resolveQueryOpts spread; audit and check now import
  config directly, other consumers use their existing loadConfig fallback
- Restructure export neo4j branch to avoid return inside try/finally;
  use output===undefined guard after the block instead

* fix: guard vacuous isNumeric on empty result sets

* fix: document dot-notation key collision assumption in flattenObject

* fix: add defensive guard for undefined plot HTML output

* refactor: extract prepareFlatItems helper to deduplicate CSV/table logic

Extracts the identical flat-items mapping and column-derivation block
from printCsv and printAutoTable into a shared prepareFlatItems helper,
so future format additions or bug fixes only need one code path.

Author: carlos-alm

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),
     });
   },
 };