@sous-io/sous 0.2.15 → 0.2.17

package/src/commands/subscription/list.ts

@@ -2,20 +2,31 @@
  * `sous subscription list`.
  *
  * Prints every subscription this project declares: the ref, the version range
- * it resolves within, the versions its lockfile currently pins, where the
- * subscription came from, and whether it is switched on. Entries switched off
- * with `enabled: false` are listed too, because an opt-out is part of what a
- * project declares.
+ * it resolves within, the versions its lockfile currently pins, the latest
+ * version each of those recipes has published, where the subscription came
+ * from, and whether it is switched on. Entries switched off with
+ * `enabled: false` are listed too, because an opt-out is part of what a project
+ * declares.
  *
- * It reads only the config and the lockfile, so it is safe offline and never
- * downloads anything.
+ * By default it reads only the config, the lockfile and the cached indexes, so
+ * it is safe offline and never downloads anything. `--latest` reads the latest
+ * versions from upstream instead, saving nothing, and `--installed` narrows the
+ * listing to the subscriptions the lockfile pins something for.
  */
 
 import { BaseCommand } from "../../base-command.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
 import { BUILT_IN_ADDED_BY } from "../../lib/repos/defaults.js";
 import { USER_ADDED_BY } from "../../lib/repos/trust.js";
+import { loadCatalogContext } from "../../lib/repos/catalog-inputs.js";
+import { listRecipes } from "../../lib/repos/catalog.js";
+import {
+  describeIndexSource,
+  pinnedCell,
+  printBrowsingNotes,
+} from "../../lib/repos/catalog-display.js";
 import { renderTable, type TableColumn } from "../../utils/table.js";
