@sous-io/sous 0.2.37 → 1.0.1

package/src/lib/config-discovery.ts

@@ -1,378 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { ConfigError } from "./errors.js";
-import {
-  listRecipeConfigLayers,
-  type RecipeConfigLayer,
-} from "./repos/recipe-config-layers.js";
-
-/**
- * The directory name sous looks for when walking up from the working directory.
- */
-export const SOUS_DIR_NAME = ".sous";
-
-/**
- * Primary config file names searched inside a `.sous/` directory. Exactly ONE of
- * these may exist per `.sous/`; more than one is a hard error (no silent
- * first-match-wins).
- */
-export const CONFIG_FILE_NAMES = [
-  "sous.config.js",
-  "sous.config.mjs",
-  "sous.config.json",
-  "sous.config.jsonc",
-  "sous.config.yaml",
-] as const;
-
-/**
- * The drop-in config layer directory inside `.sous/`. Every
- * `conf.d/*.{js,mjs,json,jsonc,yaml}` file (non-recursive) is loaded after the
- * primary config and deep-merged in bytewise filename order.
- */
-export const CONFD_DIR_NAME = "conf.d";
-
-/**
- * File extensions recognised as config layers inside `conf.d/`. A `.jsonc`
- * layer is JSON with comments: line comments, block comments and trailing
- * commas are all allowed in it, which is why the layers sous manages for a
- * project are written that way.
- */
-export const LAYER_EXTENSIONS = [".js", ".mjs", ".json", ".jsonc", ".yaml"] as const;
-
-/**
- * The name of the optional shared-defaults env file inside `.sous/`. This file
- * is meant to be committed: it holds values a whole team shares, never secrets.
- */
-export const ENV_DEFAULTS_NAME = ".env";
-
-/** The name of the optional machine-specific env file inside `.sous/`. */
-export const ENV_LOCAL_NAME = ".env.local";
-
-/** A located sous configuration. */
-export type DiscoveredConfig = {
-  /** Absolute path to the primary config file itself. */
-  configPath: string;
-  /**
-   * Absolute path to the `.sous/` directory holding the config, when the config
-   * was found by walking up. For an explicit `--config` path this is the config
-   * file's parent directory, whatever it is called.
-   */
-  sousDir: string;
-  /** Absolute path to the `conf.d/` drop-in directory (may not exist). */
-  confDir: string;
-  /**
-   * Ordered absolute paths of every config layer: the primary config first,
-   * then any config layers subscribed recipes contribute, then the `conf.d/`
-   * layers in bytewise filename order. Recipes sit in the middle so a recipe can
-   * supply defaults and the project always wins over them.
-   */
-  layerPaths: string[];
-  /** The subset of `layerPaths` that came from subscribed recipes. */
-  recipeLayerPaths: string[];
-  /**
-   * The recipe layers themselves, already read and already filtered down to the
-   * keys a recipe is allowed to set. Sous reads these instead of handing their
-   * paths to the config kernel, so a recipe cannot set a key that would change
-   * what sous trusts or what sous runs. See `repos/recipe-config-layers.ts`.
-   */
-  recipeLayers: RecipeConfigLayer[];
-  /**
-   * Complete, plain-language sentences about anything a recipe contributed that
-   * sous declined to load. Printed by the command, since discovery runs before
-   * there is anywhere good to print.
-   */
-  recipeLayerWarnings: string[];
-  /** How the config was located. */
-  source: "flag" | "walk-up";
-};
-
-/**
- * Returns the list of directories to check, starting at `startDir` and walking
- * up to the filesystem root. Used by discovery and by the not-found error message.
- */
-export function candidateDirs(startDir: string): string[] {
-  const dirs: string[] = [];
-  let current = path.resolve(startDir);
-
-  for (;;) {
-    dirs.push(current);
-    const parent = path.dirname(current);
-    if (parent === current) break;
-    current = parent;
-  }
-
-  return dirs;
-}
-
-/**
- * Returns the primary config file inside `sousDir`, or null when none exists.
- *
- * @throws ConfigError when MORE THAN ONE primary candidate exists — sous never
- *   silently picks one of several `sous.config.*` files.
- */
-export function findConfigInSousDir(sousDir: string): string | null {
-  const found: string[] = [];
-  for (const name of CONFIG_FILE_NAMES) {
-    const candidate = path.join(sousDir, name);
-    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
-      found.push(candidate);
-    }
-  }
-
-  if (found.length > 1) {
-    throw new ConfigError(
-      `Multiple primary sous config files found in ${sousDir}:\n` +
-        found.map((f) => `    ${f}`).join("\n") +
-        `\n  A .sous/ directory may hold exactly one of: ${CONFIG_FILE_NAMES.join(", ")}.\n` +
-        `  Keep one primary config and move the rest into ${CONFD_DIR_NAME}/ (with unique names) or delete them.`
-    );
-  }
-
-  return found[0] ?? null;
-}
-
-/**
- * Compares two strings bytewise (plain `<` on the string), locale-independent
- * so layer order is identical on every machine. Note this is NOT numeric:
- * `10-` sorts before `2-` (zero-pad layer prefixes if that matters).
- */
-function bytewiseCompare(a: string, b: string): number {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
-
-/**
- * Lists the config layer files inside a `conf.d/` directory: every
- * `*.{js,mjs,json,jsonc,yaml}` file directly inside it (non-recursive), sorted
- * bytewise by filename. A missing directory yields an empty list.
- */
-export function listConfDirLayers(confDir: string): string[] {
-  if (!fs.existsSync(confDir) || !fs.statSync(confDir).isDirectory()) return [];
-
-  return fs
-    .readdirSync(confDir)
-    .filter((name) => {
-      const ext = path.extname(name).toLowerCase();
-      if (!(LAYER_EXTENSIONS as readonly string[]).includes(ext)) return false;
-      const full = path.join(confDir, name);
-      return fs.statSync(full).isFile();
-    })
-    .sort(bytewiseCompare)
-    .map((name) => path.join(confDir, name));
-}
-
-/**
- * Asserts that every loaded config file (primary + conf.d layers) has a unique
- * baseName; the filename minus its FINAL extension. Two layers named
- * `500-repos.json` and `500-repos.jsonc` would otherwise merge in an order that
- * depends on their extensions, which is never what the author meant. It is also
- * what stops a managed layer from existing under both its old `.json` name and
- * its `.jsonc` one.
- *
- * @throws ConfigError naming both conflicting files.
- */
-export function assertUniqueLayerBaseNames(layerPaths: string[]): void {
-  const seen = new Map<string, string>();
-  for (const layerPath of layerPaths) {
-    const base = path.basename(layerPath, path.extname(layerPath));
-    const existing = seen.get(base);
-    if (existing !== undefined) {
-      throw new ConfigError(
-        `Duplicate config layer baseName '${base}':\n` +
-          `    ${existing}\n` +
-          `    ${layerPath}\n` +
-          `  Every loaded config file (the primary config and all ${CONFD_DIR_NAME}/ layers) must have a\n` +
-          `  unique filename once its final extension is removed. Rename one of them.`
-      );
-    }
-    seen.set(base, layerPath);
-  }
-}
-
-/**
- * Builds a full DiscoveredConfig from a located primary config: computes the
- * conf.d directory, enumerates its layers and the layers subscribed recipes
- * contribute, and runs the duplicate-baseName check.
- *
- * Recipe layers load after the primary config and before the `conf.d/` layers,
- * so a recipe supplies defaults and the project always wins over them. They are
- * left out of the duplicate-baseName check deliberately: that check exists so a
- * person never has to guess which of two files they wrote merges last, and a
- * recipe's file names are not theirs to rename.
- *
- * @param confDirOverride - Absolute path to use as the conf.d directory instead
- *   of `<sousDir>/conf.d`. Set from the `--sous-confd` flag or `SOUS_CONFD` env
- *   var; discovery then builds its layers from the overridden directory.
- */
-function buildDiscoveredConfig(
-  configPath: string,
-  sousDir: string,
-  source: DiscoveredConfig["source"],
-  confDirOverride?: string
-): DiscoveredConfig {
-  const confDir = confDirOverride ?? path.join(sousDir, CONFD_DIR_NAME);
-  const projectLayers = [configPath, ...listConfDirLayers(confDir)];
-  assertUniqueLayerBaseNames(projectLayers);
-
-  const recipes = listRecipeConfigLayers(sousDir);
-  const layerPaths = [
-    configPath,
-    ...recipes.paths,
-    ...projectLayers.slice(1),
-  ];
-
-  return {
-    configPath,
-    sousDir,
-    confDir,
-    layerPaths,
-    recipeLayerPaths: recipes.paths,
-    recipeLayers: recipes.layers,
-    recipeLayerWarnings: recipes.warnings,
-    source,
-  };
-}
-
-/**
- * Re-runs the conf.d enumeration, the recipe layer enumeration and the
- * duplicate-baseName check for an existing discovery.
- *
- * Two callers need it. Watch mode calls it because layer files can appear or
- * disappear while watching. `BaseCommand.init()` calls it once after the
- * `.sous/` env files are loaded, because `SOUS_HOME` is file-settable and it
- * decides where the store holding the recipe layers is.
- *
- * The existing `confDir` is preserved (not recomputed from `sousDir`), so a
- * `SOUS_CONFD` / `--sous-confd` override survives across watch reloads.
- */
-export function refreshDiscoveredConfig(discovered: DiscoveredConfig): DiscoveredConfig {
-  return buildDiscoveredConfig(
-    discovered.configPath,
-    discovered.sousDir,
-    discovered.source,
-    discovered.confDir
-  );
-}
-
-/**
- * Walks up from `startDir` looking for a `.sous/` directory that contains one of
- * CONFIG_FILE_NAMES. The first directory with a match wins; a `.sous/` directory
- * without a config file does not stop the walk.
- *
- * @param startDir - Directory to start from (normally `process.cwd()`).
- * @param confDirOverride - Absolute conf.d directory to use instead of
- *   `<sousDir>/conf.d` (from `--sous-confd` / `SOUS_CONFD`).
- * @returns The discovered config, or null when nothing was found.
- * @throws ConfigError when a `.sous/` holds several primary configs, or when
- *   loaded layer baseNames collide.
- */
-export function discoverConfig(
-  startDir: string = process.cwd(),
-  confDirOverride?: string
-): DiscoveredConfig | null {
-  for (const dir of candidateDirs(startDir)) {
-    const sousDir = path.join(dir, SOUS_DIR_NAME);
-    if (!fs.existsSync(sousDir) || !fs.statSync(sousDir).isDirectory()) continue;
-
-    const configPath = findConfigInSousDir(sousDir);
-    if (configPath) return buildDiscoveredConfig(configPath, sousDir, "walk-up", confDirOverride);
-  }
-
-  return null;
-}
-
-/**
- * Resolves an explicit `--config` value into a DiscoveredConfig.
- *
- * The value may point at a config file or at a directory. A directory is searched
- * for CONFIG_FILE_NAMES, and if the directory itself is not named `.sous`, its
- * `.sous/` child is searched too — so `--config .` works inside a project root.
- *
- * @param configFlag - The raw `--config` value (relative paths resolve against cwd).
- * @param cwd - Base directory for relative paths.
- * @param confDirOverride - Absolute conf.d directory to use instead of
- *   `<sousDir>/conf.d` (from `--sous-confd` / `SOUS_CONFD`).
- * @param sourceLabel - How the caller supplied the value (`--config`,
- *   `--sous-config`, `SOUS_CONFIG`, `--sous-dir`, `SOUS_DIR`). Used only in error
- *   messages so a user who set `SOUS_DIR` is not told to fix `--config`.
- * @returns The resolved config.
- * @throws When the path does not exist or holds no recognised config file.
- */
-export function resolveConfigFlag(
-  configFlag: string,
-  cwd: string = process.cwd(),
-  confDirOverride?: string,
-  sourceLabel = "--config"
-): DiscoveredConfig {
-  const resolved = path.resolve(cwd, expandHome(configFlag));
-
-  if (!fs.existsSync(resolved)) {
-    throw new Error(`${sourceLabel} path not found: ${resolved}`);
-  }
-
-  if (fs.statSync(resolved).isDirectory()) {
-    const direct = findConfigInSousDir(resolved);
-    if (direct) {
-      return buildDiscoveredConfig(direct, resolved, "flag", confDirOverride);
-    }
-
-    const nested = path.join(resolved, SOUS_DIR_NAME);
-    if (fs.existsSync(nested) && fs.statSync(nested).isDirectory()) {
-      const nestedConfig = findConfigInSousDir(nested);
-      if (nestedConfig) {
-        return buildDiscoveredConfig(nestedConfig, nested, "flag", confDirOverride);
-      }
-    }
-
-    throw new Error(
-      `${sourceLabel} points at a directory with no sous config file: ${resolved}\n` +
-        `Looked for: ${CONFIG_FILE_NAMES.join(", ")}`
-    );
-  }
-
-  return buildDiscoveredConfig(resolved, path.dirname(resolved), "flag", confDirOverride);
-}
-
-/**
- * Expands a leading `~` to the user's home directory. Leaves other paths alone.
- */
-export function expandHome(inputPath: string): string {
-  if (inputPath === "~") return process.env.HOME ?? inputPath;
-  if (inputPath.startsWith("~/")) {
-    const home = process.env.HOME;
-    if (home) return path.join(home, inputPath.slice(2));
-  }
-  return inputPath;
-}
-
-/**
- * Builds the message shown when no config could be found. Names every directory
- * that was checked and shows how to fix it.
- *
- * @param startDir - The directory discovery started from.
- */
-export function formatNotFoundMessage(startDir: string = process.cwd()): string {
-  const dirs = candidateDirs(startDir);
-  const shown = dirs.slice(0, 8);
-  const omitted = dirs.length - shown.length;
-
-  const checked = shown
-    .map((dir) => `    ${path.join(dir, SOUS_DIR_NAME)}/`)
-    .join("\n");
-
-  const more = omitted > 0 ? `\n    ... and ${omitted} more parent director${omitted === 1 ? "y" : "ies"}` : "";
-
-  return [
-    "No sous config found.",
-    "",
-    `Starting at ${startDir}, sous walked up looking for a ${SOUS_DIR_NAME}/ directory`,
-    `containing one of: ${CONFIG_FILE_NAMES.join(", ")}`,
-    "",
-    "  Checked:",
-    checked + more,
-    "",
-    "  To fix this, either:",
-    `    1. Set the project up: run 'sous init' in its root directory, which writes`,
-    `       ${SOUS_DIR_NAME}/${CONFIG_FILE_NAMES[0]} and everything else a first build needs, or`,
-    "    2. Pass the config explicitly: sous <command> --config <path>",
-  ].join("\n");
-}

package/src/lib/config-inspect.ts

@@ -1,145 +0,0 @@
-import { styleText } from "node:util";
-import { ConfigError } from "./errors.js";
-
-/**
- * Shared helpers for the `sous config *` inspection commands: dot-path lookup
- * with `[n]` array indexing, colorized pretty-JSON rendering, and value
- * truncation for the `--layers` provenance view.
- */
-
-/** Sentinel returned by lookupPath when a path segment does not exist. */
-export const NOT_FOUND = Symbol("sous.config.path.not-found");
-
-/**
- * Splits a dot-path with optional `[n]` array indices into ordered segments.
- * `compilation.targets[0].entryPoint` → `["compilation", "targets", 0, "entryPoint"]`.
- * Numeric-looking bracket segments become numbers; everything else is a string key.
- *
- * @throws ConfigError on a malformed path (empty, unbalanced brackets, etc.).
- */
-export function parsePath(path: string): (string | number)[] {
-  const trimmed = path.trim();
-  if (trimmed === "") {
-    throw new ConfigError("Empty config path. Provide a dot-path like 'compilation.targets[0].entryPoint'.");
-  }
-
-  const segments: (string | number)[] = [];
-  // Consume, in order: bare keys, `[n]` array indices, and `.` separators
-  // between them. Any character that fits none of these (e.g. `a..b`, `a[]`,
-  // `a[x]`) leaves a gap the scanner reports as malformed.
-  const tokenRe = /([^.[\]]+)|\[(\d+)\]|(\.)/g;
-  let lastIndex = 0;
-  let expectKey = false; // a `.` was just consumed, so a key must follow
-  let match: RegExpExecArray | null;
-
-  while ((match = tokenRe.exec(trimmed)) !== null) {
-    if (match.index !== lastIndex) {
-      throw new ConfigError(`Malformed config path near '${trimmed.slice(lastIndex)}' in '${path}'.`);
-    }
-    if (match[1] !== undefined) {
-      segments.push(match[1]);
-      expectKey = false;
-    } else if (match[2] !== undefined) {
-      if (expectKey) {
-        throw new ConfigError(`Malformed config path near '${trimmed.slice(match.index)}' in '${path}'.`);
-      }
-      segments.push(Number(match[2]));
-    } else {
-      // A `.` separator: a key must follow it, and one may not lead the path or
-      // directly follow another `.` (i.e. `.a`, `a..b` are malformed).
-      if (expectKey || segments.length === 0) {
-        throw new ConfigError(`Malformed config path near '${trimmed.slice(match.index)}' in '${path}'.`);
-      }
-      expectKey = true;
-    }
-    lastIndex = tokenRe.lastIndex;
-  }
-
-  if (lastIndex !== trimmed.length || expectKey) {
-    throw new ConfigError(`Malformed config path near '${trimmed.slice(lastIndex) || "end of path"}' in '${path}'.`);
-  }
-
-  return segments;
-}
-
-/**
- * Walks `root` following `segments`, returning the value found or NOT_FOUND when
- * any segment is missing (or the path descends into a non-indexable value).
- */
-export function lookupPath(root: unknown, segments: (string | number)[]): unknown {
-  let current: unknown = root;
-  for (const segment of segments) {
-    if (current === null || current === undefined || typeof current !== "object") {
-      return NOT_FOUND;
-    }
-    if (typeof segment === "number") {
-      if (!Array.isArray(current) || segment < 0 || segment >= current.length) {
-        return NOT_FOUND;
-      }
-      current = current[segment];
-    } else {
-      // Use hasOwnProperty, NOT the `in` operator: `in` walks the prototype
-      // chain, so inherited Object.prototype members (`constructor`, `toString`,
-      // `hasOwnProperty`, `__proto__`, …) would falsely "resolve" and print
-      // garbage instead of NOT_FOUND.
-      if (!Object.prototype.hasOwnProperty.call(current, segment)) {
-        return NOT_FOUND;
-      }
-      current = (current as Record<string, unknown>)[segment];
-    }
-  }
-  return current;
-}
-
-/** True for JSON scalar values (string, finite/any number, boolean, null). */
-export function isScalar(value: unknown): value is string | number | boolean | null {
-  return (
-    value === null ||
-    typeof value === "string" ||
-    typeof value === "number" ||
-    typeof value === "boolean"
-  );
-}
-
-/**
- * Colorizes an already-serialized pretty-JSON string using node:util styleText:
- * object keys cyan, string values green, numbers yellow, booleans/null magenta.
- * Operates purely on JSON token syntax, so it never mangles structure.
- *
- * Callers should only invoke this when writing to a TTY; piped output must stay
- * plain so it parses as JSON.
- */
-export function colorizeJson(json: string): string {
-  const tokenRe = /"(?:\\.|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|\b(?:true|false|null)\b/g;
-  return json.replace(tokenRe, (match, offset: number, whole: string) => {
-    if (match[0] === '"') {
-      const rest = whole.slice(offset + match.length);
-      // A string immediately followed by a colon is an object key.
-      return /^\s*:/.test(rest)
-        ? styleText("cyan", match)
-        : styleText("green", match);
-    }
-    if (match === "true" || match === "false" || match === "null") {
-      return styleText("magenta", match);
-    }
-    return styleText("yellow", match);
-  });
-}
-
-/**
- * Renders a value as pretty JSON (2-space), colorized when `useColor` is true.
- */
-export function renderJson(value: unknown, useColor: boolean): string {
-  const json = JSON.stringify(value, null, 2);
-  return useColor ? colorizeJson(json) : json;
-}
-
-/**
- * JSON-encodes a value on a single line and truncates it to `max` characters
- * (with an ellipsis) for the compact `--layers` provenance lines.
- */
-export function truncateJson(value: unknown, max = 80): string {
-  const encoded = JSON.stringify(value);
-  if (encoded === undefined) return "undefined";
-  return encoded.length > max ? `${encoded.slice(0, max - 1)}…` : encoded;
-}