@sous-io/sous 0.2.15 → 0.2.16

package/src/commands/repo/list.ts

@@ -3,9 +3,12 @@
  *
  * Shows every repository this project trusts, what it publishes, and whether it
  * is currently being read from a working copy instead of a published version.
- * It reads only what sous already has on disk: a repository whose index has
- * never been fetched says so in its own row rather than triggering a download,
- * so the command is safe to run offline.
+ * By default it reads only what sous already has on disk: a repository whose
+ * index has never been fetched says so in its own row rather than triggering a
+ * download, so the command is safe to run offline. `--latest` reads each index
+ * from upstream instead, saving nothing, and `--installed` narrows the listing
+ * to the repositories the lockfile pins a recipe from, naming each one under
+ * its row.
  */
 
 import { Flags } from "@oclif/core";
@@ -15,14 +18,24 @@ import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js"
 import { readEffectiveLinks } from "../../lib/repos/links.js";
 import { BUILT_IN_ADDED_BY } from "../../lib/repos/defaults.js";
 import { requireProvider } from "../../lib/repos/providers/index.js";
+import { readTrustedIndexes } from "../../lib/repos/catalog-inputs.js";
+import {
+  LINKED_REPO_NOTE,
+  describeIndexSource,
+  printBrowsingNotes,
+} from "../../lib/repos/catalog-display.js";
 import { renderTable, type TableColumn } from "../../utils/table.js";
+import { browsingFlags } from "../../utils/flags.js";
 import {
   footer,
   indent,
   log,
+  note,
   paragraph,
   section,
   showCommandVars,
+  wrapColumns,
+  wrapText,
 } from "../../utils/formatting.js";
 
 /** How far every line of this command's output is indented. */
