@sous-io/sous 0.2.29 → 0.2.31

package/src/lib/self-update/versions.ts

@@ -0,0 +1,243 @@
+/**
+ * Which version of sous an update moves an install to.
+ *
+ * Everything here is pure: it reads the registry's answer (the abbreviated
+ * package document) and the version an install holds, and decides. Nothing is
+ * fetched or installed, so a dry run and a real run choose exactly alike.
+ */
+
+import semver from "semver";
+import { z } from "zod";
+import { ConfigError } from "../errors.js";
+
+/** What the registry publishes for the package, reduced to what a choice needs. */
+export type RegistryMetadata = {
+  /** The package name the registry answered for. */
+  name: string;
+  /** Every published version that is valid semver, newest first. */
+  versions: string[];
+  /** Each dist-tag (`latest`, `next`) and the version it points at. */
+  distTags: Record<string, string>;
+};
+
+/**
+ * What the person asked for.
+ *
+ * - `default`: the newest version in the installed major.
+ * - `major`: the newest version, whatever its major.
+ * - `spec`: an exact version, a dist-tag name, or a semver range.
+ */
+export type VersionRequest =
+  | { kind: "default" }
+  | { kind: "major" }
+  | { kind: "spec"; spec: string };
+
+/** How the chosen version relates to the installed one. */
+export type VersionDirection = "upgrade" | "downgrade" | "current";
+
+/** The version an install moves to, and how the choice was read. */
+export type VersionChoice = {
+  /** The version to install; equal to the installed version when `direction` is `current`. */
+  target: string;
+  direction: VersionDirection;
+  /** Whether prerelease versions counted as candidates, after the default was applied. */
+  prerelease: boolean;
+  /**
+   * How a `spec` request was read: an exact version, a dist-tag or a range.
+   * Undefined for the other requests.
+   */
+  specKind?: "version" | "dist-tag" | "range";
+};
+
+/** Input to `chooseVersion`. */
+export type ChooseVersionInput = {
+  /** The version the install holds now. */
+  current: string;
+  /** Every published version (any order; invalid entries are ignored). */
+  versions: readonly string[];
+  /** The registry's dist-tags. */
+  distTags: Readonly<Record<string, string>>;
+  request: VersionRequest;
+  /**
+   * Whether prerelease versions count as candidates. Undefined means "on when
+   * the installed version is itself a prerelease".
+   */
+  prerelease?: boolean;
+};
+
+/** How many of the newest versions an error lists. */
+const NEWEST_LISTED = 5;
+
+/**
+ * The abbreviated package document, as far as sous reads it. Every other field
+ * the registry sends is kept and ignored, so a registry that adds one breaks
+ * nothing.
+ */
+const abbreviatedDocumentSchema = z.looseObject({
+  name: z.string(),
+  "dist-tags": z.record(z.string(), z.string()).default({}),
+  versions: z.record(z.string(), z.unknown()),
+});
+
+/**
+ * Reads the registry's abbreviated package document (the answer to a request
+ * sent with `Accept: application/vnd.npm.install-v1+json`).
+ *
+ * Keys of `versions` that are not valid semver are dropped, and so is a
+ * dist-tag that points at one. A body that is not JSON, or lacks `name` or
+ * `versions`, is a ConfigError naming `source`.
+ *
+ * @param text - The response body.
+ * @param source - Where the body came from (the URL), named in errors.
+ */
+export function parseRegistryMetadata(text: string, source: string): RegistryMetadata {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new ConfigError(
+      `The registry's answer from ${source} is not JSON.\n  ${(error as Error).message}`
+    );
+  }
+  const parsed = abbreviatedDocumentSchema.safeParse(raw);
+  if (!parsed.success) {
+    const problems = parsed.error.issues.map(
+      (issue) => `  ${issue.path.join(".") || "(top level)"}: ${issue.message}`
+    );
+    throw new ConfigError(
+      [`The registry's answer from ${source} is not a package document.`, ...problems].join("\n")
+    );
+  }
+
+  const versions = Object.keys(parsed.data.versions)
+    .filter((version) => semver.valid(version) === version)
+    .sort(semver.rcompare);
+  const distTags: Record<string, string> = {};
+  for (const [tag, version] of Object.entries(parsed.data["dist-tags"])) {
+    if (semver.valid(version) === version) distTags[tag] = version;
+  }
+  return { name: parsed.data.name, versions, distTags };
+}
+
+/**
+ * The range the default request looks in: at least the installed version and
+ * below the next major. For a 0.x install that is `<1.0.0`, deliberately NOT
+ * caret semantics (which would stop at the next minor): the default is "the
+ * newest published version in the current major" (sous-io/sous#135), and a
+ * 0.x install's major is 0.
+ *
+ * The upper bound is written `-0` so a prerelease of the next major
+ * (`1.0.0-rc.1`, which sorts below `1.0.0`) is outside it too.
+ *
+ * defaultRange("0.2.30") -> ">=0.2.30 <1.0.0-0"
+ */
+export function defaultRange(current: string): string {
+  return `>=${current} <${semver.major(current) + 1}.0.0-0`;
+}
+
+/**
+ * Chooses the version an install moves to.
+ *
+ * - `default`: the newest candidate in `defaultRange(current)`; nothing newer
+ *   means `current`. Never a downgrade.
+ * - `major`: the newest candidate overall; when that is older than the
+ *   installed version, `current`. Never a downgrade.
+ * - `spec`: an exact version (a leading `v` is accepted) that must be
+ *   published, a dist-tag's version, or the newest candidate a range admits.
+ *   A spec may downgrade, and `direction` then says so.
+ *
+ * A candidate is a published version that is not a prerelease, or any
+ * published version when prereleases are on. An exact version and a dist-tag
+ * are taken as named, whatever the prerelease setting.
+ *
+ * @throws ConfigError when `current` is not a version, or a spec matches
+ *   nothing; the message lists the dist-tags and the newest versions.
+ */
+export function chooseVersion(input: ChooseVersionInput): VersionChoice {
+  const current = semver.valid(input.current);
+  if (current === null) {
+    throw new ConfigError(
+      `The installed version "${input.current}" is not a version sous can compare with the published ones.`
+    );
+  }
+  const prerelease = input.prerelease ?? semver.prerelease(current) !== null;
+  const published = input.versions.filter((version) => semver.valid(version) === version);
+  const candidates = prerelease
+    ? published
+    : published.filter((version) => semver.prerelease(version) === null);
+  const range = { includePrerelease: true };
+
+  const settle = (target: string | null, specKind?: VersionChoice["specKind"]): VersionChoice => {
+    const choice: VersionChoice = {
+      target: target ?? current,
+      direction: directionOf(target ?? current, current),
+      prerelease,
+    };
+    if (specKind !== undefined) choice.specKind = specKind;
+    return choice;
+  };
+  const noDowngrade = (target: string | null): string | null =>
+    target !== null && semver.gt(target, current) ? target : null;
+
+  const { request } = input;
+  if (request.kind === "default") {
+    return settle(noDowngrade(semver.maxSatisfying(candidates, defaultRange(current), range)));
+  }
+  if (request.kind === "major") {
+    return settle(noDowngrade(semver.maxSatisfying(candidates, "*", range)));
+  }
+
+  const spec = request.spec.trim();
+  const exact = semver.valid(spec);
+  if (exact !== null) {
+    if (!published.includes(exact)) throw noMatch(spec, "is not a published version", input);
+    return settle(exact, "version");
+  }
+  const tagged = input.distTags[spec];
+  if (tagged !== undefined) return settle(tagged, "dist-tag");
+  if (semver.validRange(spec) !== null) {
+    const newest = semver.maxSatisfying(candidates, spec, range);
+    if (newest === null) {
+      throw noMatch(
+        spec,
+        prerelease
+          ? "matches no published version"
+          : "matches no published version that is not a prerelease",
+        input
+      );
+    }
+    return settle(newest, "range");
+  }
+  throw noMatch(spec, "is not a version, a range or a dist-tag", input);
+}
+
+/** How `target` relates to `current`. */
+function directionOf(target: string, current: string): VersionDirection {
+  const order = semver.compare(target, current);
+  if (order > 0) return "upgrade";
+  if (order < 0) return "downgrade";
+  return "current";
+}
+
+/**
+ * The error for a spec that names nothing: what was asked, why it matched
+ * nothing, and what the registry does publish.
+ */
+function noMatch(spec: string, why: string, input: ChooseVersionInput): ConfigError {
+  const lines = [`The requested version "${spec}" ${why}.`];
+  const tags = Object.entries(input.distTags).sort(([a], [b]) => a.localeCompare(b));
+  if (tags.length > 0) {
+    lines.push("  The dist-tags point at:");
+    for (const [tag, version] of tags) lines.push(`    ${tag}: ${version}`);
+  }
+  const newest = input.versions
+    .filter((version) => semver.valid(version) === version)
+    .sort(semver.rcompare)
+    .slice(0, NEWEST_LISTED);
+  if (newest.length > 0) {
+    lines.push(`  The newest published versions are ${newest.join(", ")}.`);
+  } else {
+    lines.push("  The registry lists no published versions.");
+  }
+  return new ConfigError(lines.join("\n"));
+}

