@sous-io/sous 0.2.37 → 1.0.2

package/src/lib/config-kernel.mjs

@@ -1,379 +0,0 @@
-/**
- * The sous "config kernel": a single loader subprocess that turns an ordered
- * list of config layer files into ONE merged, plain-JSON config.
- *
- * Spawned by loadSettings (src/lib/settings.ts). Plain JavaScript ESM, no
- * TypeScript syntax — it must run under bare Node AND under the tsx loader
- * (the tsx attempt exists so user configs may use TypeScript syntax). It ships
- * to npm via the package.json "files": "src" allowlist.
- *
- * Protocol
- * --------
- * stdin (one JSON document):
- *   {
- *     sources: (string | { path, config })[],  // ordered layers, primary first.
- *                                   // A string is an absolute layer path the
- *                                   // kernel reads itself. An object is a layer
- *                                   // the parent already read and filtered (a
- *                                   // subscribed recipe's config layer); the
- *                                   // kernel merges `config` as-is and never
- *                                   // opens `path`.
- *     context: { sousDir, confDir, sousRootPath, sousVersion, configPath },
- *     trace: boolean
- *   }
- *
- * stdout (one JSON document):
- *   { config, layers }
- *   `layers` is [] unless trace; when tracing it holds one { path, config }
- *   snapshot of the CUMULATIVE config after each top-level source. Builder
- *   sub-loads (loadConfig/loadConfigs) fold into the enclosing layer's snapshot.
- *
- * Any layer failure (parse error, import error, configure() throw, cycle,
- * old multi-project schema) writes a message NAMING THE LAYER FILE to stderr
- * and exits 1; the parent wraps stderr in a ConfigError.
- *
- * Layer contract
- * --------------
- * - .json  → JSON.parse of the file text.
- * - .jsonc → JSON with comments: line comments, block comments and trailing
- *            commas are allowed. The layers sous manages are written this way.
- * - .yaml  → parsed with the 'yaml' package.
- * - .js/.mjs → dynamic import. The module may export:
- *     * an object: `config`, else `default` when it is a non-function object;
- *     * a function: `configure`, else `default` when it is a function;
- *     * both: the object merges FIRST, then the function runs.
- *   The function is awaited: `await fn(currentConfig, builder)`. It may mutate
- *   `currentConfig` by reference freely; a returned object (if any) is merged
- *   after it resolves — UNLESS it is `currentConfig` itself (mutate-and-return
- *   for chaining), which is skipped so self-merge does not duplicate arrays.
- *
- * Every layer object is forced through a JSON round-trip BEFORE merging, so
- * functions, RegExp, Date and undefined values drop at the layer boundary.
- * The final cumulative config is JSON round-tripped again on the way out.
- *
- * Merge semantics (deepMerge): plain object + plain object → recurse;
- * array + array → concatenate (target then source); anything else → the
- * source value replaces. No dedupe.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { parse as parseYaml } from "yaml";
-import { globSync } from "glob";
-import { parse as parseJsonc, printParseErrorCode } from "jsonc-parser";
-
-// --- small utilities -----------------------------------------------------------------------------
-
-/** True for a plain object (not null, not an array). */
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-/**
- * Parses a `.jsonc` layer: JSON plus line comments, block comments and trailing
- * commas. The error names the layer file and the line the parser stopped on.
- */
-function parseJsoncLayer(text, filePath) {
-  const errors = [];
-  const value = parseJsonc(text, errors, { allowTrailingComma: true, disallowComments: false });
-
-  if (errors.length > 0) {
-    const first = errors[0];
-    const before = text.slice(0, first.offset);
-    const line = before.split("\n").length;
-    const column = first.offset - before.lastIndexOf("\n");
-    throw new Error(
-      `Config layer ${filePath} is not valid JSON with comments: ` +
-        `${printParseErrorCode(first.error)} at line ${line}, column ${column}.\n` +
-        `  Comments and trailing commas are allowed; anything else must be valid JSON.`
-    );
-  }
-
-  return value;
-}
-
-/** Forces a value through a JSON round-trip. */
-function jsonRoundTrip(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-
-/**
- * Bytewise string comparison (plain `<` on the string), locale-independent so
- * layer order is identical on every machine. NOT numeric: '10-' sorts before '2-'.
- */
-function bytewiseCompare(a, b) {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
-
-/**
- * Deep-merges `source` INTO `target` (the live cumulative config).
- * plain object + plain object → recurse; array + array → concatenate
- * (target then source, no dedupe); anything else → source replaces.
- */
-function deepMerge(target, source) {
-  for (const [key, sourceValue] of Object.entries(source)) {
-    // Guard against prototype pollution: a JSON layer can carry an OWN
-    // enumerable "__proto__" (or "constructor"/"prototype") key through the
-    // round-trip; merging it would mutate Object.prototype and corrupt every
-    // later object (including tripping the old-schema guard on innocent layers).
-    if (key === "__proto__" || key === "constructor" || key === "prototype") {
-      continue;
-    }
-    const targetValue = target[key];
-    if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
-      deepMerge(targetValue, sourceValue);
-    } else if (Array.isArray(targetValue) && Array.isArray(sourceValue)) {
-      target[key] = [...targetValue, ...sourceValue];
-    } else {
-      target[key] = sourceValue;
-    }
-  }
-  return target;
-}
-
-// --- kernel --------------------------------------------------------------------------------------
-
-async function readStdin() {
-  const chunks = [];
-  for await (const chunk of process.stdin) chunks.push(chunk);
-  return Buffer.concat(chunks).toString("utf8");
-}
-
-async function main() {
-  const { sources, context, trace } = JSON.parse(await readStdin());
-
-  /** The live cumulative config every layer merges into. */
-  const currentConfig = {};
-
-  /** Trace-mode snapshots: one per TOP-LEVEL source, taken after it finishes. */
-  const layers = [];
-
-  /** Absolute paths currently mid-load, for cycle detection. */
-  const loadingSet = new Set();
-
-  /** The layer file whose code is currently executing (for builder.currentFile). */
-  let currentFile = null;
-
-  /**
-   * The only variables usable in builder loadConfig/loadConfigs paths. Builder
-   * paths resolve BEFORE variable resolution, so user _vars do not exist yet.
-   */
-  const autoVars = {
-    sousDir: context.sousDir,
-    sousConfDir: context.confDir,
-    sousRootPath: context.sousRootPath,
-    sousVersion: context.sousVersion,
-  };
-
-  /** Substitutes ${autoVar} references in a builder path; any other var is fatal. */
-  function substituteAutoVars(rawPath, where) {
-    return rawPath.replace(/\$\{([^}]+)\}/g, (_match, name) => {
-      if (name in autoVars) return autoVars[name];
-      throw new Error(
-        `${where}: \${${name}} cannot be used in a builder path.\n` +
-          `  Builder paths (loadConfig/loadConfigs) resolve BEFORE variable resolution, so user\n` +
-          `  _vars are not available yet. Only these auto-vars are allowed:\n` +
-          `    ${Object.keys(autoVars)
-            .map((n) => "${" + n + "}")
-            .join(", ")}`
-      );
-    });
-  }
-
-  /** Resolves a builder path: auto-vars, then relative-to-the-current-layer-file. */
-  function resolveBuilderPath(rawPath, where) {
-    const substituted = substituteAutoVars(String(rawPath), where);
-    if (path.isAbsolute(substituted)) return path.normalize(substituted);
-    return path.resolve(path.dirname(currentFile), substituted);
-  }
-
-  /**
-   * Guards against the removed multi-project schema, per layer, so the error
-   * names the exact file that still uses it.
-   */
-  function assertNotOldSchema(layerObject, filePath) {
-    if (isPlainObject(layerObject) && ("projects" in layerObject || "defaultProject" in layerObject)) {
-      throw new Error(
-        `Config layer ${filePath} uses the removed multi-project schema ` +
-          `('projects' / 'defaultProject').\n` +
-          `  A sous config now describes exactly one project. To migrate:\n` +
-          `    1. Move your single project's fields (name, _vars, _aliases, compilation,\n` +
-          `       runtimeContext, tools) to the top level of the config.\n` +
-          `    2. Delete the 'projects' and 'defaultProject' keys.\n` +
-          `  A config with several projects must be split into one config per project.`
-      );
-    }
-  }
-
-  /**
-   * JSON-forces a layer's object and deep-merges it into the live config.
-   * Runs the old-schema guard on the layer's OWN object, pre-merge.
-   */
-  function mergeLayerObject(layerObject, filePath) {
-    if (!isPlainObject(layerObject)) {
-      throw new Error(
-        `Config layer ${filePath} did not produce a plain object (got ${
-          Array.isArray(layerObject) ? "an array" : typeof layerObject
-        }).`
-      );
-    }
-    assertNotOldSchema(layerObject, filePath);
-    deepMerge(currentConfig, jsonRoundTrip(layerObject));
-  }
-
-  /**
-   * The builder singleton passed to every configure(currentConfig, builder).
-   * One instance per kernel run; `currentFile` tracks whichever layer is executing.
-   */
-  const builder = {
-    get config() {
-      return currentConfig;
-    },
-    sousDir: context.sousDir,
-    confDir: context.confDir,
-    get currentFile() {
-      return currentFile;
-    },
-    env(name, fallback) {
-      return process.env[name] ?? fallback;
-    },
-    merge(obj) {
-      mergeLayerObject(obj, currentFile ?? "<builder.merge>");
-    },
-    async loadConfig(p) {
-      await loadLayer(resolveBuilderPath(p, `loadConfig(${JSON.stringify(p)}) in ${currentFile}`));
-    },
-    async loadConfigs(globPattern) {
-      const where = `loadConfigs(${JSON.stringify(globPattern)}) in ${currentFile}`;
-      const pattern = resolveBuilderPath(globPattern, where);
-      // glob reads `\` as an escape, so a Windows path is handed over with `/`
-      // separators (see src/lib/glob-pattern.ts; this file stays plain JS).
-      const matches = globSync(pattern.split(path.sep).join("/"), { absolute: true })
-        .filter((p) => fs.statSync(p).isFile())
-        .sort(bytewiseCompare);
-      for (const match of matches) {
-        await loadLayer(match);
-      }
-    },
-  };
-
-  /**
-   * Loads ONE layer file (any extension) and merges it into the cumulative
-   * config. Builder sub-loads recurse here too, under the full layer contract
-   * (including nested configure), guarded by the loading-set cycle check.
-   */
-  async function loadLayer(filePath) {
-    const resolved = path.resolve(filePath);
-
-    if (loadingSet.has(resolved)) {
-      throw new Error(
-        `Config layer cycle detected: ${resolved} is already being loaded.\n` +
-          `  Load chain: ${[...loadingSet].join(" -> ")} -> ${resolved}`
-      );
-    }
-    if (!fs.existsSync(resolved)) {
-      throw new Error(`Config layer not found: ${resolved}`);
-    }
-
-    loadingSet.add(resolved);
-    const previousFile = currentFile;
-    currentFile = resolved;
-
-    try {
-      const ext = path.extname(resolved).toLowerCase();
-
-      if (ext === ".json") {
-        mergeLayerObject(JSON.parse(fs.readFileSync(resolved, "utf8")), resolved);
-      } else if (ext === ".jsonc") {
-        mergeLayerObject(parseJsoncLayer(fs.readFileSync(resolved, "utf8"), resolved), resolved);
-      } else if (ext === ".yaml") {
-        mergeLayerObject(parseYaml(fs.readFileSync(resolved, "utf8")), resolved);
-      } else if (ext === ".js" || ext === ".mjs") {
-        const mod = await import(pathToFileURL(resolved).href);
-
-        let configObject;
-        if (mod.config !== undefined) {
-          configObject = mod.config;
-        } else if (mod.default !== undefined && typeof mod.default !== "function") {
-          configObject = mod.default;
-        }
-
-        let configureFn;
-        if (typeof mod.configure === "function") {
-          configureFn = mod.configure;
-        } else if (typeof mod.default === "function") {
-          configureFn = mod.default;
-        }
-
-        if (configObject === undefined && configureFn === undefined) {
-          throw new Error(
-            `Config layer ${resolved} exports neither a config object ` +
-              `(\`config\` or a default object) nor a configure function ` +
-              `(\`configure\` or a default function).`
-          );
-        }
-
-        // When both exist, the object merges FIRST, then the function runs.
-        if (configObject !== undefined) {
-          mergeLayerObject(configObject, resolved);
-        }
-        if (configureFn !== undefined) {
-          const returned = await configureFn(currentConfig, builder);
-          // A configure() may mutate currentConfig by reference AND return it for
-          // chaining (`cfg.x = ...; return cfg;`, or `return builder.config`).
-          // Merging currentConfig back onto itself would deepMerge it with itself,
-          // concatenating (and so duplicating) every array. Only merge a returned
-          // value when it is a DISTINCT object.
-          if (returned !== undefined && returned !== null && returned !== currentConfig) {
-            mergeLayerObject(returned, resolved);
-          }
-        }
-      } else {
-        throw new Error(
-          `Config layer ${resolved} has an unsupported extension '${ext}'. ` +
-            `Supported: .js, .mjs, .json, .jsonc, .yaml`
-        );
-      }
-    } catch (error) {
-      // Make sure every failure names a layer file.
-      const message = error instanceof Error ? error.message : String(error);
-      if (message.includes(resolved)) throw error;
-      throw new Error(`Config layer ${resolved} failed to load: ${message}`);
-    } finally {
-      loadingSet.delete(resolved);
-      currentFile = previousFile;
-    }
-  }
-
-  for (const source of sources) {
-    // An inline source is a layer the PARENT already read and already filtered
-    // (a subscribed recipe's config layer; see repos/recipe-config-layers.ts).
-    // The kernel merges the content it was handed and never opens the file, so
-    // the filtering cannot be sidestepped by re-reading it here.
-    if (isPlainObject(source)) {
-      const previousFile = currentFile;
-      currentFile = source.path;
-      try {
-        mergeLayerObject(source.config, source.path);
-      } finally {
-        currentFile = previousFile;
-      }
-    } else {
-      await loadLayer(source);
-    }
-    if (trace) {
-      layers.push({
-        path: isPlainObject(source) ? source.path : source,
-        config: jsonRoundTrip(currentConfig),
-      });
-    }
-  }
-
-  process.stdout.write(JSON.stringify({ config: jsonRoundTrip(currentConfig), layers }));
-}
-
-main().catch((error) => {
-  process.stderr.write(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-});