mandrel 2.20.0 → 2.22.0

package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js

@@ -0,0 +1,222 @@
+/**
+ * review-providers/degraded-gates.js — the review's "a gate did not run"
+ * channel (Story #4839).
+ *
+ * ## The defect this closes
+ *
+ * Story #4699 correctly decided that a tool which **could not execute** is an
+ * operational degradation, not a code finding: it is routed to friction
+ * telemetry so severity tiers keep reflecting code findings only. What #4699
+ * did not add was any *other* channel, so the review's own verdict became
+ * unable to distinguish "lint ran and found nothing" from "lint never ran" —
+ * both rendered `✅ No findings` with an all-zero severity tally, and the close
+ * pipeline read the second as the first. A gate that reports success when it
+ * did not run is worse than no gate, because it is trusted.
+ *
+ * This module is that missing channel. A degradation travels **beside** the
+ * `Finding[]`, never inside it:
+ *
+ *   - it never becomes a `Finding`, so `countBySeverity` is untouched and no
+ *     execution failure can appear as a critical / high / medium (or even a
+ *     suggestion) — #4699's intent survives intact;
+ *   - it is rendered as its own section in the structured comment, and it
+ *     suppresses the false `✅ No findings` claim;
+ *   - it is carried on the `runCodeReview` envelope as `degraded` /
+ *     `degradations[]`, so the close pipeline sees it too.
+ *
+ * ## Report, not block — and why
+ *
+ * A degraded gate is reported loudly and does **not** halt the close. The close
+ * pipeline already runs the canonical `npm run lint` as a hard
+ * close-validation gate *before* the review phase; the review's scoped lint is
+ * a second, narrower read of the same surface. Failing a merge because a
+ * *secondary* read of an already-gated surface could not start would block
+ * delivery on an operational condition the hard gate has already covered. What
+ * was actually broken was the silence, so the fix is to make the silence
+ * impossible: every surface that reads the review outcome now states the
+ * degradation explicitly. Escalating to a block is a one-line change here if
+ * the operator posture ever needs it.
+ */
+
+/**
+ * @typedef {object} GateDegradation
+ * @property {string} tool     Emitter (e.g. `native-review-lint`).
+ * @property {string} gate     Gate that degraded (e.g. `scoped-lint`).
+ * @property {string} surface  Sub-surface that could not run (e.g. `markdownlint`).
+ * @property {string} reason   Machine-readable reason code.
+ */
+
+/**
+ * Pure: keep only well-formed degradation records. A misbehaving provider must
+ * not be able to corrupt the rendered comment or the envelope.
+ *
+ * @param {unknown} input
+ * @returns {GateDegradation[]}
+ */
+export function normalizeDegradations(input) {
+  if (!Array.isArray(input)) return [];
+  const out = [];
+  for (const d of input) {
+    if (!d || typeof d !== 'object') continue;
+    const surface = typeof d.surface === 'string' ? d.surface : null;
+    const reason = typeof d.reason === 'string' ? d.reason : null;
+    if (surface === null || reason === null) continue;
+    out.push({
+      tool: typeof d.tool === 'string' ? d.tool : 'unknown',
+      gate: typeof d.gate === 'string' ? d.gate : 'unknown',
+      surface,
+      reason,
+    });
+  }
+  return out;
+}
+
+/**
+ * Feature-detect a provider's degradation channel, mirroring how
+ * `getPromptMessages` is feature-detected. Providers predating this contract
+ * carry no `getDegradations`, so the empty array keeps their output byte-stable;
+ * a throw degrades to empty (observability must never fail a review).
+ *
+ * MUST be called **after** `runReview` — a provider records its degradations
+ * during the run.
+ *
+ * @param {{ getDegradations?: Function }} reviewProvider
+ * @param {{ warn?: Function }} [logger]
+ * @returns {Promise<GateDegradation[]>}
+ */
+export async function collectProviderDegradations(reviewProvider, logger) {
+  if (typeof reviewProvider?.getDegradations !== 'function') return [];
+  try {
+    return normalizeDegradations(await reviewProvider.getDegradations());
+  } catch (err) {
+    logger?.warn?.(
+      `[code-review] getDegradations threw; treating as none. ${
+        err?.message ?? err
+      }`,
+    );
+    return [];
+  }
+}
+
+/**
+ * Pure: one-line operator-facing summary of the degraded gates, for progress
+ * output and comment tallies. Empty input renders `none` so the field is always
+ * present — a missing degradation line must never be read as "no degradation".
+ *
+ * @param {ReadonlyArray<GateDegradation>} degradations
+ * @returns {string}
+ */
+export function summarizeDegradations(degradations) {
+  const rows = normalizeDegradations(degradations);
+  if (rows.length === 0) return 'none';
+  return rows.map((d) => `${d.gate}/${d.surface} (${d.reason})`).join(', ');
+}
+
+/**
+ * Pure: the `{ degraded, degradations }` pair every outcome envelope carries, so
+ * a caller adds the channel by spreading one helper rather than restating the
+ * derivation (and cannot ship `degradations` without `degraded`).
+ *
+ * @param {unknown} degradations
+ * @returns {{ degraded: boolean, degradations: GateDegradation[] }}
+ */
+export function degradationEnvelope(degradations) {
+  const rows = normalizeDegradations(degradations);
+  return { degraded: rows.length > 0, degradations: rows };
+}
+
+/**
+ * Merge the degraded-gate records of every inline chain entry that carries the
+ * channel. A provider predating the contract contributes nothing; a throw is
+ * logged and skipped, because a chain must never lose a "this gate did not run"
+ * signal *or* fail a review over reporting one.
+ *
+ * @param {ReadonlyArray<{ name: string, provider: { getDegradations?: Function } }>} entries
+ * @param {{ warn?: Function }} [logger]
+ * @returns {Promise<GateDegradation[]>}
+ */
+export async function mergeChainDegradations(entries, logger) {
+  const merged = [];
+  for (const entry of entries) {
+    if (typeof entry.provider?.getDegradations !== 'function') continue;
+    try {
+      merged.push(
+        ...normalizeDegradations(await entry.provider.getDegradations()),
+      );
+    } catch (err) {
+      logger?.warn?.(
+        `[code-review] Inline provider "${entry.name}" getDegradations threw; skipping. ${
+          err?.message ?? err
+        }`,
+      );
+    }
+  }
+  return merged;
+}
+
+/**
+ * Pure: the header field naming how many gates did not run. Empty when the
+ * review was healthy, so a healthy body stays byte-identical to pre-#4839.
+ *
+ * @param {ReadonlyArray<GateDegradation>} degraded  Already normalized.
+ * @returns {string[]}
+ */
+export function renderDegradedHeaderLines(degraded) {
+  if (degraded.length === 0) return [];
+  return [`**Degraded gates**: ${degraded.length} (did not run)`];
+}
+
+/**
+ * Pure: the "nothing surfaced" block. This is the exact sentence the defect
+ * turned into a lie — with a degraded gate present, an all-zero tally is not a
+ * clean verdict and must not read like one.
+ *
+ * @param {ReadonlyArray<GateDegradation>} degraded  Already normalized.
+ * @returns {string[]}
+ */
+export function renderNoFindingsBlock(degraded) {
+  if (degraded.length === 0) {
+    return [
+      '### ✅ No findings',
+      '',
+      'No issues surfaced by the review provider.',
+    ];
+  }
+  return [
+    `### ⚠️ No findings — ${degraded.length} gate(s) did not run`,
+    '',
+    'The gates that ran surfaced no issues. This review does **not** vouch ' +
+      'for the degraded surface(s) listed above.',
+  ];
+}
+
+/**
+ * Pure: render the "Degraded Gates" section of the structured comment. Returns
+ * an empty array when nothing degraded, so a healthy review's body stays
+ * byte-identical to the pre-#4839 output.
+ *
+ * @param {ReadonlyArray<GateDegradation>} degradations
+ * @returns {string[]} markdown lines
+ */
+export function renderDegradedGatesSection(degradations) {
+  const rows = normalizeDegradations(degradations);
+  if (rows.length === 0) return [];
+  const lines = [
+    `### ⚠️ Degraded Gates (${rows.length})`,
+    '',
+    'The following review gate(s) **did not run**. Their surface is',
+    'unreviewed — an all-zero finding tally below does not vouch for it.',
+    '',
+  ];
+  for (const d of rows) {
+    lines.push(
+      `- \`${d.gate}\` → \`${d.surface}\` could not execute — ${d.reason} (emitter: \`${d.tool}\`).`,
+    );
+  }
+  lines.push('');
+  lines.push(
+    'Verify with the canonical `npm run lint` before trusting this review.',
+  );
+  lines.push('');
+  return lines;
+}

