@sous-io/sous 0.2.32 → 0.2.34

package/src/lib/refs/pick.ts

@@ -1,147 +0,0 @@
-/**
- * Settling on one of the things a reference could have meant.
- *
- * Finding is separate from choosing on purpose: `findReference` is pure and
- * tells the caller everything a word could have meant, and this is the one
- * place that decides which of them the run proceeds with. Every command that
- * takes a reference 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 (`formatResolvedReference`), 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 { ConfigError } from "../errors.js";
-import { nonInteractiveError } from "../interactive.js";
-import { formatParagraph, log } from "../../utils/formatting.js";
-import { askChoice } from "../../utils/prompts.js";
-import {
-  formatResolvedReference,
-  resolvedReferenceFacts,
-} from "../repos/reference-report.js";
-import { describeReference, type ReferenceMatch } from "./find.js";
-
-/** The flag that answers "which one did you mean?" ahead of time. */
-export const ACCEPT_FIRST_FLAG = "--accept-first";
-
-/** How `pickReference` should behave. */
-export type PickReferenceOptions = {
-  /** The reference exactly as it was written, for every message. */
-  search: string;
-  /** Whether a question may be asked. A run that may not fails instead. */
-  interactive: boolean;
-  /** Take the first match rather than asking, because `--accept-first` was passed. */
-  acceptFirst?: boolean;
-  /** The question to ask when there is more than one match. */
-  prompt?: string;
-  /**
-   * Write the facts about what the reference 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.
-   */
-  announce?: boolean;
-  /** Extra lines for the error a reference that matched nothing raises. */
-  details?: string[];
-  /** Where a resolution is reported. Defaults to the console. */
-  write?: (message: string) => void;
-  /** How the choice is asked. Defaults to the shared choice prompt. */
-  choose?: (message: string, matches: ReferenceMatch[]) => Promise<ReferenceMatch>;
-};
-
-/**
- * The one match a reference proceeds with.
- *
- * @param matches - What the reference could have meant, in listing order.
- * @param options - What was searched for, and whether a question may be asked.
- * @returns The match the run proceeds with.
- */
-export async function pickReference(
-  matches: ReferenceMatch[],
-  options: PickReferenceOptions
-): Promise<ReferenceMatch> {
-  const write = options.write ?? ((message: string) => log(message));
-
-  if (matches.length === 0) {
-    throw new ConfigError(
-      [`Nothing called '${options.search}' was found.`, ...(options.details ?? [])].join("\n")
-    );
-  }
-
-  const first = matches[0]!;
-
-  if (matches.length === 1) {
-    if (options.announce !== false) announce(write, first, options.search);
-    return first;
-  }
-
-  if (options.acceptFirst === true) {
-    const reason =
-      `'${options.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 (options.announce === false) {
-      for (const line of formatParagraph(reason)) write(line);
-    } else {
-      announce(write, first, options.search, reason);
-    }
-    return first;
-  }
-
-  if (!options.interactive) {
-    // The example is a spelling that says more than what was typed, so a
-    // reference that is already its own fully qualified name is not offered
-    // back unchanged.
-    const example =
-      matches.find((match) => match.key !== options.search)?.key ?? first.key;
-
-    throw nonInteractiveError({
-      prompt: `which '${options.search}' you meant`,
-      remedy:
-        `write the full reference (for example '${example}'), or pass ` +
-        `'${ACCEPT_FIRST_FLAG}' to take the first candidate listed above.`,
-      details: [
-        `'${options.search}' matched ${matches.length} things:`,
-        ...matches.map((match) => `  ${describeReference(match)}`),
-      ],
-    });
-  }
-
-  const choose =
-    options.choose ??
-    ((message: string, offered: ReferenceMatch[]) =>
-      askChoice(
-        message,
-        offered.map((match) => ({ name: describeReference(match), value: match }))
-      ));
-
-  return choose(options.prompt ?? `Which '${options.search}' did you mean?`, matches);
-}
-
-/**
- * Writes what a reference 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.
- *
- * @param write - Where the report goes.
- * @param match - The match the run proceeds with.
- * @param search - The reference exactly as it was written.
- * @param reason - The closing sentence, when it was not simply the only match.
- */
-function announce(
-  write: (message: string) => void,
-  match: ReferenceMatch,
-  search: string,
-  reason?: string
-): void {
-  for (const line of formatResolvedReference(resolvedReferenceFacts(match, search, reason))) {
-    write(line);
-  }
-}

package/src/lib/refs/scopes.ts

@@ -1,95 +0,0 @@
-/**
- * The kinds of thing a reference on the command line can name.
- *
- * Every sous command that takes a `<ref>` or a `[NAME]` argument is naming one
- * of these five things, and each command accepts only the kinds that make sense
- * for it: `sous subscribe` accepts a namespace or a recipe, `sous vars ask`
- * accepts all five. The scope list a command passes to `findReference` is
- * therefore part of that command's contract, and it is the only thing that
- * differs between one command's resolution and another's.
- */
-
-/** One kind of thing a reference can name. */
-export enum SousScope {
-  /** A repository this project trusts, named by its short name. */
-  Repository = "repository",
-  /** A namespace published by a repository. */
-  Namespace = "namespace",
-  /** A recipe published in a namespace. */
-  Recipe = "recipe",
-  /** A variable declared by a recipe, named as the recipe's author named it. */
-  VariableName = "variableName",
-  /** An environment variable name that answers a variable. */
-  EnvVarName = "envVarName",
-}
-
-/**
- * Where a ref was written. `parseRef` reads every form wherever a ref comes
- * from, and the place decides which of those forms it allows: a refused form
- * is an error saying what to write there instead.
- */
-export enum RefSource {
-  /**
-   * A ref typed on the command line. Every form is allowed: a bare name, a
-   * namespace and recipe, a `repo:` qualifier, a version range, a
-   * provider-scheme locator, an HTTPS, SSH or scheme-less URL, and a browser
-   * URL copied from a host's file view. Names may be written in any case.
-   */
-  CommandLine = "commandLine",
-  /**
-   * A subscription key in a config layer. Only the stored form is allowed:
-   * `namespace` or `namespace/recipe`, lowercase. The repository a
-   * subscription resolves into is recorded in the lockfile, and its range in
-   * the entry's own `range` field.
-   */
-  Config = "config",
-  /**
-   * An entry of a recipe manifest's `depends` or `subscribes` list. A bare ref
-   * names a recipe in the same repository; every locator and URL form names
-   * one in another repository. A `repo:` qualifier is refused, because it is
-   * one project's private name for a repository, and so is a local path.
-   */
-  Manifest = "manifest",
-  /**
-   * A key sous wrote itself: the lockfile, the index and the store. Only the
-   * canonical `namespace` or `namespace/recipe` is allowed.
-   */
-  Lockfile = "lockfile",
-}
-
-/**
- * Every scope, in the order matches of equal specificity are listed in. It is
- * the order the one-word ref search has always used (a whole namespace before
- * the recipes inside it), widened to the other three kinds: the broadest thing
- * a word could have meant is offered first, and the environment variable names
- * (the least likely reading of a plain word) come last.
- */
-export const SCOPE_ORDER: readonly SousScope[] = [
-  SousScope.Repository,
-  SousScope.Namespace,
-  SousScope.Recipe,
-  SousScope.VariableName,
-  SousScope.EnvVarName,
-] as const;
-
-/** Every scope, for a command that accepts anything a reference can name. */
-export const ALL_SCOPES: readonly SousScope[] = SCOPE_ORDER;
-
-/** What each scope is called in a sentence. */
-export const SCOPE_LABELS: Record<SousScope, string> = {
-  [SousScope.Repository]: "repository",
-  [SousScope.Namespace]: "namespace",
-  [SousScope.Recipe]: "recipe",
-  [SousScope.VariableName]: "variable",
-  [SousScope.EnvVarName]: "environment variable",
-};
-
-/**
- * Where a scope sits in the listing order.
- *
- * @param scope - The scope to rank.
- */
-export function scopeRank(scope: SousScope): number {
-  const rank = SCOPE_ORDER.indexOf(scope);
-  return rank === -1 ? SCOPE_ORDER.length : rank;
-}

package/src/lib/refs/settle.ts

@@ -1,219 +0,0 @@
-/**
- * Settling what a ref means, once the index that can say is at hand.
- *
- * `parseRef` returns every reading of a written ref. Some readings are settled
- * the moment they are read (`workflow/alpha`), and some need the index of the
- * repository they point at: a browser URL names a folder, and only the `path`
- * each recipe's index entry records says which recipe that folder is; a GitLab
- * URL with nested groups can be read as several repositories, and only their
- * indexes say which one publishes what was named.
- *
- * Names are matched the same way everywhere: the exact spelling first, then
- * ignoring case. A name that still matches several things is a question for
- * `pickReference`.
- */
-
-import {
-  isBrowsedReading,
-  isNamedReading,
-  namespaceOfKey,
-  parseRef,
-  refKey,
-  splitRecipeKey,
-  type ParsedRef,
-  type RefReading,
-} from "./parse.js";
-import { RefSource } from "./scopes.js";
-
-/**
- * The names that match a written one: those spelled exactly as written, or,
- * when there is none, those that differ only in case.
- *
- * matchNames("Workflow", ["workflow", "tooling"]); // -> ["workflow"]
- * matchNames("workflow", ["workflow", "Workflow"]); // -> ["workflow"]
- *
- * @param written - The name as written.
- * @param names - The names it could mean.
- */
-export function matchNames(written: string, names: Iterable<string>): string[] {
-  const all = [...names];
-  const exact = all.filter((name) => name === written);
-  if (exact.length > 0) return exact;
-  const folded = written.toLowerCase();
-  return all.filter((name) => name.toLowerCase() === folded);
-}
-
-/** What settling needs to know about one repository's index. */
-export type SettleIndex = {
-  /** Every namespace the index publishes. */
-  namespaces: Iterable<string>;
-  /** Every recipe it publishes, keyed `namespace/recipe`, with the folder it lives in. */
-  recipes: Record<string, { path: string }>;
-};
-
-/**
- * What a reading names in one repository's index, spelled the way the index
- * spells it. A named reading that the index does not publish settles to
- * nothing; a browsed path settles through the recipe paths.
- *
- * settleInIndex({ namespace: "Workflow", recipe: "alpha" }, index);
- * // -> [{ namespace: "workflow", recipe: "alpha" }]
- *
- * @param reading - One reading of a written ref.
- * @param index - The index of the repository the reading points at.
- */
-export function settleInIndex(reading: RefReading, index: SettleIndex): ParsedRef[] {
-  const carried = {
-    ...(reading.location === undefined ? {} : { location: reading.location }),
-    ...("range" in reading && reading.range !== undefined ? { range: reading.range } : {}),
-    ...("repo" in reading && reading.repo !== undefined ? { repo: reading.repo } : {}),
-  };
-
-  if (isBrowsedReading(reading)) {
-    return settleBrowsed(reading.browsed, index).map((settled) => ({ ...settled, ...carried }));
-  }
-  if (!isNamedReading(reading)) return [];
-
-  if (reading.recipe === undefined) {
-    return matchNames(reading.namespace, index.namespaces).map((namespace) => ({
-      namespace,
-      ...carried,
-    }));
-  }
-
-  return matchNames(refKey(reading), Object.keys(index.recipes)).map((key) => {
-    const { namespace, name } = splitRecipeKey(key);
-    return { namespace, recipe: name, ...carried };
-  });
-}
-
-/**
- * What a browser path names, through the folder each recipe's index entry
- * records. The path still carries the branch in front (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", index);
- * // -> [{ namespace: "workflow", recipe: "alpha" }]
- *
- * @param browsed - The path after `tree/` or `blob/`, branch included.
- * @param index - The repository's index.
- */
-export function settleBrowsed(browsed: string, index: SettleIndex): ParsedRef[] {
-  const segments = browsed.split("/").filter((segment) => segment.length > 0);
-  const recipes = Object.entries(index.recipes).map(([key, entry]) => ({
-    key,
-    path: entry.path.replace(/^\.?\/+|\/+$/g, ""),
-  }));
-
-  const found = new Map<string, ParsedRef>();
-
-  // 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((recipe) => folder === recipe.path || folder.startsWith(`${recipe.path}/`))
-      .sort((left, right) => right.path.length - left.path.length);
-    const deepest = holding[0];
-    if (deepest !== undefined) {
-      const { namespace, name } = splitRecipeKey(deepest.key);
-      found.set(deepest.key, { namespace, recipe: name });
-    }
-  }
-  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((recipe) => recipe.path.startsWith(`${folder}/`));
-    const namespaces = new Set(under.map((recipe) => namespaceOfKey(recipe.key)));
-    if (namespaces.size === 1) {
-      const namespace = [...namespaces][0]!;
-      found.set(namespace, { namespace });
-    }
-  }
-  return [...found.values()];
-}
-
-/** What a repository's index recorded about one dependency, as far as settling needs. */
-export type RecordedDependencies = Record<string, { repo?: string } | undefined>;
-
-/**
- * The readings of a manifest dependency that the declaring recipe's index
- * confirms. 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 dependency that reads one way needs no record and comes back as it
- * is.
- *
- * A named reading is confirmed by a record under its own key (or, for a whole
- * namespace, under a key inside it) carrying its repository; a browsed reading
- * by any record carrying its repository.
- *
- * @param readings - Every reading of the dependency, from `parseRef`.
- * @param recorded - What the declaring version's index entry records, keyed `namespace/recipe`.
- * @returns The confirmed readings: one is the answer; none or several leave it unsettled.
- */
-export function confirmedReadings(
-  readings: RefReading[],
-  recorded: RecordedDependencies | undefined
-): RefReading[] {
-  if (readings.length === 1) return readings;
-  const records = Object.entries(recorded ?? {});
-
-  return readings.filter((reading) => {
-    const identity = reading.location?.identity;
-    if (identity === undefined) return false;
-    return records.some(([key, record]) => {
-      if (record?.repo !== identity) return false;
-      if (isBrowsedReading(reading)) return true;
-      if (!isNamedReading(reading)) return false;
-      return reading.recipe === undefined
-        ? key.startsWith(`${reading.namespace}/`)
-        : key === refKey(reading);
-    });
-  });
-}
-
-/** What `settleDependency` may consult, beyond the dependency itself. */
-export type SettleDependencyOptions = {
-  /** What the declaring version's index entry records about its dependencies. */
-  recorded?: RecordedDependencies;
-  /**
-   * Whether a reading is already known to be right from what is on this
-   * machine: its repository is trusted and its cached index publishes what it
-   * names. Used only when the index recorded nothing, and it never fetches.
-   */
-  known?: (reading: RefReading) => boolean;
-};
-
-/**
- * The one reading a manifest dependency settles on, or undefined when it reads
- * more than one way and nothing at hand says which: the declaring recipe's
- * index recorded no answer, and what this machine already knows does not pick
- * exactly one.
- *
- * settleDependency("workflow/alpha");
- * // -> { namespace: "workflow", recipe: "alpha" }
- *
- * @param written - The dependency as the manifest wrote it.
- * @param options - The index's record, and what is known locally.
- */
-export function settleDependency(
-  written: string,
-  options: SettleDependencyOptions = {}
-): RefReading | undefined {
-  const readings = parseRef(written, RefSource.Manifest);
-  if (readings.length === 1) return readings[0];
-
-  const confirmed = confirmedReadings(readings, options.recorded);
-  if (confirmed.length === 1) return confirmed[0];
-
-  if (options.known !== undefined) {
-    const known = readings.filter(options.known);
-    if (known.length === 1) return known[0];
-  }
-  return undefined;
-}