@sous-io/sous 0.1.1 → 0.2.0

package/src/lib/vars/ladder.ts

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

@@ -0,0 +1,265 @@
+/**
+ * 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 {
+  NAMESPACE_NAME_PATTERN,
+  RECIPE_NAME_PATTERN,
+  REPO_NAME_PATTERN,
+  VARIABLE_NAME_PATTERN,
+} from "../repos/formats/patterns.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.");
+
+  let body = trimmed;
+  let repo: string | undefined;
+
+  const colon = body.indexOf(":");
+  if (colon !== -1) {
+    repo = body.slice(0, colon);
+    body = body.slice(colon + 1);
+    if (!REPO_NAME_PATTERN.test(repo)) {
+      fail(
+        `the repository qualifier '${repo}' must be lowercase kebab-case: a letter, ` +
+          "then letters, digits or hyphens."
+      );
+    }
+  }
+
+  const segments = body.split("/");
+  if (segments.length !== 3) {
+    fail("a target names a namespace, a recipe and a variable, joined by slashes.");
+  }
+
+  const [namespace, recipe, variable] = segments as [string, string, string];
+  if (!NAMESPACE_NAME_PATTERN.test(namespace)) {
+    fail(`the namespace '${namespace}' must be lowercase kebab-case.`);
+  }
+  if (!RECIPE_NAME_PATTERN.test(recipe)) {
+    fail(`the recipe name '${recipe}' must be lowercase kebab-case.`);
+  }
+  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

@@ -0,0 +1,94 @@
+/**
+ * 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);
+}