@sous-io/sous 0.2.37 → 1.0.2

package/src/lib/vars/ladder.ts

@@ -1,282 +0,0 @@
-/**
- * The resolution ladder: how sous decides whether a variable already has an
- * answer, and which environment variable supplied it.
- *
- * Five rungs, most specific first:
- *
- *   1. mapping    a record binding an arbitrary name to this exact variable
- *   2. recipe     SOUS_VAR_<NAMESPACE>_<RECIPE>_<VARIABLE>
- *   3. namespace  SOUS_VAR_<NAMESPACE>_<VARIABLE>
- *   4. shared     SOUS_VAR_<VARIABLE>
- *   5. bare       the definition's own `env` name, or the shared form
- *
- * Within a rung the real shell environment wins, then `.sous/.env.local`, then
- * `.sous/.env`; the same order the env file loader uses, so what the ladder
- * reports is what a build actually sees.
- *
- * The three sources are read separately rather than off `process.env`, because
- * by the time a command runs the env files have already been injected into the
- * process environment and the distinction would be lost.
- */
-
-import path from "node:path";
-import { ENV_DEFAULTS_NAME, ENV_LOCAL_NAME } from "../config-discovery.js";
-import { readEnvFileMap } from "../env-local.js";
-import type { Settings } from "../settings.js";
-import type { DefinedVariable } from "./definition-source.js";
-import { mappedNamesFor } from "./mappings.js";
-import {
-  bareName,
-  namespaceScopedName,
-  recipeScopedName,
-  sharedName,
-} from "./names.js";
-
-/** The rungs of the ladder, most specific first. */
-export const LADDER_RUNGS = ["mapping", "recipe", "namespace", "shared", "bare"] as const;
-
-/** One rung of the ladder. */
-export type LadderRung = (typeof LADDER_RUNGS)[number];
-
-/** Plain-language names for each rung, used in output. */
-export const RUNG_LABELS: Record<LadderRung, string> = {
-  mapping: "mapping record",
-  recipe: "recipe scope",
-  namespace: "namespace scope",
-  shared: "shared scope",
-  bare: "declared name",
-};
-
-/** Where a value was found: the real environment, or one of the two env files. */
-export type EnvSourceFile = "shell" | typeof ENV_LOCAL_NAME | typeof ENV_DEFAULTS_NAME;
-
-/** Plain-language names for each place a value can come from. */
-export const SOURCE_LABELS: Record<string, string> = {
-  shell: "the shell environment",
-  [ENV_LOCAL_NAME]: `the ${ENV_LOCAL_NAME} file`,
-  [ENV_DEFAULTS_NAME]: `the ${ENV_DEFAULTS_NAME} file`,
-};
-
-/** One environment variable name the ladder will look up, and why. */
-export interface LadderCandidate {
-  /** Which rung generated (or recorded) the name. */
-  rung: LadderRung;
-  /** The environment variable name. */
-  envName: string;
-}
-
-/** Where a resolved value came from. */
-export interface VariableSource extends LadderCandidate {
-  /** Which of the three layers held the value. */
-  file: EnvSourceFile;
-}
-
-/** A resolved answer: the value, and exactly where it came from. */
-export interface ResolvedVariable {
-  /** The value as stored, before validation or coercion. */
-  value: string;
-  /** Which name, on which rung, in which layer, supplied it. */
-  source: VariableSource;
-}
-
-/**
- * The three separately parsed environment layers plus the mapping records, all
- * the ladder needs to answer a lookup.
- */
-export interface LadderContext {
-  /** The real shell environment, captured before the env files were injected. */
-  shellEnv: Record<string, string>;
-  /** The parsed `.sous/.env.local` file. */
-  localEnv: Record<string, string>;
-  /** The parsed `.sous/.env` file. */
-  sharedEnv: Record<string, string>;
-  /** The merged `varMappings` block: environment variable name to target. */
-  mappings: Record<string, string>;
-}
-
-/** Drops undefined entries from a process environment, keeping the strings. */
-function sanitizeEnv(env: NodeJS.ProcessEnv): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const [key, value] of Object.entries(env)) {
-    if (typeof value === "string") out[key] = value;
-  }
-  return out;
-}
-
-/** What `loadLadderContext` needs in order to read the layers. */
-export interface LadderContextOptions {
-  /** The project's `.sous/` directory, which holds both env files. */
-  sousDir: string;
-  /** The merged config, read for its `varMappings` block. */
-  settings?: Settings;
-  /**
-   * The real shell environment. Commands pass the snapshot BaseCommand takes
-   * before it injects the env files; without it the file-supplied values would
-   * be reported as though the shell had set them.
-   */
-  shellEnv?: NodeJS.ProcessEnv;
-}
-
-/**
- * Reads the two env files and the mapping records into a ladder context.
- *
- * @param options - Where to read from; see LadderContextOptions.
- */
-export function loadLadderContext(options: LadderContextOptions): LadderContext {
-  const { sousDir, settings, shellEnv = process.env } = options;
-  return {
-    shellEnv: sanitizeEnv(shellEnv),
-    localEnv: readEnvFileMap(path.join(sousDir, ENV_LOCAL_NAME)),
-    sharedEnv: readEnvFileMap(path.join(sousDir, ENV_DEFAULTS_NAME)),
-    mappings: settings?.varMappings ?? {},
-  };
-}
-
-/**
- * Every environment variable name that could answer this variable, most
- * specific rung first. Duplicate names are dropped, keeping the most specific
- * occurrence, so a definition whose `env` field repeats a generated name is
- * reported once.
- *
- * @param defined - The definition and the recipe that published it.
- * @param context - The environment layers and mapping records.
- */
-export function variableCandidates(
-  defined: DefinedVariable,
-  context: LadderContext
-): LadderCandidate[] {
-  const { namespace, name: recipe } = defined.recipe;
-  const variable = defined.definition.name;
-
-  const ordered: LadderCandidate[] = [
-    ...mappedNamesFor(context.mappings, defined).map((envName) => ({
-      rung: "mapping" as const,
-      envName,
-    })),
-    { rung: "recipe", envName: recipeScopedName(namespace, recipe, variable) },
-    { rung: "namespace", envName: namespaceScopedName(namespace, variable) },
-    { rung: "shared", envName: sharedName(variable) },
-    { rung: "bare", envName: bareName(defined.definition) },
-  ];
-
-  const seen = new Set<string>();
-  return ordered.filter((candidate) => {
-    if (seen.has(candidate.envName)) return false;
-    seen.add(candidate.envName);
-    return true;
-  });
-}
-
-/**
- * Looks one environment variable name up across the three layers, in
- * precedence order.
- *
- * @param envName - The name to look up.
- * @param context - The environment layers.
- * @returns The value and the layer that held it, or undefined when nothing did.
- */
-export function lookupEnvName(
-  envName: string,
-  context: LadderContext
-): { value: string; file: EnvSourceFile } | undefined {
-  const shell = context.shellEnv[envName];
-  if (shell !== undefined) return { value: shell, file: "shell" };
-
-  const local = context.localEnv[envName];
-  if (local !== undefined) return { value: local, file: ENV_LOCAL_NAME };
-
-  const shared = context.sharedEnv[envName];
-  if (shared !== undefined) return { value: shared, file: ENV_DEFAULTS_NAME };
-
-  return undefined;
-}
-
-/**
- * Walks the ladder for one variable and returns the first answer it finds.
- *
- * @param defined - The definition and the recipe that published it.
- * @param context - The environment layers and mapping records.
- * @returns The value and its source, or undefined when no rung answered.
- */
-export function resolveVariable(
-  defined: DefinedVariable,
-  context: LadderContext
-): ResolvedVariable | undefined {
-  for (const candidate of variableCandidates(defined, context)) {
-    const hit = lookupEnvName(candidate.envName, context);
-    if (hit !== undefined) {
-      return {
-        value: hit.value,
-        source: { rung: candidate.rung, envName: candidate.envName, file: hit.file },
-      };
-    }
-  }
-  return undefined;
-}
-
-/** A resolution plus the full candidate list, for diagnostics and `sous vars`. */
-export interface VariableDiagnosis {
-  /** The winning answer, when a rung produced one. */
-  resolved?: ResolvedVariable;
-  /** Every name the ladder tried, most specific first. */
-  candidates: LadderCandidate[];
-}
-
-/**
- * Resolves a variable and reports every candidate name it considered, which is
- * what `sous vars <name>` prints and what a non-interactive failure message
- * lists.
- *
- * @param defined - The definition and the recipe that published it.
- * @param context - The environment layers and mapping records.
- */
-export function diagnoseVariable(
-  defined: DefinedVariable,
-  context: LadderContext
-): VariableDiagnosis {
-  const candidates = variableCandidates(defined, context);
-  for (const candidate of candidates) {
-    const hit = lookupEnvName(candidate.envName, context);
-    if (hit !== undefined) {
-      return {
-        resolved: {
-          value: hit.value,
-          source: { rung: candidate.rung, envName: candidate.envName, file: hit.file },
-        },
-        candidates,
-      };
-    }
-  }
-  return { candidates };
-}
-
-/**
- * Records a value in the context so later lookups in the same run see it, as
- * they would on the next run once the file is on disk.
- *
- * @param context - The context to update.
- * @param file - Which layer the value was written to.
- * @param envName - The environment variable name.
- * @param value - The value that was stored.
- */
-export function recordAnswerInContext(
-  context: LadderContext,
-  file: EnvSourceFile,
-  envName: string,
-  value: string
-): void {
-  if (file === "shell") context.shellEnv[envName] = value;
-  else if (file === ENV_LOCAL_NAME) context.localEnv[envName] = value;
-  else context.sharedEnv[envName] = value;
-}
-
-/**
- * A one-line, plain-language description of where a value came from, such as
- * "the shared scope name SOUS_VAR_API_URL, from the .env file".
- *
- * @param source - The resolved source.
- */
-export function describeSource(source: VariableSource): string {
-  const where = SOURCE_LABELS[source.file] ?? source.file;
-  return `the ${RUNG_LABELS[source.rung]} name ${source.envName}, from ${where}`;
-}

