@workit-dev/core 0.0.1 → 1.0.0

package/src/git/default-base.ts

@@ -0,0 +1,130 @@
+// The default base for patch-ids, author trailers and review lanes. Its own
+// module so the lane (core/policy/lane.ts) and the ledger can both read it
+// without importing each other.
+import { spawnSync } from "node:child_process";
+import { vcsConfig } from "../core/vcs-config";
+import { originHeadRef, resolveRef } from "./rev";
+
+const safeRef = (value: string): boolean => value.length > 0 && !value.startsWith("-");
+
+/**
+ * The PR target of the release track the checkout is on, when the workspace
+ * configures tracks (as `fanout plan` and `stack plan` pick their trunk); a
+ * plain workspace default does not override origin's default branch.
+ */
+const trackTrunk = (cwd: string): string | null => {
+  try {
+    const resolved = vcsConfig("resolve", cwd);
+    if (resolved.ok === false || !resolved.releaseTrack || resolved.releaseTrack.blocking)
+      return null;
+    const target = String(resolved.defaultTargetBranch ?? "").trim();
+    return target && safeRef(target) ? target : null;
+  } catch {
+    return null;
+  }
+};
+
+/** Every ref by full name: true when it peels to a commit. */
+type RefTable = { refs: Map<string, boolean>; originHead: string | null };
+
+// gitrevisions(7): where a short name is looked up, in order.
+const RULES = [
+  (n: string) => `refs/${n}`,
+  (n: string) => `refs/tags/${n}`,
+  (n: string) => `refs/heads/${n}`,
+  (n: string) => `refs/remotes/${n}`,
+  (n: string) => `refs/remotes/${n}/HEAD`,
+];
+
+/**
+ * `<name>^{commit}` resolves: git takes the FIRST existing ref in rule order
+ * (whatever it points at) and then needs a commit, so a tag `main` on a tree
+ * hides the branch `main`.
+ */
+const resolves = (table: RefTable, name: string): boolean => {
+  if (!safeRef(name)) return false;
+  for (const rule of RULES) {
+    const isCommit = table.refs.get(rule(name));
+    if (isCommit !== undefined) return isCommit;
+  }
+  return false;
+};
+
+/**
+ * `git symbolic-ref --short`'s name for a full ref: the shortest form that no
+ * earlier rule resolves to another ref (git's shorten_unambiguous_ref), so an
+ * `origin/main` branch or tag makes origin's HEAD `remotes/origin/main`.
+ */
+const shorten = (table: RefTable, full: string): string => {
+  const patterns = ["refs/", "refs/tags/", "refs/heads/", "refs/remotes/"];
+  for (let rule = RULES.length - 1; rule >= 0; rule -= 1) {
+    let short: string | null = null;
+    if (rule === 4) {
+      const match = /^refs\/remotes\/(.+)\/HEAD$/u.exec(full);
+      short = match ? match[1] : null;
+    } else if (full.startsWith(patterns[rule])) short = full.slice(patterns[rule].length);
+    if (!short) continue;
+    let clash = false;
+    for (let earlier = 0; earlier < rule && !clash; earlier += 1)
+      clash = table.refs.has(RULES[earlier](short));
+    if (!clash) return short;
+  }
+  return full;
+};
+
+/**
+ * Every ref and origin's HEAD target from one `git for-each-ref` (the
+ * candidates were probed one spawn each: #284 N6). Read fresh on every call:
+ * refs move during a workit call. Null when git refuses (a ref naming a
+ * missing object makes for-each-ref fatal), so the caller probes instead.
+ */
+function refTable(cwd: string): RefTable | null {
+  const run = spawnSync(
+    "git",
+    ["for-each-ref", "--format=%(refname)%00%(objecttype)%00%(*objecttype)%00%(symref)"],
+    { cwd, encoding: "utf8", timeout: 20_000, killSignal: "SIGKILL", windowsHide: true },
+  );
+  if (run.status !== 0) return null;
+  const refs = new Map<string, boolean>();
+  let target: string | null = null;
+  for (const row of (run.stdout ?? "").split(/\r?\n/u)) {
+    const [name, type, peeled, symref] = row.split("\0");
+    if (!name) continue;
+    refs.set(name, type === "commit" || peeled === "commit");
+    if (name === "refs/remotes/origin/HEAD" && symref) target = symref;
+  }
+  const table: RefTable = { refs, originHead: null };
+  if (target) table.originHead = shorten(table, target);
+  return table;
+}
+
+const CANDIDATES = ["origin/main", "origin/master", "main", "master", "origin/develop", "develop"];
+
+/** The base from probing each candidate with its own git call (the old way, kept for a repo for-each-ref refuses). */
+function probedBase(cwd: string, trunk: string | null): string | null {
+  if (trunk)
+    for (const candidate of [`origin/${trunk}`, trunk])
+      if (resolveRef(cwd, candidate)) return candidate;
+  const originHead = originHeadRef(cwd);
+  if (originHead && resolveRef(cwd, originHead)) return originHead;
+  for (const candidate of CANDIDATES) if (resolveRef(cwd, candidate)) return candidate;
+  return null;
+}
+
+/**
+ * The default base for patch-ids and author trailers: the release track's PR
+ * target (origin's copy, else the local one) when tracks are configured, else
+ * origin's HEAD branch, else the first of origin/main, origin/master, main,
+ * master, origin/develop, develop that exists.
+ */
+export function defaultBase(cwd: string): string | null {
+  const trunk = trackTrunk(cwd);
+  const table = refTable(cwd);
+  if (!table) return probedBase(cwd, trunk);
+  if (trunk)
+    for (const candidate of [`origin/${trunk}`, trunk])
+      if (resolves(table, candidate)) return candidate;
+  if (table.originHead && resolves(table, table.originHead)) return table.originHead;
+  for (const candidate of CANDIDATES) if (resolves(table, candidate)) return candidate;
+  return null;
+}

