@codragraph/cli 2.1.5 → 2.2.0-rc.6

package/dist/cli/tool.d.ts

@@ -21,15 +21,23 @@ export declare function queryCommand(queryText: string, options?: {
     limit?: string;
     content?: boolean;
 }): Promise<void>;
-export declare function contextCommand(name: string, options?: {
+export declare function contextCommand(name: string | undefined | {
+    opts?: () => Record<string, unknown>;
+}, options?: {
     repo?: string;
     file?: string;
     uid?: string;
+    kind?: string;
     content?: boolean;
 }): Promise<void>;
-export declare function impactCommand(target: string, options?: {
+export declare function impactCommand(target: string | undefined | {
+    opts?: () => Record<string, unknown>;
+}, options?: {
     direction?: string;
     repo?: string;
+    uid?: string;
+    file?: string;
+    kind?: string;
     depth?: string;
     includeTests?: boolean;
 }): Promise<void>;
@@ -55,6 +63,7 @@ export declare function clusterContextCommand(name: string, options?: {
 export declare function contextPackCommand(name: string, options?: {
     repo?: string;
     limit?: string;
+    compress?: string;
 }): Promise<void>;
 export declare function clusterImpactCommand(name: string, options?: {
     direction?: string;

package/dist/cli/tool.js

@@ -14,6 +14,7 @@
  * native module which captures the Node.js process.stdout stream during init.
  * See the output() function for details (#324).
  */
+import crypto from 'node:crypto';
 import { writeSync } from 'node:fs';
 import { LocalBackend } from '../mcp/local/local-backend.js';
 import { emitTokenStats } from './compress-stats.js';
@@ -45,6 +46,12 @@ async function resolveCliRepoParam(repoParam) {
     process.exitCode = 1;
     return null;
 }
+function unwrapCommanderOptions(value) {
+    if (!value || typeof value !== 'object')
+        return value;
+    const maybeCommand = value;
+    return typeof maybeCommand.opts === 'function' ? maybeCommand.opts() : value;
+}
 /**
  * Write tool output to stdout using low-level fd write.
  *
@@ -90,7 +97,12 @@ export async function queryCommand(queryText, options) {
     emitTokenStats(result);
 }
 export async function contextCommand(name, options) {
-    if (!name?.trim() && !options?.uid) {
+    let symbolName = typeof name === 'string' ? name : undefined;
+    if (typeof name !== 'string' && name && !options) {
+        options = unwrapCommanderOptions(name);
+        symbolName = undefined;
+    }
+    if (!symbolName?.trim() && !options?.uid) {
         console.error('Usage: codragraph context <symbol_name> [--uid <uid>] [--file <path>]');
         process.exit(1);
     }
@@ -98,9 +110,10 @@ export async function contextCommand(name, options) {
     if (!repo)
         return;
     const result = await callToolOnce('context', {
-        name: name || undefined,
+        name: symbolName || undefined,
         uid: options?.uid,
         file_path: options?.file,
+        kind: options?.kind,
         include_content: options?.content ?? false,
         repo,
     });
@@ -108,8 +121,13 @@ export async function contextCommand(name, options) {
     emitTokenStats(result);
 }
 export async function impactCommand(target, options) {
-    if (!target?.trim()) {
-        console.error('Usage: codragraph impact <symbol_name> [--direction upstream|downstream]');
+    let targetName = typeof target === 'string' ? target : undefined;
+    if (typeof target !== 'string' && target && !options) {
+        options = unwrapCommanderOptions(target);
+        targetName = undefined;
+    }
+    if (!targetName?.trim() && !options?.uid) {
+        console.error('Usage: codragraph impact <symbol_name> [--uid <uid>] [--direction upstream|downstream]');
         process.exit(1);
     }
     try {
@@ -117,7 +135,10 @@ export async function impactCommand(target, options) {
         if (!repo)
             return;
         const result = await callToolOnce('impact', {
-            target,
+            target: targetName || undefined,
+            target_uid: options?.uid,
+            file_path: options?.file,
+            kind: options?.kind,
             direction: options?.direction || 'upstream',
             maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
             includeTests: options?.includeTests ?? false,
@@ -131,7 +152,7 @@ export async function impactCommand(target, options) {
         // The backend's impact() already returns structured errors for graph query failures
         output({
             error: (err instanceof Error ? err.message : String(err)) || 'Impact analysis failed unexpectedly',
-            target: { name: target },
+            target: { name: targetName || options?.uid },
             direction: options?.direction || 'upstream',
             suggestion: 'Try reducing --depth or using codragraph context <symbol> as a fallback',
         });
@@ -218,8 +239,116 @@ export async function contextPackCommand(name, options) {
         repo,
         limit: options?.limit ? parseInt(options.limit, 10) : undefined,
     });
-    output(result);
-    emitTokenStats(result);
+    const maybeCompressed = options?.compress
+        ? compressContextPackForCli(result, name, options.compress)
+        : result;
+    output(maybeCompressed);
+    emitTokenStats(maybeCompressed);
+}
+function compressContextPackForCli(result, featureName, rawLevel) {
+    const level = normalizeCliCompressionLevel(rawLevel);
+    const originalText = JSON.stringify(result);
+    const compressed = pruneContextPack(result, level);
+    const compressedText = JSON.stringify(compressed);
+    const originalTokens = estimateJsonTokens(originalText);
+    const compressedTokens = estimateJsonTokens(compressedText);
+    const snapshotId = result?.snapshotId ??
+        result?.snapshot_id ??
+        result?.cluster?.lastIndexedCommit ??
+        result?.cluster?.snapshotId ??
+        'unknown';
+    const clusterId = result?.cluster?.id ?? result?.cluster?.slug ?? featureName;
+    const cacheKey = crypto
+        .createHash('sha256')
+        .update(`${snapshotId}\n${clusterId}\n${level}\ncli-context-pack-compressor-v1`)
+        .digest('hex');
+    return {
+        ...compressed,
+        compression: {
+            level,
+            compressorVersion: 'cli-context-pack-compressor-v1',
+            cacheKey: `ctxpack:${cacheKey.slice(0, 32)}`,
+            originalTokens,
+            compressedTokens,
+            tokenSavingsPct: originalTokens > 0
+                ? Number((((originalTokens - compressedTokens) / originalTokens) * 100).toFixed(1))
+                : 0,
+            preserved: [
+                'feature cluster',
+                'files',
+                'line ranges',
+                'symbols',
+                'tests',
+                'routes',
+                'tools',
+                'dependencies',
+                'warnings',
+            ],
+        },
+    };
+}
+function normalizeCliCompressionLevel(raw) {
+    if (raw === 'balanced' || raw === 'lean' || raw === 'max')
+        return raw;
+    throw new Error('context-pack --compress must be one of: balanced, lean, max');
+}
+function pruneContextPack(value, level) {
+    if (!value || typeof value !== 'object')
+        return value;
+    const memberLimit = level === 'max' ? 20 : level === 'lean' ? 40 : 80;
+    const processLimit = level === 'max' ? 5 : level === 'lean' ? 8 : 15;
+    const supportLimit = level === 'max' ? 5 : level === 'lean' ? 10 : 20;
+    return {
+        cluster: value.cluster,
+        members: Array.isArray(value.members)
+            ? value.members.slice(0, memberLimit).map(compactContextPackItem)
+            : value.members,
+        entryPoints: Array.isArray(value.entryPoints)
+            ? value.entryPoints.slice(0, supportLimit).map(compactContextPackItem)
+            : value.entryPoints,
+        routes: value.routes,
+        tools: value.tools,
+        dependencies: value.dependencies,
+        processes: Array.isArray(value.processes)
+            ? value.processes.slice(0, processLimit).map(compactContextPackItem)
+            : value.processes,
+        tests: Array.isArray(value.tests)
+            ? value.tests.slice(0, supportLimit).map(compactContextPackItem)
+            : value.tests,
+        docs: Array.isArray(value.docs)
+            ? value.docs.slice(0, supportLimit).map(compactContextPackItem)
+            : value.docs,
+        warnings: value.warnings ?? value.safeEditSurface?.warnings,
+        safeEditSurface: value.safeEditSurface,
+    };
+}
+function compactContextPackItem(item) {
+    if (!item || typeof item !== 'object')
+        return item;
+    const keys = [
+        'id',
+        'uid',
+        'name',
+        'type',
+        'kind',
+        'filePath',
+        'file',
+        'startLine',
+        'endLine',
+        'route',
+        'method',
+        'summary',
+        'confidence',
+    ];
+    const compact = {};
+    for (const key of keys) {
+        if (item[key] !== undefined)
+            compact[key] = item[key];
+    }
+    return compact;
+}
+function estimateJsonTokens(text) {
+    return Math.ceil(text.length / 4);
 }
 export async function clusterImpactCommand(name, options) {
     if (!name?.trim()) {
@@ -272,6 +401,7 @@ function formatDetectChangesResult(result) {
     return lines.join('\n').trim();
 }
 export async function detectChangesCommand(options) {
+    options = unwrapCommanderOptions(options);
     const repo = await resolveCliRepoParam(options?.repo);
     if (!repo)
         return;

package/dist/core/adaptive-profile.d.ts

@@ -0,0 +1,52 @@
+import type { ContentEncoding } from '@codragraph/graphstore';
+import type { RepoMeta } from '../storage/repo-manager.js';
+export type AnalyzeProfileOption = 'auto' | 'lean' | 'balanced' | 'power';
+export type ResolvedAnalyzeProfile = Exclude<AnalyzeProfileOption, 'auto'>;
+export type EmbeddingMode = 'auto' | 'off' | 'on';
+export type CompressionOption = ContentEncoding | 'auto';
+export interface MachineSnapshot {
+    platform: NodeJS.Platform;
+    arch: NodeJS.Architecture;
+    logicalCpus: number;
+    availableParallelism: number;
+    totalMemoryBytes: number;
+    freeMemoryBytes: number;
+    heapLimitBytes: number;
+    nodeVersion: string;
+    httpEmbeddingsConfigured: boolean;
+}
+export interface AdaptiveAnalyzePlan {
+    requestedProfile: AnalyzeProfileOption;
+    profile: ResolvedAnalyzeProfile;
+    machine: MachineSnapshot;
+    compress: ContentEncoding;
+    embeddingMode: EmbeddingMode;
+    embeddingNodeLimit: number;
+    workerPoolSize: number;
+    workerSubBatchSize: number;
+    reasons: string[];
+}
+export interface EmbeddingDecision {
+    enabled: boolean;
+    reason: string;
+    limit: number;
+}
+export declare const parseAnalyzeProfile: (value?: string) => AnalyzeProfileOption;
+export declare const parseEmbeddingMode: (value?: string) => EmbeddingMode;
+export declare const parseCompressionOption: (value?: string) => CompressionOption;
+export declare const detectMachineSnapshot: () => MachineSnapshot;
+export declare const resolveAnalyzeProfile: (requested: AnalyzeProfileOption, machine: MachineSnapshot) => ResolvedAnalyzeProfile;
+export declare const resolveEmbeddingMode: (embeddingsFlag: boolean | undefined, requestedMode: string | undefined) => EmbeddingMode;
+export declare const resolveCompression: (requested: CompressionOption, profile: ResolvedAnalyzeProfile, existingMeta?: Pick<RepoMeta, "compress"> | null) => ContentEncoding;
+export declare const embeddingLimitForProfile: (profile: ResolvedAnalyzeProfile, httpEmbeddingsConfigured: boolean) => number;
+export declare const workerPlanForProfile: (profile: ResolvedAnalyzeProfile, machine: Pick<MachineSnapshot, "availableParallelism">) => Pick<AdaptiveAnalyzePlan, "workerPoolSize" | "workerSubBatchSize">;
+export declare const resolveAdaptiveAnalyzePlan: (input: {
+    profile?: string;
+    embeddingMode?: string;
+    embeddings?: boolean;
+    compress?: string;
+    existingMeta?: Pick<RepoMeta, "compress"> | null;
+    machine?: MachineSnapshot;
+}) => AdaptiveAnalyzePlan;
+export declare const decideEmbeddingRun: (plan: Pick<AdaptiveAnalyzePlan, "embeddingMode" | "embeddingNodeLimit" | "profile" | "machine">, stats?: Pick<NonNullable<RepoMeta["stats"]>, "nodes" | "embeddings">) => EmbeddingDecision;
+export declare const formatAdaptiveAnalyzePlan: (plan: AdaptiveAnalyzePlan) => string;

package/dist/core/adaptive-profile.js

@@ -0,0 +1,180 @@
+import os from 'node:os';
+import v8 from 'node:v8';
+const GIB = 1024 * 1024 * 1024;
+const validProfiles = new Set(['auto', 'lean', 'balanced', 'power']);
+const validEmbeddingModes = new Set(['auto', 'off', 'on']);
+const validCompressionOptions = new Set(['auto', 'none', 'brotli', 'zstd']);
+const safeAvailableParallelism = () => {
+    const fn = os.availableParallelism;
+    if (typeof fn === 'function') {
+        try {
+            return Math.max(1, fn());
+        }
+        catch {
+            /* fall back to os.cpus */
+        }
+    }
+    return Math.max(1, os.cpus().length);
+};
+export const parseAnalyzeProfile = (value) => {
+    const normalized = (value ?? 'auto').toLowerCase();
+    if (validProfiles.has(normalized)) {
+        return normalized;
+    }
+    throw new Error(`profile must be one of: auto, lean, balanced, power (got: ${value})`);
+};
+export const parseEmbeddingMode = (value) => {
+    const normalized = (value ?? 'auto').toLowerCase();
+    if (validEmbeddingModes.has(normalized)) {
+        return normalized;
+    }
+    throw new Error(`embedding-mode must be one of: auto, off, on (got: ${value})`);
+};
+export const parseCompressionOption = (value) => {
+    const normalized = (value ?? 'auto').toLowerCase();
+    if (validCompressionOptions.has(normalized)) {
+        return normalized;
+    }
+    throw new Error(`compress must be one of: auto, none, brotli, zstd (got: ${value})`);
+};
+export const detectMachineSnapshot = () => ({
+    platform: process.platform,
+    arch: process.arch,
+    logicalCpus: Math.max(1, os.cpus().length),
+    availableParallelism: safeAvailableParallelism(),
+    totalMemoryBytes: os.totalmem(),
+    freeMemoryBytes: os.freemem(),
+    heapLimitBytes: v8.getHeapStatistics().heap_size_limit,
+    nodeVersion: process.version,
+    httpEmbeddingsConfigured: Boolean(process.env.CODRAGRAPH_EMBEDDING_URL && process.env.CODRAGRAPH_EMBEDDING_MODEL),
+});
+export const resolveAnalyzeProfile = (requested, machine) => {
+    if (requested !== 'auto')
+        return requested;
+    const memoryGiB = machine.totalMemoryBytes / GIB;
+    const heapGiB = machine.heapLimitBytes / GIB;
+    const parallelism = machine.availableParallelism;
+    if (parallelism >= 8 && memoryGiB >= 24 && heapGiB >= 6)
+        return 'power';
+    if (parallelism >= 4 && memoryGiB >= 8 && heapGiB >= 3)
+        return 'balanced';
+    return 'lean';
+};
+export const resolveEmbeddingMode = (embeddingsFlag, requestedMode) => {
+    if (embeddingsFlag === true)
+        return 'on';
+    return parseEmbeddingMode(requestedMode);
+};
+export const resolveCompression = (requested, profile, existingMeta) => {
+    if (requested !== 'auto')
+        return requested;
+    if (existingMeta)
+        return existingMeta.compress ?? 'none';
+    // Lean machines optimize for index footprint and lower read amplification.
+    // Balanced/power machines keep full body BM25 by default for maximum recall.
+    return profile === 'lean' ? 'brotli' : 'none';
+};
+export const embeddingLimitForProfile = (profile, httpEmbeddingsConfigured) => {
+    if (httpEmbeddingsConfigured)
+        return profile === 'lean' ? 25_000 : 150_000;
+    if (profile === 'power')
+        return 100_000;
+    if (profile === 'balanced')
+        return 35_000;
+    return 8_000;
+};
+export const workerPlanForProfile = (profile, machine) => {
+    const spare = Math.max(1, machine.availableParallelism - 1);
+    if (profile === 'power') {
+        return { workerPoolSize: Math.min(8, spare), workerSubBatchSize: 250 };
+    }
+    if (profile === 'balanced') {
+        return { workerPoolSize: Math.min(4, spare), workerSubBatchSize: 160 };
+    }
+    return { workerPoolSize: 1, workerSubBatchSize: 80 };
+};
+export const resolveAdaptiveAnalyzePlan = (input) => {
+    const machine = input.machine ?? detectMachineSnapshot();
+    const requestedProfile = parseAnalyzeProfile(input.profile);
+    const profile = resolveAnalyzeProfile(requestedProfile, machine);
+    const embeddingMode = resolveEmbeddingMode(input.embeddings, input.embeddingMode);
+    const compress = resolveCompression(parseCompressionOption(input.compress), profile, input.existingMeta);
+    const workerPlan = workerPlanForProfile(profile, machine);
+    const embeddingNodeLimit = embeddingLimitForProfile(profile, machine.httpEmbeddingsConfigured);
+    const reasons = [
+        `${machine.platform}/${machine.arch}`,
+        `${machine.availableParallelism} parallel slot(s)`,
+        `${(machine.totalMemoryBytes / GIB).toFixed(1)} GiB RAM`,
+        `${(machine.heapLimitBytes / GIB).toFixed(1)} GiB heap`,
+    ];
+    if (machine.httpEmbeddingsConfigured)
+        reasons.push('HTTP embeddings configured');
+    return {
+        requestedProfile,
+        profile,
+        machine,
+        compress,
+        embeddingMode,
+        embeddingNodeLimit,
+        workerPoolSize: workerPlan.workerPoolSize,
+        workerSubBatchSize: workerPlan.workerSubBatchSize,
+        reasons,
+    };
+};
+export const decideEmbeddingRun = (plan, stats) => {
+    const nodes = stats?.nodes;
+    const existingEmbeddings = stats?.embeddings ?? 0;
+    const overLimit = typeof nodes === 'number' && nodes > plan.embeddingNodeLimit;
+    if (plan.embeddingMode === 'off') {
+        return { enabled: false, reason: 'embedding-mode is off', limit: plan.embeddingNodeLimit };
+    }
+    if (overLimit) {
+        return {
+            enabled: false,
+            reason: `${nodes.toLocaleString('en-US')} nodes exceeds ${plan.profile} embedding limit ${plan.embeddingNodeLimit.toLocaleString('en-US')}`,
+            limit: plan.embeddingNodeLimit,
+        };
+    }
+    if (plan.embeddingMode === 'on') {
+        return { enabled: true, reason: 'explicit embedding request', limit: plan.embeddingNodeLimit };
+    }
+    if (existingEmbeddings > 0) {
+        return {
+            enabled: true,
+            reason: 'preserving existing embeddings',
+            limit: plan.embeddingNodeLimit,
+        };
+    }
+    if (plan.machine.httpEmbeddingsConfigured) {
+        return {
+            enabled: true,
+            reason: 'HTTP embedding endpoint configured',
+            limit: plan.embeddingNodeLimit,
+        };
+    }
+    if (plan.profile === 'power') {
+        return {
+            enabled: true,
+            reason: 'power profile can run local embeddings',
+            limit: plan.embeddingNodeLimit,
+        };
+    }
+    if (plan.profile === 'balanced' && (nodes ?? Number.POSITIVE_INFINITY) <= 5_000) {
+        return {
+            enabled: true,
+            reason: 'small repo on balanced profile',
+            limit: plan.embeddingNodeLimit,
+        };
+    }
+    if (plan.profile === 'lean' && (nodes ?? Number.POSITIVE_INFINITY) <= 1_000) {
+        return { enabled: true, reason: 'small repo on lean profile', limit: plan.embeddingNodeLimit };
+    }
+    return {
+        enabled: false,
+        reason: 'auto mode skipped first-time local embeddings on this profile',
+        limit: plan.embeddingNodeLimit,
+    };
+};
+export const formatAdaptiveAnalyzePlan = (plan) => `Adaptive analyze: ${plan.profile} profile (${plan.reasons.join(', ')}); ` +
+    `workers=${plan.workerPoolSize}, subBatch=${plan.workerSubBatchSize}, ` +
+    `compress=${plan.compress}, embeddings=${plan.embeddingMode}.`;

package/dist/core/cgdb/cgdb-adapter.d.ts

@@ -60,6 +60,37 @@ export declare const loadGraphToCgdb: (graph: KnowledgeGraph, repoPath: string,
     skippedRels: number;
     warnings: string[];
 }>;
+export interface FileGraphPatchResult {
+    replacedFiles: number;
+    deletedNodeIds: number;
+    insertedRels: number;
+    restoredRels: number;
+    prunedFolders: number;
+}
+export interface FileGraphPatchOptions {
+    compress?: ContentEncoding;
+    /** Map old relative paths to their new relative paths for rename remapping. */
+    pathAliases?: ReadonlyMap<string, string> | Record<string, string>;
+}
+export interface FileGraphReplacementResult {
+    deletedNodes: number;
+    insertedRels: number;
+}
+export interface GlobalGraphLayerReplaceResult {
+    deletedGlobalNodes: number;
+    insertedRels: number;
+}
+export interface LoadKnowledgeGraphFromCgdbOptions {
+    includeGlobal?: boolean;
+}
+export declare const applyFileGraphPatchToCgdb: (graph: KnowledgeGraph, repoPath: string, storagePath: string, filePaths: readonly string[], onProgress?: CgdbProgressCallback, options?: FileGraphPatchOptions) => Promise<FileGraphPatchResult>;
+export declare const replaceFileScopedGraphInCgdb: (graph: KnowledgeGraph, repoPath: string, storagePath: string, onProgress?: CgdbProgressCallback, options?: {
+    compress?: ContentEncoding;
+}) => Promise<FileGraphReplacementResult>;
+export declare const replaceGlobalGraphLayersInCgdb: (graph: KnowledgeGraph, repoPath: string, storagePath: string, onProgress?: CgdbProgressCallback, options?: {
+    compress?: ContentEncoding;
+}) => Promise<GlobalGraphLayerReplaceResult>;
+export declare const loadKnowledgeGraphFromCgdb: (options?: LoadKnowledgeGraphFromCgdbOptions) => Promise<KnowledgeGraph>;
 /**
  * Insert a single node to LadybugDB
  * @param label - Node type (File, Function, Class, etc.)
@@ -143,12 +174,10 @@ export declare const loadVectorExtension: () => Promise<void>;
  */
 export declare const createFTSIndex: (tableName: string, indexName: string, properties: string[], stemmer?: string) => Promise<void>;
 /**
- * Lazy-create an FTS index, caching the fact in-process.
+ * Create an FTS index if needed, caching the fact in-process.
  *
- * Used by `queryFTS` so that `analyze` doesn't pay the ~440 ms × 5 fixed
- * LadybugDB cost up-front (it dominates analyze on small repos). Instead,
- * the cost is moved to the first `query`/`context` call in a session,
- * where it's amortised across many lookups.
+ * Used by analyze to warm persisted keyword indexes while the DB is writable,
+ * and by direct core search as a defensive fallback for older indexes.
  *
  * Safe to call repeatedly — the in-process Set guarantees only the first
  * call hits LadybugDB. `closeCgdb` clears the cache so re-init starts fresh.