mandrel 2.21.0 → 2.22.0

package/.agents/scripts/lib/orchestration/review-providers/native.js

@@ -40,7 +40,6 @@
  * @typedef {import('./types.js').ReviewProvider} ReviewProvider
  */
 
-import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from '../../cpu-pool.js';
 import { gitSpawn } from '../../git-utils.js';
@@ -54,6 +53,20 @@ import {
 } from '../../observability/runtime-friction.js';
 import { PROJECT_ROOT } from '../../project-root.js';
 import { transpileIfNeeded } from '../../transpile.js';
+import {
+  parseLintOutput,
+  partitionFilesForLint,
+  runScopedLint,
+} from './scoped-lint.js';
+
+/**
+ * The scoped-lint surface lives in [`scoped-lint.js`](scoped-lint.js), which
+ * owns runner resolution, per-surface classification, and the merge. Story
+ * #4839 moved it there while fixing the three invocation defects that made this
+ * gate fail open on ~78% of deliveries; the module docstring there carries the
+ * diagnosis. The three names stay part of this provider's published lint seam.
+ */
+export { parseLintOutput, partitionFilesForLint, runScopedLint };
 
 /** Worker entry that scores one file into a full maintainability report. */
 const MAINTAINABILITY_REPORT_WORKER_URL = new URL(
@@ -74,72 +87,6 @@ export const SERIAL_THRESHOLD = POOL_SERIAL_THRESHOLD;
 
 const JS_MAINTAINABILITY_EXTS = new Set(['.js', '.mjs', '.cjs']);
 
-/**
- * Parse stdout/stderr from a lint runner to estimate error vs warning counts.
- *
- * Handles the two runners composing `npm run lint` in this project:
- *   - Biome: emits "Found N error(s)." and "Found N warning(s)." lines.
- *   - markdownlint: emits one diagnostic per issue, plus a trailing
- *     "Summary: N error(s)" line.
- *
- * Severity classification: when the runner exits non-zero but its output
- * matches neither known reporter format, the result is "could not classify" —
- * `executionFailed: true` so callers can degrade the gate to a suggestion +
- * skipped marker rather than mislabelling an environment problem as high risk.
- *
- * Exported for testing.
- *
- * @param {{ status: number, stdout: string, stderr: string }} result
- * @returns {{ errors: number, warnings: number, parsed: boolean, executionFailed: boolean }}
- */
-export function parseLintOutput(result) {
-  const combined = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
-
-  let errors = 0;
-  let warnings = 0;
-  let parsed = false;
-
-  const errMatches = combined.matchAll(/Found\s+(\d+)\s+error/gi);
-  for (const m of errMatches) {
-    errors += Number(m[1]);
-    parsed = true;
-  }
-  const warnMatches = combined.matchAll(/Found\s+(\d+)\s+warning/gi);
-  for (const m of warnMatches) {
-    warnings += Number(m[1]);
-    parsed = true;
-  }
-
-  const mdSummary = combined.match(/Summary:\s+(\d+)\s+error/i);
-  if (mdSummary) {
-    errors += Number(mdSummary[1]);
-    parsed = true;
-  }
-
-  const executionFailed = !parsed && result.status !== 0;
-
-  return { errors, warnings, parsed, executionFailed };
-}
-
-/**
- * Pure: split changed paths into the file lists each lint runner consumes.
- *
- * Exported for testing.
- *
- * @param {string[]} changedFiles
- * @returns {{ code: string[], md: string[] }}
- */
-export function partitionFilesForLint(changedFiles) {
-  const CODE = /\.(js|mjs|cjs|jsx|ts|tsx|json|jsonc)$/i;
-  const code = [];
-  const md = [];
-  for (const f of changedFiles) {
-    if (CODE.test(f)) code.push(f);
-    else if (/\.md$/i.test(f)) md.push(f);
-  }
-  return { code, md };
-}
-
 /**
  * Read a changed file's content as it exists at `headRef` via
  * `git show <headRef>:<relPath>`, rather than reading the on-disk copy at
@@ -197,61 +144,6 @@ export function scoreSourceReport(source, relPath) {
   return calculateReport(prepared);
 }
 
-function spawnLintRunner(bin, args, cwd) {
-  const result = spawnSync('npx', ['--no', bin, ...args], {
-    cwd,
-    encoding: 'utf-8',
-    shell: process.platform === 'win32',
-  });
-  return {
-    status: result.status ?? 1,
-    stdout: result.stdout ?? '',
-    stderr: result.stderr ?? '',
-  };
-}
-
-/**
- * Run lint scoped to the changed surface only. Returns a normalized summary
- * compatible with `parseLintOutput` plus a `skipped` flag set when there is
- * no JS or markdown file in the changed set (nothing to lint).
- *
- * @param {string[]} changedFiles
- * @param {string} cwd
- * @param {(bin: string, args: string[], cwd: string) => { status: number, stdout: string, stderr: string }} [runnerFn]
- * @returns {{ errors: number, warnings: number, parsed: boolean, skipped: boolean, mode: 'changed-only', executionFailed?: boolean }}
- */
-export function runScopedLint(changedFiles, cwd, runnerFn = spawnLintRunner) {
-  const { code, md } = partitionFilesForLint(changedFiles);
-  if (code.length === 0 && md.length === 0) {
-    return {
-      errors: 0,
-      warnings: 0,
-      parsed: false,
-      skipped: true,
-      mode: 'changed-only',
-    };
-  }
-
-  const runs = [];
-  if (code.length > 0) runs.push(runnerFn('biome', ['lint', ...code], cwd));
-  if (md.length > 0) {
-    runs.push(
-      runnerFn('markdownlint', [...md, '--ignore', 'node_modules'], cwd),
-    );
-  }
-
-  let status = 0;
-  let stdout = '';
-  let stderr = '';
-  for (const r of runs) {
-    if ((r.status ?? 1) > status) status = r.status ?? 1;
-    stdout += r.stdout ?? '';
-    stderr += r.stderr ?? '';
-  }
-  const summary = parseLintOutput({ status, stdout, stderr });
-  return { ...summary, skipped: false, mode: 'changed-only' };
-}
-
 /**
  * Pure: classify a single file's maintainability report into a row + optional
  * Finding-shaped entries. `reportFn` is the thunk that produces the file's
@@ -523,6 +415,8 @@ async function runLintPhase({
       parsed: false,
       skipped: true,
       mode: 'off',
+      executionFailed: false,
+      degradations: [],
     };
   }
   logger?.info?.(
@@ -531,6 +425,35 @@ async function runLintPhase({
   return runScopedLintFn(changedFiles, PROJECT_ROOT);
 }
 
+/**
+ * Pure: turn an `executionFailed` lint summary into the degradation records the
+ * review outcome carries beside its findings (Story #4839).
+ *
+ * A summary from `runScopedLint` names each failed surface; an injected or
+ * legacy summary that sets only `executionFailed` degrades to one record for
+ * the gate as a whole, so the outcome is never silent about a gate that did not
+ * run just because the summary predates the per-surface contract.
+ *
+ * @param {{ executionFailed?: boolean, degradations?: Array<{ surface: string, reason: string }> }} lintSummary
+ * @returns {Array<{ tool: string, gate: string, surface: string, reason: string }>}
+ */
+function buildLintDegradations(lintSummary) {
+  if (!lintSummary.executionFailed) return [];
+  const rows = Array.isArray(lintSummary.degradations)
+    ? lintSummary.degradations
+    : [];
+  const surfaces =
+    rows.length > 0
+      ? rows
+      : [{ surface: 'scoped-lint', reason: 'unparseable-output' }];
+  return surfaces.map((row) => ({
+    tool: 'native-review-lint',
+    gate: 'scoped-lint',
+    surface: row.surface,
+    reason: row.reason,
+  }));
+}
+
 /**
  * Build a `ReviewProvider` instance backed by the native in-process pipeline.
  *
@@ -560,12 +483,33 @@ export function createNativeProvider(deps = {}) {
     scopeLint = 'changed-only',
   } = deps;
 
+  /**
+   * Degradations recorded by the most recent `runReview`. Read through
+   * `getDegradations()` after the run, mirroring how `getPromptMessages` is
+   * feature-detected by the orchestrator — findings and degradations travel
+   * side by side, so an unexecutable tool never has to become a `Finding` to
+   * be visible (Story #4699's intent; Story #4839's fix).
+   *
+   * @type {Array<{ tool: string, gate: string, surface: string, reason: string }>}
+   */
+  let recordedDegradations = [];
+
   return {
+    /**
+     * Gate degradations from the last `runReview`. Never a `Finding`, so
+     * severity counts stay code-findings-only.
+     *
+     * @returns {Array<{ tool: string, gate: string, surface: string, reason: string }>}
+     */
+    getDegradations() {
+      return recordedDegradations;
+    },
     /**
      * @param {ReviewInput} input
      * @returns {Promise<Finding[]>}
      */
     async runReview(input) {
+      recordedDegradations = [];
       const { scope, ticketId, baseRef, headRef } = input ?? {};
       if (!baseRef || !headRef) {
         throw new TypeError(
@@ -623,8 +567,19 @@ export function createNativeProvider(deps = {}) {
         // Story #4699 — a tool that could not execute is an operational
         // degradation, not a code finding. Route it to friction telemetry
         // (best-effort) so severity counts reflect code findings only.
+        //
+        // Story #4839 — telemetry alone left the review's own verdict unable to
+        // distinguish "lint ran and found nothing" from "lint never ran", so
+        // the same degradation is also recorded on the outcome channel. It is
+        // still never a `Finding`: the friction emission below is unchanged and
+        // severity counts remain code-findings-only.
+        recordedDegradations = buildLintDegradations(lintSummary);
         logger?.warn?.(
-          '[native-review] Lint runner could not execute — recorded as friction telemetry, no finding emitted. Verify with the canonical `npm run lint` before merging.',
+          `[native-review] Lint runner could not execute (${recordedDegradations
+            .map((d) => `${d.surface}: ${d.reason}`)
+            .join(
+              '; ',
+            )}) — reported as a degraded gate on the review outcome and recorded as friction telemetry; no finding emitted. Verify with the canonical \`npm run lint\` before merging.`,
         );
         try {
           await emitToolDegradationFn({
@@ -646,9 +601,10 @@ export function createNativeProvider(deps = {}) {
 
       // Canonical ordering: critical (maintainability) first, then high
       // (lint errors), then medium (size/volume warnings), then suggestion
-      // (lint warnings / executionFailed). The renderer re-bucketizes by
-      // severity tier, so this order only matters for stability of fixture
-      // outputs.
+      // (lint warnings). An execution failure contributes to none of these
+      // tiers — it travels on the degradation channel. The renderer
+      // re-bucketizes by severity tier, so this order only matters for
+      // stability of fixture outputs.
       return [
         ...results.criticalFindings,
         ...lintFindings.filter((f) => f.severity === 'high'),

package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js

@@ -35,6 +35,7 @@
  */
 
 import { createCodexProviderForRegistry } from './codex.js';
+import { mergeChainDegradations } from './degraded-gates.js';
 import { createNativeProviderForRegistry } from './native.js';
 import { createSecurityReviewProviderForRegistry } from './security-review.js';
 import { createUltrareviewProviderForRegistry } from './ultrareview.js';
@@ -288,6 +289,15 @@ export function createChainProvider(chain, opts = {}) {
       }
       return merged;
     },
+    /**
+     * Degraded gates across the inline chain (Story #4839). Called after
+     * `runReview`.
+     *
+     * @returns {Promise<Array<object>>}
+     */
+    async getDegradations() {
+      return mergeChainDegradations(chain.inline, logger);
+    },
     /**
      * @param {ReviewInput} input
      * @returns {Promise<string[]>}

package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js

@@ -0,0 +1,300 @@
+/**
+ * review-providers/scoped-lint.js — the scoped-lint surface of the native
+ * review provider (extracted from `native.js` by Story #4839).
+ *
+ * ## Why this module exists
+ *
+ * The scoped-lint gate reported `executionFailed` — and therefore emitted zero
+ * findings while the review reported clean — on 18 of 23 Beestera/swarm-os
+ * Stories carrying friction (78%) and on 5 mandrel Stories. Measured
+ * 2026-07-29, the cause was **not** environmental and **not** a parse failure.
+ * Three defects in how the runners were invoked and reconciled produced the
+ * same symptom:
+ *
+ * 1. **The markdown runner was never resolvable.** The provider spawned
+ *    `npx --no markdownlint`, but the binary this project (and the consumer)
+ *    installs is `markdownlint-cli2` — `markdownlint-cli2` is the package and
+ *    the bin name; a bare `markdownlint` bin does not exist. `npx --no` with an
+ *    unresolvable bin exits 1 printing `could not determine executable to run`
+ *    and nothing else, so the summary parsed nothing and the gate degraded.
+ *    The parser was already written for **cli2's** `Summary: N error(s)` line,
+ *    so the invocation and the parser had never agreed. The `--ignore
+ *    node_modules` flag was likewise `markdownlint-cli` (v1) syntax, which
+ *    cli2 does not accept. Fix: resolve the runner from what is actually
+ *    installed and pass each candidate its own argument shape.
+ *
+ * 2. **One runner's failure poisoned the other's verdict.** The two runs were
+ *    folded into a *single* `parseLintOutput` call over concatenated output and
+ *    the maximum exit status. So the unresolvable markdown runner's exit 1
+ *    became the verdict for biome too: any change set containing at least one
+ *    `.md` file degraded the whole gate whenever biome itself had nothing to
+ *    report — i.e. exactly the clean case the gate exists to confirm. Fix:
+ *    classify each surface independently and merge structurally.
+ *
+ * 3. **Biome's "nothing in scope" exit was read as a failure.** `biome lint`
+ *    exits 1 with `No files were processed in the specified paths.` when every
+ *    supplied path is excluded by `biome.json` (`temp/`, `dist/`,
+ *    `.worktrees/`, anything in the VCS ignore file). That is an empty scope,
+ *    not a runner that could not execute. Fix: recognise the sentinel.
+ *
+ * ## What a degraded surface now produces
+ *
+ * `runScopedLint` still reports `executionFailed` — the friction-telemetry
+ * emission in `native.js` is deliberately unchanged (Story #4699 routed an
+ * unexecutable tool to telemetry so severity tiers reflect code findings only,
+ * and that intent stands). It additionally reports a `degradations[]` array
+ * naming **which** surface could not run and **why**, so the review outcome can
+ * say "this gate did not run" instead of silently reading clean.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/** Paths these extensions land on the biome (code) runner. */
+const CODE_EXTENSIONS = /\.(js|mjs|cjs|jsx|ts|tsx|json|jsonc)$/i;
+
+/** npx's message when the requested bin cannot be resolved. */
+const NPX_UNRESOLVABLE = /could not determine executable to run/i;
+
+/** Biome's exit-1 message when every supplied path is config-excluded. */
+const BIOME_EMPTY_SCOPE = /No files were processed in the specified paths/i;
+
+/**
+ * Markdown runners in preference order, each with the argument shape *it*
+ * accepts. `markdownlint-cli2` takes bare paths/globs and rejects `--ignore`;
+ * `markdownlint` (cli v1) takes `--ignore`. Explicit changed-file paths are
+ * passed either way, so the v1 ignore flag is belt-and-braces only.
+ */
+const MARKDOWN_RUNNERS = Object.freeze([
+  Object.freeze({ bin: 'markdownlint-cli2', extraArgs: Object.freeze([]) }),
+  Object.freeze({
+    bin: 'markdownlint',
+    extraArgs: Object.freeze(['--ignore', 'node_modules']),
+  }),
+]);
+
+/** Reason codes carried on a degradation record. */
+const DEGRADATION_REASONS = Object.freeze({
+  RUNNER_NOT_INSTALLED: 'runner-not-installed',
+  RUNNER_NOT_RESOLVABLE: 'runner-not-resolvable',
+  UNPARSEABLE_OUTPUT: 'unparseable-output',
+});
+
+/**
+ * Spawn one lint runner through `npx --no` (never install on the fly).
+ *
+ * @param {string} bin
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {{ status: number, stdout: string, stderr: string }}
+ */
+function spawnLintRunner(bin, args, cwd) {
+  const result = spawnSync('npx', ['--no', bin, ...args], {
+    cwd,
+    encoding: 'utf-8',
+    shell: process.platform === 'win32',
+  });
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+/**
+ * Pure-ish: pick the first markdown runner whose bin is actually installed
+ * under `<cwd>/node_modules/.bin`. Returns `null` when none is — an honest
+ * "this surface has no runner" that the caller reports rather than silently
+ * folding into a generic parse failure.
+ *
+ * The disk probe (rather than "spawn and see") is what makes the failure
+ * *nameable*: `npx --no <missing-bin>` yields only a generic npm error, which
+ * is precisely how the defect hid for months.
+ *
+ * Not exported: it is reachable — and asserted — through {@link runScopedLint},
+ * whose `existsFn` seam drives every resolution branch.
+ *
+ * @param {string} cwd
+ * @param {(p: string) => boolean} [existsFn]  Injected for testing.
+ * @returns {{ bin: string, extraArgs: ReadonlyArray<string> }|null}
+ */
+function resolveMarkdownRunner(cwd, existsFn = existsSync) {
+  for (const candidate of MARKDOWN_RUNNERS) {
+    const base = path.join(cwd, 'node_modules', '.bin', candidate.bin);
+    if (existsFn(base)) return candidate;
+    if (
+      process.platform === 'win32' &&
+      (existsFn(`${base}.cmd`) || existsFn(`${base}.ps1`))
+    ) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Pure: split changed paths into the file lists each lint runner consumes.
+ *
+ * @param {string[]} changedFiles
+ * @returns {{ code: string[], md: string[] }}
+ */
+export function partitionFilesForLint(changedFiles) {
+  const code = [];
+  const md = [];
+  for (const f of changedFiles) {
+    if (CODE_EXTENSIONS.test(f)) code.push(f);
+    else if (/\.md$/i.test(f)) md.push(f);
+  }
+  return { code, md };
+}
+
+/**
+ * Pure: classify **one** runner's result into a summary.
+ *
+ * Handles the reporter formats composing `npm run lint` here:
+ *   - Biome: `Found N error(s).` / `Found N warning(s).`
+ *   - markdownlint-cli2: a trailing `Summary: N error(s)` line.
+ *
+ * A non-zero exit whose output matches no known reporter format is "could not
+ * classify" → `executionFailed: true`, with `reason` naming what was actually
+ * observed. Biome's empty-scope exit is recognised separately as
+ * `emptyScope` — nothing to lint is not a broken runner.
+ *
+ * @param {{ status?: number, stdout?: string, stderr?: string }} result
+ * @returns {{ errors: number, warnings: number, parsed: boolean, executionFailed: boolean, emptyScope: boolean, reason: string|null }}
+ */
+export function parseLintOutput(result) {
+  const combined = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+
+  let errors = 0;
+  let warnings = 0;
+  let parsed = false;
+
+  for (const m of combined.matchAll(/Found\s+(\d+)\s+error/gi)) {
+    errors += Number(m[1]);
+    parsed = true;
+  }
+  for (const m of combined.matchAll(/Found\s+(\d+)\s+warning/gi)) {
+    warnings += Number(m[1]);
+    parsed = true;
+  }
+  const mdSummary = combined.match(/Summary:\s+(\d+)\s+error/i);
+  if (mdSummary) {
+    errors += Number(mdSummary[1]);
+    parsed = true;
+  }
+
+  const failedExit = !parsed && (result.status ?? 0) !== 0;
+  const emptyScope = failedExit && BIOME_EMPTY_SCOPE.test(combined);
+  const executionFailed = failedExit && !emptyScope;
+  const reason = executionFailed
+    ? NPX_UNRESOLVABLE.test(combined)
+      ? DEGRADATION_REASONS.RUNNER_NOT_RESOLVABLE
+      : DEGRADATION_REASONS.UNPARSEABLE_OUTPUT
+    : null;
+
+  return { errors, warnings, parsed, executionFailed, emptyScope, reason };
+}
+
+/**
+ * Pure: merge per-surface summaries into the gate's single summary. Counts add;
+ * `executionFailed` is the OR across surfaces; each failed surface contributes
+ * one degradation record naming itself. Merging *summaries* rather than raw
+ * output is what stops one runner's failure from becoming the other's verdict.
+ *
+ * @param {Array<{ surface: string, summary: ReturnType<typeof parseLintOutput> }>} surfaces
+ */
+function mergeSurfaceSummaries(surfaces) {
+  let errors = 0;
+  let warnings = 0;
+  let parsed = false;
+  let executionFailed = false;
+  const degradations = [];
+
+  for (const { surface, summary } of surfaces) {
+    errors += summary.errors;
+    warnings += summary.warnings;
+    if (summary.parsed) parsed = true;
+    if (summary.executionFailed) {
+      executionFailed = true;
+      degradations.push({
+        surface,
+        reason: summary.reason ?? DEGRADATION_REASONS.UNPARSEABLE_OUTPUT,
+      });
+    }
+  }
+
+  return {
+    errors,
+    warnings,
+    parsed,
+    executionFailed,
+    skipped: false,
+    mode: 'changed-only',
+    degradations,
+  };
+}
+
+/**
+ * Run lint scoped to the changed surface only.
+ *
+ * @param {string[]} changedFiles
+ * @param {string} cwd
+ * @param {typeof spawnLintRunner} [runnerFn]
+ * @param {{ existsFn?: (p: string) => boolean }} [deps]  Test seam for runner resolution.
+ * @returns {{ errors: number, warnings: number, parsed: boolean, skipped: boolean, mode: 'changed-only'|'off', executionFailed: boolean, degradations: Array<{ surface: string, reason: string }> }}
+ */
+export function runScopedLint(
+  changedFiles,
+  cwd,
+  runnerFn = spawnLintRunner,
+  deps = {},
+) {
+  const { existsFn = existsSync } = deps;
+  const { code, md } = partitionFilesForLint(changedFiles);
+  if (code.length === 0 && md.length === 0) {
+    return {
+      errors: 0,
+      warnings: 0,
+      parsed: false,
+      skipped: true,
+      mode: 'changed-only',
+      executionFailed: false,
+      degradations: [],
+    };
+  }
+
+  const surfaces = [];
+  if (code.length > 0) {
+    surfaces.push({
+      surface: 'biome',
+      summary: parseLintOutput(runnerFn('biome', ['lint', ...code], cwd)),
+    });
+  }
+  if (md.length > 0) {
+    const runner = resolveMarkdownRunner(cwd, existsFn);
+    if (runner === null) {
+      surfaces.push({
+        surface: 'markdownlint',
+        summary: {
+          errors: 0,
+          warnings: 0,
+          parsed: false,
+          executionFailed: true,
+          emptyScope: false,
+          reason: DEGRADATION_REASONS.RUNNER_NOT_INSTALLED,
+        },
+      });
+    } else {
+      surfaces.push({
+        surface: runner.bin,
+        summary: parseLintOutput(
+          runnerFn(runner.bin, [...md, ...runner.extraArgs], cwd),
+        ),
+      });
+    }
+  }
+
+  return mergeSurfaceSummaries(surfaces);
+}