dev-loops 0.1.0

package/scripts/refine/tree-integrity-validator.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+import { formatCliError } from "../_core-helpers.mjs";
+import {
+  DEFAULT_USAGE_SUFFIX,
+  loadTreeFromInput,
+  parseCheckerCliArgs,
+  writeCheckerOutput,
+  isDirectCliRun,
+} from "./_refine-helpers.mjs";
+
+const MAX_DEPTH = 3;
+
+const USAGE = `Usage:
+  tree-integrity-validator.mjs --input <path> [--json]
+Validate sub-issue tree integrity: parent links, orphaned issues, cycles, and depth <= ${MAX_DEPTH}.${"\n"}${DEFAULT_USAGE_SUFFIX}`;
+
+function detectCycles(tree, startIssue) {
+  const cycles = [];
+  const visiting = new Set();
+  const visited = new Set();
+
+  function dfs(nodeNumber, path = []) {
+    if (visiting.has(nodeNumber)) {
+      const cycleStart = path.indexOf(nodeNumber);
+      const cyclePath = cycleStart >= 0 ? path.slice(cycleStart).concat(nodeNumber) : [...path, nodeNumber];
+      cycles.push(cyclePath);
+      return;
+    }
+    if (visited.has(nodeNumber)) {
+      return;
+    }
+
+    visiting.add(nodeNumber);
+    const issue = tree.byNumber.get(nodeNumber);
+    if (issue) {
+      for (const child of issue.children) {
+        dfs(child, [...path, nodeNumber]);
+      }
+    }
+    visiting.delete(nodeNumber);
+    visited.add(nodeNumber);
+  }
+
+  dfs(startIssue);
+  return cycles;
+}
+
+function collectReachableIssues(tree) {
+  const reachable = new Set();
+  const queue = [tree.rootIssueNumber];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (reachable.has(current)) {
+      continue;
+    }
+    reachable.add(current);
+    const issue = tree.byNumber.get(current);
+    if (!issue) {
+      continue;
+    }
+    for (const child of issue.children) {
+      queue.push(child);
+    }
+  }
+  return reachable;
+}
+
+function detectDepthViolations(tree) {
+  const violations = [];
+  const queue = [{ number: tree.rootIssueNumber, depth: 1 }];
+  const seen = new Map();
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const existingDepth = seen.get(current.number);
+    if (existingDepth !== undefined && existingDepth <= current.depth) {
+      continue;
+    }
+    seen.set(current.number, current.depth);
+
+    if (current.depth > MAX_DEPTH) {
+      violations.push({ issue: current.number, depth: current.depth });
+    }
+
+    const issue = tree.byNumber.get(current.number);
+    if (!issue) {
+      continue;
+    }
+    for (const child of issue.children) {
+      queue.push({ number: child, depth: current.depth + 1 });
+    }
+  }
+  return violations;
+}
+
+export function runTreeIntegrityValidator(tree) {
+  const errors = [];
+  const parentsByChild = new Map();
+
+  for (const edge of tree.edges) {
+    if (!parentsByChild.has(edge.child)) {
+      parentsByChild.set(edge.child, new Set());
+    }
+    parentsByChild.get(edge.child).add(edge.parent);
+  }
+
+  if (!tree.byNumber.has(tree.rootIssueNumber)) {
+    errors.push({
+      code: "missing_root_issue",
+      issue: tree.rootIssueNumber,
+      message: `Root issue #${tree.rootIssueNumber} is missing from the tree payload.`,
+    });
+    return {
+      checker: "tree-integrity-validator",
+      ok: false,
+      errors,
+    };
+  }
+
+  for (const issue of tree.issues) {
+    if (issue.number === tree.rootIssueNumber) {
+      continue;
+    }
+    const parentSet = parentsByChild.get(issue.number) ?? new Set();
+
+    if (issue.parentNumber !== null && !tree.byNumber.has(issue.parentNumber)) {
+      errors.push({
+        code: "orphaned_issue",
+        issue: issue.number,
+        message: `Issue #${issue.number} references missing parent #${issue.parentNumber}.`,
+      });
+    }
+
+    if (issue.parentNumber !== null && !parentSet.has(issue.parentNumber)) {
+      errors.push({
+        code: "child_missing_parent_link",
+        issue: issue.number,
+        message: `Issue #${issue.number} declares parent #${issue.parentNumber}, but parent does not link to it as a child.`,
+      });
+    }
+
+    if (parentSet.size === 0) {
+      errors.push({
+        code: "missing_parent",
+        issue: issue.number,
+        message: `Issue #${issue.number} has no parent link in the tree graph.`,
+      });
+    }
+
+    if (parentSet.size > 1) {
+      errors.push({
+        code: "multiple_parents",
+        issue: issue.number,
+        message: `Issue #${issue.number} is linked by multiple parents: ${[...parentSet].map((n) => `#${n}`).join(", ")}.`,
+      });
+    }
+  }
+
+  const reachable = collectReachableIssues(tree);
+  for (const issue of tree.issues) {
+    if (!reachable.has(issue.number)) {
+      errors.push({
+        code: "orphaned_issue",
+        issue: issue.number,
+        message: `Issue #${issue.number} is not reachable from root #${tree.rootIssueNumber}.`,
+      });
+    }
+  }
+
+  const cycles = detectCycles(tree, tree.rootIssueNumber);
+  for (const cycle of cycles) {
+    errors.push({
+      code: "cycle_detected",
+      issue: cycle[0],
+      message: `Cycle detected in sub-issue graph: ${cycle.map((n) => `#${n}`).join(" -> ")}.`,
+    });
+  }
+
+  const depthViolations = detectDepthViolations(tree);
+  for (const violation of depthViolations) {
+    errors.push({
+      code: "depth_limit_exceeded",
+      issue: violation.issue,
+      message: `Issue #${violation.issue} exceeds max depth ${MAX_DEPTH} (depth=${violation.depth}).`,
+    });
+  }
+
+  return {
+    checker: "tree-integrity-validator",
+    ok: errors.length === 0,
+    errors,
+  };
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseCheckerCliArgs(argv, USAGE, "tree-integrity-validator");
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return { ok: true, help: true };
+  }
+  const tree = await loadTreeFromInput(options.input);
+  const result = runTreeIntegrityValidator(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/verify.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { buildParseError, formatCliError } from "../_core-helpers.mjs";
+import { parsePositiveInteger, requireOptionValue } from "../_cli-primitives.mjs";
+import { detectRepoSlug, parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+
+import { isDirectCliRun, loadTreeFromInput, loadTreeOnline } from "./_refine-helpers.mjs";
+import { runProseLinkageDetector } from "./prose-linkage-detector.mjs";
+import { runScopeBoundaryCrossChecker } from "./scope-boundary-cross-checker.mjs";
+import { runRefinementCompletenessChecker } from "./refinement-completeness-checker.mjs";
+import { runTreeIntegrityValidator } from "./tree-integrity-validator.mjs";
+
+const USAGE = `Usage:
+  dev-loops refine verify --issue <number> [--repo <owner/name>] [--json]
+  dev-loops refine verify --input <path> [--json]
+Run epic-tree refinement verification with four checkers:
+  1) prose-linkage-detector
+  2) scope-boundary-cross-checker
+  3) refinement-completeness-checker
+  4) tree-integrity-validator
+
+Required (exactly one mode):
+  --issue <number>          Online mode: fetch tree via GitHub sub-issues API (use --repo or git remote)
+  --input <path>            Offline mode: validate local tree JSON snapshot
+
+Optional:
+  --repo <owner/name>       Repository slug for online mode
+  --json                    Machine-readable JSON output (default: human-readable summary)
+  --help                    Show this help`.trim();
+
+const parseError = buildParseError(USAGE);
+
+export function parseRefineVerifyCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    help: false,
+    issue: undefined,
+    repo: undefined,
+    input: undefined,
+    json: false,
+  };
+
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--issue") {
+      options.issue = parsePositiveInteger(requireOptionValue(args, "--issue", parseError), "Issue number", parseError);
+      continue;
+    }
+    if (token === "--repo") {
+      options.repo = requireOptionValue(args, "--repo", parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    if (token === "--input") {
+      options.input = requireOptionValue(args, "--input", parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+
+  const hasIssueMode = options.issue !== undefined;
+  const hasInputMode = typeof options.input === "string";
+  if (hasIssueMode === hasInputMode) {
+    throw parseError("Specify exactly one of --issue <number> or --input <path>");
+  }
+
+  if (options.repo !== undefined && !hasIssueMode) {
+    throw parseError("--repo is only valid with --issue mode");
+  }
+
+  if (typeof options.repo === "string") {
+    try { parseRepoSlug(options.repo, { errorMessage: "--repo must match <owner/name>" }); } catch (err) { throw parseError(err.message); }
+  }
+
+  return options;
+}
+
+function runAllCheckers(tree) {
+  const checks = [
+    runProseLinkageDetector(tree),
+    runScopeBoundaryCrossChecker(tree),
+    runRefinementCompletenessChecker(tree),
+    runTreeIntegrityValidator(tree),
+  ];
+
+  const errors = checks.flatMap((check) => check.errors.map((error) => ({ checker: check.checker, ...error })));
+
+  return {
+    ok: checks.every((check) => check.ok),
+    checks,
+    errors,
+  };
+}
+
+function writeHumanOutput(result, tree, { stdout = process.stdout }) {
+  const lines = [
+    `refine verify: ${result.ok ? "PASS" : "FAIL"}`,
+    `mode: ${tree.mode}`,
+    `root issue: #${tree.rootIssueNumber}`,
+  ];
+  if (tree.repo) {
+    lines.push(`repo: ${tree.repo}`);
+  }
+  for (const check of result.checks) {
+    lines.push(`${check.checker}: ${check.ok ? "PASS" : "FAIL"}`);
+    for (const error of check.errors) {
+      const issuePart = Number.isInteger(error.issue) ? ` (#${error.issue})` : "";
+      lines.push(`  - [${error.code}]${issuePart} ${error.message}`);
+    }
+  }
+  if (result.errors.length === 0) {
+    lines.push("No checker errors.");
+  }
+  stdout.write(`${lines.join("\n")}\n`);
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, cwd = process.cwd(), ghCommand = "gh", env = process.env } = {},
+) {
+  const options = parseRefineVerifyCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return { ok: true, help: true };
+  }
+
+  let resolvedRepo = options.repo;
+  if (options.issue !== undefined && typeof resolvedRepo !== "string") {
+    try {
+      resolvedRepo = detectRepoSlug(cwd);
+    if (!resolvedRepo) {
+      throw parseError("Unable to detect repository slug. Pass --repo <owner/name>.");
+    }
+    } catch (err) {
+      throw parseError(err.message);
+    }
+  }
+
+  const tree = options.input
+    ? await loadTreeFromInput(options.input)
+    : await loadTreeOnline({ issue: options.issue, repo: resolvedRepo, cwd, ghCommand, env });
+
+
+  const result = runAllCheckers(tree);
+
+  const payload = {
+    ok: result.ok,
+    mode: tree.mode,
+    repo: tree.repo,
+    rootIssue: tree.rootIssueNumber,
+    checkers: result.checks,
+    errors: result.errors,
+  };
+
+  if (options.json) {
+    stdout.write(`${JSON.stringify(payload)}\n`);
+  } else {
+    writeHumanOutput(result, tree, { stdout });
+  }
+
+  if (!result.ok) {
+    process.exitCode = 1;
+  }
+  return payload;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/repo-wiki-local.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// Pinned-source fallback repo-wiki wrapper. Clones mfittko/repo-wiki at a fixed
+// commit, installs/builds it locally, and proxies the requested command against
+// this repo.
+//
+// This helper is retained for environments that prefer a pinned source checkout
+// over the published npm install path (deterministic source pin, controlled
+// GitHub-only network access, offline reproduction after the initial clone).
+// It still requires git access to https://github.com/mfittko/repo-wiki.git for
+// the initial clone/fetch step.
+//
+// The primary repo-wiki entrypoint is `scripts/repo-wiki.mjs` (npm-installed).
+import { spawnSync } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { isDirectCliRun } from "@dev-loops/core/cli/helpers";
+
+export const REPO_WIKI_GIT_URL = "https://github.com/mfittko/repo-wiki.git";
+export const REPO_WIKI_REF = "d7e772e3d702a75896a6f4eec574a4e4e5bfa6dd";
+export const REPO_WIKI_MIN_NODE_MAJOR = 24;
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, "..");
+
+export function parseCliArgs(argv) {
+  const args = Array.isArray(argv) ? [...argv] : [];
+  if (args.length === 0) {
+    return { prepareOnly: false, passthroughArgs: ["--help"] };
+  }
+  if (args[0] === "prepare") {
+    return { prepareOnly: true, passthroughArgs: [] };
+  }
+  return { prepareOnly: false, passthroughArgs: args };
+}
+
+export function resolveRepoWikiPaths(projectRoot = PROJECT_ROOT, ref = REPO_WIKI_REF) {
+  const baseDir = path.join(projectRoot, ".tmp", "repo-wiki", ref);
+  const sourceDir = path.join(baseDir, "source");
+  const cliPath = path.join(sourceDir, "dist", "bin", "repo-wiki.js");
+  const buildStampPath = path.join(baseDir, "build-stamp.json");
+  return { projectRoot, baseDir, sourceDir, cliPath, buildStampPath };
+}
+
+export function assertSupportedNodeVersion(version = process.versions.node) {
+  const major = Number.parseInt(String(version).split(".")[0] ?? "", 10);
+  if (!Number.isInteger(major) || major < REPO_WIKI_MIN_NODE_MAJOR) {
+    throw new Error(
+      `repo-wiki local helper requires Node.js ${REPO_WIKI_MIN_NODE_MAJOR}+ because repo-wiki itself requires Node.js ${REPO_WIKI_MIN_NODE_MAJOR}+. Current runtime: ${version}`,
+    );
+  }
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd ?? PROJECT_ROOT,
+    env: { ...process.env, ...(options.env ?? {}) },
+    stdio: options.stdio ?? "inherit",
+    encoding: options.encoding ?? "utf8",
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const printable = [command, ...args].join(" ");
+    throw new Error(`Command failed (${result.status ?? "unknown"}): ${printable}`);
+  }
+
+  return result;
+}
+
+async function readBuildStamp(buildStampPath) {
+  try {
+    return JSON.parse(await readFile(buildStampPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeBuildStamp(buildStampPath) {
+  await writeFile(buildStampPath, JSON.stringify({ ref: REPO_WIKI_REF }, null, 2) + "\n", "utf8");
+}
+
+export async function ensureRepoWikiPrepared(projectRoot = PROJECT_ROOT) {
+  assertSupportedNodeVersion();
+  const { baseDir, sourceDir, cliPath, buildStampPath } = resolveRepoWikiPaths(projectRoot);
+  await mkdir(baseDir, { recursive: true });
+
+  let currentHead = null;
+  try {
+    run("git", ["-C", sourceDir, "rev-parse", "--is-inside-work-tree"], { stdio: "ignore" });
+    currentHead = run("git", ["-C", sourceDir, "rev-parse", "HEAD"], { stdio: "pipe" }).stdout.trim();
+  } catch {
+    run("git", ["clone", REPO_WIKI_GIT_URL, sourceDir], { cwd: baseDir });
+  }
+
+  if (currentHead !== REPO_WIKI_REF) {
+    run("git", ["-C", sourceDir, "fetch", "origin", REPO_WIKI_REF, "--depth", "1"]);
+    run("git", ["-C", sourceDir, "checkout", "--force", REPO_WIKI_REF]);
+  }
+
+  const stamp = await readBuildStamp(buildStampPath);
+  if (stamp?.ref !== REPO_WIKI_REF) {
+    run("npm", ["install", "--silent"], { cwd: sourceDir });
+    run("npm", ["run", "build", "--silent"], { cwd: sourceDir });
+    await writeBuildStamp(buildStampPath);
+  } else {
+    try {
+      run(process.execPath, [cliPath, "--help"], { stdio: "ignore" });
+    } catch {
+      run("npm", ["install", "--silent"], { cwd: sourceDir });
+      run("npm", ["run", "build", "--silent"], { cwd: sourceDir });
+      await writeBuildStamp(buildStampPath);
+    }
+  }
+
+  return resolveRepoWikiPaths(projectRoot);
+}
+
+// Composable entry point: returns a structured result instead of calling
+// process.exit so importers can reuse this wrapper without terminating the host
+// process. The direct-run block below owns the process-level exit-code mapping.
+export async function runRepoWikiLocal(argv, projectRoot = PROJECT_ROOT) {
+  const { prepareOnly, passthroughArgs } = parseCliArgs(argv);
+  const { cliPath } = await ensureRepoWikiPrepared(projectRoot);
+  if (prepareOnly) {
+    return { ok: true, status: 0, prepared: true, cliPath };
+  }
+
+  const result = spawnSync(process.execPath, [cliPath, ...passthroughArgs], {
+    cwd: projectRoot,
+    env: process.env,
+    stdio: "inherit",
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    return { ok: false, status: result.status ?? 1, cliPath };
+  }
+  return { ok: true, status: 0, prepared: true, cliPath };
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runRepoWikiLocal(process.argv.slice(2)).then((result) => {
+    if (!result.ok) {
+      process.exitCode = result.status;
+    }
+  }).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/scripts/repo-wiki.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// Primary repo-wiki wrapper. Proxies to the published @mfittko/repo-wiki npm package
+// at a pinned version, after validating that the consumer-repo config exists.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { isDirectCliRun } from "@dev-loops/core/cli/helpers";
+
+// Pinned to the latest published release at the time this slice was opened.
+// Bump deliberately when the consumer repo wants to adopt a newer release.
+export const REPO_WIKI_NPM_PACKAGE = "@mfittko/repo-wiki";
+export const REPO_WIKI_NPM_VERSION = "0.2.6";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, "..");
+
+export const REPO_WIKI_MIN_NODE_MAJOR = 20;
+
+export function resolveRepoWikiConfigPath(projectRoot = PROJECT_ROOT) {
+  return path.join(projectRoot, ".llmwiki", "config.json");
+}
+
+export const REPO_WIKI_CONFIG_PATH = resolveRepoWikiConfigPath();
+export const REPO_WIKI_SCHEMA_PATH = path.join(PROJECT_ROOT, ".llmwiki", "schema.md");
+
+export function parseCliArgs(argv) {
+  const args = Array.isArray(argv) ? [...argv] : [];
+  if (args.length === 0) {
+    return { passthroughArgs: ["--help"] };
+  }
+  if (args[0] === "--help" || args[0] === "-h") {
+    return { passthroughArgs: ["--help"] };
+  }
+  return { passthroughArgs: args };
+}
+
+export function assertSupportedNodeVersion(version = process.versions.node) {
+  const major = Number.parseInt(String(version).split(".")[0] ?? "", 10);
+  if (!Number.isInteger(major) || major < REPO_WIKI_MIN_NODE_MAJOR) {
+    throw new Error(
+      `repo-wiki npm wrapper requires Node.js ${REPO_WIKI_MIN_NODE_MAJOR}+. Current runtime: ${version}`,
+    );
+  }
+}
+
+export function assertConsumerConfigPresent({
+  configPath = REPO_WIKI_CONFIG_PATH,
+  projectRoot = PROJECT_ROOT,
+} = {}) {
+  // When callers override projectRoot without overriding configPath, derive the
+  // expected config path from the override so tests and other call sites stay
+  // consistent with the per-project layout.
+  const resolvedConfigPath =
+    configPath === REPO_WIKI_CONFIG_PATH ? resolveRepoWikiConfigPath(projectRoot) : configPath;
+  if (!existsSync(resolvedConfigPath)) {
+    throw new Error(
+      `Missing required repo-wiki config at ${path.relative(projectRoot, resolvedConfigPath) || resolvedConfigPath}.\n` +
+      `This repository expects a checked-in \`.llmwiki/config.json\`. ` +
+      `If you deleted it intentionally, restore it from git or regenerate it with \`repo-wiki init --repo .\`.`,
+    );
+  }
+  return resolvedConfigPath;
+}
+
+export function buildNpxInvocation({
+  packageName = REPO_WIKI_NPM_PACKAGE,
+  version = REPO_WIKI_NPM_VERSION,
+  passthroughArgs = [],
+} = {}) {
+  return ["npx", "--yes", `${packageName}@${version}`, ...passthroughArgs];
+}
+
+export function runNpxInvocation({
+  command,
+  args,
+  cwd = PROJECT_ROOT,
+  env = process.env,
+} = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    stdio: "inherit",
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  return result;
+}
+
+// Composable entry point: returns a structured result instead of calling
+// process.exit so importers can reuse this wrapper without terminating the host
+// process. The direct-run block below owns the process-level exit-code mapping.
+export async function runRepoWiki(argv, projectRoot = PROJECT_ROOT) {
+  assertSupportedNodeVersion();
+  assertConsumerConfigPresent({ projectRoot });
+  const { passthroughArgs } = parseCliArgs(argv);
+  const invocation = buildNpxInvocation({ passthroughArgs });
+
+  const result = runNpxInvocation({ command: invocation[0], args: invocation.slice(1), cwd: projectRoot });
+
+  if (result.status !== 0) {
+    return { ok: false, status: result.status ?? 1, invocation };
+  }
+  return { ok: true, status: 0, invocation };
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runRepoWiki(process.argv.slice(2)).then((result) => {
+    if (!result.ok) {
+      process.exitCode = result.status;
+    }
+  }).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}