mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/dead-exports-knip.js

@@ -1,9 +1,6 @@
 /**
- * dead-exports-knip.js — the knip driver behind the dead-export ratchet.
- *
- * Owns everything about talking to knip and normalising what comes back:
- * spawning it, reading a pre-captured report, and flattening its report into
- * `{ file, symbol }` rows. `check-dead-exports.js` stays a thin CLI over this.
+ * dead-exports-knip.js — run knip and flatten its report into
+ * `{ file, symbol }` rows for the dead-export ratchet.
  *
  * @module lib/dead-exports-knip
  */
@@ -13,19 +10,12 @@ import fs from 'node:fs';
 import process from 'node:process';
 
 /**
- * Spawn `npx knip --reporter json --no-progress` and return the parsed
- * envelope. Never throws — the caller logs the error and treats current rows as
- * empty, which surfaces every baseline row as "removed": loud, but safe.
- *
- * `production` adds knip's `--production` flag, which restricts analysis to
- * entry/project patterns carrying the `!` suffix in `knip.json`. The test globs
- * deliberately lack that suffix, so production mode drops them as entry points
- * and an export reachable only from a test reads as dead. Without those
- * suffixes production mode has no entry patterns at all and reports nothing —
- * `knip.json` and this flag are a matched pair.
+ * Never throws; on error the caller treats current rows as empty, which
+ * surfaces every baseline row as removed — loud but safe.
  *
- * Exported as a hook so tests can stub the spawn without a working knip
- * workspace.
+ * `production` requires the `!`-suffixed entry patterns in `knip.json`
+ * (test globs deliberately lack it, so test-only exports read as dead);
+ * without them production mode silently reports nothing.
  *
  * @param {{ cwd?: string, spawn?: typeof spawnSync, production?: boolean }} [opts]
  * @returns {{ ok: true, envelope: unknown } | { ok: false, error: string }}
@@ -61,9 +51,6 @@ export function runKnip({
 }
 
 /**
- * Read a pre-captured knip JSON envelope from disk (the `--knip-output` test
- * seam). Returns the parsed envelope or `null` on failure.
- *
  * @param {string} filePath
  * @returns {unknown}
  */
@@ -75,26 +62,15 @@ export function readKnipOutput(filePath) {
   }
 }
 
