mandrel 2.36.0 → 2.37.0

package/.agents/scripts/lib/source-text/strip-js-comments.js

@@ -0,0 +1,115 @@
+// .agents/scripts/lib/source-text/strip-js-comments.js
+/**
+ * The one string-literal-aware JavaScript comment stripper.
+ *
+ * Several guards in this repository grep source text for a pattern that must
+ * appear in real code rather than in a docblock — a CLI citation, an import
+ * specifier, a schema path. Each grew its own stripper, and the four
+ * implementations disagreed on what a stripped block comment leaves behind:
+ * one preserved newlines only, one deleted the comment outright (losing line
+ * numbers), one blanked it to whitespace, and one used a regex that did not
+ * honour string literals at all. A fix to any of them silently missed the
+ * others, and a guard whose own rationale mentions the pattern it greps for
+ * can satisfy itself if the stripping is wrong.
+ *
+ * **Semantics: comment bodies become equivalent whitespace.** Every character
+ * of a comment is replaced by a space except newlines, which survive. That is
+ * the most information-preserving of the four behaviours and the only one that
+ * is safe for all of them:
+ *
+ *   - line and column positions are unchanged, so a guard can report a
+ *     `file:line` that matches the original source;
+ *   - a regex looking for code cannot match comment text, because none
+ *     survives;
+ *   - the output is the same length as the input, so byte offsets hold.
+ *
+ * String and template literals are copied through verbatim, so a `//` inside a
+ * URL or a `/*` inside a message is not mistaken for a comment opener. Escape
+ * sequences are honoured, so an escaped quote does not end the literal early.
+ *
+ * An unterminated comment or literal runs to end of input rather than
+ * throwing: this is a lint helper reading files that may be mid-edit, and a
+ * crash there would be a worse failure than a slightly over-stripped tail.
+ *
+ * Builtins only — no dependency, so the guards that run before a consumer's
+ * install can use it.
+ */
+
+/**
+ * Replace every non-newline character of `text` with a space.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function blank(text) {
+  return text.replace(/[^\n]/g, ' ');
+}
+
+/**
+ * Index just past the string or template literal opening at `start`.
+ * Runs to end of input when the literal is never closed.
+ *
+ * @param {string} text
+ * @param {number} start - index of the opening quote
+ * @returns {number}
+ */
+function endOfLiteral(text, start) {
+  const quote = text[start];
+  let i = start + 1;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '\\') {
+      i += 2;
+      continue;
+    }
+    if (ch === quote) return i + 1;
+    i += 1;
+  }
+  return text.length;
+}
+
+/**
+ * Strip JavaScript comments, replacing their bodies with equivalent
+ * whitespace so line numbers, columns and byte offsets all survive.
+ *
+ * @param {string} source - JavaScript source text. Nullish is treated as empty.
+ * @returns {string} the source with every comment body blanked to whitespace
+ */
+export function stripJsComments(source) {
+  const text = String(source ?? '');
+  let out = '';
+  let i = 0;
+
+  while (i < text.length) {
+    const two = text.slice(i, i + 2);
+
+    if (two === '//') {
+      const newline = text.indexOf('\n', i);
+      const stop = newline === -1 ? text.length : newline;
+      out += blank(text.slice(i, stop));
+      i = stop;
+      continue;
+    }
+
+    if (two === '/*') {
+      const close = text.indexOf('*/', i + 2);
+      const stop = close === -1 ? text.length : close + 2;
+      out += blank(text.slice(i, stop));
+      i = stop;
+      continue;
+    }
+
+    const ch = text[i];
+    if (ch === "'" || ch === '"' || ch === '`') {
+      const stop = endOfLiteral(text, i);
+      out += text.slice(i, stop);
+      i = stop;
+      continue;
+    }
+
+    out += ch;
+    i += 1;
+  }
+
+  return out;
+}

package/.agents/scripts/lib/test-isolate/runner.js

