@sous-io/sous 0.1.1 → 0.2.1

package/src/lib/vars/definition-source.ts

@@ -0,0 +1,252 @@
+/**
+ * Where variable definitions come from.
+ *
+ * A definition is a published specification, not a value: it says what a
+ * variable is called, what shape an answer takes, and what question to ask.
+ * Definitions ship inside recipe manifests, so the real source is the set of
+ * recipes a project's lockfile pins. Every consumer goes through ONE seam,
+ * `loadProjectDefinitions`; nothing else in the variables layer knows where
+ * definitions came from, which is what lets `sous vars ask --file` read a
+ * standalone file through the same machinery.
+ */
+
+import path from "node:path";
+import { z } from "zod";
+import { parseFormat } from "../repos/formats/common.js";
+import {
+  variableDefinitionSchema,
+  type VariableDefinition,
+} from "../repos/formats/recipe-manifest.js";
+import { loadManifestFile } from "../repos/load-manifest.js";
+import {
+  listLockedRecipes,
+  readProjectLockfile,
+  readRecipeManifestIn,
+} from "../repos/locked-recipes.js";
+import type { Settings } from "../settings.js";
+
+/** Which recipe published a definition, spelled out for display and for naming. */
+export interface DefiningRecipe {
+  /** The short name of the repository the recipe came from. */
+  repo: string;
+  /** The recipe's namespace. */
+  namespace: string;
+  /** The recipe's name. */
+  name: string;
+  /** The exact version of the recipe in play. */
+  version: string;
+  /**
+   * Where the repository lives: a URL for a hosted repository, or an absolute
+   * path for one read through the `local` provider. Used to show a recipe as a
+   * link rather than as a bare name.
+   */
+  url?: string;
+  /** The recipe's folder inside the repository, when it is known. */
+  path?: string;
+  /** The recipe's directory on this machine, when it is present. */
+  dir?: string;
+}
+
+/** One variable definition together with the recipe that published it. */
+export interface DefinedVariable {
+  /** The published specification. */
+  definition: VariableDefinition;
+  /** The recipe the definition came from. */
+  recipe: DefiningRecipe;
+  /**
+   * How this variable came to be in play: the subscribed recipe first, then
+   * each recipe it depends on, ending with the recipe that declares the
+   * definition. A direct subscription has one entry; an indirect one shows the
+   * whole chain. Absent when nothing recorded it, in which case the defining
+   * recipe stands for itself.
+   */
+  requiredBy?: DefiningRecipe[];
+}
+
+/** Anything that can produce the variable definitions in play for a project. */
+export interface VariableDefinitionSource {
+  /** Loads every definition this source knows about. */
+  load(): Promise<DefinedVariable[]>;
+}
+
+/**
+ * A source backed by a fixed array. Used by tests and by any caller that has
+ * already assembled its definitions.
+ */
+export class StaticDefinitionSource implements VariableDefinitionSource {
+  /**
+   * @param defined - The definitions this source returns.
+   */
+  constructor(private readonly defined: DefinedVariable[]) {}
+
+  /** Returns the definitions handed to the constructor. */
+  async load(): Promise<DefinedVariable[]> {
+    return this.defined;
+  }
+}
+
+/**
+ * The project's own definitions: every variable declared by every recipe the
+ * lockfile pins, whether the project subscribed to it directly or a dependency
+ * pulled it in.
+ *
+ * Both kinds count, deliberately. A recipe may `depends` on another purely to
+ * reuse its published variable definitions, and a build that cannot answer
+ * those variables is just as broken as one that cannot answer a subscription's.
+ *
+ * A recipe the store does not hold yet contributes nothing rather than failing:
+ * a fresh clone lists what it can until `sous build` restores the rest.
+ */
+export class ProjectDefinitionSource implements VariableDefinitionSource {
+  /**
+   * @param settings - The merged project config, which holds the subscriptions.
+   * @param sousDir - The project's `.sous/` directory, where the lockfile lives.
+   * @param env - The environment to read; decides where the store is.
+   */
+  constructor(
+    private readonly settings: Settings,
+    private readonly sousDir: string,
+    private readonly env: NodeJS.ProcessEnv = process.env
+  ) {}
+
+  /** Every variable published by every recipe this project's lockfile pins. */
+  async load(): Promise<DefinedVariable[]> {
+    void this.settings;
+
+    const defined: DefinedVariable[] = [];
+    const lock = readProjectLockfile(this.sousDir);
+
+    for (const located of listLockedRecipes({ sousDir: this.sousDir, env: this.env })) {
+      if (!located.present) continue;
+
+      const manifest = readRecipeManifestIn(located.dir);
+      if (manifest === undefined) continue;
+
+      const url = lock.repos[located.repo]?.url;
+      const recipe: DefiningRecipe = {
+        repo: located.repo,
+        namespace: located.namespace,
+        name: located.name,
+        version: located.version,
+        dir: located.dir,
+        ...(url === undefined ? {} : { url }),
+      };
+      for (const definition of manifest.variables ?? []) {
+        defined.push({ definition, recipe });
+      }
+    }
+
+    return defined;
+  }
+}
+
+/**
+ * Builds the definition source for a project. This is the single injection
+ * point every `sous vars` command uses.
+ *
+ * @param settings - The merged project config.
+ * @param sousDir - The project's `.sous/` directory.
+ * @param env - The environment to read; decides where the store is.
+ */
+export function loadProjectDefinitions(
+  settings: Settings,
+  sousDir: string,
+  env: NodeJS.ProcessEnv = process.env
+): VariableDefinitionSource {
+  return new ProjectDefinitionSource(settings, sousDir, env);
+}
+
+// --- Standalone definition files ------------------------------------------------------------------
+
+/**
+ * A standalone definitions document: the same `variables:` array a recipe
+ * manifest carries, in a file of its own. `sous vars ask --file` reads one of
+ * these, which is how a project asks questions that are not published by any
+ * recipe yet.
+ *
+ * It is the same schema, so the same rules apply: every definition must carry a
+ * description and an example, and both are shown when the question is asked.
+ */
+export const definitionsFileSchema = z.object({
+  /** The definitions to ask, in the recipe manifest's own shape. */
+  variables: z.array(variableDefinitionSchema).min(1, "must list at least one variable"),
+});
+
+/** A validated standalone definitions document. */
+export type DefinitionsFile = z.infer<typeof definitionsFileSchema>;
+
+/** The repository name recorded for definitions that came from a local file. */
+export const LOCAL_FILE_REPO = "local";
+
+/** The namespace recorded for definitions that came from a local file. */
+export const LOCAL_FILE_NAMESPACE = "local";
+
+/**
+ * Turns a file name into a kebab-case pseudo-recipe name, so definitions read
+ * from a file still have a recipe to be attributed to and still generate the
+ * usual scoped environment variable names.
+ *
+ * @param filePath - The definitions file's path.
+ */
+export function pseudoRecipeName(filePath: string): string {
+  const base = path.basename(filePath).replace(/\.[^.]+$/, "");
+  const slug = base
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug.length === 0 || !/^[a-z]/.test(slug) ? `file-${slug}` : slug;
+}
+
+/**
+ * Loads a standalone definitions file (YAML or JSON, with the same permissive
+ * JSON dialect manifests use) and attributes every definition in it to a
+ * pseudo-recipe named after the file.
+ *
+ * @param filePath - Absolute path to the definitions file.
+ */
+export function loadDefinitionsFile(filePath: string): DefinedVariable[] {
+  const raw = loadManifestFile(filePath);
+  const parsed = parseFormat(
+    definitionsFileSchema,
+    raw,
+    filePath,
+    "variable definitions file"
+  );
+  const recipe: DefiningRecipe = {
+    repo: LOCAL_FILE_REPO,
+    namespace: LOCAL_FILE_NAMESPACE,
+    name: pseudoRecipeName(filePath),
+    version: "0.0.0",
+    dir: filePath,
+  };
+  return parsed.variables.map((definition) => ({ definition, recipe }));
+}
+
+/** A source backed by a standalone definitions file. */
+export class FileDefinitionSource implements VariableDefinitionSource {
+  /**
+   * @param filePath - Absolute path to the definitions file.
+   */
+  constructor(private readonly filePath: string) {}
+
+  /** Reads and validates the file, throwing a ConfigError when it does not fit. */
+  async load(): Promise<DefinedVariable[]> {
+    return loadDefinitionsFile(this.filePath);
+  }
+}
+
+/**
+ * The display key for a defined variable: `namespace/recipe.variableName`.
+ * Sorting and lookups use it, so one variable never appears twice under two
+ * spellings.
+ *
+ * @param defined - The definition and the recipe that published it.
+ */
+export function definedVariableKey(defined: DefinedVariable): string {
+  return `${defined.recipe.namespace}/${defined.recipe.name}.${defined.definition.name}`;
+}
+
+/** The recipe's key (`namespace/recipe`), as shown in listings. */
+export function definingRecipeKey(recipe: DefiningRecipe): string {
+  return `${recipe.namespace}/${recipe.name}`;
+}

