@variance-authority/core 0.14.0 → 0.15.0

package/dist/shard/placement.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Which shard runs which group, and how many shards a suite is worth.
+ *
+ * A group is placed whole: every story of one file, every width of one route,
+ * every case of one test file loads the same modules, and split across
+ * machines each machine pays for them. Three rules decide where it goes:
+ *
+ * - **With recorded times, the time decides.** Groups go longest first to the
+ *   shard with the least time so far (LPT, within 4/3 of the best split). Ties
+ *   are broken by key in code-unit order, so the placement is a function of
+ *   the groups and their times and never of the order they were found in.
+ * - **A member nothing recorded is priced at the median of the recorded ones.**
+ *   A new file is a file, and pricing it at zero would stack every new one on
+ *   one shard.
+ * - **With nothing recorded, a checksum decides.** Each group goes to the shard
+ *   whose `sha256(key, shard)` is highest, which depends on the key and the
+ *   shard count alone, so adding a group moves no other.
+ *
+ * Every shard computes the whole placement and keeps its own part. Nothing is
+ * exchanged between shards, so two shards agree exactly when they were handed
+ * the same groups and the same times.
+ */
+/** One group placed whole, and the milliseconds recorded for each of its members. */
+export interface Placeable {
+    readonly key: string;
+    /** `undefined` for a member nothing recorded a time for. */
+    readonly costs: readonly (number | undefined)[];
+}
+export interface Placement {
+    /** The shard, from 1, of each group in the order they were handed in. */
+    readonly owner: readonly number[];
+    readonly by: 'checksum' | 'recorded cost';
+    /** Milliseconds each group is priced at; absent when placed by checksum. */
+    readonly cost?: readonly number[];
+    /** Milliseconds each shard was given, shard 1 first; absent when placed by checksum. */
+    readonly load?: readonly number[];
+}
+/**
+ * Each group's price: its members' recorded milliseconds, with the median of
+ * every recorded member standing in for one nothing recorded. Absent when no
+ * member of any group is recorded, because then there is no price to give.
+ */
+export declare function priced(groups: readonly Placeable[]): number[] | undefined;
+/** Place every group on one of `total` shards. */
+export declare function place(groups: readonly Placeable[], total: number): Placement;
+/**
+ * Group indices, longest first, ties by key in code-unit order: the order a
+ * shard's workers take its groups in, so one that finishes early takes the
+ * short ones at the end.
+ */
+export declare function longestFirst(keys: readonly string[], cost: readonly number[]): number[];
+/** Why a shard count is the one {@link shardCount} chose. */
+export type ShardCountReason = 
+/** No group to run, so no shard to start. */
+'nothing to run'
+/** The fewest shards whose setup and slowest share fit the budget. */
+ | 'within budget'
+/** One more shard would save less waiting than the setup it spends. */
+ | 'setup'
+/** The slowest group is the longest share already, and no shard finishes before it. */
+ | 'slowest group'
+/**
+ * The budget is no longer than the setup, which every shard spends before its
+ * first group, so no count meets it; the count is the one that finishes soonest.
+ */
+ | 'setup over budget'
+/** The most shards allowed. */
+ | 'max';
+export interface ShardCountOptions {
+    /** Milliseconds a shard spends before its first test: start, checkout, install, build. */
+    readonly setup: number;
+    /** Milliseconds one shard may take, setup included. */
+    readonly budget?: number;
+    /** The most shards to start. */
+    readonly max?: number;
+    /**
+     * How many groups one shard runs at once, its runner's workers: a shard is
+     * done when its share, divided among them, is, and never before its longest
+     * group. One when absent, a shard that runs its groups in turn.
+     */
+    readonly workers?: number;
+}
+export interface ShardCount {
+    readonly shards: number;
+    /** Milliseconds of groups each shard runs, shard 1 first, as {@link place} would place them. */
+    readonly load: readonly number[];
+    /** Milliseconds until the last shard finishes: the setup and the longest share, divided among its workers. */
+    readonly wall: number;
+    readonly why: ShardCountReason;
+    /** What one more shard would finish in, when the setup it spends is why it was not added. */
+    readonly next?: {
+        readonly wall: number;
+    };
+}
+/**
+ * GitHub Actions starts at most 256 jobs from one matrix, the largest limit
+ * any CI this tool is run on documents, so a count past it could not be used.
+ */
+export declare const MATRIX_LIMIT = 256;
+/**
+ * How many shards to split groups priced at `costs` milliseconds across.
+ *
+ * Every shard pays `setup` before it runs a group, so the wait is the setup
+ * plus the longest share. With a budget, the count is the fewest shards whose
+ * wait fits it. Without one, each shard is charged one setup, and the count is
+ * the one whose wait and setups come to least, the fewer of two that tie: a
+ * shard is worth starting when it shortens the wait by more than it spends.
+ * Every count is weighed, not only the next, because whole groups split
+ * unevenly: a third shard can save nothing where a fourth saves a lot. Either
+ * way the count stops where the longest share is the slowest group, because
+ * past that no shard finishes sooner. A budget no longer than the setup is met
+ * by no count, and the setup, not the slowest group, is why.
+ */
+export declare function shardCount(costs: readonly number[], options: ShardCountOptions): ShardCount;
+/** Milliseconds as a person reads them in a shard's line: `340 ms`, `9.0 s`. */
+export declare function durationText(milliseconds: number): string;
+//# sourceMappingURL=placement.d.ts.map

