vdelta 0.1.1 → 0.2.0

package/dist/run.js

@@ -15,7 +15,7 @@ import { fileURLToPath } from 'node:url';
 import { buildRunRecord, } from './adapters/vitest/recorder.js';
 import { buildComparisonReport } from './compare.js';
 import { canonicalDigest } from './digest.js';
-import { LockHeldError, RunStore } from './store.js';
+import { defaultGcPolicy, LockHeldError, RunStore } from './store.js';
 import { dirtyDiffMaterial, gitBranch, gitHead, gitRepoRoot, treeDigest, } from './tree-digest.js';
 const pkg = createRequire(import.meta.url)('../package.json');
 export const VDELTA_VERSION = pkg.version;
@@ -31,9 +31,62 @@ function findVitestToken(cmd) {
     }
     return null;
 }
+/**
+ * vitest 4.x CLI flags that always take their value as a *separate* argv
+ * token (`--flag value`), never combined into the flag token itself. Used
+ * by {@link splitCommandSelector} to recognize `--flag value` pairs and fold
+ * them into a single `--flag=value` canonical token so that space-separated
+ * and `=`-joined invocations normalize to the same command array (and
+ * therefore the same stream key — see `streamKey` in src/compare.ts).
+ *
+ * Deliberately excludes flags whose value is *optional*
+ * (`--changed`, `--silent`, `--coverage`, `--browser`, `--inspect`, etc.):
+ * for those, the token following the flag cannot be distinguished from a
+ * positional selector without vitest's own arg-parsing rules, so folding
+ * them here would risk silently swallowing a selector token. Flags outside
+ * this list keep the historical (pre-fix) behavior: a space-separated value
+ * is treated as a selector token, which may cause selector-based stream
+ * splitting and an abstain (`comparability: 'none'`) rather than a
+ * false-positive comparison.
+ *
+ * Maintenance: this list targets vitest 4.x. Revisit when bumping the
+ * vitest minor/major version (see issue #15 Open Question — no automated
+ * mechanism keeps this in sync with vitest's own CLI surface).
+ */
+const VITEST_VALUE_FLAGS = new Set([
+    '--project',
+    '--config',
+    '-c',
+    '--root',
+    '-r',
+    '--dir',
+    '--reporter',
+    '--outputFile',
+    '--pool',
+    '--maxWorkers',
+    '--minWorkers',
+    '--environment',
+    '--testNamePattern',
+    '-t',
+    '--testTimeout',
+    '--hookTimeout',
+    '--teardownTimeout',
+    '--retry',
+    '--bail',
+    '--maxConcurrency',
+    '--shard',
+    '--exclude',
+    '--mode',
+    '--workspace',
+]);
 /**
  * The invocation's selector is its inclusion intent (§6.4): the vitest CLI
  * positional filters. The canonical command excludes them (§5.1).
+ *
+ * `--flag value` pairs for known value-taking flags (see
+ * {@link VITEST_VALUE_FLAGS}) are folded into a single `--flag=value`
+ * canonical token so that this form and the pre-joined `--flag=value` form
+ * produce byte-identical `command` arrays (and thus the same stream key).
  */
 export function splitCommandSelector(cmd) {
     const idx = findVitestToken(cmd);
@@ -45,13 +98,25 @@ export function splitCommandSelector(cmd) {
         const token = cmd[i];
         if (token === 'run' && i === idx + 1) {
             command.push(token);
+            continue;
         }
-        else if (token.startsWith('-')) {
+        if (!token.startsWith('-')) {
+            selector.push(token);
+            continue;
+        }
+        if (token.includes('=')) {
             command.push(token);
+            continue;
         }
-        else {
-            selector.push(token);
+        const next = cmd[i + 1];
+        if (VITEST_VALUE_FLAGS.has(token) &&
+            next !== undefined &&
+            !next.startsWith('-')) {
+            command.push(`${token}=${next}`);
+            i++;
+            continue;
         }
+        command.push(token);
     }
     return { command, selector };
 }
@@ -149,7 +214,10 @@ export async function runAndRecord(cmd, cwd) {
         const record = buildRunRecord(capture, ctx);
         const store = new RunStore(worktree);
         store.ensure();
-        store.acquireLock();
+        const { reclaimed } = store.acquireLock();
+        if (reclaimed) {
+            diagnostics.push(`vdelta: reclaimed stale advisory lock at ${join(store.dir, 'lock')}`);
+        }
         let runId;
         try {
             runId = store.writeRun(record).runId;
@@ -160,6 +228,28 @@ export async function runAndRecord(cmd, cwd) {
         const report = buildComparisonReport(store, runId, {
             mode: 'previous-comparable',
         });
+        // Auto-GC (§4.1 SHOULD be bounded): keep the store from growing
+        // unbounded across repeated `vdelta run` invocations. Runs *after* the
+        // comparison above so the baseline it just resolved cannot be evicted
+        // out from under it — a comparison performed here always saw its
+        // baseline still present. The record just written is `last` and the
+        // resolved baseline (if any) are both protected for this pass, so
+        // neither is evicted even under a tight VDELTA_GC_MAX_COUNT/BYTES
+        // (AC-3). A GC failure (including a held lock) must not fail the run
+        // itself (INV-5 spirit) — it only downgrades to a diagnostic.
+        try {
+            store.acquireLock();
+            try {
+                const protectedIds = report.baseline ? [report.baseline.run_id] : [];
+                store.gc(defaultGcPolicy(), protectedIds);
+            }
+            finally {
+                store.releaseLock();
+            }
+        }
+        catch (e) {
+            diagnostics.push(`vdelta: gc skipped (${e instanceof Error ? e.message : String(e)})`);
+        }
         return {
             exitCode: child.exitCode,
             report,
@@ -171,7 +261,10 @@ export async function runAndRecord(cmd, cwd) {
     }
     catch (err) {
         if (err instanceof LockHeldError) {
-            return degraded('advisory lock is held');
+            // err.message already carries the lock path and the `rm -rf` recovery
+            // hint (see LockHeldError in store.ts); acquireLock() has already
+            // auto-reclaimed any stale lock, so reaching here means a live holder.
+            return degraded(err.message);
         }
         return degraded(err instanceof Error ? err.message : String(err));
     }

package/dist/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -2,26 +2,152 @@
  * Content-addressed run store (spec §4): immutable records, atomic writes,
  * fail-open advisory lock, enforced gitignore. Recency is store insertion
  * order (the append-only index), never timestamps (§7.8).
+ *
+ * The advisory lock (`.veridelta/lock`, mkdir-based for atomicity) is
+ * fail-open per INV-5: a lock that cannot be proven live degrades the
+ * caller to transparent passthrough rather than blocking indefinitely.
+ * On top of that, acquireLock() auto-reclaims *stale* locks so a crashed
+ * process doesn't wedge recording forever:
+ *   - if the lock carries `meta.json` ({pid, acquired_at_ms}), staleness is
+ *     decided purely by PID liveness (dead PID => stale, reclaim now;
+ *     regardless of age otherwise a live holder is never stolen);
+ *   - if `meta.json` is missing or unreadable/malformed (a legacy lock, or
+ *     a write that failed), staleness falls back to an mtime threshold
+ *     (`staleLockMs`, default 10 minutes) — this also preserves INV-5 for
+ *     the existing fail-open-held-lock conformance fixture, whose fresh
+ *     bare-mkdir lock must still degrade to passthrough.
+ * Reclaim moves the stale lock dir aside via renameSync (atomic: at most
+ * one concurrent reclaimer can walk off with that specific directory —
+ * a second racer's rename fails outright instead of silently trampling
+ * whatever now occupies the path) and deletes the moved-aside copy, then
+ * retries mkdir once; if that retry loses the race, we throw
+ * LockHeldError (fail-open), never loop. acquireLock() reports back
+ * whether it reclaimed a stale lock (and that lock's prior meta, if any)
+ * so callers can surface the event instead of reclaiming silently.
  */
-import { type RunRecord } from './schema.js';
+import { type CompletenessStatus, type RunRecord } from './schema.js';
 export declare class StoreCorruptError extends Error {
     constructor(message: string);
 }
 export declare class LockHeldError extends Error {
-    constructor();
+    readonly lockPath: string;
+    constructor(lockPath: string);
 }
 /** run_id = content address of the record excluding the recording group (§3.5). */
 export declare function computeRunId(record: RunRecord): string;
+/** Retention limits for {@link RunStore.gc}. `undefined` disables that limit. */
+export interface GcPolicy {
+    maxCount?: number;
+    maxBytes?: number;
+}
+/** Outcome of a {@link RunStore.gc} pass. */
+export interface GcResult {
+    removed: string[];
+    keptCount: number;
+    keptBytes: number;
+}
+/**
+ * Default retention policy (§4.1 SHOULD be bounded). Overridable via
+ * VDELTA_GC_MAX_COUNT / VDELTA_GC_MAX_BYTES (positive integers only; unset,
+ * empty, zero, or non-numeric values fall back to defaults or disable the
+ * limit respectively).
+ */
+export declare function defaultGcPolicy(): GcPolicy;
+/** Lightweight, non-strict view of a run record's addressing fields. */
+export interface RunMeta {
+    repo: {
+        identity: string;
+        worktree: string;
+        branch: string;
+        cwd: string;
+    };
+    invocation: {
+        command: string[];
+        selector: string[];
+    };
+    instrument: {
+        adapter: string;
+        adapter_version: string;
+        composition_id: string;
+        config_digest: string;
+    };
+    provenance: {
+        head: string | null;
+        tree_digest: string;
+    };
+    completeness: {
+        status: CompletenessStatus;
+        child_exit_code: number;
+    };
+}
+/** Options for RunStore's advisory lock stale-detection (testability + tuning). */
+export interface RunStoreOptions {
+    /** mtime threshold (ms) for reclaiming a meta-less legacy lock. Default 10 minutes. */
+    staleLockMs?: number;
+    /** PID liveness probe. Default: process.kill(pid, 0) (ESRCH => dead, else alive). */
+    isPidAlive?: (pid: number) => boolean;
+}
+/** Parsed contents of a lock's `meta.json`. */
+export interface LockMeta {
+    pid: number;
+    acquired_at_ms: number;
+}
+/** Result of acquireLock(): whether a stale lock had to be reclaimed. */
+export interface AcquireLockResult {
+    /** True if the lock we now hold was reclaimed from a stale prior holder. */
+    reclaimed: boolean;
+    /** The reclaimed lock's prior meta.json, if it had one and it was readable. */
+    staleMeta: LockMeta | null;
+}
 export declare class RunStore {
     readonly dir: string;
-    constructor(worktreeRoot: string);
+    private readonly staleLockMs;
+    private readonly isPidAlive;
+    constructor(worktreeRoot: string, options?: RunStoreOptions);
     private get runsDir();
     private get indexPath();
     private get lastPath();
     private get lockPath();
+    private get lockMetaPath();
     ensure(): void;
-    /** Advisory lock via mkdir; throws LockHeldError when already held (fail-open at the caller, INV-5). */
-    acquireLock(): void;
+    /** Best-effort: write lock metadata for future stale-detection. Never throws. */
+    private writeLockMeta;
+    /**
+     * Read and parse the currently-held lock's meta.json.
+     * Returns null if it's missing, unreadable, unparseable, or malformed
+     * (no finite numeric `pid`) — i.e. whenever the lock must be treated as
+     * a legacy, meta-less lock.
+     */
+    private readLockMeta;
+    /**
+     * Decide whether the currently-held lock is stale and may be reclaimed.
+     * - meta.json present and parseable with a finite numeric pid: stale iff
+     *   that pid is not alive (PID liveness is authoritative, any age).
+     * - meta.json missing/unreadable/unparseable/malformed (legacy lock):
+     *   stale iff the lock dir's mtime is older than staleLockMs (strict >).
+     */
+    private isLockStale;
+    private isLegacyLockStale;
+    /**
+     * Move the stale lock dir aside (renameSync, atomic) and delete the
+     * moved-aside copy. If the rename fails — another process already moved
+     * or recreated the lock — we do nothing further: the mkdir retry in
+     * acquireLock() is the sole arbiter of who actually ends up holding the
+     * lock, so a lost race here just falls through to that retry instead of
+     * blindly deleting whatever now occupies the path (which is what let two
+     * racers both end up "holding" the lock under a plain rmSync).
+     */
+    private reclaimStaleLock;
+    /**
+     * Advisory lock via mkdir (atomic). A stale lock (dead PID, or an aged
+     * legacy lock past staleLockMs) is auto-reclaimed: rename the stale dir
+     * aside and delete it, then retry mkdir once. If the lock is live, or
+     * the retry loses a race, throws LockHeldError — fail-open at the
+     * caller (INV-5). The return value reports whether a reclaim happened
+     * (and the reclaimed lock's prior meta, if any) so callers can surface
+     * the event rather than reclaiming silently.
+     */
+    acquireLock(): AcquireLockResult;
     releaseLock(): void;
     /**
      * Persist a record. Atomic (tmp+rename). Content-identical re-records are
@@ -38,6 +164,29 @@ export declare class RunStore {
     resolveRunId(idOrPrefix: string): string | null;
     /** Read and validate a record; parse/validation failures are store corruption. */
     readRun(runId: string): RunRecord;
+    /**
+     * Read a record's addressing/provenance fields without the full §9.4
+     * schema validation (used for cheap baseline pre-filtering). Same
+     * missing/unparseable error text as {@link readRun}; extracted-field
+     * absence or type mismatch is also a StoreCorruptError. Does not inspect
+     * observations/finding/recording.
+     */
+    readRunMeta(runId: string): RunMeta;
     /** INV-10: recompute the content address and compare with the stored id. */
     verifyIntegrity(runId: string): boolean;
+    /**
+     * Enforce a retention policy (§4.1 SHOULD be bounded). Evicts whole
+     * records (file + index entry), oldest first, until both limits are
+     * satisfied. The record pointed to by `last`, and any id passed in
+     * `protectedIds` (e.g. a baseline just selected for a comparison), are
+     * never evicted, even if one alone exceeds maxBytes (AC-3).
+     *
+     * PRECONDITION: the caller holds the advisory lock (see acquireLock()).
+     * gc() itself does not take the lock — callers that gc concurrently with a
+     * writer risk racing writeRun()'s index append.
+     *
+     * Index ids whose record file is already missing (dangling) are dropped
+     * from the index unconditionally, independent of the policy limits.
+     */
+    gc(policy: GcPolicy, protectedIds?: readonly string[]): GcResult;
 }