@codragraph/cli 1.6.4 → 2.1.0

package/README.md

@@ -155,6 +155,9 @@ codragraph analyze --embeddings    # Enable embedding generation (slower, better
 codragraph analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md codragraph section edits
 codragraph analyze --verbose       # Log skipped files when parsers are unavailable
 codragraph analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
+codragraph analyze --compress brotli  # Per-row body compression. Also: zstd, none.
+codragraph profile-heap [path]     # Run analyze with v8 heap-snapshot instrumentation
+codragraph profile-heap --no-summary  # Same, but skip the post-run RSS / heapUsed table
 codragraph mcp                     # Start MCP server (stdio) — serves all indexed repos
 codragraph serve                   # Start local HTTP server (multi-repo) for web UI
 codragraph index                   # Register an existing .codragraph/ folder into the global registry
@@ -306,6 +309,37 @@ echo "vendor/" >> .codragraphignore
 echo "dist/" >> .codragraphignore
 ```
 
+If you want to know **which phase** is dragging the heap up before
+deciding what to mitigate, run `codragraph profile-heap`. It writes a
+v8 heap snapshot at every phase boundary plus a JSONL timeline of
+`process.memoryUsage()` and prints a per-phase RSS / `heapUsed` table:
+
+```bash
+codragraph profile-heap                       # writes .codragraph/heap-profiles/
+# → load any .heapsnapshot in Chrome DevTools → Memory → Load
+```
+
+Each snapshot is 100–500 MB, so the command is opt-in only. The JSONL
+timeline is small enough to share for triage even when the snapshots
+are too big.
+
+### Index size — opt-in per-row compression
+
+For repos where `.codragraph/cgdb` itself has grown large:
+
+```bash
+codragraph analyze --compress brotli   # Node ≥ 18, brotli quality 6
+codragraph analyze --compress zstd     # Node ≥ 22.15, zstd level 3
+codragraph analyze --compress none     # explicit default
+```
+
+`--compress` routes every node-row content field through the matching
+encoder before it's written to the CSV / cgdb; readers decode
+transparently via the per-row `contentEncoding` tag. With the flag
+unset, the on-disk layout is byte-identical to pre-1.8 indexes. Pre-1.8
+indexes auto-trigger a full re-analyze the first time a 1.8+ CLI runs
+against them (one-time cost, surfaced in the analyze log).
+
 ### Large files are being skipped
 
 By default the walker skips files larger than **512 KB** (see log line `Skipped N large files (>512KB)`). Raise the threshold via either the CLI flag or the environment variable — both accept a value in **KB**:

package/dist/_shared/cgdb/schema-constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * LadybugDB schema constants — single source of truth.
+ *
+ * NODE_TABLES and REL_TYPES define what the knowledge graph can contain.
+ * Both CLI and web must agree on these for data compatibility.
+ *
+ * Full DDL schemas remain in each package's own schema.ts because
+ * the CLI uses native LadybugDB and the web uses WASM.
+ */
+export declare const NODE_TABLES: readonly ["File", "Folder", "Function", "Class", "Interface", "Method", "CodeElement", "Community", "Process", "Section", "Struct", "Enum", "Macro", "Typedef", "Union", "Namespace", "Trait", "Impl", "TypeAlias", "Const", "Static", "Variable", "Property", "Record", "Delegate", "Annotation", "Constructor", "Template", "Module", "Route", "Tool"];
+export type NodeTableName = (typeof NODE_TABLES)[number];
+export declare const REL_TABLE_NAME = "CodeRelation";
+export declare const REL_TYPES: readonly ["CONTAINS", "DEFINES", "IMPORTS", "CALLS", "EXTENDS", "IMPLEMENTS", "HAS_METHOD", "HAS_PROPERTY", "ACCESSES", "METHOD_OVERRIDES", "OVERRIDES", "METHOD_IMPLEMENTS", "MEMBER_OF", "STEP_IN_PROCESS", "HANDLES_ROUTE", "FETCHES", "HANDLES_TOOL", "ENTRY_POINT_OF", "WRAPS", "QUERIES"];
+export type RelType = (typeof REL_TYPES)[number];
+export declare const EMBEDDING_TABLE_NAME = "CodeEmbedding";
+//# sourceMappingURL=schema-constants.d.ts.map

package/dist/_shared/cgdb/schema-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-constants.d.ts","sourceRoot":"","sources":["../../src/cgdb/schema-constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,WAAW,0VAgCd,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAO,MAAM,cAAc,iBAAiB,CAAC;AAE7C,eAAO,MAAM,SAAS,iSAqBZ,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,eAAO,MAAM,oBAAoB,kBAAkB,CAAC"}

package/dist/_shared/cgdb/schema-constants.js

@@ -0,0 +1,67 @@
+/**
+ * LadybugDB schema constants — single source of truth.
+ *
+ * NODE_TABLES and REL_TYPES define what the knowledge graph can contain.
+ * Both CLI and web must agree on these for data compatibility.
+ *
+ * Full DDL schemas remain in each package's own schema.ts because
+ * the CLI uses native LadybugDB and the web uses WASM.
+ */
+export const NODE_TABLES = [
+    'File',
+    'Folder',
+    'Function',
+    'Class',
+    'Interface',
+    'Method',
+    'CodeElement',
+    'Community',
+    'Process',
+    'Section',
+    'Struct',
+    'Enum',
+    'Macro',
+    'Typedef',
+    'Union',
+    'Namespace',
+    'Trait',
+    'Impl',
+    'TypeAlias',
+    'Const',
+    'Static',
+    'Variable',
+    'Property',
+    'Record',
+    'Delegate',
+    'Annotation',
+    'Constructor',
+    'Template',
+    'Module',
+    'Route',
+    'Tool',
+];
+export const REL_TABLE_NAME = 'CodeRelation';
+export const REL_TYPES = [
+    'CONTAINS',
+    'DEFINES',
+    'IMPORTS',
+    'CALLS',
+    'EXTENDS',
+    'IMPLEMENTS',
+    'HAS_METHOD',
+    'HAS_PROPERTY',
+    'ACCESSES',
+    'METHOD_OVERRIDES',
+    'OVERRIDES', // Legacy compat alias — kept until all stored indexes are migrated
+    'METHOD_IMPLEMENTS',
+    'MEMBER_OF',
+    'STEP_IN_PROCESS',
+    'HANDLES_ROUTE',
+    'FETCHES',
+    'HANDLES_TOOL',
+    'ENTRY_POINT_OF',
+    'WRAPS',
+    'QUERIES',
+];
+export const EMBEDDING_TABLE_NAME = 'CodeEmbedding';
+//# sourceMappingURL=schema-constants.js.map

package/dist/_shared/cgdb/schema-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-constants.js","sourceRoot":"","sources":["../../src/cgdb/schema-constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,MAAM;IACN,QAAQ;IACR,UAAU;IACV,OAAO;IACP,WAAW;IACX,QAAQ;IACR,aAAa;IACb,WAAW;IACX,SAAS;IACT,SAAS;IACT,QAAQ;IACR,MAAM;IACN,OAAO;IACP,SAAS;IACT,OAAO;IACP,WAAW;IACX,OAAO;IACP,MAAM;IACN,WAAW;IACX,OAAO;IACP,QAAQ;IACR,UAAU;IACV,UAAU;IACV,QAAQ;IACR,UAAU;IACV,YAAY;IACZ,aAAa;IACb,UAAU;IACV,QAAQ;IACR,OAAO;IACP,MAAM;CACE,CAAC;AAIX,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAAC;AAE7C,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,UAAU;IACV,SAAS;IACT,SAAS;IACT,OAAO;IACP,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,UAAU;IACV,kBAAkB;IAClB,WAAW,EAAE,mEAAmE;IAChF,mBAAmB;IACnB,WAAW;IACX,iBAAiB;IACjB,eAAe;IACf,SAAS;IACT,cAAc;IACd,gBAAgB;IAChB,OAAO;IACP,SAAS;CACD,CAAC;AAIX,MAAM,CAAC,MAAM,oBAAoB,GAAG,eAAe,CAAC"}

package/dist/_shared/index.d.ts

@@ -1,6 +1,6 @@
 export type { NodeLabel, NodeProperties, RelationshipType, GraphNode, GraphRelationship, } from './graph/types.js';
-export { NODE_TABLES, REL_TABLE_NAME, REL_TYPES, EMBEDDING_TABLE_NAME, } from './lbug/schema-constants.js';
-export type { NodeTableName, RelType } from './lbug/schema-constants.js';
+export { NODE_TABLES, REL_TABLE_NAME, REL_TYPES, EMBEDDING_TABLE_NAME, } from './cgdb/schema-constants.js';
+export type { NodeTableName, RelType } from './cgdb/schema-constants.js';
 export { SupportedLanguages } from './languages.js';
 export { getLanguageFromFilename, getSyntaxLanguageFromFilename } from './language-detection.js';
 export type { MroStrategy } from './mro-strategy.js';

package/dist/_shared/index.js

@@ -1,5 +1,5 @@
 // Schema constants
-export { NODE_TABLES, REL_TABLE_NAME, REL_TYPES, EMBEDDING_TABLE_NAME, } from './lbug/schema-constants.js';
+export { NODE_TABLES, REL_TABLE_NAME, REL_TYPES, EMBEDDING_TABLE_NAME, } from './cgdb/schema-constants.js';
 // Language support
 export { SupportedLanguages } from './languages.js';
 export { getLanguageFromFilename, getSyntaxLanguageFromFilename } from './language-detection.js';

package/dist/cli/analyze.d.ts

@@ -39,5 +39,27 @@ export interface AnalyzeOptions {
      * `CODRAGRAPH_MAX_FILE_SIZE` for the rest of the pipeline.
      */
     maxFileSize?: string;
+    /**
+     * First-run auto-setup gate. Default `true` (commander injects this from the
+     * `--no-setup` flag — see CLI registration). When `true`, `analyze` detects a
+     * missing `~/.codragraph/registry.json` and runs editor setup before indexing,
+     * making `npx @codragraph/cli analyze` a true zero-install entry. Pass
+     * `--no-setup` to opt out (CI, headless servers, automated pipelines).
+     */
+    setup?: boolean;
+    /**
+     * Comma-separated list of editor targets for `--skills` output. Valid values
+     * are `claude`, `cursor`, `opencode`, `codex`. Default: `claude` (matches
+     * pre-flag behavior). Unknown values are reported and ignored.
+     */
+    skillTargets?: string;
+    /**
+     * RFC 0001 Phase 2 — opt-in per-row content compression. Accepts
+     * `'none'` (default), `'brotli'` (Node ≥ 18), or `'zstd'` (Node ≥
+     * 22.15). Compressed indexes are still queryable via the standard
+     * read path; decode happens at every external-consumer boundary
+     * (MCP, HTTP API, embeddings, CLI tools).
+     */
+    compress?: 'none' | 'brotli' | 'zstd';
 }
 export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;

package/dist/cli/analyze.js

@@ -11,7 +11,8 @@ import path from 'path';
 import { execFileSync } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
-import { closeLbug } from '../core/lbug/lbug-adapter.js';
+import * as fsSync from 'node:fs';
+import { closeCgdb } from '../core/cgdb/cgdb-adapter.js';
 import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir } from '../storage/git.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
@@ -52,9 +53,77 @@ export const analyzeCommand = async (inputPath, options) => {
     if (options?.verbose) {
         process.env.CODRAGRAPH_VERBOSE = '1';
     }
+    // RFC 0001 Phase 2 — validate --compress before doing any work. Catching
+    // a typo or an unsupported encoding here is much friendlier than failing
+    // mid-analyze with an opaque CSV-write error. Node-version gating for
+    // zstd lives in @codragraph/graphstore via isEncodingSupported, but we
+    // import the check here so the CLI can offer the brotli fallback hint.
+    if (options?.compress && options.compress !== 'none') {
+        if (options.compress !== 'brotli' && options.compress !== 'zstd') {
+            console.error(`  --compress must be one of: none, brotli, zstd (got: ${options.compress})`);
+            process.exitCode = 2;
+            return;
+        }
+        if (options.compress === 'zstd') {
+            const { isEncodingSupported } = await import('@codragraph/graphstore');
+            if (!isEncodingSupported('zstd')) {
+                console.error('  --compress zstd requires Node ≥ 22.15.0 (native node:zlib zstd).\n' +
+                    `  Detected Node ${process.version}. Use --compress brotli instead, or upgrade Node.`);
+                process.exitCode = 2;
+                return;
+            }
+        }
+        // RFC 0001 Phase 2.5 — BM25 / FTS now drops `content` from its
+        // property list when meta.compress is non-'none' (see
+        // `core/search/bm25-index.ts`), so search inside compressed bodies
+        // gracefully falls back to name-only matches instead of tokenising
+        // base64 garbage. Surface the trade-off so users know what they're
+        // opting into.
+        console.warn(`  Note: --compress ${options.compress} reduces .codragraph/cgdb size.\n` +
+            `  BM25 search will index symbol names only (function bodies are not tokenised\n` +
+            `  when compressed); embeddings, graph queries, and \`context\` / \`impact\` are\n` +
+            `  unaffected. Run with --compress none if you rely on full-text search inside\n` +
+            `  source bodies.`);
+    }
     if (options?.maxFileSize) {
         process.env.CODRAGRAPH_MAX_FILE_SIZE = options.maxFileSize;
     }
