@sous-io/sous 0.2.37 → 1.0.2

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

@@ -1,261 +0,0 @@
-/**
- * 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[]> {
-    return this.loadSync();
-  }
-
-  /**
-   * The same list, read synchronously. The lockfile and the manifests are
-   * ordinary files, and the settings scope a build renders with is assembled
-   * synchronously, so the build path needs this form.
-   */
-  loadSync(): 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

@@ -1,231 +0,0 @@
-/**
- * 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";
-import { HIDDEN_VALUE } from "./secrets.js";
-
-/** 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

@@ -1,20 +0,0 @@
-/**
- * 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 "./answers.js";
-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";
-export * from "./secrets.js";