@opengsd/gsd-core 1.5.0-rc.2 → 1.5.0-rc.4

package/scripts/run-tests.cjs

@@ -13,6 +13,15 @@
 //   node scripts/run-tests.cjs --suite slow        # *.slow.test.cjs
 //   node scripts/run-tests.cjs --files "a.test.cjs b.test.cjs"
 //   node scripts/run-tests.cjs --files-from /tmp/selected-tests.txt
+//   node scripts/run-tests.cjs --suite unit --shard 1/3   # shard 1 of 3 (#1212)
+//
+// Sharding (issue #1212): --shard <i>/<n> runs a deterministic, balanced
+// round-robin slice of the SORTED selected file list (file index k → shard
+// k % n). i is 1-based (1..n); n >= 1; n=1 is a pure no-op (all files). The
+// CI windows full-test lane shards across N parallel runners so per-job
+// wall-clock scales as O(total/N) and stops hitting the job time cap. Sharding
+// composes with --suite (it slices the post-filter selection) and preserves
+// the existing 28K argv chunking WITHIN each shard.
 //
 // Suite grouping convention: filename suffix marker before `.test.cjs`.
 // A file named `foo.security.test.cjs` belongs to the `security` suite.
@@ -21,7 +30,7 @@
 'use strict';
 
 const { readdirSync } = require('fs');
-const { join } = require('path');
+const { join, basename } = require('path');
 const { execFileSync } = require('child_process');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
@@ -112,14 +121,90 @@ function ensureBuiltArtifacts(overrides = {}) {
 }
 const MARKED_SUITES = ['integration', 'install', 'security', 'slow'];
 