package/src/lib/vars/question-plan.ts

@@ -93,11 +93,19 @@ function questionCount(count: number): string {
   return count === 1 ? "1 question" : `${count} questions`;
 }
 
-/** The labeled facts one planned question shows. */
-export function plannedVariableFacts(planned: PlannedVariable): LabeledFact[] {
+/**
+ * The labeled facts one planned question shows.
+ *
+ * @param planned - The planned question.
+ * @param answerHints - Whether to name the `--answer` flag that answers it ahead of time.
+ */
+export function plannedVariableFacts(
+  planned: PlannedVariable,
+  answerHints = true
+): LabeledFact[] {
   const { definition } = planned.defined;
 
-  return [
+  const facts: LabeledFact[] = [
     { label: "about", lines: [firstSentence(definition.description)] },
     { label: "example", lines: [String(definition.example)] },
     { label: "stored-as", lines: [planned.storedAs] },
@@ -112,8 +120,11 @@ export function plannedVariableFacts(planned: PlannedVariable): LabeledFact[] {
             : "no, and an answer is optional",
       ],
     },
-    { label: "answer-with", lines: [`--answer ${definition.name}=<value>`] },
   ];
+  if (answerHints) {
+    facts.push({ label: "answer-with", lines: [`--answer ${definition.name}=<value>`] });
+  }
+  return facts;
 }
 
 /** What `formatQuestionPlan` needs beyond the questions themselves. */
@@ -121,26 +132,37 @@ export interface QuestionPlanFormatOptions {
   /** The column to wrap descriptions at. */
   width?: number;
   /**
-   * Recipes in the closure whose files are not on this machine, so their
-   * manifests could not be read. They are named in the plan rather than
-   * silently left out of it.
+   * Recipes in the closure whose questions are unknown: their files are not on
+   * this machine, and their repository's index does not record their
+   * questions. They are named in the plan rather than silently left out of it.
    */
   unreadable?: string[];
+  /**
+   * Whether the plan says how to answer its questions ahead of time: the
+   * `--answer` flag under each question, and a closing sentence. True for the
+   * dry run of a command that asks them; false where the plan only describes.
+   */
+  answerHints?: boolean;
 }
 
 /**
- * The one line that names the recipes a dry run could not read. A dry run
- * downloads nothing, so a recipe this machine does not hold yet has no manifest
- * to read; saying so by name is more useful than leaving it out of the plan.
+ * The one line that names the recipes whose questions are unknown. Nothing is
+ * downloaded to plan, so a recipe this machine does not hold yet is described
+ * from its repository's index, and an index written before sous recorded
+ * questions there cannot say; naming those recipes is more useful than leaving
+ * them out of the plan.
  *
- * @param unreadable - The recipe keys whose manifests could not be read.
+ * @param unreadable - The recipe keys whose questions are unknown.
+ * @param answerHints - Whether the plan belongs to a dry run that could be run for real.
  */
-function unreadableLine(unreadable: string[]): string {
-  return (
-    `Not on this machine yet, so their questions cannot be listed: ` +
-    `${unreadable.join(", ")}. A dry run downloads nothing; run this command ` +
-    `again without '--dry-run' to install them and be asked.`
-  );
+function unreadableLine(unreadable: string[], answerHints: boolean): string {
+  const line =
+    `Not on this machine yet, and their repository's index does not record their ` +
+    `questions, so they cannot be listed: ${unreadable.join(", ")}.`;
+  return answerHints
+    ? `${line} A dry run downloads nothing; run this command again without ` +
+        `'--dry-run' to install them and be asked.`
+    : line;
 }
 
 /**
@@ -157,6 +179,7 @@ export function formatQuestionPlan(
   options: QuestionPlanFormatOptions = {}
 ): string[] {
   const unreadable = options.unreadable ?? [];
+  const answerHints = options.answerHints ?? true;
 
   const columns = options.width ?? wrapColumns();
   /** Wraps one sentence to the width the caller's indentation leaves for it. */
@@ -166,7 +189,7 @@ export function formatQuestionPlan(
   if (planned.length === 0) {
     return unreadable.length === 0
       ? sentence("None of these recipes ask any questions, so nothing needs answering.")
-      : sentence(unreadableLine(unreadable), palette.note);
+      : sentence(unreadableLine(unreadable, answerHints), palette.note);
   }
 
   const unanswered = planned.filter((entry) => !entry.answered).length;
@@ -194,15 +217,15 @@ export function formatQuestionPlan(
     for (const entry of entries) {
       lines.push("", `  ${color.cyan(entry.defined.definition.name)}`);
       // The facts block indents itself, so the plan adds nothing on top of it.
-      lines.push(...renderFacts(plannedVariableFacts(entry), columns - 2));
+      lines.push(...renderFacts(plannedVariableFacts(entry, answerHints), columns - 2));
     }
   }
 
   if (unreadable.length > 0) {
-    lines.push("", ...sentence(unreadableLine(unreadable), palette.note));
+    lines.push("", ...sentence(unreadableLine(unreadable, answerHints), palette.note));
   }
 
-  if (unanswered > 0) {
+  if (unanswered > 0 && answerHints) {
     lines.push(
       "",
       ...sentence(