@opengsd/gsd-core 1.11.0 → 1.12.0

package/scripts/lib/drift-scan.cjs

@@ -61,17 +61,43 @@ const SKIP_DIR_NAMES = new Set(['node_modules', 'dist', '.git']);
  *     previous regex silently MISSED every re-derivation using a
  *     cross-platform path-separator class for exactly this reason.
  */
+// Deterministic regression seam for the MAJOR-2 bound (issue #3951/#3987): a
+// counter of how many characters this tokenizer has actually examined, so a
+// test can assert the bound HOLDS (total work stays a small linear multiple
+// of the number of scan attempts × MAX_REGEX_LITERAL_LEN) without resorting
+// to a wall-clock elapsed-time assertion, which this repo's test rules ban
+// ("Clock Seams: Do not assert on wall-clock time.") and which is exactly
+// what flaked on a slow shared CI runner. `resetRegexScanStats`/
+// `getRegexScanStats` are read-modify-reset around a single scan under test;
+// they are process-global and NOT safe under concurrent scans, which is fine
+// for this synchronous, single-threaded CLI tool and its tests.
+let regexScanStats = { calls: 0, charsExamined: 0 };
+
+function resetRegexScanStats() {
+  regexScanStats = { calls: 0, charsExamined: 0 };
+}
+
+function getRegexScanStats() {
+  return { ...regexScanStats };
+}
+
 function readRegexLiteralAt(line, start) {
   if (line[start] !== '/') return null;
+  regexScanStats.calls++;
   const limit = Math.min(line.length, start + MAX_REGEX_LITERAL_LEN);
   let inClass = false;
-  for (let i = start + 1; i < limit; i++) {
+  let i = start + 1;
+  for (; i < limit; i++) {
     const ch = line[i];
     if (ch === '\\') {
       i++; // escape consumes the next character, whatever it is
       continue;
     }
-    if (ch === '\r' || ch === '\n') return null; // a literal cannot span lines
+    if (ch === '\r' || ch === '\n') {
+      // a literal cannot span lines
+      regexScanStats.charsExamined += i - start;
+      return null;
+    }
     if (ch === '[') {
       inClass = true;
     } else if (ch === ']') {
@@ -83,9 +109,11 @@ function readRegexLiteralAt(line, start) {
       // MAX_REGEX_LITERAL_LEN either.
       let end = i + 1;
       while (end < limit && line[end] >= 'a' && line[end] <= 'z') end++;
+      regexScanStats.charsExamined += end - start;
       return { text: line.slice(start, end), end };
     }
   }
+  regexScanStats.charsExamined += limit - start;
   return null;
 }
 
@@ -275,4 +303,6 @@ module.exports = {
   MAX_REGEX_LITERAL_LEN,
   sanitizeForReport,
   scanTree,
+  resetRegexScanStats,
+  getRegexScanStats,
 };

package/scripts/lib/exit-code-registry.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+// GENERATED FILE — DO NOT EDIT BY HAND.
+// Source of truth: gsd-core/bin/shared/exit-codes.json. Regenerate with:
+//   node scripts/gen-exit-code-registry.cjs --write
+// This exact content is emitted to THREE locations — gsd-core/bin/lib/exit-code-registry.cjs,
+// scripts/lib/exit-code-registry.cjs, and hooks/lib/exit-code-registry.js (the latter two
+// committed so scripts/ and hooks/ consumers work on an unbuilt clone) — all byte-compared by
+// `npm run lint:generated-sync` (#3905 ADR-3889 Phase 1; #3906 Phase 2 added the second copy;
+// #3911 ADR-3889 Phase 7 added the hooks/lib/ copy).
+//
+// exitCodeFor(name) / nameForExitCode(code) are pure and total over this
+// closed table — each throws for anything not registered here.
+
+const EXIT_CODES = Object.freeze([
+  Object.freeze({
+    code: 2,
+    name: "HOOK_DENY",
+    meaning: "Hook protocol deny — the harness blocks the tool call",
+    owner: "hook-adapter",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 64,
+    name: "USAGE",
+    meaning: "Caller error — bad argv, unknown subcommand, missing argument",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 66,
+    name: "NO_INPUT",
+    meaning: "Ran; zero units were in scope, and that emptiness is known to be genuine",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 69,
+    name: "UNAVAILABLE",
+    meaning: "Could not run — prerequisite absent, input unreadable, scope unestablished",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 70,
+    name: "INTERNAL",
+    meaning: "Self-failure — crash, timeout, killed subprocess",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 80,
+    name: "DEGRADED",
+    meaning: "Ran to completion and is reporting a condition through its result payload rather than as a process failure",
+    owner: "gsd-tools",
+    authorizedBy: "ADR-3889 + ADR-2980",
+  })
+]);
+
+const NAME_TO_CODE = new Map(EXIT_CODES.map((entry) => [entry.name, entry.code]));
+const CODE_TO_NAME = new Map(EXIT_CODES.map((entry) => [entry.code, entry.name]));
+
+/**
+ * Resolve the registered exit code for a symbolic name. Pure, total: throws
+ * for anything not an exact, registered, exact-case key — including
+ * non-strings, the empty string, untrimmed strings, wrong case, and
+ * prototype-chain names like `__proto__`/`constructor`/`toString` (a Map
+ * lookup never touches the prototype chain, so these are indistinguishable
+ * from any other unregistered name).
+ *
+ * @param {string} name
+ * @returns {number}
+ */
+function exitCodeFor(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error(`exitCodeFor: name must be a non-empty string, received ${JSON.stringify(name)}`);
+  }
+  if (!NAME_TO_CODE.has(name)) {
+    throw new Error(`exitCodeFor: unregistered exit code name: ${JSON.stringify(name)}`);
+  }
+  return NAME_TO_CODE.get(name);
+}
+
+/**
+ * Reverse of exitCodeFor: resolve the symbolic name for a registered exit
+ * code. Pure, total: throws for anything not an exact, registered code.
+ *
+ * @param {number} code
+ * @returns {string}
+ */
+function nameForExitCode(code) {
+  if (!CODE_TO_NAME.has(code)) {
+    throw new Error(`nameForExitCode: unregistered exit code: ${JSON.stringify(code)}`);
+  }
+  return CODE_TO_NAME.get(code);
+}
+
+module.exports = { EXIT_CODES, exitCodeFor, nameForExitCode };

package/scripts/lib/ndjson-reporter.cjs

@@ -0,0 +1,119 @@
+'use strict';
+
+// Machine-readable companion reporter for scripts/run-tests.cjs (#3889).
+//
+// node:test's built-in reporters (spec/tap) are human-formatted and
+// scripts/run-tests.cjs spawns the child with `stdio: 'inherit'` — by design,
+// per #3597/#1051, to avoid the maxBuffer and live-output risks of piping —
+// so the parent process has no way to see WHICH file was executing when a
+// per-chunk timeout kills the child. This reporter runs ALONGSIDE the normal
+// human reporter (a second `--test-reporter` on the same invocation, per
+// Node's documented multi-reporter pairing) and appends one JSON object per
+// line to a path supplied via the GSD_RUN_TESTS_EVENTS_FILE env var. On a
+// timeout, run-tests.cjs reads that file back to name the file(s) still
+// in flight (a `test:dequeue` with no matching `test:pass`/`test:fail`).
+//
+// Durability, not `--test-reporter-destination` (#3889 root cause): a
+// reporter that YIELDS strings has them piped by Node into a
+// `fs.WriteStream` targeting the destination path, and that stream buffers.
+// The parent's `execFileSync` timeout SIGKILLs the child on a hang, and
+// SIGKILL is uncatchable and gives the process zero chance to flush — so a
+// yield-based reporter can lose every event still sitting in the stream's
+// buffer, which is exactly the case this feature exists to diagnose (proven
+// live: a chunk killed at 2006ms produced a `killed after 2006ms` line from
+// the TIMER, which lives in the parent, but zero usable events from the
+// reporter, which lives in the child and never flushed). Writing each event
+// with `fs.appendFileSync` — synchronous and unbuffered — makes it durable
+// the instant it happens, before the process can be killed out from under
+// it. The reporter therefore yields NOTHING; it is a pure side-effecting
+// sink. Node still requires a `--test-reporter-destination` to pair with
+// this `--test-reporter` (see run-tests.cjs's reporterArgsFor), but that
+// destination is a throwaway sink that stays empty by design — the durable
+// path is GSD_RUN_TESTS_EVENTS_FILE, not the destination Node manages.
+//
+// Contract targeted: Node's "Custom reporters" contract
+// (https://nodejs.org/api/test.html#custom-reporters) — a reporter module's
+// default export is a function receiving the test runner's event stream (an
+// AsyncIterable of `{ type, data }` objects). Node feeds that function to
+// `stream.compose` as the stream's "body". When the body is an async
+// FUNCTION (not an `async function*` generator), `stream.compose`'s own
+// contract (https://nodejs.org/api/stream.html#streamcomposestreams)
+// requires it to return nully (undefined/null) — returning anything else,
+// including an array, throws `ERR_INVALID_RETURN_VALUE` ("Expected nully to
+// be returned from the 'body' function but got an instance of Array")
+// exactly once the promise resolves. Verified directly against
+// `stream.compose` in this repo's Node: calling it with a body that
+// `return`s `[]` reproduces that same TypeError. A generator form
+// (`async function*`) is the one that yields an iterable; the plain
+// `async function` form used here is the one that must return nully. This
+// repo's `engines.node` requires >=24.0.0 (package.json), where both
+// contracts have been stable since Node 20.
+//
+// Kept intentionally tiny: only the five event types run-tests.cjs needs are
+// handled — `test:enqueue`/`test:dequeue` (emitted by the RUNNER as it queues
+// and begins each spawned test-file child, independent of whether anything
+// inside that file ever completes) plus `test:start`/`test:pass`/`test:fail`
+// (emitted per-subtest, once the child reports it). `test:dequeue` is the
+// event that actually means "in flight": a subtest inside a file that hangs
+// forever never reaches `test:start`/`test:pass`/`test:fail` at all, because
+// node:test only surfaces those to the parent once the child COMPLETES that
+// test — a hang, by definition, never completes. Recording `test:dequeue`
+// closes that gap: it fires the moment the runner begins the file, so a
+// killed hang still leaves a durable "this file was running" record.
+// Everything else (diagnostics, plans, coverage) is ignored so a truncated
+// events file (the process is SIGKILLed mid-`appendFileSync` on timeout — an
+// individual write is unbuffered but not atomic, so the OS can still
+// interleave a partial write with the kill) never leaves more than one
+// dangling unparsable trailing line.
+module.exports = async function ndjsonEventReporter(source) {
+  const eventsPath = process.env.GSD_RUN_TESTS_EVENTS_FILE;
+  // #3889: an init marker, written as this reporter's FIRST action — before
+  // the `for await` loop even begins consuming the event stream — so the
+  // events file's mere existence (and its exact contents) can distinguish
+  // "the reporter module never loaded in the child at all" (file absent)
+  // from "it loaded fine but no test:start reached it before the kill"
+  // (file contains only this one line) from "it's working" (file contains
+  // more than this line). Same appendFileSync durability rationale as every
+  // other write in this file: synchronous and unbuffered, so it survives an
+  // uncatchable SIGKILL landing a moment later.
+  if (eventsPath) {
+    try {
+      require('fs').appendFileSync(eventsPath, `${JSON.stringify({ type: 'reporter:init', ts: Date.now() })}\n`);
+    } catch {
+      // Best-effort, same as every other write below — must never crash the
+      // test run this reporter is only observing.
+    }
+  }
+  for await (const event of source) {
+    if (!eventsPath) continue; // no destination configured — nothing to record
+    if (
+      event.type === 'test:enqueue' ||
+      event.type === 'test:dequeue' ||
+      event.type === 'test:start' ||
+      event.type === 'test:pass' ||
+      event.type === 'test:fail'
+    ) {
+      const { file, name, nesting, testNumber } = event.data || {};
+      const line = `${JSON.stringify({
+        type: event.type,
+        file,
+        name,
+        nesting,
+        testNumber,
+        ts: Date.now(),
+      })}\n`;
+      try {
+        require('fs').appendFileSync(eventsPath, line);
+      } catch {
+        // Best-effort: a write failure here (e.g. the events dir vanished)
+        // must never crash the test run this reporter is only observing.
+      }
+    }
+  }
+  // Falls through to an implicit `return undefined` (nully): this reporter is
+  // a pure side-effecting sink (see the durability note above), never a
+  // source of reporter OUTPUT, and `stream.compose` requires its async
+  // FUNCTION body to return nully — returning an iterable (e.g. `[]`) here
+  // raises `ERR_INVALID_RETURN_VALUE` (observed live: this exact `return []`
+  // crashed every chunk on the real remote run this regresses).
+};

package/scripts/lint-allow-test-rule-refs.unverified-ceiling.json

@@ -1,3 +1,3 @@
 {
-  "maxFiles": 280
+  "maxFiles": 282
 }