gitnexus 1.6.12-rc.2 → 1.6.12-rc.21

package/dist/server/analyze-launch.js

@@ -15,6 +15,7 @@ import { fork } from 'child_process';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { createRequire } from 'node:module';
 import { canonicalizePath, getStoragePath, INDEX_METADATA_FILE, listRegisteredRepos, registryPathEquals, } from '../storage/repo-manager.js';
+import { BRANCHES_DIR, branchSlug } from '../storage/branch-index.js';
 import { logger } from '../core/logger.js';
 import { autoHeapCapMb } from '../core/ingestion/utils/effective-ram.js';
 import { isTerminalJobStatus } from './analyze-job.js';
@@ -32,17 +33,6 @@ const MAX_WORKER_RETRIES = 2;
  */
 const FINALIZE_SETTLE_TIMEOUT_MS = 60_000;
 const FINALIZE_SETTLE_POLL_MS = 200;
-/**
- * Resolve once the analyzed repo's index is settled at `storagePath`: the
- * LadybugDB file and metadata both exist AND were (re)written by THIS job
- * (mtime >= jobStartMs — bare existence is not enough, a re-analysis leaves
- * the previous index in place while it works), and no transient WAL/shadow/
- * checkpoint sidecars remain (the worker's native close has finished).
- *
- * Never rejects. Timing out logs and proceeds (pre-gate behavior) rather
- * than failing a job whose analysis genuinely succeeded — e.g. a no-op
- * non-force analyze legitimately rewrites nothing.
- */
 /**
  * Look up the analyzed repo's registered storage path. The request's
  * user-provided path is used only as a comparison key; the filesystem probes
@@ -56,7 +46,36 @@ const registeredStoragePath = async (targetPath) => {
     const entry = entries.find((e) => registryPathEquals(canonicalizePath(e.path), target));
     return entry?.storagePath ?? null;
 };
-const waitForSettledIndex = async (targetPath, jobStartMs) => {
+/**
+ * Resolve the directory this run's index actually landed in.
+ *
+ * `registerRepo` always records the FLAT `.gitnexus` as `entry.storagePath`,
+ * but a pinned `--branch` run whose label differs from the flat slot's owner
+ * writes `lbug`/`gitnexus.json` under `branches/<slug>/` instead. Probing the
+ * flat path for such a run watches files it never rewrote, so the gate below
+ * would spin to its timeout on a perfectly successful analysis (#3199 review).
+ *
+ * `isPrimaryBranch` is the worker's own report of `!placement.branch`, so this
+ * follows the placement core actually chose rather than recomputing it here
+ * (the flat slot's recorded owner can be adopted mid-run, which would make a
+ * recomputation race the thing it is trying to observe).
+ */
+const settleDirFor = (registryStoragePath, branch, isPrimaryBranch) => branch && isPrimaryBranch === false
+    ? path.join(registryStoragePath, BRANCHES_DIR, branchSlug(branch))
+    : registryStoragePath;
+/**
+ * Resolve once the analyzed repo's index is settled at `storagePath`: the
+ * LadybugDB file and metadata both exist AND were (re)written by THIS job
+ * (mtime >= jobStartMs — bare existence is not enough, a re-analysis leaves
+ * the previous index in place while it works), and no transient WAL/shadow/
+ * checkpoint sidecars remain (the worker's native close has finished).
+ *
+ * Never rejects. Timing out logs and proceeds (pre-gate behavior) rather
+ * than failing a job whose analysis genuinely succeeded. The `alreadyUpToDate`
+ * fast path never rewrites `lbug` (see `run-analyze.ts`) and skips this wait
+ * at the `complete` handler so it does not hold the analyze slot for 60s.
+ */
+const waitForSettledIndex = async (targetPath, jobStartMs, branch, isPrimaryBranch) => {
     const settled = (storagePath) => {
         try {
             const lbugStat = statSync(path.join(storagePath, 'lbug'));
@@ -74,7 +93,7 @@ const waitForSettledIndex = async (targetPath, jobStartMs) => {
         // Re-resolved each round: the worker registers the repo as part of the
         // finalization this gate is waiting out.
         const storagePath = await registeredStoragePath(targetPath);
-        if (storagePath && settled(storagePath))
+        if (storagePath && settled(settleDirFor(storagePath, branch, isPrimaryBranch)))
             return;
         if (Date.now() > deadline) {
             logger.warn({ targetPath }, 'analyze finalization not visible after timeout; completing job anyway');
@@ -121,6 +140,13 @@ export function createLaunchAnalysisWorker(deps) {
             });
             // Capture stderr for crash diagnostics
             let stderrChunks = '';
+            // A terminal IPC message (`complete`/`error`) means the worker finished
+            // and is now winding down — it calls process.exit(0) ~500ms later. The
+            // job is deliberately still non-terminal at that point because the
+            // finalization gate is running, so without this flag the exit handler
+            // below reads that clean exit as a crash and retries a SUCCESSFUL
+            // analysis, three times, before failing it (#3199 review).
+            let terminalIpcSeen = false;
             child.stderr?.on('data', (chunk) => {
                 stderrChunks += chunk.toString();
                 if (stderrChunks.length > 4096)
@@ -134,6 +160,8 @@ export function createLaunchAnalysisWorker(deps) {
                 const current = jobManager.getJob(job.id);
                 if (!current || isTerminalJobStatus(current.status))
                     return;
+                if (msg.type === 'complete' || msg.type === 'error')
+                    terminalIpcSeen = true;
                 if (msg.type === 'progress') {
                     jobManager.updateJob(job.id, {
                         status: 'analyzing',
@@ -151,7 +179,16 @@ export function createLaunchAnalysisWorker(deps) {
                     // below true in practice: the repo is actually queryable when the
                     // client receives the SSE complete event, and an index this run knows
                     // to be incomplete is never published at all.
-                    waitForSettledIndex(targetPath, jobStartMs)
+                    //
+                    // alreadyUpToDate never opens LadybugDB and never rewrites `lbug`
+                    // (run-analyze.ts early-return; CLI notes the same). The mtime gate
+                    // would spin the full 60s and hold the single global analyze slot.
+                    // ftsRepairedOnly DOES rewrite `lbug` (initLbug + createSearchFTSIndexes)
+                    // so it still waits.
+                    const settle = msg.result.alreadyUpToDate
+                        ? Promise.resolve()
+                        : waitForSettledIndex(targetPath, jobStartMs, opts.branch, msg.result.isPrimaryBranch);
+                    settle
                         .then(() => closeDbHandle())
                         .catch(() => { }) // best-effort: eviction failure must not fail the job
                         .then(() => {
@@ -243,6 +280,13 @@ export function createLaunchAnalysisWorker(deps) {
                 const j = jobManager.getJob(job.id);
                 if (!j || isTerminalJobStatus(j.status))
                     return;
+                // The worker already reported a terminal outcome; this exit is it
+                // winding down, not dying. The job is still non-terminal only because
+                // the finalization gate above has not resolved yet, and that gate owns
+                // the outcome — retrying here would fork a second worker over a
+                // finished, successful analysis.
+                if (terminalIpcSeen)
+                    return;
                 // Worker crashed — attempt retry if under the limit
                 if (j.retryCount < MAX_WORKER_RETRIES) {
                     j.retryCount++;
@@ -283,6 +327,7 @@ export function createLaunchAnalysisWorker(deps) {
                     ...(opts.springActuatorPath ? { springActuatorPath: opts.springActuatorPath } : {}),
                     ...(opts.asyncApiSpecPath ? { asyncApiSpecPath: opts.asyncApiSpecPath } : {}),
                     ...(opts.registryName ? { registryName: opts.registryName } : {}),
+                    ...(opts.branch ? { branch: opts.branch } : {}),
                 },
             });
         };

package/dist/server/analyze-worker-ipc.d.ts

@@ -43,12 +43,13 @@ import type { AnalyzeResult } from '../core/run-analyze.js';
  * ones (e.g. `isPrimaryBranch?`), so an optional non-serializable field could be
  * advertised by the type yet silently dropped by the runtime allowlist.
  *
- * `isPrimaryBranch` is intentionally excluded: the parent (`api.ts`) reads only
- * `repoName`, and nothing consumes `isPrimaryBranch` across this fork (its CLI
- * consumer calls `runFullAnalysis` in-process). Add a field here only when a
- * server-side IPC consumer actually needs it — and only if it is JSON-safe.
+ * `isPrimaryBranch` IS on the wire, under exactly the rule this comment used to
+ * cite for excluding it: a server-side consumer now needs it. `analyze-launch.ts`
+ * settles the index the run actually wrote, and only the worker knows whether
+ * core chose the flat slot or a `branches/<slug>/` sub-slot. It is a boolean, so
+ * it is JSON-safe by construction.
  */
-export type AnalyzeResultIpc = Pick<AnalyzeResult, 'repoName' | 'repoPath' | 'stats' | 'alreadyUpToDate' | 'ftsRepairedOnly' | 'ftsSkipped' | 'graphWriteCollapsed'>;
+export type AnalyzeResultIpc = Pick<AnalyzeResult, 'repoName' | 'repoPath' | 'stats' | 'alreadyUpToDate' | 'ftsRepairedOnly' | 'ftsSkipped' | 'graphWriteCollapsed' | 'isPrimaryBranch'>;
 /**
  * Project an `AnalyzeResult` down to the JSON-safe fields the parent consumes,
  * dropping `pipelineResult` (the live `KnowledgeGraph`) and any other field not

package/dist/server/analyze-worker-ipc.js

@@ -16,5 +16,9 @@ export function projectAnalyzeResultForIpc(result) {
         // outcome the CLI does; without it the worker reports a clean `complete`
         // for a run whose edges are mostly missing.
         graphWriteCollapsed: result.graphWriteCollapsed,
+        // Tells the parent which slot this run wrote — the flat `.gitnexus` or a
+        // `branches/<slug>/` sub-slot — so its finalization gate watches the files
+        // this job actually rewrote (#3199 review).
+        isPrimaryBranch: result.isPrimaryBranch,
     };
 }

package/dist/server/api.js

@@ -29,8 +29,14 @@ import { measurePersistedEmbeddingCount, persistedEmbeddingCountOrUndefined, } f
 import { assertString, BadRequestError, createRouteLimiter } from './validation.js';
 import { parseGrepQuery, GREP_TIME_BUDGET_MS } from './grep-params.js';
 import { runGrepScanInWorker } from './grep-scan.js';
-import { extractWebRepoName, getCloneDir, cloneOrPull, warnIfInsecureAzureConfig, GITHUB_TOKEN_HOSTS, } from './git-clone.js';
+import { analyzeCloneOptions, extractWebRepoName, getCloneDir, cloneOrPull, warnIfInsecureAzureConfig, GITHUB_TOKEN_HOSTS, } from './git-clone.js';
 import { createAnalyzeUploadHandler } from './analyze-upload.js';
+import { checkStalenessAsync } from '../core/git-staleness.js';
+import { projectRepoDetail, projectRepoListEntry, resolveLastCommit } from './repo-projection.js';
+// Shared with the CLI's `--branch` (via the analyze-config wrapper) so both
+// entry points accept the same refs. Imported from core — not cli/ — so
+// createServer does not close a cycle with cli/serve.ts.
+import { InvalidBranchError, validateBranchName } from '../core/git-ref.js';
 import { assertServeAuthForPublicOrigin, createPublicOriginMatcher, createWriteOriginGuard, logOriginPolicy, PUBLIC_ORIGIN_ENV, resolveTrustProxy, TRUST_PROXY_ENV, warnIfRateLimitKeysCollapse, } from './middleware.js';
 import { createLaunchAnalysisWorker } from './analyze-launch.js';
 import { UPLOAD_ROOT } from './upload-paths.js';
@@ -805,17 +811,19 @@ export const createServer = async (port, host = '127.0.0.1') => {
         res.json(buildServerInfo(updateController.snapshot()));
     });
     // List all registered repos
-    app.get('/api/repos', async (_req, res) => {
+    // Rate-limited (CodeQL js/missing-rate-limiting) because this route now spawns
+    // one `git rev-list` per registered repo to answer freshness: an unauthenticated
+    // GET that costs N subprocesses is worth the same 60 rpm/IP ceiling `/api/repo`
+    // already carries. Web callers hit this on connect/switch, never in a loop.
+    app.get('/api/repos', createRouteLimiter(), async (_req, res) => {
         try {
             const repos = await listRegisteredRepos();
-            res.json(repos.map((r) => ({
-                name: r.name,
-                path: r.path,
-                repoPath: r.path,
-                indexedAt: r.indexedAt,
-                lastCommit: r.lastCommit,
-                stats: r.stats,
-            })));
+            // Checked in parallel, for the reason `list_repos` already does it that
+            // way: each check spawns an async `git rev-list`, and the sequential
+            // variant took ~50s across 200 repos (#1363). Projecting inside the map
+            // keeps the entry and its own check together — an index-matched second
+            // array is the shape that silently mispairs them if either is reordered.
+            res.json(await Promise.all(repos.map(async (r) => projectRepoListEntry(r, await checkStalenessAsync(r.path, r.lastCommit)))));
         }
         catch (err) {
             res.status(500).json({ error: err.message || 'Failed to list repos' });
@@ -841,12 +849,8 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 return;
             }
             const meta = await loadMeta(entry.storagePath);
-            res.json({
-                name: entry.name,
-                repoPath: entry.path,
-                indexedAt: meta?.indexedAt ?? entry.indexedAt,
-                stats: meta?.stats ?? entry.stats ?? {},
-            });
+            const staleness = await checkStalenessAsync(entry.path, resolveLastCommit(entry, meta));
+            res.json(projectRepoDetail(entry, meta, staleness));
         }
         catch (err) {
             res.status(500).json({ error: err.message || 'Failed to get repo info' });
@@ -1264,7 +1268,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
     // POST /api/analyze — start a new analysis job
     app.post('/api/analyze', createRouteLimiter({ limit: 10 }), requireTrustedOrigin, async (req, res) => {
         try {
-            const { url: repoUrl, path: repoLocalPath, force, embeddings, dropEmbeddings, springActuatorPath, asyncApiSpecPath, token: repoToken, } = req.body;
+            const { url: repoUrl, path: repoLocalPath, force, embeddings, dropEmbeddings, springActuatorPath, asyncApiSpecPath, token: repoToken, branch: repoBranch, } = req.body;
             // Input type validation
             if (repoUrl !== undefined && typeof repoUrl !== 'string') {
                 res.status(400).json({ error: '"url" must be a string' });
@@ -1288,6 +1292,27 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.status(400).json({ error: 'Provide "url" (git URL) or "path" (local path)' });
                 return;
             }
+            // Branch: optional index-branch selector, validated with the same rules
+            // as the CLI's `--branch` so both entry points accept the same refs.
+            // Rejecting here (rather than letting the clone fail) keeps a malformed
+            // ref from ever reaching `git`.
+            if (repoBranch !== undefined && typeof repoBranch !== 'string') {
+                res.status(400).json({ error: '"branch" must be a string' });
+                return;
+            }
+            let analyzeBranch;
+            if (repoBranch !== undefined) {
+                try {
+                    analyzeBranch = validateBranchName(repoBranch, '"branch"');
+                }
+                catch (err) {
+                    if (err instanceof InvalidBranchError) {
+                        res.status(400).json({ error: err.message });
+                        return;
+                    }
+                    throw err;
+                }
+            }
             // Token: optional, restricted charset to prevent header smuggling
             // (CRLF), bound length, and bound to github.com (see validateAnalyzeToken).
             const tokenError = validateAnalyzeToken(repoToken, repoUrl);
@@ -1311,7 +1336,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.status(400).json({ error: '"path" must be an absolute path' });
                 return;
             }
-            const job = jobManager.createJob({ repoUrl, repoPath: repoLocalPath });
+            const job = jobManager.createJob({
+                repoUrl,
+                repoPath: repoLocalPath,
+                branch: analyzeBranch,
+            });
             // If job was already running (dedup), just return its id. The token is
             // not part of the dedup identity and is never stored on the job, so a
             // token on THIS request had no effect — the existing job already
@@ -1337,17 +1366,21 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     // Clone if URL provided
                     if (repoUrl && !repoLocalPath) {
                         const repoName = extractWebRepoName(repoUrl);
-                        targetPath = getCloneDir(repoName);
+                        // Branch-pinned runs get their own clone dir, so they never share
+                        // a working tree with the unpinned one (see getCloneDir).
+                        targetPath = getCloneDir(repoName, analyzeBranch);
                         jobManager.updateJob(job.id, {
                             status: 'cloning',
-                            repoName,
+                            // url+branch: same value as registryName (dir basename), not
+                            // the extractWebRepoName stem used only as getCloneDir's first arg.
+                            repoName: analyzeBranch ? path.basename(targetPath) : repoName,
                             progress: { phase: 'cloning', percent: 0, message: `Cloning ${repoUrl}...` },
                         });
                         await cloneOrPull(repoUrl, targetPath, (progress) => {
                             jobManager.updateJob(job.id, {
                                 progress: { phase: progress.phase, percent: 5, message: progress.message },
                             });
-                        }, repoToken ? { token: repoToken } : undefined);
+                        }, analyzeCloneOptions(repoToken, analyzeBranch));
                     }
                     if (!targetPath) {
                         throw new Error('No target path resolved');
@@ -1358,6 +1391,20 @@ export const createServer = async (port, host = '127.0.0.1') => {
                         dropEmbeddings,
                         springActuatorPath,
                         asyncApiSpecPath,
+                        branch: analyzeBranch,
+                        // Both clone dirs share an `origin`, so the name `registerRepo`
+                        // infers from the remote would be identical and the second one
+                        // would fail with RegistryNameCollisionError. Register the pinned
+                        // clone under its directory name instead: unique per branch, and
+                        // it re-derives through getCloneDir for DELETE /api/repo.
+                        //
+                        // Gated on the SAME condition as the clone above: when a caller
+                        // supplies both `url` and `path` nothing is cloned, and renaming
+                        // the operator's own local repo after its directory would be a
+                        // surprise unrelated to branch pinning.
+                        ...(analyzeBranch && repoUrl && !repoLocalPath
+                            ? { registryName: path.basename(targetPath) }
+                            : {}),
                     });
                 }
                 catch (err) {

package/dist/server/git-clone.d.ts

@@ -25,12 +25,25 @@ export declare function extractRepoName(url: string): string;
  * `extractRepoName()` strict for internal/security-sensitive callers.
  */
 export declare function extractWebRepoName(url: string): string;
-/** Get the clone target directory for a repo name. */
-export declare function getCloneDir(repoName: string): string;
+/** Get the clone target directory for a repo name, optionally pinned to a branch. */
+export declare function getCloneDir(repoName: string, branch?: string): string;
 export interface CloneProgress {
     phase: 'cloning' | 'pulling';
     message: string;
 }
+/**
+ * Build the `cloneOrPull` options for an `/api/analyze` request.
+ *
+ * Extracted from the route so the token/branch combination is unit-testable.
+ * Inline, the branch-only case was the one nothing asserted: every existing
+ * test still passed if `branch` were dropped whenever no token was supplied —
+ * i.e. silently cloning the default branch for every public URL, which is the
+ * exact behavior #3198 is about (#3199 review).
+ *
+ * Returns `undefined` rather than `{}` when neither is set, because that is
+ * what `cloneOrPull` treats as "no options" at its own call sites.
+ */
+export declare function analyzeCloneOptions(token?: string, branch?: string): Pick<CloneOrPullOptions, 'token' | 'branch'> | undefined;
 export interface CloneOrPullOptions {
     token?: string;
     allowedCloneRoot?: string;
@@ -119,9 +132,29 @@ export declare function getRemoteOriginUrl(cwd: string, timeoutMs?: number): Pro
 export declare function assertRemoteMatchesRequestedUrl(targetDir: string, requestedUrl: string, timeoutMs?: number): Promise<void>;
 /**
  * Clone or pull a git repository.
- * If targetDir doesn't exist: git clone --depth 1
- * If targetDir exists with .git: git pull --ff-only (after verifying the
- * existing clone's remote.origin matches the requested URL).
+ *
+ * If targetDir doesn't exist: git clone --depth 1, adding `--branch <branch>`
+ * when one is requested.
+ *
+ * If targetDir exists with .git, its remote.origin is verified against the
+ * requested URL first, and then the branch decides the update:
+ *   - no `options.branch`: git pull --ff-only, which updates the current
+ *     branch in place via its configured upstream. Nothing moves, so no
+ *     dirty-tree check applies.
+ *   - a `options.branch` that is ALREADY the current named branch: restore
+ *     GitNexus overlays, then fetch via
+ *     `+refs/heads/<branch>:refs/remotes/origin/<branch>` and
+ *     `checkout -B <branch> origin/<branch>` (shallow clones cannot
+ *     `merge --ff-only` across a 2+ commit move). Never a raw
+ *     `origin <branch>` pull refspec. No porcelain refuse.
+ *   - a detached HEAD whose SHA already matches the requested ref (tag /
+ *     SHA pin): restore overlays only. Do not fetch/merge — a same-named
+ *     branch could otherwise fast-forward the pin past the tag.
+ *   - a `options.branch` that DIFFERS from the current pin: fetch that ref,
+ *     then `checkout -B <branch> origin/<branch>` — so the requested branch,
+ *     not the one already checked out, is what ends up in the working tree.
+ *     This is the switching case, and it refuses a dirty tree unless
+ *     `overwriteLocalChanges` is set.
  *
  * Security:
  *   - targetDir must resolve inside CLONE_ROOT (~/.gitnexus/repos/). The