dev-loops 0.1.0

package/scripts/refine/_refine-helpers.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { parsePositiveInteger, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { detectRepoSlug, parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+
+export const FORBIDDEN_PROSE_PATTERNS = [
+  /Child of #/iu,
+  /Parent:\s*#/iu,
+  /Depends on:\s*#/iu,
+  /sub-issue of #/iu,
+];
+
+export const DEFAULT_USAGE_SUFFIX = `
+Output:
+  Default output is human-readable text.
+  Add --json for machine-readable JSON.`.trim();
+
+export function normalizeIssueNumber(value, label, parseError) {
+  return parsePositiveInteger(value, label, parseError);
+}
+
+export function parseCheckerCliArgs(argv, usage, checkerName) {
+  const parseError = buildParseError(usage);
+  const args = [...argv];
+  const options = { help: false, input: undefined, json: false };
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--input") {
+      options.input = requireOptionValue(args, "--input", parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  if (typeof options.input !== "string" || options.input.trim().length === 0) {
+    throw parseError(`${checkerName} requires --input <path>`);
+  }
+  return options;
+}
+
+export function normalizeTreePayload(payload) {
+  if (!payload || typeof payload !== "object") {
+    throw new Error("Refinement tree input must be a JSON object");
+  }
+  const rootIssueNumber = normalizeIssueNumber(
+    payload.rootIssueNumber ?? payload.root,
+    "root issue number",
+    (message) => new Error(message),
+  );
+  if (!Array.isArray(payload.issues) || payload.issues.length === 0) {
+    throw new Error("Refinement tree input requires a non-empty issues array");
+  }
+
+  const issues = [];
+  const byNumber = new Map();
+  for (const rawIssue of payload.issues) {
+    if (!rawIssue || typeof rawIssue !== "object") {
+      throw new Error("Each issue entry must be an object");
+    }
+    const number = normalizeIssueNumber(rawIssue.number, "issue number", (message) => new Error(message));
+    const title = typeof rawIssue.title === "string" ? rawIssue.title : "";
+    const body = typeof rawIssue.body === "string" ? rawIssue.body : "";
+    const state = typeof rawIssue.state === "string" ? rawIssue.state : "open";
+
+    let parentNumber = null;
+    if (rawIssue.parentNumber !== undefined && rawIssue.parentNumber !== null) {
+      parentNumber = normalizeIssueNumber(rawIssue.parentNumber, "parent issue number", (message) => new Error(message));
+    }
+
+    const children = Array.isArray(rawIssue.children)
+      ? rawIssue.children.map((child) => normalizeIssueNumber(child, "child issue number", (message) => new Error(message)))
+      : [];
+
+    if (byNumber.has(number)) {
+      throw new Error(`Duplicate issue number in tree input: ${number}`);
+    }
+    const issue = { number, title, body, state, parentNumber, children };
+    byNumber.set(number, issue);
+    issues.push(issue);
+  }
+
+  const edges = [];
+  for (const issue of issues) {
+    for (const child of issue.children) {
+      edges.push({ parent: issue.number, child });
+    }
+  }
+
+  return {
+    mode: payload.mode === "online" ? "online" : "offline",
+    repo: typeof payload.repo === "string" ? payload.repo : null,
+    rootIssueNumber,
+    issues,
+    byNumber,
+    edges,
+  };
+}
+
+export async function loadTreeFromInput(inputPath) {
+  const raw = await readFile(inputPath, "utf8");
+  return normalizeTreePayload(parseJsonText(raw));
+}
+
+async function ghApiJson(args, { ghCommand = "gh", env = process.env } = {}) {
+  const result = await runChild(ghCommand, ["api", ...args], env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh api command failed: ${detail}`);
+  }
+  return parseJsonText(result.stdout);
+}
+
+export async function loadTreeOnline({ issue, repo, cwd = process.cwd(), ghCommand = "gh", env = process.env }) {
+  const resolvedRepo = typeof repo === "string" && repo.trim().length > 0
+    ? repo.trim()
+    : detectRepoSlug(cwd);
+  if (!resolvedRepo) {
+    throw new Error("Unable to detect repository slug. Pass --repo <owner/name>.");
+  }
+  const parsed = parseRepoSlug(resolvedRepo, { errorMessage: "--repo must match <owner/name>" });
+  const { owner, name } = parsed;
+
+  const byNumber = new Map();
+  const edges = [];
+  const queuedNumbers = new Set([issue]);
+  const queue = [{ number: issue, parentNumber: null }];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!Number.isInteger(current.number) || current.number <= 0) {
+      continue;
+    }
+
+    const issuePayload = await ghApiJson([
+      `repos/${owner}/${name}/issues/${current.number}`,
+    ], { ghCommand, env });
+
+    const number = issuePayload?.number;
+    if (!Number.isInteger(number) || number <= 0) {
+      throw new Error(`Invalid issue payload for #${current.number}`);
+    }
+
+    const existing = byNumber.get(number);
+    if (!existing) {
+      byNumber.set(number, {
+        number,
+        title: typeof issuePayload.title === "string" ? issuePayload.title : "",
+        body: typeof issuePayload.body === "string" ? issuePayload.body : "",
+        state: typeof issuePayload.state === "string" ? issuePayload.state : "open",
+        parentNumber: current.parentNumber,
+        children: [],
+      });
+    } else if (existing.parentNumber === null && current.parentNumber !== null) {
+      existing.parentNumber = current.parentNumber;
+    }
+
+    const subIssuesPayload = await ghApiJson([
+      `repos/${owner}/${name}/issues/${number}/sub_issues`,
+    ], { ghCommand, env });
+
+    const currentIssue = byNumber.get(number);
+    const children = [];
+    if (Array.isArray(subIssuesPayload)) {
+      for (const entry of subIssuesPayload) {
+        if (!entry || typeof entry !== "object") {
+          continue;
+        }
+        const childNumber = entry.number;
+        if (!Number.isInteger(childNumber) || childNumber <= 0) {
+          continue;
+        }
+        children.push(childNumber);
+        edges.push({ parent: number, child: childNumber });
+        if (!byNumber.has(childNumber) && !queuedNumbers.has(childNumber)) {
+          queuedNumbers.add(childNumber);
+          queue.push({ number: childNumber, parentNumber: number });
+        }
+      }
+    } else {
+      throw new Error(`Invalid sub-issues payload for #${number}: expected array`);
+    }
+
+    currentIssue.children = [...new Set(children)];
+  }
+
+  return {
+    mode: "online",
+    repo: resolvedRepo,
+    rootIssueNumber: issue,
+    issues: [...byNumber.values()],
+    byNumber,
+    edges,
+  };
+}
+
+export function extractSection(body, headingText) {
+  if (typeof body !== "string" || body.length === 0) {
+    return null;
+  }
+  const escapedHeading = headingText.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  const headingPattern = new RegExp(`^##\\s+${escapedHeading}\\s*$`, "imu");
+  const match = headingPattern.exec(body);
+  if (!match || match.index === undefined) {
+    return null;
+  }
+  const start = match.index + match[0].length;
+  const remaining = body.slice(start);
+  const nextHeadingMatch = /^##\s+/imu.exec(remaining);
+  const end = nextHeadingMatch && nextHeadingMatch.index !== undefined
+    ? start + nextHeadingMatch.index
+    : body.length;
+  return body.slice(start, end).trim();
+}
+
+export function normalizeScopeToken(value) {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[`*_~]/gu, "")
+    .replace(/^[:\-\s]+|[:\-\s]+$/gu, "")
+    .replace(/\s+/gu, " ");
+}
+
+export function writeCheckerOutput(result, { stdout = process.stdout, json = false }) {
+  if (json) {
+    stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+
+  const status = result.ok ? "PASS" : "FAIL";
+  const lines = [`${result.checker}: ${status}`];
+  if (result.errors.length === 0) {
+    lines.push("  - No problems found.");
+  } else {
+    for (const error of result.errors) {
+      const issuePart = Number.isInteger(error.issue) ? ` (#${error.issue})` : "";
+      lines.push(`  - [${error.code}]${issuePart} ${error.message}`);
+    }
+  }
+  stdout.write(`${lines.join("\n")}\n`);
+}
+
+
+export function handleCliError(error) {
+  process.stderr.write(`${formatCliError(error)}\n`);
+  process.exitCode = 1;
+}
+// Re-exported for checker scripts
+export { isDirectCliRun };

package/scripts/refine/prose-linkage-detector.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { formatCliError } from "../_core-helpers.mjs";
+import {
+  DEFAULT_USAGE_SUFFIX,
+  FORBIDDEN_PROSE_PATTERNS,
+  loadTreeFromInput,
+  parseCheckerCliArgs,
+  writeCheckerOutput,
+  isDirectCliRun,
+} from "./_refine-helpers.mjs";
+
+const USAGE = `Usage:
+  prose-linkage-detector.mjs --input <path> [--json]
+Fail when issue bodies use prose linkage (` + "`Child of #`, `Parent: #`, `Depends on: #`, `sub-issue of #`" + `)
+instead of GitHub sub-issue API links.${"\n"}${DEFAULT_USAGE_SUFFIX}`;
+
+export function runProseLinkageDetector(tree) {
+  const errors = [];
+  const parentByChild = new Map();
+
+  for (const edge of tree.edges) {
+    if (!parentByChild.has(edge.child)) {
+      parentByChild.set(edge.child, new Set());
+    }
+    parentByChild.get(edge.child).add(edge.parent);
+  }
+
+  for (const issue of tree.issues) {
+    for (const pattern of FORBIDDEN_PROSE_PATTERNS) {
+      if (pattern.test(issue.body)) {
+        errors.push({
+          code: "forbidden_prose_linkage",
+          issue: issue.number,
+          message: `Issue body contains forbidden prose linkage pattern: ${pattern.source}`,
+        });
+      }
+    }
+
+    for (const child of issue.children) {
+      const childIssue = tree.byNumber.get(child);
+      if (!childIssue) {
+        errors.push({
+          code: "missing_child_issue",
+          issue: issue.number,
+          message: `Sub-issue link references #${child}, but that issue is missing from the tree payload.`,
+        });
+        continue;
+      }
+      const parentSet = parentByChild.get(child) ?? new Set();
+      if (!parentSet.has(issue.number)) {
+        errors.push({
+          code: "missing_sub_issue_link",
+          issue: issue.number,
+          message: `Expected API sub-issue link #${issue.number} -> #${child} is missing.`,
+        });
+      }
+
+      if (Number.isInteger(childIssue.parentNumber) && childIssue.parentNumber !== issue.number) {
+        errors.push({
+          code: "parent_mismatch",
+          issue: child,
+          message: `Child issue #${child} declares parent #${childIssue.parentNumber}, not #${issue.number}.`,
+        });
+      }
+    }
+  }
+
+  return {
+    checker: "prose-linkage-detector",
+    ok: errors.length === 0,
+    errors,
+  };
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseCheckerCliArgs(argv, USAGE, "prose-linkage-detector");
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return { ok: true, help: true };
+  }
+  const tree = await loadTreeFromInput(options.input);
+  const result = runProseLinkageDetector(tree);
+  writeCheckerOutput(result, { stdout, json: options.json });
+  return result;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/refine/refinement-completeness-checker.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { formatCliError } from "../_core-helpers.mjs";
+import {
+  DEFAULT_USAGE_SUFFIX,
+  extractSection,
+  loadTreeFromInput,
+  parseCheckerCliArgs,
+  writeCheckerOutput,
+  isDirectCliRun,
+} from "./_refine-helpers.mjs";
+
+const USAGE = `Usage:
+  refinement-completeness-checker.mjs --input <path> [--json]
+Validate required refinement sections: Acceptance criteria, Definition of done, Non-goals, and AC / DoD matrix.${"\n"}${DEFAULT_USAGE_SUFFIX}`;
+
+function hasCheckbox(sectionText) {
+  if (typeof sectionText !== "string") {
+    return false;
+  }
+  return /^\s*-\s*\[\s\]\s+/imu.test(sectionText);
+}
+
+function hasMatrixTable(sectionText) {
+  if (typeof sectionText !== "string") {
+    return false;
+  }
+  const rows = sectionText
+    .split(/\r?\n/gu)
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("|"));
+  return rows.length >= 2;
+}
+
+export function runRefinementCompletenessChecker(tree) {
+  const errors = [];
+
+  for (const issue of tree.issues) {
+    const acceptanceCriteria = extractSection(issue.body, "Acceptance criteria");
+    const definitionOfDone = extractSection(issue.body, "Definition of done");
+    const nonGoals = extractSection(issue.body, "Non-goals");
+    const acDodMatrix = extractSection(issue.body, "AC / DoD matrix");
+
+    if (!acceptanceCriteria) {
+      errors.push({ code: "missing_acceptance_criteria", issue: issue.number, message: "Missing ## Acceptance criteria section." });
+    } else if (!hasCheckbox(acceptanceCriteria)) {
+      errors.push({ code: "missing_acceptance_checkbox", issue: issue.number, message: "Acceptance criteria section must include at least one '- [ ]' checkbox." });
+    }
+
+    if (!definitionOfDone) {
+      errors.push({ code: "missing_definition_of_done", issue: issue.number, message: "Missing ## Definition of done section." });
+    }
+
+    if (!nonGoals) {
+      errors.push({ code: "missing_non_goals", issue: issue.number, message: "Missing ## Non-goals section." });
+    }
+
+    if (!acDodMatrix) {
+      errors.push({ code: "missing_ac_dod_matrix", issue: issue.number, message: "Missing ## AC / DoD matrix section." });
+    } else if (!hasMatrixTable(acDodMatrix)) {
+      errors.push({ code: "invalid_ac_dod_matrix", issue: issue.number, message: "AC / DoD matrix section must contain a markdown table." });
+    }
+  }
+
+  return {
+    checker: "refinement-completeness-checker",
+    ok: errors.length === 0,
+    errors,
+  };
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseCheckerCliArgs(argv, USAGE, "refinement-completeness-checker");
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return { ok: true, help: true };
+  }
+  const tree = await loadTreeFromInput(options.input);
+  const result = runRefinementCompletenessChecker(tree);
+  writeCheckerOutput(result, { stdout, json: options.json });
+  return result;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/refine/scope-boundary-cross-checker.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+import { formatCliError } from "../_core-helpers.mjs";
+import {
+  DEFAULT_USAGE_SUFFIX,
+  extractSection,
+  loadTreeFromInput,
+  normalizeScopeToken,
+  parseCheckerCliArgs,
+  writeCheckerOutput,
+  isDirectCliRun,
+} from "./_refine-helpers.mjs";
+
+const USAGE = `Usage:
+  scope-boundary-cross-checker.mjs --input <path> [--json]
+Cross-check sibling scopes and non-goal handoffs to detect scope gaps and duplicate ownership.${"\n"}${DEFAULT_USAGE_SUFFIX}`;
+
+function extractOwnershipClaims(issue) {
+  const tokens = new Set();
+  const scopeSection = extractSection(issue.body, "Scope") ?? "";
+  const ownershipSection = extractSection(issue.body, "Ownership") ?? "";
+  const searchText = [scopeSection, ownershipSection, issue.body].filter(Boolean).join("\n");
+
+  const ownsPattern = /\bowns?\s+([^\n.;]+)/giu;
+  for (const match of searchText.matchAll(ownsPattern)) {
+    const token = normalizeScopeToken(match[1]);
+    if (token.length > 0) {
+      tokens.add(token);
+    }
+  }
+
+  for (const line of scopeSection.split(/\r?\n/gu)) {
+    const bullet = /^\s*[-*]\s+(.+)$/u.exec(line);
+    if (!bullet) continue;
+    const rawToken = bullet[1].replace(/^\s*owns?\s+/iu, '');
+    const token = normalizeScopeToken(rawToken);
+    if (token.length > 0) {
+      tokens.add(token);
+    }
+  }
+
+  return [...tokens];
+}
+
+function extractNonGoalDelegations(issue) {
+  const nonGoals = extractSection(issue.body, "Non-goals") ?? "";
+  const delegations = [];
+  for (const line of nonGoals.split(/\r?\n/gu)) {
+    const match = /not\s+(.+?)\s*(?:->|→)\s*#?(\d+)\b/iu.exec(line);
+    if (!match) {
+      continue;
+    }
+    const token = normalizeScopeToken(match[1]);
+    const target = Number(match[2]);
+    if (token.length > 0 && Number.isInteger(target) && target > 0) {
+      delegations.push({ token, target });
+    }
+  }
+  return delegations;
+}
+
+function buildSiblingGroups(tree) {
+  const childrenByParent = new Map();
+  for (const edge of tree.edges) {
+    if (!childrenByParent.has(edge.parent)) {
+      childrenByParent.set(edge.parent, new Set());
+    }
+    childrenByParent.get(edge.parent).add(edge.child);
+  }
+  return childrenByParent;
+}
+
+export function runScopeBoundaryCrossChecker(tree) {
+  const errors = [];
+  const ownershipByIssue = new Map();
+  const delegationsByIssue = new Map();
+
+  for (const issue of tree.issues) {
+    ownershipByIssue.set(issue.number, extractOwnershipClaims(issue));
+    delegationsByIssue.set(issue.number, extractNonGoalDelegations(issue));
+  }
+
+  for (const [parent, childrenSet] of buildSiblingGroups(tree)) {
+    const siblings = [...childrenSet].map((number) => tree.byNumber.get(number)).filter(Boolean);
+    if (siblings.length < 2) {
+      continue;
+    }
+
+    const ownersByToken = new Map();
+    for (const sibling of siblings) {
+      for (const token of ownershipByIssue.get(sibling.number) ?? []) {
+        if (!ownersByToken.has(token)) {
+          ownersByToken.set(token, new Set());
+        }
+        ownersByToken.get(token).add(sibling.number);
+      }
+    }
+
+    for (const sibling of siblings) {
+      const delegations = delegationsByIssue.get(sibling.number) ?? [];
+      for (const delegation of delegations) {
+        const target = tree.byNumber.get(delegation.target);
+        if (!target || !childrenSet.has(target.number)) {
+          continue;
+        }
+        const targetClaims = new Set(ownershipByIssue.get(target.number) ?? []);
+        if (!targetClaims.has(delegation.token)) {
+          errors.push({
+            code: "mutual_exclusion_gap",
+            issue: sibling.number,
+            message: `Issue #${sibling.number} delegates '${delegation.token}' to #${target.number}, but target does not claim ownership.`,
+            parent,
+          });
+        }
+
+        const ownerSet = ownersByToken.get(delegation.token);
+        if (!ownerSet || ownerSet.size === 0) {
+          errors.push({
+            code: "unowned_scope_gap",
+            issue: sibling.number,
+            message: `No sibling under parent #${parent} claims delegated scope '${delegation.token}'.`,
+            parent,
+          });
+        }
+      }
+    }
+
+    for (const [token, owners] of ownersByToken.entries()) {
+      if (owners.size > 1) {
+        errors.push({
+          code: "duplicate_ownership",
+          issue: parent,
+          message: `Siblings under #${parent} claim duplicate ownership for '${token}': ${[...owners].map((n) => `#${n}`).join(", ")}.`,
+          parent,
+        });
+      }
+    }
+  }
+
+  return {
+    checker: "scope-boundary-cross-checker",
+    ok: errors.length === 0,
+    errors,
+  };
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseCheckerCliArgs(argv, USAGE, "scope-boundary-cross-checker");
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return { ok: true, help: true };
+  }
+  const tree = await loadTreeFromInput(options.input);
+  const result = runScopeBoundaryCrossChecker(tree);
+  writeCheckerOutput(result, { stdout, json: options.json });
+  return result;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}