@sous-io/sous 0.2.16 → 0.2.18

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

@@ -0,0 +1,214 @@
+/**
+ * Which recipes take proposed changes, and which paths a change touches.
+ *
+ * A repository says which of its recipes do not take proposals with a
+ * `submissions` block, on its repo manifest (covering every recipe) or on a
+ * recipe manifest (covering that recipe, and winning over the repository's).
+ * The motivating case is a recipe whose files are copied in from somewhere
+ * else: a merged edit to the copy is overwritten by the next copy, and a
+ * version it tagged can collide with the one the real source publishes.
+ *
+ * Two commands read it, with different strengths. `sous repo submit` warns,
+ * prints where to go instead, and proposes anyway if the contributor carries
+ * on: informed consent, not prevention. `sous repo release --check` fails a
+ * pull request that changes such a recipe, because a pull request can be opened
+ * without `submit`, and the check is the one gate every change passes.
+ *
+ * Nothing here decides a comparison base; the callers hand in the paths a
+ * change touched, as git reported them.
+ */
+
+import path from "node:path";
+import semver from "semver";
+import { runGit, type RunOptions } from "../providers/git.js";
+import { defaultBranch, forkPoint, pathsChangedSince } from "./git-state.js";
+import { listRecipeTags, recipeTagKey } from "./tags.js";
+import type { RepoValidation, ValidatedRecipe } from "./validate.js";
+
+/** Whether one recipe takes proposals, and which manifest said so. */
+export type SubmissionPolicy = {
+  /** True when proposed changes to the recipe are accepted. */
+  allowed: boolean;
+  /** Where to send a change instead, when the manifest says. */
+  instead?: string;
+  /** Which manifest decided: the recipe's own, the repository's, or neither. */
+  declaredBy: "recipe" | "repository" | "default";
+};
+
+/** A recipe a change touches although it does not take proposals. */
+export type RefusingRecipe = {
+  /** The recipe key, `namespace/name`. */
+  key: string;
+  /** The recipe folder, relative to the repository root. */
+  path: string;
+  /** Where to send the change instead, when the manifest says. */
+  instead?: string;
+  /** Which manifest said the recipe takes no proposals. */
+  declaredBy: "recipe" | "repository";
+  /** The changed paths inside the recipe folder, relative to the repository root. */
+  changed: string[];
+};
+
+/**
+ * Whether one recipe takes proposals. A recipe's own block wins over the
+ * repository's; with neither, it does.
+ *
+ * submissionPolicy(validation, recipe);
+ * // -> { allowed: false, instead: "Propose it upstream.", declaredBy: "recipe" }
+ *
+ * @param validation - The validated repository.
+ * @param recipe - One of its recipes.
+ */
+export function submissionPolicy(
+  validation: RepoValidation,
+  recipe: ValidatedRecipe
+): SubmissionPolicy {
+  const own = recipe.manifest.submissions;
+  if (own !== undefined) {
+    return {
+      allowed: own.allowed,
+      ...(own.instead === undefined ? {} : { instead: own.instead }),
+      declaredBy: "recipe",
+    };
+  }
+  const repo = validation.manifest.submissions;
+  if (repo !== undefined) {
+    return {
+      allowed: repo.allowed,
+      ...(repo.instead === undefined ? {} : { instead: repo.instead }),
+      declaredBy: "repository",
+    };
+  }
+  return { allowed: true, declaredBy: "default" };
+}
+
+/**
+ * The recipes a change touches that do not take proposals, in the order the
+ * repo manifest lists them. A path is inside a recipe when it lies under the
+ * recipe folder.
+ *
+ * recipesRefusingSubmissions(validation, ["recipes/core/x/a.md"]);
+ * // -> [{ key: "core/x", path: "recipes/core/x", changed: ["recipes/core/x/a.md"], ... }]
+ *
+ * @param validation - The validated repository.
+ * @param changedPaths - The paths the change touched, relative to the repository root.
+ */
+export function recipesRefusingSubmissions(
+  validation: RepoValidation,
+  changedPaths: ReadonlyArray<string>
+): RefusingRecipe[] {
+  const refusing: RefusingRecipe[] = [];
+  for (const recipe of validation.recipes) {
+    const policy = submissionPolicy(validation, recipe);
+    if (policy.allowed || policy.declaredBy === "default") continue;
+
+    const changed = pathsInside(recipe.path, changedPaths);
+    if (changed.length === 0) continue;
+
+    refusing.push({
+      key: recipe.key,
+      path: toPosix(recipe.path),
+      ...(policy.instead === undefined ? {} : { instead: policy.instead }),
+      declaredBy: policy.declaredBy,
+      changed,
+    });
+  }
+  return refusing;
+}
+
+/**
+ * The paths from a list that lie inside a folder, both relative to the
+ * repository root.
+ *
+ * pathsInside("recipes/core/x", ["recipes/core/x/a.md", "recipes/core/xy/b.md"]);
+ * // -> ["recipes/core/x/a.md"]
+ *
+ * @param folder - The folder, relative to the repository root.
+ * @param paths - The paths to test, relative to the repository root.
+ */
+export function pathsInside(folder: string, paths: ReadonlyArray<string>): string[] {
+  const base = toPosix(path.posix.normalize(toPosix(folder))).replace(/\/+$/, "");
+  return paths
+    .map(toPosix)
+    .filter((entry) => base === "." || entry === base || entry.startsWith(`${base}/`));
+}
+
+/** What the pull request check found about recipes that take no proposals. */
+export type SubmissionsCheck = {
+  /** The recipes the change touches although they take no proposals. */
+  refusing: RefusingRecipe[];
+  /**
+   * What the change was compared with: the default branch it will merge into,
+   * each recipe's last release tag when the checkout holds no copy of that
+   * branch, or nothing at all when neither was there to compare with. `none
+   * declined` means no recipe declines proposals, so there was nothing to check.
+   */
+  comparedWith:
+    | { kind: "branch"; branch: string }
+    | { kind: "tags" }
+    | { kind: "nothing" }
+    | { kind: "none declined" };
+};
+
+/**
+ * The check `sous repo release --check` makes for a pull request: which recipes
+ * that take no proposals the change touches.
+ *
+ * The change is what the checked-out commit holds beyond the point it shares
+ * with the default branch on `origin`, which is exactly what a pull request
+ * proposes. A checkout with no copy of that branch is compared recipe by recipe
+ * with each one's last release tag instead: on the default branch a recipe
+ * always equals its last tag, so a difference is a change nobody released.
+ * A recipe that was never tagged has nothing to compare with and is left out.
+ *
+ * @param validation - The validated repository.
+ * @param options - The command runner to use.
+ */
+export async function checkSubmissions(
+  validation: RepoValidation,
+  options: RunOptions = {}
+): Promise<SubmissionsCheck> {
+  const { rootDir } = validation;
+  const guarded = validation.recipes.filter((recipe) => {
+    const policy = submissionPolicy(validation, recipe);
+    return !policy.allowed && policy.declaredBy !== "default";
+  });
+  if (guarded.length === 0) return { refusing: [], comparedWith: { kind: "none declined" } };
+
+  const branch = (await defaultBranch(rootDir, options)) ?? "main";
+  const since = await forkPoint(rootDir, "origin", branch, options);
+  if (since !== undefined) {
+    const changed = await pathsChangedSince(rootDir, since, options);
+    return {
+      refusing: recipesRefusingSubmissions(validation, changed),
+      comparedWith: { kind: "branch", branch },
+    };
+  }
+
+  const tags = await listRecipeTags(rootDir, options);
+  const changed: string[] = [];
+  let comparedAny = false;
+  for (const recipe of guarded) {
+    const versions = tags
+      .filter((tag) => recipeTagKey(tag) === recipe.key && semver.valid(tag.version) !== null)
+      .sort((left, right) => semver.rcompare(left.version, right.version));
+    const last = versions[0];
+    if (last === undefined) continue;
+    comparedAny = true;
+    const diff = await runGit(
+      ["diff", "--name-only", last.tag, "HEAD", "--", toPosix(recipe.path)],
+      { cwd: rootDir, run: options.run }
+    );
+    if (diff.length > 0) changed.push(...diff.split("\n").filter((line) => line.length > 0));
+  }
+
+  return {
+    refusing: recipesRefusingSubmissions(validation, changed),
+    comparedWith: comparedAny ? { kind: "tags" } : { kind: "nothing" },
+  };
+}
+
+/** Rewrites a path with forward slashes, which is how git reports them. */
+function toPosix(value: string): string {
+  return value.split(path.sep).join("/");
+}

