@sous-io/sous 0.2.32 → 0.2.34

package/src/services/ref-resolver/lookups/catalog-lookup.ts

@@ -0,0 +1,23 @@
+import type { SousRef } from "../types.js";
+import { CatalogMatcher, type CatalogRepo } from "./catalog-matcher.js";
+import type { RefLookup, RefMatch } from "./ref-lookup.js";
+
+/**
+ * Answers repositories, namespaces and recipes from a catalog a caller has
+ * already built (which repositories it knows, and what each publishes). It
+ * reads nothing, fetches nothing and never fails.
+ */
+export class CatalogLookup implements RefLookup {
+  private readonly matcher: CatalogMatcher;
+
+  /**
+   * @param repos - The repositories to search, in the order their matches are listed.
+   */
+  constructor(repos: CatalogRepo[]) {
+    this.matcher = new CatalogMatcher(repos);
+  }
+
+  async find(candidate: SousRef): Promise<RefMatch[]> {
+    return this.matcher.match(candidate);
+  }
+}

package/src/services/ref-resolver/lookups/catalog-matcher.ts

@@ -0,0 +1,261 @@
+/**
+ * Matching repositories, namespaces and recipes against a catalog of what is
+ * published. Every lookup that knows repositories (cached indexes, fetched
+ * indexes, the definitions in play) builds a catalog and asks this.
+ *
+ * Names are matched the same way everywhere: the exact spelling first, then
+ * ignoring case, and a name may be a glob pattern. A match is returned in the
+ * spelling the catalog publishes.
+ */
+
+import type { IndexFile } from "../../../lib/repos/formats/index-file.js";
+import { matchName, type NameMatch } from "../glob.js";
+import { refKey } from "../format.js";
+import type { NamespaceRef, RecipeRef, RefLocation, RepoRef, SousRef } from "../types.js";
+import type { RefMatch } from "./ref-lookup.js";
+
+/** One repository, and what it publishes. */
+export type CatalogRepo = {
+  /** The short name this project calls it, when it has one. */
+  name?: string;
+  /** Where it lives, which is how a ref written as a location finds it. */
+  location?: RefLocation;
+  /** Every namespace it publishes. */
+  namespaces: Array<{ name: string; description?: string }>;
+  /** Every recipe it publishes. */
+  recipes: Array<{ namespace: string; name: string; description?: string; path?: string }>;
+};
+
+/**
+ * The catalog entry for one repository's index.
+ *
+ * @param index - The repository's index.
+ * @param repo - What the project knows of the repository: its short name and where it lives.
+ */
+export function catalogRepoOfIndex(
+  index: IndexFile,
+  repo: { name?: string; location?: RefLocation } = {}
+): CatalogRepo {
+  return {
+    ...(repo.name === undefined ? {} : { name: repo.name }),
+    ...(repo.location === undefined ? {} : { location: repo.location }),
+    namespaces: Object.entries(index.namespaces).map(([namespace, declared]) => ({
+      name: namespace,
+      ...(declared?.description === undefined ? {} : { description: declared.description }),
+    })),
+    recipes: Object.entries(index.recipes).map(([key, recipe]) => {
+      const slash = key.indexOf("/");
+      return {
+        namespace: key.slice(0, slash),
+        name: key.slice(slash + 1),
+        path: recipe.path,
+        ...(recipe.description === undefined ? {} : { description: recipe.description }),
+      };
+    }),
+  };
+}
+
+/** The weaker of two matches: one folded part makes the whole thing folded. */
+function both(left: NameMatch, right: NameMatch): NameMatch {
+  if (left === undefined || right === undefined) return undefined;
+  return left === "folded" || right === "folded" ? "folded" : "exact";
+}
+
+/** Matches refs against a catalog, repository by repository, in catalog order. */
+export class CatalogMatcher {
+  /**
+   * @param repos - The repositories to search, in the order their matches are listed.
+   */
+  constructor(private readonly repos: CatalogRepo[]) {}
+
+  /**
+   * Every repository, namespace or recipe in the catalog a candidate names.
+   * Candidates of any other kind match nothing.
+   *
+   * @param candidate - One reading of a written ref.
+   */
+  match(candidate: SousRef): RefMatch[] {
+    const found: Array<RefMatch & { repoIndex: number }> = [];
+
+    this.repos.forEach((repo, repoIndex) => {
+      const add = (ref: SousRef, spelling: NameMatch): void => {
+        if (spelling === undefined) return;
+        found.push({ ref, exactSpelling: spelling === "exact", repoIndex });
+      };
+
+      switch (candidate.kind) {
+        case "repo": {
+          if (candidate.browsed !== undefined) {
+            for (const settled of this.settleBrowsed(candidate, repo)) add(settled, "exact");
+          } else {
+            add(...this.matchRepo(candidate, repo));
+          }
+          break;
+        }
+        case "namespace": {
+          const qualifier = this.qualifies(candidate.repo, repo);
+          for (const namespace of repo.namespaces) {
+            const spelling = both(qualifier, matchName(candidate.name, namespace.name));
+            if (spelling === undefined) continue;
+            add(
+              this.carry(candidate, {
+                kind: "namespace",
+                name: namespace.name,
+                repo: this.knownRepo(repo),
+                ...(namespace.description === undefined ? {} : { description: namespace.description }),
+              }),
+              spelling
+            );
+          }
+          break;
+        }
+        case "recipe": {
+          const qualifier = this.qualifies(candidate.namespace?.repo ?? candidate.repo, repo);
+          for (const recipe of repo.recipes) {
+            const inNamespace =
+              candidate.namespace === undefined
+                ? "exact"
+                : matchName(candidate.namespace.name, recipe.namespace);
+            const spelling = both(
+              both(qualifier, inNamespace),
+              matchName(candidate.name, recipe.name)
+            );
+            if (spelling === undefined) continue;
+            add(this.carry(candidate, this.knownRecipe(repo, recipe)), spelling);
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    });
+
+    return found
+      .sort((left, right) =>
+        left.repoIndex !== right.repoIndex
+          ? left.repoIndex - right.repoIndex
+          : refKey(left.ref) < refKey(right.ref)
+            ? -1
+            : refKey(left.ref) > refKey(right.ref)
+              ? 1
+              : 0
+      )
+      .map(({ ref, exactSpelling }) => ({ ref, exactSpelling }));
+  }
+
+  /** How a repository qualifier matches one catalog repository (no qualifier matches all). */
+  private qualifies(qualifier: RepoRef | undefined, repo: CatalogRepo): NameMatch {
+    if (qualifier === undefined) return "exact";
+    let result: NameMatch = "exact";
+    if (qualifier.name !== undefined) {
+      if (repo.name === undefined) return undefined;
+      result = matchName(qualifier.name, repo.name);
+      if (result === undefined) return undefined;
+    }
+    if (qualifier.location !== undefined) {
+      if (repo.location?.identity !== qualifier.location.identity) return undefined;
+    }
+    return result;
+  }
+
+  /** The repository ref a catalog repository is known as. */
+  private knownRepo(repo: CatalogRepo, revision?: string): RepoRef {
+    return {
+      kind: "repo",
+      ...(repo.name === undefined ? {} : { name: repo.name }),
+      ...(repo.location === undefined ? {} : { location: repo.location }),
+      ...(revision === undefined ? {} : { revision }),
+    };
+  }
+
+  /** The recipe ref a catalog recipe is known as, parents and all. */
+  private knownRecipe(repo: CatalogRepo, recipe: CatalogRepo["recipes"][number], revision?: string): RecipeRef {
+    const namespace: NamespaceRef = {
+      kind: "namespace",
+      name: recipe.namespace,
+      repo: this.knownRepo(repo, revision),
+    };
+    return {
+      kind: "recipe",
+      name: recipe.name,
+      namespace,
+      ...(recipe.description === undefined ? {} : { description: recipe.description }),
+    };
+  }
+
+  /** What a candidate carries over to the known ref it matched: its range and query values. */
+  private carry(candidate: SousRef, known: SousRef): SousRef {
+    return {
+      ...known,
+      ...(candidate.kind === "recipe" && candidate.range !== undefined
+        ? { range: candidate.range }
+        : {}),
+      ...(candidate.vars === undefined ? {} : { vars: candidate.vars }),
+    } as SousRef;
+  }
+
+  /** A repository ref, named by short name or by location. */
+  private matchRepo(candidate: RepoRef, repo: CatalogRepo): [SousRef, NameMatch] {
+    const known = this.knownRepo(repo);
+    if (candidate.name === undefined && candidate.location === undefined) return [known, undefined];
+    return [
+      { ...known, ...(candidate.vars === undefined ? {} : { vars: candidate.vars }) },
+      this.qualifies(candidate, repo),
+    ];
+  }
+
+  /**
+   * What a browser path names in one repository, through the folder each
+   * recipe lives in. The path still carries the branch in front of it (which
+   * may itself hold slashes), so every split is tried: the folder of a recipe,
+   * or anything inside it, names that recipe; a folder holding recipes of
+   * exactly one namespace names that namespace.
+   *
+   * settleBrowsed("main/recipes/workflow/alpha/SKILL.md")
+   * // -> the recipe workflow/alpha, with the revision "main"
+   */
+  private settleBrowsed(candidate: RepoRef, repo: CatalogRepo): SousRef[] {
+    if (candidate.location === undefined || repo.location?.identity !== candidate.location.identity) {
+      return [];
+    }
+    const segments = (candidate.browsed ?? "").split("/").filter((segment) => segment.length > 0);
+    const recipes = repo.recipes
+      .map((recipe) => ({ recipe, path: (recipe.path ?? "").replace(/^\.?\/+|\/+$/g, "") }))
+      .filter((entry) => entry.path.length > 0);
+
+    const range = candidate.range === undefined ? {} : { range: candidate.range };
+    const found = new Map<string, SousRef>();
+
+    // A recipe's folder, or a file inside it. The deepest recipe wins, so a
+    // recipe nested inside another's folder is named by its own path.
+    for (let start = 1; start < segments.length; start++) {
+      const folder = segments.slice(start).join("/");
+      const holding = recipes
+        .filter((entry) => folder === entry.path || folder.startsWith(`${entry.path}/`))
+        .sort((left, right) => right.path.length - left.path.length);
+      const deepest = holding[0];
+      if (deepest === undefined) continue;
+      const revision = segments.slice(0, start).join("/");
+      found.set(`${deepest.recipe.namespace}/${deepest.recipe.name}`, {
+        ...this.knownRecipe(repo, deepest.recipe, revision),
+        ...range,
+      });
+    }
+    if (found.size > 0) return [...found.values()];
+
+    // A folder above recipes: a namespace, when everything under it is one.
+    for (let start = 1; start < segments.length; start++) {
+      const folder = segments.slice(start).join("/");
+      const under = recipes.filter((entry) => entry.path.startsWith(`${folder}/`));
+      const namespaces = new Set(under.map((entry) => entry.recipe.namespace));
+      if (namespaces.size !== 1) continue;
+      const name = [...namespaces][0]!;
+      found.set(name, {
+        kind: "namespace",
+        name,
+        repo: this.knownRepo(repo, segments.slice(0, start).join("/")),
+      });
+    }
+    return [...found.values()];
+  }
+}

package/src/services/ref-resolver/lookups/chained-lookup.ts

@@ -0,0 +1,27 @@
+import type { SousRef } from "../types.js";
+import type { RefLookup, RefMatch } from "./ref-lookup.js";
+
+/**
+ * Asks several lookups in order. The first one that answers a candidate with a
+ * non-empty list wins and the rest are never asked, so a cheap, authoritative
+ * source (a release's record) can sit in front of a broad one (every cached
+ * index). A lookup that throws stops the chain: a failure is never skipped.
+ */
+export class ChainedLookup implements RefLookup {
+  private readonly lookups: RefLookup[];
+
+  /**
+   * @param lookups - The lookups to ask, most authoritative first.
+   */
+  constructor(...lookups: RefLookup[]) {
+    this.lookups = lookups;
+  }
+
+  async find(candidate: SousRef): Promise<RefMatch[]> {
+    for (const lookup of this.lookups) {
+      const matches = await lookup.find(candidate);
+      if (matches.length > 0) return matches;
+    }
+    return [];
+  }
+}

package/src/services/ref-resolver/lookups/env-var-lookup.ts

@@ -0,0 +1,65 @@
+import type { DefinedVariable } from "../../../lib/vars/definition-source.js";
+import { variableCandidates, type LadderContext } from "../../../lib/vars/ladder.js";
+import { bareName } from "../../../lib/vars/names.js";
+import type { SousRef, VariableRef } from "../types.js";
+import type { RefLookup, RefMatch } from "./ref-lookup.js";
+import { variableRefOf } from "./variable-lookup.js";
+
+/**
+ * Answers an environment variable name with the variables it answers.
+ *
+ * A name is held whole and compared in its exact spelling only, because a
+ * variable (`apiUrl`) and an environment variable name can differ only in case
+ * and the spelling typed is the one meant. The names searched are the one each
+ * definition declares (a recipe may bind an existing variable such as
+ * `GITHUB_TOKEN`) plus every generated name on the resolution ladder that is
+ * actually in use in `.sous/.env` or `.sous/.env.local`; generated names are
+ * only searched when in use, because every variable generates several and a
+ * project would otherwise be told that a name nothing has ever set names one of
+ * its variables.
+ */
+export class EnvVarLookup implements RefLookup {
+  private readonly byName = new Map<string, VariableRef[]>();
+
+  /**
+   * @param variables - The variable definitions in play.
+   * @param ladder - The environment layers, which decide which generated names are in use.
+   */
+  constructor(variables: DefinedVariable[], ladder?: LadderContext) {
+    const inUse =
+      ladder === undefined
+        ? new Set<string>()
+        : new Set([...Object.keys(ladder.localEnv), ...Object.keys(ladder.sharedEnv)]);
+
+    for (const defined of variables) {
+      const names = new Set<string>([bareName(defined.definition)]);
+      if (ladder !== undefined) {
+        for (const candidate of variableCandidates(defined, ladder)) {
+          if (inUse.has(candidate.envName)) names.add(candidate.envName);
+        }
+      }
+      for (const name of names) {
+        const answered = this.byName.get(name) ?? [];
+        answered.push(variableRefOf(defined));
+        this.byName.set(name, answered);
+      }
+    }
+  }
+
+  async find(candidate: SousRef): Promise<RefMatch[]> {
+    if (candidate.kind !== "envVar") return [];
+    const variables = this.byName.get(candidate.name);
+    if (variables === undefined) return [];
+    return [
+      {
+        ref: {
+          kind: "envVar",
+          name: candidate.name,
+          variables,
+          ...(candidate.vars === undefined ? {} : { vars: candidate.vars }),
+        },
+        exactSpelling: true,
+      },
+    ];
+  }
+}

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

@@ -0,0 +1,150 @@
+/**
+ * Settling, at release time, a dependency that reads more than one way.
+ *
+ * Most dependencies say exactly what they mean: `workflow/alpha`, or
+ * `github://owner/repo/workflow/alpha`. Two kinds do not: a GitLab URL with
+ * nested groups, which does not say where the project path ends, and a browser
+ * URL copied from a host's file view, which names a folder whose recipe only
+ * that repository's index can say.
+ *
+ * `sous repo release` settles each of them once, by fetching the index of every
+ * candidate repository through the provider layer and keeping the reading whose
+ * index publishes what was named. A network failure fails the release: a
+ * release never falls through to the next reading, because the reading it fell
+ * through to could be the wrong one. Two readings that both publish what is
+ * named are a genuine tie, and an error naming the spelling that reads one way.
+ */
+
+import { ConfigError } from "../../../lib/errors.js";
+import { INDEX_FILENAME } from "../../../lib/repos/formats/common.js";
+import { parseIndexFile, type IndexFile } from "../../../lib/repos/formats/index-file.js";
+import {
+  builtInProviders,
+  providerById,
+  type ProviderOptions,
+  type RepoProvider,
+} from "../../../lib/repos/providers/index.js";
+import { formatRef } from "../format.js";
+import { locationOf } from "../parts.js";
+import type { RefLocation, SousRef } from "../types.js";
+import { CatalogMatcher, catalogRepoOfIndex } from "./catalog-matcher.js";
+import type { RefLookup, RefMatch } from "./ref-lookup.js";
+
+/** Fetches the index of the repository at a location. */
+export type IndexFetcher = (location: RefLocation) => Promise<IndexFile>;
+
+/** What a `FetchedIndexLookup` may be given. */
+export type FetchedIndexLookupOptions = {
+  /** The providers to fetch through. Defaults to the built-ins. */
+  providers?: RepoProvider[];
+  /** Testing seams handed to every index fetch by the default fetcher. */
+  providerOptions?: ProviderOptions;
+  /** Replaces the default fetcher, which goes through the provider layer. */
+  fetchIndex?: IndexFetcher;
+  /** What the ref being settled is called in an error, such as "dependency". Defaults to "ref". */
+  subject?: string;
+};
+
+/** A failure, in a sentence. */
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Answers a located candidate by fetching the index of the repository it names
+ * (once per repository) and matching the candidate against it. A candidate
+ * with no location names no repository to fetch from and matches nothing.
+ */
+export class FetchedIndexLookup implements RefLookup {
+  private readonly providers: RepoProvider[];
+  private readonly fetcher: IndexFetcher;
+  private readonly indexes = new Map<string, Promise<IndexFile>>();
+
+  /**
+   * @param options - The providers and testing seams, or a replacement fetcher.
+   */
+  constructor(private readonly options: FetchedIndexLookupOptions = {}) {
+    this.providers = options.providers ?? builtInProviders();
+    this.fetcher = options.fetchIndex ?? ((location) => this.fetchThroughProvider(location));
+  }
+
+  async find(candidate: SousRef): Promise<RefMatch[]> {
+    const location = locationOf(candidate);
+    if (location === undefined) return [];
+
+    let index: IndexFile;
+    try {
+      index = await this.indexAt(location);
+    } catch (error) {
+      const subject = this.options.subject ?? "ref";
+      const folder = candidate.kind === "repo" && candidate.browsed !== undefined;
+      throw new ConfigError(
+        `the ${subject} reads ${folder ? "as a folder in" : "as something in"} the repository ` +
+          `at ${location.url}, and its index could not be read, so the release cannot settle ` +
+          `what it means. A release never guesses past an index it could not read.\n` +
+          `  ${describe(error)}`
+      );
+    }
+
+    return new CatalogMatcher([catalogRepoOfIndex(index, { location })]).match(candidate);
+  }
+
+  /**
+   * The one reading of a written ref that the fetched indexes confirm: every
+   * reading is looked up, and exactly one may publish what it names.
+   *
+   * @param candidates - Every reading of the written ref.
+   * @returns The one match.
+   * @throws A ConfigError when no repository publishes it, when several do (naming the
+   *   `/*` spelling that reads one way), or when an index could not be fetched.
+   */
+  async settle(candidates: SousRef[]): Promise<RefMatch> {
+    const choices: RefMatch[] = [];
+    for (const candidate of candidates) choices.push(...(await this.find(candidate)));
+
+    if (choices.length === 0) {
+      throw new ConfigError(
+        `no repository it could name publishes what it names. It was read as:\n` +
+          candidates.map((candidate) => `    ${formatRef(candidate, this.providers)}`).join("\n")
+      );
+    }
+    if (choices.length > 1) {
+      const namespace = choices.find((choice) => choice.ref.kind === "namespace") ?? choices[0]!;
+      const written = formatRef(namespace.ref, this.providers);
+      throw new ConfigError(
+        `it names more than one thing, and each of these publishes it:\n` +
+          choices.map((choice) => `    ${formatRef(choice.ref, this.providers)}`).join("\n") +
+          `\n  Write the one you mean. A namespace is written with '/*' after it, as in ` +
+          `'${namespace.ref.kind === "namespace" ? `${written}/*` : written}', and a recipe as ` +
+          `its canonical locator above.`
+      );
+    }
+    return choices[0]!;
+  }
+
+  /**
+   * The index at a location, fetched once per repository.
+   *
+   * @param location - Where the repository lives.
+   */
+  indexAt(location: RefLocation): Promise<IndexFile> {
+    let pending = this.indexes.get(location.identity);
+    if (pending === undefined) {
+      pending = this.fetcher(location);
+      this.indexes.set(location.identity, pending);
+    }
+    return pending;
+  }
+
+  /** Fetches and validates the index at a location, through its provider. */
+  private async fetchThroughProvider(location: RefLocation): Promise<IndexFile> {
+    const provider = providerById(location.provider, this.providers);
+    /* c8 ignore next */
+    if (provider === undefined) throw new Error(`sous has no '${location.provider}' provider.`);
+    const fetched = await provider.fetchIndex(
+      provider.canonicalize(location.url),
+      this.options.providerOptions ?? {}
+    );
+    return parseIndexFile(JSON.parse(fetched.text), `${location.url}/${INDEX_FILENAME}`);
+  }
+}

package/src/services/ref-resolver/lookups/recorded-dependency-lookup.ts

@@ -0,0 +1,62 @@
+import { locationOf } from "../parts.js";
+import type { SousRef } from "../types.js";
+import type { RefLookup, RefMatch } from "./ref-lookup.js";
+
+/** What a repository's index recorded about one dependency, as far as settling needs. */
+export type RecordedDependencies = Record<string, { repo?: string } | undefined>;
+
+/**
+ * Whether what a version's index entry recorded confirms a candidate reading
+ * of one of its dependencies. This is the rule `RecordedDependencyLookup`
+ * answers with, for callers that settle a dependency without waiting.
+ *
+ * @param candidate - One reading of the dependency as the manifest wrote it.
+ * @param recorded - What the declaring version's index entry records, keyed `namespace/recipe`.
+ */
+export function isConfirmedByRecord(
+  candidate: SousRef,
+  recorded: RecordedDependencies | undefined
+): boolean {
+  const identity = locationOf(candidate)?.identity;
+  const records = Object.entries(recorded ?? {}).filter(([, record]) =>
+    identity === undefined ? record?.repo === undefined : record?.repo === identity
+  );
+
+  switch (candidate.kind) {
+    case "repo":
+      return candidate.browsed !== undefined && identity !== undefined && records.length > 0;
+    case "namespace":
+      return records.some(([key]) => key.startsWith(`${candidate.name}/`));
+    case "recipe":
+      return (
+        candidate.namespace !== undefined &&
+        records.some(([key]) => key === `${candidate.namespace!.name}/${candidate.name}`)
+      );
+    default:
+      return false;
+  }
+}
+
+/**
+ * Answers from what a published version's index entry recorded about its
+ * dependencies, and never searches.
+ *
+ * A release settles a dependency that reads more than one way (a GitLab URL
+ * with nested groups, a browser URL) and records the repository it settled on
+ * beside each key it resolved; a consumer reads that record and never probes.
+ * A candidate is confirmed when a record says so: a namespace by a record
+ * under a key inside it, a recipe by a record under its own key, a browser
+ * path by any record carrying its repository. A candidate that names no
+ * location is confirmed by a record that names none, which is a sibling in the
+ * declaring recipe's own repository.
+ */
+export class RecordedDependencyLookup implements RefLookup {
+  /**
+   * @param recorded - What the declaring version's index entry records, keyed `namespace/recipe`.
+   */
+  constructor(private readonly recorded: RecordedDependencies | undefined) {}
+
+  async find(candidate: SousRef): Promise<RefMatch[]> {
+    return isConfirmedByRecord(candidate, this.recorded) ? [{ ref: candidate, exactSpelling: true }] : [];
+  }
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Lookups: what exists, as a queryable object rather than a list.
+ *
+ * A caller that knows what exists (the cached indexes, a release's recorded
+ * dependencies, the variable definitions in play) hands the resolver a lookup,
+ * and the candidate readings narrow to the ones that are actually available.
+ */
+
+import type { SousRef } from "../types.js";
+
+/** One thing a candidate reading turned out to name. */
+export type RefMatch = {
+  /**
+   * The known ref, spelled the way it is published (not the way it was
+   * typed), with every parent it has.
+   */
+  ref: SousRef;
+  /**
+   * True when every part of the candidate matched in exactly the case it was
+   * written. A lookup returns case-insensitive matches too; the resolver keeps
+   * them only when nothing matched exactly.
+   */
+  exactSpelling: boolean;
+};
+
+/**
+ * Answers what a candidate reading names.
+ *
+ * `find` returns an empty array when nothing known matches the candidate, and
+ * throws when the lookup could not find out (an index that could not be
+ * fetched): not finding an answer and failing to look are different things.
+ */
+export interface RefLookup {
+  /**
+   * Every known ref a candidate names.
+   *
+   * @param candidate - One reading of a written ref.
+   */
+  find(candidate: SousRef): Promise<RefMatch[]>;
+}
+
+/**
+ * A lookup that can also answer without waiting, for a caller whose own
+ * interface is synchronous (a template engine resolving a path). It answers
+ * exactly what `find` answers.
+ */
+export interface SyncRefLookup extends RefLookup {
+  /**
+   * Every known ref a candidate names, at once.
+   *
+   * @param candidate - One reading of a written ref.
+   */
+  findSync(candidate: SousRef): RefMatch[];
+}