@sous-io/sous 0.2.37 → 1.0.2

package/src/lib/vars/preanswers.ts

@@ -1,395 +0,0 @@
-/**
- * Answering a recipe's questions before it asks them.
- *
- * A person subscribing at a terminal answers each question as it comes. A
- * script, a continuous integration job or an agent has no terminal and knows
- * every answer already, so it supplies them up front: `--answer name=value`,
- * repeated, or a file of the same pairs. Both `sous subscription add` and
- * `sous vars ask` take them, and both hand them here, so the rules are written
- * once.
- *
- * The rules are deliberately unforgiving, because a supplied answer is never
- * seen by a human before it is stored:
- *
- *   - Every answer is validated against its definition BEFORE anything is
- *     written, so a run either stores all of them or none of them.
- *   - A name no recipe declares fails the run and lists every variable the
- *     closure does declare, so a typo can never become a stored value under a
- *     name nothing reads.
- *   - An answer for a variable that already has one replaces it, where it
- *     already lives, and the report says so.
- */
-
-import path from "node:path";
-import { ConfigError } from "../errors.js";
-import { updateEnvFile } from "../env-file.js";
-import { loadManifestFile } from "../repos/load-manifest.js";
-import {
-  answerFileFor,
-  answerHeader,
-  type AnsweredVariable,
-  type AskOptions,
-  type StoragePlan,
-} from "./ask.js";
-import {
-  definedVariableKey,
-  definingRecipeKey,
-  type DefinedVariable,
-} from "./definition-source.js";
-import { displayValue } from "./display.js";
-import {
-  recordAnswerInContext,
-  resolveVariable,
-  type LadderContext,
-} from "./ladder.js";
-import { bareName } from "./names.js";
-import { validateAnswer } from "./validate.js";
-
-/** How an answer supplied on the command line is written. */
-export const ANSWER_FLAG_FORM = "--answer <name>=<value>";
-
-/** The sentence appended to every error about a supplied answer. */
-export const ANSWER_NAME_HELP =
-  "A name is spelled exactly as the recipe declares it, in camelCase; the full " +
-  "'namespace/recipe.name' key works too.";
-
-/** One answer supplied ahead of the questions. */
-export interface ProvidedAnswer {
-  /** The variable's declared name, or its `namespace/recipe.name` key. */
-  name: string;
-  /** The answer, exactly as it was written. */
-  value: string;
-  /** Where it came from, named in every error: the flag, or the file's path. */
-  from: string;
-}
-
-/**
- * Splits one `name=value` pair. The split is on the FIRST `=` only, so a value
- * may contain as many more as it likes (a connection string, a query, a base64
- * blob).
- *
- * @param entry - The pair as written on the command line.
- * @param from - Where it came from, named in the error.
- *
- * @example
- * parseAnswerPair("apiUrl=https://x.test/?a=1&b=2");
- * // -> { name: "apiUrl", value: "https://x.test/?a=1&b=2", from: "--answer" }
- */
-export function parseAnswerPair(entry: string, from = ANSWER_FLAG_FORM): ProvidedAnswer {
-  const at = entry.indexOf("=");
-  const name = at === -1 ? "" : entry.slice(0, at).trim();
-
-  if (at === -1 || name.length === 0) {
-    throw new ConfigError(
-      `'${entry}' is not an answer sous can read.\n` +
-        `  Write one as '${ANSWER_FLAG_FORM}', for example ` +
-        `'--answer apiUrl=https://api.example.com'.\n` +
-        `  Everything after the first '=' is the answer, so a value may contain more of them.`
-    );
-  }
-
-  return { name, value: entry.slice(at + 1), from };
-}
-
-/**
- * Reads a file of answers: a YAML or JSON map of the same `name: value` pairs.
- * It goes through the manifest loader, so the JSON dialect is the permissive
- * one and a file can carry comments explaining its answers.
- *
- * @param filePath - Absolute path to the answers file.
- */
-export function loadAnswersFile(filePath: string): ProvidedAnswer[] {
-  const raw = loadManifestFile(filePath);
-
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    throw new ConfigError(
-      `The answers file at ${filePath} is not a map of answers.\n` +
-        `  It holds one entry per variable, written as 'name: value'.`
-    );
-  }
-
-  const answers: ProvidedAnswer[] = [];
-  for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
-    if (typeof value === "object" && value !== null) {
-      throw new ConfigError(
-        `The answer for '${name}' in ${filePath} is a list or a map, and an answer is a ` +
-          `single value.\n` +
-          `  Answers are stored in environment files, which hold text; write the answer ` +
-          `as a string, a number or a boolean.`
-      );
-    }
-    if (value === null || value === undefined) {
-      throw new ConfigError(
-        `The answer for '${name}' in ${filePath} is empty.\n` +
-          `  Write the value the variable should be given, or leave the entry out ` +
-          `entirely so sous asks for it.`
-      );
-    }
-    answers.push({ name: name.trim(), value: String(value), from: filePath });
-  }
-
-  return answers;
-}
-
-/** The two ways a caller supplies answers ahead of the questions. */
-export interface ProvidedAnswerInputs {
-  /** Every `--answer name=value` pair, in the order they were written. */
-  answer?: string[];
-  /** A file of `name: value` pairs, absolute or relative to `cwd`. */
-  answersFile?: string;
-  /** Where a relative answers file is resolved from. Defaults to the real cwd. */
-  cwd?: string;
-}
-
-/**
- * Collects every supplied answer into one list, with the file read first and
- * the flags laid over it, so `--answer` wins over the file for the same name.
- * A name given twice in the same place keeps the last one written, which is how
- * every other repeated flag behaves.
- *
- * @param inputs - The flag values, and where a relative file path resolves from.
- */
-export function collectProvidedAnswers(inputs: ProvidedAnswerInputs): ProvidedAnswer[] {
-  const collected = new Map<string, ProvidedAnswer>();
-
-  if (inputs.answersFile !== undefined) {
-    const filePath = path.resolve(inputs.cwd ?? process.cwd(), inputs.answersFile);
-    for (const answer of loadAnswersFile(filePath)) collected.set(answer.name, answer);
-  }
-
-  for (const entry of inputs.answer ?? []) {
-    const answer = parseAnswerPair(entry);
-    collected.set(answer.name, answer);
-  }
-
-  return [...collected.values()];
-}
-
-/** True when a supplied name names this variable, by declared name or by key. */
-function matchesName(defined: DefinedVariable, name: string): boolean {
-  return defined.definition.name === name || definedVariableKey(defined) === name;
-}
-
-/**
- * The error a name nothing declares fails with: every variable the closure DOES
- * declare, grouped by the recipe that published it, so the caller can see the
- * spelling they meant rather than guessing at it again.
- *
- * @param answer - The supplied answer whose name matched nothing.
- * @param defined - Every variable definition in play.
- */
-export function unknownAnswerError(
-  answer: ProvidedAnswer,
-  defined: DefinedVariable[]
-): ConfigError {
-  const lines = [
-    `Nothing in this project defines a variable called '${answer.name}', so the answer ` +
-      `given with ${answer.from} cannot be stored.`,
-  ];
-
-  if (defined.length === 0) {
-    lines.push(
-      "  No recipe this project subscribes to defines any variables yet, so there is " +
-        "nothing to answer."
-    );
-    return new ConfigError(lines.join("\n"));
-  }
-
-  const groups = new Map<string, string[]>();
-  for (const entry of defined) {
-    const key = definingRecipeKey(entry.recipe);
-    const names = groups.get(key) ?? [];
-    if (!names.includes(entry.definition.name)) names.push(entry.definition.name);
-    groups.set(key, names);
-  }
-
-  lines.push("", "  These are the variables in play, and the recipes that declare them:", "");
-  for (const [key, names] of groups) {
-    lines.push(`    ${key}`);
-    for (const name of names) lines.push(`      ${name}`);
-  }
-  lines.push("", `  ${ANSWER_NAME_HELP}`);
-
-  return new ConfigError(lines.join("\n"));
-}
-
-/**
- * The error a supplied answer that does not fit its definition fails with: the
- * variable, the constraint it violated, and the publisher's own example of a
- * real answer. A secret's value is never echoed back.
- *
- * @param answer - The supplied answer.
- * @param defined - The definition it was checked against.
- * @param message - The plain-language reason from `validateAnswer`.
- */
-export function invalidAnswerError(
-  answer: ProvidedAnswer,
-  defined: DefinedVariable,
-  message: string
-): ConfigError {
-  const { definition } = defined;
-  return new ConfigError(
-    `The answer given for '${answer.name}' does not fit the definition ` +
-      `${definingRecipeKey(defined.recipe)} publishes.\n` +
-      `  ${message}\n` +
-      `  For example: ${String(definition.example)}\n` +
-      `  The answer given with ${answer.from} was: ` +
-      `${displayValue(answer.value, definition.secret)}\n` +
-      `  Nothing was written; fix the answer and run the command again.`
-  );
-}
-
-/** What one run of `applyProvidedAnswers` did. */
-export interface AppliedAnswers {
-  /** Every answer that was stored, in the shape the ask report prints. */
-  stored: AnsweredVariable[];
-  /**
-   * The keys of every variable these answers settled. `askForMissing` skips
-   * them, so a supplied answer is never asked about as well as stored.
-   */
-  keys: string[];
-}
-
-/**
- * Where a supplied answer goes. A variable with no answer yet is stored exactly
- * where the interactive flow would store it: under its declared name, in the
- * file its scope asks for. A variable that ALREADY has an answer in one of the
- * project's env files is overwritten where that answer lives, because storing
- * the new value somewhere less specific would leave the old one winning and the
- * caller asking why nothing changed.
- *
- * @param defined - The variable being answered.
- * @param context - The environment layers, as they stand.
- */
-export function preAnswerPlan(
-  defined: DefinedVariable,
-  context: LadderContext
-): { plan: StoragePlan; replaced?: string; shadowedBy?: string } {
-  const fallback: StoragePlan = {
-    file: answerFileFor(defined.definition),
-    envName: bareName(defined.definition),
-  };
-  const existing = resolveVariable(defined, context);
-
-  if (existing === undefined) return { plan: fallback };
-
-  // A value the shell environment supplies is not sous's to rewrite, and it
-  // outranks both env files for as long as it is set; the answer is stored
-  // where it belongs and the report says what is covering it.
-  if (existing.source.file === "shell") {
-    return { plan: fallback, replaced: existing.value, shadowedBy: existing.source.envName };
-  }
-
-  return {
-    plan: { file: existing.source.file, envName: existing.source.envName },
-    replaced: existing.value,
-  };
-}
-
-/** One supplied answer, matched to a definition and coerced to its stored form. */
-export interface ApplicableAnswer {
-  /** The answer as it was supplied. */
-  answer: ProvidedAnswer;
-  /** The definition it answers. */
-  target: DefinedVariable;
-  /** The validated answer, in the form an env file holds. */
-  value: string;
-}
-
-/**
- * Matches every supplied answer to the definitions it answers and checks it
- * against each of them, without writing anything.
- *
- * A command calls this early, before it installs or writes anything at all, so
- * a bad answer fails the run cleanly rather than halfway through it. One name
- * can answer more than one definition, because two recipes may declare the same
- * variable; every one of them has to accept the value.
- *
- * @param defined - Every variable definition in play.
- * @param provided - The answers supplied ahead of the questions.
- * @returns One entry per definition each answer applies to.
- */
-export function validateProvidedAnswers(
-  defined: DefinedVariable[],
-  provided: ProvidedAnswer[]
-): ApplicableAnswer[] {
-  const applicable: ApplicableAnswer[] = [];
-
-  for (const answer of provided) {
-    const targets = defined.filter((entry) => matchesName(entry, answer.name));
-    if (targets.length === 0) throw unknownAnswerError(answer, defined);
-
-    for (const target of targets) {
-      const validated = validateAnswer(target.definition, answer.value, {
-        recipe: definingRecipeKey(target.recipe),
-      });
-      if (!validated.ok) throw invalidAnswerError(answer, target, validated.message);
-      applicable.push({ answer, target, value: String(validated.value) });
-    }
-  }
-
-  return applicable;
-}
-
-/**
- * Validates every supplied answer, then stores them all.
- *
- * Validation happens for all of them first, so a run with one bad answer in it
- * writes nothing at all rather than half of what it was given. A dry run
- * validates and reports without writing, but still records the answers in the
- * context it was handed, so the rest of the run plans as though they were
- * stored.
- *
- * @param defined - Every variable definition in play.
- * @param provided - The answers supplied ahead of the questions.
- * @param context - The environment layers, updated as answers are stored.
- * @param options - Where to write, and whether this is a dry run.
- * @returns What was stored, and which variables no longer need asking.
- */
-export function applyProvidedAnswers(
-  defined: DefinedVariable[],
-  provided: ProvidedAnswer[],
-  context: LadderContext,
-  options: AskOptions
-): AppliedAnswers {
-  const applicable = validateProvidedAnswers(defined, provided);
-
-  const stored: AnsweredVariable[] = [];
-  const keys: string[] = [];
-  /** Env entries this run has already written, so one file line is written once. */
-  const written = new Set<string>();
-
-  for (const entry of applicable) {
-    keys.push(definedVariableKey(entry.target));
-
-    const { plan, replaced, shadowedBy } = preAnswerPlan(entry.target, context);
-    const filePath = path.join(options.sousDir, plan.file);
-    const slot = `${plan.file}:${plan.envName}`;
-    if (written.has(slot)) continue;
-    written.add(slot);
-
-    const outcome =
-      options.dryRun === true
-        ? ("not written" as const)
-        : updateEnvFile(filePath, plan.envName, entry.value, {
-            header: answerHeader(entry.target),
-          });
-
-    // Recorded even on a dry run: everything after this point should plan as
-    // though the answer were already stored.
-    recordAnswerInContext(context, plan.file, plan.envName, entry.value);
-
-    stored.push({
-      defined: entry.target,
-      envName: plan.envName,
-      file: plan.file,
-      filePath,
-      value: entry.value,
-      outcome,
-      ...(replaced === undefined || replaced === entry.value ? {} : { replaced }),
-      ...(shadowedBy === undefined ? {} : { shadowedBy }),
-    });
-  }
-
-  return { stored, keys };
-}

