@sous-io/sous 0.2.32 → 0.2.34

package/src/services/ref-resolver/ref-picker-service.ts

@@ -0,0 +1,204 @@
+/**
+ * Settling on one of the things a ref could have meant.
+ *
+ * Resolving is separate from choosing on purpose: the resolver is pure and
+ * tells the caller everything a ref could have meant, and this is the one place
+ * that decides which of them the run proceeds with. Every command that takes a
+ * ref goes through it, so a word that means two things behaves the same
+ * everywhere:
+ *
+ *   - one match proceeds, and what it resolved to is written as the facts about
+ *     it followed by one sentence, so the reader sees what the word they typed
+ *     actually meant;
+ *   - several matches are offered as a list to choose from;
+ *   - `--accept-first` takes the first one in the documented listing order;
+ *   - a run with no terminal fails, naming the question it could not ask and
+ *     the flag that would have answered it (`src/lib/interactive.ts` holds that
+ *     rule, and every prompt in sous is gated by it).
+ */
+
+import { makeInjectable } from "./injectable.js";
+import { ConfigError } from "../../lib/errors.js";
+import { nonInteractiveError } from "../../lib/interactive.js";
+import {
+  formatResolvedReference,
+  type ResolvedReferenceFacts,
+} from "./ref-report.js";
+import { formatParagraph, log } from "../../utils/formatting.js";
+import { askChoice } from "../../utils/prompts.js";
+import { describeRef, refKey, refKindLabel, refSpelling } from "./format.js";
+import { namespaceOf, recipeOf, repoOf } from "./parts.js";
+import type { SousRef } from "./types.js";
+
+/** The flag that answers "which one did you mean?" ahead of time. */
+export const ACCEPT_FIRST_FLAG = "--accept-first";
+
+/** How `RefPickerService.pick` should behave. */
+export class RefPickArguments {
+  /** The ref exactly as it was written, for every message. */
+  readonly search: string;
+  /** Whether a question may be asked. A run that may not fails instead. */
+  readonly interactive: boolean;
+  /** Take the first match rather than asking, because `--accept-first` was passed. */
+  readonly acceptFirst: boolean;
+  /** The question to ask when there is more than one match. */
+  readonly prompt?: string;
+  /**
+   * Write the facts about what the ref resolved to. On by default; a caller
+   * that reports the resolution itself turns it off, and is still told when
+   * `--accept-first` settled an ambiguous word.
+   */
+  readonly announce: boolean;
+  /** Extra lines for the error a ref that matched nothing raises. */
+  readonly details: string[];
+  /** Where a resolution is reported. Defaults to the console. */
+  readonly write: (message: string) => void;
+  /** How the choice is asked. Defaults to the shared choice prompt. */
+  readonly choose?: (message: string, matches: SousRef[]) => Promise<SousRef>;
+
+  /**
+   * @param init - What was searched for, and whether a question may be asked.
+   */
+  constructor(init: {
+    search: string;
+    interactive: boolean;
+    acceptFirst?: boolean;
+    prompt?: string;
+    announce?: boolean;
+    details?: string[];
+    write?: (message: string) => void;
+    choose?: (message: string, matches: SousRef[]) => Promise<SousRef>;
+  }) {
+    this.search = init.search;
+    this.interactive = init.interactive;
+    this.acceptFirst = init.acceptFirst ?? false;
+    if (init.prompt !== undefined) this.prompt = init.prompt;
+    this.announce = init.announce ?? true;
+    this.details = init.details ?? [];
+    this.write = init.write ?? ((message: string) => log(message));
+    if (init.choose !== undefined) this.choose = init.choose;
+  }
+}
+
+/**
+ * The facts one resolved ref carries, ready for `formatResolvedReference`.
+ *
+ * The ref knows what it is; this decides which of its fields are facts worth
+ * showing. A repository's own name is already the resolved spelling, so it is
+ * not repeated as a line of its own. What a ref resolves to is always its
+ * fully qualified key; for an environment variable name that is the key of the
+ * variable it answers, because that is what the rest of the run proceeds with.
+ *
+ * @param ref - The ref the run proceeds with.
+ * @param search - The ref exactly as it was written.
+ * @param reason - The closing sentence, when the caller has one of its own.
+ */
+export function resolvedRefFacts(
+  ref: SousRef,
+  search: string,
+  reason?: string
+): ResolvedReferenceFacts {
+  const subject = ref.kind === "envVar" ? (ref.variables?.[0] ?? ref) : ref;
+  const resolvedTo = refKey(subject);
+  const repoName = repoOf(subject)?.name;
+  const recipe = recipeOf(subject);
+  const namespace = namespaceOf(subject);
+
+  return {
+    search,
+    resolvedTo,
+    kind: refKindLabel(ref),
+    ...(subject.kind === "variable" ? { variable: subject.name } : {}),
+    ...(recipe === undefined || subject.kind === "namespace" ? {} : { recipe: recipe.name }),
+    ...(namespace === undefined ? {} : { namespace: namespace.name }),
+    ...(repoName === undefined || repoName === resolvedTo ? {} : { repository: repoName }),
+    ...(ref.kind === "repo" && ref.location !== undefined ? { location: ref.location.url } : {}),
+    ...(ref.kind !== "repo" && subject.description !== undefined
+      ? { description: subject.description }
+      : {}),
+    ...(reason === undefined ? {} : { reason }),
+  };
+}
+
+/** Chooses the one ref a run proceeds with. */
+export class RefPickerService {
+  /**
+   * The one ref a run proceeds with.
+   *
+   * @param matches - What the ref could have meant, in listing order.
+   * @param args - What was searched for, and whether a question may be asked.
+   * @returns The ref the run proceeds with.
+   */
+  async pick(matches: SousRef[], args: RefPickArguments): Promise<SousRef> {
+    if (matches.length === 0) {
+      throw new ConfigError(
+        [`Nothing called '${args.search}' was found.`, ...args.details].join("\n")
+      );
+    }
+
+    const first = matches[0]!;
+
+    if (matches.length === 1) {
+      if (args.announce) this.announce(args, first);
+      return first;
+    }
+
+    if (args.acceptFirst) {
+      const reason =
+        `'${args.search}' named ${matches.length} things, and ` +
+        `'${ACCEPT_FIRST_FLAG}' was passed, so the first one listed is being used.`;
+
+      // A caller that reports the resolution itself still has to be told that the
+      // word was ambiguous, so the sentence is written even when the facts are not.
+      if (args.announce) {
+        this.announce(args, first, reason);
+      } else {
+        for (const line of formatParagraph(reason)) args.write(line);
+      }
+      return first;
+    }
+
+    if (!args.interactive) {
+      // The example is a spelling that says more than what was typed, so a
+      // ref that is already its own fully qualified name is not offered back
+      // unchanged.
+      const example = refSpelling(
+        matches.find((match) => refSpelling(match) !== args.search) ?? first
+      );
+
+      throw nonInteractiveError({
+        prompt: `which '${args.search}' you meant`,
+        remedy:
+          `write the full reference (for example '${example}'), or pass ` +
+          `'${ACCEPT_FIRST_FLAG}' to take the first candidate listed above.`,
+        details: [
+          `'${args.search}' matched ${matches.length} things:`,
+          ...matches.map((match) => `  ${describeRef(match)}`),
+        ],
+      });
+    }
+
+    const choose =
+      args.choose ??
+      ((message: string, offered: SousRef[]) =>
+        askChoice(
+          message,
+          offered.map((match) => ({ name: describeRef(match), value: match }))
+        ));
+
+    return choose(args.prompt ?? `Which '${args.search}' did you mean?`, matches);
+  }
+
+  /**
+   * Writes what a ref resolved to, as the key and value list every other set
+   * of facts in the CLI is written as, followed by one sentence saying why that
+   * candidate won.
+   */
+  private announce(args: RefPickArguments, ref: SousRef, reason?: string): void {
+    for (const line of formatResolvedReference(resolvedRefFacts(ref, args.search, reason))) {
+      args.write(line);
+    }
+  }
+}
+
+makeInjectable(RefPickerService);