+import { browsingFlags } from "../../utils/flags.js";
 import {
   blankLine,
   footer,
@@ -39,6 +50,7 @@ const COLUMNS: TableColumn[] = [
   { key: "key", header: "Subscription", kind: "path", overflow: "truncate", minWidth: 12 },
   { key: "range", header: "Range", overflow: "truncate", minWidth: 7 },
   { key: "pinned", header: "Pinned version", flex: 1, minWidth: 14 },
+  { key: "latest", header: "Latest version", overflow: "wrap", priority: "medium", minWidth: 14 },
   { key: "origin", header: "Origin", priority: "medium" },
   { key: "enabled", header: "Enabled", priority: "medium" },
 ];
@@ -52,16 +64,21 @@ export default class SubscriptionList extends BaseCommand {
    */
   static aliases = ["subscriptions:list"];
 
-  static examples = ["<%= config.bin %> subscription list"];
+  static examples = [
+    "<%= config.bin %> subscription list",
+    "<%= config.bin %> subscription list --installed --latest",
+  ];
 
-  static flags = { ...BaseCommand.baseFlags };
+  static flags = { ...BaseCommand.baseFlags, ...browsingFlags() };
 
   async run(): Promise<void> {
-    await this.parse(SubscriptionList);
+    const { flags } = await this.parse(SubscriptionList);
 
     showCommandVars({
       Project: this.projectLabel,
       Config: this.configContext.configPath,
+      Reading: describeIndexSource(flags.latest),
+      ...(flags.installed ? { Showing: "only what this project has installed" } : {}),
     });
 
     heading("Subscriptions");
@@ -72,28 +89,69 @@ export default class SubscriptionList extends BaseCommand {
       shellEnv: this.shellEnv,
     });
 
-    const listings = service.listSubscriptions();
+    const listings = service
+      .listSubscriptions()
+      .filter((entry) => !flags.installed || entry.pinned.length > 0);
 
     blankLine();
 
     if (listings.length === 0) {
-      paragraph("This project subscribes to nothing yet.");
+      paragraph(
+        flags.installed
+          ? "No subscription of this project has installed anything yet."
+          : "This project subscribes to nothing yet."
+      );
       footer();
       return;
     }
 
-    const rows = listings.map((entry) => ({
-      key: entry.key,
-      range: entry.range ?? "any version",
-      pinned: describePinned(entry.pinned, entry.enabled),
-      origin: describeOrigin(entry.addedBy),
-      enabled: entry.enabled ? "yes" : "no",
-    }));
+    // The latest version of each pinned recipe, from the repository the
+    // lockfile says it came from; the linked checkout, when there is one.
+    const { inputs, notChecked } = await loadCatalogContext({
+      service,
+      sousDir: this.configContext.sousDir,
+      settings: this.settings,
+      latest: flags.latest,
+    });
+    const published = new Map(
+      listRecipes(inputs).map((recipe) => [`${recipe.repo}:${recipe.key}`, recipe])
+    );
+    const lock = inputs.lock;
+
+    let anyLinked = false;
+    const rows = listings.map((entry) => {
+      const held = entry.pinned.map((pin) => {
+        const recipe = published.get(`${lock.recipes[pin.key]?.repo}:${pin.key}`);
+        if (recipe?.linkedPath !== undefined) anyLinked = true;
+        return { ...pin, recipe };
+      });
+      return {
+        key: entry.key,
+        range: entry.range ?? "any version",
+        pinned:
+          held.length === 0
+            ? describePinned([], entry.enabled)
+            : held
+                .map((pin) => `${pin.key} ${pinnedCell(pin.version, pin.recipe?.linkedPath)}`)
+                .join(", "),
+        latest: describeLatest(held.map((pin) => ({ key: pin.key, latest: pin.recipe?.latest }))),
+        origin: describeOrigin(entry.addedBy),
+        enabled: entry.enabled ? "yes" : "no",
+      };
+    });
+
+    const columns = flags.installed
+      ? COLUMNS.map((column) =>
+          column.key === "pinned" ? { ...column, header: "Installed version" } : column
+        )
+      : COLUMNS;
 
-    for (const line of renderTable(COLUMNS, rows, { indent: INDENT })) {
+    for (const line of renderTable(columns, rows, { indent: INDENT })) {
       log(indent(line, INDENT));
     }
 
+    printBrowsingNotes({ notChecked, anyLinked });
+
     footer();
   }
 }
@@ -117,6 +175,27 @@ export function describePinned(
   return enabled ? "pinned on first build" : "not pinned";
 }
 
+/**
+ * The latest published version of each recipe a subscription holds. One held
+ * recipe is the usual case, and it shows the version alone; several (a
+ * namespace subscription) are each named with the version beside them. A
+ * recipe no readable index publishes says so; a subscription holding nothing
+ * yet has no latest version to show.
+ *
+ * describeLatest([{ key: "workflow/task-files", latest: "1.2.0" }])
+ * // -> "1.2.0"
+ *
+ * @param held - Each held recipe, with its latest version when an index names one.
+ */
+export function describeLatest(held: Array<{ key: string; latest: string | undefined }>): string {
+  if (held.length === 0) return "";
+  const unknown = "not in any index sous has read";
+  if (held.length === 1) return held[0]!.latest ?? unknown;
+  return held
+    .map((entry) => `${entry.key} ${entry.latest ?? unknown}`)
+    .join(", ");
+}
+
 /**
  * Plain-language wording for a subscription entry's `addedBy` field.
  *

package/src/lib/build-preparation.ts

@@ -7,7 +7,16 @@
  */
 
 import type { SubscriptionService } from "./repos/subscription-service.js";
-import { blankLine, footer, heading, paragraph, warning } from "../utils/formatting.js";
+import {
+  blankLine,
+  footer,
+  heading,
+  note,
+  paragraph,
+  section,
+  showVariables,
+  warning,
+} from "../utils/formatting.js";
 
 /**
  * Gets this project's recipes ready to compile: restores whatever the store is
@@ -83,4 +92,38 @@ export async function prepareRepositoriesForBuild(
   }
 
   if (needsRestore) footer();
+
+  reportNewerVersions(upstream.newer);
+}
+
+/**
+ * States which recipes this project uses have a newer version within the range
+ * declared for them, as a fact: one line per recipe, the newer version beside the
+ * pinned one. Nothing moved, and the closing sentence says so. Prints nothing
+ * when there is nothing newer.
+ *
+ * @param newer - What the upstream check found.
+ */
+export function reportNewerVersions(
+  newer: Array<{ key: string; from: string; to: string }>
+): void {
+  if (newer.length === 0) return;
+
+  section("Newer versions published");
+  showVariables(
+    newer.map((entry) => ({
+      label: entry.key,
+      value: entry.to,
+      detail: `this project pins ${entry.from}`,
+    }))
+  );
+  blankLine();
+  note(
+    newer.length === 1
+      ? "This version is within the range declared for the recipe. No pin was changed, " +
+          "so this build uses the pinned version."
+      : "Each version is within the range declared for its recipe. No pin was changed, " +
+          "so this build uses the pinned versions."
+  );
+  footer();
 }

package/src/lib/repos/catalog-display.ts

@@ -10,7 +10,14 @@
  */
 
 import { renderFacts, type LabeledFact } from "../vars/display.js";
-import { log, wrapColumns } from "../../utils/formatting.js";
+import {
+  blankLine,
+  log,
+  note,
+  palette,
+  paragraph,
+  wrapColumns,
+} from "../../utils/formatting.js";
 import type { TableColumn } from "../../utils/table.js";
 import type {
   NamespaceCoverage,
@@ -42,6 +49,19 @@ export const RECIPE_COLUMNS: TableColumn[] = [
   },
 ];
 
+/**
+ * The recipe columns for one run. Narrowed to what the project has installed,
+ * the pinned column is the installed version, and is headed that way.
+ *
+ * @param options - Whether the listing is narrowed to installed recipes.
+ */
+export function recipeColumns(options: { installed?: boolean } = {}): TableColumn[] {
+  if (options.installed !== true) return RECIPE_COLUMNS;
+  return RECIPE_COLUMNS.map((column) =>
+    column.key === "pinned" ? { ...column, header: "Installed" } : column
+  );
+}
+
 /** One rendered recipe row, in the shape `RECIPE_COLUMNS` reads. */
 export type RecipeRow = {
   key: string;
@@ -64,12 +84,91 @@ export function recipeRows(listings: RecipeListing[]): RecipeRow[] {
     key: entry.key,
     repo: entry.repo,
     latest: entry.latest ?? "none published",
-    pinned: entry.pinned ?? "",
+    pinned: pinnedCell(entry.pinned, entry.linkedPath),
     subscribed: entry.subscribed ? "yes" : "no",
     description: entry.description ?? "no description published",
   }));
 }
 
