mandrel 1.57.0

package/.agents/scripts/lib/feedback-loop/code-review-graduator.js

@@ -0,0 +1,207 @@
+/**
+ * code-review-graduator.js — Auto-graduate non-blocking code-review
+ * findings from the Epic's `code-review` structured comment into routed
+ * GitHub follow-up issues.
+ *
+ * Story #2555 / Epic #2547. As of Story #3845 / Epic #3823 the spawn
+ * helper, the path/idempotency probes, the `gh issue create` filer, the
+ * toggle reader, and the route → probe → file walk all live in the
+ * shared [`graduator-core.js`](./graduator-core.js). This module is the
+ * thin code-review-specific shell: it owns the code-review finding parser
+ * (the 🟢→low severity mapping, no lens), the code-review label / title /
+ * body shape, and the code-review idempotency marker. Behaviour is
+ * identical to the pre-consolidation graduator.
+ *
+ *   - Read the `code-review` structured comment off the Epic ticket via
+ *     the injected provider (findStructuredComment surface).
+ *   - For each non-blocking finding (severity high/medium/low — i.e.
+ *     anything that is NOT a 🔴 Critical Blocker), check that the cited
+ *     file still exists in the merged tree (`git cat-file -e <ref>:<path>`)
+ *     via the injected spawn seam.
+ *   - Route by source classification (framework vs consumer) using
+ *     `classifyPathSource` (S1 helper). When the routed repo differs
+ *     from the current repo, record under `skipped: 'cross-repo-deferred'`
+ *     and log the would-be `gh issue create` invocation — do NOT actually
+ *     shell out against a different repo.
+ *   - File a follow-up issue with `gh issue create --repo <routed-repo>`
+ *     carrying a `code-review::<severity>` label plus the matching
+ *     `meta::<framework-gap|consumer-improvement>` label.
+ *   - Embed an idempotency marker in each body:
+ *       <!-- code-review-followup: epic-<id>-finding-<idx> -->
+ *     Before filing, probe via `gh search issues "<marker>" --repo …`
+ *     and skip findings whose marker is already present in any issue.
+ *   - Short-circuit when `config.delivery.feedbackLoop.codeReviewAutoFile`
+ *     is `false` — return `{ filed: [], skipped: [{reason:
+ *     'toggle-disabled'}], errors: [] }`.
+ *   - NEVER throw. Every failure path (missing comment, parse failure,
+ *     gh/git spawn error, non-zero exit) is captured in `errors[]`.
+ *
+ * Tests inject `provider`, `classifier`, and `spawnImpl` to drive every
+ * branch deterministically.
+ */
+
+import {
+  graduate,
+  makeIsAutoFileEnabled,
+  probePathExists,
+} from './graduator-core.js';
+
+/**
+ * Resolve the toggle from the resolved agentrc config. Defaults to `true`
+ * — the feature is opt-out, not opt-in.
+ *
+ * @param {object|undefined|null} config
+ * @returns {boolean}
+ */
+export const isAutoFileEnabled = makeIsAutoFileEnabled('codeReviewAutoFile');
+
+// Re-export the shared path probe so existing importers keep working.
+export { probePathExists };
+
+/**
+ * Severity → label mapping. Only non-blocking severities have a route;
+ * 🔴 Critical Blocker is explicitly filtered out upstream.
+ */
+const SEVERITY_LABEL = Object.freeze({
+  high: 'code-review::high',
+  medium: 'code-review::medium',
+  low: 'code-review::low',
+});
+
+/**
+ * Map a classification source to its meta routing label.
+ *
+ * @param {string} source
+ * @returns {string}
+ */
+function metaSourceLabel(source) {
+  return source === 'framework'
+    ? 'meta::framework-gap'
+    : 'meta::consumer-improvement';
+}
+
+/**
+ * Compile a marker for a given epicId / finding index. The marker is an
+ * HTML comment so it survives GitHub markdown rendering without leaking
+ * into the visible body — but it's still indexable via `gh search`.
+ *
+ * @param {number} epicId
+ * @param {number} index — zero-based finding ordinal within the Epic.
+ * @returns {string}
+ */
+export function buildIdempotencyMarker(epicId, index) {
+  return `<!-- code-review-followup: epic-${epicId}-finding-${index} -->`;
+}
+
+/**
+ * Parse the rendered code-review markdown into a list of findings. Each
+ * finding has `{ severity, path, summary, index }`. Pure. Exported so
+ * the parser can be unit-tested in isolation.
+ *
+ * The structured `code-review` comment emits findings as bullet lines under the
+ * "🚨 Critical Findings" and "🟡 Warnings" sections. Each line begins
+ * with a severity emoji and embeds the cited path inside backticks. We
+ * filter 🔴 (Critical Blocker — blocking) out; 🟠/🟡/🟢 are non-blocking
+ * and graduate to follow-up issues.
+ *
+ * @param {string} body
+ * @returns {Array<{ severity: 'high'|'medium'|'low', path: string, summary: string, index: number }>}
+ */
+export function parseFindings(body) {
+  if (typeof body !== 'string' || body.length === 0) return [];
+  const findings = [];
+  const lines = body.split(/\r?\n/);
+  let idx = 0;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    let severity = null;
+    if (trimmed.startsWith('🟠')) severity = 'high';
+    else if (trimmed.startsWith('🟡')) severity = 'medium';
+    else if (trimmed.startsWith('🟢')) severity = 'low';
+    else continue;
+    // Path is the first backticked token on the line.
+    const pathMatch = trimmed.match(/`([^`]+)`/);
+    if (!pathMatch) continue;
+    const path = pathMatch[1];
+    // Summary is the line itself, stripped of the leading emoji bullet.
+    findings.push({
+      severity,
+      path,
+      summary: trimmed,
+      index: idx,
+    });
+    idx += 1;
+  }
+  return findings;
+}
+
+/**
+ * Auto-graduate non-blocking code-review findings into routed follow-up
+ * issues. Never throws. Thin wrapper around the shared `graduate()` walk
+ * with the code-review-specific behaviour bundle.
+ *
+ * @param {object} opts
+ * @param {number} opts.epicId
+ * @param {object} opts.provider — ticketing provider exposing
+ *   `getTicketComments(ticketId)`.
+ * @param {object} [opts.config] — resolved agentrc.
+ * @param {{owner: string, repo: string}} opts.currentRepo — the repo the
+ *   listener is running inside; used for the cross-repo guard.
+ * @param {{owner: string, repo: string}} [opts.frameworkRepo] — where
+ *   framework-tagged findings get routed. Defaults to
+ *   `currentRepo` when this is the framework repo, otherwise typically
+ *   `{ owner: 'dsj1984', repo: 'mandrel' }`.
+ * @param {string} [opts.gitRef='HEAD'] — ref against which to probe path
+ *   existence.
+ * @param {Function} [opts.classifier=classifyPathSource] — S1 helper.
+ * @param {string} [opts.ghPath='gh']
+ * @param {Function} [opts.spawnImpl]
+ * @param {string} [opts.cwd]
+ * @param {{info?: Function, warn?: Function, debug?: Function}} [opts.logger]
+ * @returns {Promise<{
+ *   filed: Array<{ index: number, severity: string, path: string, source: string, repo: string, url: string|null }>,
+ *   skipped: Array<{ index?: number, reason: string, path?: string, severity?: string }>,
+ *   errors: string[],
+ * }>}
+ */
+export async function graduateFindings(opts = {}) {
+  return graduate({
+    ...opts,
+    spec: {
+      fnName: 'graduateFindings',
+      isAutoFileEnabled,
+      commentMarker: '<!-- structured-comment: code-review -->',
+      noCommentReason: 'no-code-review-comment',
+      parseFindings,
+      buildIdempotencyMarker,
+      buildCrossRepoLog: ({ finding, routedRepo, source }) => {
+        const metaLabel = metaSourceLabel(source);
+        return `[code-review-graduator] cross-repo skip (would file in ${routedRepo.owner}/${routedRepo.repo}): gh issue create --repo ${routedRepo.owner}/${routedRepo.repo} --title "Code review follow-up: ${finding.path}" --label "${metaLabel},${SEVERITY_LABEL[finding.severity]}"`;
+      },
+      buildFollowUp: ({ finding, source, epicId, idMarker }) => {
+        const metaLabel = metaSourceLabel(source);
+        const title = `Code review follow-up: ${finding.path}`;
+        const body = [
+          idMarker,
+          '',
+          `Auto-filed from the Epic #${epicId} code-review pass.`,
+          '',
+          `**Severity**: ${finding.severity}`,
+          `**Source**: ${source}`,
+          `**Path**: \`${finding.path}\``,
+          '',
+          '### Finding',
+          '',
+          finding.summary,
+          '',
+          `_See Epic #${epicId} for the full code-review report._`,
+        ].join('\n');
+        const labels = [metaLabel, SEVERITY_LABEL[finding.severity]];
+        return { title, body, labels };
+      },
+    },
+  });
+}
+
+export default graduateFindings;

