@sous-io/sous 0.2.37 → 1.0.2

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

@@ -1,204 +0,0 @@
-/**
- * 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/services/ref-resolver/ref-report.ts

@@ -1,84 +0,0 @@
-/**
- * Saying what a reference resolved to.
- *
- * A word on the command line can name a repository, a namespace, a recipe or a
- * variable, and when sous settles which one it means it has to say so. What it
- * 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; `RefPickerService`
- * in `ref-picker-service.ts` is the single caller, which is how every command gets it.
- */
-
-import {
-  formatVariable,
-  indent,
-  wrapColumns,
-  wrapText,
-  type VariableEntry,
-} from "../../utils/formatting.js";
-
-/** What a resolved reference is, in the words the report shows. */
-export interface ResolvedReferenceFacts {
-  /** The reference exactly as the person wrote it. */
-  search: string;
-  /** The fully qualified spelling the run proceeds with. */
-  resolvedTo: string;
-  /** What kind of thing it turned out to be: "recipe", "namespace", "repository". */
-  kind: string;
-  /** The repository publishing it. */
-  repository?: string;
-  /** The namespace it lives in, when it has one. */
-  namespace?: string;
-  /** The recipe itself, when the reference named one. */
-  recipe?: string;
-  /** The variable itself, when the reference named one. */
-  variable?: string;
-  /** Where a repository lives, when the reference named a repository. */
-  location?: string;
-  /** The publisher's one-line summary, when there is one. */
-  description?: string;
-  /**
-   * Why this candidate won, as the closing sentence. The default says the
-   * reference named one thing and nothing else; a caller that settled it some
-   * other way (taking the first of several, say) supplies its own.
-   */
-  reason?: string;
-}
-
-/**
- * The report as lines to write: the facts, a blank line, and the sentence.
- *
- * @param facts - What the reference resolved to.
- * @returns The lines to write, ready for the console.
- */
-export function formatResolvedReference(facts: ResolvedReferenceFacts): string[] {
-  const entries: VariableEntry[] = [
-    { label: "Resolved to", value: facts.resolvedTo },
-    ...(facts.variable === undefined ? [] : [{ label: "Variable", value: facts.variable }]),
-    ...(facts.recipe === undefined ? [] : [{ label: "Recipe", value: facts.recipe }]),
-    ...(facts.namespace === undefined ? [] : [{ label: "Namespace", value: facts.namespace }]),
-    ...(facts.repository === undefined
-      ? []
-      : [{ label: "Repository", value: facts.repository }]),
-    ...(facts.location === undefined ? [] : [{ label: "Location", value: facts.location }]),
-    ...(facts.description === undefined
-      ? []
-      : [{ label: "Description", value: facts.description }]),
-  ];
-
-  const labelWidth = Math.max(...entries.map((entry) => entry.label.length));
-  const lines = entries.flatMap((entry) => formatVariable(entry, { labelWidth }));
-
-  const reason =
-    facts.reason ??
-    `'${facts.search}' named one ${facts.kind}, and nothing else, so that is what ` +
-      `is being used.`;
-
-  lines.push("");
-  for (const line of wrapText(reason, wrapColumns() - 4)) {
-    lines.push(indent(line));
-  }
-
-  return lines;
-}

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

@@ -1,47 +0,0 @@
-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

@@ -1,36 +0,0 @@
-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

@@ -1,323 +0,0 @@
-/**
- * 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 }]);