@sous-io/sous 0.2.37 → 1.0.2

package/src/lib/repos/catalog.ts

@@ -1,842 +0,0 @@
-/**
- * Browsing what a project trusts.
- *
- * Every trusted repository publishes an index, and the project's lockfile
- * records what it currently pins. Put those two together and a project can be
- * asked four questions without downloading anything: which namespaces exist,
- * what is in one of them, which recipes exist, and everything about one recipe.
- * This module answers all four.
- *
- * Everything here is a pure function over data the caller hands it: the cached
- * indexes, the lockfile, and the subscription keys the project declares. The
- * content a recipe contributes is known only from its own manifest, inside the
- * recipe's files, so the caller supplies a reader for it; a recipe whose files
- * are not on this machine is described from its index alone rather than being
- * an error, and an index recorded by a current release says how each of its
- * dependencies was declared.
- *
- * Refs resolve the way `sous subscribe` resolves them: `namespace`,
- * `namespace/recipe`, and either of those qualified with `repo:`. A one-word ref
- * is searched across every trusted repository, and a word that means more than
- * one thing is an error listing what it could have meant.
- */
-
-import semver from "semver";
-import { ConfigError } from "../errors.js";
-import type { IndexDependency, IndexFile } from "./formats/index-file.js";
-import type { Lockfile } from "./formats/lockfile.js";
-import type { ContentKind, RecipeManifest } from "./formats/recipe-manifest.js";
-import {
-  CachedIndexLookup,
-  RefResolveArguments,
-  describeRef,
-  isNamedRef,
-  locationOf,
-  namespaceOf,
-  namespaceOfKey,
-  repoOf,
-  settleDependency,
-  shortKey,
-  sharedRefResolver,
-  splitRecipeKey,
-  type NamedRef,
-  type RefKind,
-  type SousRef,
-} from "../../services/ref-resolver/index.js";
-import { declarationFor, type DependencyLists } from "./declarations.js";
-
-// --- What the catalog reads ---------------------------------------------------------------------
-
-/** One trusted repository whose index has been fetched. */
-export type CatalogRepo = {
-  /** The short name this project calls it. */
-  name: string;
-  /** Where it lives, as the project's config records it. */
-  url?: string;
-  /** Its cached index. */
-  index: IndexFile;
-};
-
-/** Where one published recipe's files would be read from. */
-export type RecipeLocation = {
-  /** The recipe key, `namespace/recipe`. */
-  key: string;
-  namespace: string;
-  name: string;
-  /** The short name of the repository publishing it. */
-  repo: string;
-  /** The version being described. */
-  version: string;
-  /** The recipe folder, relative to the repository root. */
-  path: string;
-};
-
-/** Everything the catalog functions read. */
-export type CatalogInputs = {
-  /**
-   * The trusted repositories with a readable index, in the order a one-word ref
-   * searches them: the built-in repository first, then the ones the config
-   * names, in config order.
-   */
-  repos: CatalogRepo[];
-  /** The project's lockfile, which is where a pinned version comes from. */
-  lock: Lockfile;
-  /** The ref keys the project subscribes to: namespaces, and `namespace/recipe`. */
-  subscriptions: string[];
-  /**
-   * The repositories read from a linked working copy instead of the store, by
-   * short name, each with the checkout's path.
-   */
-  linked?: Record<string, string>;
-  /**
-   * Reads one published recipe's manifest, when its files are on this machine.
-   * Returning undefined means "not available", and the recipe is described from
-   * its index alone.
-   */
-  readManifest?: (recipe: RecipeLocation) => RecipeManifest | undefined;
-  /** Where one content kind's files land in this project, when anywhere does. */
-  destinationsFor?: (kind: ContentKind) => string[];
-};
-
-// --- What the catalog answers -------------------------------------------------------------------
-
-/** How much of a namespace a project subscribes to. */
-export type NamespaceCoverage = "whole namespace" | "some recipes" | "none";
-
-/** One namespace, as the listing shows it. */
-export type NamespaceListing = {
-  /** The short name of the repository publishing it. */
-  repo: string;
-  /** The namespace name. */
-  namespace: string;
-  /** The namespace's one-paragraph summary, when its index carries one. */
-  description?: string;
-  /** How many recipes the repository publishes in it. */
-  recipeCount: number;
-  /** How much of it this project subscribes to. */
-  subscribed: NamespaceCoverage;
-};
-
-/** One recipe, as a listing shows it. */
-export type RecipeListing = {
-  /** The recipe key, `namespace/recipe`. */
-  key: string;
-  namespace: string;
-  name: string;
-  /** The short name of the repository publishing it. */
-  repo: string;
-  /** The highest published version, prereleases considered only when nothing else is published. */
-  latest?: string;
-  /** The version this project's lockfile pins, when it pins one. */
-  pinned?: string;
-  /**
-   * The linked checkout builds read this recipe from instead of the pinned
-   * version, when the project pins it and its repository is linked.
-   */
-  linkedPath?: string;
-  /** True when the project subscribes to this recipe, or to the whole namespace holding it. */
-  subscribed: boolean;
-  /** The recipe's one-paragraph summary, when its index carries one. */
-  description?: string;
-};
-
-/** One namespace in full: the namespace itself, and every recipe in it. */
-export type NamespaceDetail = {
-  repo: string;
-  /** Where the repository lives, as the project's config records it. */
-  repoUrl?: string;
-  namespace: string;
-  description?: string;
-  subscribed: NamespaceCoverage;
-  /** Every recipe the repository publishes in the namespace, by key. */
-  recipes: RecipeListing[];
-};
-
-/** What one published version is to this project. */
-export type VersionStatus = "latest" | "pinned" | "latest and pinned" | "other";
-
-/** One published version of one recipe. */
-export type RecipeVersionListing = {
-  /** The exact version. */
-  version: string;
-  /** What the version is to this project. */
-  status: VersionStatus;
-  /** True when the index marks it a prerelease. */
-  prerelease: boolean;
-  /** When it was released, when the index records it. */
-  releasedAt?: string;
-};
-
-/** One dependency of the version being described. */
-export type RecipeDependencyListing = {
-  /** The recipe key the dependency names, `namespace/recipe`. */
-  key: string;
-  /**
-   * The manifest entry that brings it in, exactly as written (a recipe, a whole
-   * namespace, or a locator), from the index when it records one and from the
-   * manifest otherwise.
-   */
-  declared?: string;
-  /** Whether that entry makes it a build dependency or a co-subscription. */
-  kind?: "depends" | "subscribes";
-  /** The exact version the release resolved it to, when the index records one. */
-  resolvedVersion?: string;
-  /** The range the index recorded instead, when it could not resolve an exact version. */
-  resolvedRange?: string;
-  /** The canonical identity of the repository publishing it, for a cross-repository dependency. */
-  repo?: string;
-};
-
-/** One content kind a recipe contributes, and where its files would land. */
-export type RecipeContentListing = {
-  /** The content kind, as the manifest declares it. */
-  kind: ContentKind;
-  /** The glob patterns the manifest includes. */
-  include: string[];
-  /** Every directory in this project the files would be written into. */
-  destinations: string[];
-};
-
-/** One recipe in full. */
-export type RecipeDetail = {
-  /** The recipe key, `namespace/recipe`. */
-  key: string;
-  namespace: string;
-  name: string;
-  /** The short name of the repository publishing it. */
-  repo: string;
-  /** Where that repository lives, as the project's config records it. */
-  repoUrl?: string;
-  /** The recipe's one-paragraph summary, when its index carries one. */
-  description?: string;
-  /** The recipe folder, relative to the repository root. */
-  path: string;
-  /** The highest published version. */
-  latest?: string;
-  /** The version this project's lockfile pins, when it pins one. */
-  pinned?: string;
-  /**
-   * The linked checkout builds read this recipe from instead of the pinned
-   * version, when the project pins it and its repository is linked.
-   */
-  linkedPath?: string;
-  /** True when the project subscribes to this recipe, or to the whole namespace holding it. */
-  subscribed: boolean;
-  /**
-   * The version everything else here describes: the pinned one when the project
-   * pins one, and the latest published one otherwise.
-   */
-  describing?: string;
-  /** Every published version, newest first. */
-  versions: RecipeVersionListing[];
-  /** What the described version depends on, by key. */
-  dependencies: RecipeDependencyListing[];
-  /**
-   * True when the index records the described version's dependencies, even as
-   * none at all, so an empty list means "depends on nothing" rather than "not
-   * recorded".
-   */
-  dependenciesRecorded: boolean;
-  /** What the recipe contributes, and where each kind's files land. */
-  contents: RecipeContentListing[];
-  /**
-   * True when the recipe's own manifest could be read. When it is false, the
-   * contents are unknown rather than empty, because the recipe's files are not
-   * on this machine.
-   */
-  manifestRead: boolean;
-};
-
-// --- Listings -----------------------------------------------------------------------------------
-
-/**
- * Every namespace every trusted repository publishes, sorted by namespace and
- * then by repository, so two repositories publishing the same namespace name sit
- * beside each other.
- *
- * @param inputs - The cached indexes, the lockfile and the project's subscriptions.
- */
-export function listNamespaces(inputs: CatalogInputs): NamespaceListing[] {
-  const subscriptions = new Set(inputs.subscriptions);
-  const listings: NamespaceListing[] = [];
-
-  for (const repo of inputs.repos) {
-    for (const [namespace, declared] of Object.entries(repo.index.namespaces)) {
-      listings.push({
-        repo: repo.name,
-        namespace,
-        ...(declared.description === undefined ? {} : { description: declared.description }),
-        recipeCount: recipeKeysIn(repo.index, namespace).length,
-        subscribed: coverageOf(namespace, repo.index, subscriptions),
-      });
-    }
-  }
-
-  return listings.sort(byNamespaceThenRepo);
-}
-
-/**
- * Every recipe every trusted repository publishes, sorted by key and then by
- * repository.
- *
- * @param inputs - The cached indexes, the lockfile and the project's subscriptions.
- */
-export function listRecipes(inputs: CatalogInputs): RecipeListing[] {
-  const subscriptions = new Set(inputs.subscriptions);
-  const listings: RecipeListing[] = [];
-
-  for (const repo of inputs.repos) {
-    for (const key of Object.keys(repo.index.recipes)) {
-      listings.push(recipeListing(key, repo, inputs, subscriptions));
-    }
-  }
-
-  return listings.sort((left, right) =>
-    left.key === right.key
-      ? compare(left.repo, right.repo)
-      : compare(left.key, right.key)
-  );
-}
-
-/**
- * One namespace in full: what the repository says about it, and every recipe it
- * publishes in it.
- *
- * @param inputs - The cached indexes, the lockfile and the project's subscriptions.
- * @param ref - The namespace, optionally qualified with `repo:`.
- */
-export async function describeNamespace(
-  inputs: CatalogInputs,
-  ref: string
-): Promise<NamespaceDetail> {
-  const found = await resolveNamespaceRef(inputs, ref);
-  const subscriptions = new Set(inputs.subscriptions);
-  const declared = found.repo.index.namespaces[found.namespace]!;
-
-  return {
-    repo: found.repo.name,
-    ...(found.repo.url === undefined ? {} : { repoUrl: found.repo.url }),
-    namespace: found.namespace,
-    ...(declared.description === undefined ? {} : { description: declared.description }),
-    subscribed: coverageOf(found.namespace, found.repo.index, subscriptions),
-    recipes: recipeKeysIn(found.repo.index, found.namespace).map((key) =>
-      recipeListing(key, found.repo, inputs, subscriptions)
-    ),
-  };
-}
-
-/**
- * One recipe in full: its identity, every version it publishes, what it depends
- * on, what it asks about, and where its files would land in this project.
- *
- * @param inputs - The cached indexes, the lockfile, the subscriptions and the manifest reader.
- * @param ref - The recipe, as `namespace/recipe`, a bare recipe name, or either qualified with `repo:`.
- */
-export async function describeRecipe(
-  inputs: CatalogInputs,
-  ref: string
-): Promise<RecipeDetail> {
-  const found = await resolveRecipeRef(inputs, ref);
-  const subscriptions = new Set(inputs.subscriptions);
-  const listing = recipeListing(found.key, found.repo, inputs, subscriptions);
-  const entry = found.repo.index.recipes[found.key]!;
-
-  const describing = listing.pinned ?? listing.latest;
-  const published = entry.versions[describing ?? ""];
-
-  const manifest =
-    describing === undefined || inputs.readManifest === undefined
-      ? undefined
-      : inputs.readManifest({
-          key: found.key,
-          namespace: found.namespace,
-          name: found.name,
-          repo: found.repo.name,
-          version: describing,
-          path: entry.path,
-        });
-
-  return {
-    ...listing,
-    ...(found.repo.url === undefined ? {} : { repoUrl: found.repo.url }),
-    path: entry.path,
-    ...(describing === undefined ? {} : { describing }),
-    versions: versionListings(entry.versions, listing.latest, listing.pinned),
-    dependencies: dependencyListings(published?.dependencies, manifest),
-    dependenciesRecorded: published?.dependencies !== undefined,
-    contents: (manifest?.contents ?? []).map((content) => ({
-      kind: content.kind,
-      include: [...content.include],
-      destinations: inputs.destinationsFor?.(content.kind) ?? [],
-    })),
-    manifestRead: manifest !== undefined,
-  };
-}
-
-/**
- * The same inputs, narrowed to what this project has installed: each
- * repository's index keeps only the recipes the lockfile pins from that
- * repository, and only the namespaces holding one of them. Every listing and
- * every ref lookup over the result therefore sees only installed recipes. A
- * recipe's published version history is kept whole, so the installed version
- * still sits among the others.
- *
- * narrowToInstalled(inputs)
- * // -> the index of "r" holds "a/x" only, when the lockfile pins "a/x" from "r"
- *
- * @param inputs - The catalog's inputs.
- */
-export function narrowToInstalled(inputs: CatalogInputs): CatalogInputs {
-  const repos = inputs.repos.map((repo) => {
-    const recipes = Object.fromEntries(
-      Object.entries(repo.index.recipes).filter(
-        ([key]) => inputs.lock.recipes[key]?.repo === repo.name
-      )
-    );
-    const held = new Set(Object.keys(recipes).map(namespaceOfKey));
-    const namespaces = Object.fromEntries(
-      Object.entries(repo.index.namespaces).filter(([namespace]) => held.has(namespace))
-    );
-    return { ...repo, index: { ...repo.index, recipes, namespaces } };
-  });
-  return { ...inputs, repos };
-}
-
-/**
- * Looks a ref up among the installed recipes only, so an ambiguity between an
- * installed recipe and one the project does not use settles itself. A ref that
- * names something published but not installed is an error saying exactly that,
- * rather than the "no repository publishes" error the narrowed lookup alone
- * would raise.
- *
- * describeInstalled(inputs, "workflow/task-files", describeRecipe, "recipe")
- * // -> the recipe, when the lockfile pins it; otherwise an error saying the
- * //    project has not installed it
- *
- * @param inputs - The catalog's inputs, not yet narrowed.
- * @param ref - The ref being looked up.
- * @param describe - The lookup to run: `describeNamespace` or `describeRecipe`.
- * @param what - What the ref names, for the error.
- */
-export async function describeInstalled<T>(
-  inputs: CatalogInputs,
-  ref: string,
-  describe: (inputs: CatalogInputs, ref: string) => Promise<T>,
-  what: "namespace" | "recipe"
-): Promise<T> {
-  try {
-    return await describe(narrowToInstalled(inputs), ref);
-  } catch {
-    // The full lookup either explains the ref better (ambiguous, unknown) or
-    // proves it is published and simply not installed.
-    await describe(inputs, ref);
-    throw what === "namespace"
-      ? new ConfigError(
-          `This project has installed no recipe from the namespace '${ref}', so there is ` +
-            `nothing to show with '--installed'.`
-        )
-      : new ConfigError(
-          `This project has not installed the recipe '${ref}', so there is nothing to ` +
-            `show with '--installed'.`
-        );
-  }
-}
-
-// --- Resolving a ref ----------------------------------------------------------------------------
-
-/** One namespace a ref resolved to. */
-export type ResolvedNamespace = {
-  /** The repository publishing it. */
-  repo: CatalogRepo;
-  /** The namespace name. */
-  namespace: string;
-};
-
-/** One recipe a ref resolved to. */
-export type ResolvedRecipeRef = {
-  /** The repository publishing it. */
-  repo: CatalogRepo;
-  /** The recipe key, `namespace/recipe`. */
-  key: string;
-  namespace: string;
-  name: string;
-};
-
-/**
- * The namespace a ref names. A one-word ref is searched across every trusted
- * repository; a word that names a namespace in two of them is an error listing
- * both.
- *
- * @param inputs - The cached indexes.
- * @param ref - The namespace, optionally qualified with `repo:`.
- */
-export async function resolveNamespaceRef(
-  inputs: CatalogInputs,
-  ref: string
-): Promise<ResolvedNamespace> {
-  const parsed = readShortRef(ref);
-
-  if (parsed?.kind === "recipe") {
-    throw new ConfigError(
-      `'${ref}' names the recipe '${parsed.name}', not a namespace.\n` +
-        `  The namespace it belongs to is '${parsed.namespace!.name}'.`
-    );
-  }
-
-  const matches = await findIn(inputs, ref, ["namespace"]);
-
-  if (matches.length === 1) {
-    const match = matches[0]!;
-    return { repo: repoNamed(inputs, repoOf(match)!.name!), namespace: namespaceOf(match)!.name };
-  }
-
-  if (matches.length > 1) throw ambiguousError(ref, "namespace", matches);
-
-  const asRecipe = await findIn(inputs, ref, ["recipe"]);
-  if (parsed !== undefined && repoOf(parsed) === undefined && asRecipe.length > 0) {
-    throw new ConfigError(
-      `No repository this project trusts publishes a namespace called ` +
-        `'${parsed.name}'.\n` +
-        `  It is the name of a recipe:\n` +
-        asRecipe.map((candidate) => `    ${describeRef(candidate)}`).join("\n")
-    );
-  }
-
-  throw unknownError(inputs, ref, "namespace", parsed === undefined ? undefined : repoOf(parsed)?.name);
-}
-
-/**
- * The recipe a ref names. A two-segment ref names it exactly; a one-word ref is
- * searched as a recipe name across every trusted repository, and a name two of
- * them publish is an error listing both.
- *
- * @param inputs - The cached indexes.
- * @param ref - The recipe, as `namespace/recipe`, a bare recipe name, or either qualified with `repo:`.
- */
-export async function resolveRecipeRef(
-  inputs: CatalogInputs,
-  ref: string
-): Promise<ResolvedRecipeRef> {
-  const parsed = readShortRef(ref);
-
-  const matches = await findIn(inputs, ref, ["recipe"]);
-
-  if (matches.length === 1) {
-    const match = matches[0]!;
-    const namespace = namespaceOf(match)!.name;
-    const name = (match as { name: string }).name;
-    return {
-      repo: repoNamed(inputs, repoOf(match)!.name!),
-      key: `${namespace}/${name}`,
-      namespace,
-      name,
-    };
-  }
-
-  if (matches.length > 1) throw ambiguousError(ref, "recipe", matches);
-
-  const asNamespace = await findIn(inputs, ref, ["namespace"]);
-  if (asNamespace.length > 0) {
-    throw new ConfigError(
-      `No repository this project trusts publishes a recipe called ` +
-        `'${parsed === undefined ? ref : namespaceNameOf(parsed)}'.\n` +
-        `  It is the name of a namespace:\n` +
-        asNamespace.map((candidate) => `    ${describeRef(candidate)}`).join("\n")
-    );
-  }
-
-  throw unknownError(inputs, ref, "recipe", parsed === undefined ? undefined : repoOf(parsed)?.name);
-}
-
-// --- The pieces ---------------------------------------------------------------------------------
-
-/** Every recipe key one index publishes in one namespace, sorted. */
-function recipeKeysIn(index: IndexFile, namespace: string): string[] {
-  return Object.keys(index.recipes)
-    .filter((key) => namespaceOfKey(key) === namespace)
-    .sort();
-}
-
-/**
- * How much of one namespace a project subscribes to: the whole namespace when it
- * subscribes to the namespace itself, some recipes when it subscribes to at
- * least one recipe in it, and none otherwise.
- *
- * @param namespace - The namespace name.
- * @param index - The index publishing it.
- * @param subscriptions - The ref keys the project subscribes to.
- */
-function coverageOf(
-  namespace: string,
-  index: IndexFile,
-  subscriptions: Set<string>
-): NamespaceCoverage {
-  if (subscriptions.has(namespace)) return "whole namespace";
-  const some = recipeKeysIn(index, namespace).some((key) => subscriptions.has(key));
-  return some ? "some recipes" : "none";
-}
-
-/**
- * One recipe's listing row: what the index publishes, what the lockfile pins,
- * and whether the project subscribes to it.
- *
- * @param key - The recipe key.
- * @param repo - The repository publishing it.
- * @param inputs - The lockfile and the linked repositories.
- * @param subscriptions - The ref keys the project subscribes to.
- */
-function recipeListing(
-  key: string,
-  repo: CatalogRepo,
-  inputs: Pick<CatalogInputs, "lock" | "linked">,
-  subscriptions: Set<string>
-): RecipeListing {
-  const lock = inputs.lock;
-  const entry = repo.index.recipes[key]!;
-  const { namespace, name } = splitRecipeKey(key);
-  const latest = latestVersion(Object.keys(entry.versions), entry.versions);
-
-  // A locked entry pins one recipe from one repository. Two repositories can
-  // publish the same key, so the row only claims the pin when the lockfile says
-  // the recipe came from this repository.
-  const locked = lock.recipes[key];
-  const pinned = locked !== undefined && locked.repo === repo.name ? locked.version : undefined;
-  const linkedPath = pinned === undefined ? undefined : inputs.linked?.[repo.name];
-
-  return {
-    key,
-    namespace,
-    name,
-    repo: repo.name,
-    ...(latest === undefined ? {} : { latest }),
-    ...(pinned === undefined ? {} : { pinned }),
-    ...(linkedPath === undefined ? {} : { linkedPath }),
-    subscribed: subscriptions.has(key) || subscriptions.has(namespace),
-    ...(entry.description === undefined ? {} : { description: entry.description }),
-  };
-}
-
-/**
- * The highest published version. Prereleases are considered only when a recipe
- * has published nothing else, so a repository mid-prerelease still reports a
- * latest version rather than none.
- *
- * @param versions - Every published version string.
- * @param published - The index entries those versions carry.
- */
-function latestVersion(
-  versions: string[],
-  published: Record<string, { prerelease: boolean }>
-): string | undefined {
-  const stable = versions.filter((version) => published[version]?.prerelease !== true);
-  const pool = stable.length > 0 ? stable : versions;
-  return semver.maxSatisfying(pool, "*", { includePrerelease: true }) ?? undefined;
-}
-
-/**
- * Every published version, newest first, each labeled with what it is to this
- * project.
- *
- * @param versions - The index's version entries.
- * @param latest - The highest published version.
- * @param pinned - The version the lockfile pins, when it pins one.
- */
-function versionListings(
-  versions: Record<string, { prerelease: boolean; releasedAt?: string }>,
-  latest: string | undefined,
-  pinned: string | undefined
-): RecipeVersionListing[] {
-  return Object.keys(versions)
-    .sort((left, right) => semver.rcompare(left, right, { loose: true }))
-    .map((version) => {
-      const entry = versions[version]!;
-      const isLatest = version === latest;
-      const isPinned = version === pinned;
-      const status: VersionStatus =
-        isLatest && isPinned
-          ? "latest and pinned"
-          : isLatest
-            ? "latest"
-            : isPinned
-              ? "pinned"
-              : "other";
-      return {
-        version,
-        status,
-        prerelease: entry.prerelease,
-        ...(entry.releasedAt === undefined ? {} : { releasedAt: entry.releasedAt }),
-      };
-    });
-}
-
-/**
- * What one version depends on, from both sides: the dependencies the recipe's
- * manifest declares, and the versions the release resolved them to in the
- * index. A dependency that appears on only one side is still a row, because the
- * two disagreeing is exactly what somebody reading this needs to see.
- *
- * @param resolved - The index's record of what the version was released against.
- * @param manifest - The recipe's manifest, when its files could be read.
- */
-function dependencyListings(
-  resolved: Record<string, IndexDependency> | undefined,
-  manifest: RecipeManifest | undefined
-): RecipeDependencyListing[] {
-  const rows = new Map<string, RecipeDependencyListing>();
-  const lists: DependencyLists | undefined =
-    manifest === undefined
-      ? undefined
-      : { depends: manifest.depends ?? [], subscribes: manifest.subscribes ?? [] };
-
-  for (const [key, entry] of Object.entries(resolved ?? {})) {
-    // The index says how the release that published the version saw it. An
-    // entry recorded before the index said so is answered from the manifest,
-    // by the same rule the release applies.
-    const declaration =
-      entry.declared !== undefined && entry.kind !== undefined
-        ? { declared: entry.declared, kind: entry.kind }
-        : lists === undefined
-          ? undefined
-          : declarationFor(lists, key, resolved);
-    rows.set(key, {
-      key,
-      ...(entry.version === undefined ? {} : { resolvedVersion: entry.version }),
-      ...(entry.range === undefined ? {} : { resolvedRange: entry.range }),
-      ...(entry.repo === undefined ? {} : { repo: entry.repo }),
-      ...(declaration ?? {}),
-    });
-  }
-
-  // A manifest entry that covers no row the index recorded is still shown, so a
-  // reader sees everything the manifest declares.
-  const covered = new Set([...rows.values()].map((row) => row.declared));
-  for (const [kind, declared] of [
-    ["depends", lists?.depends ?? []],
-    ["subscribes", lists?.subscribes ?? []],
-  ] as Array<["depends" | "subscribes", string[]]>) {
-    for (const written of declared) {
-      if (covered.has(written.trim())) continue;
-      // A dependency that reads more than one way is listed under the key the
-      // index recorded for it. One sous cannot parse or settle is still worth
-      // showing; it is listed under what it was written as, so the reader sees
-      // the entry as it stands.
-      let key = written;
-      try {
-        const reading = settleDependency(written, {
-          ...(resolved === undefined ? {} : { recorded: resolved }),
-        });
-        if (reading !== undefined && isNamedRef(reading)) key = shortKey(reading);
-      } catch {
-        key = written;
-      }
-      rows.set(key, { ...(rows.get(key) ?? { key }), declared: written, kind });
-    }
-  }
-
-  return [...rows.values()].sort((left, right) => compare(left.key, right.key));
-}
-
-/**
- * The repository a match named. Every match comes from this catalog's own
- * repositories, so the lookup always finds one.
- *
- * @param inputs - The cached indexes.
- * @param name - The repository's short name.
- */
-function repoNamed(inputs: CatalogInputs, name: string): CatalogRepo {
-  return inputs.repos.find((repo) => repo.name === name)!;
-}
-
-/**
- * Every ref in this catalog's repositories that a ref written on the command
- * line names, of the kinds given, best match first.
- *
- * @param inputs - The cached indexes.
- * @param ref - The ref as typed.
- * @param kinds - The kinds of ref the caller accepts.
- */
-async function findIn(
-  inputs: CatalogInputs,
-  ref: string,
-  kinds: readonly RefKind[]
-): Promise<SousRef[]> {
-  const lookup = new CachedIndexLookup(
-    new Map(inputs.repos.map((repo) => [repo.name, repo.index])),
-    {
-      order: inputs.repos.map((repo) => repo.name),
-      urls: Object.fromEntries(inputs.repos.map((repo) => [repo.name, repo.url])),
-    }
-  );
-  const result = await sharedRefResolver().resolve(new RefResolveArguments({ input: ref, lookup, kinds }));
-  return result.refs;
-}
-
-/**
- * The namespace or recipe a ref from the command line names by its short form,
- * checked by the one parser: undefined when the ref names a location instead.
- *
- * @param ref - The ref as typed.
- */
-function readShortRef(ref: string): NamedRef | undefined {
-  const { refs } = sharedRefResolver().parse(ref);
-  return refs.find(
-    (candidate): candidate is NamedRef => isNamedRef(candidate) && locationOf(candidate) === undefined
-  );
-}
-
-/** The name a short ref was written with: its namespace for a namespace, its recipe name otherwise. */
-function namespaceNameOf(ref: NamedRef): string {
-  return ref.kind === "namespace" ? ref.name : ref.namespace!.name;
-}
-
-/** The error a ref that could have meant several things raises. */
-function ambiguousError(
-  ref: string,
-  what: "namespace" | "recipe",
-  candidates: SousRef[]
-): ConfigError {
-  return new ConfigError(
-    `'${ref}' names a ${what} in more than one repository this project trusts:\n` +
-      candidates.map((candidate) => `    ${describeRef(candidate)}`).join("\n") +
-      `\n  Name the repository as well, as 'repository:${ref}', to say which one you mean.`
-  );
-}
-
-/** The error a ref that matched nothing raises, naming what was searched. */
-function unknownError(
-  inputs: CatalogInputs,
-  ref: string,
-  what: "namespace" | "recipe",
-  qualifier: string | undefined
-): ConfigError {
-  if (qualifier !== undefined && !inputs.repos.some((repo) => repo.name === qualifier)) {
-    return new ConfigError(
-      `This project trusts no repository called '${qualifier}', so '${ref}' could not ` +
-        `be looked up.\n` +
-        `  Repositories with an index sous has read: ${describeRepos(inputs)}.`
-    );
-  }
-
-  return new ConfigError(
-    `No repository this project trusts publishes a ${what} called '${ref}'.\n` +
-      `  Repositories with an index sous has read: ${describeRepos(inputs)}.`
-  );
-}
-
-/** The repositories that were searched, in plain language. */
-function describeRepos(inputs: CatalogInputs): string {
-  if (inputs.repos.length === 0) return "none";
-  return inputs.repos.map((repo) => repo.name).join(", ");
-}
-
-/** Sorts namespace listings by namespace, then by repository. */
-function byNamespaceThenRepo(left: NamespaceListing, right: NamespaceListing): number {
-  return left.namespace === right.namespace
-    ? compare(left.repo, right.repo)
-    : compare(left.namespace, right.namespace);
-}
-
-/** Bytewise string ordering, so a listing sorts the same on every machine. */
-function compare(left: string, right: string): number {
-  return left < right ? -1 : left > right ? 1 : 0;
-}