package/src/lib/vars/mappings.ts

@@ -1,260 +0,0 @@
-/**
- * Mapping records: the universal conflict resolver for variable answers.
- *
- * A mapping record binds one environment variable, of any name at all, to one
- * fully qualified variable:
- *
- *     SOME_VAR -> sous-recipes:misc/stuff/apiUrl
- *
- * It is the top rung of the resolution ladder, and it exists because generated
- * names can collide: two recipes may both declare `apiUrl`, or an author may
- * bind an existing name such as `GITHUB_TOKEN` that something else already
- * uses. Rather than inventing a name grammar that sous would have to parse back
- * into scopes, a record simply states the binding.
- *
- * Records live under the top-level `varMappings` config key. sous writes the
- * ones it creates into the machine-written `conf.d/520-var-mappings.jsonc`
- * layer; a user may also hand-write `varMappings` in the primary config, and
- * the layers merge like anything else.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { parse as parseJsonc, type ParseError } from "jsonc-parser";
-import { ConfigError } from "../errors.js";
-import {
-  managedLayerHeader,
-  updateManagedLayer,
-} from "../repos/managed-layer.js";
-import { VARIABLE_NAME_PATTERN } from "../repos/formats/patterns.js";
-import {
-  RefSource,
-  formatRef,
-  namespaceOf,
-  parseNamedRef,
-  repoOf,
-  type NamedRef,
-} from "../../services/ref-resolver/index.js";
-import type { DefinedVariable } from "./definition-source.js";
-
-/** File name of the machine-written mapping record layer. */
-export const VAR_MAPPINGS_LAYER_FILENAME = "520-var-mappings.jsonc";
-
-/** What the mapping record layer holds, written into its header comment. */
-export const VAR_MAPPINGS_DESCRIPTION = [
-  "Each entry under 'varMappings' binds an environment variable to one recipe",
-  "variable, so an answer can be stored under a name of your choosing when the",
-  "usual names are taken. The 'sous vars ask' command writes them; run",
-  "'sous vars' to see which name answered what.",
-];
-
-/** The header comment sous writes at the top of the mapping record layer. */
-export const VAR_MAPPINGS_COMMENT = managedLayerHeader(
-  VAR_MAPPINGS_LAYER_FILENAME,
-  VAR_MAPPINGS_DESCRIPTION
-);
-
-/** A mapping record's target: one variable, named in full. */
-export interface MappingTarget {
-  /** The repository's short name, when the record names one. */
-  repo?: string;
-  /** The recipe's namespace. */
-  namespace: string;
-  /** The recipe's name. */
-  recipe: string;
-  /** The variable's camelCase name. */
-  variable: string;
-}
-
-/** The one-line reminder appended to every mapping error. */
-const TARGET_HELP =
-  "A mapping target is written as 'namespace/recipe/variableName', optionally " +
-  "qualified with a repository as 'repo:namespace/recipe/variableName'.";
-
-/**
- * Parses a mapping target string into its parts, throwing a ConfigError that
- * quotes the input and shows the grammar when it does not fit.
- *
- * @param input - The target as written in the config.
- */
-export function parseMappingTarget(input: string): MappingTarget {
-  const fail = (problem: string): never => {
-    throw new ConfigError(
-      `Invalid variable mapping target '${input}': ${problem}\n  ${TARGET_HELP}`
-    );
-  };
-
-  const trimmed = typeof input === "string" ? input.trim() : "";
-  if (trimmed.length === 0) fail("a target must not be empty.");
-
-  // A target is a recipe ref with the variable after one more slash, so the
-  // ref part is read by the one ref parser and held to the stored form.
-  const slash = trimmed.lastIndexOf("/");
-  const variable = slash === -1 ? "" : trimmed.slice(slash + 1);
-  let ref: NamedRef | undefined;
-  try {
-    ref = parseNamedRef(trimmed.slice(0, Math.max(slash, 0)), RefSource.CommandLine);
-  } catch (error) {
-    fail((error as Error).message.split("\n")[0]!.replace(/^Invalid ref '[^']*': /, ""));
-  }
-  if (ref?.kind !== "recipe" || ref.range !== undefined) {
-    fail("a target names a namespace, a recipe and a variable, joined by slashes.");
-  }
-  const repo = repoOf(ref!)?.name;
-  const namespace = namespaceOf(ref!)!.name;
-  const recipe = ref!.kind === "recipe" ? ref!.name : "";
-  if (formatRef(ref!) !== formatRef(ref!).toLowerCase()) {
-    fail(`the repository, namespace and recipe in '${formatRef(ref!)}' must be lowercase.`);
-  }
-  if (!VARIABLE_NAME_PATTERN.test(variable)) {
-    fail(
-      `the variable name '${variable}' must be camelCase: a lowercase letter, then ` +
-        "letters or digits."
-    );
-  }
-
-  const parsed: MappingTarget = { namespace, recipe, variable };
-  if (repo !== undefined) parsed.repo = repo;
-  return parsed;
-}
-
-/**
- * Renders a mapping target back into its written form, which round-trips with
- * `parseMappingTarget`.
- *
- * @param target - The target parts.
- */
-export function formatMappingTarget(target: MappingTarget): string {
-  const qualifier = target.repo === undefined ? "" : `${target.repo}:`;
-  return `${qualifier}${target.namespace}/${target.recipe}/${target.variable}`;
-}
-
-/**
- * The fully qualified target for one defined variable, repository qualifier
- * included, which is what a new record is written with.
- *
- * @param defined - The definition and the recipe that published it.
- */
-export function mappingTargetFor(defined: DefinedVariable): MappingTarget {
-  return {
-    repo: defined.recipe.repo,
-    namespace: defined.recipe.namespace,
-    recipe: defined.recipe.name,
-    variable: defined.definition.name,
-  };
-}
-
-/**
- * True when a mapping record's target names this variable. A record without a
- * repository qualifier matches the variable in any repository; one with a
- * qualifier must name the same repository.
- *
- * @param target - The record's parsed target.
- * @param defined - The definition and the recipe that published it.
- */
-export function mappingMatches(target: MappingTarget, defined: DefinedVariable): boolean {
-  if (target.repo !== undefined && target.repo !== defined.recipe.repo) return false;
-  return (
-    target.namespace === defined.recipe.namespace &&
-    target.recipe === defined.recipe.name &&
-    target.variable === defined.definition.name
-  );
-}
-
-/**
- * Every environment variable name bound to this variable by a mapping record,
- * sorted so the order never depends on config layer order.
- *
- * @param mappings - The merged `varMappings` block.
- * @param defined - The definition and the recipe that published it.
- */
-export function mappedNamesFor(
-  mappings: Record<string, string>,
-  defined: DefinedVariable
-): string[] {
-  const names: string[] = [];
-  for (const [envName, rawTarget] of Object.entries(mappings)) {
-    if (mappingMatches(parseMappingTarget(rawTarget), defined)) names.push(envName);
-  }
-  return names.sort();
-}
-
-/**
- * Records a mapping in the machine-written `conf.d/520-var-mappings.jsonc`
- * layer, editing only that one entry's bytes so any comments, key order and
- * formatting already in the file survive.
- *
- * The edit stages to a temporary name and renames over the layer, like every
- * other file sous writes for a machine. A layer truncated by an interrupt would
- * fail to parse and break every later command until someone deleted it by hand;
- * a rename either happens or does not, so the previous layer survives.
- *
- * @param confDir - The project's `conf.d/` directory (`configContext.confDir`).
- * @param envName - The environment variable the answer is stored under.
- * @param target - The variable the name is bound to.
- * @returns The path of the layer file that was written.
- */
-export function writeMappingRecord(
-  confDir: string,
-  envName: string,
-  target: MappingTarget | string
-): string {
-  const rendered = typeof target === "string" ? target : formatMappingTarget(target);
-  // Parse before writing, so a bad target is refused rather than persisted.
-  parseMappingTarget(rendered);
-
-  return updateManagedLayer(
-    path.dirname(confDir),
-    VAR_MAPPINGS_LAYER_FILENAME,
-    [{ path: ["varMappings", envName], value: rendered }],
-    { confDir, header: VAR_MAPPINGS_COMMENT }
-  );
-}
-
-/**
- * Reads the records already in the mapping layer file, returning an empty
- * object when the file is missing. A layer still under the old
- * `520-var-mappings.json` name is read as a fallback; the next write migrates
- * it.
- *
- * @param filePath - Path to the mapping record layer file.
- */
-export function readMappingRecords(filePath: string): Record<string, string> {
-  let readPath = filePath;
-  if (!fs.existsSync(readPath)) {
-    const legacy = filePath.endsWith(".jsonc") ? filePath.slice(0, -1) : undefined;
-    if (legacy === undefined || !fs.existsSync(legacy)) return {};
-    readPath = legacy;
-  }
-
-  const errors: ParseError[] = [];
-  const parsed = parseJsonc(fs.readFileSync(readPath, "utf8"), errors, {
-    allowTrailingComma: true,
-    disallowComments: false,
-  });
-  if (errors.length > 0) {
-    throw new ConfigError(
-      `Could not read the variable mapping records at ${readPath}:\n` +
-        `  The file is not valid JSON with comments.\n` +
-        `  This file is written by sous; deleting it removes every mapping record.`
-    );
-  }
-
-  const block =
-    parsed !== null && typeof parsed === "object"
-      ? (parsed as { varMappings?: unknown }).varMappings
-      : undefined;
-  if (block === undefined) return {};
-  if (block === null || typeof block !== "object" || Array.isArray(block)) {
-    throw new ConfigError(
-      `The variable mapping records at ${readPath} are malformed: 'varMappings' must ` +
-        `be an object of environment variable names to targets.`
-    );
-  }
-
-  const records: Record<string, string> = {};
-  for (const [key, value] of Object.entries(block as Record<string, unknown>)) {
-    if (typeof value === "string") records[key] = value;
-  }
-  return records;
-}

package/src/lib/vars/names.ts

@@ -1,94 +0,0 @@
-/**
- * Environment variable names for recipe variable answers.
- *
- * Every name here is GENERATED and then LOOKED UP. Nothing in sous ever parses
- * a name back into the scope that produced it: `_` is both the delimiter and a
- * legal identifier character, so `SOUS_VAR_MISC_STUFF_API_URL` could be split
- * in several places and no parse would be trustworthy. When a generated name
- * collides with something else, a mapping record (see `mappings.ts`) binds an
- * arbitrary name to one fully qualified variable instead.
- */
-
-import type { VariableDefinition } from "../repos/formats/recipe-manifest.js";
-
-/** The prefix every generated answer name carries. */
-export const ENV_PREFIX = "SOUS_VAR_";
-
-/**
- * Converts a camelCase or kebab-case identifier to upper snake case.
- *
- * @param name - The identifier, such as `apiBaseUrl` or `task-files`.
- * @returns The upper snake case form, such as `API_BASE_URL` or `TASK_FILES`.
- */
-export function toUpperSnake(name: string): string {
-  return name
-    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
-    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
-    .replace(/[-\s.]+/g, "_")
-    .replace(/_+/g, "_")
-    .replace(/^_|_$/g, "")
-    .toUpperCase();
-}
-
-/**
- * The default environment variable name for a variable, derived from its
- * camelCase name: `apiUrl` becomes `SOUS_VAR_API_URL`. This is the same string
- * as the shared rung of the resolution ladder.
- *
- * @param variableName - The variable's camelCase name.
- */
-export function deriveEnvName(variableName: string): string {
-  return `${ENV_PREFIX}${toUpperSnake(variableName)}`;
-}
-
-/**
- * The recipe-scoped name: the most specific generated rung, naming both the
- * namespace and the recipe. `misc` plus `stuff` plus `apiUrl` becomes
- * `SOUS_VAR_MISC_STUFF_API_URL`.
- *
- * @param namespace - The recipe's namespace.
- * @param recipe - The recipe's name.
- * @param variableName - The variable's camelCase name.
- */
-export function recipeScopedName(
-  namespace: string,
-  recipe: string,
-  variableName: string
-): string {
-  return `${ENV_PREFIX}${toUpperSnake(namespace)}_${toUpperSnake(recipe)}_${toUpperSnake(
-    variableName
-  )}`;
-}
-
-/**
- * The namespace-scoped name, which answers the same variable for every recipe
- * in one namespace. `misc` plus `apiUrl` becomes `SOUS_VAR_MISC_API_URL`.
- *
- * @param namespace - The recipe's namespace.
- * @param variableName - The variable's camelCase name.
- */
-export function namespaceScopedName(namespace: string, variableName: string): string {
-  return `${ENV_PREFIX}${toUpperSnake(namespace)}_${toUpperSnake(variableName)}`;
-}
-
-/**
- * The shared name, which answers a variable of this name for every recipe that
- * declares one. `apiUrl` becomes `SOUS_VAR_API_URL`.
- *
- * @param variableName - The variable's camelCase name.
- */
-export function sharedName(variableName: string): string {
-  return deriveEnvName(variableName);
-}
-
-/**
- * The bare declared name: the definition's own `env` field when its author set
- * one (so a recipe can bind an existing variable such as `GITHUB_TOKEN`), and
- * the shared form otherwise. This is also the name a new answer is written
- * under.
- *
- * @param definition - The variable definition.
- */
-export function bareName(definition: VariableDefinition): string {
-  return definition.env ?? sharedName(definition.name);
-}