package/.agents/scripts/lib/feedback-loop/graduator-core.js

@@ -0,0 +1,421 @@
+/**
+ * graduator-core.js — shared mechanism for the feedback-loop graduators.
+ *
+ * Story #3845 / Epic #3823. The audit-results graduator
+ * (`audit-results-graduator.js`) and the code-review graduator
+ * (`code-review-graduator.js`) duplicated ~90% of their mechanism: a
+ * `spawn`-based child runner, the `git cat-file` path probe, the
+ * `gh search issues` idempotency probe, the `gh issue create` filer, the
+ * `isAutoFileEnabled` toggle reader, and the route → probe → file
+ * envelope walk. This module folds all of that into one place so the two
+ * graduators become thin shells that inject the bits that genuinely
+ * differ (the finding parser and the body/title/label builders).
+ *
+ * The third `runGh` spawn copy in `prior-feedback-fetcher.js` is also
+ * collapsed onto the single `runChild` helper here.
+ *
+ * Behaviour-preserving: the parametrized `graduate()` walk reproduces the
+ * exact envelope, skip reasons, label sets, titles, and bodies the two
+ * standalone graduators produced before consolidation. The only injected
+ * seams are the parser (`parseFindings`) and the per-finding
+ * `bodyBuilder`; everything mechanical is shared.
+ */
+
+import { spawn as defaultSpawn } from 'node:child_process';
+
+import { classifyPathSource as defaultClassifier } from '../observability/source-classifier.js';
+
+/**
+ * Spawn a child process and resolve to `{ code, stdout, stderr, spawnError }`.
+ * Never throws — spawn-time errors are captured as `spawnError`.
+ *
+ * This is the single spawn helper for the feedback-loop modules. Both
+ * graduators and `prior-feedback-fetcher.js` route their child-process
+ * reads through it so the error envelope stays consistent. `stdio` is
+ * always `['ignore', 'pipe', 'pipe']`; callers that need extra spawn
+ * options (e.g. omitting `cwd`) pass `undefined` and the option is
+ * dropped by the child_process layer.
+ *
+ * @param {object} opts
+ * @param {string} opts.cmd — binary to spawn (e.g. "git", "gh")
+ * @param {string[]} opts.args — positional + flag arguments
+ * @param {Function} [opts.spawnImpl] — test seam; defaults to node:child_process spawn
+ * @param {string} [opts.cwd] — working directory for the child
+ * @returns {Promise<{ code: number|null, stdout: string, stderr: string, spawnError: Error|null }>}
+ */
+export function runChild({ cmd, args, spawnImpl = defaultSpawn, cwd }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnImpl(cmd, args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd,
+      });
+    } catch (err) {
+      resolve({ code: null, stdout: '', stderr: '', spawnError: err });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let spawnError = null;
+    child.stdout?.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('error', (err) => {
+      spawnError = err;
+    });
+    child.on('close', (code) => {
+      resolve({ code, stdout, stderr, spawnError });
+    });
+  });
+}
+
+/**
+ * Build an `isAutoFileEnabled(config)` reader bound to a specific
+ * `delivery.feedbackLoop.<key>` toggle. The feature is opt-out: the
+ * toggle defaults to `true` and only an explicit `false` disables it.
+ *
+ * @param {string} toggleKey — key under `config.delivery.feedbackLoop`
+ *   (e.g. "auditResultsAutoFile", "codeReviewAutoFile")
+ * @returns {(config: object|undefined|null) => boolean}
+ */
+export function makeIsAutoFileEnabled(toggleKey) {
+  return function isAutoFileEnabled(config) {
+    const value = config?.delivery?.feedbackLoop?.[toggleKey];
+    if (value === false) return false;
+    return true;
+  };
+}
+
+/**
+ * Probe whether the cited path exists in the merged tree at the given
+ * git ref via `git cat-file -e <ref>:<path>`. Resolves `true` when the
+ * file is present, `false` otherwise — a spawn failure degrades to
+ * `false` (we cannot prove existence, so the finding skips with
+ * `file-removed`).
+ *
+ * @param {object} opts
+ * @param {string} opts.ref
+ * @param {string} opts.path
+ * @param {Function} [opts.spawnImpl]
+ * @param {string} [opts.cwd]
+ */
+export async function probePathExists({ ref, path, spawnImpl, cwd }) {
+  const res = await runChild({
+    cmd: 'git',
+    args: ['cat-file', '-e', `${ref}:${path}`],
+    spawnImpl,
+    cwd,
+  });
+  return res.code === 0;
+}
+
+/**
+ * Probe whether a follow-up issue carrying the given idempotency marker
+ * already exists in the routed repo. Uses `gh search issues` so we hit
+ * the body field directly. Returns `true` when at least one match is
+ * present; degrades to `false` on any spawn/parse error (better to risk
+ * a duplicate than swallow the finding entirely).
+ */
+export async function probeMarkerExists({
+  marker,
+  owner,
+  repo,
+  ghPath,
+  spawnImpl,
+  cwd,
+}) {
+  const args = [
+    'search',
+    'issues',
+    marker,
+    '--repo',
+    `${owner}/${repo}`,
+    '--json',
+    'number',
+    '--limit',
+    '1',
+  ];
+  const res = await runChild({ cmd: ghPath, args, spawnImpl, cwd });
+  if (res.spawnError || (typeof res.code === 'number' && res.code !== 0)) {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(res.stdout || '[]');
+    return Array.isArray(parsed) && parsed.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * File a new follow-up issue via `gh issue create` and resolve to
+ * `{ url, error }`. On success `url` is the trimmed stdout and `error` is
+ * null; on failure `url` is null and `error` carries a human-readable
+ * message.
+ */
+export async function createFollowUpIssue({
+  owner,
+  repo,
+  title,
+  body,
+  labels,
+  ghPath,
+  spawnImpl,
+  cwd,
+}) {
+  const args = [
+    'issue',
+    'create',
+    '--repo',
+    `${owner}/${repo}`,
+    '--title',
+    title,
+    '--body',
+    body,
+  ];
+  for (const label of labels) {
+    args.push('--label', label);
+  }
+  const res = await runChild({ cmd: ghPath, args, spawnImpl, cwd });
+  if (res.spawnError || (typeof res.code === 'number' && res.code !== 0)) {
+    return {
+      url: null,
+      error: res.spawnError
+        ? `gh issue create spawn failed: ${res.spawnError.message}`
+        : `gh issue create exited ${res.code}: ${(res.stderr || '').trim()}`,
+    };
+  }
+  const url = (res.stdout || '').trim();
+  return { url, error: null };
+}
+
+/**
+ * Parametrized graduator walk. Reads the Epic's structured comment via
+ * the injected provider, parses non-blocking findings with the injected
+ * `parseFindings`, then for each finding runs the shared route → path
+ * probe → idempotency probe → file sequence. Never throws — every
+ * failure path is captured in `errors[]`.
+ *
+ * The per-graduator variation lives entirely in the injected callbacks:
+ *
+ *   - `parseFindings(body)` — turns the rendered comment into findings.
+ *     Each finding MUST carry `{ severity, path, summary, index }` and
+ *     MAY carry additional fields (e.g. `lens`) that the builder uses.
+ *   - `buildIdempotencyMarker(epicId, index)` — the HTML-comment marker
+ *     embedded in (and searched for in) follow-up bodies.
+ *   - `buildFollowUp({ finding, source, epicId })` — returns
+ *     `{ title, body, labels }` for the issue to file.
+ *   - `buildCrossRepoLog({ finding, routedRepo })` — returns the
+ *     human-readable would-be-command string logged on a cross-repo skip.
+ *   - `decorateRecord(record, finding)` — copies finding-specific fields
+ *     (e.g. `lens`) onto a `skipped`/`filed` record before it is pushed.
+ *
+ * @param {object} opts
+ * @param {number} opts.epicId
+ * @param {object} opts.provider — exposes `getTicketComments(ticketId)`
+ * @param {object} [opts.config]
+ * @param {{owner: string, repo: string}} opts.currentRepo
+ * @param {{owner: string, repo: string}} [opts.frameworkRepo]
+ * @param {string} [opts.gitRef='HEAD']
+ * @param {Function} [opts.classifier=classifyPathSource]
+ * @param {string} [opts.ghPath='gh']
+ * @param {Function} [opts.spawnImpl]
+ * @param {string} [opts.cwd]
+ * @param {{info?: Function, warn?: Function, debug?: Function}} [opts.logger]
+ * @param {object} opts.spec — the per-graduator behaviour bundle
+ * @param {string} opts.spec.fnName — name used in error-message prefixes
+ * @param {(config: object|undefined|null) => boolean} opts.spec.isAutoFileEnabled
+ * @param {string} opts.spec.commentMarker — structured-comment marker to match
+ * @param {string} opts.spec.noCommentReason — skip reason when absent
+ * @param {Function} opts.spec.parseFindings
+ * @param {(epicId: number, index: number) => string} opts.spec.buildIdempotencyMarker
+ * @param {Function} opts.spec.buildFollowUp
+ * @param {Function} opts.spec.buildCrossRepoLog
+ * @param {(record: object, finding: object) => object} [opts.spec.decorateRecord]
+ * @returns {Promise<{ filed: object[], skipped: object[], errors: string[] }>}
+ */
+export async function graduate({
+  epicId,
+  provider,
+  config,
+  currentRepo,
+  frameworkRepo,
+  gitRef = 'HEAD',
+  classifier = defaultClassifier,
+  ghPath = 'gh',
+  spawnImpl,
+  cwd,
+  logger,
+  spec,
+}) {
+  const envelope = { filed: [], skipped: [], errors: [] };
+  const decorate =
+    typeof spec.decorateRecord === 'function'
+      ? spec.decorateRecord
+      : (record) => record;
+
+  if (!spec.isAutoFileEnabled(config)) {
+    envelope.skipped.push({ reason: 'toggle-disabled' });
+    return envelope;
+  }
+
+  if (!Number.isInteger(epicId) || epicId < 1) {
+    envelope.errors.push(`${spec.fnName}: missing or invalid epicId`);
+    return envelope;
+  }
+  if (!provider || typeof provider.getTicketComments !== 'function') {
+    envelope.errors.push(`${spec.fnName}: provider lacks getTicketComments`);
+    return envelope;
+  }
+  if (
+    !currentRepo ||
+    typeof currentRepo.owner !== 'string' ||
+    typeof currentRepo.repo !== 'string'
+  ) {
+    envelope.errors.push(`${spec.fnName}: missing currentRepo {owner,repo}`);
+    return envelope;
+  }
+
+  // 1. Read the structured comment off the Epic.
+  let comments;
+  try {
+    comments = await provider.getTicketComments(epicId);
+  } catch (err) {
+    envelope.errors.push(
+      `getTicketComments failed for epic #${epicId}: ${err?.message ?? err}`,
+    );
+    return envelope;
+  }
+  if (!Array.isArray(comments) || comments.length === 0) {
+    envelope.skipped.push({ reason: spec.noCommentReason });
+    return envelope;
+  }
+  const matched = comments.filter(
+    (c) => typeof c?.body === 'string' && c.body.includes(spec.commentMarker),
+  );
+  if (matched.length === 0) {
+    envelope.skipped.push({ reason: spec.noCommentReason });
+    return envelope;
+  }
+  const sourceComment = matched[matched.length - 1];
+
+  // 2. Parse findings.
+  const findings = spec.parseFindings(sourceComment.body);
+  if (findings.length === 0) {
+    envelope.skipped.push({ reason: 'no-non-blocking-findings' });
+    return envelope;
+  }
+
+  // 3. For each finding, route → idempotency probe → file.
+  for (const finding of findings) {
+    const exists = await probePathExists({
+      ref: gitRef,
+      path: finding.path,
+      spawnImpl,
+      cwd,
+    });
+    if (!exists) {
+      envelope.skipped.push(
+        decorate(
+          {
+            index: finding.index,
+            reason: 'file-removed',
+            path: finding.path,
+            severity: finding.severity,
+          },
+          finding,
+        ),
+      );
+      continue;
+    }
+
+    const source = classifier(finding.path, null);
+    const routedRepo =
+      source === 'framework' && frameworkRepo ? frameworkRepo : currentRepo;
+
+    const isCrossRepo =
+      routedRepo.owner !== currentRepo.owner ||
+      routedRepo.repo !== currentRepo.repo;
+    if (isCrossRepo) {
+      logger?.info?.(spec.buildCrossRepoLog({ finding, routedRepo, source }));
+      envelope.skipped.push(
+        decorate(
+          {
+            index: finding.index,
+            reason: 'cross-repo-deferred',
+            path: finding.path,
+            severity: finding.severity,
+          },
+          finding,
+        ),
+      );
+      continue;
+    }
+
+    const idMarker = spec.buildIdempotencyMarker(epicId, finding.index);
+    const alreadyFiled = await probeMarkerExists({
+      marker: idMarker,
+      owner: routedRepo.owner,
+      repo: routedRepo.repo,
+      ghPath,
+      spawnImpl,
+      cwd,
+    });
+    if (alreadyFiled) {
+      envelope.skipped.push(
+        decorate(
+          {
+            index: finding.index,
+            reason: 'already-filed',
+            path: finding.path,
+            severity: finding.severity,
+          },
+          finding,
+        ),
+      );
+      continue;
+    }
+
+    const { title, body, labels } = spec.buildFollowUp({
+      finding,
+      source,
+      epicId,
+      idMarker,
+    });
+    const created = await createFollowUpIssue({
+      owner: routedRepo.owner,
+      repo: routedRepo.repo,
+      title,
+      body,
+      labels,
+      ghPath,
+      spawnImpl,
+      cwd,
+    });
+    if (created.error) {
+      envelope.errors.push(
+        `finding ${finding.index} (${finding.path}): ${created.error}`,
+      );
+      continue;
+    }
+    envelope.filed.push(
+      decorate(
+        {
+          index: finding.index,
+          severity: finding.severity,
+          path: finding.path,
+          source,
+          repo: `${routedRepo.owner}/${routedRepo.repo}`,
+          url: created.url,
+        },
+        finding,
+      ),
+    );
+  }
+
+  return envelope;
+}