package/src/git/env-redirect.ts

@@ -0,0 +1,28 @@
+// Environment that points git at another repository, index, object store or
+// ref namespace than the one at the working directory (#545). Grants resolve
+// from the working directory; git follows these, so a grant-gated verb run
+// with any of them set could act on a repository whose grants were never read.
+
+export const GIT_REDIRECT_ENV = [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_COMMON_DIR",
+  "GIT_INDEX_FILE",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+  "GIT_NAMESPACE",
+] as const;
+
+/** The redirecting variables set (even empty) in any of `envs`, in GIT_REDIRECT_ENV order. */
+export const gitRedirectsIn = (...envs: ReadonlyArray<NodeJS.ProcessEnv>): string[] =>
+  GIT_REDIRECT_ENV.filter((name) => envs.some((env) => env[name] !== undefined));
+
+/** Why a grant-gated `workit <verb>` does not run under them, with its unblock. */
+export const gitRedirectRefusal = (
+  names: readonly string[],
+  verb: string,
+  cwd: string,
+): { error: string; unblock: string } => ({
+  error: `git_env_redirect: ${names.join(", ")} ${names.length === 1 ? "is" : "are"} set, so git would act on the repository ${names.length === 1 ? "it names" : "they name"} while grants are checked for ${cwd}; workit ${verb} does not run`,
+  unblock: `unset ${names.join(" ")}, or cd into the repository and run workit ${verb} there`,
+});

package/src/git/facts.ts