@@ -71,10 +84,12 @@ export default class RepoList extends BaseCommand {
   static examples = [
     "<%= config.bin %> repo list",
     "<%= config.bin %> repo list --verbose",
+    "<%= config.bin %> repo list --installed --latest",
   ];
 
   static flags = {
     ...BaseCommand.baseFlags,
+    ...browsingFlags(),
     verbose: Flags.boolean({
       description: "Show the namespaces each repository publishes, under its row",
       default: false,
@@ -87,9 +102,15 @@ export default class RepoList extends BaseCommand {
     showCommandVars({
       Project: this.projectLabel,
       Config: this.configContext.configPath,
+      Reading: describeIndexSource(flags.latest),
+      ...(flags.installed ? { Showing: "only what this project has installed" } : {}),
     });
 
-    section("Repositories this project trusts");
+    section(
+      flags.installed
+        ? "Repositories this project has installed recipes from"
+        : "Repositories this project trusts"
+    );
 
     const service = subscriptionServiceFor({
       configContext: this.configContext,
@@ -98,7 +119,20 @@ export default class RepoList extends BaseCommand {
     });
 
     const repos = service.currentRepos();
-    const names = Object.keys(repos).sort();
+    const lock = service.lockService.read();
+    const names = Object.keys(repos)
+      .sort()
+      .filter(
+        (name) =>
+          !flags.installed ||
+          Object.values(lock.recipes).some((locked) => locked.repo === name)
+      );
+
+    if (names.length === 0 && flags.installed && Object.keys(repos).length > 0) {
+      paragraph("This project has installed no recipe from the repositories it trusts.");
+      footer();
+      return;
+    }
 
     if (names.length === 0) {
       paragraph(
@@ -110,10 +144,12 @@ export default class RepoList extends BaseCommand {
     }
 
     const links = readEffectiveLinks(this.configContext.sousDir);
+    const indexes = await readTrustedIndexes(service, { latest: flags.latest });
+    const indexFor = new Map(indexes.repos.map((entry) => [entry.name, entry.index]));
 
     const rows = names.map((name) => {
       const entry = repos[name]!;
-      const index = service.cachedIndex(name);
+      const index = indexFor.get(name);
       const namespaces =
         index === undefined ? "not fetched" : Object.keys(index.namespaces).sort().join(", ");
       // A repository whose index has never been fetched says so in the cell
@@ -130,19 +166,40 @@ export default class RepoList extends BaseCommand {
         namespaces: namespaces.length > 0 ? namespaces : "none",
         recipes,
         linked: links[name] === undefined ? "no" : `yes: ${links[name]!.path}`,
+        installed: Object.entries(lock.recipes)
+          .filter(([, locked]) => locked.repo === name)
+          .map(([key, locked]) => `${key} ${locked.version}`)
+          .sort()
+          .join(", "),
       };
     });
 
     for (const line of renderTable(COLUMNS, rows, {
       indent: INDENT,
-      rowNote: flags.verbose
-        ? (row) => color.gray(indent(`Namespaces: ${row.namespaces}`, INDENT))
-        : undefined,
+      rowNote: (row) => {
+        const notes: string[] = [];
+        if (flags.verbose) notes.push(`Namespaces: ${row.namespaces}`);
+        if (flags.installed) notes.push(`Installed: ${row.installed}`);
+        // Each note wraps under itself, inside the two indents it is printed at.
+        const width = Math.max(20, wrapColumns() - INDENT * 2);
+        return notes.length === 0
+          ? undefined
+          : notes
+              .flatMap((text) => wrapText(text, width))
+              .map((line) => color.gray(indent(line, INDENT)))
+              .join("\n");
+      },
     })) {
       log(indent(line, INDENT));
     }
 
-    // Everything the table can say, the table says; nothing goes under it.
+    // The table says everything about each repository; what sits under it is
+    // only what the rows could not: a repository upstream could not answer for,
+    // and what a linked row means for the installed recipes it names.
+    printBrowsingNotes({ notChecked: indexes.notChecked.filter((name) => names.includes(name)) });
+    if (flags.installed && names.some((name) => links[name] !== undefined)) {
+      note(LINKED_REPO_NOTE);
+    }
     footer();
   }
 }

package/src/commands/repo/search.ts

@@ -2,21 +2,32 @@
  * `sous repo search <text>`.
  *
  * Searches the cached index of every repository this project trusts: recipe
- * names, namespace names and descriptions. It reads only what is already on
- * disk, so it works offline and never downloads anything; a repository whose
- * index has not been fetched yet is named at the end rather than silently left
- * out of the results.
+ * names, namespace names and descriptions. By default it reads only what is
+ * already on disk, so it works offline and never downloads anything; a
+ * repository whose index has not been fetched yet is named at the end rather
+ * than silently left out of the results. `--latest` searches each index as
+ * upstream serves it, saving nothing, and `--installed` searches only the
+ * recipes the lockfile pins, showing the installed version.
  */
 
 import { Args, Flags } from "@oclif/core";
 import { BaseCommand } from "../../base-command.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import { readTrustedIndexes } from "../../lib/repos/catalog-inputs.js";
+import {
+  LINKED_NOTE,
+  describeIndexSource,
+  pinnedCell,
+} from "../../lib/repos/catalog-display.js";
+import { readEffectiveLinks } from "../../lib/repos/links.js";
 import { renderTable, type TableColumn } from "../../utils/table.js";
+import { browsingFlags } from "../../utils/flags.js";
 import {
   blankLine,
   footer,
   indent,
   log,
+  note,
   paragraph,
   section,
   showCommandVars,
@@ -45,12 +56,24 @@ const COLUMNS: TableColumn[] = [
   },
 ];
 
+/** The column an `--installed` search adds: the version the lockfile pins. */
+const INSTALLED_COLUMN: TableColumn = {
+  key: "installed",
+  header: "Installed",
+  overflow: "truncate",
+  minWidth: 9,
+};
+
 /** One recipe that matched, ready to be shown. */
 type Match = {
   repo: string;
   key: string;
   description: string;
   versions: string[];
+  /** The version the lockfile pins, when it pins this recipe from this repository. */
+  installed?: string;
+  /** The linked checkout builds read it from, when it is installed and its repository is linked. */
+  linkedPath?: string;
 };
 
 export default class RepoSearch extends BaseCommand {
@@ -67,6 +90,7 @@ export default class RepoSearch extends BaseCommand {
   static examples = [
     "<%= config.bin %> repo search task",
     "<%= config.bin %> repo search browser --limit 50",
+    "<%= config.bin %> repo search task --installed --latest",
   ];
 
   static args = {
@@ -78,6 +102,7 @@ export default class RepoSearch extends BaseCommand {
 
   static flags = {
     ...BaseCommand.baseFlags,
+    ...browsingFlags(),
     limit: Flags.integer({
       description: "How many matches to show",
       default: 25,
@@ -92,6 +117,8 @@ export default class RepoSearch extends BaseCommand {
       Project: this.projectLabel,
       Config: this.configContext.configPath,
       Searching: args.text,
+      Reading: describeIndexSource(flags.latest),
+      ...(flags.installed ? { Showing: "only what this project has installed" } : {}),
     });
 
     section("Recipes matching your search");
@@ -104,16 +131,17 @@ export default class RepoSearch extends BaseCommand {
 
     const repos = Object.keys(service.currentRepos()).sort();
     const matches: Match[] = [];
-    const notFetched: string[] = [];
-
-    for (const repo of repos) {
-      const index = service.cachedIndex(repo);
-      if (index === undefined) {
-        notFetched.push(repo);
-        continue;
-      }
+    const indexes = await readTrustedIndexes(service, { latest: flags.latest });
+    const { notFetched, notChecked } = indexes;
+    const lock = service.lockService.read();
+    const links = readEffectiveLinks(this.configContext.sousDir);
 
+    for (const { name: repo, index } of indexes.repos) {
       for (const [key, recipe] of Object.entries(index.recipes)) {
+        const locked = lock.recipes[key];
+        const installed = locked?.repo === repo ? locked.version : undefined;
+        if (flags.installed && installed === undefined) continue;
+
         const namespace = key.slice(0, key.indexOf("/"));
         const haystack = [
           key,
@@ -129,6 +157,10 @@ export default class RepoSearch extends BaseCommand {
           key,
           description: recipe.description ?? "",
           versions: Object.keys(recipe.versions).sort(),
+          ...(installed === undefined ? {} : { installed }),
+          ...(installed === undefined || links[repo] === undefined
+            ? {}
+            : { linkedPath: links[repo]!.path }),
         });
       }
     }
@@ -148,7 +180,9 @@ export default class RepoSearch extends BaseCommand {
         repos.length === 0
           ? "This project trusts no repositories yet, so there is nothing to search. " +
             "Add one with 'sous repo add <url>'."
-          : `Nothing in the repositories this project trusts matches '${args.text}'.`
+          : flags.installed
+            ? `Nothing this project has installed matches '${args.text}'.`
+            : `Nothing in the repositories this project trusts matches '${args.text}'.`
       );
     } else {
       const shown = matches.slice(0, flags.limit);
@@ -156,11 +190,18 @@ export default class RepoSearch extends BaseCommand {
         key: match.key,
         repo: match.repo,
         versions: match.versions.join(", "),
+        installed: pinnedCell(match.installed, match.linkedPath),
         description:
           match.description.length > 0 ? match.description : "no description published",
       }));
 
-      for (const line of renderTable(COLUMNS, rows, { indent: INDENT })) {
+      // Narrowed to what is installed, the installed version sits right after
+      // the recipe, ahead of every version the repository publishes.
+      const columns = flags.installed
+        ? [COLUMNS[0]!, INSTALLED_COLUMN, ...COLUMNS.slice(1)]
+        : COLUMNS;
+
+      for (const line of renderTable(columns, rows, { indent: INDENT })) {
         log(indent(line, INDENT));
       }
 
@@ -179,9 +220,21 @@ export default class RepoSearch extends BaseCommand {
       );
     }
 
+    if (notChecked.length > 0) {
+      summary.push(
+        `These repositories could not be reached, so they were searched as the cache ` +
+          `has them and were not checked: ${notChecked.join(", ")}.`
+      );
+    }
+
     if (summary.length > 0) {
       blankLine();
-      for (const line of summary) log(indent(line));
+      for (const line of summary) paragraph(line);
+    }
+
+    if (matches.slice(0, flags.limit).some((match) => match.linkedPath !== undefined)) {
+      blankLine();
+      note(LINKED_NOTE);
     }
 
     footer();

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.
  *