@sous-io/sous 0.2.37 → 1.0.2

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

@@ -1,214 +0,0 @@
-/**
- * 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

@@ -1,290 +0,0 @@
-/**
- * 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/services/ref-resolver/`, 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 {
-  CatalogLookup,
-  RefPickArguments,
-  RefResolveArguments,
-  locationFromUrl,
-  repoOf,
-  sharedRefPicker,
-  sharedRefResolver,
-  type CatalogRepo,
-} from "../../../services/ref-resolver/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 { refs } = await sharedRefResolver().resolve(
-    new RefResolveArguments({
-      input: options.repo,
-      lookup: new CatalogLookup(reference),
-      kinds: ["repo"],
-      refusedIsEmpty: true,
-    })
-  );
-  const match = await sharedRefPicker().pick(
-    refs,
-    new RefPickArguments({
-      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 = repoOf(match)!.name!;
-
-  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 }>
-): CatalogRepo[] {
-  const known = (name: string, url: string): CatalogRepo => {
-    const location = locationFromUrl(url);
-    return { name, ...(location === undefined ? {} : { location }), namespaces: [], recipes: [] };
-  };
-  const repos: CatalogRepo[] = Object.entries(project.repos).map(([name, entry]) =>
-    known(name, entry.url)
-  );
-  for (const name of Object.keys(links).sort()) {
-    if (project.repos[name] === undefined) repos.push(known(name, links[name]!.path));
-  }
-  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

@@ -1,153 +0,0 @@
-/**
- * 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),
-};