@workit-dev/core 0.0.1 → 1.0.0

package/src/core/changelog-gate.ts

@@ -0,0 +1,349 @@
+// The Keep a Changelog gate `workit pr create` runs when a workspace opts in
+// (`changelog: update|create` in workspaces.json, default off). A user-facing
+// PR (any Conventional Commit type but chore, test, docs, ci, build, style,
+// or a breaking `!`) needs at least one bullet under `## [Unreleased]` that
+// the branch adds against its PR base. The gate only reads: entries are
+// written by `workit changelog apply`, never here, so existing entries are
+// never rewritten or reordered.
+//
+// - The changelog is CHANGELOG.md at the root unless the workspace sets
+//   `changelogPath` (one path, or a list: an entry in any of them counts).
+//   A glob entry (`projects/*/CHANGELOG.md`) makes each matched file the
+//   changelog of its directory: every such directory the diff touches needs
+//   its own entry; a diff touching none of them needs one in any.
+// - `update` asks for an entry only where a changelog exists at HEAD.
+// - `create` asks for it always (`workit changelog apply` creates the file).
+// - `--no-changelog "<reason>"` skips it; the reason goes on the PR.
+// - The base is fetched from the base remote first (as `--fill` does); one
+//   that still cannot be compared blocks with its own reason and a fetch fix,
+//   since an unchecked PR is exactly the forgotten entry the gate exists for.
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { GIT_TIMEOUTS, fetchRefs, mergeBase, pushRemoteName, resolveRef } from "../git/rev";
+import { DEFAULT_CHANGELOG_PATH, type ChangelogMode } from "./workspaces";
+
+/** Conventional Commit types whose change no user sees: no entry needed. */
+const NON_USER_FACING_TYPES = ["chore", "test", "docs", "ci", "build", "style"] as const;
+
+export type ChangelogGate =
+  | { status: "off" }
+  | { status: "not-user-facing"; mode: ChangelogMode; type: string }
+  | { status: "skipped"; mode: ChangelogMode; reason: string }
+  | { status: "no-file"; mode: ChangelogMode; paths: string[]; candidates: string[] }
+  | { status: "base-unknown"; mode: ChangelogMode; base: string; remote: string; fetch: string }
+  | {
+      status: "has-entry";
+      mode: ChangelogMode;
+      file: string;
+      added: string[];
+      /** Every changelog that gained an entry, when more than one did. */
+      files?: string[];
+      /** The fetch failed but a local copy of the base resolved: compared with that copy. */
+      staleBase?: string;
+    }
+  | {
+      status: "missing";
+      mode: ChangelogMode;
+      file: string;
+      category: string;
+      command: string;
+      candidates: string[];
+      /** The changelog files the check read (the configured paths when none exists). */
+      looked: string[];
+      /** Package changelogs the diff touches that gained no entry (glob paths only). */
+      lacking?: string[];
+      staleBase?: string;
+    };
+
+const TITLE_RE = /^(\w+)(?:\([^)]*\))?(!)?:/u;
+const UNRELEASED_RE = /^##\s+\[Unreleased\][^\n]*\n([\s\S]*?)(?=^##\s+\[|(?![\s\S]))/imu;
+const BULLET_RE = /^[-*]\s+(.+?)\s*$/u;
+
+/**
+ * The title's Conventional Commit type when it is not user-facing, else null.
+ * A breaking change (`chore!:`) and a title that is not a Conventional Commit
+ * count as user-facing.
+ */
+export function nonUserFacingType(title: string): string | null {
+  const parsed = TITLE_RE.exec(title.split("\n", 1)[0] ?? "");
+  if (!parsed || parsed[2]) return null;
+  const type = parsed[1].toLowerCase();
+  return (NON_USER_FACING_TYPES as readonly string[]).includes(type) ? type : null;
+}
+
+/** The bullets under `## [Unreleased]`, trimmed, in file order. */
+export function unreleasedBullets(text: string): string[] {
+  const body = UNRELEASED_RE.exec(text.replaceAll("\r\n", "\n"))?.[1] ?? "";
+  return body
+    .split("\n")
+    .map((line) => BULLET_RE.exec(line)?.[1])
+    .filter((bullet): bullet is string => Boolean(bullet));
+}
+
+/** The Keep a Changelog category a title's change most likely belongs to. */
+const categoryFor = (title: string): string => {
+  const type = TITLE_RE.exec(title)?.[1]?.toLowerCase();
+  return type === "feat" ? "Added" : type === "fix" ? "Fixed" : "Changed";
+};
+
+/** The command that writes the missing entry into `file`. */
+const applyCommand = (category: string, file: string): string =>
+  `workit changelog apply --entries '{"${category}": ["<what users can now do>"]}'${
+    file === DEFAULT_CHANGELOG_PATH ? "" : ` --path ${file}`
+  }`;
+
+/** `file` (repo-relative) at `rev`, or null when it is not in that commit. */
+const fileAt = (cwd: string, rev: string, file: string): string | null => {
+  const run = spawnSync("git", ["show", `${rev}:${file}`], {
+    cwd,
+    encoding: "utf8",
+    timeout: GIT_TIMEOUTS.local,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return run.status === 0 ? run.stdout : null;
+};
+
+const CHANGELOG_NAME = /(?:^|\/)(?:changelog|changes|history)(?:\.md)?$/iu;
+
+/** Tracked changelog-like files other than the root one, for a hint to set `changelogPath`. */
+const candidatesAt = (cwd: string): string[] => {
+  const run = spawnSync("git", ["ls-files", "-z"], {
+    cwd,
+    encoding: "utf8",
+    timeout: GIT_TIMEOUTS.local,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (run.status !== 0) return [];
+  return run.stdout
+    .split("\0")
+    .filter((file) => CHANGELOG_NAME.test(file) && file !== DEFAULT_CHANGELOG_PATH)
+    .filter((file) => !file.split("/").includes("node_modules"))
+    .slice(0, 5);
+};
+
+/**
+ * The PR base, fetched from the base remote first so a fork or a stale ref
+ * never moves the fork point: that remote's ref, else the local branch. The
+ * fetch error (offline, no such branch) is kept for the block message.
+ */
+const baseCommit = (
+  cwd: string,
+  remote: string,
+  base: string,
+): { rev: string | null; fetchError: string | null } => {
+  const tracking = `refs/remotes/${remote}/${base}`;
+  if (base.startsWith("-")) return { rev: null, fetchError: "a branch name cannot start with -" };
+  const fetched = fetchRefs(cwd, remote, [`+refs/heads/${base}:${tracking}`]);
+  return {
+    rev: resolveRef(cwd, tracking) ?? resolveRef(cwd, `refs/heads/${base}`),
+    fetchError: fetched.ok ? null : fetched.error,
+  };
+};
+
+/** Where HEAD forked from the PR base, resolved once for every `pr create` check. */
+export type ForkPoint = {
+  remote: string;
+  base: string;
+  /** The merge base of the PR base and HEAD; null when the base is unknown here. */
+  fork: string | null;
+  /** The base resolved but its fetch failed: the comparison used the older local copy. */
+  staleBase: string | null;
+  fetchError: string | null;
+};
+
+export function resolveForkPoint(cwd: string, base: string, baseRemote?: string): ForkPoint {
+  const remote = baseRemote ?? pushRemoteName(cwd) ?? "origin";
+  const resolved = baseCommit(cwd, remote, base);
+  return {
+    remote,
+    base,
+    fork: resolved.rev ? mergeBase(cwd, resolved.rev, "HEAD") : null,
+    staleBase: resolved.rev ? resolved.fetchError : null,
+    fetchError: resolved.fetchError,
+  };
+}
+
+const gitList = (cwd: string, args: string[]): string[] => {
+  const run = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: GIT_TIMEOUTS.local,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return run.status === 0 ? run.stdout.split("\0").filter(Boolean) : [];
+};
+
+/** The files the branch changed since `fork`, repo-relative. */
+export const changedSince = (cwd: string, fork: string): string[] =>
+  gitList(cwd, ["diff", "--name-only", "-z", "--no-renames", fork, "HEAD"]);
+
+/** Whether a `changelogPath` entry is a glob (`*`, `**`, `?`) rather than one file. */
+export const isChangelogGlob = (pattern: string): boolean => /[*?]/u.test(pattern);
+
+const escapeRe = (text: string): string => text.replace(/[.+^${}()|[\]\\]/gu, "\\$&");
+
+/** `*` and `?` stay inside one path segment; `**` spans any number of them. */
+const globRe = (pattern: string): RegExp => {
+  const source = pattern
+    .split(/(\*\*\/|\*\*|\*|\?)/u)
+    .map((part) =>
+      part === "**/"
+        ? "(?:[^/]+/)*"
+        : part === "**"
+          ? ".*"
+          : part === "*"
+            ? "[^/]*"
+            : part === "?"
+              ? "[^/]"
+              : escapeRe(part),
+    )
+    .join("");
+  return new RegExp(`^${source}$`, "u");
+};
+
+/** One changelog a `changelogPath` entry names; `pkg` is its directory when a glob matched it. */
+type ChangelogFile = { file: string; pkg: string | null };
+
+const expand = (paths: readonly string[], tracked: () => string[]): ChangelogFile[] => {
+  const seen = new Set<string>();
+  const out: ChangelogFile[] = [];
+  for (const pattern of paths) {
+    const matches = isChangelogGlob(pattern)
+      ? tracked()
+          .filter((file) => globRe(pattern).test(file))
+          .toSorted()
+          .map((file) => ({ file, pkg: file.includes("/") ? path.posix.dirname(file) : null }))
+      : [{ file: pattern, pkg: null }];
+    for (const match of matches)
+      if (!seen.has(match.file)) {
+        seen.add(match.file);
+        out.push(match);
+      }
+  }
+  // Globs that match nothing here (a single-package repo under a monorepo setting) mean the root file.
+  if (!out.length && paths.every(isChangelogGlob))
+    out.push({ file: DEFAULT_CHANGELOG_PATH, pkg: null });
+  return out;
+};
+
+const trackedAt = (cwd: string, rev: string) => {
+  let files: string[] | null = null;
+  return () => (files ??= gitList(cwd, ["ls-tree", "-r", "-z", "--name-only", rev]));
+};
+
+/**
+ * The changelog files `paths` resolves to at `rev` (default HEAD): each plain
+ * path as given, each glob as the tracked files it matches.
+ */
+export const resolveChangelogPaths = (cwd: string, paths: readonly string[], rev = "HEAD") =>
+  expand(paths, trackedAt(cwd, rev)).map(({ file }) => file);
+
+/** The package changelog that owns `file`: the deepest glob-matched directory holding it. */
+const ownerOf = (packages: readonly ChangelogFile[], file: string): string | null => {
+  let owner: ChangelogFile | null = null;
+  for (const candidate of packages)
+    if (
+      candidate.pkg &&
+      file.startsWith(`${candidate.pkg}/`) &&
+      candidate.pkg.length > (owner?.pkg?.length ?? -1)
+    )
+      owner = candidate;
+  return owner?.file ?? null;
+};
+
+/** Whether a PR titled `title` from HEAD into `base` may open under `mode`. */
+export function changelogGate(input: {
+  cwd: string;
+  mode: ChangelogMode;
+  title: string;
+  base: string;
+  /** The remote the PR targets (the forge's base remote); default the push remote, else origin. */
+  baseRemote?: string;
+  /**
+   * Repo-relative changelog paths or globs (default: CHANGELOG.md). A file a
+   * glob matched is its directory's changelog: each such directory the diff
+   * touches needs its own entry.
+   */
+  paths?: string[];
+  /** Whether `paths` came from the workspace; if not, a missing root file names candidates. */
+  pathConfigured?: boolean;
+  skipReason?: string | null;
+  /** The fork point, when the caller resolved it already (`pr create` shares it with the docs check). */
+  forkPoint?: () => ForkPoint;
+}): ChangelogGate {
+  const { cwd, mode, title, base } = input;
+  const paths = input.paths?.length ? input.paths : [DEFAULT_CHANGELOG_PATH];
+  if (mode === "off") return { status: "off" };
+  const type = nonUserFacingType(title);
+  if (type) return { status: "not-user-facing", mode, type };
+  if (input.skipReason) return { status: "skipped", mode, reason: input.skipReason };
+  const atHead = expand(paths, trackedAt(cwd, "HEAD"));
+  const present = atHead.flatMap((entry) => {
+    const text = fileAt(cwd, "HEAD", entry.file);
+    return text === null ? [] : [{ ...entry, text }];
+  });
+  const point = input.forkPoint?.() ?? resolveForkPoint(cwd, base, input.baseRemote);
+  const { fork, remote } = point;
+  const unknown: ChangelogGate = {
+    status: "base-unknown",
+    mode,
+    base,
+    remote,
+    fetch: point.fetchError ?? "the base has no common history with this branch here",
+  };
+  // The fetch failed but an older local copy resolved: the comparison stands, and says so.
+  const stale = point.staleBase ? { staleBase: point.staleBase } : {};
+  const category = categoryFor(title);
+  // A file the base has and the branch deleted is an entry removed, not "nothing to update".
+  const deleted = fork
+    ? expand(paths, trackedAt(cwd, fork)).find(({ file }) => fileAt(cwd, fork, file) !== null)?.file
+    : undefined;
+  const looked = present.length ? present.map(({ file }) => file) : paths;
+  const candidates = present.length || deleted || input.pathConfigured ? [] : candidatesAt(cwd);
+  const missingOf = (file: string, lacking?: string[]): ChangelogGate => ({
+    status: "missing",
+    mode,
+    file,
+    category,
+    command: applyCommand(category, file),
+    candidates,
+    looked,
+    ...(lacking ? { lacking } : {}),
+    ...stale,
+  });
+  if (!present.length) {
+    const file = deleted ?? atHead.find(({ pkg }) => pkg === null)?.file;
+    if (file && (mode === "create" || deleted)) return missingOf(file);
+    // Without a base the deletion check cannot run; `update` asks nothing of a repo with no file.
+    return { status: "no-file", mode, paths, candidates };
+  }
+  if (!fork) return unknown;
+  const entries = present.map(({ file, text }) => {
+    const before = new Set(
+      unreleasedBullets(fileAt(cwd, fork, file) ?? "").map((bullet) => bullet.toLowerCase()),
+    );
+    return { file, added: unreleasedBullets(text).filter((b) => !before.has(b.toLowerCase())) };
+  });
+  const expected = [
+    ...new Set(
+      changedSince(cwd, fork)
+        .map((file) => ownerOf(present, file))
+        .filter((file): file is string => file !== null),
+    ),
+  ];
+  const withEntry = entries.filter(({ added }) => added.length);
+  if (expected.length) {
+    const lacking = expected.filter((file) => !withEntry.some((entry) => entry.file === file));
+    if (lacking.length) return missingOf(lacking[0], lacking);
+  }
+  if (!withEntry.length) return missingOf(present[0].file);
+  const [first] = withEntry;
+  return {
+    status: "has-entry",
+    mode,
+    file: first.file,
+    added: first.added,
+    ...(withEntry.length > 1 ? { files: withEntry.map(({ file }) => file) } : {}),
+    ...stale,
+  };
+}

package/src/core/changelog-merge.ts

@@ -0,0 +1,214 @@
+// Three-way merge of a Keep a Changelog file for `workit changelog merge`, a git
+// merge driver: two branches that each add bullets under `## [Unreleased]` merge
+// without a conflict. Only the Unreleased body is merged here; the caller hands
+// the rest of the file to `git merge-file`, so a conflict elsewhere keeps git's
+// normal markers.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { gitError, git } from "../git/ops";
+import { workspaceChangelog } from "./workspaces";
+import { bulletBlocks, hasUnreleasedHeading, splitSections, splitUnreleased } from "./changelog";
+
+type Section = { heading: string; id: string; preamble: string[]; blocks: Map<string, string[]> };
+
+const headingId = (heading: string): string =>
+  heading
+    .replace(/\r?\n$/u, "")
+    .replace(/^###\s+/u, "")
+    .trim()
+    .toLowerCase();
+
+const withNewline = (line: string): string => (line.endsWith("\n") ? line : `${line}\n`);
+
+const parseBody = (body: string): { preamble: string[]; sections: Section[] } => {
+  const [preamble, raw] = splitSections(body);
+  const sections: Section[] = [];
+  for (const one of raw) {
+    const id = headingId(one.heading);
+    let section = sections.find((s) => s.id === id);
+    if (!section) {
+      section = { heading: one.heading, id, preamble: [], blocks: new Map() };
+      sections.push(section);
+    }
+    for (const [key, lines] of bulletBlocks(one.body)) {
+      const kept = lines.map(withNewline);
+      if (key === null) {
+        if (kept.some((line) => line.trim())) section.preamble.push(...kept);
+        continue;
+      }
+      while (kept.length > 1 && !kept[kept.length - 1].trim()) kept.pop();
+      if (!section.blocks.has(key)) section.blocks.set(key, kept);
+    }
+  }
+  return { preamble: preamble.map(withNewline), sections };
+};
+
+/** Ours, then theirs; a bullet one side dropped from base stays dropped. */
+const mergeBlocks = (
+  base: Map<string, string[]> | undefined,
+  ours: Map<string, string[]> | undefined,
+  theirs: Map<string, string[]> | undefined,
+): string[][] => {
+  const out = new Map<string, string[]>();
+  for (const [key, lines] of ours ?? []) {
+    if (base?.has(key) && theirs && !theirs.has(key)) continue;
+    out.set(key, lines);
+  }
+  for (const [key, lines] of theirs ?? []) {
+    if (out.has(key) || base?.has(key)) continue;
+    out.set(key, lines);
+  }
+  return [...out.values()];
+};
+
+/** The merged `## [Unreleased]` body (everything after that heading line). */
+export const mergeUnreleasedBody = (base: string, ours: string, theirs: string): string => {
+  if (ours === theirs || theirs === base) return ours;
+  if (ours === base) return theirs;
+  const b = parseBody(base);
+  const o = parseBody(ours);
+  const t = parseBody(theirs);
+  const ids = [...new Set([...o.sections, ...t.sections].map((s) => s.id))];
+  const sectionOf = (side: { sections: Section[] }, id: string) =>
+    side.sections.find((s) => s.id === id);
+  let out = o.preamble.join("") || t.preamble.join("");
+  for (const id of ids) {
+    const mine = sectionOf(o, id);
+    const theirsOne = sectionOf(t, id);
+    const baseOne = sectionOf(b, id);
+    const blocks = mergeBlocks(baseOne?.blocks, mine?.blocks, theirsOne?.blocks);
+    // A section both sides emptied (or one emptied that the other left alone) is dropped.
+    if (!blocks.length && baseOne && (!mine || !theirsOne)) continue;
+    const prose = (mine ?? theirsOne)?.preamble.join("") ?? "";
+    const heading = (mine ?? theirsOne)!.heading;
+    out += `${withNewline(heading)}\n${prose}${blocks.flat().join("")}\n`;
+  }
+  return out;
+};
+
+/**
+ * Replace each file's Unreleased body with the merged body, so only text
+ * outside Unreleased can still differ. null when a file has no Unreleased
+ * heading (the caller falls back to a plain three-way merge).
+ */
+export const withMergedUnreleased = (
+  base: string,
+  ours: string,
+  theirs: string,
+): { base: string; ours: string; theirs: string } | null => {
+  if (![base, ours, theirs].every(hasUnreleasedHeading)) return null;
+  const [bBefore, bBody, bAfter] = splitUnreleased(base);
+  const [oBefore, oBody, oAfter] = splitUnreleased(ours);
+  const [tBefore, tBody, tAfter] = splitUnreleased(theirs);
+  const merged = mergeUnreleasedBody(bBody, oBody, tBody);
+  return {
+    base: bBefore + merged + bAfter,
+    ours: oBefore + merged + oAfter,
+    theirs: tBefore + merged + tAfter,
+  };
+};
+
+export const CHANGELOG_DRIVER = "workit-changelog";
+/**
+ * Git runs the driver through sh. When `workit` cannot run (not on PATH: 127,
+ * an older CLI without the verb: 2), git would leave a conflicted file holding
+ * only ours with no markers, and a quick `git add` would drop theirs; falling
+ * back to `git merge-file` leaves normal markers instead. Exit 0 or 1 is the
+ * driver's own answer and is passed through untouched.
+ */
+export const CHANGELOG_DRIVER_COMMAND =
+  'workit changelog merge %O %A %B; s=$?; [ "$s" -le 1 ] && exit "$s"; git merge-file %A %O %B';
+
+/** The `.gitattributes` file `driver install` edits: the one at the work tree root. */
+export const gitattributesPath = (root: string): string => path.join(root, ".gitattributes");
+
+/**
+ * Merge the three files git hands a merge driver, writing the result over
+ * `ours`. Returns the exit code git expects: 0 clean, 1 conflict markers left.
+ */
+export const mergeChangelogFiles = (files: {
+  base: string;
+  ours: string;
+  theirs: string;
+}): { code: 0 | 1; error?: string } => {
+  const read = (file: string) => fs.readFileSync(file, "utf8");
+  const [base, ours, theirs] = [read(files.base), read(files.ours), read(files.theirs)];
+  const merged = withMergedUnreleased(base, ours, theirs) ?? { base, ours, theirs };
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "workit-changelog-merge-"));
+  try {
+    const one = (name: string, text: string) => {
+      const file = path.join(dir, name);
+      fs.writeFileSync(file, text, "utf8");
+      return file;
+    };
+    const o = one("ours", merged.ours);
+    const run = git(
+      dir,
+      [
+        "merge-file",
+        "-L",
+        "ours",
+        "-L",
+        "base",
+        "-L",
+        "theirs",
+        o,
+        one("base", merged.base),
+        one("theirs", merged.theirs),
+      ],
+      { timeoutMs: 30_000 },
+    );
+    if (run.status === null || run.status > 127) return { code: 1, error: gitError(run) };
+    fs.writeFileSync(files.ours, fs.readFileSync(o));
+    return { code: run.status === 0 ? 0 : 1 };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+};
+
+/**
+ * Register the driver in the repo's local git config and give the configured
+ * changelog paths a `merge=` attribute. Running it again changes nothing.
+ */
+export const installChangelogDriver = (
+  cwd: string,
+): { root: string; paths: string[]; attributes: string; changed: string[] } | { error: string } => {
+  const top = git(cwd, ["rev-parse", "--show-toplevel"]);
+  if (!top.ok) return { error: "not inside a git work tree" };
+  const root = fs.realpathSync(top.stdout.trim());
+  const changed: string[] = [];
+  const settings: Array<[string, string]> = [
+    [`merge.${CHANGELOG_DRIVER}.name`, "Workit changelog: keep both Unreleased entries"],
+    [`merge.${CHANGELOG_DRIVER}.driver`, CHANGELOG_DRIVER_COMMAND],
+  ];
+  for (const [key, value] of settings) {
+    const current = git(root, ["config", "--local", "--get", key]);
+    if (current.ok && current.stdout.trim() === value) continue;
+    const set = git(root, ["config", "--local", key, value]);
+    if (!set.ok) return { error: `git config ${key}: ${gitError(set)}` };
+    changed.push(`git config ${key}`);
+  }
+
+  const { paths } = workspaceChangelog(root);
+  const attributes = gitattributesPath(root);
+  const existing = fs.existsSync(attributes) ? fs.readFileSync(attributes, "utf8") : "";
+  const have = new Set(
+    existing
+      .split(/\r?\n/u)
+      .map((line) => line.trim().split(/\s+/u))
+      .filter((fields) => fields.slice(1).includes(`merge=${CHANGELOG_DRIVER}`))
+      .map((fields) => fields[0]),
+  );
+  const missing = paths.filter((one) => !have.has(one));
+  if (missing.length) {
+    const lead = existing && !existing.endsWith("\n") ? "\n" : "";
+    fs.writeFileSync(
+      attributes,
+      `${existing}${lead}${missing.map((one) => `${one} merge=${CHANGELOG_DRIVER}\n`).join("")}`,
+      "utf8",
+    );
+    changed.push(".gitattributes");
+  }
+  return { root, paths, attributes, changed };
+};