fix(#2979): document ExitError plain-text carve-out in json-errors.md (#3093)

* fix(#2979): document ExitError plain-text carve-out in json-errors.md

The JSON-errors doc claimed every error emits a structured JSON envelope,
but usage errors (ExitError) intentionally emit plain text with their own
exit code (src/cli-exit.cts:36-39 catches ExitError before the envelope
branch). Anyone following the doc's 'always parse stderr as JSON' guidance
against a usage error got a parse failure.

Amended the Wire format + Overview + Writing tests sections to scope the
structured envelope to non-ExitError failures, stated the carve-out with a
pointer to cli-exit.cts, and scoped the JSON-parse instruction to the
envelope branch. Added a characterization test pinning both paths together
(ExitError -> plain text + own code; non-ExitError -> JSON envelope) so the
code cannot drift toward the doc's prior overstated claim. No runtime
change — the test passes before and after the doc edit.

Re-scoped per maintainer triage: the smart-entry --json part is already
satisfied (shipped payload exposes the command token); only the doc
correction + characterization test remain.

* chore(#2979): backfill changeset PR number 3093

---------

Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
2026-08-05 18:57:10 -04:00
committed by GitHub
parent 2979f2a994
commit 955655407c
3 changed files with 64 additions and 6 deletions

View File

@@ -183,11 +183,18 @@ describe('runMain', () => {
describe('regressions', () => {
/** Spawn a one-shot script that sets json-error mode and calls runMain with a throwing handler. */
function spawnJsonErrorRun({ jsonMode, errorType = 'TypeError', message = 'unexpected boom' } = {}) {
// ExitError lives in the same module as runMain; import it when the test
// wants to exercise the ExitError carve-out path. ExitError takes (code, message).
const isExitError = errorType === 'ExitError';
const destructure = isExitError ? '{ runMain, ExitError }' : '{ runMain }';
const throwExpr = isExitError
? `new ExitError(1, ${JSON.stringify(message)})`
: `new ${errorType}(${JSON.stringify(message)})`;
const script = `
const io = require(${JSON.stringify(IO_PATH)});
const { runMain } = require(${JSON.stringify(BUILT_CLI_EXIT_PATH)});
const ${destructure} = require(${JSON.stringify(BUILT_CLI_EXIT_PATH)});
io.setJsonErrorMode(${jsonMode ? 'true' : 'false'});
runMain(() => { throw new ${errorType}(${JSON.stringify(message)}); });
runMain(() => { throw ${throwExpr}; });
setImmediate(() => {});
`;
return spawnSync(process.execPath, ['-e', script], { encoding: 'utf-8' });
@@ -245,5 +252,35 @@ describe('regressions', () => {
`expected "unexpected boom" in stderr, got: ${stderrTrimmed.slice(0, 200)}`
);
});
// #2979: characterization test pinning the two error paths under json-errors
// mode. The structured envelope covers non-ExitError failures; ExitError
// (usage errors) intentionally emits plain text with its own exit code.
// Both halves asserted together so the code cannot drift toward the doc's
// prior overstated claim that EVERY error emits JSON.
test('#2979: ExitError emits plain text (not JSON) even under --json-errors; non-ExitError emits the envelope', () => {
// ExitError path: plain text, own exit code, NOT a JSON object.
const exitResult = spawnJsonErrorRun({
jsonMode: true,
errorType: 'ExitError',
message: 'Usage: gsd-tools <command> [args]',
});
assert.strictEqual(exitResult.status, 1, 'ExitError exits with its code');
const exitStderr = exitResult.stderr.trim();
let exitParsed = null;
try { exitParsed = JSON.parse(exitStderr); } catch { /* expected — plain text */ }
assert.strictEqual(exitParsed, null,
`ExitError must emit plain text, not JSON; got: ${exitStderr.slice(0, 200)}`);
assert.ok(exitStderr.includes('Usage'),
`ExitError plain-text message must reach stderr; got: ${exitStderr.slice(0, 200)}`);
// Non-ExitError path: structured JSON envelope.
const envResult = spawnJsonErrorRun({ jsonMode: true });
assert.strictEqual(envResult.status, 1);
const envParsed = JSON.parse(envResult.stderr.trim());
assert.strictEqual(envParsed.ok, false);
assert.strictEqual(envParsed.reason, 'sdk_fail_fast');
assert.ok(envParsed.message, 'envelope must carry a message');
});
});
});