gitnexus 1.6.13-rc.81 → 1.6.13-rc.83

package/dist/core/ingestion/community-processor.d.ts

@@ -12,6 +12,12 @@ import type { NodeLabel } from '../../_shared/index.js';
 import { KnowledgeGraph } from '../graph/types.js';
 /** Graphology Graph instance type (AbstractGraph from graphology-types avoids CJS/ESM interop namespace issue) */
 type GraphInstance = AbstractGraph<Attributes, Attributes, Attributes>;
+/** Result returned by leiden.detailed() */
+interface LeidenDetailedResult {
+    communities: Record<string, number>;
+    count: number;
+    modularity: number;
+}
 type CommunityEngine = 'graphology' | 'icebug';
 export type CommunityDetectionEngine = CommunityEngine | 'auto';
 export interface CommunityDetectionOptions {
@@ -48,6 +54,11 @@ export interface CommunityCsr {
     indptr: BigUint64Array;
     indices: BigUint64Array;
 }
+interface CommunityEngineResult extends LeidenDetailedResult {
+    engine: CommunityEngine;
+    engineRequested: CommunityDetectionEngine;
+    fallbackReason?: string;
+}
 export declare const resolveCommunityDetectionEngine: (raw?: string) => CommunityDetectionEngine;
 export interface CommunityNode {
     id: string;
@@ -92,6 +103,7 @@ export declare const processCommunities: (knowledgeGraph: KnowledgeGraph, onProg
 export declare const buildCommunityProjection: (knowledgeGraph: KnowledgeGraph) => CommunityProjection;
 export declare const buildCommunityCsr: (projection: CommunityProjection) => CommunityCsr;
 export declare const buildGraphologyGraph: (projection: CommunityProjection) => GraphInstance;
+export declare const runGraphologyLeiden: (graph: GraphInstance, isLarge: boolean, engineRequested: CommunityDetectionEngine, timeoutMs?: number) => Promise<CommunityEngineResult>;
 /**
  * Runs Leiden in a worker so a native crash cannot take the analyze process
  * with it. Written against @ladybugmem/icebug's published surface (lib/index.js

package/dist/core/ingestion/community-processor.js

@@ -21,7 +21,9 @@ const __dirname = dirname(__filename);
 // Navigate to package root (works from both src/ and dist/)
 const leidenPath = resolve(__dirname, '..', '..', '..', 'vendor', 'leiden', 'index.cjs');
 const _require = createRequire(import.meta.url);
-const leiden = _require(leidenPath);
+// The Leiden worker loads its own copy; this load keeps a missing vendor/ asset
+// failing at import time and keeps it visible to dockerfile-runtime-asset-parity.
+_require(leidenPath);
 /**
  * Deterministic PRNG (mulberry32) seed for the vendored Leiden algorithm.
  * Vendored Leiden defaults `rng: Math.random`, which makes community
@@ -30,15 +32,6 @@ const leiden = _require(leidenPath);
  * incremental-indexing equivalence test (incremental ≡ full rebuild).
  */
 const LEIDEN_SEED = 0xc0de;
-function createSeededRng(seed) {
-    let s = seed >>> 0;
-    return () => {
-        s = (s + 0x6d2b79f5) >>> 0;
-        let t = Math.imul(s ^ (s >>> 15), 1 | s);
-        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
-        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-    };
-}
 const COMMUNITY_ENGINE_ENV = 'GITNEXUS_COMMUNITY_ENGINE';
 /**
  * Not a declared dependency: the prebuilds need system Arrow 24, libomp and
@@ -289,19 +282,96 @@ const runCommunityEngine = async (graph, projection, engineRequested, options, o
         const fallbackReason = error instanceof Error ? error.message : String(error);
         onProgress?.(`Icebug community engine unavailable, falling back to Graphology: ${fallbackReason}`, 35);
         const fallback = await runGraphologyLeiden(graph, projection.isLarge, engineRequested);
-        return { ...fallback, fallbackReason };
+        return {
+            ...fallback,
+            fallbackReason: fallback.fallbackReason
+                ? `${fallbackReason}; ${fallback.fallbackReason}`
+                : fallbackReason,
+        };
     }
 };
-const runGraphologyLeiden = async (graph, isLarge, engineRequested) => {
+/**
+ * Runs the vendored Leiden in a worker so LEIDEN_TIMEOUT_MS can actually fire.
+ * leiden.detailed is synchronous and, on some graphs, never returns
+ * (graphology/graphology#557); a timer on the main thread cannot interrupt it.
+ * The worker is pure JS, so terminate() is safe (unlike the icebug N-API worker).
+ */
+const GRAPHOLOGY_WORKER_SOURCE = `
+const { parentPort, workerData } = require('node:worker_threads');
+try {
+  const Graph = require(workerData.graphologyPath);
+  const leiden = require(workerData.leidenPath);
+  const graph = Graph.from(workerData.graph);
+  const rng = (() => {
+    let s = workerData.seed >>> 0;
+    return () => {
+      s = (s + 0x6d2b79f5) >>> 0;
+      let t = Math.imul(s ^ (s >>> 15), 1 | s);
+      t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+  })();
+  const d = leiden.detailed(graph, {
+    resolution: workerData.resolution,
+    maxIterations: workerData.maxIterations,
+    rng,
+  });
+  parentPort.postMessage({
+    ok: true,
+    communities: d.communities,
+    count: d.count,
+    modularity: d.modularity,
+  });
+} catch (error) {
+  parentPort.postMessage({ ok: false, error: error instanceof Error ? error.message : String(error) });
+}
+`;
+export const runGraphologyLeiden = async (graph, isLarge, engineRequested, timeoutMs = LEIDEN_TIMEOUT_MS) => {
     try {
-        const details = await Promise.race([
-            Promise.resolve(leiden.detailed(graph, {
-                resolution: isLarge ? 2.0 : 1.0,
-                maxIterations: isLarge ? 3 : 0,
-                rng: createSeededRng(LEIDEN_SEED),
-            })),
-            new Promise((_, reject) => setTimeout(() => reject(new Error('Leiden timeout')), LEIDEN_TIMEOUT_MS)),
-        ]);
+        const details = await new Promise((resolve, reject) => {
+            const worker = new Worker(GRAPHOLOGY_WORKER_SOURCE, {
+                eval: true,
+                workerData: {
+                    graphologyPath: _require.resolve('graphology'),
+                    leidenPath,
+                    graph: graph.export(),
+                    seed: LEIDEN_SEED,
+                    resolution: isLarge ? 2.0 : 1.0,
+                    maxIterations: isLarge ? 3 : 0,
+                },
+            });
+            let settled = false;
+            const timeout = setTimeout(() => {
+                settled = true;
+                void worker.terminate();
+                reject(new Error('Leiden timeout'));
+            }, timeoutMs);
+            worker.once('message', (message) => {
+                settled = true;
+                clearTimeout(timeout);
+                if (message.ok === true) {
+                    resolve({
+                        communities: message.communities,
+                        count: message.count,
+                        modularity: message.modularity,
+                    });
+                }
+                else {
+                    reject(new Error(message.error));
+                }
+            });
+            worker.once('error', (error) => {
+                settled = true;
+                clearTimeout(timeout);
+                reject(error);
+            });
+            worker.once('exit', (code) => {
+                if (settled)
+                    return;
+                clearTimeout(timeout);
+                reject(new Error(`Graphology Leiden worker exited with code ${code}`));
+            });
+        });
         return { ...details, engine: 'graphology', engineRequested };
     }
     catch (e) {

package/dist/core/ingestion/languages/dart/package-config.d.ts

@@ -15,14 +15,21 @@ export interface DartPackageConfigOptions {
      * is listed and before its entries are opened.
      */
     readonly beforeEntryOpen?: (relativePath: string) => void | Promise<void>;
+    /**
+     * Test seam. Production calls omit it. Invoked after the directory is
+     * opened and before it is listed.
+     */
+    readonly beforeDirectoryList?: (relativePath: string) => void | Promise<void>;
 }
 /** Linux anchors child opens. macOS verifies them. Every other platform does neither. */
 export declare function pubspecWalkAnchored(): boolean;
 export declare function directoryOpenFlags(): number;
 /**
  * Path that lists the directory inode already open on `fd`.
- * Linux uses `/proc/self/fd/N` and macOS uses `/dev/fd/N`.
- * Other platforms have no such path; callers refuse instead of listing by name.
+ * Only Linux has one: `/proc/self/fd/N`. macOS refuses `opendir` on
+ * `/dev/fd/N` for a directory (ENOTDIR) and Node has no `fdopendir`, so the
+ * walker lists the lexical path and verifies the pinned chain around it.
+ * Every other platform returns null and is not walked.
  */
 export declare function descriptorDirectoryPath(fd: number): string | null;
 /**

package/dist/core/ingestion/languages/dart/package-config.js

@@ -94,14 +94,14 @@ function directoryIdentity(stat) {
 }
 /**
  * Path that lists the directory inode already open on `fd`.
- * Linux uses `/proc/self/fd/N` and macOS uses `/dev/fd/N`.
- * Other platforms have no such path; callers refuse instead of listing by name.
+ * Only Linux has one: `/proc/self/fd/N`. macOS refuses `opendir` on
+ * `/dev/fd/N` for a directory (ENOTDIR) and Node has no `fdopendir`, so the
+ * walker lists the lexical path and verifies the pinned chain around it.
+ * Every other platform returns null and is not walked.
  */
 export function descriptorDirectoryPath(fd) {
     if (process.platform === 'linux')
         return `/proc/self/fd/${fd}`;
-    if (process.platform === 'darwin')
-        return `/dev/fd/${fd}`;
     return null;
 }
 /**
@@ -204,11 +204,31 @@ async function openChildFile(frames, parentFd, name, lexicalPath) {
         return openLexicalFile(frames, lexicalPath);
     throw Object.assign(new Error('no descriptor anchor'), { code: 'ENOTSUP' });
 }
-async function listOpenedDirectory(handle, entryLimit) {
-    const listing = descriptorDirectoryPath(handle.fd);
-    if (listing === null) {
+/**
+ * List the directory open on the last frame of `frames`. Linux lists the
+ * pinned inode through its descriptor. macOS re-checks the pinned chain, lists
+ * the lexical path, then re-checks the chain, so a path replaced around the
+ * listing fails the walk instead of being listed.
+ */
+async function listOpenedDirectory(frames, entryLimit, beforeList) {
+    const frame = frames[frames.length - 1];
+    if (frame === undefined) {
+        throw Object.assign(new Error('no directory to list'), { code: 'EINVAL' });
+    }
+    const anchored = descriptorDirectoryPath(frame.handle.fd);
+    if (anchored === null && process.platform !== 'darwin') {
         throw Object.assign(new Error('no descriptor listing'), { code: 'ENOTSUP' });
     }
+    if (anchored === null)
+        await assertPinnedChain(frames);
+    if (beforeList)
+        await beforeList();
+    const entries = await readDirectoryBounded(anchored ?? frame.absolute, entryLimit);
+    if (anchored === null)
+        await assertPinnedChain(frames);
+    return entries;
+}
+async function readDirectoryBounded(listing, entryLimit) {
     const dir = await opendir(listing);
     const entries = [];
     try {
@@ -236,8 +256,16 @@ async function listOpenedDirectory(handle, entryLimit) {
  */
 export async function readDirectoryNoFollow(directory) {
     const opened = await openVerifiedDirectory(directory);
+    const frame = {
+        relative: '',
+        absolute: directory,
+        handle: opened.handle,
+        identity: opened.identity,
+        entries: [],
+        next: 0,
+    };
     try {
-        return await listOpenedDirectory(opened.handle, DART_PUBSPEC_DIRECTORY_ENTRY_LIMIT);
+        return await listOpenedDirectory([frame], DART_PUBSPEC_DIRECTORY_ENTRY_LIMIT);
     }
     finally {
         await opened.handle.close();
@@ -280,7 +308,8 @@ export async function loadDartPackageConfig(repoPath, options) {
         if (++visited > directoryLimit)
             return incomplete('directory-limit', frame.relative || '.');
         try {
-            frame.entries = await listOpenedDirectory(frame.handle, directoryEntryLimit);
+            const beforeList = options?.beforeDirectoryList;
+            frame.entries = await listOpenedDirectory(stack, directoryEntryLimit, beforeList ? () => beforeList(frame.relative) : undefined);
         }
         catch (error) {
             const reason = error.code === 'E2BIG' ? 'directory-entries' : 'read-directory';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.13-rc.81",
+  "version": "1.6.13-rc.83",
   "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",
@@ -59,6 +59,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:cross-platform": "tsx scripts/run-cross-platform.ts",
+    "test:benchmarks": "node --import tsx scripts/run-benchmarks.ts",
     "postinstall": "node scripts/build-tree-sitter-grammars.cjs",
     "assert-publish-coverage": "node scripts/assert-publish-grammar-coverage.cjs",
     "prepare": "node scripts/build.js",

package/scripts/cross-platform-tests.ts

@@ -206,9 +206,8 @@ const LBUG_NATIVE = [
   // (the same reason fts-extension-e2e.test.ts is registered below), so the
   // FTS-unavailable branch has to run on a real Windows/macOS runner rather
   // than only on Ubuntu where FTS always loads. And its both-blocked case is
-  // gated on GITNEXUS_REQUIRE_VECTOR=1, which ci-tests.yml sets ONLY on this
-  // job — everywhere else an unavailable VECTOR extension skips instead of
-  // failing. Budget: four real analyze runs, so expect it to sit alongside the
+  // gated on GITNEXUS_REQUIRE_VECTOR=1, which ci-tests.yml requires in both
+  // coverage and platform jobs so an unavailable VECTOR fails loudly. Budget: four real analyze runs, so expect it to sit alongside the
   // VECTOR sibling's ~87s Windows measurement.
   'test/unit/incremental-index-extension-dml-gate.test.ts',
 ];
@@ -290,6 +289,7 @@ const SPAWN_CLI = [
 // Worker threads tests — exercise real worker_threads which have
 // platform-specific behavior (thread spawning, IPC, exit handling)
 const WORKER_THREADS = [
+  'test/unit/community-processor.test.ts',
   'test/integration/worker-pool.test.ts',
   'test/integration/parse-impl-quarantine-cache-skip.test.ts',
 ];
@@ -308,6 +308,10 @@ const NATIVE_ADDON_SMOKE = [
 // Filesystem behavior tests — exercise operations that vary across
 // platforms (CRLF, symlinks, permissions, temp dirs)
 const FILESYSTEM = [
+  // The deletion-guard cases in this file require real Windows path semantics.
+  'test/unit/canonicalize-path-long-path-prefix.test.ts',
+  'test/unit/storage-resolver.test.ts',
+  'test/unit/dart-package-imports.test.ts',
   // Cargo membership uses path normalization, descriptor validation, symlinks,
   // and Rust native parsing (including long Windows source strings).
   'test/unit/scope-resolution/rust-cargo-targets.test.ts',

package/scripts/execution-reporter.ts

@@ -0,0 +1,33 @@
+import { JsonReporter, type TestRunEndReason } from 'vitest/node';
+
+/** Vitest's stock JSON omits unhandled errors, even when success is true. */
+export default class ExecutionReporter extends JsonReporter {
+  private executionErrors = 0;
+  private executionReason: TestRunEndReason = 'interrupted';
+
+  constructor() {
+    super({});
+  }
+
+  override async onTestRunEnd(
+    modules: Parameters<JsonReporter['onTestRunEnd']>[0],
+    errors: readonly unknown[] = [],
+    reason: TestRunEndReason = 'interrupted',
+  ): Promise<void> {
+    this.executionErrors = errors.length;
+    this.executionReason = reason;
+    await super.onTestRunEnd(modules);
+  }
+
+  override async writeReport(json: string): Promise<void> {
+    const report = JSON.parse(json);
+    await super.writeReport(
+      JSON.stringify({
+        ...report,
+        success: report.success && this.executionErrors === 0 && this.executionReason === 'passed',
+        executionErrors: this.executionErrors,
+        executionReason: this.executionReason,
+      }),
+    );
+  }
+}

package/scripts/run-benchmarks.ts

@@ -0,0 +1,32 @@
+import { execFileSync } from 'node:child_process';
+import { globSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const root = fileURLToPath(new URL('../', import.meta.url));
+// Discover the opt-in suites from source so a new benchmark cannot silently
+// miss a hand-maintained workflow list. Keep wall-clock measurements serial.
+const files = globSync('test/**/*.test.ts', { cwd: root })
+  .filter((file) =>
+    /process\.env(?:\.GITNEXUS_BENCH|\[['"]GITNEXUS_BENCH['"]\])/.test(
+      readFileSync(new URL(`../${file.replaceAll('\\', '/')}`, import.meta.url), 'utf8'),
+    ),
+  )
+  .sort();
+if (!files.length) throw new Error('No benchmark test suites discovered');
+execFileSync(
+  process.execPath,
+  [
+    fileURLToPath(new URL('../node_modules/vitest/vitest.mjs', import.meta.url)),
+    'run',
+    '--no-file-parallelism',
+    ...files,
+    '--reporter=default',
+    '--reporter=./scripts/execution-reporter.ts',
+    '--outputFile=benchmarks.json',
+  ],
+  {
+    cwd: root,
+    stdio: 'inherit',
+    env: { ...process.env, GITNEXUS_BENCH: '1' },
+  },
+);

package/scripts/run-cross-platform.ts

@@ -80,8 +80,19 @@ console.log(
 );
 
 const startedAt = Date.now();
+const reportName = process.env.GITNEXUS_TEST_REPORT;
+if (reportName && !/^[a-zA-Z0-9_-]+\.json$/.test(reportName)) {
+  throw new Error('GITNEXUS_TEST_REPORT must be a JSON basename');
+}
+const reportArgs = reportName
+  ? [
+      '--reporter=default',
+      '--reporter=./scripts/execution-reporter.ts',
+      `--outputFile=${reportName}`,
+    ]
+  : [];
 try {
-  execFileSync('npx', ['vitest', 'run', ...files], {
+  execFileSync('npx', ['vitest', 'run', ...files, ...reportArgs], {
     cwd: ROOT,
     stdio: 'inherit',
     timeout: timeoutMs,

package/scripts/test-completeness.ts

@@ -0,0 +1,203 @@
+import { globSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import type { TestRunEndReason } from 'vitest/node';
+
+type Assertion = {
+  ancestorTitles: string[];
+  title: string;
+  fullName: string;
+  status: string;
+  location?: { line: number; column: number };
+};
+type Suite = {
+  name: string;
+  status: string;
+  assertionResults: Assertion[];
+  endTime?: number;
+  message?: string;
+};
+type Report = {
+  success?: boolean;
+  numTotalTests?: number;
+  startTime?: number;
+  executionErrors: number;
+  executionReason: TestRunEndReason;
+  testResults: Suite[];
+};
+
+/** Stable across GitHub's Linux, macOS and Windows checkout roots. */
+function testPath(name: string, packageName: string): string {
+  const normalized = name.replaceAll('\\', '/');
+  const relative =
+    normalized.match(new RegExp(`(?:^|/)${packageName}/((?:test|src)/.+)$`))?.[1] ?? normalized;
+  if (!/^(?:test|src)\/.+\.test\.[jt]sx?$/.test(relative)) {
+    throw new Error(`Invalid test report path: ${name}`);
+  }
+  return relative;
+}
+
+/** A skip is resolved only by a recorded pass of that same test in another job. */
+export function reconcileTestReports(
+  inputs: unknown[],
+  expectedFiles: string[] = [],
+  packageName = 'gitnexus',
+) {
+  if (inputs.length === 0) throw new Error('No execution reports supplied');
+  const tests = new Map<
+    string,
+    { file: string; assertion: Assertion; passed: boolean; failed: boolean }
+  >();
+  const failures = new Set<string>();
+  const failedSuites = new Set<string>();
+  const startTimes: number[] = [];
+  const endTimes: number[] = [];
+  for (const [index, input] of inputs.entries()) {
+    const report = input as Report;
+    if (!report || !Array.isArray(report.testResults) || report.testResults.length === 0) {
+      throw new Error(`Missing or empty execution report ${index}`);
+    }
+    if (report.success === false) failures.add(`Report ${index}: unsuccessful runner result`);
+    if (
+      !Number.isInteger(report.executionErrors) ||
+      report.executionErrors < 0 ||
+      !['passed', 'failed', 'interrupted'].includes(report.executionReason)
+    ) {
+      throw new Error(`Report ${index}: missing execution reporter evidence`);
+    }
+    if (report.executionErrors || report.executionReason !== 'passed') {
+      failures.add(
+        `Report ${index}: ${report.executionErrors} unhandled errors; ${report.executionReason}`,
+      );
+    }
+    if (typeof report.startTime === 'number') startTimes.push(report.startTime);
+    let count = 0;
+    const seen = new Set<string>();
+    for (const suite of report.testResults) {
+      const file = testPath(suite.name, packageName);
+      if (!Array.isArray(suite.assertionResults) || suite.assertionResults.length === 0) {
+        throw new Error(`No collected tests in ${file}`);
+      }
+      if (suite.status === 'failed') {
+        failures.add(`${file}: failed suite`);
+        failedSuites.add(file);
+      }
+      if (typeof suite.endTime === 'number') endTimes.push(suite.endTime);
+      for (const assertion of suite.assertionResults) {
+        if (
+          !['passed', 'failed', 'pending', 'skipped', 'todo', 'disabled'].includes(
+            assertion.status,
+          ) ||
+          !Array.isArray(assertion.ancestorTitles) ||
+          typeof assertion.title !== 'string' ||
+          (assertion.location !== undefined &&
+            (!Number.isInteger(assertion.location.line) ||
+              !Number.isInteger(assertion.location.column)))
+        ) {
+          throw new Error(`Malformed assertion in ${file}`);
+        }
+        // Collection order differs across platforms. Source location, not an
+        // ordinal, distinguishes equal titles declared at different locations.
+        // Helper-generated tests may have no location; their complete title
+        // must then be unique within the file (the duplicate check still applies).
+        const title = JSON.stringify([...assertion.ancestorTitles, assertion.title]);
+        const key = JSON.stringify([
+          file,
+          title,
+          assertion.location?.line ?? null,
+          assertion.location?.column ?? null,
+        ]);
+        if (seen.has(key))
+          throw new Error(
+            `Ambiguous test identity in ${file}: ${title}; give parameterized cases unique titles`,
+          );
+        seen.add(key);
+        const result = tests.get(key) ?? { file, assertion, passed: false, failed: false };
+        result.passed ||= assertion.status === 'passed';
+        result.failed ||= assertion.status === 'failed';
+        tests.set(key, result);
+        if (result.failed) failures.add(`${file}: ${assertion.fullName ?? title}`);
+        count++;
+      }
+    }
+    if (typeof report.numTotalTests === 'number' && report.numTotalTests !== count) {
+      throw new Error(`Report ${index}: expected ${report.numTotalTests} tests, found ${count}`);
+    }
+  }
+  const unverified = [...tests.values()]
+    .filter((test) => !test.passed && !test.failed)
+    .map((test) => `${test.file}: ${test.assertion.fullName}`);
+  const suites = new Map<string, Suite>();
+  for (const test of tests.values()) {
+    const status = test.failed ? 'failed' : test.passed ? 'passed' : 'pending';
+    const suite = suites.get(test.file) ?? {
+      name: test.file,
+      status: 'passed',
+      assertionResults: [],
+    };
+    suite.assertionResults.push({ ...test.assertion, status });
+    if (status === 'failed' || failedSuites.has(test.file)) suite.status = 'failed';
+    suites.set(test.file, suite);
+  }
+  for (const file of expectedFiles) {
+    if (!suites.has(file.replaceAll('\\', '/')))
+      throw new Error(`Test file was never collected: ${file}`);
+  }
+  const passed = [...tests.values()].filter((test) => test.passed && !test.failed).length;
+  const endTime = endTimes.length ? Math.max(...endTimes) : 0;
+  return {
+    total: tests.size,
+    passed,
+    unverified,
+    failures: [...failures],
+    report: {
+      success: failures.size === 0 && unverified.length === 0,
+      numTotalTests: tests.size,
+      numPassedTests: passed,
+      numFailedTests: [...tests.values()].filter((test) => test.failed).length,
+      numPendingTests: unverified.length,
+      numTotalTestSuites: suites.size,
+      numFailedTestSuites: failedSuites.size,
+      executionFailures: [...failures],
+      startTime: startTimes.length ? Math.min(...startTimes) : 0,
+      testResults: [...suites.values()].map((suite) => ({ ...suite, endTime })),
+    },
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  const [directory, output, shardsText] = process.argv.slice(2);
+  const shards = Number(shardsText);
+  if (!directory || !output || !Number.isInteger(shards) || shards < 1) {
+    throw new Error('Usage: test-completeness.ts <reports-dir> <output.json> <platform-shards>');
+  }
+  const names = ['coverage.json', 'benchmarks.json', 'preflight.json'];
+  for (const os of ['windows-latest', 'macos-latest']) {
+    for (let shard = 1; shard <= shards; shard++) names.push(`${os}-${shard}.json`);
+  }
+  // Exact expected receipts: an absent/cancelled job is never an empty success.
+  const root = fileURLToPath(new URL('../', import.meta.url));
+  const expected = globSync('test/**/*.test.ts', { cwd: root });
+  const result = reconcileTestReports(
+    names.map((name) => JSON.parse(readFileSync(path.join(directory, name), 'utf8'))),
+    expected,
+  );
+  writeFileSync(output, JSON.stringify(result.report));
+  console.log(
+    `Test execution: ${result.passed}/${result.total} passed; ${result.unverified.length} unverified; ${result.failures.length} failures`,
+  );
+  for (const message of [...result.unverified, ...result.failures]) console.error(message);
+  if (!result.report.success) process.exitCode = 1;
+  const webPath = path.join(root, '../gitnexus-web/web-test-results.json');
+  const web = reconcileTestReports(
+    [JSON.parse(readFileSync(webPath, 'utf8'))],
+    globSync('{test,src}/**/*.test.{ts,tsx}', { cwd: path.join(root, '../gitnexus-web') }),
+    'gitnexus-web',
+  );
+  writeFileSync(webPath, JSON.stringify(web.report));
+  console.log(
+    `Web execution: ${web.passed}/${web.total} passed; ${web.unverified.length} unverified; ${web.failures.length} failures`,
+  );
+  for (const message of [...web.unverified, ...web.failures]) console.error(message);
+  if (!web.report.success) process.exitCode = 1;
+}