Skip to content
Merged
7 changes: 7 additions & 0 deletions .changeset/gap-cli-internal-error-prefix.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@tanstack/oracles': patch
---

The `oracle-gaps` CLI's internal error now prints one prefixed line, `oracle-gaps: error <message>: a bug in oracle-gaps, not in your oracle; its stack is in <path>`, before its `oracle-gaps: done error, log <path>` line. Before, its two message lines had no `oracle-gaps:` prefix. A line break in the message prints as an escape, so the message stays on one line. The stack stays in `error.log`, and the exit code stays 3.

A path that a stream line names, such as the output directory in a done line or a note, now prints a line break or another control character as its `\uXXXX` escape, so a directory name cannot split the line.
23 changes: 15 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,17 +115,24 @@ agent.
| `summary` | `oracle-gaps: summary <run id>: 120 mutants, 98 killed, 12 gaps, 10 unowned (warnings). …` |
| `legend` | `oracle-gaps: legend <class>: <what it means and what to do>`, once for each class of gap the run found |
| `function` | `oracle-gaps: function fn <name> (<source>) (owners: <files>)`, the heading over that function's gap lines |
| `error` | `oracle-gaps: error <message>: a bug in oracle-gaps, not in your oracle; its stack is in <path>/error.log`, once, before the done line of an internal error |
| `done` (last) | `oracle-gaps: done completed, 12 gaps, report <path>/summary.md` (`(provisional)` after the count when an oracle file failed), `oracle-gaps: done refused[, report <path>]`, `oracle-gaps: done error, log <path>`, or `oracle-gaps: done stopped (SIGINT)` |

Only two kinds of line have no prefix: the lines indented under a failing
baseline file (`failing:`, `law:`, `counterexample:`, `replay:`), and a
refusal's `refused:` and `fix:` block on stderr. No line is blank. The
Only these lines have no prefix: the lines indented under a failing
baseline file (`failing:`, `law:`, `counterexample:`, `replay:`), a
refusal's `refused:` and `fix:` block on stderr, `--help`'s usage text,
and lines that Node, V8, esbuild, or Vite print on the CLI's streams
(a warning, V8's out-of-memory block, esbuild's error block). The CLI
writes no blank line of its own. A path in a line, such as the output
directory, prints a line break or another control character as its
`\uXXXX` escape, so it cannot end the line. The
done line is the last line of both stdout and stderr, once each, for
every ending, and its status matches the exit code. A test's own output
to the process's stdout and stderr goes to `test-output.log` in the output
directory, which a note names; `summary.md` holds the report for reading.
A run through the daemon prints the same lines, at the end of its check.
`--help` is not a check, so its usage text has no prefix.
`--help` is not a check, so its usage text has no prefix and no done
line. `--stop-daemon` prints nothing.

For contributors: the `ORACLE_GAPS_TEST_` environment variables are test-only
hooks for the CLI's own oracle, not settings for users. Each is inert unless
Expand Down Expand Up @@ -168,11 +175,11 @@ agent.
SIGABRT), the CLI writes `oracle-gaps: done error, the run's process
exited with <signal or code>` and exits 3; after an out-of-memory crash
the line says to give Node more memory (`NODE_OPTIONS=--max-old-space-size=<MB>`)
or to run fewer `--contexts`. An internal error's own message lines
(`oracle-gaps internal error: …`) have no prefix. A config's syntax error
or to run fewer `--contexts`. An internal error prints one
`oracle-gaps: error` line with its message, its line breaks escaped,
and its stack goes to `error.log`. A config's syntax error
is refused with its first error; a syntax error in a module the config
imports still lets esbuild print its own error block, which has no
prefix.
imports lets esbuild print its own error block before the refusal.

