@sous-io/sous 0.2.30 → 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"));
+}