+/**
+ * The pinned version as a cell: the version alone, or the version marked
+ * `linked` in muted grey when builds read the recipe from a linked checkout.
+ *
+ * @param pinned - The version the lockfile pins, when it pins one.
+ * @param linkedPath - The linked checkout, when the repository is linked.
+ */
+export function pinnedCell(pinned: string | undefined, linkedPath: string | undefined): string {
+  if (pinned === undefined) return "";
+  return linkedPath === undefined ? pinned : `${pinned} ${palette.muted("linked")}`;
+}
+
+/** What a listing says about the linked recipes it marked. */
+export const LINKED_NOTE =
+  "A recipe marked linked is pinned at the version shown, but builds currently read it " +
+  "from the linked checkout of its repository.";
+
+/** What a repository listing says when an installed repository is linked. */
+export const LINKED_REPO_NOTE =
+  "A recipe installed from a linked repository is pinned at the version shown, but " +
+  "builds currently read it from the linked checkout.";
+
+/**
+ * Where a browsing command read the indexes from, in the words its opening
+ * block shows.
+ *
+ * @param latest - Whether the latest was asked for.
+ */
+export function describeIndexSource(latest: boolean): string {
+  return latest ? "each repository, upstream" : "the cached indexes";
+}
+
+/** What a browsing command could not read, and whether any row is linked. */
+export type BrowsingNotes = {
+  /** Trusted repositories with no index at all. */
+  notFetched?: string[];
+  /** Repositories upstream could not answer for, shown from the cache. */
+  notChecked?: string[];
+  /** True when some row was marked linked. */
+  anyLinked?: boolean;
+};
+
+/**
+ * Prints what a browsing command's rows could not say themselves: repositories
+ * that were not listed at all, repositories shown from the cache because
+ * upstream could not be reached, and what `linked` means when a row carries
+ * it. Prints nothing when there is nothing to say.
+ *
+ * @param notes - What the command could not read, and whether a row was linked.
+ */
+export function printBrowsingNotes(notes: BrowsingNotes): void {
+  const lines: Array<{ text: string; kind: "fact" | "note" }> = [];
+
+  if ((notes.notFetched ?? []).length > 0) {
+    lines.push({
+      kind: "fact",
+      text:
+        `These repositories are trusted and their index has not been fetched yet, so ` +
+        `nothing in them is listed: ${notes.notFetched!.join(", ")}.`,
+    });
+  }
+  if ((notes.notChecked ?? []).length > 0) {
+    lines.push({
+      kind: "fact",
+      text:
+        `These repositories could not be reached, so they are shown from the cache and ` +
+        `were not checked: ${notes.notChecked!.join(", ")}.`,
+    });
+  }
+  if (notes.anyLinked === true) lines.push({ kind: "note", text: LINKED_NOTE });
+
+  if (lines.length === 0) return;
+  blankLine();
+  for (const line of lines) {
+    if (line.kind === "note") note(line.text);
+    else paragraph(line.text);
+  }
+}
+
 /**
  * Plain-language wording for how much of a namespace a project subscribes to.
  *

package/src/lib/repos/catalog-inputs.ts

@@ -8,15 +8,18 @@
  * is pinned, the links map and the store for a recipe's own files, and
  * `recipeOutputs` for where a content kind lands.
  *
- * Nothing here downloads anything. A repository whose index has never been
- * fetched is left out of the catalog and named separately, so a browsing command
- * is safe offline.
+ * By default nothing here downloads anything: a repository whose index has
+ * never been fetched is left out of the catalog and named separately, so a
+ * browsing command is safe offline. Asked for the latest, it reads each index
+ * from upstream instead and writes none of it to the cache; a repository that
+ * cannot be reached is read from the cache and named as not checked.
  */
 
 import type { Settings, VarScope } from "../settings.js";
 import type { SubscriptionService } from "./subscription-service.js";
 import type { CatalogInputs, CatalogRepo } from "./catalog.js";