@@ -58,7 +58,7 @@ const NODE_TEST_BASE = [
  * @param {typeof spawn} [opts.spawnFn]
  * @returns {Promise<IsolatedResult>}
  */
-export function runFileIsolated({
+function runFileIsolated({
   repoRoot,
   file,
   envOutDir,
@@ -195,7 +195,7 @@ function sanitizeEnv(source) {
  * @param {typeof spawn} [opts.spawnFn]
  * @returns {Promise<{ results: SuiteResult[], exitCode: number, stdout: string, stderr: string }>}
  */
-export function runSuite({
+function runSuite({
   repoRoot,
   files,
   concurrency = 8,
@@ -266,7 +266,7 @@ export function runSuite({
  * @param {(r: IsolatedResult) => void} [opts.onResult]
  * @returns {Promise<IsolatedResult[]>}
  */
-export async function runIsolatedPool({
+async function runIsolatedPool({
   repoRoot,
   files,
   envOutDir,

package/.agents/scripts/lib/test-runner-contract.js

@@ -90,13 +90,20 @@ export const TEST_RUNNER_FLAGS = Object.freeze([
  * the spawns `runTierPreflight` actually issues — which is the thing that
  * has to be true.
  */
+const STATE_PROBE_ONLY = Object.freeze(['.agents/scripts/test-wrapper.js']);
+
 const TIER_PREFLIGHT_SCRIPTS = Object.freeze({
   full: Object.freeze([
-    '.agents/scripts/test-wrapper.js',
+    ...STATE_PROBE_ONLY,
     '.agents/scripts/validate-skills.js',
   ]),
-  quick: Object.freeze(['.agents/scripts/test-wrapper.js']),
-  integration: Object.freeze(['.agents/scripts/test-wrapper.js']),
+  quick: STATE_PROBE_ONLY,
+  integration: STATE_PROBE_ONLY,
+  // Story #5111: the `e2e` tier gets the state probe like every other
+  // non-full tier. An absent entry is not a neutral default — the lookup
+  // below falls through to `[]`, so a tier missing from this map runs *no*
+  // preflight at all and the omission is invisible in a green run.
+  e2e: STATE_PROBE_ONLY,
 });
 
 /**
@@ -108,7 +115,7 @@ const TIER_PREFLIGHT_SCRIPTS = Object.freeze({
  * executes, which the npm hook does not under `ignore-scripts=true`.
  *
  * @param {object} [opts]
- * @param {'full' | 'quick' | 'integration'} [opts.tier]
+ * @param {'full' | 'quick' | 'integration' | 'e2e'} [opts.tier]
  * @param {string} [opts.repoRoot] Absolute repository root.
  * @param {typeof spawnSync} [opts.spawn] Injected in tests.
  * @param {string} [opts.execPath] Node binary to spawn; injected in tests.
@@ -127,8 +134,9 @@ export function runTierPreflight({
       stdio: 'inherit',
     });
     if (run.error) throw run.error;
-    const status = run.status ?? 1;
-    if (status !== 0) return status;
+    // A signal-killed child reports `status: null`; treat that as the
+    // reserved failure code rather than letting it read as "not zero, no code".
+    if (run.status !== 0) return run.status ?? 1;
   }
   return 0;
 }

package/.agents/scripts/lib/test-tiers.js

@@ -23,6 +23,46 @@ export const INTEGRATION_INCLUDE = [
 
 const matchesIntegration = picomatch(INTEGRATION_INCLUDE, { dot: true });
 
+/**
+ * Globs for the `e2e` tier — real-binary suites under `tests/e2e/` that pack
+ * this repository, install it into a temp consumer and drive the shipped
+ * `mandrel` binary end to end.
+ *
+ * They are the most expensive files the repository owns by an order of
+ * magnitude: one `npm pack` plus real `npm install` spawns per file, measured
+ * (Story #5111) at ~7 s of system time and ~17 s of summed install wall clock
+ * for `update-chain.integration.test.js` alone. Every one of those seconds was
+ * charged to `npm test` — i.e. to every pre-push hook and every local
+ * iteration — for a signal that only changes when the release-shaped install
+ * path changes.
+ *
+ * So they get their own tier and leave every other one: `full` (`npm test`),
+ * `quick` and `integration` all exclude them, and `npm run test:e2e` is how
+ * they run. CI runs that tier as its own job on every PR, so the
+ * release-shaped path keeps its per-PR signal.
+ *
+ * Deliberately not exported: a second reader of this list is a second place
+ * for the tier definition to drift. `listTestFilesForTier('e2e', root)` is the
+ * public answer to "which files are e2e", and the tests assert through it.
+ */
+const E2E_INCLUDE = ['tests/e2e/**/*.test.js'];
+
+const matchesE2E = picomatch(E2E_INCLUDE, { dot: true });
+
+/** Tier names `parseTierArgv` accepts, in the order `--help` lists them. */
+const TIERS = ['full', 'quick', 'integration', 'e2e'];
+
+/**
+ * `node --test` flags the runner forwards verbatim to the child.
+ *
+ * Everything else that looks like a flag is a mistake — a typo, a retired
+ * option, or a flag meant for `npm` that landed after the `--` separator —
+ * and `parseTierArgv` rejects it rather than passing it to `node --test`,
+ * which reads an unknown `--flag` as a *file pattern* and silently runs a
+ * suite that matches nothing while exiting 0.
+ */
+const PASSTHROUGH_FLAGS = ['--test-name-pattern', '--test-only'];
+
 /**
  * Repo-relative roots the tier walker scans for test files (names ending in
  * `.test.js`).
@@ -47,12 +87,22 @@ const TEST_WALK_ROOTS = ['tests', 'lib', '.agents/scripts'];
  * globs are scoped to `__tests__` subtrees so they only match colocated
  * tests, never the shipped source modules themselves.
  *
- * Exported because the full tier has two runners, not one: `run-tests.js`
- * (via `listTestFilesForTier`) and `run-coverage.js`. Story #4922 — the
- * coverage runner used to restate `tests/**` on its own, so the 47 colocated
- * `__tests__` files ran under `npm test` but were absent from the measured
- * surface, leaving the coverage and CRAP numbers computed over code the
- * measuring run never executed. Consume this constant; never restate a glob.
+ * Exported because it is the **measured surface**: `run-coverage.js` — the
+ * required CI job, and the run every coverage / CRAP baseline is scored from —
+ * consumes it directly. Story #4922: the coverage runner used to restate
+ * `tests/**` on its own, so the 47 colocated `__tests__` files ran under
+ * `npm test` but were absent from the measured surface, leaving the coverage
+ * and CRAP numbers computed over code the measuring run never executed.
+ * Consume this constant; never restate a glob.
+ *
+ * Story #5111 made this a strict **superset** of the `full` runner tier: the
+ * measured surface still includes `tests/e2e/**`, while `npm test` no longer
+ * runs it. That asymmetry is deliberate and load-bearing. The e2e suites drive
+ * the shipped binary through `bin/mandrel.js` and `lib/cli/update.js` in real
+ * child processes, and c8's `NODE_V8_COVERAGE` is inherited by those children —
+ * so dropping them from the measured run would deflate exactly the CLI files
+ * they exist to exercise and red the coverage ratchet on code nobody touched.
+ * Cheapening the pre-push loop must not cost the measurement its subject.
  */
 export const FULL_TIER_GLOBS = [
   'tests/**/*.test.js',
@@ -81,10 +131,47 @@ function walkTestFiles(dir, prefix, fsLike) {
   return out;
 }
 
+/**
+ * Split the walked set into the `e2e` tier and the remainder every other tier
+ * is drawn from, so an e2e file belongs to exactly one tier and `npm test`
+ * never pays for it.
+ *
+ * @param {string[]} all
+ * @returns {{ e2e: string[], rest: string[] }}
+ */
+function partitionE2E(all) {
+  const e2e = all.filter((file) => matchesE2E(file));
+  const e2eSet = new Set(e2e);
+  return { e2e, rest: all.filter((file) => !e2eSet.has(file)) };
+}
+
+/**
+ * Split the non-e2e remainder into the slow `integration` tier and the `quick`
+ * complement — the historical partition, unchanged.
+ *
+ * @param {string[]} rest
+ * @param {'quick' | 'integration'} tier
+ * @returns {string[]}
+ */
+function splitBySpeed(rest, tier) {
+  const integration = rest.filter((file) => matchesIntegration(file));
+  if (tier === 'integration') {
+    return integration;
+  }
+  const integrationSet = new Set(integration);
+  return rest.filter((file) => !integrationSet.has(file));
+}
+
 /**
  * List repo-relative test file paths for a tier.
  *
- * @param {'full' | 'quick' | 'integration'} tier
+ * `full` used to return {@link FULL_TIER_GLOBS} verbatim and let `node --test`
+ * expand them. It enumerates files instead since Story #5111, because the one
+ * thing a glob list cannot express is an exclusion: `node --test` has no
+ * negative pattern, so "everything except `tests/e2e/**`" is only sayable as
+ * a file set. The measured surface keeps the globs (see `FULL_TIER_GLOBS`).
+ *
+ * @param {'full' | 'quick' | 'integration' | 'e2e'} tier
  * @param {string} repoRoot
  * @param {typeof fs} [fsLike]
  * @returns {string[]}
@@ -93,34 +180,64 @@ export function listTestFilesForTier(tier, repoRoot, fsLike = fs) {
   const all = TEST_WALK_ROOTS.flatMap((root) =>
     walkTestFiles(path.join(repoRoot, root), root, fsLike),
   ).sort();
-  if (tier === 'full') {
-    return [...FULL_TIER_GLOBS];
+  const { e2e, rest } = partitionE2E(all);
+  if (tier === 'e2e') {
+    return e2e;
   }
-  const integration = all.filter((file) => matchesIntegration(file));
-  if (tier === 'integration') {
-    return integration;
+  if (tier === 'full') {
+    return rest;
   }
-  const integrationSet = new Set(integration);
-  return all.filter((file) => !integrationSet.has(file));
+  return splitBySpeed(rest, tier);
+}
+
+/**
+ * Reject argv tokens that look like flags but are neither `--tier` (already
+ * consumed) nor a sanctioned `node --test` pass-through.
+ *
+ * Silence was the old behaviour and the reason this exists: the runner
+ * forwarded every unrecognized token verbatim, and `node --test` treats an
+ * unknown `--flag` as another **file pattern**. A typo therefore produced a
+ * run that matched nothing, printed a plausible-looking summary and exited 0 —
+ * a green that proved nothing.
+ *
+ * @param {string[]} rest
+ * @throws {Error} naming both the accepted tiers and the accepted flags.
+ */
+function assertKnownFlags(rest) {
+  const unknown = rest.filter(
+    (arg) =>
+      arg.startsWith('--') &&
+      !PASSTHROUGH_FLAGS.includes(arg) &&
+      !PASSTHROUGH_FLAGS.some((flag) => arg.startsWith(`${flag}=`)),
+  );
+  if (unknown.length === 0) return;
+  throw new Error(
+    `[run-tests] unrecognized argument(s): ${unknown.join(', ')}. ` +
+      `Accepted: --tier <${TIERS.join('|')}>, ${PASSTHROUGH_FLAGS.join(', ')}, --help. ` +
+      'Unrecognized flags are not forwarded: `node --test` would read them as ' +
+      'file patterns and exit 0 having run nothing.',
+  );
 }
 
 /**
- * Parse `--tier <name>` from argv. Unknown tiers throw.
+ * Parse `--tier <name>` from argv. Unknown tiers and unknown flags throw.
  *
  * @param {string[]} argv
- * @returns {{ tier: 'full' | 'quick' | 'integration', rest: string[] }}
+ * @returns {{ tier: 'full' | 'quick' | 'integration' | 'e2e', rest: string[] }}
  */
 export function parseTierArgv(argv) {
   const tierIdx = argv.indexOf('--tier');
   if (tierIdx === -1) {
+    assertKnownFlags(argv);
     return { tier: 'full', rest: argv };
   }
   const tier = argv[tierIdx + 1];
-  if (!tier || !['full', 'quick', 'integration'].includes(tier)) {
+  if (!tier || !TIERS.includes(tier)) {
     throw new Error(
-      `[run-tests] --tier requires one of: full, quick, integration (got ${JSON.stringify(tier)})`,
+      `[run-tests] --tier requires one of: ${TIERS.join(', ')} (got ${JSON.stringify(tier)})`,
     );
   }
   const rest = argv.filter((_, i) => i !== tierIdx && i !== tierIdx + 1);
+  assertKnownFlags(rest);
   return { tier, rest };
 }

package/.agents/scripts/lib/transpile.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { createRequire, SourceMap } from 'node:module';
 import path from 'node:path';
+import { resolveDependencyVersion } from './dependency-version.js';
 import { Logger } from './Logger.js';
 
 const require = createRequire(import.meta.url);
@@ -22,18 +23,30 @@ function loadTypeScript() {
   }
 }
 
+let _tsVersion = null;
+
 /**
  * Resolve the `typescript` package version, used to stamp baselines so
  * consumers can detect transpiler drift. Returns `'0.0.0'` when the
  * dependency is unresolvable — callers treat that sentinel as "unknown
  * environment" and may refuse to persist a baseline that includes TS rows.
  *
+ * **The version is read from the package manifest, never by evaluating the
+ * compiler** (Story #5109) — see
+ * [`dependency-version.js`](dependency-version.js) for how, and for what it
+ * cost to do it the other way. The manifest returns the identical string, so
+ * the stamp (and therefore every committed baseline envelope) is
+ * byte-identical either way. The compiler itself is still loaded — lazily, by
+ * `transpileIfNeeded` — the first time a `.ts`/`.tsx` input is actually
+ * transpiled.
+ *
  * @returns {string}
  */
 export function resolveTsTranspilerVersion() {
-  const ts = loadTypeScript();
-  if (ts && typeof ts.version === 'string') return ts.version;
-  return '0.0.0';
+  if (_tsVersion === null) {
+    _tsVersion = resolveDependencyVersion('typescript', require) ?? '0.0.0';
+  }
+  return _tsVersion;
 }
 
 function isTypeScriptPath(filePath) {