-/**
- * Sentinel `symbol` recorded for a **whole-file death** row.
- *
- * Knip's `files` category names a module nothing in the graph imports. There
- * is no per-export identity to record — the whole file is the finding — so the
- * ratchet encodes exactly one row per dead file carrying this symbol. `*` is
- * not a legal JavaScript identifier, so a whole-file row can never collide
- * with a real export row for the same path.
- */
+/** Whole-file death row symbol; not a legal identifier, so it cannot collide. */
 const WHOLE_FILE_SYMBOL = '*';
 
 /**
- * Pull the dead-file paths out of one knip issue's `files` category.
- *
- * Knip emits `files: [{ name: '<path>' }]`, but tolerate a bare string and
- * fall back to the issue's own `file` so a reporter-shape change degrades to
- * "one row for this path" rather than to silence.
+ * Tolerates bare strings and falls back to the issue's own `file`, so a
+ * reporter-shape change degrades to one row rather than silence.
  *
  * @param {{ files?: unknown }} issue
- * @param {string} fallbackFile The issue's own `file` path.
+ * @param {string} fallbackFile
  * @returns {string[]}
  */
 function extractDeadFileNames(issue, fallbackFile) {
@@ -111,8 +87,7 @@ function extractDeadFileNames(issue, fallbackFile) {
 }
 
 /**
- * Pull the dead-export symbol names out of one knip issue's `exports`
- * category. Knip emits `exports: [{ name, ... }]`; older shapes used `symbol`.
+ * Accepts `name` or the older `symbol` field.
  *
  * @param {{ exports?: unknown }} issue
  * @returns {string[]}
@@ -131,26 +106,13 @@ function extractDeadExportSymbols(issue) {
 }
 
 /**
- * Flatten knip's `--reporter json` output into `{ file, symbol }` rows. Knip
- * emits `{ issues: [{ file, files: [...], exports: [{ name, ... }], ... }] }`.
- *
- * Two categories are mapped, and the ratchet treats their rows identically:
- *
- * - **`exports`** → one row per unused export, `{ file, symbol: '<name>' }`.
- * - **`files`** → one row per module nothing imports,
- *   `{ file, symbol: '*' }`. Story #5001 added this leg: mapping only
- *   `exports` made the ratchet structurally blind to *whole-file* death, so a
- *   module could lose its last caller and every one of its exports go unused
- *   without a single row changing. Knip reports such a module once, under
- *   `files`, and suppresses its per-export rows — which is exactly why the
- *   export-only reading saw nothing.
- *
- * Whole-file rows are de-duplicated by path so the row set is stable across
- * runs regardless of how many issue records mention the same file. Dependency-
- * and duplicate-level issues stay ignored; knip surfaces those under their own
- * `rules` keys and they are not a code-death signal.
+ * Maps `exports` (one row per unused export) and `files` (one `'*'` row per
+ * unimported module, de-duplicated). The `files` leg is required: knip
+ * suppresses a dead module's per-export rows, so an export-only reading is
+ * blind to whole-file death. Dependency issues are not code death and are
+ * ignored.
  *
- * @param {unknown} knipEnvelope The parsed knip JSON report.
+ * @param {unknown} knipEnvelope
  * @returns {Array<{ file: string, symbol: string }>}
  */
 export function extractRowsFromKnip(knipEnvelope) {

package/.agents/scripts/lib/dead-exports-mode.js

@@ -1,42 +1,23 @@
 /**
- * dead-exports-mode.js — the two passes of the dead-export ratchet.
- *
- * The gate runs twice with different reachability assumptions, and each pass
- * needs a matched triple: which knip invocation to make, which baseline to
- * ratchet against, and how to label its output. Resolving that triple in one
- * place keeps the three from drifting apart — a pass that ran production knip
- * against the default baseline would report every test-only export as newly
- * dead and fail the build for no reason.
- *
- * - **default** — `tests/**` are knip entry points, so an export imported only
- *   by a test reads as used. This is the historical gate.
- * - **production** — knip's `--production` drops the test entries, so an export
- *   no production code reaches reads as dead. Depends on the `!` pattern
- *   suffixes in `knip.json`; without them production mode has no entry points
- *   and silently reports nothing.
- *
- * The two ratchet against separate baselines on purpose. This repo sanctions
- * exporting purely for a test (`.agents/rules/test-seams.md`), so the
- * production row set is large and mostly intentional; merging it into the
- * default baseline would destroy that baseline's meaning.
+ * dead-exports-mode.js — the matched knip-mode / baseline / label triple for
+ * each dead-export pass; mixing them (production knip against the default
+ * baseline) would flag every test-only export as newly dead. Separate
+ * baselines on purpose: exporting for tests is sanctioned, so the production
+ * row set is large and mostly intentional.
  *
  * @module lib/dead-exports-mode
  */
 
 import path from 'node:path';
 
-/** Baseline for the default pass (test entry points included). */
 const DEFAULT_BASELINE = path.join('baselines', 'dead-exports.json');
 
-/** Baseline for the `--production` pass (test-only-importer discount). */
 const PRODUCTION_BASELINE = path.join(
   'baselines',
   'dead-exports-production.json',
 );
 
 /**
- * Resolve the baseline / label / mode-tag triple for a pass.
- *
  * @param {boolean} production
  * @returns {{ mode: 'production'|'default', label: string, baseline: string }}
  */

package/.agents/scripts/lib/degraded-mode.js

@@ -1,21 +1,10 @@
 /**
- * Shared helper for the explicit-degraded contract used by soft-failing gates.
- *
- * Tech Spec #819 §"Degraded-mode contract (Story 3)" — three soft-fail sites
- * (audit-suite selector diff-timeout, lint-baseline JSON-parse, baseline-refresh
- * guardrail git-diff) historically returned a silent zero/empty result. Two
- * remain; the lint-baseline site left with its CLI. The contract is:
- *
- *   { ok: false, degraded: true, reason: <code>, detail: <human> }
- *
- * with a non-zero CLI exit so the operator/agent has explicit visibility, OR
- * a hard-fail closed when `--gate-mode` / `MANDREL_GATE_MODE=1` is set
- * (CI invocations).
+ * Explicit-degraded contract for soft-failing gates: return the degraded
+ * envelope (with a non-zero CLI exit) instead of a silent empty result, or
+ * hard-fail when `--gate-mode` / `MANDREL_GATE_MODE=1` is set (CI).
  */
 
 /**
- * Build the canonical degraded envelope.
- *
  * @param {string} reason  Machine-readable code (e.g. `GIT_DIFF_TIMEOUT`).
  * @param {string} [detail] Human-readable explanation for operators.
  * @returns {{ ok: false, degraded: true, reason: string, detail: string }}
@@ -24,9 +13,6 @@ export function degraded(reason, detail = '') {
   return { ok: false, degraded: true, reason, detail };
 }
 
-/**
- * True when `value` carries the degraded envelope shape.
- */
 export function isDegraded(value) {
   return Boolean(
     value &&
@@ -37,11 +23,6 @@ export function isDegraded(value) {
   );
 }
 
-/**
- * Decide whether the caller is running in gate-mode (hard-fail closed) based
- * on argv and env. CI invocations set `--gate-mode` or
- * `MANDREL_GATE_MODE=1`; local invocations leave both unset.
- */
 export function isGateMode({ argv = process.argv, env = process.env } = {}) {
   if (Array.isArray(argv) && argv.includes('--gate-mode')) return true;
   if (env && env.MANDREL_GATE_MODE === '1') return true;
@@ -49,10 +30,6 @@ export function isGateMode({ argv = process.argv, env = process.env } = {}) {
 }
 
 /**
- * In gate-mode, throw a hard-fail Error keyed to `reason`. Otherwise return
- * the degraded envelope. Centralises the if-gate-mode branch so each site has
- * a single call site.
- *
  * @param {string} reason
  * @param {string} [detail]
  * @param {{ argv?: string[], env?: NodeJS.ProcessEnv }} [opts]

package/.agents/scripts/lib/dependency-parser.js

@@ -1,31 +1,14 @@
 /**
- * dependency-parser.js — Shared Dependency & Metadata Parsing Utilities
- *
- * Canonical implementation of dependency-related regex parsing and
- * ticket metadata extraction, shared by the ticketing provider and the
- * orchestration layer (e.g. providers/github/tickets.js,
- * lib/story-adjacency.js, lib/branch-name-guard.js).
+ * dependency-parser.js — dependency-edge and ticket-metadata parsing shared
+ * by the ticketing provider and orchestration layer.
  */
 
 import { parseFooterBlockedByIds } from './story-body/footer-block.js';
 
 /**
- * Parse a body's declared blocker issue numbers — **footer-scoped and
- * strict**.
- *
- * Only a `blocked by #N` line standing alone inside the `---` footer block
- * declares an edge. The unanchored predecessor scanned the whole body for
- * `blocked by|depends on #N` anywhere, so a Story whose prose merely mentioned
- * a blocker — an example, a changelog note, an acceptance criterion describing
- * this very defect — minted a real dispatch gate that withheld the Story until
- * an unrelated issue closed.
- *
- * The behaviour change is deliberate and user-visible: prose-only mentions
- * outside the footer no longer gate. Every machine-authored body already
- * carries the canonical footer form (`plan-persist` has always serialized it),
- * so only hand-written prose edges are affected — those must be moved into the
- * footer block to keep gating. The grammar itself lives in
- * `lib/story-body/footer-block.js`, shared with the body parser.
+ * Footer-scoped and strict: only a standalone `blocked by #N` line in the
+ * `---` footer declares an edge. Prose mentions elsewhere never gate, so a
+ * hand-written edge must live in the footer.
  *
  * @param {string} body - Issue body or freeform text.
  * @returns {number[]} Array of issue numbers this body declares as blockers.
@@ -35,8 +18,6 @@ export function parseBlockedBy(body) {
 }
 
 /**
- * Parse `blocks #NNN` references from text.
- *
  * @param {string} body - Issue body or freeform text.
  * @returns {number[]} Array of issue numbers this text declares as blocked.
  */
@@ -47,11 +28,7 @@ export function parseBlocks(body) {
 }
 
 /**
- * Extract the parent Epic id from a ticket body. Matches `Epic: #NNN`
- * anchored to the start of a line (multiline + case-insensitive). The
- * anchored form prevents accidental matches inside prose ("...this Epic:
- * #...follow-on..."). Used during state-transition notification dispatch
- * and Story-level execution planning.
+ * Line-anchored `Epic: #N`, so prose like "this Epic: #…" cannot match.
  *
  * @param {string|null|undefined} body
  * @returns {number|null}
@@ -63,22 +40,15 @@ export function extractEpicIdFromBody(body) {
 }
 
 /**
- * Validates that a string is safe to use as a git branch name component.
- * Rejects shell metacharacters, whitespace, and other dangerous patterns.
+ * Allow-list: alphanumerics, `.`, `_`, `-`, `/`.
  *
  * @param {string} value - The value to validate.
  * @returns {boolean} True if safe for use in branch names.
  */
 export function isSafeBranchComponent(value) {
-  // Allow: alphanumeric, hyphens, underscores, dots, forward slashes
-  // Reject: everything else (shell metacharacters, spaces, etc.)
   return /^[a-zA-Z0-9._\-/]+$/.test(value);
 }
 
-/**
- * Pre-compiled `**Key**: value` matchers for every metadata key we extract.
- * Construction cost is paid once at module load rather than per task.
- */
 const METADATA_FIELD_KEYS = [
   'Persona',
   'Mode',
@@ -94,9 +64,7 @@ const METADATA_FIELD_RES = new Map(
 );
 
 /**
- * Parse task execution metadata from the `## Metadata` section of a ticket body.
- * Returns a plain object with `persona`, `mode`, `skills`, `focusAreas`,
- * and `protocolVersion`.
+ * Parse the `## Metadata` section's `**Key**: value` fields.
  *
  * @param {string} body - Issue body text.
  * @returns {{ persona: string, mode: string, skills: string[], focusAreas: string[], protocolVersion: string }}

package/.agents/scripts/lib/dependency-version.js

@@ -1,21 +1,9 @@
 /**
- * dependency-version.js — read an installed package's version without
- * evaluating the package (Story #5109).
- *
- * Baselines stamp the versions of the tools that produced them so a consumer
- * can detect scorer drift. The obvious way to get one — `require(pkg).version`
- * — pays the package's whole module-initialisation cost for a string that is
- * sitting in a manifest a few kilobytes long. For `typescript` that was ~65 ms
- * of CPU and ~75 MB of RSS on every `check-baselines --gate crap` and every
- * `quality-preview` run, in a repository with no TypeScript in it at all.
- *
- * `require.resolve` walks the resolver without reading or executing the
- * target, so everything here is path arithmetic plus one small `JSON.parse`.
- *
- * This deliberately does **not** replace `crap-utils.js#resolveEscomplexVersion`,
- * which answers a different question: it walks `node_modules` upward from a
- * caller-supplied `cwd` rather than resolving from this module's own location,
- * because the escomplex stamp must describe the tree being scanned.
+ * dependency-version.js — read an installed package's version from its
+ * manifest without evaluating the package (`require(pkg).version` pays the
+ * whole module init; for `typescript` that is tens of ms and MB per gate).
+ * Unlike `crap-utils.js#resolveEscomplexVersion`, this resolves from this
+ * module's location, not a scanned `cwd`.
  *
  * @module lib/dependency-version
  */
@@ -24,17 +12,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /**
- * Locate a package's manifest via the module resolver, without loading it.
+ * Tries `<pkg>/package.json` first; when `exports` withholds it, resolves the
+ * main entry and walks up — still evaluation-free.
  *
- * The `<pkg>/package.json` subpath is tried first because it is a single
- * resolver call. A package whose `exports` map withholds `./package.json`
- * falls back to resolving the main entry and walking up to the nearest
- * `package.json`, which is still evaluation-free.
- *
- * @param {string} name Package name, e.g. `'typescript'`.
- * @param {NodeJS.Require} requireFn A `createRequire`-produced require whose
- *   resolution base is the calling module.
- * @returns {string | null} Absolute manifest path, or `null` when unresolvable.
+ * @param {string} name
+ * @param {NodeJS.Require} requireFn
+ * @returns {string | null}
  */
 function resolveManifestPath(name, requireFn) {
   try {
@@ -60,15 +43,10 @@ function resolveManifestPath(name, requireFn) {
 }
 
 /**
- * Resolve an installed package's declared version.
- *
- * Returns `null` — never a guess and never a throw — when the package cannot
- * be resolved, its manifest cannot be read or parsed, or it declares no
- * usable `version`. Callers map that onto their own sentinel (the baseline
- * writers use `'0.0.0'`, meaning "unknown environment").
+ * `null` — never a guess or a throw — when unresolvable or versionless.
  *
- * @param {string} name Package name.
- * @param {NodeJS.Require} requireFn A `createRequire`-produced require.
+ * @param {string} name
+ * @param {NodeJS.Require} requireFn
  * @returns {string | null}
  */
 export function resolveDependencyVersion(name, requireFn) {

package/.agents/scripts/lib/detect-package-manager.js

@@ -1,39 +1,14 @@
 /**
- * detect-package-manager — shared lockfile-probe helper (Story #4048 B3).
- *
- * Several independent copies of this lockfile probe existed across the
- * codebase before this consolidation:
- *   - `lib/cli/update.js#detectPackageManager`
- *   - `lib/bootstrap/project-bootstrap.js#detectPackageManager`
- *   - `lib/runtime-deps/preflight.js#detectPackageManager`
- *   - `lib/worktree/node-modules-strategy.js#selectInstallCommand` (inline)
- *
- * This module is the single authoritative implementation. It uses the
- * strictest semantics from the prior copies: detects `bun` in addition to
- * pnpm/yarn/npm, returns `null` when the directory has no Node manifest at
- * all (not even `package.json`), and optionally reports `workspaceRoot` for
- * pnpm (the `update.js` caller's unique requirement).
- *
- * All callers must handle `null` explicitly — it means the directory carries
- * no recognizable Node toolchain, so callers that need a concrete fallback
- * should coerce: `detectPm(root) ?? 'npm'`.
- *
- * Injectable seams: the `exists` parameter replaces `fs.existsSync` so
- * callers can drive the function with an in-memory fixture in unit tests.
- *
- * Builtins only — this module runs before third-party packages are
- * guaranteed to be present and is also imported from the worktree and
- * runtime-deps preflight guards.
+ * detect-package-manager — the single lockfile probe. `null` means no Node
+ * manifest at all; callers needing a default coerce (`?? 'npm'`). Builtins
+ * only: it runs before third-party packages are guaranteed present.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 
 /**
- * Detect the package manager from lockfile and manifest presence.
- *
- * Precedence: `pnpm-lock.yaml` > `yarn.lock` > `bun.lockb` >
- * `package-lock.json` > `package.json` (npm without a lockfile yet) > `null`.
+ * Precedence: pnpm > yarn > bun > package-lock > bare `package.json` (npm).
  *
  * @param {string} root - Absolute directory to probe (consumer project root).
  * @param {(p: string) => boolean} [exists=fs.existsSync] - Path existence probe.
@@ -49,13 +24,8 @@ export function detectPackageManager(root, exists = fs.existsSync) {
 }
 
 /**
- * Detect the package manager and whether the directory is a pnpm workspace
- * root. The `workspaceRoot` flag is `true` only for pnpm when
- * `pnpm-workspace.yaml` is present alongside the lockfile — the signal that
- * `pnpm add` must carry `-w` to target the workspace-root manifest.
- *
- * Used by `lib/cli/update.js` which needs both pieces of information to
- * construct the correct install command.
+ * `workspaceRoot` is true only for pnpm with `pnpm-workspace.yaml` — then
+ * `pnpm add` needs `-w`.
  *
  * @param {string} root - Absolute directory to probe.
  * @param {(p: string) => boolean} [exists=fs.existsSync] - Path existence probe.