-import { linkedPathFor } from "./links.js";
+import type { IndexFile } from "./formats/index-file.js";
+import { linkedPathFor, readEffectiveLinks } from "./links.js";
 import { mapLinkedRecipes, readRecipeManifestIn } from "./locked-recipes.js";
 import { WRITABLE_CONTENT_KINDS, destinationsFor } from "./recipe-targets.js";
 import type { WritableContentKind } from "./recipe-targets.js";
@@ -37,8 +40,94 @@ export type CatalogInputsOptions = {
   scope?: VarScope;
   /** The environment to read; decides where the store and the links map are. */
   env?: NodeJS.ProcessEnv;
+  /**
+   * The indexes to read, when the caller has already gathered them (with
+   * `readTrustedIndexes`, say, to read upstream). The cached indexes otherwise.
+   */
+  indexes?: TrustedIndexes;
+};
+
+/** Where to read the trusted repositories' indexes from. */
+export type TrustedIndexesOptions = {
+  /** Read each index from upstream rather than the cache, writing none of it. */
+  latest?: boolean;
 };
 
+/** One trusted repository's index, and where it was read from. */
+export type TrustedIndex = {
+  /** The repository's short name. */
+  name: string;
+  /** Where it lives, as the project's config records it. */
+  url?: string;
+  /** The index that was read. */
+  index: IndexFile;
+  /** Whether it came from upstream just now or from the cache. */
+  source: "upstream" | "cache";
+};
+
+/** Every trusted repository's index sous could read, and what it could not. */
+export type TrustedIndexes = {
+  /** The indexes, by repository short name, sorted. */
+  repos: TrustedIndex[];
+  /**
+   * Trusted repositories with no index at all: never fetched, and (when the
+   * latest was asked for) not reachable either. Sorted.
+   */
+  notFetched: string[];
+  /**
+   * Repositories the latest was asked for that could not be reached, and were
+   * read from the cache instead. Sorted; always empty when reading the cache.
+   */
+  notChecked: string[];
+};
+
+/**
+ * Reads the index of every repository this project trusts. From the cache by
+ * default, which downloads nothing. With `latest`, from upstream, all at once,
+ * and nothing fetched is written to the cache: only a command that resolves
+ * versions changes what the cache holds. A repository upstream cannot answer
+ * for is read from the cache and named in `notChecked`.
+ *
+ * @param service - The subscription service for this project.
+ * @param options - Whether to read upstream.
+ */
+export async function readTrustedIndexes(
+  service: SubscriptionService,
+  options: TrustedIndexesOptions = {}
+): Promise<TrustedIndexes> {
+  if (options.latest !== true) return cachedTrustedIndexes(service);
+
+  const trusted = service.currentRepos();
+  const names = Object.keys(trusted).sort();
+  const answers = await Promise.allSettled(names.map((name) => service.upstreamIndex(name)));
+
+  const result: TrustedIndexes = { repos: [], notFetched: [], notChecked: [] };
+  names.forEach((name, position) => {
+    const url = trusted[name]?.url;
+    const answer = answers[position]!;
+    if (answer.status === "fulfilled") {
+      result.repos.push({
+        name,
+        ...(url === undefined ? {} : { url }),
+        index: answer.value,
+        source: "upstream",
+      });
+      return;
+    }
+
+    // Upstream could not answer, so the cached copy stands in and says so. A
+    // repository with no cached copy either is named once, as never fetched.
+    const cached = service.cachedIndex(name);
+    if (cached === undefined) {
+      result.notFetched.push(name);
+      return;
+    }
+    result.notChecked.push(name);
+    result.repos.push({ name, ...(url === undefined ? {} : { url }), index: cached, source: "cache" });
+  });
+  return result;
+}
+
 /** The catalog's inputs, plus what could not be read. */
 export type CatalogContext = {
   /** What the catalog functions read. */
@@ -48,6 +137,11 @@ export type CatalogContext = {
    * could be listed. Sorted.
    */
   notFetched: string[];
+  /**
+   * Repositories the latest was asked for that could not be reached, listed
+   * from the cache instead. Sorted.
+   */
+  notChecked: string[];
 };
 
 /**
@@ -60,25 +154,23 @@ export type CatalogContext = {
 export function catalogContextFor(options: CatalogInputsOptions): CatalogContext {
   const { service } = options;
   const env = options.env ?? process.env;
+  const indexes = options.indexes ?? cachedTrustedIndexes(service);
 
-  const repos: CatalogRepo[] = [];
-  const notFetched: string[] = [];
+  const repos: CatalogRepo[] = indexes.repos.map((entry) => ({
+    name: entry.name,
+    ...(entry.url === undefined ? {} : { url: entry.url }),
+    index: entry.index,
+  }));
 
-  const trusted = service.currentRepos();
-  for (const name of Object.keys(trusted).sort()) {
-    const index = service.cachedIndex(name);
-    if (index === undefined) {
-      notFetched.push(name);
-      continue;
-    }
-    const url = trusted[name]?.url;
-    repos.push({ name, ...(url === undefined ? {} : { url }), index });
-  }
+  const links = readEffectiveLinks(options.sousDir, env);
+  const linked: Record<string, string> = {};
+  for (const [name, link] of Object.entries(links)) linked[name] = link.path;
 
   const inputs: CatalogInputs = {
     repos,
     lock: service.lockService.read(),
     subscriptions: Object.keys(service.allSubscriptions()).sort(),
+    linked,
     readManifest: (recipe) => {
       const directory = recipeFilesDirectory({
         service,
@@ -105,7 +197,43 @@ export function catalogContextFor(options: CatalogInputsOptions): CatalogContext
     },
   };
 
-  return { inputs, notFetched };
+  return { inputs, notFetched: indexes.notFetched, notChecked: indexes.notChecked };
+}
+
+/**
+ * The catalog's inputs, reading the indexes the way the options say: from the
+ * cache, or with `latest` from upstream without writing to the cache.
+ *
+ * @param options - The subscription service, the project's directory and config,
+ *   and whether to read upstream.
+ */
+export async function loadCatalogContext(
+  options: Omit<CatalogInputsOptions, "indexes"> & TrustedIndexesOptions
+): Promise<CatalogContext> {
+  const indexes = await readTrustedIndexes(options.service, {
+    ...(options.latest === undefined ? {} : { latest: options.latest }),
+  });
+  return catalogContextFor({ ...options, indexes });
+}
+
+/**
+ * Every trusted repository's cached index, read synchronously.
+ *
+ * @param service - The subscription service for this project.
+ */
+function cachedTrustedIndexes(service: SubscriptionService): TrustedIndexes {
+  const trusted = service.currentRepos();
+  const result: TrustedIndexes = { repos: [], notFetched: [], notChecked: [] };
+  for (const name of Object.keys(trusted).sort()) {
+    const index = service.cachedIndex(name);
+    if (index === undefined) {
+      result.notFetched.push(name);
+      continue;
+    }
+    const url = trusted[name]?.url;
+    result.repos.push({ name, ...(url === undefined ? {} : { url }), index, source: "cache" });
+  }
+  return result;
 }
 
 /** Which recipe, at which version, in which of this project's repositories. */