mandrel 2.16.0 → 2.17.0

package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js

@@ -0,0 +1,166 @@
+/**
+ * story-deliver-terminal-schema.js — load `story-deliver-terminal.schema.json`
+ * and validate envelopes against it.
+ *
+ * Split out of `story-deliver-terminal.js` so the envelope WRITER holds only
+ * the contract's shape and vocabulary, and this module holds the one thing
+ * the writer must never depend on at call time: the filesystem.
+ *
+ * That separation is the fix, not just tidiness. `single-story-close.js`
+ * invoked by a *worktree-relative* path runs the Story worktree's own copy of
+ * the script and then **reaps that worktree** as one of its phases. The schema
+ * used to be read lazily, on the first envelope build — which happens after
+ * the reap — so the read hit a path that no longer existed. The throw landed
+ * inside the close CLI's error path, so a Story whose PR had merged, whose
+ * label was `agent::done`, and whose post-land tail was green exited non-zero
+ * emitting NO envelope at all: the delivery engine's documented return
+ * contract lost to a success, recoverable only by a second close run from the
+ * main checkout.
+ *
+ * Two guarantees close that, and both live here:
+ *
+ *   1. The schema is read and parsed ONCE, at module load. The parsed schema
+ *      outlives the file, so what happens to the directory afterwards is
+ *      irrelevant. Compilation stays lazy — it needs no filesystem — so an
+ *      import costs one small read and nothing else.
+ *   2. An unreadable schema DEGRADES validation rather than throwing. A
+ *      schema violation still fails loudly; see {@link validateTerminalEnvelope}.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the shipped schema — the SSOT this module reads.
+ *
+ * Module-private, like every other `SCHEMA_PATH` in the tree
+ * (`validation-evidence.js`, `signal-validator.js`): the path is an
+ * implementation detail of loading, and callers want the verdict, not the
+ * location.
+ */
+const SCHEMA_PATH = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'story-deliver-terminal.schema.json',
+);
+
+/**
+ * Read and parse the shipped schema. Never throws: a read failure is recorded
+ * on the returned source and degrades validation downstream, because importing
+ * this module must never be what breaks a delivery.
+ *
+ * @returns {{ schema: object|null, error: string|null }}
+ */
+function loadSchemaSource() {
+  try {
+    return {
+      schema: JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8')),
+      error: null,
+    };
+  } catch (err) {
+    return { schema: null, error: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * The schema, read and parsed at module load. Deliberately eager — see the
+ * module header for the failure that made it so.
+ *
+ * @type {{ schema: object|null, error: string|null }}
+ */
+const SCHEMA_SOURCE = loadSchemaSource();
+
+/**
+ * Compiled validators keyed by the source object they came from.
+ *
+ * A `WeakMap` rather than one module-level slot so an injected `schemaSource`
+ * (the test seam) can never poison the validator the production path memoizes.
+ *
+ * @type {WeakMap<object, Function>}
+ */
+const VALIDATORS = new WeakMap();
+
+/**
+ * Compile (once per source) and return the terminal-envelope validator, or
+ * `null` when the source carries no usable schema.
+ *
+ * @param {{ schema: object|null }} source
+ * @returns {Function|null}
+ */
+function getValidator(source) {
+  if (!source?.schema) return null;
+  const cached = VALIDATORS.get(source);
+  if (cached) return cached;
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(source.schema);
+  VALIDATORS.set(source, validate);
+  return validate;
+}
+
+let _unvalidatedWarned = false;
+
+/**
+ * Announce — once per process — that an envelope is going out unvalidated.
+ *
+ * Written straight to stderr rather than through `Logger.warn` for the same
+ * reason `emitTerminalEnvelope` bypasses `Logger.info`: the envelope itself is
+ * unsuppressible, so the notice that one was not checked has to be too. Under
+ * `AGENT_LOG_LEVEL=silent` a level-gated warning would vanish and the degrade
+ * would be invisible.
+ *
+ * @param {string|null|undefined} error
+ * @returns {void}
+ */
+function warnUnvalidated(error) {
+  if (_unvalidatedWarned) return;
+  _unvalidatedWarned = true;
+  process.stderr.write(
+    `[story-deliver-terminal] ⚠️ terminal-envelope schema unavailable (${error ?? 'unknown'}) — ` +
+      `emitting the envelope UNVALIDATED. The return contract is preserved; its shape is not checked. ` +
+      `Expected at: ${SCHEMA_PATH}\n`,
+  );
+}
+
+/**
+ * Validate a candidate envelope against the shipped schema.
+ *
+ * When the schema is unavailable the result reports `validated: false` and
+ * `valid: true` — a **deliberate degrade**, not an oversight. Losing the shape
+ * check costs a guard against a malformed envelope; throwing here costs the
+ * envelope entirely, and the envelope is the documented return contract of the
+ * delivery engine. An unvalidated terminal a caller can act on beats no
+ * terminal at all, so the unreadable-schema case degrades and says so on
+ * stderr while a schema *violation* still fails loudly at the writer.
+ *
+ * @param {object} envelope
+ * @param {{ schemaSource?: { schema: object|null, error: string|null } }} [opts]
+ *   `schemaSource` is a test seam — production always uses the eagerly loaded
+ *   module-level source.
+ * @returns {{ valid: boolean, errors: string[], validated: boolean }}
+ */
+export function validateTerminalEnvelope(
+  envelope,
+  { schemaSource = SCHEMA_SOURCE } = {},
+) {
+  const validate = getValidator(schemaSource);
+  if (!validate) {
+    warnUnvalidated(schemaSource?.error);
+    return { valid: true, errors: [], validated: false };
+  }
+  const valid = validate(envelope);
+  if (valid) return { valid: true, errors: [], validated: true };
+  const errors = (validate.errors ?? []).map(
+    (e) => `${e.instancePath || '/'} ${e.message}`,
+  );
+  return { valid: false, errors, validated: true };
+}

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -28,22 +28,12 @@
  * pre-#4543 pipeline collapsed by treating budget exhaustion as a block.
  */
 
-import { readFileSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { validateTerminalEnvelope } from './story-deliver-terminal-schema.js';
 
-import Ajv2020 from 'ajv/dist/2020.js';
-import addFormats from 'ajv-formats';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SCHEMA_PATH = path.resolve(
-  __dirname,
-  '..',
-  '..',
-  '..',
-  'schemas',
-  'story-deliver-terminal.schema.json',
-);
+// Re-exported so the schema split stays an implementation detail: every
+// consumer still reaches the validator through the envelope module that owns
+// the contract.
+export { validateTerminalEnvelope };
 
 export const TERMINAL_ENVELOPE_KIND = 'story-deliver-terminal';
 
@@ -152,39 +142,6 @@ export const NEXT_COMMANDS = Object.freeze({
   escalateToPlan: (prompt) => `/plan "${quoteForPlan(prompt)}"`,
 });
 
-/** @type {Function|null} */
-let _validator = null;
-
-/**
- * Compile (once) and return the terminal-envelope validator.
- *
- * @returns {Function}
- */
-function getValidator() {
-  if (_validator) return _validator;
-  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
-  const ajv = new Ajv2020({ allErrors: true, strict: false });
-  addFormats(ajv);
-  _validator = ajv.compile(schema);
-  return _validator;
-}
-
-/**
- * Validate a candidate envelope against the shipped schema.
- *
- * @param {object} envelope
- * @returns {{ valid: boolean, errors: string[] }}
- */
-export function validateTerminalEnvelope(envelope) {
-  const validate = getValidator();
-  const valid = validate(envelope);
-  if (valid) return { valid: true, errors: [] };
-  const errors = (validate.errors ?? []).map(
-    (e) => `${e.instancePath || '/'} ${e.message}`,
-  );
-  return { valid: false, errors };
-}
-
 /**
  * Drop `undefined`-valued keys so the schema's `additionalProperties: false`
  * and its nullable unions both stay satisfiable from one optional-argument
@@ -207,9 +164,14 @@ function compact(obj) {
  * Throws a `TypeError` naming the schema violations when the assembled
  * object does not validate. That is deliberate: the whole point of the
  * envelope is that a caller can trust its status without re-probing
- * GitHub, so emitting an unvalidated one would reintroduce the ambiguity
+ * GitHub, so emitting a *malformed* one would reintroduce the ambiguity
  * this replaces.
  *
+ * A schema that cannot be READ is the opposite case and does not throw —
+ * see {@link validateTerminalEnvelope}. "This envelope is wrong" is worth
+ * failing on; "I could not check this envelope" is not worth destroying
+ * the return contract over.
+ *
  * @param {object} args
  * @param {number|null} args.storyId `null` only for an `escalated` terminal,
  *   which by construction never authored a Story.
@@ -227,6 +189,9 @@ function compact(obj) {
  * @param {number} args.elapsedSeconds
  * @param {object|null} [args.waitBudget]
  * @param {string} [args.timestamp]
+ * @param {{ schema: object|null, error: string|null }} [args.schemaSource]
+ *   Test seam; never passed in production. Not part of the envelope — the
+ *   envelope is assembled from named fields only.
  * @returns {object} The validated envelope.
  */
 export function buildTerminalEnvelope({
@@ -245,6 +210,7 @@ export function buildTerminalEnvelope({
   elapsedSeconds = 0,
   waitBudget,
   timestamp = new Date().toISOString(),
+  schemaSource,
 }) {
   const envelope = compact({
     kind: TERMINAL_ENVELOPE_KIND,
@@ -268,7 +234,12 @@ export function buildTerminalEnvelope({
     timestamp,
   });
 
-  const { valid, errors } = validateTerminalEnvelope(envelope);
+  // Passing `{ schemaSource }` unconditionally is safe: an `undefined`
+  // property value is exactly what triggers the destructuring default on the
+  // other side, so production still gets the eagerly-loaded module source.
+  const { valid, errors } = validateTerminalEnvelope(envelope, {
+    schemaSource,
+  });
   if (!valid) {
     throw new TypeError(
       `buildTerminalEnvelope: assembled envelope violates story-deliver-terminal.schema.json:\n` +

package/.agents/scripts/lib/orchestration/ticket-validator-conflicts.js

@@ -449,15 +449,29 @@ function computeMissingBddScaffoldFindings(stories, reach, severity) {
  * Tasks satisfy (a) or (b). When ≥2 such Stories sit in the same wave (no
  * transitive `depends_on` between them), emit a single finding keyed by the
  * registry path.
+ *
+ * Reached from the module's `_internal` named export. The pass is pure — it
+ * performs no filesystem I/O and spawns no process — so its optional final
+ * `deps` parameter seams the three collaborating predicates rather than a
+ * built-in; each entry defaults to the real implementation
+ * (`.agents/rules/test-seams.md` rules 1-3: the defaults live on the function,
+ * never on a module-level mutable variable).
+ *
+ * @param {object} input
+ * @param {{
+ *   isRegistryPathImpl?: typeof isRegistryPath,
+ *   inSameWaveImpl?: typeof inSameWave,
+ *   registryRegistryImpl?: typeof registryRegistry,
+ * }} [deps]
  */
-function computeRegistryFindings({
-  stories,
-  reach,
-  patterns,
-  producers,
-  assumptionEntries,
-  severity,
-}) {
+function computeRegistryFindings(
+  { stories, reach, patterns, producers, assumptionEntries, severity },
+  {
+    isRegistryPathImpl = isRegistryPath,
+    inSameWaveImpl = inSameWave,
+    registryRegistryImpl = registryRegistry,
+  } = {},
+) {
   const findings = [];
   // Build the matching registry path set from producer & creator paths.
   const registryHits = new Map(); // registryPath -> Map<storySlug, producers[]>
@@ -474,7 +488,7 @@ function computeRegistryFindings({
   // (a) direct registry edits — object-form `{ path, assumption }` entries
   // from `indexAssumptionEntries` (and the producer index built from them).
   for (const [path, entries] of producers.entries()) {
-    if (!isRegistryPath(path, patterns)) continue;
+    if (!isRegistryPathImpl(path, patterns)) continue;
     for (const e of entries) {
       bump(path, {
         storySlug: e.storySlug,
@@ -485,7 +499,7 @@ function computeRegistryFindings({
     }
   }
   for (const e of assumptionEntries) {
-    if (!isRegistryPath(e.path, patterns)) continue;
+    if (!isRegistryPathImpl(e.path, patterns)) continue;
     bump(e.path, {
       storySlug: e.storySlug,
       taskSlug: e.taskSlug,
@@ -510,7 +524,7 @@ function computeRegistryFindings({
         continue;
       const childParent = parentDirOf(change.path);
       if (!childParent) continue;
-      for (const reg of registryRegistry(
+      for (const reg of registryRegistryImpl(
         producers,
         assumptionEntries,
         patterns,
@@ -532,7 +546,7 @@ function computeRegistryFindings({
     const cluster = new Set();
     for (let i = 0; i < stories.length; i += 1) {
       for (let j = i + 1; j < stories.length; j += 1) {
-        if (inSameWave(reach, stories[i], stories[j])) {
+        if (inSameWaveImpl(reach, stories[i], stories[j])) {
           cluster.add(stories[i]);
           cluster.add(stories[j]);
         }

package/.agents/scripts/lib/stdio-flush.js

@@ -0,0 +1,71 @@
+// .agents/scripts/lib/stdio-flush.js
+/**
+ * Stdio drain helper (Story #4783).
+ *
+ * `process.stdout` / `process.stderr` are only synchronous when they point at
+ * a TTY or a regular file. On a **pipe** — every `cmd | consumer`, every
+ * `child_process` capture, every `$(...)` substitution — Node writes
+ * asynchronously once the 64 KiB kernel pipe buffer fills: `write()` returns
+ * `false` and the remaining bytes sit in the stream's internal queue until the
+ * reader drains it.
+ *
+ * `process.exit()` does not wait for that queue. Anything still buffered when
+ * the process terminates is discarded, so a CLI that emits more than a pipe
+ * buffer's worth of output and then exits eagerly silently truncates — the
+ * exit code still reads green, and the consumer parses a half-written
+ * envelope. `runAsCli` is the shared boundary where that used to happen for
+ * every `.agents/scripts` entry point.
+ *
+ * The fix is to stop exiting eagerly (set `process.exitCode` and let the loop
+ * drain naturally). This helper is the belt-and-braces half: an explicit await
+ * on the queued bytes, so the flush is complete before the CLI's last frame
+ * unwinds even when something further out terminates the process.
+ *
+ * @module stdio-flush
+ */
+
+/**
+ * Await the point at which one writable stream's queued bytes have been handed
+ * to the OS. Resolves immediately when the stream has nothing queued, is not
+ * writable, or is not a stream at all — a flush must never be the reason a
+ * process hangs.
+ *
+ * Both settle paths are covered: the zero-length `write()` callback (which
+ * fires after every previously queued chunk, since writes are ordered) and the
+ * `'drain'` event (which fires when a backed-up stream empties). Whichever
+ * lands first resolves; the other is detached.
+ *
+ * @param {NodeJS.WritableStream & { writableLength?: number, writableEnded?: boolean, destroyed?: boolean }} [stream]
+ * @returns {Promise<void>}
+ */
+function drainStream(stream) {
+  if (!stream || typeof stream.write !== 'function') return Promise.resolve();
+  if (stream.destroyed || stream.writableEnded) return Promise.resolve();
+  if ((stream.writableLength ?? 0) === 0) return Promise.resolve();
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      stream.removeListener?.('drain', done);
+      resolve();
+    };
+    stream.once?.('drain', done);
+    // The write callback fires once this (empty) chunk — and therefore every
+    // chunk queued ahead of it — has been flushed to the underlying handle.
+    stream.write('', done);
+  });
+}
+
+/**
+ * Await the drain of the process's stdio streams. Never rejects: a stream that
+ * errored, closed, or was never writable resolves as already-flushed.
+ *
+ * @param {Array<NodeJS.WritableStream|undefined>} [streams] Defaults to
+ *   `[process.stdout, process.stderr]`.
+ * @returns {Promise<void>}
+ */
+export async function flushStdio(streams = [process.stdout, process.stderr]) {
+  await Promise.all(streams.map((stream) => drainStream(stream)));
+}

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

@@ -1,4 +1,5 @@
-import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import { createRequire, SourceMap } from 'node:module';
 import path from 'node:path';
 import { Logger } from './Logger.js';
 
@@ -39,6 +40,71 @@ function isTypeScriptPath(filePath) {
   return TS_EXTS.has(path.extname(String(filePath)).toLowerCase());
 }
 
+/**
+ * Trailing `//# sourceMappingURL=…` comment `ts.transpileModule` appends
+ * when `sourceMap: true` is requested. Stripping it makes the emitted code
+ * byte-identical to the `sourceMap: false` emit, which is what keeps the
+ * maintainability path — and every MI score in the committed baseline —
+ * untouched by the CRAP path opting into a map.
+ */
+const SOURCE_MAPPING_URL_RE = /\n?\/\/# sourceMappingURL=[^\n]*\n?$/;
+
+/**
+ * Build a `transpiledLine → originalLine` resolver over a raw
+ * `sourceMapText` payload, using Node's built-in `SourceMap` (no new
+ * runtime dependency).
+ *
+ * `SourceMap#findEntry(line, column)` is 0-based and returns the mapping at
+ * or before the requested position, so a bare `findEntry(line, 0)` can
+ * silently answer with a *previous* line's mapping when the requested line
+ * carries no mapping at column 0. The resolver therefore walks the columns
+ * of the generated line and accepts only an entry that actually originates
+ * on that generated line; a line with no mapping at all resolves to `null`
+ * and the caller falls back to the un-remapped coordinate.
+ *
+ * Results are memoised per generated line — a file's methods are looked up
+ * once each, but the same line is often probed by several callers.
+ *
+ * @param {string} sourceMapText Raw JSON source map emitted by TypeScript.
+ * @param {string} code The generated (transpiled) code the map describes.
+ * @returns {((line: number) => number|null)|null}
+ */
+function buildLineMapper(sourceMapText, code) {
+  let sourceMap;
+  try {
+    sourceMap = new SourceMap(JSON.parse(sourceMapText));
+  } catch {
+    return null;
+  }
+  const lines = String(code).split('\n');
+  const memo = new Map();
+  return function mapLine(generatedLine) {
+    if (typeof generatedLine !== 'number' || generatedLine < 1) return null;
+    if (memo.has(generatedLine)) return memo.get(generatedLine);
+    const zeroBased = generatedLine - 1;
+    const lineText = lines[zeroBased] ?? '';
+    let resolved = null;
+    for (let column = 0; column <= lineText.length; column += 1) {
+      let entry;
+      try {
+        entry = sourceMap.findEntry(zeroBased, column);
+      } catch {
+        break;
+      }
+      if (
+        entry &&
+        entry.generatedLine === zeroBased &&
+        typeof entry.originalLine === 'number'
+      ) {
+        resolved = entry.originalLine + 1;
+        break;
+      }
+    }
+    memo.set(generatedLine, resolved);
+    return resolved;
+  };
+}
+
 /**
  * Pre-transpile TypeScript or TSX sources to JavaScript that the
  * Esprima-based escomplex kernel can parse. Returns the input unchanged
@@ -54,12 +120,33 @@ function isTypeScriptPath(filePath) {
  * On transpile failure the helper returns `null` — callers treat that
  * as "skip this file" rather than crashing the scan.
  *
+ * **Line coordinates (Story #4775).** The transpile does not preserve line
+ * numbers: interface elision and the injected JSX-runtime import shift the
+ * emitted code relative to the original source. escomplex then reports each
+ * method's `lineStart` in *transpiled* coordinates while istanbul's `fnMap`
+ * is in *original source* coordinates — so a per-method coverage join keyed
+ * on the raw `lineStart` cannot match. Callers that need to join against
+ * coverage pass `{ withLineMap: true }` and receive
+ * `{ code, mapLine }`, where `mapLine(transpiledLine)` returns the original
+ * source line (or `null` when the line has no mapping).
+ *
+ * `withLineMap` is opt-in precisely so the maintainability path — which is
+ * module-level and never joins coverage — keeps paying nothing for a map it
+ * would not read, and keeps emitting byte-identical scores. A JavaScript
+ * input is a passthrough in both modes: `mapLine` is `null` because the
+ * coordinates already *are* original-source coordinates, so no remap is
+ * needed and none is computed.
+ *
  * @param {string} filePath
  * @param {string} source
- * @returns {string|null}
+ * @param {{withLineMap?: boolean}} [opts]
+ * @returns {string|null|{code: string, mapLine: ((line: number) => number|null)|null}}
  */
-export function transpileIfNeeded(filePath, source) {
-  if (!isTypeScriptPath(filePath)) return source;
+export function transpileIfNeeded(filePath, source, opts = {}) {
+  const withLineMap = opts?.withLineMap === true;
+  if (!isTypeScriptPath(filePath)) {
+    return withLineMap ? { code: source, mapLine: null } : source;
+  }
   const ts = loadTypeScript();
   if (!ts) {
     Logger.warn(
@@ -78,12 +165,18 @@ export function transpileIfNeeded(filePath, source) {
         importHelpers: false,
         removeComments: false,
         jsx: ts.JsxEmit.ReactJSX,
-        sourceMap: false,
+        sourceMap: withLineMap,
       },
       fileName: path.basename(filePath),
       reportDiagnostics: false,
     });
-    return result.outputText;
+    if (!withLineMap) return result.outputText;
+    const code = result.outputText.replace(SOURCE_MAPPING_URL_RE, '\n');
+    const mapLine =
+      typeof result.sourceMapText === 'string'
+        ? buildLineMapper(result.sourceMapText, code)
+        : null;
+    return { code, mapLine };
   } catch (err) {
     Logger.warn(
       `[Maintainability] ⚠ TS transpile failed for ${filePath}: ${err?.message ?? err}; skipping.`,
@@ -91,3 +184,37 @@ export function transpileIfNeeded(filePath, source) {
     return null;
   }
 }
+
+/**
+ * Prepare a source file for scoring: read it, transpile TS/TSX with a
+ * line map, and hand back the JavaScript escomplex will parse alongside the
+ * transpiled → original-source line resolver the coverage join needs
+ * (Story #4775).
+ *
+ * Failure is reported as `{error: 'read'}` or `{error: 'transpile'}` rather
+ * than a bare null: CRAP drops the file either way, but the combined MI path
+ * distinguishes them (a read failure drops the MI score, a transpile failure
+ * scores it 0 — matching `calculateForFile`).
+ *
+ * @param {string} abs Absolute path of the source file.
+ * @param {{readFile?: (p: string) => string, transpile?: Function}} [deps]
+ * @returns {{code: string, mapLine: ((line: number) => number|null)|null}
+ *   | {error: 'read'|'transpile'}}
+ */
+export function prepareSourceForScoring(abs, deps = {}) {
+  const readFile = deps.readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
+  const transpile = deps.transpile ?? transpileIfNeeded;
+  let source;
+  try {
+    source = readFile(abs);
+  } catch {
+    return { error: 'read' };
+  }
+  const prepared = transpile(abs, source, { withLineMap: true });
+  if (prepared === null || prepared === undefined)
+    return { error: 'transpile' };
+  // Tolerate a `deps.transpile` stub that still returns a bare string.
+  if (typeof prepared === 'string') return { code: prepared, mapLine: null };
+  if (typeof prepared.code !== 'string') return { error: 'transpile' };
+  return { code: prepared.code, mapLine: prepared.mapLine ?? null };
+}