mandrel 1.62.0 → 1.63.0

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

@@ -238,183 +238,217 @@ export async function createFollowUpIssue({
  * @param {(record: object, finding: object) => object} [opts.spec.decorateRecord]
  * @returns {Promise<{ filed: object[], skipped: object[], errors: string[] }>}
  */
-export async function graduate({
+/**
+ * Validate the `graduate` preconditions (toggle, epicId, provider shape,
+ * currentRepo shape). Returns `null` when all preconditions pass, or a
+ * `{ skipped?, errors? }` partial-envelope the caller short-circuits on.
+ * Story #4075 — extracted from `graduate` so the orchestrating body holds
+ * no guard-chain branching.
+ */
+function checkGraduatePreconditions({
   epicId,
   provider,
-  config,
   currentRepo,
-  frameworkRepo,
-  gitRef = 'HEAD',
-  classifier = defaultClassifier,
-  ghPath = 'gh',
-  spawnImpl,
-  cwd,
-  logger,
+  config,
   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;
+    return { skipped: [{ reason: 'toggle-disabled' }] };
   }
-
   if (!Number.isInteger(epicId) || epicId < 1) {
-    envelope.errors.push(`${spec.fnName}: missing or invalid epicId`);
-    return envelope;
+    return { errors: [`${spec.fnName}: missing or invalid epicId`] };
   }
   if (!provider || typeof provider.getTicketComments !== 'function') {
-    envelope.errors.push(`${spec.fnName}: provider lacks getTicketComments`);
-    return envelope;
+    return { errors: [`${spec.fnName}: provider lacks getTicketComments`] };
   }
   if (
     !currentRepo ||
     typeof currentRepo.owner !== 'string' ||
     typeof currentRepo.repo !== 'string'
   ) {
-    envelope.errors.push(`${spec.fnName}: missing currentRepo {owner,repo}`);
-    return envelope;
+    return { errors: [`${spec.fnName}: missing currentRepo {owner,repo}`] };
   }
+  return null;
+}
 
-  // 1. Read the structured comment off the Epic.
+/**
+ * Read the source structured comment off the Epic and parse its findings.
+ * Returns `{ findings }` on success, or `{ skipped?, errors? }` for the
+ * no-comment / parse-empty / fetch-error short-circuits. Story #4075 —
+ * extracted from `graduate`.
+ */
+async function loadGraduateFindings({ epicId, provider, spec }) {
   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;
+    return {
+      errors: [
+        `getTicketComments failed for epic #${epicId}: ${err?.message ?? err}`,
+      ],
+    };
   }
-  const matched = comments.filter(
+  const matched = (Array.isArray(comments) ? comments : []).filter(
     (c) => typeof c?.body === 'string' && c.body.includes(spec.commentMarker),
   );
   if (matched.length === 0) {
-    envelope.skipped.push({ reason: spec.noCommentReason });
-    return envelope;
+    return { skipped: [{ reason: spec.noCommentReason }] };
   }
-  const sourceComment = matched[matched.length - 1];
-
-  // 2. Parse findings.
-  const findings = spec.parseFindings(sourceComment.body);
+  const findings = spec.parseFindings(matched[matched.length - 1].body);
   if (findings.length === 0) {
-    envelope.skipped.push({ reason: 'no-non-blocking-findings' });
-    return envelope;
+    return { skipped: [{ reason: 'no-non-blocking-findings' }] };
   }
+  return { findings };
+}
 
-  // 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;
-    }
+/**
+ * Route a single finding (path-exists probe → repo routing → idempotency
+ * probe → file) and fold the outcome into the running envelope. Story #4075
+ * — extracted from `graduate`'s per-finding loop body.
+ */
+async function processGraduateFinding({
+  finding,
+  envelope,
+  decorate,
+  epicId,
+  currentRepo,
+  frameworkRepo,
+  classifier,
+  gitRef,
+  ghPath,
+  spawnImpl,
+  cwd,
+  logger,
+  spec,
+}) {
+  const skip = (reason) =>
+    envelope.skipped.push(
+      decorate(
+        {
+          index: finding.index,
+          reason,
+          path: finding.path,
+          severity: finding.severity,
+        },
+        finding,
+      ),
+    );
 
-    const source = classifier(finding.path, null);
-    const routedRepo =
-      source === 'framework' && frameworkRepo ? frameworkRepo : currentRepo;
+  const exists = await probePathExists({
+    ref: gitRef,
+    path: finding.path,
+    spawnImpl,
+    cwd,
+  });
+  if (!exists) return skip('file-removed');
 
-    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 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 }));
+    return skip('cross-repo-deferred');
+  }
 
-    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 idMarker = spec.buildIdempotencyMarker(epicId, finding.index);
+  const alreadyFiled = await probeMarkerExists({
+    marker: idMarker,
+    owner: routedRepo.owner,
+    repo: routedRepo.repo,
+    ghPath,
+    spawnImpl,
+    cwd,
+  });
+  if (alreadyFiled) return skip('already-filed');
+
+  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}`,
+    );
+    return;
+  }
+  envelope.filed.push(
+    decorate(
+      {
+        index: finding.index,
+        severity: finding.severity,
+        path: finding.path,
+        source,
+        repo: `${routedRepo.owner}/${routedRepo.repo}`,
+        url: created.url,
+      },
+      finding,
+    ),
+  );
+}
+
+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;
 
-    const { title, body, labels } = spec.buildFollowUp({
+  const precondition = checkGraduatePreconditions({
+    epicId,
+    provider,
+    currentRepo,
+    config,
+    spec,
+  });
+  if (precondition) return { ...envelope, ...precondition };
+
+  const loaded = await loadGraduateFindings({ epicId, provider, spec });
+  if (!loaded.findings) return { ...envelope, ...loaded };
+
+  for (const finding of loaded.findings) {
+    await processGraduateFinding({
       finding,
-      source,
+      envelope,
+      decorate,
       epicId,
-      idMarker,
-    });
-    const created = await createFollowUpIssue({
-      owner: routedRepo.owner,
-      repo: routedRepo.repo,
-      title,
-      body,
-      labels,
+      currentRepo,
+      frameworkRepo,
+      classifier,
+      gitRef,
       ghPath,
       spawnImpl,
       cwd,
+      logger,
+      spec,
     });
-    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;