@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/gates/suite.d.ts

@@ -0,0 +1,217 @@
+/**
+ * THE SUITE GATE (kernel plan M2, M2-P3).
+ *
+ * Replaces "the suite is green" with a machine-countable claim: the suite
+ * ran as configured, every discovered test file was reported, every
+ * registered behavior resolves to a reported test, no behavior registered
+ * at the merge base has been deleted, every skip carries a reason, the
+ * tree did not change under the run (M2-C-5 pin), and the counts come from
+ * a pinned structured stream plus the child's exit code and from nowhere
+ * else (C-1).
+ *
+ * HOW THE SUITE IS RUN. The repository's own `package.json` scripts.test
+ * is executed VERBATIM through `/bin/sh -c`, exactly as npm runs it. The
+ * gate never parses or reconstructs the script: deciding what another
+ * program will do by pattern-matching the text of a file it consumes is
+ * the mechanism MECHANISMS.md records four fix rounds for. What npm adds
+ * beyond sh -c (node_modules/.bin on PATH, lifecycle hooks) is not
+ * reproduced; a test script that depends on either fails LOUDLY here
+ * (the reporter stream never appears, which is `error`), never silently.
+ *
+ * THE REPORTER IS A PINNED, REQUESTED INPUT (M2-P3 step 2, MECHANISMS.md
+ * "Parsing another program's reporter output"). Measured on both installed
+ * toolchains (v22.22.2 and v26.6.0, work history m2-p3 step 1):
+ *
+ *   - tap carries NO file attribution for passing tests, so it cannot
+ *     support discovery parity or name the missing file;
+ *   - junit loses file attribution on nested tests and DROPS raw test
+ *     output, so a counterfeit line cannot be captured verbatim from it;
+ *   - the documented custom-reporter event stream carries file, name,
+ *     nesting, skip (with reason), todo, entity type and failureType for
+ *     every test on both toolchains, and delivers raw test output as
+ *     test:stdout/test:stderr events whose payload is a JSON string.
+ *
+ * So the gate pins `tiphys-suite-events-v1`: an NDJSON stream emitted by
+ * the reporter module below, embedded as a data: URL so the reporter
+ * cannot drift apart from the parser that consumes it. It is REQUESTED
+ * explicitly for the child via child-scoped NODE_OPTIONS; the inherited
+ * NODE_OPTIONS is deliberately dropped, because an inherited reporter
+ * option is precisely the ambient default the pin exists to exclude. The
+ * received stream is validated to be this format BEFORE any count is
+ * parsed: header first, every line a known event, explicit stream-end
+ * trailer last. A stream in any other format, or truncated, is `error`
+ * naming the expected and observed formats. Widening the parse to accept
+ * whichever format arrived is forbidden.
+ *
+ * WHY A COUNTERFEIT LINE CANNOT COUNT (C-1, criterion 6). A test body
+ * printing "pass 999", or even a byte-exact tiphys event line, arrives as
+ * a test:stdout EVENT whose text sits INSIDE a JSON string field, escaped
+ * by the reporter's own JSON.stringify. It cannot form an event line, so
+ * it cannot reach the arithmetic; it is captured verbatim in the evidence
+ * instead. The measured tap contrast is in the work history: there the
+ * same bytes land as `# pass 999`, byte-identical in grammar to the real
+ * `# pass 3` summary line below it.
+ *
+ * DISCOVERY PARITY (step 3, PR-106): candidates are enumerated by WALKING
+ * the declared test roots for the declared suffix, never by expanding the
+ * runner's own selection pattern, because the pattern is the thing that
+ * can be wrong and an enumeration sharing it cannot see that. Both
+ * directions are enforced: a walked file absent from the reporter and a
+ * reported file outside the walk are each parity failures naming the file.
+ *
+ * M2-C-6: every path this gate reads that it did not create goes through
+ * the delivered classifyEntry / readRegularFileIfPresent /
+ * refuseOpenForWrite from src/task.ts. The walk probes types before
+ * reading names' targets and throws on anything irregular, so a named
+ * pipe inside a declared root is `error` naming the path and type, never
+ * a hang.
+ *
+ * CHILD ENVIRONMENT, deterministic by construction: NODE_OPTIONS is
+ * replaced (see above) and NODE_TEST_CONTEXT/NODE_TEST_* are removed,
+ * because a nested `node --test` that inherits them switches to its
+ * child-of-a-runner protocol and reports nothing usable (measured by
+ * M1-P6; see test/exit-test-local.test.ts identityLessEnv).
+ */
+export declare const SUITE_GATE_ID = "suite";
+export declare const SUITE_UNIT_LABEL = "tests reported";
+export declare const REPORTER_NAME = "tiphys-suite-events-v1";
+export declare const STREAM_FILE = "suite-events.ndjson";
+export declare const STDOUT_FILE = "suite-stdout.txt";
+export declare const STDERR_FILE = "suite-stderr.txt";
+export declare const RAW_OUTPUT_FILE = "suite-raw-output.txt";
+export declare const COUNTS_FILE = "counts.json";
+export declare function reporterDataUrl(): string;
+/** One reported test point, decoded from the pinned stream. */
+export interface SuitePoint {
+    event: "test:pass" | "test:fail";
+    name: string;
+    file: string;
+    nesting: number;
+    skip?: boolean | string;
+    todo?: boolean | string;
+    entityType: "test" | "suite";
+    failureType?: string;
+}
+export interface SuiteStream {
+    /** process.version of the node that actually ran the suite. */
+    childNode: string;
+    points: SuitePoint[];
+    /** Raw test output, concatenated in stream order. Evidence, never data. */
+    rawOutput: string;
+}
+export type StreamParse = {
+    ok: true;
+    stream: SuiteStream;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validate that `body` is a tiphys-suite-events-v1 stream and decode it.
+ * The format is checked BEFORE any count is derived; a stream in another
+ * format, however valid in its own grammar, is a refusal naming both
+ * formats, never a widened parse.
+ */
+export declare function parseSuiteStream(body: string): StreamParse;
+/**
+ * THE MAPPING, recorded here once and restated in every counts.json
+ * (M2-P3 step 6, M2R-022). Buckets are mutually exclusive and each
+ * reported test lands in exactly one:
+ *
+ *   skipped     the point carries a skip marker (reason or bare)
+ *   todo        not skipped, carries a todo marker
+ *   didNotRun   test:fail with failureType cancelledByParent; this is the
+ *               one shape node itself counted under "# cancelled" in the
+ *               same measured run (work history step 1 finding 7). Every
+ *               other failureType, including testTimeoutFailure, ran and
+ *               failed, which is `fail`.
+ *   fail        any other test:fail
+ *   pass        any other test:pass
+ *
+ * `reported` counts points whose entityType is `test`, which reproduces
+ * node's own "# tests" semantics for every REAL test (measured: suites
+ * are not tests). This does NOT hold for a file that defines zero tests:
+ * node still emits one nesting-0 test:pass for it, entityType `test`,
+ * named after the file's own invocation path (CR-1306, fixed below by
+ * `isFileWrapperPhantom`; a prior version of this comment asserted the
+ * false generalization "file wrappers emit no pass/fail"). The identity
+ * pass + fail + skipped + todo + didNotRun == reported is asserted, and
+ * `discovered` is the independent walk's file set, tied to `reported` by
+ * the file-set equality check rather than by unit-mixing arithmetic.
+ */
+export declare const MAPPING_STATEMENT: string;
+/**
+ * CR-1306: a `.test.ts` file that defines ZERO tests is not silent. Node
+ * itself (measured on v22.22.2 and v26.6.0, both directions of the glob
+ * the repo's own test script uses) still emits exactly one nesting-0
+ * test:pass point for such a file, entityType `test`, whose `name` is the
+ * file's own path exactly AS IT WAS INVOKED. Counting that point as
+ * `entityType === "test"` like every other reported point (the mechanism
+ * `bucketPoints` and the discovery/registry filters below all shared)
+ * inflates `units` by one per emptied file, and because `units > 0` the
+ * M2-C-2 "never green by omission" rewrite in result.ts never triggers:
+ * a suite that ran zero real tests would report green.
+ *
+ * A real top-level test is ALSO nesting 0 and entityType `test` (measured:
+ * `describe()` wrappers are entityType `suite` and never collide), so
+ * nesting and entityType alone cannot distinguish the phantom from a real
+ * test. The one further fact that does, and the only one node offers, is
+ * the point's own name coinciding exactly with its file's identity; a real
+ * test can only produce that collision by deliberately naming itself after
+ * its own file, which this function accepts as the residual, documented
+ * non-coverage (see delivery/work-history/m2-p3.md fix round one
+ * derivation).
+ *
+ * CR-1410-1 (fix round two): the string this coincidence is compared
+ * against MUST be spelling-invariant, not one particular spelling. Round
+ * one compared `point.name === relative(cwd, point.file)`, which is a
+ * comparison between two DIFFERENT strings whenever the invocation spells
+ * the path other than relative-to-cwd; node names the phantom by the
+ * file's path exactly as invoked (measured, both toolchains, fix round two
+ * derivation in delivery/work-history/m2-p3.md step "fix round two"):
+ * relative glob, bare auto-discovery and a `./`-prefixed path all name it
+ * relatively, but an ABSOLUTE-path invocation names it absolutely, and
+ * `relative(cwd, point.file)` is always relative, so the comparison misses
+ * that spelling and the phantom is counted as a real test again -- the
+ * exact CR-1306 defect through a different spelling, and the gate cannot
+ * control the spelling because it reads the target repo's `scripts.test`
+ * verbatim (see the file header). The fix compares two REPRESENTATIONS OF
+ * THE SAME FILE instead of two spellings of a path: `resolve(cwd,
+ * point.name)` normalizes whatever spelling `name` carries (relative,
+ * `./`-prefixed, or already absolute -- `resolve` returns an absolute
+ * argument unchanged, measured) into the same absolute string `point.file`
+ * already is, so the equality is invariant across every spelling node
+ * produces it in, by construction rather than by enumeration.
+ *
+ * The fix filters the phantom out before ANY of the three counting sites
+ * that read `entityType === "test"` (bucketPoints, the discovery-parity
+ * reportedFiles set, and the registry-resolution reportedTestNames set) so
+ * an emptied file is not silently miscounted as a passing test; it instead
+ * falls out of `reportedFiles`, which the existing discovery-parity check
+ * (step 3, unchanged) already reports as "test file discovered by the walk
+ * but absent from the reporter" -- a red finding, never a counted green.
+ */
+export declare function isFileWrapperPhantom(point: SuitePoint, cwd: string): boolean;
+export interface SuiteCounts {
+    reported: number;
+    pass: number;
+    fail: number;
+    skipped: number;
+    todo: number;
+    didNotRun: number;
+}
+export declare function bucketPoints(points: SuitePoint[]): {
+    counts: SuiteCounts;
+    skipsWithoutReason: SuitePoint[];
+    failures: SuitePoint[];
+    cancelled: SuitePoint[];
+};
+/**
+ * Walk one declared root for files carrying the declared suffix. The walk
+ * never expands the runner's selection pattern; the roots and suffix are
+ * the declaration, and the walk is exhaustive under them. Fail closed on
+ * anything that is not a regular file or a real directory (M2-C-6): a
+ * named pipe inside a test root makes the gate `error`, never a hang.
+ */
+export declare function walkTestFiles(root: string, suffix: string): string[];
+export declare function runSuiteGate(argv: string[]): number;