CapaKraken/scripts/worktree-hygiene.mjs

#!/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);
}