@orkestrel/test 0.0.39 → 0.0.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -13,6 +13,7 @@ import type { TestModule } from 'vitest/node';
13
13
  import type { TestRunEndReason } from 'vitest/node';
14
14
  import type { TestSpecification } from 'vitest/node';
15
15
  import type { Vitest } from 'vitest/node';
16
+ import type { VitestPluginContext } from 'vitest/node';
16
17
  import type { WaitOptions } from '@orkestrel/test';
17
18
 
18
19
  /**
@@ -179,6 +180,33 @@ export declare function createLink(path: string, source: string): void;
179
180
  */
180
181
  export declare function createLoopback(server: Server): Promise<LoopbackInterface>;
181
182
 
183
+ /**
184
+ * Creates a Vitest plugin that adds one `ProgressReporter` to every run naming a progress file, so
185
+ * the reporter still runs when command-line `--reporter` flags replace the configured reporters.
186
+ *
187
+ * @remarks Mount the value in the root `plugins` of a configuration. Vitest calls its hook once per
188
+ * project that carries it, and the hook adds a reporter only while the run's reporters hold no
189
+ * `ProgressReporter` from any copy of this package, read by its `PROGRESS_BRAND` brand, so a run
190
+ * writes one `init` line wherever the plugin is mounted, a configuration that imports the package
191
+ * by a file path included. The hook adds
192
+ * a reporter when the resolved `outputFile` names `progress`, from `--outputFile.progress` or from
193
+ * the configuration's `outputFile`, and adds none otherwise, because `ProgressReporter` refuses to
194
+ * initialize without that file.
195
+ *
196
+ * @example
197
+ * ```ts
198
+ * import { defineConfig } from 'vitest/config'
199
+ * import { createProgressPlugin } from '@orkestrel/test/server'
200
+ *
201
+ * export default defineConfig({
202
+ * plugins: [createProgressPlugin()],
203
+ * test: { projects: [() => ({ test: { name: 'unit' } })] },
204
+ * })
205
+ * // npx vitest run --reporter=dot --outputFile.progress=tmp/runs/progress.jsonl
206
+ * ```
207
+ */
208
+ export declare function createProgressPlugin(): ProgressPluginInterface;
209
+
182
210
  /**
183
211
  * Allocates an owned temporary directory with contained file operations.
184
212
  *
@@ -431,11 +459,11 @@ export declare const isProgressError: Guard<ProgressError>;
431
459
  export declare const isProgressEvent: Guard<ProgressEvent>;
432
460
 
433
461
  /**
434
- * Reports whether a process id names a live process.
462
+ * Reports whether a process id names a live process, reading each of its threads on Linux.
435
463
  *
436
464
  * @param pid - The process id to read.
437
- * @returns True if a process holds that id at the moment of the call; false otherwise, including a
438
- * pid the host refuses.
465
+ * @returns True if a process holds that id at the moment of the call and, on Linux, one of its
466
+ * threads has not exited; false otherwise, including a pid the host refuses.
439
467
  * @throws Nothing. Every host refusal reads as false.
440
468
  * @remarks This is an instantaneous observation rather than a claim of ownership. A host reuses a
441
469
  * process id after the process holding it exits, so a true answer says some process holds that id at the time of the check
@@ -444,8 +472,14 @@ export declare const isProgressEvent: Guard<ProgressEvent>;
444
472
  * false here. A pid of `0` names the caller's own process group on POSIX and the system idle process
445
473
  * on Windows, so it reads as true on both without naming a process anyone started.
446
474
  *
447
- * A Linux zombie — a process that has exited and whose parent has not reaped it — still accepts
448
- * signal `0`, so its `/proc` status is read and a `Z` state reads as false.
475
+ * A signal reaches a Linux process that has exited but whose parent has not reaped it, so on Linux
476
+ * the answer also reads `/proc/<pid>/task`. The process has ended only when two readings taken one
477
+ * after the other list the same threads and every thread in both reads `Z` (exited) or `X` (dead).
478
+ * The leader thread's own state decides nothing: a process whose main thread has exited reads `Z`
479
+ * for its leader while another thread still runs, as a Node process does for milliseconds while its
480
+ * worker threads stop during exit, and it reads as true. A thread whose `stat` cannot be read has
481
+ * gone and counts as exited, and a process whose `task` directory cannot be listed reads as false.
482
+ * The thread table is Linux's layout, so every other host keeps the signal answer.
449
483
  *
450
484
  * @example
451
485
  * ```ts
@@ -519,6 +553,27 @@ export declare function matchesPlannedCase(test: {
519
553
  };
520
554
  }): boolean;
521
555
 
556
+ /**
557
+ * Checks whether a value is a progress reporter from any copy of this package, by the brand each
558
+ * one carries under `PROGRESS_BRAND`.
559
+ *
560
+ * @param value - The value to inspect, such as an entry of `vitest.config.reporters`.
561
+ * @returns True if the value holds an own `PROGRESS_BRAND` property whose value is the value
562
+ * itself; false otherwise, a value whose inspection throws included.
563
+ * @remarks A configuration that imports the package by a file path loads a separate copy of the
564
+ * module for each evaluation, so an `instanceof` check against one copy's class misses the
565
+ * reporters another copy made, and the brand recognizes them all.
566
+ *
567
+ * @example
568
+ * ```ts
569
+ * import { matchesProgressReporter, ProgressReporter } from '@orkestrel/test/server'
570
+ *
571
+ * matchesProgressReporter(new ProgressReporter()) // true
572
+ * matchesProgressReporter('dot') // false
573
+ * ```
574
+ */
575
+ export declare function matchesProgressReporter(value: unknown): boolean;
576
+
522
577
  /**
523
578
  * Normalizes a module or stack-frame path to the form a progress line carries.
524
579
  *
@@ -537,6 +592,12 @@ export declare function matchesPlannedCase(test: {
537
592
  */
