@sous-io/sous 0.2.16 → 0.2.18

package/src/lib/repos/resolver.ts

@@ -95,6 +95,14 @@ export type ResolveContext = {
   loadManifest: RecipeManifestLoader;
   /** Whether prereleases are allowed when a request does not say. Defaults to false. */
   prerelease?: boolean;
+  /**
+   * Versions to hold where they are, keyed by recipe key. A recipe named here
+   * resolves to that version whenever it still satisfies every range asked of
+   * it, rather than to the newest one that does; a range that no longer allows
+   * it wins, and the newest satisfying version is chosen as usual. This is how
+   * an update moves only the pins it was asked to move.
+   */
+  keep?: Record<string, string>;
 };
 
 /** One recipe version the resolver settled on. */
@@ -608,7 +616,7 @@ function resolveRecipeRef(
     (previous?.prerelease ?? false) ||
     (item.prerelease ?? context.prerelease ?? false);
 
-  const version = pickVersion(key, entry, ranges, prerelease);
+  const version = pickVersion(key, entry, ranges, prerelease, context.keep?.[key]);
   const versionEntry = entry.versions[version]!;
 
   const requestedBy = [...(previous?.requestedBy ?? [])];
@@ -645,12 +653,14 @@ function resolveRecipeRef(
  * @param entry - The recipe's index entry.
  * @param ranges - Every range that has to hold, with who asked for it.
  * @param prerelease - Whether prereleases may match.
+ * @param keep - A version to hold, chosen whenever it is among the candidates.
  */
 function pickVersion(
   key: string,
   entry: IndexFile["recipes"][string],
   ranges: Array<{ range: string; requestedBy: string }>,
-  prerelease: boolean
+  prerelease: boolean,
+  keep?: string
 ): string {
   const published = Object.keys(entry.versions);
   const eligible = prerelease
@@ -664,6 +674,19 @@ function pickVersion(
     );
   }
 
+  // A held version is kept exactly as long as every range still allows it. It
+  // is checked against the published list rather than the eligible one, so a
+  // prerelease a subscription once opted into is not moved just for being one.
+  if (
+    keep !== undefined &&
+    Object.hasOwn(entry.versions, keep) &&
+    ranges.every(({ range }) =>
+      semver.satisfies(keep, range, { includePrerelease: true })
+    )
+  ) {
+    return keep;
+  }
+
   const best = semver.maxSatisfying(candidates, "*", { includePrerelease: prerelease });
   if (best !== null) return best;
 

package/src/lib/repos/seed.ts

@@ -48,6 +48,7 @@ import {
   type IndexOverlay,
 } from "./providers/index-cache.js";
 import { warning } from "../../utils/formatting.js";
+import { hashDirectorySync } from "./store/hash.js";
 import { identitySegments } from "./identity.js";
 import { ensureIndexCacheDirectory } from "../../utils/sous-directory.js";
 import type { RecipeStoreLike, StoreKey } from "./store/contract.js";
@@ -204,14 +205,70 @@ export async function seedCoreRecipe(
 export type CoreIndexOverlayOptions = {
   /** The packaged version, which is by rule the running sous version. */
   version: string;
-  /** The content hash of the entry the seed put in the store. */
-  hash: string;
+  /**
+   * The content hash of the entry the seed put in the store, or a function
+   * that works it out the first time it is needed. The function form is what
+   * lets an overlay be installed before anything has been seeded.
+   */
+  hash: string | (() => string);
   /** The installed package's root directory. Defaults to the running CLI's own. */
   packageRoot?: string;
   /** Where the one warning this can produce goes. Defaults to the console banner. */
   warn?: (message: string) => void;
 };
 
+/**
+ * The overlay every index cache a command builds starts with: the packaged core
+ * version, hashed from the package itself the first time the official
+ * repository's index is read.
+ *
+ * Seeding installs a precise overlay of its own (carrying the hash of the entry
+ * it just wrote), but only the commands that seed get that one. This is what
+ * makes the packaged version resolvable everywhere else too: a lockfile rebuild,
+ * a browsing command, anything that reads the official index. The hash of the
+ * packaged folder is the hash a seeded store entry carries, because the store
+ * copies the folder byte for byte.
+ *
+ * A package whose core recipe cannot be read adds nothing, silently: seeding
+ * reports that failure in full, and a read-only command has nothing better to
+ * say about it.
+ *
+ * @param options - The packaged version, and where the package is.
+ */
+export function packagedCoreIndexOverlay(options: {
+  /** The packaged version, which is by rule the running sous version. */
+  version: string;
+  /** The installed package's root directory. Defaults to the running CLI's own. */
+  packageRoot?: string;
+  /** Where the one warning the overlay can produce goes. */
+  warn?: (message: string) => void;
+}): IndexOverlay {
+  let hash: string | null | undefined;
+  const packagedHash = (): string | null => {
+    if (hash === undefined) {
+      try {
+        hash = hashDirectorySync(packagedCoreRecipeDir(options.packageRoot));
+      } catch {
+        hash = null;
+      }
+    }
+    return hash;
+  };
+
+  const overlay = coreIndexOverlay({
+    version: options.version,
+    hash: () => packagedHash()!,
+    ...(options.packageRoot === undefined ? {} : { packageRoot: options.packageRoot }),
+    ...(options.warn === undefined ? {} : { warn: options.warn }),
+  });
+
+  return (identity, index) => {
+    if (identity !== OFFICIAL_REPO_IDENTITY) return index;
+    if (packagedHash() === null) return index;
+    return overlay(identity, index);
+  };
+}
+
 /**
  * Builds the overlay that makes the packaged core recipe resolvable whatever
  * the official repository has published so far.
@@ -236,6 +293,8 @@ export type CoreIndexOverlayOptions = {
  */
 export function coreIndexOverlay(options: CoreIndexOverlayOptions): IndexOverlay {
   let warned = false;
+  const packagedHash = (): string =>
+    typeof options.hash === "function" ? options.hash() : options.hash;
 
   return (identity: string, index: IndexFile): IndexFile => {
     if (identity !== OFFICIAL_REPO_IDENTITY) return index;
@@ -243,14 +302,14 @@ export function coreIndexOverlay(options: CoreIndexOverlayOptions): IndexOverlay
     const published = index.recipes[CORE_RECIPE_KEY]?.versions[options.version];
 
     if (published !== undefined) {
-      if (published.hash !== options.hash && !warned) {
+      if (published.hash !== packagedHash() && !warned) {
         warned = true;
         (options.warn ?? warning)(
           `The repository '${OFFICIAL_REPO_NAME}' publishes version ${options.version} of ` +
             `'${CORE_RECIPE_KEY}' with different contents from the copy inside this ` +
             `installation of sous, so sous is using the published one.\n` +
             `  Published: ${published.hash}\n` +
-            `  Packaged:  ${options.hash}\n` +
+            `  Packaged:  ${packagedHash()}\n` +
             `  Reinstalling sous will bring the two back into line.`
         );
       }
@@ -276,7 +335,7 @@ export function coreIndexOverlay(options: CoreIndexOverlayOptions): IndexOverlay
           versions: {
             ...recipe?.versions,
             [options.version]: {
-              hash: options.hash,
+              hash: packagedHash(),
               tag: `${CORE_RECIPE_KEY}@${options.version}`,
               prerelease: semver.prerelease(options.version) !== null,
               seeded: true,

package/src/lib/repos/store/hash.ts

@@ -29,7 +29,8 @@
  * recipe folder containing a link.
  */
 
-import { createHash } from "node:crypto";
+import { createHash, type Hash } from "node:crypto";
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { STORE_ENTRY_FILENAME } from "../formats/common.js";
@@ -89,18 +90,77 @@ export async function hashDirectory(dir: string): Promise<string> {
   const hash = createHash("sha256");
 
   for (const relative of files) {
-    const bytes = await fs.readFile(path.join(root, ...relative.split("/")));
-    hash.update(Buffer.from(relative, "utf8"));
-    hash.update(FIELD_SEPARATOR);
-    hash.update(Buffer.from(String(bytes.byteLength), "utf8"));
-    hash.update(FIELD_SEPARATOR);
-    hash.update(bytes);
-    hash.update(FIELD_SEPARATOR);
+    updateWithFile(hash, relative, await fs.readFile(path.join(root, ...relative.split("/"))));
   }
 
   return `sha256-${hash.digest("hex")}`;
 }
 
+/**
+ * The same hash as `hashDirectory`, computed synchronously. It exists for the
+ * one place that needs a hash inside a synchronous read: folding the packaged
+ * core recipe into a cached index as the index is read.
+ *
+ * hashDirectorySync(dir) === (await hashDirectory(dir))
+ * // -> true, for any directory
+ *
+ * @param dir - Absolute path to the directory to hash.
+ */
+export function hashDirectorySync(dir: string): string {
+  const root = path.resolve(dir);
+  const files = collectFilesSync(root).sort(bytewiseCompare);
+  const hash = createHash("sha256");
+
+  for (const relative of files) {
+    updateWithFile(hash, relative, fsSync.readFileSync(path.join(root, ...relative.split("/"))));
+  }
+
+  return `sha256-${hash.digest("hex")}`;
+}
+
+/**
+ * Collects every hashable file under `dir`, synchronously. The rules are exactly
+ * those of `collectFiles`; the two differ only in how they wait.
+ *
+ * @param dir - The directory to walk.
+ * @param prefix - The relative path of `dir` within the tree being hashed.
+ */
+function collectFilesSync(dir: string, prefix = ""): string[] {
+  const entries = fsSync.readdirSync(dir, { withFileTypes: true });
+  const found: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.name === GIT_DIR_NAME) continue;
+    if (entry.name === STORE_ENTRY_FILENAME) continue;
+    if (entry.isSymbolicLink()) continue;
+
+    const relative = prefix.length > 0 ? `${prefix}/${entry.name}` : entry.name;
+    const absolute = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) found.push(...collectFilesSync(absolute, relative));
+    else if (entry.isFile()) found.push(relative);
+  }
+
+  return found;
+}
+
+/**
+ * Feeds one file's canonical record into a hash: its path, its byte length and
+ * its bytes, each followed by the separator.
+ *
+ * @param hash - The hash being built.
+ * @param relative - The file's path relative to the tree root, posix separators.
+ * @param bytes - The file's contents.
+ */
+function updateWithFile(hash: Hash, relative: string, bytes: Buffer): void {
+  hash.update(Buffer.from(relative, "utf8"));
+  hash.update(FIELD_SEPARATOR);
+  hash.update(Buffer.from(String(bytes.byteLength), "utf8"));
+  hash.update(FIELD_SEPARATOR);
+  hash.update(bytes);
+  hash.update(FIELD_SEPARATOR);
+}
+
 /**
  * Compares two content hashes. Both are canonical lowercase strings, so this is
  * an exact comparison; it exists so callers read as intent rather than as