dev-loops 0.6.0 → 0.7.2

package/scripts/loop/detect-change-scope.mjs

@@ -2,6 +2,7 @@
 import { execFileSync } from "node:child_process";
 import process from "node:process";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: detect-change-scope.mjs [--base <ref>] [--head <ref>]
 Detect change scope from git diff for light-mode eligibility.
@@ -9,9 +10,13 @@ Options:
   --base <ref>   Override base ref (default: HEAD~1)
   --head <ref>   Override head ref; ignored unless --base is also set
   --help, -h     Show this help
+
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0   Success
   1   Error
+  2   Invalid --jq filter
 `;
 
 function parseCliArgs(argv) {
@@ -21,6 +26,7 @@ function parseCliArgs(argv) {
       base: { type: "string" },
       head: { type: "string" },
       help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -43,7 +49,9 @@ function parseCliArgs(argv) {
       }
       if (token.name === "head") {
         opts.head = token.value ?? null;
+        continue;
       }
+      if (matchJqOutputToken(token, opts)) continue;
     }
   }
   return opts;
@@ -67,7 +75,7 @@ export function parseGitDiffStat(output) {
   }
   return { filesChanged: fileCount, linesChanged: insertions + deletions };
 }
-function detectScope({ base, head } = {}) {
+function detectScope({ base, head, cwd } = {}) {
   let diffArgs = ["diff", "--stat"];
   if (base && head) {
     diffArgs.push(`${base}..${head}`);
@@ -78,7 +86,7 @@ function detectScope({ base, head } = {}) {
   }
   let output;
   try {
-    output = execFileSync("git", diffArgs, { encoding: "utf8", maxBuffer: 1_000_000 });
+    output = execFileSync("git", diffArgs, { encoding: "utf8", maxBuffer: 1_000_000, cwd: cwd || undefined });
   } catch (err) {
     return { ok: false, filesChanged: 0, linesChanged: 0, error: err instanceof Error ? err.message : String(err) };
   }
@@ -88,6 +96,27 @@ function detectScope({ base, head } = {}) {
 function isEligibleForLightMode(scope, threshold) {
   return scope.filesChanged <= threshold.maxFiles && scope.linesChanged <= threshold.maxLines;
 }
+/**
+ * Detect change scope for the merge-base diff between `base` and `head` (the
+ * three-dot `base...head` diff git resolves against merge-base(base, head)).
+ *
+ * Fails CLOSED: a missing base/head, or any git failure, returns `{ ok: false }`
+ * so callers that gate on scope (e.g. the light-mode pre-merge acceptance) reject
+ * rather than silently treating an unmeasurable diff as under threshold. Reuses
+ * the same `parseGitDiffStat` scope resolution as `detectScope`.
+ */
+function detectMergeBaseScope({ base, head, cwd } = {}) {
+  if (!base || !head) {
+    return { ok: false, filesChanged: 0, linesChanged: 0, error: "base and head are required for merge-base scope detection" };
+  }
+  let output;
+  try {
+    output = execFileSync("git", ["diff", "--stat", `${base}...${head}`], { encoding: "utf8", maxBuffer: 1_000_000, cwd: cwd || undefined });
+  } catch (err) {
+    return { ok: false, filesChanged: 0, linesChanged: 0, error: err instanceof Error ? err.message : String(err) };
+  }
+  return { ok: true, ...parseGitDiffStat(output) };
+}
 async function main() {
   const opts = parseCliArgs(process.argv.slice(2));
   const scope = detectScope(opts);
@@ -108,12 +137,12 @@ async function main() {
     }
   } catch {
   }
-  process.stdout.write(
-    JSON.stringify({
-      ...scope,
-      eligibleForLightMode: eligible,
-      threshold,
-    }) + "\n"
+  // This tool always exits 0 on a parsed run (scope.ok:false only reflects a git
+  // diff failure inside the payload, never the process outcome) — force ok:true
+  // as emitResult's default so --jq/--silent compose without changing that.
+  process.exitCode = emitResult(
+    { ...scope, eligibleForLightMode: eligible, threshold },
+    { jq: opts.jq, silent: opts.silent, ok: true },
   );
 }
 const isDirectRun =
@@ -124,4 +153,4 @@ if (isDirectRun) {
     process.exitCode = 1;
   });
 }
-export { detectScope, isEligibleForLightMode };
+export { detectScope, detectMergeBaseScope, isEligibleForLightMode };

package/scripts/loop/detect-copilot-loop-state.mjs

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
-import path from "node:path";
 import { parseArgs } from "node:util";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import {
@@ -15,7 +14,7 @@ import {
 } from "../_core-helpers.mjs";
 import { fetchGithubReviewThreadsPayload } from "../github/capture-review-threads.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
-import { loadDevLoopConfig, resolveRefinement } from "@dev-loops/core/config";
+import { loadDevLoopConfig, resolveEffectiveCopilotRoundCap, resolveRefinement } from "@dev-loops/core/config";
 import {
   buildSnapshotFromPrFacts,
   interpretLoopState,
@@ -28,6 +27,8 @@ import {
   normalizeHeadScopedCommitStatus,
   normalizeHeadScopedCiContract,
 } from "@dev-loops/core/loop/copilot-ci-status";
+import { resolveRepoRoot } from "./_repo-root-resolver.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage:
   detect-copilot-loop-state.mjs --repo <owner/name> --pr <number>
   detect-copilot-loop-state.mjs --input <path>
@@ -42,8 +43,13 @@ Required (auto-detect mode):
   --pr <number>                              Pull request number
 Required (snapshot mode):
   --input <path>                             Path to snapshot JSON file
-Optional (auto-detect mode only):
-Optional (auto-detect mode only):
+Optional (either mode):
+  --lightweight   This PR is light-dispatched (#1210): compose the Copilot
+                  round cap with localImplementation.lightMode.maxCopilotRounds
+                  (default 1) via min(lightMode.maxCopilotRounds,
+                  refinement.maxCopilotRounds) instead of using
+                  refinement.maxCopilotRounds alone. refinement.maxCopilotRounds:
+                  0 still disables Copilot rounds even with --lightweight.
 Output (stdout, JSON):
   { "ok": true, "snapshot": {..., "copilotReviewRoundCount": N}, "state": "...", "allowedTransitions": [...], "nextAction": "...",
     "autoRerequestEligible": true|false, "sameHeadCleanConverged": true|false,
@@ -53,9 +59,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
     { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error, gh failure, or indeterminate state`.trim();