package/dist/shard/placement.js

@@ -0,0 +1,170 @@
+/**
+ * Which shard runs which group, and how many shards a suite is worth.
+ *
+ * A group is placed whole: every story of one file, every width of one route,
+ * every case of one test file loads the same modules, and split across
+ * machines each machine pays for them. Three rules decide where it goes:
+ *
+ * - **With recorded times, the time decides.** Groups go longest first to the
+ *   shard with the least time so far (LPT, within 4/3 of the best split). Ties
+ *   are broken by key in code-unit order, so the placement is a function of
+ *   the groups and their times and never of the order they were found in.
+ * - **A member nothing recorded is priced at the median of the recorded ones.**
+ *   A new file is a file, and pricing it at zero would stack every new one on
+ *   one shard.
+ * - **With nothing recorded, a checksum decides.** Each group goes to the shard
+ *   whose `sha256(key, shard)` is highest, which depends on the key and the
+ *   shard count alone, so adding a group moves no other.
+ *
+ * Every shard computes the whole placement and keeps its own part. Nothing is
+ * exchanged between shards, so two shards agree exactly when they were handed
+ * the same groups and the same times.
+ */
+import { sha256Hex } from '../format/sha256.js';
+import { codeUnitOrder } from '../segment/index.js';
+/**
+ * Each group's price: its members' recorded milliseconds, with the median of
+ * every recorded member standing in for one nothing recorded. Absent when no
+ * member of any group is recorded, because then there is no price to give.
+ */
+export function priced(groups) {
+    const known = groups.flatMap((group) => group.costs.filter((cost) => cost !== undefined));
+    if (known.length === 0)
+        return undefined;
+    const median = known.sort((a, b) => a - b)[Math.floor(known.length / 2)];
+    return groups.map((group) => group.costs.reduce((sum, cost) => sum + (cost ?? median), 0));
+}
+/** Place every group on one of `total` shards. */
+export function place(groups, total) {
+    const cost = priced(groups);
+    if (cost === undefined) {
+        return { owner: groups.map((group) => (total === 1 ? 1 : rendezvous(group.key, total))), by: 'checksum' };
+    }
+    const order = longestFirst(groups.map((group) => group.key), cost);
+    const { owner, load } = packed(order.map((index) => cost[index]), total);
+    const byGroup = Array.from({ length: groups.length }, () => 0);
+    order.forEach((index, at) => (byGroup[index] = owner[at]));
+    return { owner: byGroup, by: 'recorded cost', cost, load };
+}
+/**
+ * Group indices, longest first, ties by key in code-unit order: the order a
+ * shard's workers take its groups in, so one that finishes early takes the
+ * short ones at the end.
+ */
+export function longestFirst(keys, cost) {
+    return keys.map((_, index) => index).sort((a, b) => cost[b] - cost[a] || codeUnitOrder(keys[a], keys[b]));
+}
+/**
+ * GitHub Actions starts at most 256 jobs from one matrix, the largest limit
+ * any CI this tool is run on documents, so a count past it could not be used.
+ */
+export const MATRIX_LIMIT = 256;
+/**
+ * How many shards to split groups priced at `costs` milliseconds across.
+ *
+ * Every shard pays `setup` before it runs a group, so the wait is the setup
+ * plus the longest share. With a budget, the count is the fewest shards whose
+ * wait fits it. Without one, each shard is charged one setup, and the count is
+ * the one whose wait and setups come to least, the fewer of two that tie: a
+ * shard is worth starting when it shortens the wait by more than it spends.
+ * Every count is weighed, not only the next, because whole groups split
+ * unevenly: a third shard can save nothing where a fourth saves a lot. Either
+ * way the count stops where the longest share is the slowest group, because
+ * past that no shard finishes sooner. A budget no longer than the setup is met
+ * by no count, and the setup, not the slowest group, is why.
+ */
+export function shardCount(costs, options) {
+    if (costs.length === 0)
+        return { shards: 0, load: [], wall: 0, why: 'nothing to run' };
+    const sorted = [...costs].sort((a, b) => b - a);
+    const slowest = sorted[0];
+    const total = sorted.reduce((sum, cost) => sum + cost, 0);
+    const limit = Math.max(1, Math.min(options.max ?? MATRIX_LIMIT, sorted.length));
+    const workers = options.workers ?? 1;
+    const at = (shards) => {
+        const { load, first } = packed(sorted, shards);
+        const share = Math.max(...load.map((part, shard) => Math.max(part / workers, first[shard])));
+        return { shards, load, wall: options.setup + share };
+    };
+    const counted = (shards, why, next) => ({ ...shards, why, ...(next === undefined ? {} : { next: { wall: next.wall } }) });
+    const reached = (shards) => shards.wall - options.setup <= slowest;
+    if (options.budget !== undefined) {
+        // With no setup, the slowest group is what no count gets under, not the setup.
+        const unmet = options.setup > 0 && options.budget <= options.setup;
+        for (let here = at(1);; here = at(here.shards + 1)) {
+            if (here.wall <= options.budget)
+                return counted(here, 'within budget');
+            if (reached(here))
+                return counted(here, unmet ? 'setup over budget' : 'slowest group');
+            if (here.shards === limit)
+                return counted(here, unmet ? 'setup over budget' : 'max');
+        }
+    }
+    const spent = (shards) => shards.wall + options.setup * shards.shards;
+    let best = at(1);
+    for (let shards = 2; shards <= limit && !reached(best); shards++) {
+        // No split of `shards` waits less than the slowest group or an even share,
+        // and every count past this one spends more setup, so none can do better.
+        if (options.setup + Math.max(slowest, total / shards / workers) + options.setup * shards >= spent(best))
+            break;
+        const here = at(shards);
+        if (spent(here) < spent(best))
+            best = here;
+    }
+    if (reached(best))
+        return counted(best, 'slowest group');
+    if (best.shards === limit)
+        return counted(best, 'max');
+    return counted(best, 'setup', at(best.shards + 1));
+}
+/** Milliseconds as a person reads them in a shard's line: `340 ms`, `9.0 s`. */
+export function durationText(milliseconds) {
+    return milliseconds < 1000 ? `${Math.round(milliseconds)} ms` : `${(milliseconds / 1000).toFixed(1)} s`;
+}
+/**
+ * LPT over costs already sorted longest first: each to the shard with the
+ * least so far, the lowest-numbered of equals. `first` is each shard's
+ * longest group, the first it was given.
+ */
+function packed(sorted, total) {
+    const load = Array.from({ length: total }, () => 0);
+    const first = Array.from({ length: total }, () => 0);
+    // A binary heap of shard indices by (load, index), so a suite of tens of
+    // thousands of files is placed in n log k rather than n·k.
+    const heap = Array.from({ length: total }, (_, index) => index);
+    const before = (a, b) => load[a] < load[b] || (load[a] === load[b] && a < b);
+    const owner = sorted.map((cost) => {
+        const least = heap[0];
+        if (load[least] === 0)
+            first[least] = cost;
+        load[least] = load[least] + cost;
+        for (let at = 0;;) {
+            const left = 2 * at + 1;
+            const right = left + 1;
+            let next = at;
+            if (left < total && before(heap[left], heap[next]))
+                next = left;
+            if (right < total && before(heap[right], heap[next]))
+                next = right;
+            if (next === at)
+                break;
+            [heap[at], heap[next]] = [heap[next], heap[at]];
+            at = next;
+        }
+        return least + 1;
+    });
+    return { owner, load, first };
+}
+function rendezvous(key, total) {
+    let best = 1;
+    let bestScore = '';
+    for (let shard = 1; shard <= total; shard++) {
+        const score = sha256Hex(`${key}\0${shard}`);
+        if (score > bestScore) {
+            best = shard;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=placement.js.map

package/dist/shard/placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../../src/shard/placement.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which shard runs which group, and how many shards a suite is worth.\n *\n * A group is placed whole: every story of one file, every width of one route,\n * every case of one test file loads the same modules, and split across\n * machines each machine pays for them. Three rules decide where it goes:\n *\n * - **With recorded times, the time decides.** Groups go longest first to the\n *   shard with the least time so far (LPT, within 4/3 of the best split). Ties\n *   are broken by key in code-unit order, so the placement is a function of\n *   the groups and their times and never of the order they were found in.\n * - **A member nothing recorded is priced at the median of the recorded ones.**\n *   A new file is a file, and pricing it at zero would stack every new one on\n *   one shard.\n * - **With nothing recorded, a checksum decides.** Each group goes to the shard\n *   whose `sha256(key, shard)` is highest, which depends on the key and the\n *   shard count alone, so adding a group moves no other.\n *\n * Every shard computes the whole placement and keeps its own part. Nothing is\n * exchanged between shards, so two shards agree exactly when they were handed\n * the same groups and the same times.\n */\n\nimport { sha256Hex } from '../format/sha256.js';\nimport { codeUnitOrder } from '../segment/index.js';\n\n/** One group placed whole, and the milliseconds recorded for each of its members. */\nexport interface Placeable {\n  readonly key: string;\n  /** `undefined` for a member nothing recorded a time for. */\n  readonly costs: readonly (number | undefined)[];\n}\n\nexport interface Placement {\n  /** The shard, from 1, of each group in the order they were handed in. */\n  readonly owner: readonly number[];\n  readonly by: 'checksum' | 'recorded cost';\n  /** Milliseconds each group is priced at; absent when placed by checksum. */\n  readonly cost?: readonly number[];\n  /** Milliseconds each shard was given, shard 1 first; absent when placed by checksum. */\n  readonly load?: readonly number[];\n}\n\n/**\n * Each group's price: its members' recorded milliseconds, with the median of\n * every recorded member standing in for one nothing recorded. Absent when no\n * member of any group is recorded, because then there is no price to give.\n */\nexport function priced(groups: readonly Placeable[]): number[] | undefined {\n  const known = groups.flatMap((group) => group.costs.filter((cost): cost is number => cost !== undefined));\n  if (known.length === 0) return undefined;\n  const median = known.sort((a, b) => a - b)[Math.floor(known.length / 2)]!;\n  return groups.map((group) => group.costs.reduce<number>((sum, cost) => sum + (cost ?? median), 0));\n}\n\n/** Place every group on one of `total` shards. */\nexport function place(groups: readonly Placeable[], total: number): Placement {\n  const cost = priced(groups);\n  if (cost === undefined) {\n    return { owner: groups.map((group) => (total === 1 ? 1 : rendezvous(group.key, total))), by: 'checksum' };\n  }\n  const order = longestFirst(groups.map((group) => group.key), cost);\n  const { owner, load } = packed(order.map((index) => cost[index]!), total);\n  const byGroup: number[] = Array.from({ length: groups.length }, () => 0);\n  order.forEach((index, at) => (byGroup[index] = owner[at]!));\n  return { owner: byGroup, by: 'recorded cost', cost, load };\n}\n\n/**\n * Group indices, longest first, ties by key in code-unit order: the order a\n * shard's workers take its groups in, so one that finishes early takes the\n * short ones at the end.\n */\nexport function longestFirst(keys: readonly string[], cost: readonly number[]): number[] {\n  return keys.map((_, index) => index).sort((a, b) => cost[b]! - cost[a]! || codeUnitOrder(keys[a]!, keys[b]!));\n}\n\n/** Why a shard count is the one {@link shardCount} chose. */\nexport type ShardCountReason =\n  /** No group to run, so no shard to start. */\n  | 'nothing to run'\n  /** The fewest shards whose setup and slowest share fit the budget. */\n  | 'within budget'\n  /** One more shard would save less waiting than the setup it spends. */\n  | 'setup'\n  /** The slowest group is the longest share already, and no shard finishes before it. */\n  | 'slowest group'\n  /**\n   * The budget is no longer than the setup, which every shard spends before its\n   * first group, so no count meets it; the count is the one that finishes soonest.\n   */\n  | 'setup over budget'\n  /** The most shards allowed. */\n  | 'max';\n\nexport interface ShardCountOptions {\n  /** Milliseconds a shard spends before its first test: start, checkout, install, build. */\n  readonly setup: number;\n  /** Milliseconds one shard may take, setup included. */\n  readonly budget?: number;\n  /** The most shards to start. */\n  readonly max?: number;\n  /**\n   * How many groups one shard runs at once, its runner's workers: a shard is\n   * done when its share, divided among them, is, and never before its longest\n   * group. One when absent, a shard that runs its groups in turn.\n   */\n  readonly workers?: number;\n}\n\nexport interface ShardCount {\n  readonly shards: number;\n  /** Milliseconds of groups each shard runs, shard 1 first, as {@link place} would place them. */\n  readonly load: readonly number[];\n  /** Milliseconds until the last shard finishes: the setup and the longest share, divided among its workers. */\n  readonly wall: number;\n  readonly why: ShardCountReason;\n  /** What one more shard would finish in, when the setup it spends is why it was not added. */\n  readonly next?: { readonly wall: number };\n}\n\n/**\n * GitHub Actions starts at most 256 jobs from one matrix, the largest limit\n * any CI this tool is run on documents, so a count past it could not be used.\n */\nexport const MATRIX_LIMIT = 256;\n\n/**\n * How many shards to split groups priced at `costs` milliseconds across.\n *\n * Every shard pays `setup` before it runs a group, so the wait is the setup\n * plus the longest share. With a budget, the count is the fewest shards whose\n * wait fits it. Without one, each shard is charged one setup, and the count is\n * the one whose wait and setups come to least, the fewer of two that tie: a\n * shard is worth starting when it shortens the wait by more than it spends.\n * Every count is weighed, not only the next, because whole groups split\n * unevenly: a third shard can save nothing where a fourth saves a lot. Either\n * way the count stops where the longest share is the slowest group, because\n * past that no shard finishes sooner. A budget no longer than the setup is met\n * by no count, and the setup, not the slowest group, is why.\n */\nexport function shardCount(costs: readonly number[], options: ShardCountOptions): ShardCount {\n  if (costs.length === 0) return { shards: 0, load: [], wall: 0, why: 'nothing to run' };\n  const sorted = [...costs].sort((a, b) => b - a);\n  const slowest = sorted[0]!;\n  const total = sorted.reduce((sum, cost) => sum + cost, 0);\n  const limit = Math.max(1, Math.min(options.max ?? MATRIX_LIMIT, sorted.length));\n  const workers = options.workers ?? 1;\n  const at = (shards: number) => {\n    const { load, first } = packed(sorted, shards);\n    const share = Math.max(...load.map((part, shard) => Math.max(part / workers, first[shard]!)));\n    return { shards, load, wall: options.setup + share };\n  };\n  const counted = (shards: ReturnType<typeof at>, why: ShardCountReason, next?: ReturnType<typeof at>): ShardCount =>\n    ({ ...shards, why, ...(next === undefined ? {} : { next: { wall: next.wall } }) });\n  const reached = (shards: ReturnType<typeof at>) => shards.wall - options.setup <= slowest;\n\n  if (options.budget !== undefined) {\n    // With no setup, the slowest group is what no count gets under, not the setup.\n    const unmet = options.setup > 0 && options.budget <= options.setup;\n    for (let here = at(1); ; here = at(here.shards + 1)) {\n      if (here.wall <= options.budget) return counted(here, 'within budget');\n      if (reached(here)) return counted(here, unmet ? 'setup over budget' : 'slowest group');\n      if (here.shards === limit) return counted(here, unmet ? 'setup over budget' : 'max');\n    }\n  }\n\n  const spent = (shards: ReturnType<typeof at>) => shards.wall + options.setup * shards.shards;\n  let best = at(1);\n  for (let shards = 2; shards <= limit && !reached(best); shards++) {\n    // No split of `shards` waits less than the slowest group or an even share,\n    // and every count past this one spends more setup, so none can do better.\n    if (options.setup + Math.max(slowest, total / shards / workers) + options.setup * shards >= spent(best)) break;\n    const here = at(shards);\n    if (spent(here) < spent(best)) best = here;\n  }\n  if (reached(best)) return counted(best, 'slowest group');\n  if (best.shards === limit) return counted(best, 'max');\n  return counted(best, 'setup', at(best.shards + 1));\n}\n\n/** Milliseconds as a person reads them in a shard's line: `340 ms`, `9.0 s`. */\nexport function durationText(milliseconds: number): string {\n  return milliseconds < 1000 ? `${Math.round(milliseconds)} ms` : `${(milliseconds / 1000).toFixed(1)} s`;\n}\n\n/**\n * LPT over costs already sorted longest first: each to the shard with the\n * least so far, the lowest-numbered of equals. `first` is each shard's\n * longest group, the first it was given.\n */\nfunction packed(sorted: readonly number[], total: number): { owner: number[]; load: number[]; first: number[] } {\n  const load: number[] = Array.from({ length: total }, () => 0);\n  const first: number[] = Array.from({ length: total }, () => 0);\n  // A binary heap of shard indices by (load, index), so a suite of tens of\n  // thousands of files is placed in n log k rather than n·k.\n  const heap = Array.from({ length: total }, (_, index) => index);\n  const before = (a: number, b: number) => load[a]! < load[b]! || (load[a] === load[b] && a < b);\n  const owner = sorted.map((cost) => {\n    const least = heap[0]!;\n    if (load[least] === 0) first[least] = cost;\n    load[least] = load[least]! + cost;\n    for (let at = 0; ; ) {\n      const left = 2 * at + 1;\n      const right = left + 1;\n      let next = at;\n      if (left < total && before(heap[left]!, heap[next]!)) next = left;\n      if (right < total && before(heap[right]!, heap[next]!)) next = right;\n      if (next === at) break;\n      [heap[at], heap[next]] = [heap[next]!, heap[at]!];\n      at = next;\n    }\n    return least + 1;\n  });\n  return { owner, load, first };\n}\n\nfunction rendezvous(key: string, total: number): number {\n  let best = 1;\n  let bestScore = '';\n  for (let shard = 1; shard <= total; shard++) {\n    const score = sha256Hex(`${key}\\0${shard}`);\n    if (score > bestScore) {\n      best = shard;\n      bestScore = score;\n    }\n  }\n  return best;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@variance-authority/core",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "The Variance Authority format, rules, comparison, attribution and verdicts. Pure data in, pure data out, no DOM and no I/O.",
   "keywords": [
     "variance-authority",
@@ -62,6 +62,10 @@
     "./plan": {
       "types": "./dist/plan/index.d.ts",
       "default": "./dist/plan/index.js"
+    },
+    "./shard": {
+      "types": "./dist/shard/index.d.ts",
+      "default": "./dist/shard/index.js"
     }
   },
   "main": "./dist/index.js",
@@ -73,5 +77,8 @@
   ],
   "scripts": {
     "build": "tsc --build"
+  },
+  "devDependencies": {
+    "@variance-authority/sense": "^0.15.0"
   }
 }