package/src/{lib/repos/reference-report.ts → services/ref-resolver/ref-report.ts}

@@ -6,8 +6,8 @@
  * resolved to is a set of facts, so it is written as the same key and value
  * list every other set of facts in the CLI is written as, with one short
  * sentence after it saying why that candidate won. One function builds it, so
- * every command that resolves a reference reports it the same way; `pickReference`
- * in `src/lib/refs/pick.ts` is the single caller, which is how every command gets it.
+ * every command that resolves a reference reports it the same way; `RefPickerService`
+ * in `ref-picker-service.ts` is the single caller, which is how every command gets it.
  */
 
 import {
@@ -17,8 +17,6 @@ import {
   wrapText,
   type VariableEntry,
 } from "../../utils/formatting.js";
-import { SCOPE_LABELS, SousScope } from "../refs/scopes.js";
-import type { ReferenceMatch } from "../refs/find.js";
 
 /** What a resolved reference is, in the words the report shows. */
 export interface ResolvedReferenceFacts {
@@ -84,39 +82,3 @@ export function formatResolvedReference(facts: ResolvedReferenceFacts): string[]
 
   return lines;
 }
-
-/**
- * The facts one match carries, ready for `formatResolvedReference`.
- *
- * The match knows what it is; this decides which of its fields are facts worth
- * showing. A repository's detail is where it lives rather than a summary of it,
- * and a repository's own name is already the resolved spelling, so neither is
- * repeated as a line of its own. What a match resolves to is always its fully
- * qualified key, including for an environment variable name, because the key is
- * what the rest of the run proceeds with.
- *
- * @param match - The match the run proceeds with.
- * @param search - The reference exactly as it was written.
- * @param reason - The closing sentence, when the caller has one of its own.
- */
-export function resolvedReferenceFacts(
-  match: ReferenceMatch,
-  search: string,
-  reason?: string
-): ResolvedReferenceFacts {
-  const isRepository = match.scope === SousScope.Repository;
-  const resolvedTo = match.key;
-
-  return {
-    search,
-    resolvedTo,
-    kind: SCOPE_LABELS[match.scope],
-    ...(match.variable === undefined ? {} : { variable: match.variable }),
-    ...(match.recipe === undefined ? {} : { recipe: match.recipe }),
-    ...(match.namespace === undefined ? {} : { namespace: match.namespace }),
-    ...(match.repo === undefined || match.repo === resolvedTo ? {} : { repository: match.repo }),
-    ...(isRepository && match.detail !== undefined ? { location: match.detail } : {}),
-    ...(!isRepository && match.detail !== undefined ? { description: match.detail } : {}),
-    ...(reason === undefined ? {} : { reason }),
-  };
-}

package/src/services/ref-resolver/ref-resolve-arguments.ts

@@ -0,0 +1,47 @@
+import type { RefLookup } from "./lookups/ref-lookup.js";
+import { RefSource } from "./source.js";
+import type { RefKind } from "./types.js";
+
+/** What `RefResolverService.resolve` is asked. */
+export class RefResolveArguments {
+  /** The ref exactly as it was written. */
+  readonly input: string;
+  /** Where it was written, which decides the forms allowed. */
+  readonly from: RefSource;
+  /**
+   * What exists. When given, the readings narrow to the ones it knows, spelled
+   * the way they are published; when absent, the readings the place allows are
+   * returned as they were read.
+   */
+  readonly lookup?: RefLookup;
+  /**
+   * The kinds of ref the caller accepts. Readings of any other kind are set
+   * aside before the lookup is asked, so a word that is a repository exactly
+   * and a namespace only ignoring case is still found as the namespace by a
+   * caller that accepts namespaces alone.
+   */
+  readonly kinds?: readonly RefKind[];
+  /**
+   * True when a ref the place refuses in every reading (an empty word, a path
+   * of three segments) names nothing instead of raising the refusal. A command
+   * that takes any word and answers "nothing called that was found" uses it.
+   */
+  readonly refusedIsEmpty: boolean;
+
+  /**
+   * @param init - The ref, where it was written (the command line by default), what exists, the kinds accepted, and whether a refused ref names nothing.
+   */
+  constructor(init: {
+    input: string;
+    from?: RefSource;
+    lookup?: RefLookup;
+    kinds?: readonly RefKind[];
+    refusedIsEmpty?: boolean;
+  }) {
+    this.input = init.input;
+    this.from = init.from ?? RefSource.CommandLine;
+    if (init.lookup !== undefined) this.lookup = init.lookup;
+    if (init.kinds !== undefined) this.kinds = init.kinds;
+    this.refusedIsEmpty = init.refusedIsEmpty ?? false;
+  }
+}

package/src/services/ref-resolver/ref-resolve-result.ts

@@ -0,0 +1,36 @@
+import type { DroppedRef } from "./pruners/ref-pruner.js";
+import type { SousRef } from "./types.js";
+
+/** What `RefResolverService.resolve` found. */
+export class RefResolveResult {
+  /**
+   * @param input - The ref exactly as it was written.
+   * @param refs - The refs it names, best first: the more qualified the spelling that
+   *   matched, the earlier. Empty when a lookup knew none of the readings.
+   * @param dropped - The readings the place refused, with the reason for each.
+   * @param warnings - Sentences about readings that were kept all the same.
+   * @param usedLookup - True when `refs` were narrowed against what exists.
+   */
+  constructor(
+    readonly input: string,
+    readonly refs: SousRef[],
+    readonly dropped: DroppedRef[],
+    readonly warnings: string[],
+    readonly usedLookup: boolean
+  ) {}
+
+  /** True when exactly one ref is left, so the caller has nothing to decide. */
+  get isUnique(): boolean {
+    return this.refs.length === 1;
+  }
+
+  /** True when no ref is left. */
+  get isEmpty(): boolean {
+    return this.refs.length === 0;
+  }
+
+  /** The best ref, or undefined when none is left. */
+  first(): SousRef | undefined {
+    return this.refs[0];
+  }
+}

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

@@ -0,0 +1,323 @@
+/**
+ * The ref resolver: parse a written ref, prune it by where it was written,
+ * and, when the caller knows what exists, narrow it to what is there.
+ *
+ * It orchestrates three parts that know nothing of one another: a `RefParser`
+ * (every reading of the text), a `RefPruner` per place (which readings that
+ * place allows) and, per call, a `RefLookup` (which readings exist). What to do
+ * about a ref that is still ambiguous, and how to find the ref inside the text
+ * around it, are the caller's decisions; the helpers here and in
+ * `ref-helpers.ts` assist with both.
+ */
+
+import { makeInjectable } from "./injectable.js";
+import { REF_TOKENS } from "./tokens.js";
+import { ConfigError } from "../../lib/errors.js";
+import { refIdentity } from "./format.js";
+import type { RefLookup, RefMatch, SyncRefLookup } from "./lookups/ref-lookup.js";
+import { repoOf } from "./parts.js";
+import type { RefParser } from "./parser/ref-parser.js";
+import { DroppedRef, type RefPruner } from "./pruners/ref-pruner.js";
+import { RefResolveArguments } from "./ref-resolve-arguments.js";
+import { RefResolveResult } from "./ref-resolve-result.js";
+import { RefSource } from "./source.js";
+import { REF_KINDS, type SousRef } from "./types.js";
+
+/** One ref found inside a longer text. */
+export type RefInString = {
+  /** The text that parsed, with the punctuation around it taken off. */
+  text: string;
+  /** Where it starts in the string. */
+  index: number;
+  /** What it resolved to. */
+  result: RefResolveResult;
+};
+
+/**
+ * How qualified the spelling that produced a candidate was. Lower is more
+ * specific, and the listing order follows it: a fully qualified ref first, then
+ * a partly qualified one, then a bare name, and an environment variable name
+ * last (the least likely reading of a plain word).
+ *
+ * @param candidate - One reading of a written ref.
+ */
+export function qualificationOf(candidate: SousRef): number {
+  if (candidate.kind === "envVar") return 3;
+  if (candidate.kind === "repo" || repoOf(candidate) !== undefined) return 0;
+  const partial =
+    (candidate.kind === "recipe" && candidate.namespace !== undefined) ||
+    candidate.kind === "recipeFile" ||
+    (candidate.kind === "variable" && candidate.recipe !== undefined);
+  return partial ? 1 : 2;
+}
+
+/** Resolves written refs. */
+export class RefResolverService {
+  /**
+   * @param parser - Reads every way a text can be a ref.
+   * @param pruners - Decide, one place each, which readings count there.
+   */
+  constructor(
+    private readonly parser: RefParser,
+    private readonly pruners: RefPruner[]
+  ) {}
+
+  /**
+   * Parses a ref and prunes it by where it was written, with no lookup.
+   *
+   * @param input - The ref exactly as it was written.
+   * @param from - Where it was written.
+   * @throws A ConfigError listing every reason when the place refuses every reading.
+   */
+  parse(input: string, from: RefSource = RefSource.CommandLine): RefResolveResult {
+    const { kept, dropped, warnings, place } = this.prune(input, from);
+    if (kept.length === 0) throw this.refusal(input, place, dropped);
+    return new RefResolveResult(input, this.order(kept.map((ref) => ({ ref, rank: ref }))), dropped, warnings, false);
+  }
+
+  /**
+   * Parses a ref, prunes it by where it was written and, when a lookup is
+   * given, narrows it to what exists. When `kinds` is given, readings of other
+   * kinds are set aside first, and so are the matches of other kinds. A browser
+   * URL is the one reading that is a repository until a lookup settles it into
+   * the namespace or recipe it names, so it is kept for a caller that accepts
+   * namespaces or recipes.
+   *
+   * With a lookup, every kept reading is asked; the exact-spelling matches are
+   * kept when there are any, and the case-insensitive ones otherwise; matches
+   * are de-duplicated and returned in the spelling they are published in. A
+   * ref nothing knows comes back with no refs; that is for the caller to
+   * report. A lookup that could not find out throws.
+   *
+   * @param args - The ref, where it was written, and what exists.
+   * @throws A ConfigError listing every reason when the place refuses every reading.
+   */
+  async resolve(args: RefResolveArguments): Promise<RefResolveResult> {
+    const early = this.beginResolve(args);
+    if ("result" in early) return early.result;
+    const found: Array<{ match: RefMatch; rank: SousRef }> = [];
+    if (early.lookup !== undefined) {
+      for (const candidate of early.kept) {
+        for (const match of await early.lookup.find(candidate)) {
+          found.push({ match, rank: candidate });
+        }
+      }
+    }
+    return this.finishResolve(args, early, found);
+  }
+
+  /**
+   * The same as `resolve`, for a caller that cannot wait: it asks the lookup's
+   * `findSync`, so the lookup must have one. A template engine's path
+   * resolution is synchronous, and is why this exists.
+   *
+   * @param args - The ref, where it was written, and what exists (a lookup with `findSync`).
+   * @throws A ConfigError listing every reason when the place refuses every reading.
+   */
+  resolveSync(args: RefResolveArguments): RefResolveResult {
+    const early = this.beginResolve(args);
+    if ("result" in early) return early.result;
+    const found: Array<{ match: RefMatch; rank: SousRef }> = [];
+    if (early.lookup !== undefined) {
+      const lookup = early.lookup as Partial<SyncRefLookup>;
+      if (lookup.findSync === undefined) {
+        throw new ConfigError("resolveSync needs a lookup that has a findSync method.");
+      }
+      for (const candidate of early.kept) {
+        for (const match of lookup.findSync(candidate)) found.push({ match, rank: candidate });
+      }
+    }
+    return this.finishResolve(args, early, found);
+  }
+
+  /**
+   * Parses and prunes without refusing: the readings a place keeps and the
+   * ones it drops, with the reason for each. For a caller that explains a
+   * refusal in its own words.
+   *
+   * @param input - The ref exactly as it was written.
+   * @param from - Where it was written.
+   * @throws A ConfigError when the text is not a ref in any reading.
+   */
+  inspect(input: string, from: RefSource): { kept: SousRef[]; dropped: DroppedRef[] } {
+    const { kept, dropped } = this.prune(input, from);
+    return { kept, dropped };
+  }
+
+  /** Everything `resolve` does before it asks a lookup, or the answer when it needs none. */
+  private beginResolve(
+    args: RefResolveArguments
+  ):
+    | { result: RefResolveResult }
+    | {
+        kept: SousRef[];
+        dropped: DroppedRef[];
+        warnings: string[];
+        lookup: RefLookup | undefined;
+      } {
+    let pruned;
+    try {
+      pruned = this.prune(args.input, args.from);
+    } catch (error) {
+      // A text no reading exists for (empty, say) is refused the same way.
+      if (args.refusedIsEmpty) return { result: new RefResolveResult(args.input, [], [], [], true) };
+      throw error;
+    }
+    const { dropped, warnings, place } = pruned;
+    if (pruned.kept.length === 0) {
+      if (args.refusedIsEmpty) {
+        return { result: new RefResolveResult(args.input, [], dropped, warnings, true) };
+      }
+      throw this.refusal(args.input, place, dropped);
+    }
+    const kinds = args.kinds;
+    const kept =
+      kinds === undefined
+        ? pruned.kept
+        : pruned.kept.filter(
+            (ref) =>
+              kinds.includes(ref.kind) ||
+              (ref.kind === "repo" &&
+                ref.browsed !== undefined &&
+                (kinds.includes("namespace") || kinds.includes("recipe")))
+          );
+
+    if (args.lookup === undefined) {
+      return {
+        result: new RefResolveResult(
+          args.input,
+          this.order(kept.map((ref) => ({ ref, rank: ref }))),
+          dropped,
+          warnings,
+          false
+        ),
+      };
+    }
+    return { kept, dropped, warnings, lookup: args.lookup };
+  }
+
+  /** Everything `resolve` does with what a lookup found. */
+  private finishResolve(
+    args: RefResolveArguments,
+    early: { dropped: DroppedRef[]; warnings: string[] },
+    found: Array<{ match: RefMatch; rank: SousRef }>
+  ): RefResolveResult {
+    const kinds = args.kinds;
+    const matching = found.filter(
+      (entry) => kinds === undefined || kinds.includes(entry.match.ref.kind)
+    );
+    const exact = matching.filter((entry) => entry.match.exactSpelling);
+    const chosen = exact.length > 0 ? exact : matching;
+
+    return new RefResolveResult(
+      args.input,
+      this.order(chosen.map((entry) => ({ ref: entry.match.ref, rank: entry.rank }))),
+      early.dropped,
+      early.warnings,
+      true
+    );
+  }
+
+  /**
+   * True when the ref parses and the place allows at least one reading of it.
+   *
+   * @param input - The ref exactly as it was written.
+   * @param from - Where it was written.
+   */
+  isValidRef(input: string, from: RefSource = RefSource.CommandLine): boolean {
+    try {
+      this.parse(input, from);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Every ref found in a longer text, one per whitespace-separated word that
+   * is a valid ref where it was written, with the quotes, brackets and
+   * sentence punctuation around the word taken off. Words that are not refs
+   * are left out.
+   *
+   * getRefsInString("see 'workflow/task-files', then run it.");
+   * // -> workflow/task-files, and the other words that happen to read as a ref
+   *
+   * @param text - The text to search.
+   * @param from - Where the text was written.
+   */
+  getRefsInString(text: string, from: RefSource = RefSource.CommandLine): RefInString[] {
+    const found: RefInString[] = [];
+    for (const word of text.matchAll(/\S+/g)) {
+      const bare = word[0].replace(/^[`"'([<{]+/, "").replace(/[`"')\]>},.;:!]+$/, "");
+      if (bare.length === 0) continue;
+      const start = word.index + word[0].indexOf(bare);
+      try {
+        found.push({ text: bare, index: start, result: this.parse(bare, from) });
+      } catch {
+        // Not a ref; the words around it may be.
+      }
+    }
+    return found;
+  }
+
+  /** Parses and prunes, and says where the ref was written in words. */
+  private prune(
+    input: string,
+    from: RefSource
+  ): { kept: SousRef[]; dropped: DroppedRef[]; warnings: string[]; place: string } {
+    const pruners = this.pruners.filter((pruner) => pruner.source === from);
+    if (pruners.length === 0) {
+      throw new ConfigError(`No pruner is registered for a ref written as '${from}'.`);
+    }
+
+    let kept = this.parser.parse(input);
+    const dropped: DroppedRef[] = [];
+    const warnings: string[] = [];
+    for (const pruner of pruners) {
+      const result = pruner.prune(kept, input.trim());
+      kept = result.kept;
+      dropped.push(...result.dropped);
+      warnings.push(...result.warnings);
+    }
+    return { kept, dropped, warnings, place: pruners[0]!.place };
+  }
+
+  /** The error for a ref the place refuses in every reading. */
+  private refusal(input: string, place: string, dropped: DroppedRef[]): ConfigError {
+    const reasons = [...new Set(dropped.map((entry) => entry.describe()))];
+    if (reasons.length === 1) {
+      return new ConfigError(`The ref '${input.trim()}' cannot be written ${place}: ${reasons[0]}`);
+    }
+    return new ConfigError(
+      `The ref '${input.trim()}' cannot be written ${place}. Every way it reads is refused:\n` +
+        reasons.map((reason) => `  - ${reason}`).join("\n")
+    );
+  }
+
+  /**
+   * Sorts refs into the documented listing order and drops any the same
+   * search found twice: by how qualified the spelling that produced each was,
+   * then by kind, then in the order they came (a lookup lists repositories in
+   * the order the project searches them).
+   */
+  private order(entries: Array<{ ref: SousRef; rank: SousRef }>): SousRef[] {
+    const indexed = entries.map((entry, position) => ({ ...entry, position }));
+    indexed.sort(
+      (left, right) =>
+        qualificationOf(left.rank) - qualificationOf(right.rank) ||
+        REF_KINDS.indexOf(left.ref.kind) - REF_KINDS.indexOf(right.ref.kind) ||
+        left.position - right.position
+    );
+    const seen = new Set<string>();
+    return indexed
+      .map((entry) => entry.ref)
+      .filter((ref) => {
+        const identity = `${refIdentity(ref)} ${JSON.stringify(ref.vars ?? {})}`;
+        if (seen.has(identity)) return false;
+        seen.add(identity);
+        return true;
+      });
+  }
+}
+
+makeInjectable(RefResolverService, [REF_TOKENS.Parser, { multi: REF_TOKENS.Pruner }]);