@sous-io/sous 0.1.1 → 0.2.1

package/src/lib/repos/release/bump.ts

@@ -0,0 +1,161 @@
+/**
+ * Raising, or setting, the version in a recipe manifest.
+ *
+ * A recipe manifest is HAND-WRITTEN, and the scaffold sous writes is mostly
+ * comments, so a version bump must give the file back to its author looking the
+ * way they left it. Both supported formats are edited in place rather than
+ * re-serialized from a parsed object: YAML through the `yaml` package's
+ * document model, which keeps comments and layout, and JSON through
+ * `jsonc-parser`, which edits the exact byte range of the value and leaves
+ * everything else, comments included, untouched.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import semver from "semver";
+import YAML from "yaml";
+import { applyEdits, modify } from "jsonc-parser";
+import { ConfigError } from "../../errors.js";
+import { parseJsoncText } from "../load-manifest.js";
+
+/** How far a version is being raised. */
+export const BUMP_LEVELS = ["patch", "minor", "major", "prerelease"] as const;
+
+/** One of the ways `sous repo release --bump` can raise a version. */
+export type BumpLevel = (typeof BUMP_LEVELS)[number];
+
+/** What one bump did. */
+export type BumpResult = {
+  /** The manifest that was rewritten. */
+  manifestPath: string;
+  /** The version it declared before. */
+  from: string;
+  /** The version it declares now. */
+  to: string;
+};
+
+/**
+ * The version one level up from the current one, using npm's own semantics.
+ *
+ * @param current - The version the manifest declares now.
+ * @param level - How far to raise it.
+ */
+export function nextVersion(current: string, level: BumpLevel): string {
+  const next = semver.inc(current, level);
+  if (next === null) {
+    throw new ConfigError(
+      `Cannot raise the version '${current}' by a ${level} step.\n` +
+        `  A recipe version is an exact semantic version, such as '1.4.0' or '2.0.0-beta.1'.`
+    );
+  }
+  return next;
+}
+
+/**
+ * Rewrites a recipe manifest's `version` field in place, preserving the rest of
+ * the file as written.
+ *
+ * @param manifestPath - Absolute path to the recipe manifest.
+ * @param level - How far to raise the version.
+ */
+export function bumpRecipeVersion(manifestPath: string, level: BumpLevel): BumpResult {
+  return rewriteVersion(manifestPath, (current) => nextVersion(current, level));
+}
+
+/**
+ * Writes an exact version into a recipe manifest, preserving the rest of the
+ * file as written.
+ *
+ * This is what the release pipeline uses to hold the packaged core recipe at
+ * the sous package's own version (see `scripts/sync-core-version.mts`), where
+ * the new version is dictated rather than stepped. A manifest that already
+ * declares this version is left untouched, byte for byte, so running the sync
+ * twice cannot reformat a hand-written file.
+ *
+ * @param manifestPath - Absolute path to the recipe manifest.
+ * @param version - The exact semantic version the manifest should declare.
+ */
+export function setRecipeVersion(manifestPath: string, version: string): BumpResult {
+  if (semver.valid(version) === null) {
+    throw new ConfigError(
+      `Cannot set the recipe version to '${version}'.\n` +
+        `  A recipe version is an exact semantic version, such as '1.4.0' or '2.0.0-beta.1'.`
+    );
+  }
+  return rewriteVersion(manifestPath, () => version);
+}
+
+/**
+ * The one writer both callers share: read the version the manifest declares,
+ * work out what it becomes, and rewrite that value alone.
+ *
+ * @param manifestPath - Absolute path to the recipe manifest.
+ * @param nextFrom - Given the declared version, the version to write.
+ */
+function rewriteVersion(
+  manifestPath: string,
+  nextFrom: (current: string) => string
+): BumpResult {
+  const text = fs.readFileSync(manifestPath, "utf8");
+  const extension = path.extname(manifestPath).toLowerCase();
+
+  if (extension === ".json" || extension === ".jsonc") {
+    return rewriteJson(manifestPath, text, nextFrom);
+  }
+  return rewriteYaml(manifestPath, text, nextFrom);
+}
+
+/** Rewrites the version in a YAML manifest, keeping its comments and layout. */
+function rewriteYaml(
+  manifestPath: string,
+  text: string,
+  nextFrom: (current: string) => string
+): BumpResult {
+  const document = YAML.parseDocument(text);
+  const node = document.get("version", true);
+
+  if (!YAML.isScalar(node) || typeof node.value !== "string") {
+    throw missingVersion(manifestPath);
+  }
+
+  const from = node.value;
+  const to = nextFrom(from);
+  if (to === from) return { manifestPath, from, to };
+
+  node.value = to;
+  fs.writeFileSync(manifestPath, document.toString(), "utf8");
+
+  return { manifestPath, from, to };
+}
+
+/** Rewrites the version in a JSON or JSONC manifest, editing only that value's bytes. */
+function rewriteJson(
+  manifestPath: string,
+  text: string,
+  nextFrom: (current: string) => string
+): BumpResult {
+  // The manifest dialect allows comments and trailing commas, so it is read
+  // through the loader's own permissive parser rather than JSON.parse.
+  const parsed = parseJsoncText(text, manifestPath);
+  const from =
+    typeof parsed === "object" && parsed !== null
+      ? (parsed as Record<string, unknown>).version
+      : undefined;
+  if (typeof from !== "string") throw missingVersion(manifestPath);
+
+  const to = nextFrom(from);
+  if (to === from) return { manifestPath, from, to };
+
+  const edits = modify(text, ["version"], to, {});
+  fs.writeFileSync(manifestPath, applyEdits(text, edits), "utf8");
+
+  return { manifestPath, from, to };
+}
+
+/** The error for a manifest with no usable `version` field. */
+function missingVersion(manifestPath: string): ConfigError {
+  return new ConfigError(
+    `The recipe manifest at ${manifestPath} has no 'version' field to write.\n` +
+      `  Every recipe declares an exact semantic version; add one, then try again.`
+  );
+}

