dev-loops 0.1.0

package/scripts/loop/debt-remediate.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+// ============================================================================
+// Debt remediation loop command
+//
+// Single CLI entrypoint: --input → cluster → score → shape → issue → report
+//
+// Usage:
+//   debt-remediate.mjs --input <path> [--repo <owner/name>] [--dry-run]
+//
+// Takes a JSON array of debt_signal objects, runs the full remediation pipeline,
+// and creates GitHub issues for each remediation_item outcome.
+// ============================================================================
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { requireOptionValue } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { DebtSignalSchema } from "@dev-loops/core/debt/signal";
+import { clusterSignalsEnriched } from "@dev-loops/core/debt/cluster";
+import { shapeFindings } from "@dev-loops/core/debt/shape";
+import { createRemediationIssue } from "@dev-loops/core/debt/remediation-to-issue";
+
+const REPO_ROOT = fileURLToPath(new URL("../..", import.meta.url));
+
+const USAGE = `Usage:
+  debt-remediate.mjs --input <path>
+  debt-remediate.mjs --input <path> --repo <owner/name>
+  debt-remediate.mjs --input <path> --dry-run
+
+Run the debt pipeline: cluster signals → score → shape → create
+GitHub issues for remediation_items.
+
+Required:
+  --input <path>          Path to a JSON file with array of debt_signal objects
+
+Optional:
+  --repo <owner/name>     Target repository (default: detected from git remote)
+  --dry-run               Validate and report without creating issues
+
+Output (stdout, JSON):
+  { "ok": true, "signals": N, "findings": N, "remediationItems": N, "issues": [...], "summary": "..." }
+
+Exit codes:
+  0  Success (all remediation issue creations succeeded)
+  1  Argument error, input validation failure, or issue creation failure`.trim();
+
+const parseError = buildParseError(USAGE);
+
+// ============================================================================
+// Signal validation
+// ============================================================================
+
+function validateSignals(signals) {
+  if (!Array.isArray(signals)) {
+    return { ok: false, error: "Input must be a JSON array of debt_signal objects" };
+  }
+  if (signals.length === 0) {
+    return { ok: false, error: "Input array must contain at least one debt_signal" };
+  }
+
+  const errors = [];
+  for (let i = 0; i < signals.length; i++) {
+    const result = DebtSignalSchema.safeParse(signals[i]);
+    if (!result.success) {
+      errors.push({
+        index: i,
+        id: signals[i]?.id || `index-${i}`,
+        issues: result.error.issues,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, error: "Signal validation failed", validationErrors: errors };
+  }
+
+  return { ok: true, signals };
+}
+
+// ============================================================================
+// Detect repo from git remote
+// ============================================================================
+
+function detectRepo() {
+  try {
+    const remote = execFileSync("git", ["remote", "get-url", "origin"], {
+      cwd: REPO_ROOT,
+      encoding: "utf-8",
+    }).trim();
+    // parseRepoSlug expects owner/name; extract from common remote URL formats
+    const match = remote.match(/(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/);
+    if (match) {
+      return parseRepoSlug(match[1]);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// Build summary report
+// ============================================================================
+
+function buildReport(signalsCount, findingsCount, results) {
+  const remediationItems = results.filter(r => r.outcome === "remediation_item");
+  const epics = results.filter(r => r.outcome === "debt_epic");
+  const defers = results.filter(r => r.outcome === "defer");
+  const watches = results.filter(r => r.outcome === "watch");
+  const dismisses = results.filter(r => r.outcome === "dismiss");
+
+  const issuesCreated = remediationItems.filter(r => r.issueCreated);
+  const issuesFailed = remediationItems.filter(r => !r.issueCreated && r.issueError);
+
+  const summary = [
+    `${signalsCount} signals → ${findingsCount} findings`,
+    `${remediationItems.length} remediation items (${issuesCreated.length} issues created, ${issuesFailed.length} failed)`,
+    `${epics.length} debt epics`,
+    `${defers.length} deferred`,
+    `${watches.length} watching`,
+    `${dismisses.length} dismissed`,
+  ].join("; ");
+
+  return {
+    signals: signalsCount,
+    findings: findingsCount,
+    remediationItems: remediationItems.length,
+    debtEpics: epics.length,
+    deferred: defers.length,
+    watching: watches.length,
+    dismissed: dismisses.length,
+    issues: remediationItems.map(r => ({
+      findingId: r.findingId,
+      title: r.artifact?.title,
+      created: r.issueCreated || false,
+      issueNumber: r.issueNumber || null,
+      issueUrl: r.issueUrl || null,
+      error: r.issueError || null,
+    })),
+    summary,
+  };
+}
+
+// ============================================================================
+// Run CLI (test-compatible: returns exitCode without calling process.exit)
+// ============================================================================
+
+export async function runCli(argv) {
+  const args = [...argv];
+  const options = { input: undefined, repo: undefined, dryRun: false, help: false };
+
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      break;
+    }
+    if (token === "--input") {
+      options.input = requireOptionValue(args, "--input", parseError);
+      continue;
+    }
+    if (token === "--repo") {
+      options.repo = requireOptionValue(args, "--repo", parseError);
+      continue;
+    }
+    if (token === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    throw parseError(`Unknown flag: ${token}`);
+  }
+
+  if (options.help) {
+    process.stdout.write(USAGE + "\n");
+    return { exitCode: 0 };
+  }
+
+  if (!options.input) {
+    throw parseError("Missing required flag: --input <path>");
+  }
+
+  // Resolve input path
+  const inputPath = path.resolve(options.input);
+
+  // Read and parse input
+  let rawInput;
+  try {
+    rawInput = await readFile(inputPath, "utf-8");
+  } catch (err) {
+    return { exitCode: 1, output: { ok: false, error: `Cannot read input file: ${inputPath}`, detail: err.message } };
+  }
+
+  let signals;
+  try {
+    signals = JSON.parse(rawInput);
+  } catch (err) {
+    return { exitCode: 1, output: { ok: false, error: "Input file is not valid JSON", detail: err.message } };
+  }
+
+  // Validate signals
+  const validation = validateSignals(signals);
+  if (!validation.ok) {
+    return { exitCode: 1, output: validation };
+  }
+
+  // Resolve repo
+  let repo;
+  if (options.repo) {
+    try {
+      repo = parseRepoSlug(options.repo);
+    } catch {
+      return { exitCode: 1, output: { ok: false, error: `Invalid repo slug: ${options.repo}` } };
+    }
+  } else {
+    repo = detectRepo();
+  }
+
+  if (!repo) {
+    return { exitCode: 1, output: { ok: false, error: "Cannot detect repository. Pass --repo <owner/name>." } };
+  }
+
+  // Run pipeline: cluster → score → shape
+  const findings = clusterSignalsEnriched(signals);
+  const shaped = shapeFindings(findings);
+
+  // Create issues for remediation_items (skip in dry-run mode)
+  const results = [];
+  let anyIssueFailed = false;
+  for (const { outcome, artifact, findingId } of shaped) {
+    if (outcome === "remediation_item" && artifact && !options.dryRun) {
+      try {
+        const issueResult = createRemediationIssue(artifact, repo);
+        if (!issueResult.ok) {
+          anyIssueFailed = true;
+        }
+        results.push({
+          outcome,
+          findingId,
+          artifact,
+          issueCreated: issueResult.ok,
+          issueNumber: issueResult.issueNumber || null,
+          issueUrl: issueResult.issueUrl || null,
+          issueError: issueResult.ok ? null : issueResult.error,
+        });
+      } catch (err) {
+        anyIssueFailed = true;
+        results.push({
+          outcome,
+          findingId,
+          artifact,
+          issueCreated: false,
+          issueNumber: null,
+          issueUrl: null,
+          issueError: err.message || "Unknown error creating issue",
+        });
+      }
+    } else if (outcome === "remediation_item" && artifact && options.dryRun) {
+      results.push({
+        outcome,
+        findingId,
+        artifact,
+        issueCreated: false,
+        issueNumber: null,
+        issueUrl: null,
+        issueError: null,
+        dryRun: true,
+      });
+    } else {
+      results.push({ outcome, findingId, artifact });
+    }
+  }
+
+  // Build report
+  const report = buildReport(signals.length, findings.length, results);
+  report.ok = !anyIssueFailed;
+  report.dryRun = options.dryRun;
+  report.repo = `${repo.owner}/${repo.name}`;
+
+  const outputTarget = report.ok ? process.stdout : process.stderr;
+  outputTarget.write(JSON.stringify(report) + "\n");
+  return { exitCode: anyIssueFailed ? 1 : 0 };
+}
+
+// ============================================================================
+// Direct CLI entrypoint
+// ============================================================================
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli(process.argv.slice(2)).then(({ exitCode, output }) => {
+    if (output) {
+      process.stderr.write(JSON.stringify(output) + "\n");
+    }
+    process.exitCode = exitCode;
+  }).catch((err) => {
+    process.stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = 1;
+  });
+}
+
+export { validateSignals, buildReport, detectRepo };

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = { base: null, head: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--help" || args[i] === "-h") {
+      process.stdout.write(`Usage: detect-change-scope.mjs [--base <ref>] [--head <ref>]
+Detect change scope from git diff for light-mode eligibility.
+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
+Exit codes:
+  0   Success
+  1   Error
+`);
+      process.exit(0);
+    }
+    if (args[i] === "--base" && i + 1 < args.length) opts.base = args[++i];
+    else if (args[i] === "--head" && i + 1 < args.length) opts.head = args[++i];
+  }
+  return opts;
+}
+export function parseGitDiffStat(output) {
+  const trimmed = output.trim();
+  if (trimmed.length === 0) {
+    return { filesChanged: 0, linesChanged: 0 };
+  }
+  const lines = trimmed.split("\n");
+  const lastLine = lines[lines.length - 1];
+  const isSummary = /\d+\s+files?\s+changed/.test(lastLine) || /\d+\s+insertion/.test(lastLine) || /\d+\s+deletion/.test(lastLine);
+  const fileCount = isSummary ? lines.length - 1 : lines.length;
+  let insertions = 0;
+  let deletions = 0;
+  if (isSummary) {
+    const insMatch = lastLine.match(/(\d+)\s+insertion/);
+    const delMatch = lastLine.match(/(\d+)\s+deletion/);
+    if (insMatch) insertions = parseInt(insMatch[1], 10);
+    if (delMatch) deletions = parseInt(delMatch[1], 10);
+  }
+  return { filesChanged: fileCount, linesChanged: insertions + deletions };
+}
+function detectScope({ base, head } = {}) {
+  let diffArgs = ["diff", "--stat"];
+  if (base && head) {
+    diffArgs.push(`${base}..${head}`);
+  } else if (base) {
+    diffArgs.push(base);
+  } else {
+    diffArgs.push("HEAD~1..HEAD");
+  }
+  let output;
+  try {
+    output = execFileSync("git", diffArgs, { encoding: "utf8", maxBuffer: 1_000_000 });
+  } catch (err) {
+    return { ok: false, filesChanged: 0, linesChanged: 0, error: err instanceof Error ? err.message : String(err) };
+  }
+  const parsed = parseGitDiffStat(output);
+  return { ok: true, ...parsed };
+}
+function isEligibleForLightMode(scope, threshold) {
+  return scope.filesChanged <= threshold.maxFiles && scope.linesChanged <= threshold.maxLines;
+}
+async function main() {
+  const opts = parseArgs();
+  const scope = detectScope(opts);
+  let threshold = { maxFiles: 3, maxLines: 200 };
+  let eligible = false;
+  try {
+    const { loadDevLoopConfig, resolveLightMode } = await import(
+      "@dev-loops/core/config"
+    );
+    const { config, errors } = await loadDevLoopConfig({ repoRoot: process.cwd() });
+    if (Array.isArray(errors) && errors.length > 0) {
+    } else {
+      const lightMode = resolveLightMode(config);
+      if (lightMode && scope.ok !== false) {
+        threshold = { maxFiles: lightMode.maxFiles, maxLines: lightMode.maxLines };
+        eligible = isEligibleForLightMode(scope, threshold);
+      }
+    }
+  } catch {
+  }
+  process.stdout.write(
+    JSON.stringify({
+      ...scope,
+      eligibleForLightMode: eligible,
+      threshold,
+    }) + "\n"
+  );
+}
+const isDirectRun =
+  process.argv[1] && process.argv[1].includes("detect-change-scope.mjs");
+if (isDirectRun) {
+  main().catch((err) => {
+    process.stderr.write(`${err.message}\n`);
+    process.exitCode = 1;
+  });
+}
+export { detectScope, isEligibleForLightMode };