package/src/lib/vars/display.ts

@@ -0,0 +1,233 @@
+/**
+ * Shared display helpers for the `sous vars` commands: masking secrets, and the
+ * labeled facts block both the listing and the ask report use. The tables those
+ * commands print are laid out by the shared renderer in `src/utils/table.ts`.
+ */
+
+import path from "node:path";
+import type { VariableDefinition } from "../repos/formats/recipe-manifest.js";
+import {
+  BULLET,
+  formatVariable,
+  VARIABLE_INDENT,
+  wrapColumns,
+  type VariableEntry,
+} from "../../utils/formatting.js";
+import {
+  definingRecipeKey,
+  type DefinedVariable,
+  type DefiningRecipe,
+} from "./definition-source.js";
+import { constraintBullets } from "./validate.js";
+
+/** What the value column shows for a secret whose answer is known. */
+export const HIDDEN_VALUE = "(hidden)";
+
+/** What the value column shows for a variable nothing has answered. */
+export const UNANSWERED_VALUE = "(unanswered)";
+
+/**
+ * The display form of a value: a secret never prints, so that a terminal
+ * recording, a screen share or a scrollback buffer cannot leak one.
+ *
+ * @param value - The stored value, or undefined when there is no answer.
+ * @param secret - Whether the definition declared the variable a secret.
+ */
+export function displayValue(value: string | undefined, secret: boolean): string {
+  if (value === undefined) return UNANSWERED_VALUE;
+  if (secret) return HIDDEN_VALUE;
+  return value;
+}
+
+/**
+ * The two documentation rows every command shows for a variable: the
+ * publisher's description, and the sample answer that makes the one-line
+ * question concrete. A published definition must carry both, so every caller
+ * can show them without checking first.
+ *
+ * @param definition - The variable definition to document.
+ * @returns Label-to-text rows, ready for `showVariables` or an aligned label block.
+ */
+export function documentationRows(
+  definition: VariableDefinition
+): Record<string, string> {
+  return {
+    About: definition.description,
+    "For example": String(definition.example),
+  };
+}
+
+// --- The labeled facts about one variable --------------------------------------------------------
+
+/**
+ * One line of a fact: the text, and any secondary detail shown after it in
+ * muted grey (a repository location, for instance) rather than in parentheses.
+ */
+export interface FactLine {
+  /** The text shown beside the label. */
+  text: string;
+  /** The secondary detail that follows it, muted. */
+  detail?: string;
+}
+
+/** One labeled fact: the label, and the lines shown beside it. */
+export interface LabeledFact {
+  /**
+   * The label, in the plain-word form every key and value display uses
+   * (`default`, `required-by`); the `@` the recipe manifests write is not part
+   * of it.
+   */
+  label: string;
+  /** The text shown beside the label, one entry per line. */
+  lines: Array<string | FactLine>;
+}
+
+/** True when a repository location is a URL rather than a path on this machine. */
+function isHostedUrl(location: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(location) || location.startsWith("git@");
+}
+
+/**
+ * Where a recipe's source lives: the repository URL with the recipe's folder
+ * appended for a hosted repository, the filesystem path for one read from this
+ * machine, and nothing at all when neither was recorded.
+ *
+ * @param recipe - The recipe to locate.
+ */
+export function recipeLocation(recipe: DefiningRecipe): string | undefined {
+  if (recipe.url !== undefined && isHostedUrl(recipe.url)) {
+    const base = recipe.url.replace(/\/+$/, "");
+    return recipe.path === undefined ? base : `${base}/${recipe.path}`;
+  }
+
+  return recipe.url !== undefined
+    ? recipe.path === undefined
+      ? recipe.url
+      : path.join(recipe.url, recipe.path)
+    : recipe.dir;
+}
+
+/**
+ * A recipe written as a fact line: its key, with its location following it in
+ * muted grey. The location is a trailing detail rather than a parenthetical, so
+ * the recipe key stays the thing the eye lands on.
+ *
+ * @param recipe - The recipe to link to.
+ */
+export function recipeLink(recipe: DefiningRecipe): FactLine {
+  const key = definingRecipeKey(recipe);
+  const location = recipeLocation(recipe);
+  return location === undefined ? { text: key } : { text: key, detail: location };
+}
+
+/** Everything the facts renderer needs that the definition itself does not carry. */
+export interface VariableFactsInput {
+  /** The variable and the recipe that published it. */
+  defined: DefinedVariable;
+  /** Absolute path of the env file the answer is stored in. */
+  storagePath: string;
+  /** The environment variable name the answer is stored under. */
+  storedAs: string;
+}
+
+/**
+ * The labeled facts about one variable, in the order both the advanced view and
+ * `sous vars show` print them. One function builds them so the two never drift
+ * apart in wording or in order.
+ *
+ * @param input - The variable, where its answer is stored, and under what name.
+ * @returns The facts, ready for `renderFacts`.
+ */
+export function variableFacts(input: VariableFactsInput): LabeledFact[] {
+  const { defined, storagePath, storedAs } = input;
+  const { definition } = defined;
+  const facts: LabeledFact[] = [];
+
+  if (definition.default !== undefined) {
+    facts.push({ label: "default", lines: [String(definition.default)] });
+  }
+  facts.push({ label: "example", lines: [String(definition.example)] });
+
+  const chain = defined.requiredBy ?? [defined.recipe];
+  const requiredBy: Array<string | FactLine> = [recipeLink(chain[0] ?? defined.recipe)];
+  if (chain.length > 1) {
+    requiredBy.push(
+      `pulled in through ${chain.map((recipe) => definingRecipeKey(recipe)).join(" then ")}`
+    );
+  }
+  facts.push({ label: "required-by", lines: requiredBy });
+  facts.push({ label: "defined-by", lines: [recipeLink(defined.recipe)] });
+  facts.push({ label: "storage-path", lines: [storagePath] });
+  facts.push({ label: "stored-as", lines: [storedAs] });
+  facts.push({
+    label: "constraints",
+    lines: constraintBullets(definition).map((bullet) => `${BULLET} ${bullet}`),
+  });
+
+  return facts;
+}
+
+/**
+ * The facts the basic view of a question shows, in the order it shows them. It
+ * is a subset of the same list the advanced view prints, selected by label, so
+ * the two views can never word a fact differently or lay it out differently.
+ */
+export const BASIC_FACT_LABELS = [
+  "default",
+  "example",
+  "stored-as",
+  "storage-path",
+];
+
+/**
+ * Picks the named facts out of a fact list, in the order the labels were given
+ * and skipping any the variable does not have (a variable with no default has
+ * no `default` fact).
+ *
+ * @param facts - Every fact about the variable.
+ * @param labels - The labels to keep, in the order they should be shown.
+ */
+export function selectFacts(facts: LabeledFact[], labels: string[]): LabeledFact[] {
+  const byLabel = new Map(facts.map((fact) => [fact.label, fact]));
+  return labels
+    .map((label) => byLabel.get(label))
+    .filter((fact): fact is LabeledFact => fact !== undefined);
+}
+
+/**
+ * How far a rendered facts block is indented under the text above it. It is the
+ * same depth as every other key and value block, so a facts block never reads
+ * as a different kind of list.
+ */
+export const FACTS_INDENT = VARIABLE_INDENT;
+
+/**
+ * Lays the labeled facts out through the one key and value renderer, so a fact
+ * about a variable looks exactly like every other key and value sous prints:
+ * labels aligned, colons lined up, values in the value color, and a location
+ * trailing in muted grey.
+ *
+ * @param facts - The facts to render.
+ * @param width - The column to wrap at, indentation included.
+ * @returns The rendered lines, colored for a terminal, indented by `FACTS_INDENT`.
+ */
+export function renderFacts(facts: LabeledFact[], width = wrapColumns()): string[] {
+  const labelWidth = Math.max(...facts.map((fact) => fact.label.length));
+  const lines: string[] = [];
+
+  for (const fact of facts) {
+    fact.lines.forEach((raw, index) => {
+      const line: FactLine = typeof raw === "string" ? { text: raw } : raw;
+      const entry: VariableEntry = {
+        // A fact needing more than one line labels only the first of them; the
+        // rest continue underneath it.
+        label: index === 0 ? fact.label : "",
+        value: line.text,
+        ...(line.detail === undefined ? {} : { detail: line.detail }),
+      };
+      lines.push(...formatVariable(entry, { indent: FACTS_INDENT, labelWidth, width }));
+    });
+  }
+
+  return lines;
+}

package/src/lib/vars/index.ts

@@ -0,0 +1,18 @@
+/**
+ * The variables layer: where variable definitions come from, how a stored
+ * answer is found, how an answer is validated, and how a question is asked.
+ *
+ * Import from here rather than from the individual modules, so the commands and
+ * later phases have one place to look for what this layer offers.
+ */
+
+export * from "./definition-source.js";
+export * from "./display.js";
+export * from "./ladder.js";
+export * from "./mappings.js";
+export * from "./names.js";
+export * from "./validate.js";
+export * from "./ask.js";
+export * from "./report.js";
+export * from "./preanswers.js";
+export * from "./question-plan.js";