@sous-io/sous 0.1.1 → 0.2.0

package/src/lib/refs/pick.ts

@@ -0,0 +1,147 @@
+/**
+ * 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

@@ -0,0 +1,61 @@
+/**
+ * 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",
+}
+
+/**
+ * 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/repos/catalog-display.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared display helpers for the browsing commands.
+ *
+ * `sous namespace show` and `sous recipe list` both print a table of recipes,
+ * and every one of the four commands turns the catalog's words into the ones a
+ * person reads. One module holds them so the four never drift apart in wording.
+ *
+ * The labeled facts block is the one `sous vars show` prints; it is rendered by
+ * `renderFacts`, which is already generic over a label and its lines.
+ */
+
+import { renderFacts, type LabeledFact } from "../vars/display.js";
+import { log, wrapColumns } from "../../utils/formatting.js";
+import type { TableColumn } from "../../utils/table.js";
+import type {
+  NamespaceCoverage,
+  RecipeListing,
+  VersionStatus,
+} from "./catalog.js";
+
+/** How far every line of a browsing command's output is indented. */
+export const INDENT = 2;
+
+/**
+ * The columns a recipe listing shows. The recipe and its versions are why
+ * anybody ran the command, so they stay however narrow the terminal is; the
+ * description takes the room that is left and wraps rather than being cut.
+ */
+export const RECIPE_COLUMNS: TableColumn[] = [
+  { key: "key", header: "Recipe", kind: "path", overflow: "truncate", minWidth: 12 },
+  { key: "repo", header: "Repository", overflow: "truncate", priority: "medium" },
+  { key: "latest", header: "Latest", overflow: "truncate", minWidth: 6 },
+  { key: "pinned", header: "Pinned", overflow: "truncate", minWidth: 6 },
+  { key: "subscribed", header: "Subscribed", priority: "medium" },
+  {
+    key: "description",
+    header: "What it is",
+    overflow: "wrap",
+    flex: 1,
+    priority: "low",
+    minWidth: 16,
+  },
+];
+
+/** One rendered recipe row, in the shape `RECIPE_COLUMNS` reads. */
+export type RecipeRow = {
+  key: string;
+  repo: string;
+  latest: string;
+  pinned: string;
+  subscribed: string;
+  description: string;
+};
+
+/**
+ * Turns recipe listings into table rows. A recipe the project does not pin
+ * leaves the pinned column blank, because there is nothing to report there
+ * rather than something worth a word.
+ *
+ * @param listings - What the catalog produced.
+ */
+export function recipeRows(listings: RecipeListing[]): RecipeRow[] {
+  return listings.map((entry) => ({
+    key: entry.key,
+    repo: entry.repo,
+    latest: entry.latest ?? "none published",
+    pinned: entry.pinned ?? "",
+    subscribed: entry.subscribed ? "yes" : "no",
+    description: entry.description ?? "no description published",
+  }));
+}
+
+/**
+ * Plain-language wording for how much of a namespace a project subscribes to.
+ *
+ * @param coverage - What the catalog worked out.
+ */
+export function describeCoverage(coverage: NamespaceCoverage): string {
+  if (coverage === "whole namespace") return "the whole namespace";
+  if (coverage === "some recipes") return "some recipes";
+  return "no";
+}
+
+/**
+ * Plain-language wording for what one published version is to this project.
+ *
+ * @param status - What the catalog worked out.
+ */
+export function describeVersionStatus(status: VersionStatus): string {
+  if (status === "latest and pinned") return "the latest version, and the one pinned here";
+  if (status === "latest") return "the latest version";
+  if (status === "pinned") return "the version pinned here";
+  return "an earlier version";
+}
+
+/**
+ * Prints a labeled facts block, wrapped to the terminal. The renderer indents
+ * the block itself, so every facts block in the CLI sits at the same depth
+ * whichever command printed it.
+ *
+ * @param facts - The facts to print.
+ */
+export function printFacts(facts: LabeledFact[]): void {
+  for (const line of renderFacts(facts, wrapColumns())) log(line);
+}
+
+/**
+ * One labeled fact, when there is anything to say. Used to keep an absent field
+ * out of a facts block rather than printing an empty line for it.
+ *
+ * @param label - The label to show.
+ * @param value - The text beside it, or undefined to leave the fact out.
+ */
+export function factIf(label: string, value: string | undefined): LabeledFact[] {
+  return value === undefined || value.length === 0 ? [] : [{ label, lines: [value] }];
+}

package/src/lib/repos/catalog-inputs.ts

