@quiesco/protocol 0.2.0 → 0.4.0

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.
package/dist/index.d.ts CHANGED
@@ -10,4 +10,5 @@ export * from './matcher.js';
10
10
  export * from './messages.js';
11
11
  export * from './methods.js';
12
12
  export * from './webview.js';
13
+ export * from './run-events.js';
13
14
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC"}
package/dist/index.js CHANGED
@@ -10,4 +10,5 @@ export * from './matcher.js';
10
10
  export * from './messages.js';
11
11
  export * from './methods.js';
12
12
  export * from './webview.js';
13
+ export * from './run-events.js';
13
14
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC"}
@@ -0,0 +1,159 @@
1
+ /**
2
+ * Run events: what a test runner's Quiesco reporter tells the `quiesco` process while tests run (the
3
+ * progress bar and `quiesco ui`). Runner independent: the cucumber formatter, the Vitest reporter and
4
+ * the Jest reporter all map their own events onto these.
5
+ *
6
+ * Wire format: NDJSON (one JSON object per line) over a local socket whose address the CLI passes in
7
+ * the QUIESCO_EVENTS environment variable (a Unix socket path, or a `\\.\pipe\…` name on Windows).
8
+ * Without the variable a reporter sends nothing.
9
+ *
10
+ * Several connections may send events for one run: the reporter in the runner's main process, and
11
+ * test workers that add evidence (`test:evidence`). Tests are matched by `id`.
12
+ */
13
+ /** Bumped on any incompatible change to the run events. Sent in `hello`. */
14
+ export declare const RUN_EVENTS_PROTOCOL = 1;
15
+ /** Environment variable holding the socket address. */
16
+ export declare const RUN_EVENTS_ENV = "QUIESCO_EVENTS";
17
+ export type RunnerName = 'cucumber' | 'vitest' | 'jest';
18
+ /**
19
+ * - `pending`: cucumber, a pending step (Jest's skipped tests are sent as `skipped`).
20
+ * - `undefined`: cucumber, a step without a definition.
21
+ * - `notRun`: never finished (the run ended or was interrupted first). Set by the consumer, never sent.
22
+ */
23
+ export type TestStatus = 'passed' | 'failed' | 'skipped' | 'todo' | 'pending' | 'undefined' | 'notRun';
24
+ export interface TestRef {
25
+ /**
26
+ * Stable across runs of the same files: cucumber `uri:line`; Vitest its test id; Jest the file and
27
+ * the title path joined with NUL.
28
+ */
29
+ id: string;
30
+ /** Path relative to the project root, `/`-separated. */
31
+ file: string;
32
+ /** 1-based line of the test (the Examples row for a Scenario Outline), when the runner knows it. */
33
+ line?: number;
34
+ /** The test's own title. */
35
+ name: string;
36
+ /** Group titles and the test title, outermost first (cucumber: [feature, rule?, scenario]). */
37
+ path: readonly string[];
38
+ }
39
+ export interface RunError {
40
+ message: string;
41
+ stack?: string;
42
+ /** Expected / actual difference, already formatted by the runner. */
43
+ diff?: string;
44
+ }
45
+ export interface RunCounts {
46
+ passed: number;
47
+ failed: number;
48
+ skipped: number;
49
+ todo: number;
50
+ pending: number;
51
+ undefined: number;
52
+ notRun: number;
53
+ }
54
+ export interface RunEvents {
55
+ /** First event on every connection. */
56
+ hello: {
57
+ protocol: number;
58
+ runner: RunnerName;
59
+ runnerVersion?: string;
60
+ pid: number;
61
+ };
62
+ /**
63
+ * The run starts. `total` is what the runner knows at this point: exact for cucumber, an estimate for
64
+ * Vitest (static parse), the number of tests known so far for Jest (0). `files` are the test files.
65
+ */
66
+ 'run:start': {
67
+ total: number;
68
+ totalIsEstimate: boolean;
69
+ files: readonly string[];
70
+ workers?: number;
71
+ };
72
+ /** A better total (a file was collected). */
73
+ 'total:update': {
74
+ total: number;
75
+ totalIsEstimate: boolean;
76
+ };
77
+ 'file:start': {
78
+ file: string;
79
+ };
80
+ /** `error`: the file failed outside any test (syntax error, error while collecting, BeforeAll). */
81
+ 'file:end': {
82
+ file: string;
83
+ error?: RunError;
84
+ };
85
+ /** `worker`: 0-based index of the worker (device) running the test, when the runner tells. `startedAt`: epoch ms. */
86
+ 'test:start': {
87
+ test: TestRef;
88
+ worker?: number;
89
+ attempt: number;
90
+ startedAt: number;
91
+ };
92
+ 'test:end': {
93
+ test: TestRef;
94
+ status: Exclude<TestStatus, 'notRun'>;
95
+ durationMs: number;
96
+ error?: RunError;
97
+ /** The runner will run this test again (retry): do not count it yet. */
98
+ willRetry: boolean;
99
+ /** Console output of the test, when the runner keeps it per test. */
100
+ logs?: readonly {
101
+ stream: 'stdout' | 'stderr';
102
+ text: string;
103
+ }[];
104
+ worker?: number;
105
+ };
106
+ /** Quiesco evidence files of a failed test (absolute paths), sent from the worker that ran it. */
107
+ 'test:evidence': {
108
+ testId: string;
109
+ files: readonly string[];
110
+ };
111
+ /** An error outside any file (cucumber BeforeAll, Vitest unhandled errors). */
112
+ 'run:error': {
113
+ error: RunError;
114
+ };
115
+ 'run:end': {
116
+ success: boolean;
117
+ interrupted: boolean;
118
+ durationMs: number;
119
+ };
120
+ }
121
+ export type RunEventType = keyof RunEvents;
122
+ export type RunEvent = {
123
+ [K in RunEventType]: {
124
+ type: K;
125
+ } & RunEvents[K];
126
+ }[RunEventType];
127
+ export type RunEventOf<K extends RunEventType> = Extract<RunEvent, {
128
+ type: K;
129
+ }>;
130
+ export declare function isRunEvent(value: unknown): value is RunEvent;
131
+ /** One NDJSON line (with its newline). JSON.stringify never emits a raw newline. */
132
+ export declare function encodeRunEvent(event: RunEvent): string;
133
+ export interface RunEventDecoder {
134
+ /** Feed text as it arrives; complete lines are decoded at once. */
135
+ push(chunk: string): void;
136
+ /** The connection ended: decode a last line without its newline. */
137
+ end(): void;
138
+ }
139
+ /**
140
+ * Splits NDJSON text into events. Lines that are not JSON, or not a known event (a newer reporter),
141
+ * go to `onInvalid` and are skipped: a bad line never stops the stream.
142
+ */
143
+ export declare function createRunEventDecoder(onEvent: (event: RunEvent) => void, onInvalid?: (line: string, reason: string) => void): RunEventDecoder;
144
+ export declare function emptyCounts(): RunCounts;
145
+ /**
146
+ * The tests a runner would run, listed without running them (`quiesco list`, the UI's test tree). Ids
147
+ * match the run events' test ids. Vitest lists `test.each` once (its rows appear after a run).
148
+ */
149
+ export interface TestList {
150
+ runner: RunnerName;
151
+ files: readonly string[];
152
+ tests: readonly TestRef[];
153
+ /** Files that could not be listed (syntax error, error while collecting). */
154
+ errors: readonly {
155
+ file?: string;
156
+ message: string;
157
+ }[];
158
+ }
159
+ //# sourceMappingURL=run-events.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run-events.d.ts","sourceRoot":"","sources":["../src/run-events.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Run events: what a test runner's Quiesco reporter tells the `quiesco` process while tests run (the
3
+ * progress bar and `quiesco ui`). Runner independent: the cucumber formatter, the Vitest reporter and
4
+ * the Jest reporter all map their own events onto these.
5
+ *
6
+ * Wire format: NDJSON (one JSON object per line) over a local socket whose address the CLI passes in
7
+ * the QUIESCO_EVENTS environment variable (a Unix socket path, or a `\\.\pipe\…` name on Windows).
8
+ * Without the variable a reporter sends nothing.
9
+ *
10
+ * Several connections may send events for one run: the reporter in the runner's main process, and
11
+ * test workers that add evidence (`test:evidence`). Tests are matched by `id`.
12
+ */
13
+ /** Bumped on any incompatible change to the run events. Sent in `hello`. */
14
+ export const RUN_EVENTS_PROTOCOL = 1;
15
+ /** Environment variable holding the socket address. */
16
+ export const RUN_EVENTS_ENV = 'QUIESCO_EVENTS';
17
+ const RUN_EVENT_TYPES = new Set([
18
+ 'hello',
19
+ 'run:start',
20
+ 'total:update',
21
+ 'file:start',
22
+ 'file:end',
23
+ 'test:start',
24
+ 'test:end',
25
+ 'test:evidence',
26
+ 'run:error',
27
+ 'run:end',
28
+ ]);
29
+ export function isRunEvent(value) {
30
+ return typeof value === 'object' && value !== null && typeof value.type === 'string' && RUN_EVENT_TYPES.has(value.type);
31
+ }
32
+ /** One NDJSON line (with its newline). JSON.stringify never emits a raw newline. */
33
+ export function encodeRunEvent(event) {
34
+ return `${JSON.stringify(event)}\n`;
35
+ }
36
+ /**
37
+ * Splits NDJSON text into events. Lines that are not JSON, or not a known event (a newer reporter),
38
+ * go to `onInvalid` and are skipped: a bad line never stops the stream.
39
+ */
40
+ export function createRunEventDecoder(onEvent, onInvalid = () => { }) {
41
+ let buffer = '';
42
+ const line = (text) => {
43
+ if (text.trim() === '')
44
+ return;
45
+ let value;
46
+ try {
47
+ value = JSON.parse(text);
48
+ }
49
+ catch (e) {
50
+ onInvalid(text, e.message);
51
+ return;
52
+ }
53
+ if (isRunEvent(value))
54
+ onEvent(value);
55
+ else
56
+ onInvalid(text, 'not a known run event');
57
+ };
58
+ return {
59
+ push(chunk) {
60
+ buffer += chunk;
61
+ let i;
62
+ while ((i = buffer.indexOf('\n')) !== -1) {
63
+ const text = buffer.slice(0, i);
64
+ buffer = buffer.slice(i + 1);
65
+ line(text);
66
+ }
67
+ },
68
+ end() {
69
+ const rest = buffer;
70
+ buffer = '';
71
+ line(rest);
72
+ },
73
+ };
74
+ }
75
+ export function emptyCounts() {
76
+ return { passed: 0, failed: 0, skipped: 0, todo: 0, pending: 0, undefined: 0, notRun: 0 };
77
+ }
78
+ //# sourceMappingURL=run-events.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run-events.js","sourceRoot":"","sources":["../src/run-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAErC,uDAAuD;AACvD,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAiF/C,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAe;IACjE,OAAO;IACP,WAAW;IACX,cAAc;IACd,YAAY;IACZ,UAAU;IACV,YAAY;IACZ,UAAU;IACV,eAAe;IACf,WAAW;IACX,SAAS;CACV,CAAC,CAAC;AAEH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ,IAAI,eAAe,CAAC,GAAG,CAAE,KAA0B,CAAC,IAAI,CAAC,CAAC;AACxK,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,KAAe;IAC5C,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC;AACtC,CAAC;AASD;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAkC,EAAE,YAAoD,GAAG,EAAE,GAAE,CAAC;IACpI,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE;QAC5B,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO;QAC/B,IAAI,KAAc,CAAC;QACnB,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,SAAS,CAAC,IAAI,EAAG,CAAW,CAAC,OAAO,CAAC,CAAC;YACtC,OAAO;QACT,CAAC;QACD,IAAI,UAAU,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,KAAK,CAAC,CAAC;;YACjC,SAAS,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAC;IAChD,CAAC,CAAC;IACF,OAAO;QACL,IAAI,CAAC,KAAK;YACR,MAAM,IAAI,KAAK,CAAC;YAChB,IAAI,CAAS,CAAC;YACd,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;gBACzC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBAChC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBAC7B,IAAI,CAAC,IAAI,CAAC,CAAC;YACb,CAAC;QACH,CAAC;QACD,GAAG;YACD,MAAM,IAAI,GAAG,MAAM,CAAC;YACpB,MAAM,GAAG,EAAE,CAAC;YACZ,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AAC5F,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quiesco/protocol",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "Shared protocol types and constants between the Quiesco host and agent",
5
5
  "license": "MIT",