package/src/lib/repos/release/git-state.ts

@@ -0,0 +1,305 @@
+/**
+ * What git says about the working tree a release or a submission is standing in.
+ *
+ * Both `sous repo release` and `sous repo submit` need the same handful of
+ * facts before they are allowed to do anything: is anything uncommitted, which
+ * branch is checked out, which branch is the default one, and where does
+ * `origin` point. A release makes exactly one commit of its own (its version
+ * bumps and its index, through `commitPaths`) and refuses while anything else
+ * is uncommitted; everything else here is read to refuse politely rather than
+ * to fix anything.
+ *
+ * Every function takes the injectable command runner, so tests never spawn git
+ * unless they mean to.
+ */
+
+import { runGit, type RunOptions } from "../providers/git.js";
+
+/** One path git reports as changed, with the two-letter status it reported. */
+export type ChangedPath = {
+  /** The status code from `git status --porcelain`, such as `M `, `??` or `A `. */
+  status: string;
+  /** The path, relative to the repository root. */
+  path: string;
+};
+
+/**
+ * Everything `git status --porcelain` reports: staged changes, unstaged changes
+ * and untracked files alike. An empty list means the working tree is clean.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param options - The command runner to use.
+ */
+export async function uncommittedChanges(
+  rootDir: string,
+  options: RunOptions = {}
+): Promise<ChangedPath[]> {
+  const output = await runGit(["status", "--porcelain"], {
+    cwd: rootDir,
+    run: options.run,
+  });
+  if (output.length === 0) return [];
+
+  const changed: ChangedPath[] = [];
+  for (const line of output.split("\n")) {
+    // The status field is one or two characters, and the command runner trims
+    // its output, so a leading space (an unstaged edit) is already gone by the
+    // time the line arrives here. Split on the whitespace instead of counting
+    // columns. A rename is reported as 'old -> new'; the new name is the one
+    // that still exists, so that is the one reported.
+    const match = /^(\S{1,2})\s+(.*)$/.exec(line.trim());
+    if (match === null) continue;
+    const target = match[2]!;
+    const arrow = target.indexOf(" -> ");
+    changed.push({
+      status: match[1]!,
+      path: arrow === -1 ? target : target.slice(arrow + 4),
+    });
+  }
+  return changed;
+}
+
+/**
+ * The name of the checked-out branch, or undefined when HEAD is detached (which
+ * is what a CI checkout of a tag looks like).
+ *
+ * @param rootDir - The repository's root directory.
+ * @param options - The command runner to use.
+ */
+export async function currentBranch(
+  rootDir: string,
+  options: RunOptions = {}
+): Promise<string | undefined> {
+  try {
+    const name = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd: rootDir,
+      run: options.run,
+    });
+    return name === "HEAD" ? undefined : name;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The repository's default branch, taken from what `origin/HEAD` points at.
+ * Returns undefined when the remote never told this clone, which is normal for
+ * a repository cloned with `--depth 1` or created locally.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param options - The command runner to use.
+ */
+export async function defaultBranch(
+  rootDir: string,
+  options: RunOptions = {}
+): Promise<string | undefined> {
+  try {
+    const ref = await runGit(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], {
+      cwd: rootDir,
+      run: options.run,
+    });
+    const slash = ref.indexOf("/");
+    return slash === -1 ? ref : ref.slice(slash + 1);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The URL of a remote, or undefined when the repository has no such remote.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param remote - The remote's name, normally `origin`.
+ * @param options - The command runner to use.
+ */
+export async function remoteUrl(
+  rootDir: string,
+  remote: string,
+  options: RunOptions = {}
+): Promise<string | undefined> {
+  try {
+    const url = await runGit(["remote", "get-url", remote], {
+      cwd: rootDir,
+      run: options.run,
+    });
+    return url.length > 0 ? url : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * True when a path is tracked by git and identical to what HEAD holds. It is how
+ * a caller confirms that a file it is about to act on is the one the repository
+ * actually committed.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param relativePath - The path to check, relative to the repository root.
+ * @param options - The command runner to use.
+ */
+export async function isCommittedAndUnchanged(
+  rootDir: string,
+  relativePath: string,
+  options: RunOptions = {}
+): Promise<boolean> {
+  const tracked = await runGit(["ls-files", "--", relativePath], {
+    cwd: rootDir,
+    run: options.run,
+  });
+  if (tracked.length === 0) return false;
+
+  const changed = await runGit(["status", "--porcelain", "--", relativePath], {
+    cwd: rootDir,
+    run: options.run,
+  });
+  return changed.length === 0;
+}
+
+/**
+ * True when git can work out who is committing, which is what it needs before
+ * it will make a commit or an annotated tag.
+ *
+ * `git var GIT_AUTHOR_IDENT` answers the exact question git asks itself: it
+ * honours the `user.name` and `user.email` settings, the `GIT_AUTHOR_*` and
+ * `GIT_COMMITTER_*` environment variables, and the strict rules that reject a
+ * guessed identity. It fails with the same "empty ident name" or "unable to
+ * auto-detect email address" that a commit would have failed with, which is
+ * why the check is made ahead of time rather than left to the commit.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param options - The command runner to use.
+ */
+export async function hasCommitIdentity(
+  rootDir: string,
+  options: RunOptions = {}
+): Promise<boolean> {
+  for (const name of ["GIT_AUTHOR_IDENT", "GIT_COMMITTER_IDENT"]) {
+    try {
+      const ident = await runGit(["var", name], { cwd: rootDir, run: options.run });
+      if (ident.length === 0) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Stages exactly the given paths and commits them.
+ *
+ * This is the one place sous commits on an author's behalf, and it is
+ * deliberately narrow: a release writes version bumps and an index, and those
+ * are the only paths it stages. Anything else in the working tree is left
+ * exactly as it was.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param paths - The paths to stage, relative to the repository root.
+ * @param message - The commit message.
+ * @param options - The command runner to use.
+ */
+export async function commitPaths(
+  rootDir: string,
+  paths: ReadonlyArray<string>,
+  message: string,
+  options: RunOptions = {}
+): Promise<void> {
+  if (paths.length === 0) return;
+  await runGit(["add", "--", ...paths], { cwd: rootDir, run: options.run });
+  await runGit(["commit", "--message", message, "--", ...paths], {
+    cwd: rootDir,
+    run: options.run,
+  });
+}
+
+/**
+ * True when any of the given paths differs from what HEAD holds, so a release
+ * knows whether it has anything to commit.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param paths - The paths to check, relative to the repository root.
+ * @param options - The command runner to use.
+ */
+export async function anythingToCommit(
+  rootDir: string,
+  paths: ReadonlyArray<string>,
+  options: RunOptions = {}
+): Promise<boolean> {
+  if (paths.length === 0) return false;
+  const changed = await runGit(["status", "--porcelain", "--", ...paths], {
+    cwd: rootDir,
+    run: options.run,
+  });
+  return changed.length > 0;
+}
+
+/**
+ * Creates a branch at HEAD and checks it out.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param branch - The branch to create.
+ * @param options - The command runner to use.
+ */
+export async function createBranch(
+  rootDir: string,
+  branch: string,
+  options: RunOptions = {}
+): Promise<void> {
+  await runGit(["checkout", "-b", branch], { cwd: rootDir, run: options.run });
+}
+
+/**
+ * Pushes one branch to a remote, setting it as the branch's upstream.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param remote - The remote to push to.
+ * @param branch - The branch to push.
+ * @param options - The command runner to use.
+ */
+export async function pushBranch(
+  rootDir: string,
+  remote: string,
+  branch: string,
+  options: RunOptions = {}
+): Promise<void> {
+  await runGit(["push", "--set-upstream", remote, branch], {
+    cwd: rootDir,
+    run: options.run,
+  });
+}
+
+/**
+ * The subject line of the most recent commit, or undefined when there is none.
+ * It is the default title for a proposed change, which is what a contributor
+ * would have typed anyway.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param options - The command runner to use.
+ */
+export async function lastCommitSubject(
+  rootDir: string,
+  options: RunOptions = {}
+): Promise<string | undefined> {
+  try {
+    const subject = await runGit(["log", "-1", "--format=%s"], {
+      cwd: rootDir,
+      run: options.run,
+    });
+    return subject.length > 0 ? subject : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The branch name sous proposes for a submission, stamped with the minute it
+ * was made so two submissions from one checkout never collide.
+ *
+ * @param now - The moment the branch is being created.
+ */
+export function submitBranchName(now: Date): string {
+  const pad = (value: number) => String(value).padStart(2, "0");
+  const stamp =
+    `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}` +
+    `-${pad(now.getHours())}${pad(now.getMinutes())}`;
+  return `sous/submit-${stamp}`;
+}