@@ -0,0 +1,160 @@
+/**
+ * Wiring the catalog to a running command.
+ *
+ * `catalog.ts` is pure: it reads indexes, a lockfile and a list of subscription
+ * keys. This module is where those come from in a real project, and it is
+ * deliberately the only place that knows: the subscription service for the
+ * trusted repositories and their cached indexes, the lockfile service for what
+ * is pinned, the links map and the store for a recipe's own files, and
+ * `recipeOutputs` for where a content kind lands.
+ *
+ * Nothing here downloads anything. A repository whose index has never been
+ * fetched is left out of the catalog and named separately, so a browsing command
+ * is safe offline.
+ */
+
+import type { Settings, VarScope } from "../settings.js";
+import type { SubscriptionService } from "./subscription-service.js";
+import type { CatalogInputs, CatalogRepo } from "./catalog.js";
+import { linkedPathFor } from "./links.js";
+import { mapLinkedRecipes, readRecipeManifestIn } from "./locked-recipes.js";
+import { WRITABLE_CONTENT_KINDS, destinationsFor } from "./recipe-targets.js";
+import type { WritableContentKind } from "./recipe-targets.js";
+
+/** What building the catalog's inputs needs. */
+export type CatalogInputsOptions = {
+  /** The subscription service for this project. */
+  service: SubscriptionService;
+  /** The project's `.sous/` directory. */
+  sousDir: string;
+  /** The merged project config. */
+  settings: Settings;
+  /**
+   * The resolved settings scope, when the caller has one. Only the destinations
+   * a recipe's files land in need it, so a command that does not show them may
+   * leave it out.
+   */
+  scope?: VarScope;
+  /** The environment to read; decides where the store and the links map are. */
+  env?: NodeJS.ProcessEnv;
+};
+
+/** The catalog's inputs, plus what could not be read. */
+export type CatalogContext = {
+  /** What the catalog functions read. */
+  inputs: CatalogInputs;
+  /**
+   * Trusted repositories whose index has never been fetched, so nothing in them
+   * could be listed. Sorted.
+   */
+  notFetched: string[];
+};
+
+/**
+ * Builds the catalog's inputs for one project: every trusted repository whose
+ * index sous already has, the lockfile, and the subscription keys the project
+ * declares.
+ *
+ * @param options - The subscription service, the project's directory and config.
+ */
+export function catalogContextFor(options: CatalogInputsOptions): CatalogContext {
+  const { service } = options;
+  const env = options.env ?? process.env;
+
+  const repos: CatalogRepo[] = [];
+  const notFetched: string[] = [];
+
+  const trusted = service.currentRepos();
+  for (const name of Object.keys(trusted).sort()) {
+    const index = service.cachedIndex(name);
+    if (index === undefined) {
+      notFetched.push(name);
+      continue;
+    }
+    const url = trusted[name]?.url;
+    repos.push({ name, ...(url === undefined ? {} : { url }), index });
+  }
+
+  const inputs: CatalogInputs = {
+    repos,
+    lock: service.lockService.read(),
+    subscriptions: Object.keys(service.allSubscriptions()).sort(),
+    readManifest: (recipe) => {
+      const directory = recipeFilesDirectory({
+        service,
+        sousDir: options.sousDir,
+        env,
+        repo: recipe.repo,
+        key: recipe.key,
+        namespace: recipe.namespace,
+        name: recipe.name,
+        version: recipe.version,
+      });
+      return directory === undefined ? undefined : readRecipeManifestIn(directory);
+    },
+    destinationsFor: (kind) => {
+      // Config layers are loaded, not written into the project, so they land
+      // nowhere a listing could name.
+      if (!isWritableKind(kind)) return [];
+      return destinationsFor(kind, {
+        sousDir: options.sousDir,
+        settings: options.settings,
+        ...(options.scope === undefined ? {} : { scope: options.scope }),
+        env,
+      });
+    },
+  };
+
+  return { inputs, notFetched };
+}
+
+/** Which recipe, at which version, in which of this project's repositories. */
+export type RecipeFilesQuery = {
+  /** The subscription service, which knows the store and the repository identities. */
+  service: SubscriptionService;
+  /** The project's `.sous/` directory, which holds the links map. */
+  sousDir: string;
+  /** The environment to read; decides where the store is. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /** The short name of the repository publishing it. */
+  repo: string;
+  /** The recipe key, `namespace/recipe`. */
+  key: string;
+  namespace: string;
+  name: string;
+  /** The exact version wanted. */
+  version: string;
+};
+
+/**
+ * The directory one published recipe's files are read from: a linked working
+ * copy when the repository is linked, and the store entry for that exact
+ * version otherwise. Undefined when neither is on this machine.
+ *
+ * Nothing is fetched, and the directory is not checked for existence: the
+ * caller reads what is there, and an absent manifest is an ordinary answer.
+ *
+ * @param input - The recipe's identity, and where this project keeps its state.
+ */
+export function recipeFilesDirectory(input: RecipeFilesQuery): string | undefined {
+  const checkout = linkedPathFor(input.repo, input.sousDir, input.env ?? process.env);
+  if (checkout !== undefined) {
+    const linked = mapLinkedRecipes(checkout)[input.key];
+    if (linked !== undefined) return linked;
+  }
+
+  const identity = input.service.identityForRepo(input.repo);
+  if (identity === undefined) return undefined;
+
+  return input.service.store.entryDir({
+    identity,
+    namespace: input.namespace,
+    name: input.name,
+    version: input.version,
+  });
+}
+
+/** True when a content kind's files are written into the project. */
+function isWritableKind(kind: string): kind is WritableContentKind {
+  return (WRITABLE_CONTENT_KINDS as readonly string[]).includes(kind);
+}