6
6
  "author": "h2nology",
package/src/index.ts CHANGED
@@ -10,3 +10,4 @@ export * from './matcher.js';
10
10
  export * from './messages.js';
11
11
  export * from './methods.js';
12
12
  export * from './webview.js';
13
+ export * from './run-events.js';
@@ -0,0 +1,178 @@
1
+ /**
2
+ * Run events: what a test runner's Quiesco reporter tells the `quiesco` process while tests run (the
3
+ * progress bar and `quiesco ui`). Runner independent: the cucumber formatter, the Vitest reporter and
4
+ * the Jest reporter all map their own events onto these.
5
+ *
6
+ * Wire format: NDJSON (one JSON object per line) over a local socket whose address the CLI passes in
7
+ * the QUIESCO_EVENTS environment variable (a Unix socket path, or a `\\.\pipe\…` name on Windows).
8
+ * Without the variable a reporter sends nothing.
9
+ *
10
+ * Several connections may send events for one run: the reporter in the runner's main process, and
11
+ * test workers that add evidence (`test:evidence`). Tests are matched by `id`.
12
+ */
13
+
14
+ /** Bumped on any incompatible change to the run events. Sent in `hello`. */
15
+ export const RUN_EVENTS_PROTOCOL = 1;
16
+
17
+ /** Environment variable holding the socket address. */
18
+ export const RUN_EVENTS_ENV = 'QUIESCO_EVENTS';
19
+
20
+ export type RunnerName = 'cucumber' | 'vitest' | 'jest';
21
+
22
+ /**
23
+ * - `pending`: cucumber, a pending step (Jest's skipped tests are sent as `skipped`).
24
+ * - `undefined`: cucumber, a step without a definition.
25
+ * - `notRun`: never finished (the run ended or was interrupted first). Set by the consumer, never sent.
26
+ */
27
+ export type TestStatus = 'passed' | 'failed' | 'skipped' | 'todo' | 'pending' | 'undefined' | 'notRun';
28
+
29
+ export interface TestRef {
30
+ /**
31
+ * Stable across runs of the same files: cucumber `uri:line`; Vitest its test id; Jest the file and
32
+ * the title path joined with NUL.
33
+ */
34
+ id: string;
35
+ /** Path relative to the project root, `/`-separated. */
36
+ file: string;
37
+ /** 1-based line of the test (the Examples row for a Scenario Outline), when the runner knows it. */
38
+ line?: number;
39
+ /** The test's own title. */
40
+ name: string;
41
+ /** Group titles and the test title, outermost first (cucumber: [feature, rule?, scenario]). */
42
+ path: readonly string[];
43
+ }
44
+
45
+ export interface RunError {
46
+ message: string;
47
+ stack?: string;
48
+ /** Expected / actual difference, already formatted by the runner. */
49
+ diff?: string;
50
+ }
51
+
52
+ export interface RunCounts {
53
+ passed: number;
54
+ failed: number;
55
+ skipped: number;
56
+ todo: number;
57
+ pending: number;
58
+ undefined: number;
59
+ notRun: number;
60
+ }
61
+
62
+ export interface RunEvents {
63
+ /** First event on every connection. */
64
+ hello: { protocol: number; runner: RunnerName; runnerVersion?: string; pid: number };
65
+ /**
66
+ * The run starts. `total` is what the runner knows at this point: exact for cucumber, an estimate for
67
+ * Vitest (static parse), the number of tests known so far for Jest (0). `files` are the test files.
68
+ */
69
+ 'run:start': { total: number; totalIsEstimate: boolean; files: readonly string[]; workers?: number };
70
+ /** A better total (a file was collected). */
71
+ 'total:update': { total: number; totalIsEstimate: boolean };
72
+ 'file:start': { file: string };
73
+ /** `error`: the file failed outside any test (syntax error, error while collecting, BeforeAll). */
74
+ 'file:end': { file: string; error?: RunError };
75
+ /** `worker`: 0-based index of the worker (device) running the test, when the runner tells. `startedAt`: epoch ms. */
76
+ 'test:start': { test: TestRef; worker?: number; attempt: number; startedAt: number };
77
+ 'test:end': {
78
+ test: TestRef;
79
+ status: Exclude<TestStatus, 'notRun'>;
80
+ durationMs: number;
81
+ error?: RunError;
82
+ /** The runner will run this test again (retry): do not count it yet. */
83
+ willRetry: boolean;
84
+ /** Console output of the test, when the runner keeps it per test. */
85
+ logs?: readonly { stream: 'stdout' | 'stderr'; text: string }[];
86
+ worker?: number;
87
+ };
88
+ /** Quiesco evidence files of a failed test (absolute paths), sent from the worker that ran it. */
89
+ 'test:evidence': { testId: string; files: readonly string[] };
90
+ /** An error outside any file (cucumber BeforeAll, Vitest unhandled errors). */
91
+ 'run:error': { error: RunError };
92
+ 'run:end': { success: boolean; interrupted: boolean; durationMs: number };
93
+ }
94
+
95
+ export type RunEventType = keyof RunEvents;
96
+ export type RunEvent = { [K in RunEventType]: { type: K } & RunEvents[K] }[RunEventType];
97
+ export type RunEventOf<K extends RunEventType> = Extract<RunEvent, { type: K }>;
98
+
99
+ const RUN_EVENT_TYPES: ReadonlySet<string> = new Set<RunEventType>([
100
+ 'hello',
101
+ 'run:start',
102
+ 'total:update',
103
+ 'file:start',
104
+ 'file:end',
105
+ 'test:start',
106
+ 'test:end',
107
+ 'test:evidence',
108
+ 'run:error',
109
+ 'run:end',
110
+ ]);
111
+
112
+ export function isRunEvent(value: unknown): value is RunEvent {
113
+ return typeof value === 'object' && value !== null && typeof (value as { type?: unknown }).type === 'string' && RUN_EVENT_TYPES.has((value as { type: string }).type);
114
+ }
115
+
116
+ /** One NDJSON line (with its newline). JSON.stringify never emits a raw newline. */
117
+ export function encodeRunEvent(event: RunEvent): string {
118
+ return `${JSON.stringify(event)}\n`;
119
+ }
120
+
121
+ export interface RunEventDecoder {
122
+ /** Feed text as it arrives; complete lines are decoded at once. */
123
+ push(chunk: string): void;
124
+ /** The connection ended: decode a last line without its newline. */
125
+ end(): void;
126
+ }
127
+
128
+ /**
129
+ * Splits NDJSON text into events. Lines that are not JSON, or not a known event (a newer reporter),
130
+ * go to `onInvalid` and are skipped: a bad line never stops the stream.
131
+ */
132
+ export function createRunEventDecoder(onEvent: (event: RunEvent) => void, onInvalid: (line: string, reason: string) => void = () => {}): RunEventDecoder {
133
+ let buffer = '';
134
+ const line = (text: string) => {
135
+ if (text.trim() === '') return;
136
+ let value: unknown;
137
+ try {
138
+ value = JSON.parse(text);
139
+ } catch (e) {
140
+ onInvalid(text, (e as Error).message);
141
+ return;
142
+ }
143
+ if (isRunEvent(value)) onEvent(value);
144
+ else onInvalid(text, 'not a known run event');
145
+ };
146
+ return {
147
+ push(chunk) {
148
+ buffer += chunk;
149
+ let i: number;
150
+ while ((i = buffer.indexOf('\n')) !== -1) {
151
+ const text = buffer.slice(0, i);
152
+ buffer = buffer.slice(i + 1);
153
+ line(text);
154
+ }
155
+ },
156
+ end() {
157
+ const rest = buffer;
158
+ buffer = '';
159
+ line(rest);
160
+ },
161
+ };
162
+ }
163
+
164
+ export function emptyCounts(): RunCounts {
165
+ return { passed: 0, failed: 0, skipped: 0, todo: 0, pending: 0, undefined: 0, notRun: 0 };
166
+ }
167
+
168
+ /**
169
+ * The tests a runner would run, listed without running them (`quiesco list`, the UI's test tree). Ids
170
+ * match the run events' test ids. Vitest lists `test.each` once (its rows appear after a run).
171
+ */
172
+ export interface TestList {
173
+ runner: RunnerName;
174
+ files: readonly string[];
175
+ tests: readonly TestRef[];
176
+ /** Files that could not be listed (syntax error, error while collecting). */
177
+ errors: readonly { file?: string; message: string }[];
178
+ }