+    // ── Auto-reindex coalesce-file cleanup ─────────────────────────────
+    // When the Claude Code PostToolUse hook spawns us in background mode, it
+    // passes the coalesce file path through this env var. We delete it on every
+    // exit path so the next commit immediately triggers a new reindex (rather
+    // than being blocked by a 10-min mtime TTL). The hook's TTL is just a
+    // crash safety net — this is the happy path.
+    const reindexLockPath = process.env.CODRAGRAPH_REINDEX_LOCK_PATH || '';
+    if (reindexLockPath) {
+        process.on('exit', () => {
+            try {
+                fsSync.unlinkSync(reindexLockPath);
+            }
+            catch {
+                /* already gone or unreadable — fine */
+            }
+        });
+    }
+    // ── First-run auto-setup ───────────────────────────────────────────
+    // Makes `npx @codragraph/cli analyze` a true one-command entry. We detect
+    // first-run by the absence of the global registry — analyze writes to it on
+    // every successful index, so it's a reliable "this user has never run us
+    // before" signal. Opt out with `--no-setup` for CI / headless contexts;
+    // commander maps `--no-setup` to `options.setup === false`.
+    if (options?.setup !== false) {
+        let registryExists = true;
+        try {
+            await fs.access(getGlobalRegistryPath());
+        }
+        catch {
+            registryExists = false;
+        }
+        if (!registryExists) {
+            const { runSetup } = await import('./setup.js');
+            await runSetup({ skipNextSteps: true, compactHeader: true });
+        }
+    }
     console.log('\n  CodraGraph Analyzer\n');
     let repoPath;
     if (inputPath) {
@@ -113,7 +182,7 @@ export const analyzeCommand = async (inputPath, options) => {
         aborted = true;
         bar.stop();
         console.log('\n  Interrupted — cleaning up...');
-        closeLbug()
+        closeCgdb()
             .catch(() => { })
             .finally(() => process.exit(130));
     };
@@ -168,6 +237,9 @@ export const analyzeCommand = async (inputPath, options) => {
             // be able to accept the duplicate name without also paying the
             // cost of a full pipeline re-index. See #829 review round 2.
             allowDuplicateName: options?.allowDuplicateName,
+            // RFC 0001 Phase 2 — pass through the per-row encoding choice.
+            // Default 'none' / undefined keeps the pre-Phase-2 wire layout.
+            compress: options?.compress,
         }, {
             onProgress: (_phase, percent, message) => {
                 updateBar(percent, message);
@@ -190,9 +262,23 @@ export const analyzeCommand = async (inputPath, options) => {
         if (options?.skills && result.pipelineResult) {
             updateBar(99, 'Generating skill files...');
             try {
-                const { generateSkillFiles } = await import('./skill-gen.js');
+                const { generateSkillFiles, SKILL_TARGETS } = await import('./skill-gen.js');
                 const { generateAIContextFiles } = await import('./ai-context.js');
-                const skillResult = await generateSkillFiles(repoPath, result.repoName, result.pipelineResult);
+                // Parse --skill-targets CSV; default to ['claude'] when omitted.
+                // Unknown tokens are reported once and dropped — we don't fail the
+                // whole analyze for a typo here, but we do want the user to see it.
+                const requestedTargets = (options?.skillTargets || 'claude')
+                    .split(',')
+                    .map((s) => s.trim().toLowerCase())
+                    .filter(Boolean);
+                const validTargets = requestedTargets.filter((t) => SKILL_TARGETS.includes(t));
+                const invalidTargets = requestedTargets.filter((t) => !SKILL_TARGETS.includes(t));
+                if (invalidTargets.length > 0) {
+                    barLog(`  Skills: unknown target(s) ignored: ${invalidTargets.join(', ')} ` +
+                        `(valid: ${SKILL_TARGETS.join(', ')})`);
+                }
+                const targetsToUse = validTargets.length > 0 ? validTargets : ['claude'];
+                const skillResult = await generateSkillFiles(repoPath, result.repoName, result.pipelineResult, targetsToUse);
                 if (skillResult.skills.length > 0) {
                     barLog(`  Generated ${skillResult.skills.length} skill files`);
                     // Re-generate AI context files now that we have skill info
@@ -235,11 +321,28 @@ export const analyzeCommand = async (inputPath, options) => {
         console.log(`\n  Repository indexed successfully (${totalTime}s)\n`);
         console.log(`  ${(s.nodes ?? 0).toLocaleString()} nodes | ${(s.edges ?? 0).toLocaleString()} edges | ${s.communities ?? 0} clusters | ${s.processes ?? 0} flows`);
         console.log(`  ${repoPath}`);
+        // Surface @codragraph/compress's value prop with concrete numbers: how
+        // many tokens of distilled context did we generate. Best-effort — never
+        // fail the analyze for a stat read.
         try {
-            await fs.access(getGlobalRegistryPath());
+            const { estimateTokens } = await import('./compress-stats.js');
+            const candidates = ['AGENTS.md', 'CLAUDE.md'];
+            const sizes = [];
+            for (const file of candidates) {
+                try {
+                    const content = await fs.readFile(path.join(repoPath, file), 'utf-8');
+                    sizes.push(`${file} ~${estimateTokens(content).toLocaleString()} tokens`);
+                }
+                catch {
+                    /* file not generated for this run — skip */
+                }
+            }
+            if (sizes.length > 0) {
+                console.log(`  @codragraph/compress: ${sizes.join(' | ')}`);
+            }
         }
         catch {
-            console.log('\n  Tip: Run `codragraph setup` to configure MCP for your editor.');
+            /* compress-stats import failed — non-fatal */
         }
         console.log('');
     }

package/dist/cli/compress-stats.d.ts

@@ -0,0 +1,29 @@
+/** chars/4 token estimate. Matches @codragraph/compress's `estimateTokens`. */
+export declare function estimateTokens(text: string): number;
+/**
+ * Walk a result object and collect every file path we can find. Looks for
+ * `filePath`, `file_path`, and `file` keys at any depth. Used to estimate
+ * the raw-grep baseline (sum of source bytes the agent would have read
+ * without CodraGraph).
+ */
+export declare function collectFilePaths(obj: unknown, paths?: Set<string>): Set<string>;
+/**
+ * Estimate raw-grep-equivalent token count by summing on-disk byte sizes of
+ * the referenced files. Returns null if any file is missing or unreadable —
+ * in that case we silently skip the comparison rather than show a misleading
+ * number.
+ */
+export declare function estimateRawGrepTokens(filePaths: Iterable<string>): number | null;
+/**
+ * Format a one-line token-savings summary suitable for stderr display.
+ * If a raw baseline is provided AND it's larger than the structured response,
+ * the line includes the savings percentage. Otherwise it only reports
+ * the structured token count.
+ */
+export declare function formatTokenLine(structuredTokens: number, rawTokens?: number | null): string;
+/**
+ * Compute and print the token-savings line for a tool result. Best-effort:
+ * never throws, never blocks output. Goes to stderr so JSON consumers piping
+ * stdout to jq stay clean.
+ */
+export declare function emitTokenStats(result: unknown): void;

package/dist/cli/compress-stats.js

@@ -0,0 +1,97 @@
+/**
+ * Token-savings reporter for CLI output.
+ *
+ * Surfaces the @codragraph/compress value proposition on every `query`,
+ * `context`, `impact`, and `analyze` invocation: how many tokens of
+ * structured context did we return vs the equivalent raw-grep response.
+ *
+ * Uses the same chars/4 heuristic as @codragraph/compress's `estimateTokens`
+ * for cross-package consistency. Inlined rather than imported because pulling
+ * in @codragraph/compress as a runtime dep also pulls @codragraph/harness as a
+ * transitive — too heavy for what is logically a one-line approximation. When
+ * we add real LLM compression (`--compress` opt-in), the package import will
+ * follow.
+ */
+import * as fsSync from 'node:fs';
+/** chars/4 token estimate. Matches @codragraph/compress's `estimateTokens`. */
+export function estimateTokens(text) {
+    return Math.max(0, Math.floor(text.trim().length / 4));
+}
+/**
+ * Walk a result object and collect every file path we can find. Looks for
+ * `filePath`, `file_path`, and `file` keys at any depth. Used to estimate
+ * the raw-grep baseline (sum of source bytes the agent would have read
+ * without CodraGraph).
+ */
+export function collectFilePaths(obj, paths = new Set()) {
+    if (!obj || typeof obj !== 'object')
+        return paths;
+    if (Array.isArray(obj)) {
+        for (const item of obj)
+            collectFilePaths(item, paths);
+        return paths;
+    }
+    for (const [key, value] of Object.entries(obj)) {
+        if ((key === 'filePath' || key === 'file_path' || key === 'file') &&
+            typeof value === 'string' &&
+            value.length > 0) {
+            paths.add(value);
+        }
+        else if (typeof value === 'object') {
+            collectFilePaths(value, paths);
+        }
+    }
+    return paths;
+}
+/**
+ * Estimate raw-grep-equivalent token count by summing on-disk byte sizes of
+ * the referenced files. Returns null if any file is missing or unreadable —
+ * in that case we silently skip the comparison rather than show a misleading
+ * number.
+ */
+export function estimateRawGrepTokens(filePaths) {
+    let totalChars = 0;
+    for (const fp of filePaths) {
+        try {
+            const stat = fsSync.statSync(fp);
+            if (!stat.isFile())
+                return null;
+            totalChars += stat.size;
+        }
+        catch {
+            return null;
+        }
+    }
+    return Math.floor(totalChars / 4);
+}
+/**
+ * Format a one-line token-savings summary suitable for stderr display.
+ * If a raw baseline is provided AND it's larger than the structured response,
+ * the line includes the savings percentage. Otherwise it only reports
+ * the structured token count.
+ */
+export function formatTokenLine(structuredTokens, rawTokens) {
+    if (rawTokens && rawTokens > structuredTokens) {
+        const savings = Math.round((1 - structuredTokens / rawTokens) * 100);
+        return (`  @codragraph/compress: ~${structuredTokens.toLocaleString()} tokens of structured context ` +
+            `(vs ~${rawTokens.toLocaleString()} tokens of raw source — ${savings}% smaller).`);
+    }
+    return `  @codragraph/compress: ~${structuredTokens.toLocaleString()} tokens of structured context.`;
+}
+/**
+ * Compute and print the token-savings line for a tool result. Best-effort:
+ * never throws, never blocks output. Goes to stderr so JSON consumers piping
+ * stdout to jq stay clean.
+ */
+export function emitTokenStats(result) {
+    try {
+        const structured = typeof result === 'string' ? result : JSON.stringify(result);
+        const sTokens = estimateTokens(structured);
+        const files = collectFilePaths(result);
+        const rawTokens = files.size > 0 ? estimateRawGrepTokens(files) : null;
+        process.stderr.write('\n' + formatTokenLine(sTokens, rawTokens) + '\n');
+    }
+    catch {
+        /* never let stats break the actual output */
+    }
+}

package/dist/cli/graphstore.d.ts

@@ -12,7 +12,9 @@ export declare const logCommand: (opts?: {
     limit?: string;
 }) => Promise<void>;
 export declare const branchListCommand: () => Promise<void>;
-export declare const diffCommand: (from: string, to: string) => Promise<void>;
+export declare const diffCommand: (from: string, to: string, opts?: {
+    json?: boolean;
+}) => Promise<void>;
 export declare const commitCommand: (opts?: {
     message?: string;
 }) => Promise<void>;
@@ -36,5 +38,7 @@ export declare const mergeCommand: (target: string, opts?: {
 export declare const gcCommand: (opts?: {
     dryRun?: boolean;
 }) => Promise<void>;
-export declare const diffSemanticCommand: (from: string, to: string) => Promise<void>;
+export declare const diffSemanticCommand: (from: string, to: string, opts?: {
+    json?: boolean;
+}) => Promise<void>;
 export { DEFAULT_BRANCH };