chore(repo): add parallel worktree hygiene guardrail

2026-04-01 08:53:14 +02:00
parent 90f2f3c123
commit 6249f61ce1
4 changed files with 253 additions and 0 deletions
@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/worktree-hygiene.mjs [--scope <path>]... [--allow-outside-scope] [--fail-outside-scope] [--fail-on-dirty] [--json]
+
+Examples:
+  node scripts/worktree-hygiene.mjs --scope docs/ --scope scripts/
+  node scripts/worktree-hygiene.mjs --scope apps/web/src/components/timeline/ --scope apps/web/e2e/timeline.spec.ts
+  node scripts/worktree-hygiene.mjs --scope docs/ --scope scripts/ --fail-outside-scope
+  node scripts/worktree-hygiene.mjs --fail-on-dirty
+  node scripts/worktree-hygiene.mjs --scope packages/api/src/router/ --allow-outside-scope
+`);
+}
+
+function normalizeScope(scope) {
+  return scope.replace(/\\/gu, "/").replace(/^\.\/+/u, "");
+}
+
+function parseArgs(argv) {
+  const scopes = [];
+  let allowOutsideScope = false;
+  let failOutsideScope = false;
+  let failOnDirty = false;
+  let json = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--") {
+      continue;
+    }
+    if (arg === "--scope") {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error("--scope requires a path value.");
+      }
+      scopes.push(normalizeScope(value));
+      index += 1;
+      continue;
+    }
+    if (arg === "--allow-outside-scope") {
+      allowOutsideScope = true;
+      continue;
+    }
+    if (arg === "--fail-outside-scope") {
+      failOutsideScope = true;
+      continue;
+    }
+    if (arg === "--fail-on-dirty") {
+      failOnDirty = true;
+      continue;
+    }
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      printUsage();
+      process.exit(0);
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return { scopes, allowOutsideScope, failOutsideScope, failOnDirty, json };
+}
+
+function runGit(args) {
+  return execFileSync("git", args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function parsePorcelain(output) {
+  return output
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const xy = line.slice(0, 2);
+      const rawPath = line.slice(3);
+      const renamed = xy.includes("R") || xy.includes("C");
+      const path = renamed ? rawPath.split(" -> ").at(-1) ?? rawPath : rawPath;
+      return {
+        xy,
+        path: path.replace(/\\/gu, "/"),
+      };
+    });
+}
+
+function matchesScope(path, scopes) {
+  return scopes.some((scope) => path === scope || path.startsWith(scope.endsWith("/") ? scope : `${scope}/`));
+}
+
+function summarize(entries) {
+  const summary = {
+    staged: 0,
+    unstaged: 0,
+    untracked: 0,
+  };
+
+  for (const entry of entries) {
+    if (entry.xy === "??") {
+      summary.untracked += 1;
+      continue;
+    }
+    if (entry.xy[0] && entry.xy[0] !== " ") {
+      summary.staged += 1;
+    }
+    if (entry.xy[1] && entry.xy[1] !== " ") {
+      summary.unstaged += 1;
+    }
+  }
+
+  return summary;
+}
+
+function formatEntries(title, entries) {
+  if (entries.length === 0) {
+    return `${title}: none`;
+  }
+  return `${title}:\n${entries.map((entry) => `- ${entry.xy} ${entry.path}`).join("\n")}`;
+}
+
+function main() {
+  const { scopes, allowOutsideScope, failOutsideScope, failOnDirty, json } = parseArgs(process.argv.slice(2));
+  const root = runGit(["rev-parse", "--show-toplevel"]).trim();
+  const branch = runGit(["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+  const entries = parsePorcelain(runGit(["status", "--short"]));
+  const inScope = scopes.length === 0 ? entries : entries.filter((entry) => matchesScope(entry.path, scopes));
+  const outOfScope = scopes.length === 0 ? [] : entries.filter((entry) => !matchesScope(entry.path, scopes));
+  const status = {
+    root,
+    branch,
+    scopes,
+    totals: summarize(entries),
+    inScope: inScope.length,
+    outOfScope: outOfScope.length,
+    allowOutsideScope,
+    failOutsideScope,
+    failOnDirty,
+  };
+
+  if (json) {
+    console.log(JSON.stringify({ ...status, entries: { inScope, outOfScope } }, null, 2));
+  } else {
+    console.log(`Repository: ${root}`);
+    console.log(`Branch: ${branch}`);
+    console.log(`Dirty entries: ${entries.length}`);
+    console.log(
+      `Summary: staged=${status.totals.staged}, unstaged=${status.totals.unstaged}, untracked=${status.totals.untracked}`,
+    );
+    if (scopes.length > 0) {
+      console.log(`Owned scope: ${scopes.join(", ")}`);
+      console.log(formatEntries("In scope", inScope));
+      console.log(formatEntries("Outside scope", outOfScope));
+      if (outOfScope.length > 0 && !allowOutsideScope) {
+        console.log("\nResult: outside-scope changes detected.");
+      } else if (outOfScope.length > 0) {
+        console.log("\nResult: outside-scope changes detected but tolerated by flag.");
+      } else {
+        console.log("\nResult: all dirty files are inside the declared scope.");
+      }
+    } else {
+      console.log(formatEntries("Dirty files", entries));
+    }
+  }
+
+  if (failOnDirty && entries.length > 0) {
+    process.exit(1);
+  }
+
+  if (scopes.length > 0 && outOfScope.length > 0 && (failOutsideScope || !allowOutsideScope)) {
+    process.exit(2);
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  printUsage();
+  process.exit(1);
+}