package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js

@@ -15,6 +15,13 @@
  * @typedef {import('./types.js').Severity} Severity
  */
 
+import {
+  normalizeDegradations,
+  renderDegradedGatesSection,
+  renderDegradedHeaderLines,
+  renderNoFindingsBlock,
+} from './degraded-gates.js';
+
 /**
  * Canonical severity ordering. The render output always lists the
  * severity-tier counts in this order and emits the per-finding sections
@@ -115,6 +122,12 @@ export function renderManualPromptsSection(messages) {
  * manual-prompt provider output; rendered as a trailing section when
  * non-empty.
  *
+ * Story #4839 — an optional `degradations` field names review gates that could
+ * not execute. They are **not** findings and never enter `countBySeverity`; they
+ * render as their own section and suppress the unqualified "no findings" claim,
+ * because a review that could not run a gate has not established that the
+ * gate's surface is clean.
+ *
  * @param {{
  *   ticketId: number,
  *   baseRef: string,
@@ -122,6 +135,7 @@ export function renderManualPromptsSection(messages) {
  *   findings: ReadonlyArray<Finding>,
  *   provider?: string,
  *   promptMessages?: ReadonlyArray<string>,
+ *   degradations?: ReadonlyArray<object>,
  * }} input
  * @returns {string}
  */
@@ -131,6 +145,7 @@ export function renderFindings(input) {
   const counts = countBySeverity(findings);
   const totalKnown =
     counts.critical + counts.high + counts.medium + counts.suggestion;
+  const degraded = normalizeDegradations(input.degradations);
 
   const providerLine = provider
     ? `**Provider**: \`${provider}\``
@@ -142,6 +157,7 @@ export function renderFindings(input) {
     `**Comparison**: \`${baseRef}\` … \`${headRef}\``,
     providerLine,
     `**Findings**: ${totalKnown}`,
+    ...renderDegradedHeaderLines(degraded),
     '',
     '### 📦 Severity Tier Counts',
     '',
@@ -150,12 +166,11 @@ export function renderFindings(input) {
       return `- ${meta.emoji} ${meta.label}: ${counts[sev]}`;
     }),
     '',
+    ...renderDegradedGatesSection(degraded),
   ];
 
   if (totalKnown === 0) {
-    lines.push('### ✅ No findings');
-    lines.push('');
-    lines.push('No issues surfaced by the review provider.');
+    lines.push(...renderNoFindingsBlock(degraded));
   } else {
     for (const sev of SEVERITY_ORDER) {
       const tierFindings = findings.filter((f) => f && f.severity === sev);

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[]>}