538
593
  export declare function normalizeProgressPath(file: string, root: string): string;
539
594
 
595
+ /**
596
+ * Keys the brand every `ProgressReporter` carries, registered so that each copy of this package
597
+ * reads the same key.
598
+ */
599
+ export declare const PROGRESS_BRAND: unique symbol;
600
+
540
601
  /**
541
602
  * Names the label a rendered progress reading prints for each failure relation.
542
603
  */
@@ -697,20 +758,47 @@ export declare interface ProgressModuleEvent extends ProgressStamp {
697
758
  /** Names the state a finished module reports, mirroring Vitest's `TestModuleState`. */
698
759
  export declare type ProgressModuleState = 'passed' | 'failed' | 'skipped' | 'pending' | 'queued';
699
760
 
761
+ /** Represents the Vitest plugin that adds one progress reporter to every run naming a progress file. */
762
+ export declare interface ProgressPluginInterface {
763
+ /** Names the plugin to Vite. */
764
+ readonly name: string;
765
+ /**
766
+ * Adds a `ProgressReporter` to the run's reporters when `outputFile` names `progress`, and adds
767
+ * nothing when no progress file is named or the reporters already hold a `ProgressReporter` from
768
+ * any copy of this package.
769
+ *
770
+ * @remarks Mirrors the `configureVitest` hook of a Vitest plugin, which Vitest calls once per
771
+ * project that carries the plugin and before it constructs the run's reporters.
772
+ */
773
+ configureVitest(context: VitestPluginContext): void;
774
+ }
775
+
700
776
  /** Represents one project's tallies in a progress reading. */
701
777
  export declare interface ProgressProject {
702
778
  /** Names the Vitest project. */
703
779
  readonly name: string;
704
780
  /** Counts the cases the project's collected modules plan to report. */
705
781
  readonly planned: number;
706
- /** Counts the cases that reported a result. */
782
+ /**
783
+ * Counts the cases that reported a settled result: passed, failed, or skipped, the cases a bail's
784
+ * cancel skipped included.
785
+ */
707
786
  readonly done: number;
708
787
  /** Counts the cases that passed. */
709
788
  readonly passed: number;
710
789
  /** Counts the cases that failed and the modules that failed to collect. */
711
790
  readonly failed: number;
712
- /** Counts the planned cases that reported a skip at run time, a bail-cut case included. */
791
+ /**
792
+ * Counts the planned cases that reported a skip at run time. Under a bail, Vitest reports a skip
793
+ * for the case a module is running when the cancel arrives and for each case left after it in
794
+ * that module, and gives a reporter nothing that tells them from a case that skipped itself.
795
+ */
713
796
  readonly skipped: number;
797
+ /**
798
+ * Counts the planned cases that reported a `pending` result, which Vitest gives each case a bail
799
+ * leaves in a module that was running no case when the cancel arrived.
800
+ */
801
+ readonly pending: number;
714
802
  /** Counts the modules the run started for the project. */
715
803
  readonly modules: number;
716
804
  /** Counts the modules Vitest has collected for the project. */
@@ -740,6 +828,10 @@ export declare type ProgressRelation = 'first' | 'bail' | 'later';
740
828
  * Appends one JSON line per Vitest run event to the file `--outputFile.progress` names, so a live
741
829
  * run's progress and each failure's first error can be read before the run ends.
742
830
  *
831
+ * @remarks Only the first instance in `vitest.config.reporters` writes; a later instance in the same
832
+ * Vitest writes nothing, so a run is never counted twice. Each instance carries the
833
+ * `PROGRESS_BRAND` brand, so an instance from another copy of this package counts as earlier.
834
+ *
743
835
  * @example
744
836
  * ```ts
745
837
  * import { defineConfig } from 'vitest/config'
@@ -781,7 +873,10 @@ export declare interface ProgressRun {
781
873
  readonly bail: number;
782
874
  /** Holds the milliseconds the run has taken, up to its end or to the reading. */
783
875
  readonly elapsed: number;
784
- /** Counts the cases that reported a result, across every project. */
876
+ /**
877
+ * Counts the cases that reported a settled result across every project, the cases a bail's cancel
878
+ * skipped included.
879
+ */
785
880
  readonly done: number;
786
881
  /** Counts the cases the collected modules plan to report, across every project. */
787
882
  readonly planned: number;
@@ -790,7 +885,10 @@ export declare interface ProgressRun {
790
885
  * false otherwise.
791
886
  */
792
887
  readonly exact: boolean;
793
- /** Holds the results per minute since the first case started, or `undefined` before one. */
888
+ /**
889
+ * Holds the settled results per minute since the first case started, the cases a bail's cancel
890
+ * skipped included, or `undefined` before one.
891
+ */
794
892
  readonly rate: number | undefined;
795
893
  /**
796
894
  * Holds the estimated milliseconds left, or `undefined` once the run ended, before a rate exists,
@@ -13,6 +13,7 @@ import type { TestModule } from 'vitest/node';
13
13
  import type { TestRunEndReason } from 'vitest/node';
14
14
  import type { TestSpecification } from 'vitest/node';
15
15
  import type { Vitest } from 'vitest/node';
16
+ import type { VitestPluginContext } from 'vitest/node';
16
17
  import type { WaitOptions } from '@orkestrel/test';
17
18
 
18
19
  /**
@@ -179,6 +180,33 @@ export declare function createLink(path: string, source: string): void;
179
180
  */
180
181
  export declare function createLoopback(server: Server): Promise<LoopbackInterface>;
181
182
 
183
+ /**
184
+ * Creates a Vitest plugin that adds one `ProgressReporter` to every run naming a progress file, so
185
+ * the reporter still runs when command-line `--reporter` flags replace the configured reporters.
186
+ *
187
+ * @remarks Mount the value in the root `plugins` of a configuration. Vitest calls its hook once per
188
+ * project that carries it, and the hook adds a reporter only while the run's reporters hold no
189
+ * `ProgressReporter` from any copy of this package, read by its `PROGRESS_BRAND` brand, so a run
190
+ * writes one `init` line wherever the plugin is mounted, a configuration that imports the package
191
+ * by a file path included. The hook adds
192
+ * a reporter when the resolved `outputFile` names `progress`, from `--outputFile.progress` or from
193
+ * the configuration's `outputFile`, and adds none otherwise, because `ProgressReporter` refuses to
194
+ * initialize without that file.
195
+ *
196
+ * @example
197
+ * ```ts
198
+ * import { defineConfig } from 'vitest/config'
199
+ * import { createProgressPlugin } from '@orkestrel/test/server'
200
+ *
201
+ * export default defineConfig({
202
+ * plugins: [createProgressPlugin()],
203
+ * test: { projects: [() => ({ test: { name: 'unit' } })] },
204
+ * })
205
+ * // npx vitest run --reporter=dot --outputFile.progress=tmp/runs/progress.jsonl
206
+ * ```
207
+ */
208
+ export declare function createProgressPlugin(): ProgressPluginInterface;
209
+
182
210
  /**
183
211
  * Allocates an owned temporary directory with contained file operations.
184
212
  *
@@ -431,11 +459,11 @@ export declare const isProgressError: Guard<ProgressError>;
431
459
  export declare const isProgressEvent: Guard<ProgressEvent>;
432
460
 
433
461
  /**
434
- * Reports whether a process id names a live process.
462
+ * Reports whether a process id names a live process, reading each of its threads on Linux.
435
463
  *
436
464
  * @param pid - The process id to read.
437
- * @returns True if a process holds that id at the moment of the call; false otherwise, including a
438
- * pid the host refuses.
465
+ * @returns True if a process holds that id at the moment of the call and, on Linux, one of its
466
+ * threads has not exited; false otherwise, including a pid the host refuses.
439
467
  * @throws Nothing. Every host refusal reads as false.
440
468
  * @remarks This is an instantaneous observation rather than a claim of ownership. A host reuses a
441
469
  * process id after the process holding it exits, so a true answer says some process holds that id at the time of the check
@@ -444,8 +472,14 @@ export declare const isProgressEvent: Guard<ProgressEvent>;
444
472
  * false here. A pid of `0` names the caller's own process group on POSIX and the system idle process
445
473
  * on Windows, so it reads as true on both without naming a process anyone started.
446
474
  *
447
- * A Linux zombie — a process that has exited and whose parent has not reaped it — still accepts
448
- * signal `0`, so its `/proc` status is read and a `Z` state reads as false.
475
+ * A signal reaches a Linux process that has exited but whose parent has not reaped it, so on Linux
476
+ * the answer also reads `/proc/<pid>/task`. The process has ended only when two readings taken one
477
+ * after the other list the same threads and every thread in both reads `Z` (exited) or `X` (dead).
478
+ * The leader thread's own state decides nothing: a process whose main thread has exited reads `Z`
479
+ * for its leader while another thread still runs, as a Node process does for milliseconds while its
480
+ * worker threads stop during exit, and it reads as true. A thread whose `stat` cannot be read has
481
+ * gone and counts as exited, and a process whose `task` directory cannot be listed reads as false.
482
+ * The thread table is Linux's layout, so every other host keeps the signal answer.
449
483
  *
450
484
  * @example
451
485
  * ```ts
@@ -519,6 +553,27 @@ export declare function matchesPlannedCase(test: {
519
553
  };
520
554
  }): boolean;
521
555
 
556
+ /**
557
+ * Checks whether a value is a progress reporter from any copy of this package, by the brand each
558
+ * one carries under `PROGRESS_BRAND`.
559
+ *
560
+ * @param value - The value to inspect, such as an entry of `vitest.config.reporters`.
561
+ * @returns True if the value holds an own `PROGRESS_BRAND` property whose value is the value
562
+ * itself; false otherwise, a value whose inspection throws included.
563
+ * @remarks A configuration that imports the package by a file path loads a separate copy of the
564
+ * module for each evaluation, so an `instanceof` check against one copy's class misses the
565
+ * reporters another copy made, and the brand recognizes them all.
566
+ *
567
+ * @example
568
+ * ```ts
569
+ * import { matchesProgressReporter, ProgressReporter } from '@orkestrel/test/server'
570
+ *
571
+ * matchesProgressReporter(new ProgressReporter()) // true
572
+ * matchesProgressReporter('dot') // false
573
+ * ```
574
+ */
575
+ export declare function matchesProgressReporter(value: unknown): boolean;
576
+
522
577
  /**
523
578
  * Normalizes a module or stack-frame path to the form a progress line carries.
524
579
  *
@@ -537,6 +592,12 @@ export declare function matchesPlannedCase(test: {
537
592
  */
538
593
  export declare function normalizeProgressPath(file: string, root: string): string;
539
594
 
595
+ /**
596
+ * Keys the brand every `ProgressReporter` carries, registered so that each copy of this package
597
+ * reads the same key.
598
+ */
599
+ export declare const PROGRESS_BRAND: unique symbol;
600
+
540
601
  /**
541
602
  * Names the label a rendered progress reading prints for each failure relation.
542
603
  */
@@ -697,20 +758,47 @@ export declare interface ProgressModuleEvent extends ProgressStamp {
697
758
  /** Names the state a finished module reports, mirroring Vitest's `TestModuleState`. */
698
759
  export declare type ProgressModuleState = 'passed' | 'failed' | 'skipped' | 'pending' | 'queued';
699
760
 
761
+ /** Represents the Vitest plugin that adds one progress reporter to every run naming a progress file. */
762
+ export declare interface ProgressPluginInterface {
763
+ /** Names the plugin to Vite. */
764
+ readonly name: string;
765
+ /**
766
+ * Adds a `ProgressReporter` to the run's reporters when `outputFile` names `progress`, and adds
767
+ * nothing when no progress file is named or the reporters already hold a `ProgressReporter` from
768
+ * any copy of this package.
769
+ *
770
+ * @remarks Mirrors the `configureVitest` hook of a Vitest plugin, which Vitest calls once per
771
+ * project that carries the plugin and before it constructs the run's reporters.
772
+ */
773
+ configureVitest(context: VitestPluginContext): void;
774
+ }
775
+
700
776
  /** Represents one project's tallies in a progress reading. */
701
777
  export declare interface ProgressProject {
702
778
  /** Names the Vitest project. */
703
779
  readonly name: string;
704
780
  /** Counts the cases the project's collected modules plan to report. */
705
781
  readonly planned: number;
706
- /** Counts the cases that reported a result. */
782
+ /**
783
+ * Counts the cases that reported a settled result: passed, failed, or skipped, the cases a bail's
784
+ * cancel skipped included.
785
+ */
707
786
  readonly done: number;
708
787
  /** Counts the cases that passed. */
709
788
  readonly passed: number;
710
789
  /** Counts the cases that failed and the modules that failed to collect. */
711
790
  readonly failed: number;
712
- /** Counts the planned cases that reported a skip at run time, a bail-cut case included. */
791
+ /**
792
+ * Counts the planned cases that reported a skip at run time. Under a bail, Vitest reports a skip
793
+ * for the case a module is running when the cancel arrives and for each case left after it in
794
+ * that module, and gives a reporter nothing that tells them from a case that skipped itself.
795
+ */
713
796
  readonly skipped: number;
797
+ /**
798
+ * Counts the planned cases that reported a `pending` result, which Vitest gives each case a bail
799
+ * leaves in a module that was running no case when the cancel arrived.
800
+ */
801
+ readonly pending: number;
714
802
  /** Counts the modules the run started for the project. */
715
803
  readonly modules: number;
716
804
  /** Counts the modules Vitest has collected for the project. */
@@ -740,6 +828,10 @@ export declare type ProgressRelation = 'first' | 'bail' | 'later';
740
828
  * Appends one JSON line per Vitest run event to the file `--outputFile.progress` names, so a live
741
829
  * run's progress and each failure's first error can be read before the run ends.
742
830
  *
831
+ * @remarks Only the first instance in `vitest.config.reporters` writes; a later instance in the same
832
+ * Vitest writes nothing, so a run is never counted twice. Each instance carries the
833
+ * `PROGRESS_BRAND` brand, so an instance from another copy of this package counts as earlier.
834
+ *
743
835
  * @example
744
836
  * ```ts
745
837
  * import { defineConfig } from 'vitest/config'
@@ -781,7 +873,10 @@ export declare interface ProgressRun {
781
873
  readonly bail: number;
782
874
  /** Holds the milliseconds the run has taken, up to its end or to the reading. */
783
875
  readonly elapsed: number;
784
- /** Counts the cases that reported a result, across every project. */
876
+ /**
877
+ * Counts the cases that reported a settled result across every project, the cases a bail's cancel
878
+ * skipped included.
879
+ */
785
880
  readonly done: number;
786
881
  /** Counts the cases the collected modules plan to report, across every project. */
787
882
  readonly planned: number;
@@ -790,7 +885,10 @@ export declare interface ProgressRun {
790
885
  * false otherwise.
791
886
  */
792
887
  readonly exact: boolean;
793
- /** Holds the results per minute since the first case started, or `undefined` before one. */
888
+ /**
889
+ * Holds the settled results per minute since the first case started, the cases a bail's cancel
890
+ * skipped included, or `undefined` before one.
891
+ */
794
892
  readonly rate: number | undefined;
795
893
  /**
796
894
  * Holds the estimated milliseconds left, or `undefined` once the run ended, before a rate exists,
@@ -1,4 +1,4 @@
1
- import { arrayOf, isFunction, isNumber, isObject, isString, literalOf, recordOf, unionOf } from "@orkestrel/contract";
1
+ import { arrayOf, attempt, holds, isFunction, isNumber, isObject, isString, literalOf, recordOf, unionOf } from "@orkestrel/contract";
2
2
  import { Buffer } from "node:buffer";
3
3
  import { createHash } from "node:crypto";
4
4
  import { appendFileSync, closeSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
@@ -37,6 +37,11 @@ var PROGRESS_VERSION = 1;
37
37
  */
38
38
  var PROGRESS_MESSAGE_LIMIT = 300;
39
39
  /**
40
+ * Keys the brand every `ProgressReporter` carries, registered so that each copy of this package
41
+ * reads the same key.
42
+ */
43
+ var PROGRESS_BRAND = Symbol.for("@orkestrel/test.ProgressReporter");
44
+ /**
40
45
  * Names the label a rendered progress reading prints for each failure relation.
41
46
  */
42
47
  var PROGRESS_LABELS = Object.freeze({
@@ -458,11 +463,11 @@ function readInventory(root, targets, options) {
458
463
  return Object.fromEntries(Array.from(contents).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
459
464
  }
460
465
  /**
461
- * Reports whether a process id names a live process.
466
+ * Reports whether a process id names a live process, reading each of its threads on Linux.
462
467
  *
463
468
  * @param pid - The process id to read.
464
- * @returns True if a process holds that id at the moment of the call; false otherwise, including a
465
- * pid the host refuses.
469
+ * @returns True if a process holds that id at the moment of the call and, on Linux, one of its
470
+ * threads has not exited; false otherwise, including a pid the host refuses.
466
471
  * @throws Nothing. Every host refusal reads as false.
467
472
  * @remarks This is an instantaneous observation rather than a claim of ownership. A host reuses a
468
473
  * process id after the process holding it exits, so a true answer says some process holds that id at the time of the check
@@ -471,8 +476,14 @@ function readInventory(root, targets, options) {
471
476
  * false here. A pid of `0` names the caller's own process group on POSIX and the system idle process
472
477
  * on Windows, so it reads as true on both without naming a process anyone started.
473
478
  *
474
- * A Linux zombie — a process that has exited and whose parent has not reaped it — still accepts
475
- * signal `0`, so its `/proc` status is read and a `Z` state reads as false.
479
+ * A signal reaches a Linux process that has exited but whose parent has not reaped it, so on Linux
480
+ * the answer also reads `/proc/<pid>/task`. The process has ended only when two readings taken one
481
+ * after the other list the same threads and every thread in both reads `Z` (exited) or `X` (dead).
482
+ * The leader thread's own state decides nothing: a process whose main thread has exited reads `Z`
483
+ * for its leader while another thread still runs, as a Node process does for milliseconds while its
484
+ * worker threads stop during exit, and it reads as true. A thread whose `stat` cannot be read has
485
+ * gone and counts as exited, and a process whose `task` directory cannot be listed reads as false.
486
+ * The thread table is Linux's layout, so every other host keeps the signal answer.
476
487
  *
477
488
  * @example
478
489
  * ```ts
@@ -488,14 +499,23 @@ function isRunning(pid) {
488
499
  } catch {
489
500
  return false;
490
501
  }
491
- if (process.platform !== "linux") return true;
492
- try {
493
- const status = readFileSync(`/proc/${String(pid)}/stat`, "utf8");
494
- const boundary = status.lastIndexOf(") ");
495
- return boundary < 0 || status.slice(boundary + 2, boundary + 3) !== "Z";
496
- } catch {
497
- return false;
498
- }
502
+ if (process.platform !== "linux" || pid === 0) return true;
503
+ const directory = join("/proc", String(pid), "task");
504
+ const [first, second] = Array.from({ length: 2 }, () => {
505
+ const listing = attempt(() => readdirSync(directory));
506
+ return listing.success ? listing.value.flatMap((thread) => {
507
+ const status = attempt(() => readFileSync(join(directory, thread, "stat"), "utf8"));
508
+ if (!status.success) return [];
509
+ const boundary = status.value.lastIndexOf(") ");
510
+ return [{
511
+ thread,
512
+ state: boundary < 0 ? "" : status.value.slice(boundary + 2, boundary + 3)
513
+ }];
514
+ }) : void 0;
515
+ });
516
+ if (first === void 0 || second === void 0) return false;
517
+ const [listed, relisted] = [first, second].map((reading) => reading.map(({ thread }) => thread).toSorted().join(" "));
518
+ return listed !== relisted || [...first, ...second].some(({ state }) => state !== "Z" && state !== "X");
499
519
  }
500
520
  /**
501
521
  * Waits for a socket to close, accepting a peer reset as a forced close.
@@ -996,7 +1016,9 @@ async function chooseFiles(context, request) {
996
1016
  * ```
997
1017
  */
998
1018
  function normalizeProgressPath(file, root) {
999
- const path = relative(root, file.replace(/^\/@fs\//u, "")).replaceAll("\\", "/");
1019
+ const named = file.startsWith("/@fs/") ? file.slice(5) : file;
1020
+ const absolute = named === file || named.startsWith("/") || /^[a-z]:/iu.test(named) ? named : `/${named}`;
1021
+ const path = relative(root, absolute).replaceAll("\\", "/");
1000
1022
  return path === ".." || path.startsWith("../") || isAbsolute(path) ? file : path;
1001
1023
  }
1002
1024
  /**
@@ -1050,6 +1072,28 @@ function matchesPlannedCase(test) {
1050
1072
  return test.options.mode === "run" || test.options.mode === "only";
1051
1073
  }
1052
1074
  /**
1075
+ * Checks whether a value is a progress reporter from any copy of this package, by the brand each
1076
+ * one carries under `PROGRESS_BRAND`.
1077
+ *
1078
+ * @param value - The value to inspect, such as an entry of `vitest.config.reporters`.
1079
+ * @returns True if the value holds an own `PROGRESS_BRAND` property whose value is the value
1080
+ * itself; false otherwise, a value whose inspection throws included.
1081
+ * @remarks A configuration that imports the package by a file path loads a separate copy of the
1082
+ * module for each evaluation, so an `instanceof` check against one copy's class misses the
1083
+ * reporters another copy made, and the brand recognizes them all.
1084
+ *
1085
+ * @example
1086
+ * ```ts
1087
+ * import { matchesProgressReporter, ProgressReporter } from '@orkestrel/test/server'
1088
+ *
1089
+ * matchesProgressReporter(new ProgressReporter()) // true
1090
+ * matchesProgressReporter('dot') // false
1091
+ * ```
1092
+ */
1093
+ function matchesProgressReporter(value) {
1094
+ return holds(() => isObject(value) && Object.hasOwn(value, PROGRESS_BRAND) && Reflect.get(value, PROGRESS_BRAND) === value);
1095
+ }
1096
+ /**
1053
1097
  * Reads the bytes a file holds when it is opened, leaving out every byte appended during the read.
1054
1098
  *
1055
1099
  * @param path - The file to read.
@@ -1151,6 +1195,7 @@ function computeProgressRun(events, now) {
1151
1195
  const specifications = filterProgressEvents(own, "start").flatMap((start) => start.specifications);
1152
1196
  const collections = filterProgressEvents(own, "collected");
1153
1197
  const cases = filterProgressEvents(own, "case");
1198
+ const settled = cases.filter((entry) => entry.state !== "pending");
1154
1199
  const cancel = filterProgressEvents(own, "cancel").at(0);
1155
1200
  const end = filterProgressEvents(own, "end").at(0);
1156
1201
  const clock = end?.time ?? now - init.wall + init.time;
@@ -1164,19 +1209,20 @@ function computeProgressRun(events, now) {
1164
1209
  return {
1165
1210
  name,
1166
1211
  planned: collected.reduce((total, entry) => total + entry.planned, 0),
1167
- done: results.length,
1212
+ done: results.filter((entry) => entry.state !== "pending").length,
1168
1213
  passed: results.filter((entry) => entry.state === "passed").length,
1169
1214
  failed: results.filter((entry) => entry.state === "failed").length + collected.filter((entry) => entry.errors.length > 0).length,
1170
1215
  skipped: results.filter((entry) => entry.state === "skipped").length,
1216
+ pending: results.filter((entry) => entry.state === "pending").length,
1171
1217
  modules: specifications.filter((entry) => entry.project === name).length,
1172
1218
  collected: collected.length
1173
1219
  };
1174
1220
  });
1175
1221
  const planned = projects.reduce((total, project) => total + project.planned, 0);
1176
1222
  const exact = specifications.length > 0 && projects.every((project) => project.collected >= project.modules);
1177
- const first = cases.at(0);
1223
+ const first = settled.at(0);
1178
1224
  const span = first === void 0 ? 0 : clock - (first.time - (first.duration ?? 0));
1179
- const rate = cases.length > 0 && span > 0 ? cases.length / span * 6e4 : void 0;
1225
+ const rate = settled.length > 0 && span > 0 ? settled.length / span * 6e4 : void 0;
1180
1226
  const finished = new Set(cases.map((entry) => entry.id));
1181
1227
  const position = cancel === void 0 ? -1 : own.indexOf(cancel);
1182
1228
  const trigger = own.find((event) => event.event === "case" && event.state === "failed");
@@ -1200,11 +1246,11 @@ function computeProgressRun(events, now) {
1200
1246
  state: end?.reason ?? "live",
1201
1247
  bail: init.bail,
1202
1248
  elapsed: clock,
1203
- done: cases.length,
1249
+ done: settled.length,
1204
1250
  planned,
1205
1251
  exact,
1206
1252
  rate,
1207
- remaining: end === void 0 && exact && rate !== void 0 ? Math.max(0, (planned - cases.length) / rate * 6e4) : void 0,
1253
+ remaining: end === void 0 && exact && rate !== void 0 ? Math.max(0, (planned - settled.length) / rate * 6e4) : void 0,
1208
1254
  projects,
1209
1255
  running: end === void 0 ? filterProgressEvents(own, "ready").filter((ready) => !finished.has(ready.id)).map((ready) => ({
1210
1256
  project: ready.project,
@@ -1310,7 +1356,7 @@ function renderProgress(runs) {
1310
1356
  const width = Math.max(0, ...run.projects.map((project) => project.name.length));
1311
1357
  return [
1312
1358
  `run ${run.pid} ${run.state} ${run.bail === 0 ? "full" : `bail=${run.bail}`}: ${run.done}/${run.planned}${run.exact ? "" : "+"} cases, elapsed ${renderDuration(run.elapsed)}, rate ${run.rate === void 0 ? "-" : `${run.rate.toFixed(1)}/min`}, ETA ${run.remaining === void 0 ? "-" : renderDuration(run.remaining)}`,
1313
- ...run.projects.map((project) => ` ${project.name.padEnd(width)} ${project.done}/${project.planned} passed ${project.passed} failed ${project.failed} skipped ${project.skipped}${project.collected < project.modules ? ` (${project.collected}/${project.modules} modules collected)` : ""}`),
1359
+ ...run.projects.map((project) => ` ${project.name.padEnd(width)} ${project.done}/${project.planned} passed ${project.passed} failed ${project.failed} skipped ${project.skipped}${project.pending > 0 ? ` pending ${project.pending}` : ""}${project.collected < project.modules ? ` (${project.collected}/${project.modules} modules collected)` : ""}`),
1314
1360
  ...run.running.map((entry) => ` running ${renderDuration(entry.duration)} [${entry.project}] ${entry.name}`),
1315
1361
  ...run.cancel === void 0 ? [] : [` cancelled (${run.cancel.reason}) at ${renderDuration(run.cancel.time)}`],
1316
1362
  ...[...run.failures.map((failure) => ({
@@ -1557,6 +1603,10 @@ function createCookieJar() {
1557
1603
  * Appends one JSON line per Vitest run event to the file `--outputFile.progress` names, so a live
1558
1604
  * run's progress and each failure's first error can be read before the run ends.
1559
1605
  *
1606
+ * @remarks Only the first instance in `vitest.config.reporters` writes; a later instance in the same
1607
+ * Vitest writes nothing, so a run is never counted twice. Each instance carries the
1608
+ * `PROGRESS_BRAND` brand, so an instance from another copy of this package counts as earlier.
1609
+ *
1560
1610
  * @example
1561
1611
  * ```ts
1562
1612
  * import { defineConfig } from 'vitest/config'
@@ -1579,12 +1629,15 @@ var ProgressReporter = class {
1579
1629
  #overhead = 0;
1580
1630
  constructor() {
1581
1631
  this.#listener = this.#cancel.bind(this);
1632
+ Object.defineProperty(this, PROGRESS_BRAND, { value: this });
1582
1633
  }
1583
1634
  onInit(vitest) {
1584
1635
  this.#measure(() => {
1585
1636
  const output = vitest.config.outputFile;
1586
1637
  const named = typeof output === "object" ? output.progress : void 0;
1587
1638
  if (named === void 0) throw new Error("ProgressReporter writes no file: pass --outputFile.progress=<file>, or set outputFile: { progress: <file> } in the test config");
1639
+ const writer = vitest.config.reporters.find((entry) => matchesProgressReporter(entry));
1640
+ if (writer !== void 0 && writer !== this) return;
1588
1641
  this.#vitest = vitest;
1589
1642
  this.#path = resolve(vitest.config.root, named);
1590
1643
  mkdirSync(dirname(this.#path), { recursive: true });
@@ -1716,6 +1769,43 @@ var ProgressReporter = class {
1716
1769
  appendFileSync(this.#path, `${JSON.stringify(event)}\n`);
1717
1770
  }
1718
1771
  };
1719
- export { PROGRESS_LABELS, PROGRESS_MESSAGE_LIMIT, PROGRESS_VERSION, ProgressReporter, REMOVE_TREE_MAX_ATTEMPTS, REMOVE_TREE_RETRYABLE_CODES, REMOVE_TREE_RETRY_DELAY_MS, alignLoopClock, chooseFiles, computeProgress, computeProgressRun, createCookieJar, createLink, createLoopback, createScratch, destroyScratch, extractProgressError, extractProgressEvents, filterProgressEvents, hasScratchPath, isExcluded, isProgressError, isProgressEvent, isRunning, matchesIdentity, matchesPlannedCase, normalizeProgressPath, readCapture, readErrorCode, readFileSnapshot, readIdentity, readInventory, readLoopClock, readProgress, removeTree, renderDuration, renderProgress, requestUpgrade, requireContained, resolveContained, supportsBytes, supportsCase, supportsDirectoryLinks, supportsFileLinks, supportsMode, waitForSocketClose };
1772
+ // src/server/plugins.ts
1773
+ /**
1774
+ * Creates a Vitest plugin that adds one `ProgressReporter` to every run naming a progress file, so
1775
+ * the reporter still runs when command-line `--reporter` flags replace the configured reporters.
1776
+ *
1777
+ * @remarks Mount the value in the root `plugins` of a configuration. Vitest calls its hook once per
1778
+ * project that carries it, and the hook adds a reporter only while the run's reporters hold no
1779
+ * `ProgressReporter` from any copy of this package, read by its `PROGRESS_BRAND` brand, so a run
1780
+ * writes one `init` line wherever the plugin is mounted, a configuration that imports the package
1781
+ * by a file path included. The hook adds
1782
+ * a reporter when the resolved `outputFile` names `progress`, from `--outputFile.progress` or from
1783
+ * the configuration's `outputFile`, and adds none otherwise, because `ProgressReporter` refuses to
1784
+ * initialize without that file.
1785
+ *
1786
+ * @example
1787
+ * ```ts
1788
+ * import { defineConfig } from 'vitest/config'
1789
+ * import { createProgressPlugin } from '@orkestrel/test/server'
1790
+ *
1791
+ * export default defineConfig({
1792
+ * plugins: [createProgressPlugin()],
1793
+ * test: { projects: [() => ({ test: { name: 'unit' } })] },
1794
+ * })
1795
+ * // npx vitest run --reporter=dot --outputFile.progress=tmp/runs/progress.jsonl
1796
+ * ```
1797
+ */
1798
+ function createProgressPlugin() {
1799
+ return {
1800
+ name: "orkestrel:progress",
1801
+ configureVitest({ vitest }) {
1802
+ const output = vitest.config.outputFile;
1803
+ if (typeof output !== "object" || output.progress === void 0) return;
1804
+ if (vitest.config.reporters.some((entry) => matchesProgressReporter(entry))) return;
1805
+ vitest.config.reporters.push(new ProgressReporter());
1806
+ }
1807
+ };
1808
+ }
1809
+ export { PROGRESS_BRAND, PROGRESS_LABELS, PROGRESS_MESSAGE_LIMIT, PROGRESS_VERSION, ProgressReporter, REMOVE_TREE_MAX_ATTEMPTS, REMOVE_TREE_RETRYABLE_CODES, REMOVE_TREE_RETRY_DELAY_MS, alignLoopClock, chooseFiles, computeProgress, computeProgressRun, createCookieJar, createLink, createLoopback, createProgressPlugin, createScratch, destroyScratch, extractProgressError, extractProgressEvents, filterProgressEvents, hasScratchPath, isExcluded, isProgressError, isProgressEvent, isRunning, matchesIdentity, matchesPlannedCase, matchesProgressReporter, normalizeProgressPath, readCapture, readErrorCode, readFileSnapshot, readIdentity, readInventory, readLoopClock, readProgress, removeTree, renderDuration, renderProgress, requestUpgrade, requireContained, resolveContained, supportsBytes, supportsCase, supportsDirectoryLinks, supportsFileLinks, supportsMode, waitForSocketClose };
1720
1810
 
1721
1811
  //# sourceMappingURL=index.js.map