+// Recursively collect *.test.cjs files under dir, returning paths relative to dir.
+// Skips node_modules to avoid accidentally picking up decoy files.
+function walkTestFiles(dir, relBase) {
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules') continue;
+      results.push(...walkTestFiles(join(dir, entry.name), relBase ? `${relBase}/${entry.name}` : entry.name));
+    } else if (entry.name.endsWith('.test.cjs')) {
+      results.push(relBase ? `${relBase}/${entry.name}` : entry.name);
+    }
+  }
+  return results;
+}
+
+// Parse a `--shard i/n` value into { index, total } or { error }.
+// i is 1-based and must satisfy 1 <= i <= n; n must be >= 1. Both parts must be
+// plain non-negative integers (no decimals, signs, or surrounding whitespace).
+// `n=1` is the pure no-op (every file). This is the strict-input boundary
+// (Postel's Law: be strict in what a CLI flag accepts so a typo fails loudly
+// rather than silently running the wrong slice of the suite).
+function parseShardArg(value) {
+  if (typeof value !== 'string') {
+    return { error: `--shard requires a value of the form i/n` };
+  }
+  const m = /^(\d+)\/(\d+)$/.exec(value);
+  if (!m) {
+    return { error: `--shard value "${value}" must be of the form i/n (e.g. 1/3)` };
+  }
+  const index = Number(m[1]);
+  const total = Number(m[2]);
+  if (!Number.isInteger(total) || total < 1) {
+    return { error: `--shard total n must be an integer >= 1, got "${m[2]}"` };
+  }
+  if (!Number.isInteger(index) || index < 1 || index > total) {
+    return { error: `--shard index i must be an integer in 1..${total}, got "${m[1]}"` };
+  }
+  return { index, total };
+}
+
+// Deterministic, balanced round-robin partition of an ALREADY-SORTED file list.
+// Shard `index` (1-based) receives every file whose position k in the sorted
+// list satisfies k % total === index - 1. Round-robin (not contiguous blocks)
+// spreads duration variance across shards and guarantees shard sizes differ by
+// at most 1. Selection keys off array INDEX, never off the path string, so the
+// partition is byte-identical across Windows/macOS/Linux as long as the caller
+// sorts the list with the same (locale-independent) comparator. `total=1`
+// returns the input unchanged (pure no-op). A shard with no files (total >
+// file count) returns [] and is a legitimate result, not an error.
+function selectShard(sortedFiles, { index, total }) {
+  if (total === 1) return sortedFiles;
+  return sortedFiles.filter((_, k) => k % total === index - 1);
+}
+
 function parseArgs(argv) {
   let suite = null;
   let seen = false;
   let files = null;
   let filesFrom = null;
+  let shard = null;
+  let shardSeen = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--suite') {
+    if (a === '--shard' || a.startsWith('--shard=')) {
+      if (shardSeen) {
+        return { error: 'duplicate --shard flag' };
+      }
+      shardSeen = true;
+      let v;
+      if (a === '--shard') {
+        v = argv[i + 1];
+        if (v === undefined || (typeof v === 'string' && v.startsWith('--'))) {
+          return { error: '--shard requires a value of the form i/n' };
+        }
+        i++;
+      } else {
+        v = a.slice('--shard='.length);
+      }
+      const parsed = parseShardArg(v);
+      if (parsed.error) {
+        return { error: parsed.error };
+      }
+      shard = parsed;
+    } else if (a === '--suite') {
       if (seen) {
         return { error: 'duplicate --suite flag' };
       }
@@ -182,15 +267,18 @@ function parseArgs(argv) {
   if (files !== null && filesFrom !== null) {
     return { error: '--files and --files-from cannot be combined' };
   }
-  return { suite, files, filesFrom };
+  return { suite, files, filesFrom, shard };
 }
 
 // Return the marked suite name embedded in a filename, or null if it's unmarked.
 // foo.security.test.cjs -> "security"
 // foo.test.cjs          -> null (unit)
+// Accepts either a bare filename or a relative subdir path; classification is
+// based on the basename only so subdir paths classify identically to root files.
 function suiteOf(filename) {
-  if (!filename.endsWith('.test.cjs')) return null;
-  const base = filename.slice(0, -'.test.cjs'.length);
+  const name = basename(filename);
+  if (!name.endsWith('.test.cjs')) return null;
+  const base = name.slice(0, -'.test.cjs'.length);
   const lastDot = base.lastIndexOf('.');
   if (lastDot === -1) return null;
   const marker = base.slice(lastDot + 1);
@@ -213,7 +301,8 @@ function splitFileList(value) {
     .split(/[,\s]+/)
     .map(v => v.trim())
     .filter(Boolean)
-    .map(v => v.replace(/^tests[\\/]/, ''));
+    .map(v => v.replace(/\\/g, '/'))   // normalize Windows backslashes
+    .map(v => v.replace(/^tests\//, ''));
 }
 
 function selectExplicitFiles(allFiles, filesValue, filesFrom) {
@@ -222,8 +311,19 @@ function selectExplicitFiles(allFiles, filesValue, filesFrom) {
     ? splitFileList(fs.readFileSync(filesFrom, 'utf8'))
     : splitFileList(filesValue);
   const available = new Set(allFiles);
+
+  // Build a basename -> [relpath, ...] index for bare-basename resolution.
+  // A bare basename (no directory separator) may match exactly one subdir file.
+  const basenameIndex = new Map();
+  for (const f of allFiles) {
+    const b = basename(f);
+    if (!basenameIndex.has(b)) basenameIndex.set(b, []);
+    basenameIndex.get(b).push(f);
+  }
+
   const selected = [];
   const missing = [];
+  const errors = [];
   for (const file of requested) {
     // If the token is a bare suite name (e.g. "unit" written by ci-test-scope
     // as the #408 fallback sentinel), delegate to the existing suite resolver
@@ -234,11 +334,27 @@ function selectExplicitFiles(allFiles, filesValue, filesFrom) {
         selected.push(f);
       }
     } else if (available.has(file)) {
+      // Exact relpath match (e.g. "installer-migrations/001-legacy-orphan-files.test.cjs").
       selected.push(file);
+    } else if (!file.includes('/')) {
+      // Bare basename (no directory separator): resolve via index.
+      const candidates = basenameIndex.get(file);
+      if (!candidates || candidates.length === 0) {
+        missing.push(file);
+      } else if (candidates.length > 1) {
+        errors.push(
+          `ambiguous basename "${file}" matches multiple files: ${candidates.join(', ')} — pass the subdir path instead`,
+        );
+      } else {
+        selected.push(candidates[0]);
+      }
     } else {
       missing.push(file);
     }
   }
+  if (errors.length > 0) {
+    return { error: errors.join('; ') };
+  }
   if (missing.length > 0) {
     return {
       error: `requested test file(s) not found: ${missing.join(', ')}`,
@@ -266,17 +382,16 @@ function main() {
     ? process.env.GSD_TEST_DIR
     : join(__dirname, '..', 'tests');
 
-  const allFiles = readdirSync(testDir)
-    .filter(f => f.endsWith('.test.cjs'))
-    .sort();
+  const allFiles = walkTestFiles(testDir, '').sort();
 
   if (allFiles.length === 0) {
     console.error(`No test files found in ${testDir}`);
     throw new ExitError(1);
   }
 
+  const usingExplicitFiles = parsed.files !== null || parsed.filesFrom !== null;
   let selectedNames;
-  if (parsed.files !== null || parsed.filesFrom !== null) {
+  if (usingExplicitFiles) {
     const explicit = selectExplicitFiles(allFiles, parsed.files, parsed.filesFrom);
     if (explicit.error) {
       console.error(`run-tests: ${explicit.error}`);
@@ -286,14 +401,54 @@ function main() {
   } else {
     selectedNames = selectFiles(allFiles, suite);
   }
+
+  // Shard partitioning (#1212): when --shard i/n is given, keep only this
+  // shard's deterministic round-robin slice of the selected list. Applied
+  // AFTER suite/explicit selection so it composes with --suite (each shard
+  // runs i/n of the post-filter selection).
+  //
+  // The partition keys off array index, so the slice is only reproducible if
+  // the input is in a stable order. --suite/default selections are already
+  // sorted (allFiles came from walkTestFiles(...).sort() and selectFiles
+  // preserves that order), but --files/--files-from preserve REQUEST order.
+  // Sort here so --shard is deterministic regardless of how the selection was
+  // produced — the runner's documented contract is a sorted partition.
+  //
+  // emptyBeforeShard distinguishes "this shard legitimately got zero files
+  // from a non-empty list" (total > file count — a valid no-op) from "the
+  // selection was already empty before sharding" (a genuinely empty suite,
+  // which must still hit the discovery hard-error below — Codex #1212 review).
+  const usingShard = parsed.shard !== null;
+  let emptyBeforeShard = false;
+  if (usingShard) {
+    emptyBeforeShard = selectedNames.length === 0;
+    selectedNames = selectShard([...selectedNames].sort(), parsed.shard);
+  }
+
   const selected = selectedNames.map(f => join(testDir, f));
 
   if (selected.length === 0) {
-    // Empty suite: report and exit 0 so empty lanes (e.g. `security` before
-    // adversarial tests land) don't gate CI. CI consumers wanting strictness
-    // can grep stderr for "no tests in suite".
-    console.error(`run-tests: no tests in suite "${suite || 'all'}"`);
-    return 0;
+    // A legitimately-empty shard: --shard was given, the pre-shard selection
+    // had files, but this shard index drew zero (total > file count). Exit 0.
+    const legitimatelyEmptyShard = usingShard && !emptyBeforeShard;
+    if (usingExplicitFiles || legitimatelyEmptyShard) {
+      // Empty file list from --files/--files-from (e.g. CI passes an empty
+      // .ci-selected-tests.txt on docs-only/inert PRs) OR a legitimately-empty
+      // shard: both are expected. Exit 0 silently rather than taking the
+      // "discovery broken" hard-error path below. An EMPTY suite that was
+      // empty BEFORE sharding falls through to the hard error so a broken
+      // --suite filter is still caught even with --shard present.
+      console.error(`run-tests: no tests in suite "${suite || 'all'}"`);
+      return 0;
+    }
+    // Empty suite/default run: this means discovery or the suite filter is broken.
+    // Allow GSD_ALLOW_EMPTY_SUITE=1 as an escape hatch (downgrades to a warning).
+    if (process.env.GSD_ALLOW_EMPTY_SUITE === '1') {
+      console.error(`run-tests: WARNING: 0 test files selected for suite "${suite || 'all'}" — discovery or suite filter may be broken (GSD_ALLOW_EMPTY_SUITE=1 suppressed the error)`);
+      return 0;
+    }
+    console.error(`run-tests: ERROR: 0 test files selected for suite "${suite || 'all'}" — discovery or suite filter is broken`);
+    throw new ExitError(1);
   }
 
   // Build the gitignored bin/lib artifact if absent, before any test requires it.
@@ -342,6 +497,9 @@ function main() {
   const MAX_CMDLINE_CHARS = process.env.RUN_TESTS_MAX_CMDLINE_CHARS
     ? Number(process.env.RUN_TESTS_MAX_CMDLINE_CHARS)
     : 28000; // headroom below the 32,767 Windows ceiling
+  const MAX_FILES_PER_CHUNK = process.env.RUN_TESTS_MAX_FILES_PER_CHUNK
+    ? Number(process.env.RUN_TESTS_MAX_FILES_PER_CHUNK)
+    : 180;
 
   // node:test does not exit until the event loop drains. A unit test that leaks
   // an open handle (un-terminated Worker, un-killed child_process, ref'd timer)
@@ -362,7 +520,10 @@ function main() {
   let currentLen = FIXED_OVERHEAD;
   for (const file of selected) {
     const add = file.length + 1; // +1 for the inter-arg separator
-    if (current.length > 0 && currentLen + add > MAX_CMDLINE_CHARS) {
+    if (
+      current.length > 0 &&
+      (currentLen + add > MAX_CMDLINE_CHARS || current.length >= MAX_FILES_PER_CHUNK)
+    ) {
       chunks.push(current);
       current = [];
       currentLen = FIXED_OVERHEAD;
@@ -424,4 +585,4 @@ if (require.main === module) {
   runMain(main);
 }
 
-module.exports = { suiteOf, ensureBuiltArtifacts };
+module.exports = { suiteOf, ensureBuiltArtifacts, parseShardArg, selectShard };