package/src/lib/repos/release/submit-checkout.ts

@@ -0,0 +1,271 @@
+/**
+ * Which working copy `sous repo submit` proposes from.
+ *
+ * Inside a recipe repository with no argument, it is that repository, as it
+ * always was. Inside a project, the argument names a repository the project
+ * knows (resolved through `src/lib/refs/`, like every reference), and the
+ * submission runs in that repository's checkout:
+ *
+ *   - a linked repository is read from the checkout its link points at;
+ *   - a repository no longer linked, whose checkout sous cloned is still where
+ *     `sous repo link` puts one, is submitted from that checkout, with a note
+ *     saying it is not linked here;
+ *   - a repository with no checkout at all cannot be submitted from, and the
+ *     error says there is no working copy to propose from.
+ *
+ * With no argument inside a project, exactly one linked repository is used and
+ * named; several are a question, which a run with no terminal cannot ask.
+ *
+ * Nothing here writes anything. It reads the links maps and looks at the disk.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError } from "../../errors.js";
+import { nonInteractiveError } from "../../interactive.js";
+import { findRepository, pickReference, type ReferenceRepo } from "../../refs/index.js";
+import type { RepoEntry } from "../../settings.js";
+import { isGitCheckout, remoteUrlOf, repoSlugFromUrl, sameRemote } from "../git-clone.js";
+import { globalReposDir, projectReposDir, readEffectiveLinks } from "../links.js";
+import { askChoice } from "../../../utils/prompts.js";
+import { findRepoRoot } from "./validate.js";
+
+/** The project a submission may be run from, when one was found. */
+export type SubmitProject = {
+  /** The project's discovered `.sous/` directory. */
+  sousDir: string;
+  /** The repositories the project uses, keyed by short name. */
+  repos: Record<string, RepoEntry>;
+};
+
+/** What `findSubmitCheckout` needs to know. */
+export type FindSubmitCheckoutOptions = {
+  /** The working directory the command was run from. */
+  cwd: string;
+  /** The repository the command line named, when it named one. */
+  repo?: string;
+  /** The project around the working directory, when there is one. */
+  project?: SubmitProject;
+  /** Whether a question may be asked. */
+  interactive: boolean;
+  /** The environment, for the machine-wide links map and checkouts. */
+  env?: NodeJS.ProcessEnv;
+  /** How a choice between several linked repositories is asked. */
+  choose?: (message: string, names: string[]) => Promise<string>;
+  /** Where the facts about a resolved reference are written. */
+  write?: (message: string) => void;
+};
+
+/** The working copy a submission runs in, and how it was chosen. */
+export type SubmitCheckout = {
+  /** The checkout's root directory. */
+  rootDir: string;
+  /** The project's short name for the repository, when a project named it. */
+  repo?: string;
+  /** How the checkout was found, in one sentence, ready to print. */
+  reason: string;
+  /** Anything else worth saying about it, such as a checkout that is no longer linked. */
+  notes: string[];
+};
+
+/**
+ * Works out which checkout a submission runs in.
+ *
+ * @param options - The working directory, the argument, the project and the testing seams.
+ */
+export async function findSubmitCheckout(
+  options: FindSubmitCheckoutOptions
+): Promise<SubmitCheckout> {
+  const { cwd, project } = options;
+  const env = options.env ?? process.env;
+
+  if (options.repo === undefined) {
+    const inside = recipeRepoAround(cwd);
+    if (inside !== undefined) {
+      return { rootDir: inside, reason: "The working directory is inside it.", notes: [] };
+    }
+    if (project === undefined) {
+      // Neither a recipe repository nor a project: the recipe repository error
+      // is the one that says what to do.
+      findRepoRoot(cwd);
+    }
+    return chooseLinked(project!, env, options);
+  }
+
+  if (project === undefined) {
+    throw new ConfigError(
+      `'${options.repo}' names a repository a project uses, but ${path.resolve(cwd)} is not ` +
+        `inside a sous project.\n` +
+        `  Run the command from inside the project that links the repository, or from inside ` +
+        `the repository's own checkout with no argument.`
+    );
+  }
+
+  const links = readEffectiveLinks(project.sousDir, env);
+  const reference = referenceRepos(project, links);
+  const match = await pickReference(findRepository(options.repo, { repos: reference }), {
+    search: options.repo,
+    interactive: options.interactive,
+    ...(options.write === undefined ? {} : { write: options.write }),
+    details: [
+      reference.length === 0
+        ? "  This project uses no repositories."
+        : `  This project uses: ${reference.map((entry) => entry.name).join(", ")}.`,
+    ],
+  });
+  const name = match.repo ?? match.key;
+
+  const link = links[name];
+  if (link !== undefined) {
+    if (!fs.existsSync(link.path)) {
+      throw noWorkingCopy(name, `Its link points at ${link.path}, which does not exist.`);
+    }
+    return {
+      rootDir: link.path,
+      repo: name,
+      reason: `'${name}' is linked to this checkout.`,
+      notes: [],
+    };
+  }
+
+  const leftover = leftoverCheckout(name, project, env);
+  if (leftover !== undefined) {
+    return {
+      rootDir: leftover,
+      repo: name,
+      reason: `Sous cloned '${name}' into this checkout earlier.`,
+      notes: [
+        `'${name}' is not linked in this project, so builds read its published versions; ` +
+          `the checkout sous cloned for it is still at ${leftover}, and the change is ` +
+          `proposed from there.`,
+      ],
+    };
+  }
+
+  throw noWorkingCopy(
+    name,
+    `It is not linked in this project, and no checkout of it is where 'sous repo link' ` +
+      `clones one.`
+  );
+}
+
+/** The recipe repository around a directory, or undefined when there is none. */
+function recipeRepoAround(cwd: string): string | undefined {
+  try {
+    return findRepoRoot(cwd);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * With no argument inside a project: the one linked repository, or a choice
+ * between several.
+ */
+async function chooseLinked(
+  project: SubmitProject,
+  env: NodeJS.ProcessEnv,
+  options: FindSubmitCheckoutOptions
+): Promise<SubmitCheckout> {
+  const links = readEffectiveLinks(project.sousDir, env);
+  const names = Object.keys(links).sort();
+
+  if (names.length === 0) {
+    throw new ConfigError(
+      "This project links no repository, so there is no working copy to propose from.\n" +
+        "  Link one with 'sous repo link <repo>', make your change in its checkout, then run " +
+        "'sous repo submit <repo>'."
+    );
+  }
+
+  let name: string;
+  let reason: string;
+  if (names.length === 1) {
+    name = names[0]!;
+    reason = `It is the only repository this project links.`;
+  } else {
+    if (!options.interactive) {
+      throw nonInteractiveError({
+        prompt: "which linked repository to propose a change from",
+        remedy: `name it as the argument, as in 'sous repo submit ${names[0]}'.`,
+        details: [`This project links ${names.join(", ")}.`],
+      });
+    }
+    const choose =
+      options.choose ??
+      ((message: string, offered: string[]) =>
+        askChoice(
+          message,
+          offered.map((entry) => ({ name: `${entry}  ${links[entry]!.path}`, value: entry }))
+        ));
+    name = await choose("Which linked repository should the change be proposed from?", names);
+    reason = "You chose it.";
+  }
+
+  const link = links[name]!;
+  if (!fs.existsSync(link.path)) {
+    throw noWorkingCopy(name, `Its link points at ${link.path}, which does not exist.`);
+  }
+  return { rootDir: link.path, repo: name, reason, notes: [] };
+}
+
+/**
+ * The repositories a reference may name here: every one the project uses, and
+ * any linked name the config does not list, so a link is never unreachable.
+ */
+function referenceRepos(
+  project: SubmitProject,
+  links: Record<string, { path: string }>
+): ReferenceRepo[] {
+  const repos: ReferenceRepo[] = Object.entries(project.repos).map(([name, entry]) => ({
+    name,
+    url: entry.url,
+    namespaces: [],
+    recipes: [],
+  }));
+  for (const name of Object.keys(links).sort()) {
+    if (project.repos[name] === undefined) {
+      repos.push({ name, url: links[name]!.path, namespaces: [], recipes: [] });
+    }
+  }
+  return repos;
+}
+
+/**
+ * A checkout sous cloned for a repository that is no longer linked: the
+ * project's own clone first, then the machine-wide one, each only when it is a
+ * checkout of that same repository.
+ */
+function leftoverCheckout(
+  name: string,
+  project: SubmitProject,
+  env: NodeJS.ProcessEnv
+): string | undefined {
+  const url = project.repos[name]?.url;
+  if (url === undefined) return undefined;
+
+  let slug: { owner: string; name: string };
+  try {
+    slug = repoSlugFromUrl(url);
+  } catch {
+    return undefined;
+  }
+
+  for (const base of [projectReposDir(project.sousDir), globalReposDir(env)]) {
+    const directory = path.join(base, slug.owner, slug.name);
+    if (!isGitCheckout(directory)) continue;
+    const remote = remoteUrlOf(directory);
+    if (remote !== undefined && sameRemote(remote, url)) return directory;
+  }
+  return undefined;
+}
+
+/** The error for a repository with no working copy to propose from. */
+function noWorkingCopy(name: string, why: string): ConfigError {
+  return new ConfigError(
+    `There is no working copy of '${name}' to propose a change from.\n` +
+      `  ${why}\n` +
+      `  Link it with 'sous repo link ${name}', make your change in its checkout, then run ` +
+      `the command again.`
+  );
+}

package/src/lib/repos/release/submit-questions.ts

@@ -0,0 +1,153 @@
+/**
+ * How `sous repo submit` asks its questions.
+ *
+ * The sequencer (`submit-service.ts`) never prompts; it calls a
+ * `SubmitQuestions` and carries on with the answer. This module builds that
+ * object from the two facts a command knows: whether a question may be asked
+ * at all (`src/lib/interactive.ts` decides), and whether the shared
+ * confirmation flag already answered every yes-or-no question.
+ *
+ * A question nobody can ask raises the error that names the flag answering it,
+ * so a script learns what to pass rather than hanging on a prompt it cannot see:
+ * the title and description name `--title` and `--body` together, and every
+ * confirmation names `--yes`.
+ */
+
+import { editor } from "@inquirer/prompts";
+import { nonInteractiveError } from "../../interactive.js";
+import { blankLines, keysHelpTip, log } from "../../../utils/formatting.js";
+import { askChoice, askYesNo } from "../../../utils/prompts.js";
+import { valuePrompt } from "../../../utils/value-prompt.js";
+import type { ProposalSummary } from "../providers/provider.js";
+import type { ChangedPath } from "./git-state.js";
+import type { NextBranchChoice, SubmitQuestions } from "./submit-service.js";
+
+/** The prompts the questions are asked with; each one is replaceable in a test. */
+export type SubmitPrompts = {
+  /** Asks for one line of text, with an editor behind Tab for a longer answer. */
+  text(message: string): Promise<string>;
+  /** Asks a yes-or-no question. */
+  confirm(message: string): Promise<boolean>;
+  /** Asks the contributor to pick one of several choices. */
+  choose<T>(message: string, choices: Array<{ name: string; value: T }>): Promise<T>;
+};
+
+/** What `submitQuestions` needs to know. */
+export type SubmitQuestionOptions = {
+  /** Whether a question may be asked. */
+  interactive: boolean;
+  /** True when the confirmation flag answered every yes-or-no question already. */
+  yes: boolean;
+  /** How the questions are put. Defaults to the shared terminal prompts. */
+  prompts?: SubmitPrompts;
+  /** Where a list shown before a question is written. Defaults to the console. */
+  write?: (line: string) => void;
+};
+
+/** The flag spellings every confirmation's remedy names. */
+const YES_REMEDY = "pass '--yes' (spelled '-y' or '--force' if you prefer)";
+
+/** The remedy for a missing title or description, naming both flags. */
+const TEXT_REMEDY =
+  "pass '--title' and '--body'. A new proposal, and a commit sous makes for you, both need " +
+  "a title and a description written by you.";
+
+/**
+ * Builds the questions a submission asks, bound to this run's terminal and
+ * flags.
+ *
+ * @param options - Whether asking is possible, whether `--yes` was passed, and the prompts.
+ */
+export function submitQuestions(options: SubmitQuestionOptions): SubmitQuestions {
+  const prompts = options.prompts ?? terminalPrompts;
+  const write = options.write ?? log;
+  const { interactive, yes } = options;
+
+  const askText = async (message: string): Promise<string> => {
+    if (!interactive) {
+      throw nonInteractiveError({
+        prompt: "for the proposal's title and description",
+        remedy: TEXT_REMEDY,
+      });
+    }
+    return prompts.text(message);
+  };
+
+  return {
+    title: () => askText("What is the title of this proposal?"),
+    body: () => askText("Describe the change: what it does, and why."),
+
+    async confirmCommit(paths: ReadonlyArray<ChangedPath>): Promise<boolean> {
+      if (yes) return true;
+      write("  These paths are uncommitted, and '--commit' would commit all of them:");
+      for (const entry of paths) write(`    ${entry.path}`);
+      if (!interactive) {
+        throw nonInteractiveError({
+          prompt: "whether to commit the paths listed above",
+          remedy: `${YES_REMEDY} to commit them without being asked.`,
+        });
+      }
+      return prompts.confirm("Commit these paths?");
+    },
+
+    async proceedDespiteSubmissions(): Promise<boolean> {
+      if (yes) return true;
+      if (!interactive) {
+        throw nonInteractiveError({
+          prompt: "whether to propose a change to recipes that do not take proposals",
+          remedy: `${YES_REMEDY} to propose it anyway.`,
+        });
+      }
+      return prompts.confirm("Propose the change anyway?");
+    },
+
+    async nextBranch(merged: ProposalSummary, generated: string): Promise<NextBranchChoice> {
+      if (yes) return { kind: "generate" };
+      if (!interactive) {
+        throw nonInteractiveError({
+          prompt: "which new branch to continue on, now the proposal was merged",
+          remedy: `${YES_REMEDY} to continue on a branch sous names for you.`,
+          details: [`The merged proposal was '${merged.title}'.`],
+        });
+      }
+      const picked = await prompts.choose<"name" | "generate" | "cancel">(
+        "Continue on a new branch?",
+        [
+          { name: `Generate one: ${generated}`, value: "generate" },
+          { name: "Name the branch myself", value: "name" },
+          { name: "Cancel", value: "cancel" },
+        ]
+      );
+      if (picked !== "name") return { kind: picked };
+      const name = (await prompts.text("What should the new branch be called?")).trim();
+      return name.length === 0 ? { kind: "generate" } : { kind: "name", name };
+    },
+  };
+}
+
+/**
+ * The prompts a real terminal gets. A text question answers on Enter; Tab
+ * opens the contributor's editor instead, which is where a description longer
+ * than one line is written.
+ */
+const terminalPrompts: SubmitPrompts = {
+  async text(message: string): Promise<string> {
+    blankLines(2);
+    for (;;) {
+      const answered = await valuePrompt({
+        message,
+        hint: keysHelpTip([
+          ["⏎", "answer"],
+          ["⇥", "advanced"],
+        ]),
+        validate: (value) => (value.trim().length > 0 ? true : "An answer is required."),
+      });
+      if (answered.kind === "value") return answered.value;
+      const written = await editor({ message, waitForUserInput: false });
+      if (written.trim().length > 0) return written;
+    }
+  },
+  confirm: (message: string) => askYesNo(message),
+  choose: <T>(message: string, choices: Array<{ name: string; value: T }>) =>
+    askChoice(message, choices),
+};