Function planCiShards

e2e/scripts/ci-shard.ts:163–218

(
  files: readonly WeightedTestFile[],
  shardCount: number,
)

 * or more shards than files. External CLI values must be parsed first.
 */
export const planCiShards = (
  files: readonly WeightedTestFile[],
  shardCount: number,
): readonly CiShardAssignment[] => {
  if (!Number.isSafeInteger(shardCount) || shardCount <= 0) {
    throw new Error("shard count must be a positive safe integer");
  }
  if (files.length < shardCount) {
    throw new Error("every configured shard must receive at least one test file");
  }

  const paths = files.map((file) => file.path);
  if (new Set(paths).size !== paths.length) {
    throw new Error("test file paths must be unique");
  }
  for (const file of files) {
    if (file.path.length === 0 || !Number.isFinite(file.durationMs) || file.durationMs <= 0) {
      throw new Error("test files must have a path and positive finite duration");
    }
  }

  const bins = Array.from({ length: shardCount }, (_, index) => ({
    index: index + 1,
    estimatedDurationMs: 0,
    files: [] as string[],
    isolated: false,
  }));
  const longestFirst = [...files].sort(
    (left, right) => right.durationMs - left.durationMs || comparePaths(left.path, right.path),
  );

  for (const file of longestFirst) {
    const mustIsolate = file.durationMs >= ISOLATED_TEST_DURATION_MS;
    const candidates = bins.filter((bin) => (mustIsolate ? bin.files.length === 0 : !bin.isolated));
    const firstCandidate = candidates[0];
    if (firstCandidate === undefined) {
      throw new Error("configured shard count cannot isolate every long-running test file");
    }

    let lightest = firstCandidate;
    for (const candidate of candidates.slice(1)) {
      if (candidate.estimatedDurationMs < lightest.estimatedDurationMs) {
        lightest = candidate;
      }
    }
    lightest.files.push(file.path);
    lightest.estimatedDurationMs += file.durationMs;
    lightest.isolated = mustIsolate;
  }

  return bins.map((bin) => ({
    index: bin.index,
    estimatedDurationMs: bin.estimatedDurationMs,
    files: [...bin.files].sort(comparePaths),
  }));
};

/** Discovers and plans all shards for one configured target. */