@cleocode/core 2026.10.27 → 2026.11.1-canary.3

package/dist/tasks/test-report-counts.d.ts

@@ -0,0 +1,274 @@
+/**
+ * One reader for test-report counts, shared by `test-run:` evidence and typed
+ * test gates' `minCount` (T14124).
+ *
+ * The two paths used to parse reports separately: a typed gate refused a
+ * node:test event report with node-style counters (`tests`/`pass`/`fail`,
+ * no `numTotalTests`; VidaPeps T2373) whose shape `test-run:` read, and
+ * `test-run:` read JUnit, libtest and Playwright through adapters the gate
+ * never saw. {@link readTestReport}
+ * tries every format in {@link TEST_REPORT_FORMATS} order, adapts it to the
+ * vitest shape, and returns its counts under one set of integrity rules:
+ *
+ * - counts are non-negative integers that add up to the total;
+ * - when the report also lists per-test results, its counters must equal
+ *   them ({@link assertionDisagreement}) — a report whose counters contradict
+ *   its own assertions is not evidence.
+ *
+ * What each caller does with failures differs: `test-run:` refuses a report
+ * with any failure; a typed gate reads the counts and fails the gate.
+ *
+ * @module tasks/test-report-counts
+ * @task T14124
+ */
+import type { TestRunReport } from './test-run-binding.js';
+/**
+ * A report adapted to the vitest shape the binding and the counter checks
+ * read: Playwright JSON (T14031), JUnit XML and libtest JSON (T14084).
+ */
+export type AdaptedTestRun = {
+    readonly startTime?: number;
+    readonly testResults: Array<{
+        status: string;
+        name: string;
+        assertionResults: Array<{
+            status: string;
+        }>;
+    }>;
+    readonly numTotalTests: number;
+    readonly numPassedTests: number;
+    readonly numFailedTests: number;
+    readonly numPendingTests: number;
+    readonly numTodoTests: number;
+};
+/** An adapted report that cannot stand as test-run evidence, and why. */
+export interface AdaptedTestRunRefusal {
+    readonly refusal: string;
+    readonly codeName: 'E_EVIDENCE_INVALID' | 'E_EVIDENCE_TESTS_FAILED';
+}
+/** A Playwright JSON report in the vitest shape (T14031). */
+export type PlaywrightTestRun = AdaptedTestRun;
+/** A Playwright report that cannot stand as test-run evidence (T14031). */
+export type PlaywrightTestRunRefusal = AdaptedTestRunRefusal;
+/**
+ * Adapt a Playwright JSON report (`--reporter=json`) to the vitest shape, so
+ * an e2e spec can be test-run evidence (T14031); null when `report` is not
+ * one (no `suites` array and numeric `stats.expected`).
+ *
+ * The files run are the suites' `file`s (each spec's own `file` when set),
+ * resolved against `config.rootDir`, which Playwright makes them relative to.
+ * Counts come from the spec results, one per test and project: `expected`
+ * and `flaky` (passed on retry) pass, `unexpected` fails, `skipped` is
+ * pending. They must equal `stats`, and the run time is `stats.startTime`. A
+ * report listing top-level `errors` (no tests found, a config or global setup
+ * failure) is refused; the rest — vacuous, skipped-only or failing runs — is
+ * refused by the same checks as a vitest report.
+ *
+ * @param report - A parsed test-run report.
+ * @returns The adapted report, a refusal, or null when it is not Playwright's.
+ * @task T14031
+ */
+export declare function playwrightTestRun(report: Readonly<Record<string, unknown>>): PlaywrightTestRun | PlaywrightTestRunRefusal | null;
+/**
+ * Adapt a JUnit XML report to the vitest shape, so a runner without a JSON
+ * reporter can be test-run evidence (T14084): cargo nextest
+ * (`[profile.*.junit]`), pytest `--junitxml`, and most other runners; null
+ * when `text` is not JUnit XML (no `<testsuite` element).
+ *
+ * Each `<testcase>` is one test: a `<failure>` or `<error>` child fails it, a
+ * `<skipped>` child makes it pending, otherwise it passed. Its file is the
+ * testcase's `file` attribute, else its suite's, else the suite name (pytest
+ * xunit1 and Jest record files; nextest and pytest xunit2 name binaries and
+ * classes, which then cover no file). A `tests`, `failures`, `errors` or
+ * `skipped` total the report states must equal its testcases, and the run
+ * time is the earliest suite `timestamp`. Nested `<testsuite>` elements are
+ * refused rather than undercounted.
+ *
+ * @param text - The report file's text.
+ * @returns The adapted report, a refusal, or null when it is not JUnit XML.
+ * @task T14084
+ */
+export declare function junitTestRun(text: string): AdaptedTestRun | AdaptedTestRunRefusal | null;
+/**
+ * Adapt libtest JSON lines to the vitest shape (T14084): `cargo test --
+ * -Z unstable-options --format json --report-time`, or cargo nextest
+ * `--message-format libtest-json`; null when `text` is not libtest JSON (a
+ * line that is not a JSON object with `type` `suite` or `test`).
+ *
+ * Each finished `test` event is one test (`ok` passes, `failed` fails,
+ * `ignored` is pending). Tests are grouped by their binary, the name before a
+ * `$` (nextest) or `::`. Libtest names no files, so a report covers none. Each
+ * suite's `passed`/`failed`/`ignored` summary must equal its test events, and
+ * every `started` suite must finish with as many test events as its
+ * `test_count`: a killed run is refused as truncated, never read as complete.
+ * Suites are tracked per binary when nextest's `libtest-json-plus` names them
+ * (its suites of parallel binaries interleave); otherwise one at a time.
+ *
+ * @param text - The report file's text.
+ * @returns The adapted report, a refusal, or null when it is not libtest JSON.
+ * @task T14084
+ */
+export declare function libtestTestRun(text: string): AdaptedTestRun | AdaptedTestRunRefusal | null;
+/** A parsed `test-run:` report: the binding's fields plus whatever counters it carries. */
+export type TestRunReportJson = TestRunReport & Readonly<Record<string, unknown>>;
+/**
+ * The counter sets a `test-run:` report may carry (gh#1804), tried in order;
+ * the first whose total key is present is read. `failed` and `notRun` sum
+ * their keys, and an absent count is 0.
+ *
+ * | Shape | Total | Passed | Failed | Skipped / todo |
+ * |---|---|---|---|---|
+ * | vitest `--reporter=json`, jest `--json` | `numTotalTests` | `numPassedTests` | `numFailedTests` | `numPendingTests`, `numTodoTests` |
+ * | a runner's summary output (bun test, tsx --test) | `total` | `passed` | `failed` | `skipped`, `todo` |
+ * | node --test summary (`# tests`, `# pass`, ...) | `tests` | `pass` | `fail`, `cancelled` | `skipped`, `todo` |
+ *
+ * Integrity (T13136 review): every count is a non-negative integer;
+ * passed + failed + skipped/todo equals the total; a failure under ANY key
+ * ({@link TEST_RUN_FAILURE_KEYS}) is reported as `failure`, whichever set
+ * supplied the total, and `test-run:` refuses it;
+ * a report's `exit` / `exitCode` must be a number, and a non-zero one is
+ * refused. A `test-run:` atom proves only what its file says; `tool:test` and
+ * `ci:<pr>` are what prove the run. `cleo verify --help` documents the same
+ * sets.
+ *
+ * @task T13136
+ */
+export declare const TEST_RUN_COUNTER_SHAPES: readonly [{
+    readonly name: "vitest/jest";
+    readonly total: "numTotalTests";
+    readonly passed: "numPassedTests";
+    readonly failed: readonly ["numFailedTests"];
+    readonly notRun: readonly ["numPendingTests", "numTodoTests"];
+}, {
+    readonly name: "summary";
+    readonly total: "total";
+    readonly passed: "passed";
+    readonly failed: readonly ["failed"];
+    readonly notRun: readonly ["skipped", "todo"];
+}, {
+    readonly name: "node --test";
+    readonly total: "tests";
+    readonly passed: "pass";
+    readonly failed: readonly ["fail", "cancelled"];
+    readonly notRun: readonly ["skipped", "todo"];
+}];
+/** The keys of each counter set, as the refusals name them. */
+export declare const TEST_RUN_SHAPE_HINT: string;
+/** The counts a report states, and the counter set they came from. */
+export interface TestRunCounts {
+    readonly shape: (typeof TEST_RUN_COUNTER_SHAPES)[number];
+    readonly total: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly notRun: number;
+    /** A failure under any {@link TEST_RUN_FAILURE_KEYS} key (`numFailedTestSuites = 1`), when one is positive. */
+    readonly failure?: string;
+}
+/** A refusal while reading a report's counts. */
+export interface TestRunCountsRefusal {
+    readonly reason: string;
+    readonly codeName: 'E_EVIDENCE_INVALID' | 'E_EVIDENCE_TESTS_FAILED';
+}
+/** A present, non-null JSON value. */
+export declare const present: (value: unknown) => boolean;
+/**
+ * Read a report's counts from the first counter set it carries, enforcing
+ * their integrity; `null` when it carries none.
+ *
+ * @param report - A report in the vitest shape (adapted when it was another format).
+ * @returns The counts, an integrity refusal, or null when no counter set is present.
+ * @task T13136
+ * @task T14124
+ */
+export declare function reportCounts(report: TestRunReportJson): TestRunCounts | TestRunCountsRefusal | null;
+/**
+ * Adapt node:test TAP output (`node --test --test-reporter=tap`, also via
+ * `tsx --test`), which ships no JSON reporter (T14051), to the vitest shape. The run's LAST
+ * top-level plan (`1..N` at column 0) must be followed by its `# tests N`,
+ * `# pass N` and `# fail N` summary; `# cancelled N` counts as failed. Test
+ * console output is re-emitted as indented or `# ` comment lines before that
+ * plan, so it cannot forge the summary.
+ *
+ * TAP names no files, so the adapted report covers none.
+ *
+ * T14161: a file that declares no tests is reported as one passing top-level
+ * test named after the file (`ok 1 - smoke/empty.test.mjs`, `type: 'test'`,
+ * nothing nested), and its `# tests 1` passed `minCount: 1`. Node 22, 24 and
+ * 26 print that entry exactly like a real top-level test, so nothing in the
+ * TAP tells them apart. Given the run's `cwd`, an entry like that whose name
+ * is an existing file under `cwd` counts as zero tests. A file that failed to
+ * load is `not ok` and still counts as a failure.
+ *
+ * @param stdout - A run's captured stdout, or a TAP report file's text.
+ * @param options - `cwd`: the directory the run's file names resolve against.
+ * @returns The adapted report, a refusal, or null when the text is not TAP.
+ * @task T14051
+ * @task T14124
+ * @task T14161
+ */
+export declare function tapTestRun(stdout: string, options?: TestReportReadOptions): AdaptedTestRun | AdaptedTestRunRefusal | null;
+/** Options for reading a test report's text. */
+export interface TestReportReadOptions {
+    /** The directory the run's test file names resolve against (T14161). */
+    readonly cwd?: string;
+}
+/**
+ * Why a report's counters contradict its own per-test results, or null when
+ * they agree or it lists none (T14124). Counted over `testResults[].
+ * assertionResults[].status`: `passed`, `failed`, and every other status as
+ * not run. Applies to every counter set.
+ *
+ * @param report - A report in the vitest shape.
+ * @param counts - The counts read from its counter set.
+ * @returns The disagreement, or null.
+ * @task T14124
+ */
+export declare function assertionDisagreement(report: TestRunReportJson, counts: TestRunCounts): string | null;
+/** The report formats {@link readTestReport} tries, in order, as refusals name them. */
+export declare const TEST_REPORT_FORMATS: readonly ["JUnit XML", "Playwright JSON", "vitest/jest JSON", "runner summary JSON", "node --test summary JSON", "libtest JSON lines", "node:test TAP"];
+/** One of {@link TEST_REPORT_FORMATS}. */
+export type TestReportFormat = (typeof TEST_REPORT_FORMATS)[number];
+/** A report {@link readTestReport} read. */
+export interface ReadTestReport {
+    readonly ok: true;
+    /** The format it was read as. */
+    readonly format: TestReportFormat;
+    /** The report in the vitest shape. */
+    readonly report: TestRunReportJson;
+    /** Its counts. */
+    readonly counts: TestRunCounts;
+}
+/** A report {@link readTestReport} recognised but refused. */
+export interface RefusedTestReport {
+    readonly ok: false;
+    /** The format it was read as. */
+    readonly format: TestReportFormat;
+    readonly reason: string;
+    readonly codeName: 'E_EVIDENCE_INVALID' | 'E_EVIDENCE_TESTS_FAILED';
+}
+/**
+ * Read a parsed JSON report: Playwright, then a counter set (vitest/jest,
+ * runner summary, node --test summary; T14124).
+ *
+ * @param parsed - The parsed JSON value.
+ * @returns The read report, a refusal, or null when it is none of these.
+ * @task T14124
+ */
+export declare function readParsedTestReport(parsed: unknown): ReadTestReport | RefusedTestReport | null;
+/**
+ * Read a test report's text in any supported format (T14124): JUnit XML, a
+ * JSON report ({@link readParsedTestReport}), libtest JSON lines, or node:test
+ * TAP. Each is adapted to the vitest shape and counted under the same rules.
+ *
+ * @param text - The report's text (a file, or a run's captured output).
+ * @param options - `cwd`: where a TAP run's file names resolve (T14161).
+ * @returns The read report, a refusal, or null when no format matches.
+ * @example
+ * ```ts
+ * const read = readTestReport(readFileSync('report.json', 'utf-8'));
+ * if (read?.ok) console.log(read.format, read.counts.passed);
+ * ```
+ * @task T14124
+ */
+export declare function readTestReport(text: string, options?: TestReportReadOptions): ReadTestReport | RefusedTestReport | null;
+//# sourceMappingURL=test-report-counts.d.ts.map

package/dist/tasks/test-report-counts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-report-counts.d.ts","sourceRoot":"","sources":["../../src/tasks/test-report-counts.ts"],"names":[],"mappings":"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"}