@sous-io/sous 0.2.32 → 0.2.34

package/src/lib/refs/find.ts

@@ -1,770 +0,0 @@
-/**
- * Working out what a word on the command line names.
- *
- * Sous commands take a reference where a person would say a name: `sous
- * subscribe task-files`, `sous namespace show workflow`, `sous vars ask apiUrl`.
- * One module settles what such a word means, for every command, so a reference
- * that resolves in one place resolves the same way everywhere.
- *
- * A reference may be written at any level of qualification, and the fully
- * qualified spelling is always accepted:
- *
- *     sous-recipes                              a repository
- *     sous-recipes:workflow                     a namespace, fully qualified
- *     workflow                                  the same namespace, bare
- *     sous-recipes:workflow/task-files          a recipe, fully qualified
- *     workflow/task-files                       the same recipe, partly qualified
- *     task-files                                the same recipe, bare
- *     workflow/task-files.taskFileRoot          a variable, partly qualified
- *     taskFileRoot                              the same variable, bare
- *     SOUS_VAR_TASK_FILE_ROOT                   the environment variable answering it
- *
- * A location names the same things: an HTTPS, SSH or scheme-less URL, a
- * provider-scheme locator, or a URL copied from the browser, matched against
- * the trusted repository at that location and settled through its index.
- *
- * Matching tries the exact spelling first, then ignores case; a name that still
- * matches several things is a question for `pickReference`. The exact pass
- * comes first because a variable (`apiUrl`) and an environment variable name
- * can differ only in case, and the spelling typed is the one meant.
- *
- * The order matches come back in is part of the contract, because it is the
- * order they are offered in and the one `--accept-first` picks from. Matches
- * are sorted by how qualified the spelling that matched was (a fully qualified
- * reference first, then a partly qualified one, then a bare name, and an
- * environment variable name last), then by scope in the order `SCOPE_ORDER`
- * documents, then by repository in search order, then alphabetically by
- * namespace, recipe and variable.
- */
-
-import type { IndexFile } from "../repos/formats/index-file.js";
-import { repoIdentity } from "../repos/identity.js";
-import { requireProvider } from "../repos/providers/index.js";
-import {
-  isRepositoryReading,
-  looksLikeLocation,
-  parseRef,
-  splitRecipeKey,
-  type ParsedRef,
-  type RefReading,
-} from "./parse.js";
-import { settleInIndex } from "./settle.js";
-import type { DefinedVariable } from "../vars/definition-source.js";
-import { variableCandidates, type LadderContext } from "../vars/ladder.js";
-import { bareName } from "../vars/names.js";
-import { SCOPE_LABELS, SousScope, scopeRank } from "./scopes.js";
-
-// --- What the search reads ----------------------------------------------------------------------
-
-/** One namespace a reference could name. */
-export type ReferenceNamespace = {
-  /** The namespace name. */
-  name: string;
-  /** Its one-paragraph summary, when the index carries one. */
-  description?: string;
-};
-
-/** One recipe a reference could name. */
-export type ReferenceRecipe = {
-  /** The namespace publishing it. */
-  namespace: string;
-  /** The recipe name. */
-  name: string;
-  /** Its one-paragraph summary, when the index carries one. */
-  description?: string;
-  /** The folder it lives in, relative to the repository root, when the index says. */
-  path?: string;
-};
-
-/** One repository a reference could name, and what it publishes. */
-export type ReferenceRepo = {
-  /** The short name this project calls it. */
-  name: string;
-  /** Where it lives, as the project's config records it. */
-  url?: string;
-  /**
-   * Its canonical identity, which is how a reference written as a location
-   * finds it whatever short name this project gave it.
-   */
-  identity?: string;
-  /** Every namespace it publishes. */
-  namespaces: ReferenceNamespace[];
-  /** Every recipe it publishes. */
-  recipes: ReferenceRecipe[];
-};
-
-/**
- * Everything a reference resolves against. Each part is optional, because a
- * command supplies only what it can see: a browsing command has repositories
- * and their indexes, `sous vars ask --file` has definitions and no repository
- * at all.
- */
-export type ReferenceContext = {
-  /**
-   * The repositories to search, in the order their matches should be listed:
-   * the built-in repository first, then the ones the config names, in config
-   * order.
-   */
-  repos?: ReferenceRepo[];
-  /** The variable definitions in play, with the recipe that published each. */
-  variables?: DefinedVariable[];
-  /**
-   * The environment layers, which decide which generated environment variable
-   * names are in use. Without it only a definition's declared `env` name is
-   * searched.
-   */
-  ladder?: LadderContext;
-};
-
-// --- What the search answers --------------------------------------------------------------------
-
-/**
- * How qualified the spelling that matched was. Lower is more specific, and the
- * listing order follows it.
- */
-export enum Qualification {
-  /** The reference named the whole identity, repository included. */
-  Full = 0,
-  /** The reference named part of the identity, such as `namespace/recipe`. */
-  Partial = 1,
-  /** The reference was a bare name. */
-  Bare = 2,
-  /** The reference was an environment variable name. */
-  EnvName = 3,
-}
-
-/** One thing a reference could have meant. */
-export type ReferenceMatch = {
-  /** What kind of thing it is. */
-  scope: SousScope;
-  /**
-   * The fully qualified name of it: `repo`, `repo:namespace`,
-   * `repo:namespace/recipe`, or `repo:namespace/recipe.variable`. Two matches
-   * never share a key within one scope, so it is safe to compare and to print.
-   */
-  key: string;
-  /** The short name of the thing itself, without any qualifier. */
-  label: string;
-  /** What it is, in one line: a description, a prompt, or where it lives. */
-  detail?: string;
-  /** The repository it belongs to, when it has one. */
-  repo?: string;
-  /** The namespace it is, or the one it lives in. */
-  namespace?: string;
-  /** The recipe it is, or the one that declares it. */
-  recipe?: string;
-  /** The variable it is, or the one an environment variable name answers. */
-  variable?: string;
-  /** The environment variable name, when the reference named one. */
-  envName?: string;
-  /** How qualified the spelling that matched was. */
-  qualification: Qualification;
-};
-
-// --- The search ---------------------------------------------------------------------------------
-
-/**
- * Every meaning a reference could have, in the documented order.
- *
- * Nothing is fetched and nothing is asked: this reads the context it is handed
- * and returns what matched. An empty result means the reference named nothing
- * the caller can see; one result is the answer; several are offered to the
- * caller by `pickReference`.
- *
- * @param search - The reference exactly as it was written.
- * @param scopes - The kinds of thing this command accepts.
- * @param context - The repositories, definitions and environment layers to search.
- */
-export function findReference(
-  search: string,
-  scopes: readonly SousScope[],
-  context: ReferenceContext
-): ReferenceMatch[] {
-  const wanted = new Set(scopes);
-  const term = search.trim();
-  if (term.length === 0) return [];
-
-  if (looksLikeLocation(term)) return findLocated(term, wanted, context);
-
-  const exact = collectMatches(term, wanted, context, (one, other) => one === other);
-  if (exact.length > 0) return exact;
-  return collectMatches(
-    term,
-    wanted,
-    context,
-    (one, other) => one.toLowerCase() === other.toLowerCase()
-  );
-}
-
-/** How two spellings are compared in one pass of the search. */
-type SameSpelling = (one: string, other: string) => boolean;
-
-/**
- * Every match of a term under one way of comparing spellings.
- *
- * @param term - The reference, trimmed.
- * @param wanted - The kinds of thing the command accepts.
- * @param context - What to search.
- * @param same - Whether two spellings count as the same.
- */
-function collectMatches(
-  term: string,
-  wanted: Set<SousScope>,
-  context: ReferenceContext,
-  same: SameSpelling
-): ReferenceMatch[] {
-  const matches: ReferenceMatch[] = [];
-  const repoOrder = new Map((context.repos ?? []).map((repo, position) => [repo.name, position]));
-
-  for (const repo of context.repos ?? []) {
-    if (wanted.has(SousScope.Repository) && same(term, repo.name)) {
-      matches.push({
-        scope: SousScope.Repository,
-        key: repo.name,
-        label: repo.name,
-        repo: repo.name,
-        qualification: Qualification.Full,
-        ...(repo.url === undefined ? {} : { detail: repo.url }),
-      });
-    }
-
-    if (wanted.has(SousScope.Namespace)) {
-      for (const namespace of repo.namespaces) {
-        const key = `${repo.name}:${namespace.name}`;
-        const qualification = qualificationOf(term, same, [
-          [key, Qualification.Full],
-          [namespace.name, Qualification.Bare],
-        ]);
-        if (qualification === undefined) continue;
-        matches.push({
-          scope: SousScope.Namespace,
-          key,
-          label: namespace.name,
-          repo: repo.name,
-          namespace: namespace.name,
-          qualification,
-          ...(namespace.description === undefined ? {} : { detail: namespace.description }),
-        });
-      }
-    }
-
-    if (wanted.has(SousScope.Recipe)) {
-      for (const recipe of repo.recipes) {
-        const key = `${repo.name}:${recipe.namespace}/${recipe.name}`;
-        const qualification = qualificationOf(term, same, [
-          [key, Qualification.Full],
-          [`${recipe.namespace}/${recipe.name}`, Qualification.Partial],
-          [`${repo.name}:${recipe.name}`, Qualification.Partial],
-          [recipe.name, Qualification.Bare],
-        ]);
-        if (qualification === undefined) continue;
-        matches.push({
-          scope: SousScope.Recipe,
-          key,
-          label: recipe.name,
-          repo: repo.name,
-          namespace: recipe.namespace,
-          recipe: recipe.name,
-          qualification,
-          ...(recipe.description === undefined ? {} : { detail: recipe.description }),
-        });
-      }
-    }
-  }
-
-  if (wanted.has(SousScope.VariableName) || wanted.has(SousScope.EnvVarName)) {
-    for (const defined of context.variables ?? []) {
-      const key = variableReferenceKey(defined);
-      const { repo, namespace, name: recipe } = defined.recipe;
-      const variable = defined.definition.name;
-
-      if (wanted.has(SousScope.VariableName)) {
-        const qualification = qualificationOf(term, same, [
-          [key, Qualification.Full],
-          [`${namespace}/${recipe}.${variable}`, Qualification.Partial],
-          [`${recipe}.${variable}`, Qualification.Partial],
-          [`${repo}:${variable}`, Qualification.Partial],
-          [variable, Qualification.Bare],
-        ]);
-        if (qualification !== undefined) {
-          matches.push({
-            scope: SousScope.VariableName,
-            key,
-            label: variable,
-            repo,
-            namespace,
-            recipe,
-            variable,
-            qualification,
-            detail: defined.definition.prompt,
-          });
-          continue;
-        }
-      }
-
-      const envName = [...environmentNamesFor(defined, context)].find((name) => same(term, name));
-      if (wanted.has(SousScope.EnvVarName) && envName !== undefined) {
-        matches.push({
-          scope: SousScope.EnvVarName,
-          key,
-          label: envName,
-          repo,
-          namespace,
-          recipe,
-          variable,
-          envName,
-          qualification: Qualification.EnvName,
-          detail: defined.definition.prompt,
-        });
-      }
-    }
-  }
-
-  return sortMatches(matches, repoOrder);
-}
-
-/**
- * Every match of a reference written as a location. Each reading of it is
- * looked for among the repositories at that location, whatever short name this
- * project gave them, and settled through that repository's index: a named
- * namespace or recipe exactly first and then ignoring case, a browser path
- * through the folder each recipe lives in. A location that does not parse, or
- * whose repository this project does not trust, names nothing here.
- *
- * @param term - The reference, trimmed.
- * @param wanted - The kinds of thing the command accepts.
- * @param context - What to search.
- */
-function findLocated(
-  term: string,
-  wanted: Set<SousScope>,
-  context: ReferenceContext
-): ReferenceMatch[] {
-  let readings: RefReading[];
-  try {
-    readings = parseRef(term);
-  } catch {
-    return [];
-  }
-
-  const matches: ReferenceMatch[] = [];
-  const repoOrder = new Map((context.repos ?? []).map((repo, position) => [repo.name, position]));
-
-  for (const reading of readings) {
-    for (const repo of context.repos ?? []) {
-      if (repo.identity === undefined || repo.identity !== reading.location?.identity) continue;
-
-      if (isRepositoryReading(reading)) {
-        if (wanted.has(SousScope.Repository)) {
-          matches.push({
-            scope: SousScope.Repository,
-            key: repo.name,
-            label: repo.name,
-            repo: repo.name,
-            qualification: Qualification.Full,
-            ...(repo.url === undefined ? {} : { detail: repo.url }),
-          });
-        }
-        continue;
-      }
-
-      const recipes: Record<string, { path: string }> = {};
-      for (const recipe of repo.recipes) {
-        recipes[`${recipe.namespace}/${recipe.name}`] = { path: recipe.path ?? "" };
-      }
-      const settled = settleInIndex(reading, {
-        namespaces: repo.namespaces.map((namespace) => namespace.name),
-        recipes,
-      });
-
-      for (const found of settled) {
-        if (found.recipe === undefined) {
-          if (!wanted.has(SousScope.Namespace)) continue;
-          const namespace = repo.namespaces.find((entry) => entry.name === found.namespace);
-          matches.push({
-            scope: SousScope.Namespace,
-            key: `${repo.name}:${found.namespace}`,
-            label: found.namespace,
-            repo: repo.name,
-            namespace: found.namespace,
-            qualification: Qualification.Full,
-            ...(namespace?.description === undefined ? {} : { detail: namespace.description }),
-          });
-          continue;
-        }
-        if (!wanted.has(SousScope.Recipe)) continue;
-        const recipe = repo.recipes.find(
-          (entry) => entry.namespace === found.namespace && entry.name === found.recipe
-        );
-        matches.push({
-          scope: SousScope.Recipe,
-          key: `${repo.name}:${found.namespace}/${found.recipe}`,
-          label: found.recipe,
-          repo: repo.name,
-          namespace: found.namespace,
-          recipe: found.recipe,
-          qualification: Qualification.Full,
-          ...(recipe?.description === undefined ? {} : { detail: recipe.description }),
-        });
-      }
-    }
-  }
-
-  return sortMatches(matches, repoOrder);
-}
-
-/**
- * The repository a reference names.
- *
- * @param search - The reference exactly as it was written.
- * @param context - What to search.
- */
-export function findRepository(
-  search: string,
-  context: ReferenceContext
-): ReferenceMatch[] {
-  return findReference(search, [SousScope.Repository], context);
-}
-
-/**
- * The namespace a reference names, bare or written as `repository:namespace`.
- *
- * @param search - The reference exactly as it was written.
- * @param context - What to search.
- */
-export function findNamespace(search: string, context: ReferenceContext): ReferenceMatch[] {
-  return findReference(search, [SousScope.Namespace], context);
-}
-
-/**
- * The recipe a reference names, at any level of qualification.
- *
- * @param search - The reference exactly as it was written.
- * @param context - What to search.
- */
-export function findRecipe(search: string, context: ReferenceContext): ReferenceMatch[] {
-  return findReference(search, [SousScope.Recipe], context);
-}
-
-/**
- * The variable a reference names, by its own name or by the name of an
- * environment variable that answers it.
- *
- * @param search - The reference exactly as it was written.
- * @param context - What to search.
- */
-export function findVariable(search: string, context: ReferenceContext): ReferenceMatch[] {
-  return findReference(search, [SousScope.VariableName, SousScope.EnvVarName], context);
-}
-
-// --- Describing what was found ------------------------------------------------------------------
-
-/**
- * Describes one match in the words a person choosing between them needs: the
- * fully qualified name, and what it actually means.
- *
- * @param match - The match to describe.
- */
-export function describeReference(match: ReferenceMatch): string {
-  const summary = match.detail === undefined ? "" : `: ${match.detail}`;
-
-  switch (match.scope) {
-    case SousScope.Repository:
-      return (
-        `${match.key}  (the repository '${match.repo}'` +
-        `${match.detail === undefined ? "" : `, at ${match.detail}`})`
-      );
-    case SousScope.Namespace:
-      return (
-        `${match.key}  (the whole namespace '${match.namespace}' in the ` +
-        `repository '${match.repo}')`
-      );
-    case SousScope.Recipe:
-      return (
-        `${match.key}  (the recipe '${match.recipe}' in the namespace ` +
-        `'${match.namespace}' of the repository '${match.repo}'${summary})`
-      );
-    case SousScope.VariableName:
-      return (
-        `${match.key}  (the variable '${match.variable}' of the recipe ` +
-        `'${match.namespace}/${match.recipe}'${summary})`
-      );
-    case SousScope.EnvVarName:
-      return (
-        `${match.envName}  (the environment variable answering '${match.variable}' ` +
-        `of the recipe '${match.namespace}/${match.recipe}'${summary})`
-      );
-  }
-}
-
-/**
- * The plain-language name of what a match is, for a sentence that has to say
- * what kind of thing was found.
- *
- * @param match - The match to name.
- */
-export function referenceKindLabel(match: ReferenceMatch): string {
-  return SCOPE_LABELS[match.scope];
-}
-
-// --- Building a context -------------------------------------------------------------------------
-
-/**
- * Turns cached repository indexes into the repositories a reference searches,
- * in the order they were given.
- *
- * @param repoOrder - The repository short names, in search order.
- * @param indexes - Each repository's cached index, keyed by short name.
- */
-export function referenceReposFromIndexes(
-  repoOrder: readonly string[],
-  indexes: Map<string, IndexFile>,
-  urls: Record<string, string | undefined> = {}
-): ReferenceRepo[] {
-  const repos: ReferenceRepo[] = [];
-
-  for (const name of repoOrder) {
-    const index = indexes.get(name);
-    if (index === undefined) continue;
-
-    const namespaces: ReferenceNamespace[] = Object.entries(index.namespaces).map(
-      ([namespace, declared]) => ({
-        name: namespace,
-        ...(declared?.description === undefined ? {} : { description: declared.description }),
-      })
-    );
-
-    const recipes: ReferenceRecipe[] = [];
-    for (const [key, recipe] of Object.entries(index.recipes)) {
-      const { namespace, name: recipeName } = splitRecipeKey(key);
-      recipes.push({
-        namespace,
-        name: recipeName,
-        path: recipe.path,
-        ...(recipe.description === undefined ? {} : { description: recipe.description }),
-      });
-    }
-
-    const url = urls[name];
-    const identity = url === undefined ? undefined : identityOfUrl(url);
-    repos.push({
-      name,
-      namespaces,
-      recipes,
-      ...(url === undefined ? {} : { url }),
-      ...(identity === undefined ? {} : { identity }),
-    });
-  }
-
-  return repos;
-}
-
-/**
- * The canonical identity of a repository at a URL, or undefined when no
- * provider recognizes it.
- *
- * @param url - Where the repository lives.
- */
-function identityOfUrl(url: string): string | undefined {
-  try {
-    return repoIdentity(requireProvider(url).canonicalize(url));
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * The repositories, namespaces and recipes the variable definitions in play
- * belong to, derived from the definitions themselves.
- *
- * This is the context a variables command searches: a namespace that publishes
- * no variable this project holds has no questions to ask, so naming it would
- * resolve to an empty set of questions rather than to an answer. Deriving the
- * context from the definitions also means `sous vars ask --file` resolves
- * references exactly as a subscribed project does.
- *
- * The trusted repositories, when given, lend each repository its identity and
- * URL and each recipe its folder, so a reference written as a location (a URL,
- * a locator, a URL copied from the browser) settles here exactly as it does in
- * every other command.
- *
- * @param variables - The variable definitions in play.
- * @param ladder - The environment layers, for environment variable names.
- * @param trusted - The trusted repositories as a reference searches them.
- */
-export function referenceContextFromVariables(
-  variables: DefinedVariable[],
-  ladder?: LadderContext,
-  trusted: readonly ReferenceRepo[] = []
-): ReferenceContext {
-  const repos = new Map<string, ReferenceRepo>();
-
-  for (const defined of variables) {
-    const { repo: repoName, namespace, name: recipe } = defined.recipe;
-    const known = trusted.find((entry) => entry.name === repoName);
-
-    let repo = repos.get(repoName);
-    if (repo === undefined) {
-      repo = {
-        name: repoName,
-        namespaces: [],
-        recipes: [],
-        ...(known?.url === undefined ? {} : { url: known.url }),
-        ...(known?.identity === undefined ? {} : { identity: known.identity }),
-      };
-      repos.set(repoName, repo);
-    }
-
-    if (!repo.namespaces.some((entry) => entry.name === namespace)) {
-      repo.namespaces.push({ name: namespace });
-    }
-    if (!repo.recipes.some((entry) => entry.namespace === namespace && entry.name === recipe)) {
-      const path = known?.recipes.find(
-        (entry) => entry.namespace === namespace && entry.name === recipe
-      )?.path;
-      repo.recipes.push({ namespace, name: recipe, ...(path === undefined ? {} : { path }) });
-    }
-  }
-
-  return {
-    repos: [...repos.values()],
-    variables,
-    ...(ladder === undefined ? {} : { ladder }),
-  };
-}
-
-/**
- * The fully qualified name of one variable: `repo:namespace/recipe.variable`.
- * It is what a reference to a variable resolves to, and what a command hands
- * back to the asking machinery when it has decided which variables to ask.
- *
- * @param defined - The definition and the recipe that published it.
- */
-export function variableReferenceKey(defined: DefinedVariable): string {
-  const { repo, namespace, name } = defined.recipe;
-  return `${repo}:${namespace}/${name}.${defined.definition.name}`;
-}
-
-// --- Turning a match back into a ref --------------------------------------------------------------
-
-/**
- * Turns a chosen match into a parsed ref, carrying over the version range the
- * original ref asked for. The repository qualifier is kept, so what gets
- * resolved is exactly the match that was chosen and not another repository's
- * recipe of the same name.
- *
- * @param match - The match that was chosen.
- * @param original - The ref as the user wrote it.
- */
-export function referenceToRef(match: ReferenceMatch, original: ParsedRef): ParsedRef {
-  return {
-    ...(match.repo === undefined ? {} : { repo: match.repo }),
-    namespace: match.namespace ?? original.namespace,
-    ...(match.recipe === undefined ? {} : { recipe: match.recipe }),
-    ...(original.range === undefined ? {} : { range: original.range }),
-  };
-}
-
-// --- The pieces -----------------------------------------------------------------------------------
-
-/**
- * How qualified a spelling of one thing the search term matched, or undefined
- * when it matched none of them. Spellings are given most specific first, and
- * the first one that matches wins.
- *
- * @param term - The search term.
- * @param same - Whether two spellings count as the same.
- * @param spellings - Each spelling of this thing, with how qualified it is.
- */
-function qualificationOf(
-  term: string,
-  same: SameSpelling,
-  spellings: [string, Qualification][]
-): Qualification | undefined {
-  for (const [spelling, qualification] of spellings) {
-    if (same(spelling, term)) return qualification;
-  }
-  return undefined;
-}
-
-/**
- * Every environment variable name that would be recognized as naming one
- * variable: the name its definition declares (a recipe may bind an existing
- * variable such as `GITHUB_TOKEN`), plus any generated name on the resolution
- * ladder that is actually in use in `.sous/.env` or `.sous/.env.local`.
- *
- * Generated names are only searched when they are in use, because every
- * variable generates four of them and a project would otherwise be told that a
- * name nothing has ever set names one of its variables.
- *
- * @param defined - The definition and the recipe that published it.
- * @param context - The environment layers, when the caller has them.
- */
-function environmentNamesFor(
-  defined: DefinedVariable,
-  context: ReferenceContext
-): Set<string> {
-  const names = new Set<string>([bareName(defined.definition)]);
-
-  const ladder = context.ladder;
-  if (ladder === undefined) return names;
-
-  const inUse = new Set([...Object.keys(ladder.localEnv), ...Object.keys(ladder.sharedEnv)]);
-  for (const candidate of variableCandidates(defined, ladder)) {
-    if (inUse.has(candidate.envName)) names.add(candidate.envName);
-  }
-
-  return names;
-}
-
-/**
- * Sorts matches into the documented listing order and drops anything the same
- * search found twice.
- *
- * @param matches - Every match, in the order they were collected.
- * @param repoOrder - Where each repository sits in the search order.
- */
-function sortMatches(
-  matches: ReferenceMatch[],
-  repoOrder: Map<string, number>
-): ReferenceMatch[] {
-  const position = (repo: string | undefined): number =>
-    repo === undefined ? 0 : (repoOrder.get(repo) ?? repoOrder.size);
-
-  const sorted = [...matches].sort((left, right) => {
-    if (left.qualification !== right.qualification) {
-      return left.qualification - right.qualification;
-    }
-    const scopes = scopeRank(left.scope) - scopeRank(right.scope);
-    if (scopes !== 0) return scopes;
-
-    const repos = position(left.repo) - position(right.repo);
-    if (repos !== 0) return repos;
-
-    return compare(
-      [left.namespace, left.recipe, left.variable],
-      [right.namespace, right.recipe, right.variable]
-    );
-  });
-
-  const seen = new Set<string>();
-  return sorted.filter((match) => {
-    const identity = `${match.scope}${match.key}${match.envName ?? ""}`;
-    if (seen.has(identity)) return false;
-    seen.add(identity);
-    return true;
-  });
-}
-
-/** Bytewise comparison of the parts of an identity, so listings are stable. */
-function compare(
-  left: (string | undefined)[],
-  right: (string | undefined)[]
-): number {
-  for (let index = 0; index < left.length; index += 1) {
-    const one = left[index] ?? "";
-    const other = right[index] ?? "";
-    if (one !== other) return one < other ? -1 : 1;
-  }
-  return 0;
-}