gitnexus 1.6.3-rc.46 → 1.6.3-rc.48

package/dist/cli/analyze.d.ts

@@ -10,6 +10,12 @@
 export interface AnalyzeOptions {
     force?: boolean;
     embeddings?: boolean;
+    /**
+     * Explicitly drop existing embeddings on rebuild instead of preserving
+     * them. Without this flag, a routine `analyze` keeps any embeddings
+     * already present in the index even when `--embeddings` is omitted.
+     */
+    dropEmbeddings?: boolean;
     skills?: boolean;
     verbose?: boolean;
     /** Skip AGENTS.md and CLAUDE.md gitnexus block updates. */

package/dist/cli/analyze.js

@@ -159,6 +159,7 @@ export const analyzeCommand = async (inputPath, options) => {
             // collision guard (see allowDuplicateName below).
             force: options?.force || options?.skills,
             embeddings: options?.embeddings,
+            dropEmbeddings: options?.dropEmbeddings,
             skipGit: options?.skipGit,
             skipAgentsMd: options?.skipAgentsMd,
             noStats: options?.noStats,

package/dist/cli/index.js

@@ -18,6 +18,8 @@ program
     .description('Index a repository (full analysis)')
     .option('-f, --force', 'Force full re-index even if up to date')
     .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
+    .option('--drop-embeddings', 'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` ' +
+    'preserves any embeddings already present in the index.')
     .option('--skills', 'Generate repo-specific skill files from detected communities')
     .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
     .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')

package/dist/core/embedding-mode.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure derivation of the embedding-mode flags for `runFullAnalysis`.
+ *
+ * Lives in its own module (no native imports) so the branching contract can
+ * be unit-tested without spinning up LadybugDB, tree-sitter, or any of the
+ * other side-effecting dependencies pulled in by `run-analyze.ts`.
+ *
+ * Semantics:
+ *   --drop-embeddings         -> wipe (skip cache load entirely)
+ *   --embeddings              -> load cache, restore, then generate
+ *   --force + existing>0      -> load cache, restore, then generate (regenerate top-up)
+ *   (default) + existing>0    -> preserve only (load + restore, no generation)
+ *   any path with existing=0  -> no cache work, no preservation
+ */
+export interface EmbeddingModeInput {
+    force?: boolean;
+    embeddings?: boolean;
+    dropEmbeddings?: boolean;
+}
+export interface EmbeddingMode {
+    /** True when phase 4 should run the embedding generation pipeline. */
+    shouldGenerateEmbeddings: boolean;
+    /** True when we should load the cache to re-insert vectors after rebuild without generating new ones. */
+    preserveExistingEmbeddings: boolean;
+    /** True when `--force` upgraded a default analyze into a regeneration because the repo was already embedded. */
+    forceRegenerateEmbeddings: boolean;
+    /** True when we need to load cached embeddings from the existing DB before the rebuild. */
+    shouldLoadCache: boolean;
+}
+export declare function deriveEmbeddingMode(options: EmbeddingModeInput, existingEmbeddingCount: number): EmbeddingMode;

package/dist/core/embedding-mode.js

@@ -0,0 +1,30 @@
+/**
+ * Pure derivation of the embedding-mode flags for `runFullAnalysis`.
+ *
+ * Lives in its own module (no native imports) so the branching contract can
+ * be unit-tested without spinning up LadybugDB, tree-sitter, or any of the
+ * other side-effecting dependencies pulled in by `run-analyze.ts`.
+ *
+ * Semantics:
+ *   --drop-embeddings         -> wipe (skip cache load entirely)
+ *   --embeddings              -> load cache, restore, then generate
+ *   --force + existing>0      -> load cache, restore, then generate (regenerate top-up)
+ *   (default) + existing>0    -> preserve only (load + restore, no generation)
+ *   any path with existing=0  -> no cache work, no preservation
+ */
+export function deriveEmbeddingMode(options, existingEmbeddingCount) {
+    const hasExisting = existingEmbeddingCount > 0;
+    const drop = !!options.dropEmbeddings;
+    const explicit = !!options.embeddings;
+    const force = !!options.force;
+    const forceRegenerateEmbeddings = force && !explicit && !drop && hasExisting;
+    const preserveExistingEmbeddings = !explicit && !drop && !forceRegenerateEmbeddings && hasExisting;
+    const shouldGenerateEmbeddings = explicit || forceRegenerateEmbeddings;
+    const shouldLoadCache = !drop && (shouldGenerateEmbeddings || preserveExistingEmbeddings);
+    return {
+        shouldGenerateEmbeddings,
+        preserveExistingEmbeddings,
+        forceRegenerateEmbeddings,
+        shouldLoadCache,
+    };
+}

package/dist/core/run-analyze.d.ts

@@ -21,6 +21,15 @@ export interface AnalyzeOptions {
      */
     force?: boolean;
     embeddings?: boolean;
+    /**
+     * Explicitly drop any embeddings present in the existing index instead of
+     * preserving them. Only meaningful when `embeddings` is false/undefined:
+     * the default behavior in that case is to load the previously generated
+     * embeddings and re-insert them after the rebuild so a routine
+     * re-analyze does not silently wipe a long embedding pass (#issue: analyze
+     * silently wipes existing embeddings when run without --embeddings).
+     */
+    dropEmbeddings?: boolean;
     skipGit?: boolean;
     /** Skip AGENTS.md and CLAUDE.md gitnexus block updates. */
     skipAgentsMd?: boolean;
@@ -57,6 +66,8 @@ export interface AnalyzeResult {
     /** The raw pipeline result — only populated when needed by callers (e.g. skill generation). */
     pipelineResult?: any;
 }
+export { deriveEmbeddingMode } from './embedding-mode.js';
+export type { EmbeddingMode } from './embedding-mode.js';
 export declare const PHASE_LABELS: Record<string, string>;
 /**
  * Run the full GitNexus analysis pipeline.

package/dist/core/run-analyze.js

@@ -19,6 +19,10 @@ import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
 import { STALE_HASH_SENTINEL } from './lbug/schema.js';
 /** Threshold: auto-skip embeddings for repos with more nodes than this */
 const EMBEDDING_NODE_LIMIT = 50_000;
+// Re-export the pure flag-derivation helper so external callers (and tests)
+// keep importing from this module's stable surface.
+export { deriveEmbeddingMode } from './embedding-mode.js';
+import { deriveEmbeddingMode as _deriveEmbeddingMode } from './embedding-mode.js';
 export const PHASE_LABELS = {
     extracting: 'Scanning files',
     structure: 'Building structure',
@@ -73,9 +77,39 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         }
     }
     // ── Cache embeddings from existing index before rebuild ────────────
+    // Four modes:
+    //   --embeddings              -> load cache, restore, then generate any new ones
+    //   --force (with existing
+    //    embeddings)              -> auto-imply --embeddings: load cache, restore,
+    //                                regenerate embeddings for new/changed nodes
+    //                                (a forced re-index of an embedded repo
+    //                                shouldn't quietly downgrade to "preserve only")
+    //   (default)                 -> if existing index has embeddings, preserve them
+    //                                (load + restore, but do not generate); otherwise no-op
+    //   --drop-embeddings         -> skip cache load entirely; rebuild wipes embeddings
+    //
+    // The default-preserve branch is what makes a routine `analyze` (e.g. a
+    // post-commit hook) safe: a multi-minute embedding pass is no longer
+    // silently dropped just because the caller omitted `--embeddings`.
     let cachedEmbeddingNodeIds = new Set();
     let cachedEmbeddings = [];
-    if (options.embeddings && existingMeta && !options.force) {
+    const existingEmbeddingCount = existingMeta?.stats?.embeddings ?? 0;
+    const { forceRegenerateEmbeddings, preserveExistingEmbeddings, shouldGenerateEmbeddings, shouldLoadCache, } = _deriveEmbeddingMode(options, existingEmbeddingCount);
+    if (options.dropEmbeddings && existingEmbeddingCount > 0) {
+        log(`Dropping ${existingEmbeddingCount} existing embeddings (--drop-embeddings). ` +
+            `Re-run with --embeddings to regenerate.`);
+    }
+    else if (forceRegenerateEmbeddings) {
+        log(`--force on a repo with ${existingEmbeddingCount} existing embeddings: ` +
+            `regenerating embeddings for new/changed nodes. ` +
+            `Pass --drop-embeddings to wipe them instead.`);
+    }
+    else if (preserveExistingEmbeddings) {
+        log(`Preserving ${existingEmbeddingCount} existing embeddings. ` +
+            `Pass --embeddings to also generate embeddings for new/changed nodes, ` +
+            `or --drop-embeddings to wipe them.`);
+    }
+    if (shouldLoadCache && existingMeta) {
         try {
             progress('embeddings', 0, 'Caching embeddings...');
             await initLbug(lbugPath);
@@ -84,7 +118,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             cachedEmbeddings = cached.embeddings;
             await closeLbug();
         }
-        catch {
+        catch (err) {
+            // Surface cache-load failures explicitly: silently swallowing here would
+            // re-introduce the original silent-data-loss symptom (embeddings end up
+            // at 0 in meta.json with no diagnostic) through a different door.
+            log(`Warning: could not load cached embeddings ` +
+                `(${err?.message ?? String(err)}). ` +
+                `Embeddings will not be preserved on this run.`);
+            cachedEmbeddingNodeIds = new Set();
+            cachedEmbeddings = [];
             try {
                 await closeLbug();
             }
@@ -157,7 +199,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // ── Phase 4: Embeddings (90–98%) ──────────────────────────────────
         const stats = await getLbugStats();
         let embeddingSkipped = true;
-        if (options.embeddings) {
+        if (shouldGenerateEmbeddings) {
             if (stats.nodes <= EMBEDDING_NODE_LIMIT) {
                 embeddingSkipped = false;
             }

package/dist/server/api.js

@@ -1002,7 +1002,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
     // POST /api/analyze — start a new analysis job
     app.post('/api/analyze', async (req, res) => {
         try {
-            const { url: repoUrl, path: repoLocalPath, force, embeddings } = req.body;
+            const { url: repoUrl, path: repoLocalPath, force, embeddings, dropEmbeddings } = req.body;
             // Input type validation
             if (repoUrl !== undefined && typeof repoUrl !== 'string') {
                 res.status(400).json({ error: '"url" must be a string' });
@@ -1176,7 +1176,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
                         child.send({
                             type: 'start',
                             repoPath: targetPath,
-                            options: { force: !!force, embeddings: !!embeddings },
+                            options: {
+                                force: !!force,
+                                embeddings: !!embeddings,
+                                dropEmbeddings: !!dropEmbeddings,
+                            },
                         });
                     };
                     forkWorker();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.3-rc.46",
+  "version": "1.6.3-rc.48",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",

package/skills/gitnexus-cli.md

@@ -21,6 +21,7 @@ Run from the project root. This parses all source files, builds the knowledge gr
 | -------------- | ---------------------------------------------------------------- |
 | `--force`      | Force full re-index even if up to date                           |
 | `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
 
 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.