Exit codes: 0 the check completed, whatever its gaps (its last line is
`oracle-gaps: done completed, …`); 2 the run was refused, with `refused:`
Expand Down
2 changes: 1 addition & 1 deletion packages/oracles/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,4 +29,4 @@ Under the hook, each check also writes `check.pid` (the id of the process that r
- For a settled or rejected batch: `after` (the sizes after its copies are retired), `copyNodes` (Vite module nodes that still name a copy, must be 0), and `nonCopyDup` (non-copy files with more than one module node in an environment, must be 0 beyond the measured plain-plus-`?raw` pair).
- For a cut batch: `cut: true` and no `after`. Its context is replaced, not retired.

`ORACLE_GAPS_TEST_REJECT_BATCH` (a batch number from 1, unset in normal use) makes the gap CLI's n-th batch run reject, as a crash in Vitest would. It is a test-only fault: the batch's run completes, so its copies are in Vitest's and Vite's state, and then the run's promise rejects, which takes the same path a real crash takes. The run then ends as an internal error: exit 3, the done error line, and `error.log` in its output directory. The batch's copies are still retired and its retention line is still written.
`ORACLE_GAPS_TEST_REJECT_BATCH` (a batch number from 1, unset in normal use) makes the gap CLI's n-th batch run reject, as a crash in Vitest would. Its message holds a line break and a line after it that reads as a done line, so the CLI's ending must keep the message on its one error line. It is a test-only fault: the batch's run completes, so its copies are in Vitest's and Vite's state, and then the run's promise rejects, which takes the same path a real crash takes. The run then ends as an internal error: exit 3, the done error line, and `error.log` in its output directory. The batch's copies are still retired and its retention line is still written.
12 changes: 9 additions & 3 deletions packages/oracles/oracle-gaps/check.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ import {
import {
baselineLines,
blockedLines,
escapeControls,
gapLine,
progressLine,
streamLine,
Expand Down Expand Up @@ -191,7 +192,7 @@ function captureLines(capture, { partial = false } = {}) {
const end = text.lastIndexOf(`\n`) + 1
if (!partial && end !== text.length)
throw new Error(
`oracle-gaps internal error: the capture ${capture} ends in a row with no newline after its run finished`,
`the capture ${capture} ends in a row with no newline after its run finished`,
)
return text.slice(0, end).split(`\n`).filter(Boolean)
}
Expand Down Expand Up @@ -2611,7 +2612,12 @@ export default async (env) => {
}),
)
if (existsSync(testOutput) && statSync(testOutput).size > 0)
log(streamLine(`note`, `test output in ${testOutput}`))
log(
streamLine(
`note`,
`test output in ${escapeControls(posix(testOutput))}`,
),
)
return renderStdout({
results,
run: runIdentity,
Expand All @@ -2620,7 +2626,7 @@ export default async (env) => {
baseline: baselineFiles,
config: options.config,
paths: {
report: posix(join(options.out, `summary.md`)),
report: escapeControls(posix(join(options.out, `summary.md`))),
results: join(options.out, `results.json`),
out: options.out,
},
Expand Down
27 changes: 19 additions & 8 deletions packages/oracles/oracle-gaps/ending.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,23 @@
// `refused: <cause>` and `fix: <one directive>`, and, when the run knows its
// output directory, writes the refusal there as results.json and summary.md
// and names its report there in its last line, `oracle-gaps: done refused`.
// Any other error is a bug in the CLI. It exits 3,
// says so, and keeps its stack in error.log, in the output directory when
// the run knows one. Each ending replaces the files of another ending that
// an earlier run left in the directory (check.mjs removes error.log when a
// check completes).
// Any other error is a bug in the CLI. It exits 3, says so in one
// `oracle-gaps: error` line, and keeps its stack in error.log, in the
// output directory when the run knows one. Every line an ending prints is
// a line of the stream (stream.mjs) or of the refusal block. Each ending
// replaces the files of another ending that an earlier run left in the
// directory (check.mjs removes error.log when a check completes).
import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { posix, realPathOf } from './paths.mjs'
import { escapeControls, streamLine } from './stream.mjs'

// A path as a line of the stream shows it: in forward slashes, with a line
// break or another control character as its escape, so that a path cannot
// end its line or forge another (the register's C entry "The internal-error
// line", 2026-11-16).
const shown = (path) => escapeControls(posix(path))

/** A problem the author can fix: its cause, and the one step that fixes it. */
export class Refusal extends Error {
Expand Down Expand Up @@ -43,7 +51,7 @@ export function endRun(error, out = error?.out) {
results,
`Refused: ${message}\n\nFix: ${error.fix}\n`,
)
? `oracle-gaps: done refused, report ${posix(join(out, `summary.md`))}`
? `oracle-gaps: done refused, report ${shown(join(out, `summary.md`))}`
: `oracle-gaps: done refused`
return { exitCode: 2, stderr: `${[...block, done].join(`\n`)}\n`, done }
}
Expand All @@ -54,10 +62,13 @@ export function endRun(error, out = error?.out) {
log = join(realPathOf(tmpdir()), `oracle-gaps-error-${process.pid}.log`)
writeFileSync(log, stack)
}
const done = `oracle-gaps: done error, log ${posix(log)}`
const done = `oracle-gaps: done error, log ${shown(log)}`
// The message stays one line: its own line breaks print as escapes. A
// message that already names the CLI does not name it twice.
const said = escapeControls(message.replace(/^oracle-gaps: /, ``))
return {
exitCode: 3,
stderr: `oracle-gaps internal error: ${message}\nThis is a bug in oracle-gaps, not in your oracle. Its stack is in ${posix(log)}.\n${done}\n`,
stderr: `${streamLine(`error`, `${said}: a bug in oracle-gaps, not in your oracle; its stack is in ${shown(log)}`)}\n${done}\n`,
done,
}
}
Expand Down
30 changes: 22 additions & 8 deletions packages/oracles/oracle-gaps/gap-report-model-oracle.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -4354,7 +4354,12 @@ const reachesRun = (history) =>
// (`summary`), one directive per gap class (`legend`), and each function's
// heading over its gap lines (`function`) (the coordinator's decision of
// 2026-11-12 on review F1: every line of either stream is a line of the
// stream).
// stream). An internal error says so on a line of its own kind (`error`,
// law 12) before its done line: P10 prefixes every line the CLI writes,
// and its declared exempt lines (v21.2 P10 and I3) do not name an internal
// error's lines. The kind is the done line's status word for exit 3 (v21.2
// I7), and the line's form is the register's C entry "The internal-error
// line" (2026-11-16).
const streamKinds = [
`config`,
`note`,
Expand All @@ -4366,6 +4371,7 @@ const streamKinds = [
`summary`,
`legend`,
`function`,
`error`,
`done`,
]
// The one decisive baseline line, before any mutant runs: every oracle
Expand Down Expand Up @@ -5797,16 +5803,24 @@ function applyEdit(state, edit) {
// exits 2 and prints one block on stderr with no stack frames: `refused:
// <cause>`, then `fix: <directive>`. The directive is one next step, and it
// offers no way around the fix (no "ignore it", no "mark it equivalent").
// When the run knows its output directory, the block ends with `output:
// <dir>`, and the directory holds a results.json, `{ status: "refused",
// cause, directive }`, whose cause and directive are the block's, and a
// summary.md, and no error.log: every ending removes the other ending's
// When the run knows its output directory, its done line names the
// directory's summary.md (`done refused, report <dir>/summary.md`), and the
// directory holds a results.json, `{ status: "refused", cause, directive
// }`, whose cause and directive are the block's, and a summary.md, and no
// error.log: every ending removes the other ending's
// files. Arguments the CLI cannot parse know their output directory only
// when they name it (`--out`).
//
// An internal error is a bug in the CLI. It exits 3, says so, and keeps the
// stack in an error.log rather than on stderr. No legal history reaches one,
// so this law's check judges refusals only (see each oracle's limits).
// An internal error is a bug in the CLI. It exits 3, says so in one
// `oracle-gaps: error` line on stderr and none on stdout, with the line
// breaks of its message and of its log's path escaped, and keeps the stack
// in an error.log rather than on stderr (the register's C entry "The
// internal-error line", 2026-11-16). No legal history reaches one; the
// end-to-end oracle's constructed rejected-batch history (a test-only
// fault) reaches it, and that oracle judges its exit, its error line, its
// error.log, the absence of stack frames on stderr, and the stream law (law
// 15) on both streams. This check judges refusals only (see each oracle's
// limits).

/**
* What a run that ended without completing printed and wrote, as the
Expand Down
Loading
Loading