package/src/lib/vars/question-plan.ts

@@ -1,241 +0,0 @@
-/**
- * The questions a subscription is going to ask, written out before it asks any
- * of them.
- *
- * A dry run is how a caller with no terminal finds out what a subscription
- * wants: every variable the closure declares, what each one is for, where its
- * answer will be stored, and whether something already answers it. With that in
- * hand the whole subscription can be done in one more command, every answer
- * supplied with `--answer`.
- *
- * The facts are laid out by the renderer `sous vars show` uses, so the labels
- * and the vocabulary are the same wherever a variable is described.
- */
-
-import path from "node:path";
-import { color } from "@oclif/color";
-import { palette, wrapColumns, wrapText } from "../../utils/formatting.js";
-import { answerFileFor, type AnswerFile } from "./ask.js";
-import { definingRecipeKey, type DefinedVariable } from "./definition-source.js";
-import { renderFacts, type LabeledFact } from "./display.js";
-import { describeSource, resolveVariable, type LadderContext } from "./ladder.js";
-import { bareName } from "./names.js";
-import { validateAnswer } from "./validate.js";
-
-/** One question the closure would ask, and what would happen to its answer. */
-export interface PlannedVariable {
-  /** The variable and the recipe that published it. */
-  defined: DefinedVariable;
-  /** The environment variable the answer would be stored under. */
-  storedAs: string;
-  /** The env file it would be stored in. */
-  file: AnswerFile;
-  /** That file's absolute path. */
-  filePath: string;
-  /** True when something already answers this variable, and the answer fits. */
-  answered: boolean;
-  /** Where the existing answer came from, in plain language. */
-  answeredFrom?: string;
-}
-
-/** What `planQuestions` needs beyond the definitions themselves. */
-export interface QuestionPlanOptions {
-  /** The project's `.sous/` directory, which holds both env files. */
-  sousDir: string;
-}
-
-/**
- * The first sentence of a description, which is what a plan shows; the rest is
- * in `sous vars show <name>`.
- *
- * @param text - The publisher's description.
- */
-export function firstSentence(text: string): string {
-  const match = /^.*?[.!?](?=\s|$)/s.exec(text.trim());
-  return (match?.[0] ?? text.trim()).replace(/\s+/g, " ");
-}
-
-/**
- * Works out, for every variable in play, where its answer would go and whether
- * anything answers it already.
- *
- * @param defined - Every variable definition the closure declares.
- * @param context - The environment layers and mapping records to resolve against.
- * @param options - Where the project's env files live.
- */
-export function planQuestions(
-  defined: DefinedVariable[],
-  context: LadderContext,
-  options: QuestionPlanOptions
-): PlannedVariable[] {
-  return defined.map((entry) => {
-    const file = answerFileFor(entry.definition);
-    const existing = resolveVariable(entry, context);
-    const answered =
-      existing !== undefined &&
-      validateAnswer(entry.definition, existing.value, {
-        recipe: definingRecipeKey(entry.recipe),
-      }).ok;
-
-    return {
-      defined: entry,
-      storedAs: answered ? existing!.source.envName : bareName(entry.definition),
-      file,
-      filePath: path.join(options.sousDir, file),
-      answered,
-      ...(answered ? { answeredFrom: describeSource(existing!.source) } : {}),
-    };
-  });
-}
-
-/** "1 question" or "3 questions", so no count is printed with the wrong noun. */
-function questionCount(count: number): string {
-  return count === 1 ? "1 question" : `${count} questions`;
-}
-
-/**
- * The labeled facts one planned question shows.
- *
- * @param planned - The planned question.
- * @param answerHints - Whether to name the `--answer` flag that answers it ahead of time.
- */
-export function plannedVariableFacts(
-  planned: PlannedVariable,
-  answerHints = true
-): LabeledFact[] {
-  const { definition } = planned.defined;
-
-  const facts: LabeledFact[] = [
-    { label: "about", lines: [firstSentence(definition.description)] },
-    { label: "example", lines: [String(definition.example)] },
-    { label: "stored-as", lines: [planned.storedAs] },
-    { label: "storage-path", lines: [planned.filePath] },
-    {
-      label: "answered",
-      lines: [
-        planned.answered
-          ? `yes, from ${planned.answeredFrom}`
-          : definition.required
-            ? "no, and this recipe requires an answer"
-            : "no, and an answer is optional",
-      ],
-    },
-  ];
-  if (answerHints) {
-    facts.push({ label: "answer-with", lines: [`--answer ${definition.name}=<value>`] });
-  }
-  return facts;
-}
-
-/** What `formatQuestionPlan` needs beyond the questions themselves. */
-export interface QuestionPlanFormatOptions {
-  /** The column to wrap descriptions at. */
-  width?: number;
-  /**
-   * Recipes in the closure whose questions are unknown: their files are not on
-   * this machine, and their repository's index does not record their
-   * questions. They are named in the plan rather than silently left out of it.
-   */
-  unreadable?: string[];
-  /**
-   * Whether the plan says how to answer its questions ahead of time: the
-   * `--answer` flag under each question, and a closing sentence. True for the
-   * dry run of a command that asks them; false where the plan only describes.
-   */
-  answerHints?: boolean;
-}
-
-/**
- * The one line that names the recipes whose questions are unknown. Nothing is
- * downloaded to plan, so a recipe this machine does not hold yet is described
- * from its repository's index, and an index written before sous recorded
- * questions there cannot say; naming those recipes is more useful than leaving
- * them out of the plan.
- *
- * @param unreadable - The recipe keys whose questions are unknown.
- * @param answerHints - Whether the plan belongs to a dry run that could be run for real.
- */
-function unreadableLine(unreadable: string[], answerHints: boolean): string {
-  const line =
-    `Not on this machine yet, and their repository's index does not record their ` +
-    `questions, so they cannot be listed: ${unreadable.join(", ")}.`;
-  return answerHints
-    ? `${line} A dry run downloads nothing; run this command again without ` +
-        `'--dry-run' to install them and be asked.`
-    : line;
-}
-
-/**
- * The whole plan as lines to print: one block per recipe, one labeled fact
- * sheet per variable, a line naming any recipe that could not be read, and a
- * closing sentence naming how to answer them all ahead of time.
- *
- * @param planned - Every question the closure would ask.
- * @param options - The wrap column, and any recipes that could not be read.
- * @returns The lines to print, without indentation.
- */
-export function formatQuestionPlan(
-  planned: PlannedVariable[],
-  options: QuestionPlanFormatOptions = {}
-): string[] {
-  const unreadable = options.unreadable ?? [];
-  const answerHints = options.answerHints ?? true;
-
-  const columns = options.width ?? wrapColumns();
-  /** Wraps one sentence to the width the caller's indentation leaves for it. */
-  const sentence = (text: string, paint = (line: string): string => line): string[] =>
-    wrapText(text, columns - 2).map(paint);
-
-  if (planned.length === 0) {
-    return unreadable.length === 0
-      ? sentence("None of these recipes ask any questions, so nothing needs answering.")
-      : sentence(unreadableLine(unreadable, answerHints), palette.note);
-  }
-
-  const unanswered = planned.filter((entry) => !entry.answered).length;
-  // When part of the closure could not be read, the count below describes only
-  // the part that could, and the sentence says so rather than overstating it.
-  const subject =
-    unreadable.length === 0 ? "These recipes ask" : "The recipes sous could read ask";
-
-  const lines: string[] = sentence(
-    unanswered === 0
-      ? `${subject} ${questionCount(planned.length)}, and everything they ask ` +
-        `is already answered.`
-      : `${subject} ${questionCount(planned.length)}, ` +
-        `${unanswered} of which nothing answers yet.`
-  );
-
-  const groups = new Map<string, PlannedVariable[]>();
-  for (const entry of planned) {
-    const key = definingRecipeKey(entry.defined.recipe);
-    groups.set(key, [...(groups.get(key) ?? []), entry]);
-  }
-
-  for (const [key, entries] of groups) {
-    lines.push("", `${key} asks ${questionCount(entries.length)}:`);
-    for (const entry of entries) {
-      lines.push("", `  ${color.cyan(entry.defined.definition.name)}`);
-      // The facts block indents itself, so the plan adds nothing on top of it.
-      lines.push(...renderFacts(plannedVariableFacts(entry, answerHints), columns - 2));
-    }
-  }
-
-  if (unreadable.length > 0) {
-    lines.push("", ...sentence(unreadableLine(unreadable, answerHints), palette.note));
-  }
-
-  if (unanswered > 0 && answerHints) {
-    lines.push(
-      "",
-      ...sentence(
-        "Answer them all ahead of time by running this command again without " +
-          "'--dry-run', with one '--answer <name>=<value>' for each, or with " +
-          "'--answers-file <path>'.",
-        palette.note
-      )
-    );
-  }
-
-  return lines;
-}