+  1  Argument error, gh failure, or indeterminate state
+  2  Invalid --jq filter`.trim();
 const VALID_OVERRIDE_STATUSES = new Set(["requested", "already-requested", "unavailable", "none", "failed"]);
 const parseError = buildParseError(USAGE);
 export function parseDetectCliArgs(argv) {
@@ -64,6 +72,7 @@ export function parseDetectCliArgs(argv) {
     inputPath: undefined,
     repo: undefined,
     pr: undefined,
+    lightweight: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -72,6 +81,8 @@ export function parseDetectCliArgs(argv) {
       input: { type: "string" },
       repo: { type: "string" },
       pr: { type: "string" },
+      lightweight: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -100,6 +111,11 @@ export function parseDetectCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (token.name === "lightweight") {
+      options.lightweight = true;
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.inputPath !== undefined) {
@@ -419,6 +435,7 @@ export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -445,13 +462,22 @@ export async function runCli(
     interpretationInput = snapshot;
   }
   let interpretation;
-  const config = await loadDevLoopConfig({ repoRoot: path.resolve(process.cwd()) });
+  const config = await loadDevLoopConfig({ repoRoot: resolveRepoRoot(process.cwd()) });
   const refinementConfig = config.errors.length > 0
     ? resolveRefinement({ version: 1 })
     : resolveRefinement(config.config);
+  if (options.lightweight) {
+    // Compose (not replace) the round cap for light-dispatched PRs (#1210):
+    // min(lightMode.maxCopilotRounds ?? 1, refinement.maxCopilotRounds), so
+    // maxCopilotRounds: 0 still disables Copilot rounds everywhere.
+    refinementConfig.maxCopilotRounds = resolveEffectiveCopilotRoundCap(
+      config.errors.length > 0 ? { version: 1 } : config.config,
+      { lightweight: true },
+    );
+  }
   interpretation = interpretLoopState(interpretationInput, refinementConfig);
   const interpretationSummary = summarizeLoopInterpretation(interpretation);
-  stdout.write(`${JSON.stringify({
+  process.exitCode = emitResult({
     ok: true,
     snapshot,
     state: interpretation.state,
@@ -461,7 +487,7 @@ export async function runCli(
     sameHeadCleanConverged: interpretation.sameHeadCleanConverged,
     loopDisposition: interpretationSummary.loopDisposition,
     terminal: interpretationSummary.terminal,
-  })}\n`);
+  }, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

package/scripts/loop/detect-copilot-session-activity.mjs

@@ -3,6 +3,7 @@ import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "
 import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: detect-copilot-session-activity.mjs --repo <owner/name> --branch <name> [--limit <number>]
 Detect Copilot GitHub Actions session activity on a branch.
 Required:
@@ -32,7 +33,8 @@ Error output (stderr, JSON):
   Argument/usage errors:
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
-    { "ok": false, "error": "..." }`.trim();
+    { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}`.trim();
 const DEFAULT_LIMIT = 20;
 const ACTIVE_RUN_STATUSES = new Set(["queued", "in_progress", "pending", "requested", "waiting"]);
 const COPILOT_RUN_NAME_PATTERNS = Object.freeze([
@@ -55,6 +57,7 @@ export function parseDetectCopilotSessionActivityCliArgs(argv) {
       repo: { type: "string" },
       branch: { type: "string" },
       limit: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -83,6 +86,7 @@ export function parseDetectCopilotSessionActivityCliArgs(argv) {
       options.limit = parsePositiveInteger(requireTokenValue(token, parseError), "--limit", parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.branch === undefined || options.branch.length === 0) {
@@ -185,7 +189,7 @@ export async function detectCopilotSessionActivity({ repo, branch, limit = DEFAU
 }
 export async function runCli(
   argv = process.argv.slice(2),
-  { stdout = process.stdout, env = process.env, ghCommand = "gh" } = {},
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh" } = {},
 ) {
   const options = parseDetectCopilotSessionActivityCliArgs(argv);
   if (options.help) {
@@ -193,7 +197,7 @@ export async function runCli(
     return;
   }
   const result = await detectCopilotSessionActivity(options, { env, ghCommand });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

package/scripts/loop/detect-initial-copilot-pr-state.mjs

@@ -5,6 +5,7 @@ import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { detectLinkedIssuePr } from "../github/detect-linked-issue-pr.mjs";
 import { detectCopilotSessionActivity } from "./detect-copilot-session-activity.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: detect-initial-copilot-pr-state.mjs --repo <owner/name> --issue <number>
 Detect whether an assigned issue is still on the bootstrap-only Copilot draft PR
 or has moved into normal linked-PR follow-up.
@@ -43,7 +44,8 @@ Error output (stderr, JSON):
   Argument/usage errors:
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
-    { "ok": false, "error": "..." }`.trim();
+    { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}`.trim();
 export const LINKED_PR_STATE = Object.freeze({
   NO_LINKED_PR: "no_linked_pr",
   PRIOR_LINKED_PR_CLOSED_UNMERGED: "prior_linked_pr_closed_unmerged",
@@ -91,6 +93,7 @@ export function parseDetectInitialCopilotPrStateCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
       issue: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -115,6 +118,7 @@ export function parseDetectInitialCopilotPrStateCliArgs(argv) {
       options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.issue === undefined) {
@@ -313,7 +317,7 @@ export async function detectInitialCopilotPrState({ repo, issue }, { env = proce
 }
 export async function runCli(
   argv = process.argv.slice(2),
-  { stdout = process.stdout, env = process.env, ghCommand = "gh" } = {},
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh" } = {},
 ) {
   const options = parseDetectInitialCopilotPrStateCliArgs(argv);
   if (options.help) {
@@ -324,7 +328,7 @@ export async function runCli(
     { repo: options.repo, issue: options.issue },
     { env, ghCommand },
   );
-  stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

package/scripts/loop/detect-internal-only-pr.mjs

@@ -6,6 +6,7 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: detect-internal-only-pr.mjs --repo <owner/name> --pr <number> [--config <path>]
 Detect whether a PR only touches internal tooling files (scripts, docs, tests, config)
@@ -20,9 +21,11 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "internalOnly": true|false, "files": ["path1", "path2", ...],
     "reason": "...", "repo": "...", "pr": N }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or gh failure`.trim();
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -134,6 +137,7 @@ export function parseCliArgs(argv) {
       pr: { type: "string" },
       config: { type: "string" },
       "label-check": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -166,6 +170,7 @@ export function parseCliArgs(argv) {
       options.labelCheck = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -265,6 +270,7 @@ export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -275,7 +281,7 @@ export async function runCli(
     return;
   }
   const result = await detectInternalOnly(options, { env, ghCommand });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 
 if (isDirectCliRun(import.meta.url)) {

package/scripts/loop/detect-issue-refinement-artifact.mjs

@@ -8,6 +8,7 @@ import {
   detectIssueRefinementArtifact,
   REFINEMENT_SOURCE,
 } from "@dev-loops/core/loop/issue-refinement-artifact";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage:
   detect-issue-refinement-artifact.mjs --repo <owner/name> --issue <number>
   detect-issue-refinement-artifact.mjs --input <path>
@@ -31,7 +32,8 @@ Success output (stdout, JSON):
     "reason": "..."
   }
 Error output (stderr, JSON):
-  { "ok": false, "error": "...", "usage": "..." }`.trim();
+  { "ok": false, "error": "...", "usage": "..." }
+${JQ_OUTPUT_USAGE}`.trim();
 const parseError = buildParseError(USAGE);
 export function parseDetectIssueRefinementArtifactCliArgs(argv) {
   const options = {
@@ -47,6 +49,7 @@ export function parseDetectIssueRefinementArtifactCliArgs(argv) {
       repo: { type: "string" },
       issue: { type: "string" },
       input: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -79,6 +82,7 @@ export function parseDetectIssueRefinementArtifactCliArgs(argv) {
       options.input = requireTokenValue(token, parseError).trim();
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const hasInput = typeof options.input === "string" && options.input.length > 0;
@@ -165,8 +169,7 @@ export async function runCli(
   }
   try {
     const result = await detectIssueRefinementArtifactFromOptions(options, { env, ghCommand });
-    stdout.write(`${JSON.stringify(result)}\n`);
-    return 0;
+    return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
   } catch (error) {
     stderr.write(`${formatCliError(error)}\n`);
     return 1;