@@ -0,0 +1,122 @@
+// Git facts that cannot change while one workit process runs, asked once.
+//
+// A checkout's top level, git dir and common dir are fixed for the life of a
+// workit call (no verb moves or re-initialises the repository it runs in), yet
+// readers across the CLI asked git for them again and again: in one ledger
+// test file, 141 of 1,285 spawned processes (#284 N6). On Windows each spawn
+// costs 10-30x more than on Linux.
+//
+// Only successful answers are cached, so a directory that becomes a repository
+// later is asked again. A cached entry whose checkout no longer leads to its
+// git dir (removed, or re-added as a new worktree) is dropped. HEAD,
+// branches and other refs are never cached here: they move during a call, and
+// a stale HEAD would mis-key a SHA-keyed verdict.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/** Absolute paths as git prints them with --path-format=absolute; `top` is null in a bare repository or a git dir. */
+export type GitDirs = { top: string | null; gitDir: string; commonDir: string };
+
+const cache = new Map<string, GitDirs>();
+
+const revParse = (cwd: string, args: string[]): string[] | null => {
+  const run = spawnSync("git", ["rev-parse", "--path-format=absolute", ...args], {
+    cwd,
+    encoding: "utf8",
+    timeout: 20_000,
+    killSignal: "SIGKILL",
+    windowsHide: true,
+  });
+  if (run.status !== 0) return null;
+  const lines = (run.stdout ?? "").split(/\r?\n/u).filter(Boolean);
+  return lines.length === args.length ? lines : null;
+};
+
+const realOrNull = (file: string): string | null => {
+  try {
+    return fs.realpathSync.native(file);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Whether a cached entry still describes the checkout: its `.git` (the git
+ * dir itself, or a `gitdir:` file) must still lead to the cached git dir. A
+ * worktree removed and re-added at the same path gets a new admin dir, and
+ * git may hand the old name to another worktree, so the git dir existing is
+ * not enough.
+ */
+const stillValid = (facts: GitDirs): boolean => {
+  const gitDir = realOrNull(facts.gitDir);
+  if (!gitDir) return false;
+  if (!facts.top) return true;
+  const dotGit = path.join(facts.top, ".git");
+  let target: string | null = null;
+  try {
+    if (fs.statSync(dotGit).isDirectory()) target = dotGit;
+    else {
+      const match = /^gitdir:\s*(.+?)\s*$/mu.exec(fs.readFileSync(dotGit, "utf8"));
+      target = match ? path.resolve(facts.top, match[1]) : null;
+    }
+  } catch {
+    return false;
+  }
+  return target !== null && realOrNull(target) === gitDir;
+};
+
+/** The checkout's top level, git dir and common dir, from one git call per directory and process; null outside a repository. */
+export function gitDirs(cwd: string): GitDirs | null {
+  const key = path.resolve(cwd);
+  const hit = cache.get(key);
+  if (hit && stillValid(hit)) return hit;
+  cache.delete(key);
+  const full = revParse(key, ["--git-dir", "--git-common-dir", "--show-toplevel"]);
+  // A bare repository (or a cwd inside the git dir) has no top level, and git
+  // refuses the whole call: ask again without it.
+  const dirs = full ?? revParse(key, ["--git-dir", "--git-common-dir"]);
+  if (!dirs) return null;
+  const facts = { gitDir: dirs[0], commonDir: dirs[1], top: dirs[2] ?? null };
+  cache.set(key, facts);
+  return facts;
+}
+
+/** For tests that rebuild a repository at a path this process already asked about. */
+export function forgetGitDirs(): void {
+  cache.clear();
+}
+
+// One read per call, never across calls: the origin URL can be changed by the
+// user between two workit calls, but one verdict gate asked git for it twice
+// (the provider in vcs-config, the verdict mirror's identity in the ledger).
+// Inside `withinCall`, the first answer per directory is reused until `fn`
+// returns; outside it every read asks git.
+let callReads: Map<string, string | null> | null = null;
+
+/** Run `fn` with per-call reads (originUrl) shared, and forgotten when it returns. Nested calls join the outer one. */
+export function withinCall<T>(fn: () => T): T {
+  if (callReads) return fn();
+  callReads = new Map();
+  try {
+    return fn();
+  } finally {
+    callReads = null;
+  }
+}
+
+/** `git remote get-url origin`, trimmed; null without an origin. */
+export function originUrl(cwd: string): string | null {
+  const key = path.resolve(cwd);
+  if (callReads?.has(key)) return callReads.get(key) ?? null;
+  const run = spawnSync("git", ["remote", "get-url", "origin"], {
+    cwd,
+    encoding: "utf8",
+    timeout: 20_000,
+    killSignal: "SIGKILL",
+    windowsHide: true,
+  });
+  const url = run.status === 0 ? (run.stdout ?? "").trim() || null : null;
+  callReads?.set(key, url);
+  return url;
+}