@sous-io/sous 0.2.32 → 0.2.34

package/src/services/ref-resolver/format.ts

@@ -0,0 +1,197 @@
+/**
+ * Printing a ref: its key (what everything is stored and compared under) and
+ * its canonical written form (how sous prints it).
+ */
+
+import {
+  builtInProviders,
+  providerById,
+  type RepoProvider,
+} from "../../lib/repos/providers/index.js";
+import { repoOf } from "./parts.js";
+import { KIND_LABELS, type RepoRef, type SousRef } from "./types.js";
+
+/**
+ * The part of a key that names the repository: its short name, or its
+ * identity when it was named by location.
+ */
+function repoPart(repo: RepoRef | undefined): string | undefined {
+  if (repo === undefined) return undefined;
+  return repo.name ?? repo.location?.identity;
+}
+
+/**
+ * The path part of a key, without any repository.
+ *
+ * @param ref - Any ref.
+ */
+function pathPart(ref: SousRef): string {
+  switch (ref.kind) {
+    case "repo":
+      return ref.browsed === undefined ? "" : `tree/${ref.browsed}`;
+    case "namespace":
+      return ref.name;
+    case "recipe":
+      return ref.namespace === undefined ? ref.name : `${ref.namespace.name}/${ref.name}`;
+    case "recipeFile":
+      return `${pathPart(ref.recipe)}/${ref.path}`;
+    case "variable": {
+      const recipe = ref.recipe === undefined ? "" : `${pathPart(ref.recipe)}.`;
+      return `${recipe}${ref.name}`;
+    }
+    case "envVar":
+      return ref.name;
+  }
+}
+
+/**
+ * The canonical key of a ref, with its version range and query values left
+ * off, so the same thing is never keyed twice under two spellings. A
+ * repository qualifier is part of the key, because the same recipe name in two
+ * repositories is two things.
+ *
+ * refKey(namespace("workflow")); // -> "workflow"
+ * refKey(recipe("task-files", "workflow", "sous-recipes")); // -> "sous-recipes:workflow/task-files"
+ * refKey(variable("apiUrl", recipe)); // -> "workflow/task-files.apiUrl"
+ *
+ * @param ref - Any ref.
+ */
+export function refKey(ref: SousRef): string {
+  const repo = ref.kind === "envVar" ? undefined : repoPart(repoOf(ref));
+  const rest = pathPart(ref);
+  if (ref.kind === "repo") return repo === undefined ? rest : rest === "" ? repo : `${repo}:${rest}`;
+  return repo === undefined ? rest : `${repo}:${rest}`;
+}
+
+/**
+ * The key of a ref together with its kind, which is what tells a namespace
+ * `workflow` from a repository `workflow` apart.
+ *
+ * @param ref - Any ref.
+ */
+export function refIdentity(ref: SousRef): string {
+  return `${ref.kind} ${refKey(ref)}`;
+}
+
+/**
+ * Writes the repository qualifier in front of what is named inside it: `name:`
+ * for a repository this project knows by short name (whatever else it knows of
+ * it), and the provider's canonical locator for one known only by location.
+ */
+function qualified(
+  repo: RepoRef | undefined,
+  rest: string,
+  providers: RepoProvider[]
+): string {
+  if (repo === undefined) return rest;
+  if (repo.name !== undefined) return rest === "" ? repo.name : `${repo.name}:${rest}`;
+  if (repo.location !== undefined) {
+    const { host, repoPath } = repo.location;
+    const provider = providerById(repo.location.provider, providers);
+    if (provider !== undefined && provider.id !== "local") {
+      return provider.formatLocator(host, repoPath, rest);
+    }
+    return rest === "" ? repo.location.url : `${repo.location.url}/${rest}`;
+  }
+  return rest;
+}
+
+/**
+ * The canonical written form of a ref, which is how sous prints it: the short
+ * form for a short ref and each provider's own locator for a located one, then
+ * the version range, then the query values.
+ *
+ * formatRef(parse("https://github.com/o/r/w/a@^1")[0]); // -> "github://o/r/w/a@^1"
+ *
+ * @param ref - Any ref.
+ * @param providers - The providers that format locators. Defaults to the built-ins.
+ */
+export function formatRef(ref: SousRef, providers: RepoProvider[] = builtInProviders()): string {
+  const body = qualified(ref.kind === "envVar" ? undefined : repoOf(ref), pathPart(ref), providers);
+  const written =
+    ref.kind === "recipe" || ref.kind === "recipeFile" || ref.kind === "repo"
+      ? ref.range
+      : undefined;
+  const range = written === undefined ? "" : `@${written}`;
+  const pairs = Object.entries(ref.vars ?? {}).map(
+    ([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`
+  );
+  return `${body}${range}${pairs.length === 0 ? "" : `?${pairs.join("&")}`}`;
+}
+
+/**
+ * What kind of thing a ref names, in a sentence.
+ *
+ * @param ref - Any ref.
+ */
+export function refKindLabel(ref: SousRef): string {
+  return KIND_LABELS[ref.kind];
+}
+
+/**
+ * How a ref is written to a person, so they can type it back: its key when a
+ * repository's short name qualifies it, and its canonical locator when only a
+ * location does (a ref that has not been matched to a repository this project
+ * knows by name).
+ *
+ * refSpelling(recipe "task-files" in "sous-recipes") // -> "sous-recipes:workflow/task-files"
+ * refSpelling(a recipe at a located repository)      // -> its canonical locator
+ *
+ * @param ref - Any ref.
+ */
+export function refSpelling(ref: SousRef): string {
+  const repo = ref.kind === "envVar" ? undefined : repoOf(ref);
+  if (repo !== undefined && repo.name === undefined && repo.location !== undefined) {
+    return formatRef(ref);
+  }
+  return refKey(ref);
+}
+
+/** The repository a person is told a ref lives in: its short name, or where it lives. */
+function repoLabel(repo: RepoRef | undefined): string {
+  return repo?.name ?? repo?.location?.url ?? "unknown";
+}
+
+/**
+ * Describes one ref in the words a person choosing between several needs: the
+ * fully qualified name, and what it actually means.
+ *
+ * @param ref - A known ref, as a lookup returns it.
+ */
+export function describeRef(ref: SousRef): string {
+  const summary = ref.description === undefined ? "" : `: ${ref.description}`;
+  const key = refSpelling(ref);
+
+  switch (ref.kind) {
+    case "repo": {
+      const where = ref.location?.url;
+      return `${key}  (the repository '${ref.name ?? key}'${where === undefined ? "" : `, at ${where}`})`;
+    }
+    case "namespace":
+      return (
+        `${key}  (the whole namespace '${ref.name}' in the ` +
+        `repository '${repoLabel(ref.repo)}')`
+      );
+    case "recipe":
+      return (
+        `${key}  (the recipe '${ref.name}' in the namespace ` +
+        `'${ref.namespace?.name ?? "unknown"}' of the repository ` +
+        `'${repoLabel(repoOf(ref))}'${summary})`
+      );
+    case "recipeFile":
+      return `${key}  (the file '${ref.path}' of the recipe '${pathPart(ref.recipe)}'${summary})`;
+    case "variable":
+      return (
+        `${key}  (the variable '${ref.name}' of the recipe ` +
+        `'${ref.recipe === undefined ? "unknown" : pathPart(ref.recipe)}'${summary})`
+      );
+    case "envVar": {
+      const first = ref.variables?.[0];
+      const answers =
+        first === undefined
+          ? ""
+          : `answering '${first.name}' of the recipe '${first.recipe === undefined ? "unknown" : pathPart(first.recipe)}'`;
+      return `${ref.name}  (the environment variable${answers === "" ? "" : ` ${answers}`}${summary})`;
+    }
+  }
+}

package/src/services/ref-resolver/glob.ts

@@ -0,0 +1,115 @@
+/**
+ * Names, glob patterns and how a written name is compared with a known one.
+ *
+ * Every name or path part of a ref may be a glob pattern (`*`, `**`, `?`,
+ * `[..]`, `{a,b}`), matched with minimatch. Plain names are compared as
+ * strings. Either way the exact spelling is tried first and ignoring case is
+ * the fallback, so the caller can tell which one matched.
+ */
+
+import { minimatch } from "minimatch";
+
+/** A name as the parser accepts it: kebab-case, in any case. */
+export const NAME_ANY_CASE = /^[a-z][a-z0-9-]*$/i;
+
+/** A name as it is stored: lowercase kebab-case. */
+export const NAME_STORED = /^[a-z][a-z0-9-]*$/;
+
+/** A variable name, as a recipe's author writes it: camelCase. */
+export const VARIABLE_NAME = /^[a-z][a-zA-Z0-9]*$/;
+
+/** An environment variable name: whatever a shell accepts. */
+export const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The characters a glob pattern is made of. */
+const GLOB_CHARS = /[*?[\]{}]/;
+
+/** The characters a glob pattern standing for a name may use. */
+const GLOB_NAME = /^[A-Za-z0-9_\-.*?[\]{},!^]+$/;
+
+/** True when a string holds glob syntax. */
+export function hasGlob(text: string): boolean {
+  return GLOB_CHARS.test(text);
+}
+
+/** True when a string is a glob pattern that could stand for a name. */
+export function isGlobName(text: string): boolean {
+  return hasGlob(text) && GLOB_NAME.test(text);
+}
+
+/**
+ * Splits text at `/`, except inside braces, so `{a/b,c}` stays whole.
+ *
+ * splitSegments("a/{b/c,d}/e"); // -> ["a", "{b/c,d}", "e"]
+ *
+ * @param text - The text to split.
+ */
+export function splitSegments(text: string): string[] {
+  const segments: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const character of text) {
+    if (character === "{") depth += 1;
+    if (character === "}" && depth > 0) depth -= 1;
+    if (character === "/" && depth === 0) {
+      segments.push(current);
+      current = "";
+      continue;
+    }
+    current += character;
+  }
+  segments.push(current);
+  return segments;
+}
+
+/** How a written name matched a known one. */
+export type NameMatch = "exact" | "folded" | undefined;
+
+/**
+ * Whether a written name (or glob pattern) matches a known one: exactly, only
+ * ignoring case, or not at all.
+ *
+ * matchName("Workflow", "workflow"); // -> "folded"
+ * matchName("work*", "workflow"); // -> "exact"
+ *
+ * @param written - The name or pattern as written.
+ * @param known - The name as it is spelled where it is published.
+ */
+export function matchName(written: string, known: string): NameMatch {
+  if (hasGlob(written)) {
+    if (minimatch(known, written, { dot: true })) return "exact";
+    return minimatch(known, written, { dot: true, nocase: true }) ? "folded" : undefined;
+  }
+  if (written === known) return "exact";
+  return written.toLowerCase() === known.toLowerCase() ? "folded" : undefined;
+}
+
+/**
+ * The names that match a written one: those spelled exactly as written, or,
+ * when there is none, those that differ only in case.
+ *
+ * matchNames("Workflow", ["workflow", "tooling"]); // -> ["workflow"]
+ * matchNames("workflow", ["workflow", "Workflow"]); // -> ["workflow"]
+ *
+ * @param written - The name as written.
+ * @param names - The names it could mean.
+ */
+export function matchNames(written: string, names: Iterable<string>): string[] {
+  const all = [...names];
+  const exact = all.filter((name) => matchName(written, name) === "exact");
+  if (exact.length > 0) return exact;
+  return all.filter((name) => matchName(written, name) === "folded");
+}
+
+/**
+ * Orders two strings by their UTF-8 bytes, so the order is the same on every
+ * machine whatever its locale.
+ *
+ * ["b", "B", "a"].sort(compareBytewise); // -> ["B", "a", "b"]
+ *
+ * @param left - The first string.
+ * @param right - The second string.
+ */
+export function compareBytewise(left: string, right: string): number {
+  return Buffer.compare(Buffer.from(left), Buffer.from(right));
+}

package/src/services/ref-resolver/hash-names.ts

@@ -0,0 +1,155 @@
+/**
+ * The `#` names: the built-in names an include line, a `{% render %}` path or
+ * an `entryGlob` may start with, such as `#project`.
+ *
+ * `~` keeps meaning the home directory and recipe namespaces; `#` is for names
+ * sous or a plugin provides. Each name is registered once, with the directories
+ * it stands for, and a registration that repeats a name is an error naming both
+ * registrants. A later layer registers a view the same way.
+ *
+ * A plugin adds a name by binding one more `HashName` under
+ * `REF_TOKENS.HashName` on a container it builds with `createRefContainer()`.
+ */
+
+import { ConfigError } from "../../lib/errors.js";
+import { compareBytewise } from "./glob.js";
+import { makeInjectable } from "./injectable.js";
+import { REF_TOKENS } from "./tokens.js";
+
+/** One file a view lists: where it sits in the view, and the real file behind it. */
+export interface ViewFile {
+  /** The path inside the view, without the `#name/` prefix, with `/` separators. */
+  readonly path: string;
+  /** The real file's absolute path. */
+  readonly file: string;
+}
+
+/** What a view needs to know about the project to list its files. */
+export interface HashViewContext {
+  /** The project's `.sous/` directory. */
+  sousDir: string;
+  /** The environment to read; decides where the recipe store is. */
+  env?: NodeJS.ProcessEnv;
+  /** The merged project config, read for the `recipes` key. */
+  settings: {
+    recipes?: { memories?: { first?: string[] | undefined; exclude?: string[] | undefined } };
+  };
+}
+
+/** One `#` name and what it stands for. */
+export interface HashName {
+  /** The name without its `#`: lowercase kebab-case, such as `project`. */
+  readonly name: string;
+  /** Who registers it, for the error a duplicate raises (`sous`, or a plugin's name). */
+  readonly registeredBy: string;
+  /** What the name is, in one sentence. */
+  readonly description: string;
+  /**
+   * The directories the name stands for, in the order they are tried. A path
+   * after the name is looked up under each in turn, the first that exists
+   * wins. Empty when the name has nothing to stand for in this project.
+   *
+   * @param scope - The settings scope the project's paths come from.
+   */
+  bases(scope: Record<string, string>): string[];
+  /**
+   * A view lists virtual files instead of standing for directories: an include
+   * of `#name/<glob>` selects among the listed paths and includes the real
+   * files behind them, in the listed order. A view has no bases.
+   *
+   * @param context - The project the files are listed for.
+   */
+  view?(context: HashViewContext): ViewFile[];
+}
+
+/** The characters a registered name may hold. */
+const VALID_NAME = /^[a-z][a-z0-9-]*$/;
+
+/** The built-in `#project`: the consuming project's root. */
+export class ProjectHashName implements HashName {
+  readonly name = "project";
+  readonly registeredBy = "sous";
+  readonly description = "the root directory of the project being built.";
+
+  bases(scope: Record<string, string>): string[] {
+    return scope.projectRoot ? [scope.projectRoot] : [];
+  }
+}
+
+makeInjectable(ProjectHashName);
+
+/** Every registered `#` name. */
+export class HashNameRegistry {
+  private readonly entries = new Map<string, HashName>();
+
+  /**
+   * @param names - The names to register, each once.
+   * @throws A ConfigError when a name is invalid or registered twice.
+   */
+  constructor(names: HashName[] = []) {
+    for (const entry of names) this.register(entry);
+  }
+
+  /**
+   * Adds a name.
+   *
+   * @param entry - The name to add.
+   * @throws A ConfigError naming both registrants when the name is already taken.
+   */
+  register(entry: HashName): void {
+    if (!VALID_NAME.test(entry.name)) {
+      throw new ConfigError(
+        `The name '#${entry.name}' registered by '${entry.registeredBy}' is invalid: a name is ` +
+          "lowercase kebab-case, a letter then letters, digits or hyphens."
+      );
+    }
+    const existing = this.entries.get(entry.name);
+    if (existing !== undefined) {
+      throw new ConfigError(
+        `The name '#${entry.name}' is registered twice: by '${existing.registeredBy}' and by ` +
+          `'${entry.registeredBy}'.`
+      );
+    }
+    this.entries.set(entry.name, entry);
+  }
+
+  /** The registered name, or undefined. */
+  get(name: string): HashName | undefined {
+    return this.entries.get(name);
+  }
+
+  /** Every registered name, sorted. */
+  list(): HashName[] {
+    return [...this.entries.values()].sort((left, right) => compareBytewise(left.name, right.name));
+  }
+
+  /**
+   * Every view's listed files, keyed by the name with its `#`.
+   *
+   * @param context - The project the files are listed for.
+   */
+  viewMap(context: HashViewContext): Record<string, ViewFile[]> {
+    const map: Record<string, ViewFile[]> = {};
+    for (const entry of this.list()) {
+      if (entry.view !== undefined) map[`#${entry.name}`] = entry.view(context);
+    }
+    return map;
+  }
+
+  /**
+   * The alias map the registered names make for a project: `#name` to its
+   * directories, leaving out a name with none.
+   *
+   * @param scope - The settings scope the project's paths come from.
+   */
+  aliasMap(scope: Record<string, string>): Record<string, string[]> {
+    const map: Record<string, string[]> = {};
+    for (const entry of this.list()) {
+      const bases = entry.bases(scope);
+      if (bases.length > 0) map[`#${entry.name}`] = bases;
+    }
+    return map;
+  }
+}
+
+makeInjectable(HashNameRegistry, [{ multi: REF_TOKENS.HashName }]);

package/src/services/ref-resolver/index.ts

@@ -0,0 +1,55 @@
+/**
+ * The ref resolver service: how every sous command and template turns a
+ * written ref into the thing it names.
+ *
+ * Import from here. `types.ts` says what a ref is, the parser reads every way a
+ * text can be one, a pruner per place says which readings count there, a
+ * lookup says which exist, `RefResolverService` runs the three in order, and
+ * `RefPickerService` settles which meaning a run proceeds with.
+ *
+ * `EnvVarLookup` is not exported here. It reads the variable ladder, which
+ * reaches config discovery, and config discovery reaches this module through
+ * the recipe formats, so exporting it from the barrel would make an import
+ * cycle that fails at load time. Import it from `lookups/env-var-lookup.js`.
+ */
+
+export * from "./source.js";
+export * from "./types.js";
+export * from "./parts.js";
+export * from "./glob.js";
+export * from "./location.js";
+export * from "./format.js";
+export * from "./tokens.js";
+export * from "./hash-names.js";
+export * from "./injectable.js";
+export * from "./parser/partial-ref.js";
+export * from "./parser/ref-parser.js";
+export * from "./parser/query-splitter.js";
+export * from "./parser/range-splitter.js";
+export * from "./parser/location-splitter.js";
+export * from "./parser/repo-qualifier-splitter.js";
+export * from "./parser/name-path-splitter.js";
+export * from "./parser/env-var-splitter.js";
+export * from "./pruners/ref-pruner.js";
+export * from "./pruners/rule-helpers.js";
+export * from "./pruners/command-line-pruner.js";
+export * from "./pruners/stored-key-pruner.js";
+export * from "./pruners/manifest-pruner.js";
+export * from "./pruners/include-pruner.js";
+export * from "./lookups/ref-lookup.js";
+export * from "./lookups/chained-lookup.js";
+export * from "./lookups/catalog-matcher.js";
+export * from "./lookups/catalog-lookup.js";
+export * from "./lookups/cached-index-lookup.js";
+export * from "./lookups/recorded-dependency-lookup.js";
+export * from "./lookups/fetched-index-lookup.js";
+export * from "./lookups/variable-lookup.js";
+export * from "./ref-resolve-arguments.js";
+export * from "./ref-resolve-result.js";
+export * from "./ref-resolver-service.js";
+export * from "./ref-picker-service.js";
+export * from "./ref-report.js";
+export * from "./named-refs.js";
+export * from "./dependency.js";
+export * from "./ref-helpers.js";
+export * from "./container.js";

package/src/services/ref-resolver/injectable.ts

@@ -0,0 +1,36 @@
+/**
+ * Marking a class as injectable without decorator syntax.
+ *
+ * sous runs TypeScript through tsx, and the published `bin/run.js` registers
+ * tsx from the directory a command runs in, so the `experimentalDecorators`
+ * flag in this repository's tsconfig does not reach it; esbuild also emits no
+ * decorator metadata. Inversify's decorators are plain functions, though, so
+ * calling them here marks every constructor parameter with its token
+ * explicitly and needs neither a compiler flag nor `reflect-metadata`.
+ */
+
+import { decorate, inject, injectable, multiInject } from "inversify";
+
+/** One constructor parameter: a token bound once, or a token bound many times. */
+export type ConstructorParameter = symbol | { multi: symbol };
+
+/**
+ * Marks a class injectable and names the token of every constructor parameter,
+ * in order.
+ *
+ * makeInjectable(RefParser, [{ multi: REF_TOKENS.Splitter }]);
+ *
+ * @param target - The class.
+ * @param parameters - The token of each constructor parameter, in order.
+ */
+export function makeInjectable(
+  target: new (...args: never[]) => unknown,
+  parameters: ConstructorParameter[] = []
+): void {
+  decorate(injectable(), target);
+  parameters.forEach((parameter, index) => {
+    const decorator =
+      typeof parameter === "symbol" ? inject(parameter) : multiInject(parameter.multi);
+    decorate(decorator, target, index);
+  });
+}

package/src/services/ref-resolver/location.ts

@@ -0,0 +1,62 @@
+/**
+ * Building a `RefLocation`: where a repository lives, in the form every ref
+ * and every machine-wide key agrees on.
+ */
+
+import { repoIdentity } from "../../lib/repos/identity.js";
+import {
+  requireProvider,
+  type RepoProvider,
+} from "../../lib/repos/providers/index.js";
+import type { RefLocation } from "./types.js";
+
+/**
+ * Where one repository lives, or undefined when its provider cannot take the
+ * path apart (a path of one segment, say).
+ *
+ * @param provider - The provider that reads the location.
+ * @param host - The repository's host.
+ * @param repoPath - The repository's path on that host.
+ */
+export function locationFor(
+  provider: RepoProvider,
+  host: string,
+  repoPath: string
+): RefLocation | undefined {
+  const url = `https://${host}/${repoPath}`;
+  try {
+    return {
+      provider: provider.id,
+      host,
+      repoPath,
+      identity: repoIdentity(provider.canonicalize(url)),
+      url,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Where the repository at a configured URL lives, or undefined when no
+ * provider recognizes it. The location's `url` is the URL as the project
+ * configured it, which is what a person is shown.
+ *
+ * @param url - The repository's URL, as a project's config records it.
+ * @param providers - The providers to ask. Defaults to the built-ins.
+ */
+export function locationFromUrl(url: string, providers?: RepoProvider[]): RefLocation | undefined {
+  try {
+    const provider = requireProvider(url, undefined, providers);
+    const canonical = provider.canonicalize(url);
+    return {
+      provider: provider.id,
+      host: canonical.host,
+      repoPath: `${canonical.owner}/${canonical.name}`,
+      identity: repoIdentity(canonical),
+      url,
+    };
+  } catch {
+    return undefined;
+  }
+}

package/src/services/ref-resolver/lookups/cached-index-lookup.ts

@@ -0,0 +1,53 @@
+import type { IndexFile } from "../../../lib/repos/formats/index-file.js";
+import { locationFromUrl } from "../location.js";
+import type { SousRef } from "../types.js";
+import { CatalogMatcher, catalogRepoOfIndex, type CatalogRepo } from "./catalog-matcher.js";
+import type { RefLookup, RefMatch } from "./ref-lookup.js";
+
+/** What a `CachedIndexLookup` needs to know beyond the indexes themselves. */
+export type CachedIndexLookupOptions = {
+  /**
+   * The repositories' short names, in the order their matches should be
+   * listed: the built-in repository first, then the ones the config names.
+   * Defaults to the order the indexes were added to the map.
+   */
+  order?: readonly string[];
+  /**
+   * Where each repository lives, by short name. It is how a ref written as a
+   * location (a URL, a locator, a URL copied from the browser) finds the
+   * repository whatever short name this project gave it.
+   */
+  urls?: Record<string, string | undefined>;
+};
+
+/**
+ * Answers repositories, namespaces and recipes from the repository indexes
+ * already on this machine. It reads nothing, fetches nothing and never fails:
+ * a candidate no index publishes simply has no match.
+ */
+export class CachedIndexLookup implements RefLookup {
+  private readonly matcher: CatalogMatcher;
+
+  /**
+   * @param indexes - Each repository's cached index, keyed by short name.
+   * @param options - The listing order, and where each repository lives.
+   */
+  constructor(indexes: Map<string, IndexFile>, options: CachedIndexLookupOptions = {}) {
+    const order = options.order ?? [...indexes.keys()];
+    const repos: CatalogRepo[] = [];
+
+    for (const name of order) {
+      const index = indexes.get(name);
+      if (index === undefined) continue;
+      const url = options.urls?.[name];
+      const location = url === undefined ? undefined : locationFromUrl(url);
+
+      repos.push(catalogRepoOfIndex(index, { name, ...(location === undefined ? {} : { location }) }));
+    }
+    this.matcher = new CatalogMatcher(repos);
+  }
+
+  async find(candidate: SousRef): Promise<RefMatch[]> {
+    return this.matcher.match(candidate);
+  }
+}