wyvrnpm 2.3.2 → 2.8.1

package/src/conf/index.js

@@ -0,0 +1,391 @@
+'use strict';
+
+// Non-ABI build-time configuration — the `conf` system (PLAN-CONF.md).
+//
+// `conf` is the sibling of `options` with the opposite hashing
+// property: options fold into `profileHash` (ABI-affecting), conf
+// never does (build-time knobs). See plan §2 for the rationale.
+//
+// This module is the pure core. It parses the four layers
+// (CLI, `wyvrn.local.json`, named profile `[conf]`, recipe
+// `wyvrn.json`), merges them with per-leaf precedence, and produces
+// a flat `{ "namespace.leaf": value }` map ready for each sink to
+// consume. It does NOT know about CMake, filesystems beyond reading
+// a given JSON file, or any command — those live one level up in
+// src/commands/* and src/toolchain/*.
+
+const fs   = require('fs');
+const path = require('path');
+
+const { validateFlatConfKeys } = require('./namespaces');
+
+const LOCAL_OVERLAY_FILENAME = 'wyvrn.local.json';
+
+// Per plan §4.5 "Strict top-level allow-list". Phase-1 accepts only
+// `{ conf }` at the top level of wyvrn.local.json. Adding
+// dependencies/options/etc. to this set is deliberate and plan-2
+// territory.
+const LOCAL_OVERLAY_ALLOWED_TOP_KEYS = new Set(['conf']);
+
+// ---------------------------------------------------------------------------
+// Value normalisation
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalise a single leaf VALUE into the string CMake (or whichever
+ * sink consumes it) expects. JSON `true`/`false` become `"ON"`/`"OFF"`;
+ * numbers are stringified; strings pass through. Arrays / objects /
+ * null at a leaf position are a hard error — those live at branch
+ * positions, not leaves.
+ *
+ * CLI values arrive as strings and are passed through verbatim.
+ *
+ * @param {unknown} value
+ * @param {string}  keyForError
+ * @returns {string}
+ */
+function normalizeLeafValue(value, keyForError) {
+  if (value === true)  return 'ON';
+  if (value === false) return 'OFF';
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  if (typeof value === 'string') return value;
+  throw new Error(
+    `conf value for ${JSON.stringify(keyForError)} must be a string, ` +
+    `number, or boolean — got ${JSON.stringify(value)}`,
+  );
+}
+
+/**
+ * Flatten a nested conf object (recipe/local form) into a flat
+ * `{ "ns.leaf": stringValue }` map. Keys are joined with `.`. The
+ * recursion stops at any non-object (strings, numbers, booleans) —
+ * those are leaves.
+ *
+ * Throws on:
+ *   - null at a leaf position
+ *   - arrays anywhere (arrays are not meaningful for cmake cache vars
+ *     and leaving them as "maybe later" invites footguns)
+ *   - objects whose keys contain `.` (would clash with our separator)
+ *
+ * @param {object} nested
+ * @param {string} [prefix]
+ * @param {Record<string, string>} [out]
+ * @returns {Record<string, string>}
+ */
+function flattenConf(nested, prefix = '', out = {}) {
+  if (nested === null || typeof nested !== 'object') {
+    throw new Error(
+      `conf block must be an object — got ${JSON.stringify(nested)} at ` +
+      `${prefix || '<root>'}`,
+    );
+  }
+  if (Array.isArray(nested)) {
+    throw new Error(`conf block must be an object, not an array — at ${prefix || '<root>'}`);
+  }
+
+  for (const [rawKey, value] of Object.entries(nested)) {
+    if (rawKey.includes('.')) {
+      throw new Error(
+        `conf key segment ${JSON.stringify(rawKey)} must not contain a period — ` +
+        `use nested objects or the flat "namespace.leaf" form, not both`,
+      );
+    }
+    const fullKey = prefix ? `${prefix}.${rawKey}` : rawKey;
+
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      flattenConf(value, fullKey, out);
+    } else {
+      out[fullKey] = normalizeLeafValue(value, fullKey);
+    }
+  }
+  return out;
+}
+
+/**
+ * Re-expand a flat `{ "ns.leaf": value }` map back into nested form,
+ * for emitting into JSON manifests / lockfiles / payloads in the same
+ * shape authors author with. Values round-trip as strings (conf
+ * values are always strings post-normalisation).
+ *
+ * @param {Record<string, string>} flat
+ * @returns {object}
+ */
+function unflattenConf(flat) {
+  const root = {};
+  for (const [key, value] of Object.entries(flat)) {
+    const parts = key.split('.');
+    let node = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const seg = parts[i];
+      if (node[seg] === undefined || typeof node[seg] !== 'object') {
+        node[seg] = {};
+      }
+      node = node[seg];
+    }
+    node[parts[parts.length - 1]] = value;
+  }
+  return root;
+}
+
+// ---------------------------------------------------------------------------
+// CLI parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse an array of `--conf KEY=VALUE` strings (yargs delivers
+ * `argv.conf` when the option is registered as `array: true`) into a
+ * flat map. See plan §4.4 for semantics:
+ *
+ *   KEY=VALUE  → set the key to VALUE verbatim (string).
+ *   KEY        → alias for KEY=true (matches CMake's -D convention).
+ *   KEY=       → unset (remove the key from lower layers on merge).
+ *
+ * Returns two maps — set values and unset keys — so the merger can
+ * treat the latter specially.
+ *
+ * @param {string[] | undefined} rawArgs
+ * @returns {{ sets: Record<string,string>, unsets: Set<string> }}
+ */
+function parseCliConf(rawArgs) {
+  const sets   = {};
+  const unsets = new Set();
+
+  if (!rawArgs || rawArgs.length === 0) {
+    return { sets, unsets };
+  }
+
+  for (const arg of rawArgs) {
+    if (typeof arg !== 'string') {
+      throw new Error(`--conf expects KEY=VALUE string; got ${JSON.stringify(arg)}`);
+    }
+    const eqIdx = arg.indexOf('=');
+    if (eqIdx < 0) {
+      // Bare `KEY` → KEY=true (normalised to "ON").
+      const key = arg.trim();
+      if (key.length === 0) {
+        throw new Error('--conf was given an empty key');
+      }
+      sets[key] = 'ON';
+    } else {
+      const key   = arg.slice(0, eqIdx).trim();
+      const value = arg.slice(eqIdx + 1);
+      if (key.length === 0) {
+        throw new Error(`--conf ${JSON.stringify(arg)} has an empty key`);
+      }
+      if (value.length === 0) {
+        // KEY= → unset. Distinguish from KEY="" which callers can
+        // achieve by quoting the value; here the shell has already
+        // stripped the quotes, so an empty string past the `=` means
+        // "clear any inherited value for this key."
+        unsets.add(key);
+      } else {
+        sets[key] = value;
+      }
+    }
+  }
+
+  return { sets, unsets };
+}
+
+// ---------------------------------------------------------------------------
+// Local-overlay file
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and validate `wyvrn.local.json` at the given project root.
+ * Returns the parsed `conf` block as a flat map, or an empty map when
+ * the file is absent.
+ *
+ * Enforces plan §4.5: the only top-level key this file may carry in
+ * phase 1 is `conf`; anything else is a hard error (not a warning).
+ *
+ * @param {string} rootDir
+ * @returns {{ flat: Record<string,string>, path: string|null }}
+ */
+function readLocalOverlay(rootDir) {
+  const p = path.join(rootDir, LOCAL_OVERLAY_FILENAME);
+  if (!fs.existsSync(p)) return { flat: {}, path: null };
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (err) {
+    throw new Error(`cannot parse ${LOCAL_OVERLAY_FILENAME}: ${err.message}`);
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${LOCAL_OVERLAY_FILENAME} must contain a JSON object at the top level`);
+  }
+
+  for (const key of Object.keys(raw)) {
+    if (!LOCAL_OVERLAY_ALLOWED_TOP_KEYS.has(key)) {
+      const allowed = [...LOCAL_OVERLAY_ALLOWED_TOP_KEYS].join(', ');
+      throw new Error(
+        `${LOCAL_OVERLAY_FILENAME}: unknown top-level key ${JSON.stringify(key)} — ` +
+        `phase-1 allow-list: [${allowed}]. ` +
+        `If you meant to override dependencies or options, that is reserved ` +
+        `for a future phase; see claude/PLAN-CONF.md §4.5.`,
+      );
+    }
+  }
+
+  const confBlock = raw.conf ?? {};
+  const flat = flattenConf(confBlock);
+  validateFlatConfKeys(flat);
+  return { flat, path: p };
+}
+
+// ---------------------------------------------------------------------------
+// Recipe extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Pull the `conf` block out of an already-loaded recipe manifest and
+ * flatten it. A missing block is an empty map.
+ *
+ * Validation runs against the phase-1 allow-list; if a recipe declares
+ * a namespace we don't support yet, the install fails with a clear
+ * error rather than silently dropping the config.
+ *
+ * @param {object} manifest
+ * @returns {Record<string,string>}
+ */
+function readRecipeConf(manifest) {
+  const block = manifest?.conf ?? null;
+  if (block === null || block === undefined) return {};
+  const flat = flattenConf(block);
+  validateFlatConfKeys(flat);
+  return flat;
+}
+
+// ---------------------------------------------------------------------------
+// Profile extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Pull the optional `conf` block out of a loaded named profile JSON
+ * (see src/profile.js) and flatten it. A missing block is an empty
+ * map — profiles without `conf` round-trip byte-identically to
+ * pre-phase-2 behaviour.
+ *
+ * Validation runs against the phase-1 allow-list; an unknown
+ * namespace in a profile fails fast rather than silently dropping
+ * the config (CLAUDE.md §2 principle 8).
+ *
+ * @param {object|null|undefined} profile
+ * @returns {Record<string,string>}
+ */
+function readProfileConf(profile) {
+  const block = profile?.conf ?? null;
+  if (block === null || block === undefined) return {};
+  const flat = flattenConf(block);
+  validateFlatConfKeys(flat);
+  return flat;
+}
+
+// ---------------------------------------------------------------------------
+// Merge
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge the four layers with plan §4.2 precedence (post phase-2):
+ *
+ *   CLI unsets   — remove named keys from below.
+ *   CLI sets     — highest wins.
+ *   local        — overrides profile.
+ *   profile      — overrides recipe (team-shared team defaults).
+ *   recipe       — base defaults.
+ *
+ * Per-leaf override, not per-branch replace — so CLI setting only
+ * cmake.cache.FOO does not disturb a recipe's cmake.cache.BAR.
+ *
+ * The `profileFlat` parameter is optional. Pre-phase-2 callers that
+ * pass only three layers (recipe, local, cli) still work — profile
+ * defaults to an empty map, preserving the three-layer semantics
+ * exactly.
+ *
+ * @param {Record<string,string>} recipeFlat
+ * @param {Record<string,string>} localFlat
+ * @param {{ sets: Record<string,string>, unsets: Set<string> }} cli
+ * @param {Record<string,string>} [profileFlat]
+ * @returns {Record<string,string>}
+ */
+function mergeConfLayers(recipeFlat, localFlat, cli, profileFlat = {}) {
+  const out = { ...recipeFlat, ...profileFlat, ...localFlat, ...cli.sets };
+  for (const k of cli.unsets) delete out[k];
+  validateFlatConfKeys(out);
+  return out;
+}
+
+/**
+ * Convenience: do the whole four-layer resolution at once. Most
+ * callers want this. Individual layer helpers are exported for tests.
+ *
+ * The `profile` argument is optional. Callers that don't have a
+ * resolved profile to hand (e.g. the legacy three-layer call sites in
+ * `publish`, which intentionally ignore the profile tier so published
+ * artefacts aren't skewed by dev machines) pass nothing and get the
+ * three-layer merge (CLI > local > recipe).
+ *
+ * @param {object} args
+ * @param {object} [args.manifest]
+ * @param {string} args.rootDir
+ * @param {string[]} [args.cliConf]
+ * @param {object} [args.profile]  Resolved named profile JSON (may carry .conf).
+ * @returns {{
+ *   flat:             Record<string,string>,
+ *   recipeFlat:       Record<string,string>,
+ *   profileFlat:      Record<string,string>,
+ *   localFlat:        Record<string,string>,
+ *   cli:              { sets: Record<string,string>, unsets: Set<string> },
+ *   localOverlayPath: string | null,
+ * }}
+ */
+function resolveEffectiveConf({ manifest, rootDir, cliConf, profile }) {
+  const recipeFlat  = readRecipeConf(manifest);
+  const profileFlat = readProfileConf(profile);
+  const { flat: localFlat, path: localOverlayPath } = readLocalOverlay(rootDir);
+  const cli = parseCliConf(cliConf);
+  const flat = mergeConfLayers(recipeFlat, localFlat, cli, profileFlat);
+  return { flat, recipeFlat, profileFlat, localFlat, cli, localOverlayPath };
+}
+
+/**
+ * Extract only the `cmake.cache.*` portion of a flat conf map as
+ * `{ VARNAME: stringValue }` — the shape
+ * `src/toolchain/presets.js` wants for `cacheVariables`. Stable
+ * alphabetical key order so preset diffs are deterministic.
+ *
+ * @param {Record<string,string>} flatConf
+ * @returns {Record<string,string>}
+ */
+function cmakeCacheVariables(flatConf) {
+  const out = {};
+  const prefix = 'cmake.cache.';
+  const keys = Object.keys(flatConf).filter((k) => k.startsWith(prefix)).sort();
+  for (const k of keys) {
+    out[k.slice(prefix.length)] = flatConf[k];
+  }
+  return out;
+}
+
+module.exports = {
+  // High-level
+  resolveEffectiveConf,
+
+  // Per-layer
+  parseCliConf,
+  readLocalOverlay,
+  readRecipeConf,
+  readProfileConf,
+  mergeConfLayers,
+
+  // Shape transforms
+  flattenConf,
+  unflattenConf,
+  normalizeLeafValue,
+  cmakeCacheVariables,
+
+  // Constants (exported for tests + integration)
+  LOCAL_OVERLAY_FILENAME,
+  LOCAL_OVERLAY_ALLOWED_TOP_KEYS,
+};

package/src/conf/namespaces.js

@@ -0,0 +1,94 @@
+'use strict';
+
+// Allow-list of recognised `conf` namespaces (PLAN-CONF.md §4.1).
+//
+// Adding a new namespace is an intentional act — the plan commits to
+// expanding this file only when a concrete use case lands, not
+// speculatively. Phase 1 ships `cmake.cache.*` only; every other
+// namespace (env.*, build.*, tool.*) is reserved but not yet valid.
+//
+// Each entry describes how leaf names under that namespace are
+// validated. A namespace with `leaf: true` accepts any non-empty leaf
+// name; a namespace with `leaf: /regex/` enforces the regex at load
+// time. The regex only validates the leaf name — leaf VALUES are
+// normalised separately in ../conf/index.js.
+
+/**
+ * @typedef {Object} NamespaceSpec
+ * @property {RegExp} leaf
+ *   Pattern that every leaf name under this namespace must satisfy.
+ * @property {string} description
+ *   Human-readable one-liner shown in error messages.
+ */
+
+/** @type {Record<string, NamespaceSpec>} */
+const NAMESPACES = {
+  'cmake.cache': {
+    // CMake variable names: C/C++ identifier rules, no hyphens.
+    leaf:        /^[A-Za-z_][A-Za-z0-9_]*$/,
+    description: 'CMake cache variables — baked into CMakePresets.json cacheVariables.',
+  },
+};
+
+/**
+ * Parse a full dotted conf key (e.g. `cmake.cache.CHROMA_ENABLE_TEST`)
+ * into its namespace prefix and leaf name. The namespace is the
+ * longest matching prefix registered in NAMESPACES; anything after is
+ * the leaf.
+ *
+ * Returns `{ namespace, leaf }` on success, `null` when the key does
+ * not belong to any registered namespace or has no leaf component.
+ *
+ * @param {string} key
+ * @returns {{ namespace: string, leaf: string } | null}
+ */
+function splitKey(key) {
+  // Try longer namespaces first so "a.b.c" prefers namespace "a.b"
+  // over a hypothetical namespace "a".
+  const known = Object.keys(NAMESPACES).sort((a, b) => b.length - a.length);
+  for (const ns of known) {
+    const prefix = `${ns}.`;
+    if (key.startsWith(prefix)) {
+      const leaf = key.slice(prefix.length);
+      if (leaf.length === 0) return null;
+      return { namespace: ns, leaf };
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate a flat `{key: value}` map against the namespace allow-list.
+ * Throws on the first offender (fail-fast, matches the Zip Slip
+ * validator's style). Leaf VALUES are not type-checked here — values
+ * arrive as strings from the CLI, normalised from JSON elsewhere; type
+ * enforcement happens in ../conf/index.js at merge time.
+ *
+ * @param {Record<string, string>} flatConf
+ * @throws {Error} if any key's namespace or leaf is rejected.
+ */
+function validateFlatConfKeys(flatConf) {
+  const knownList = Object.keys(NAMESPACES).sort().join(', ');
+  for (const key of Object.keys(flatConf)) {
+    const parts = splitKey(key);
+    if (!parts) {
+      throw new Error(
+        `unknown conf namespace in ${JSON.stringify(key)} — ` +
+        `phase-1 allow-list: [${knownList}]`,
+      );
+    }
+    const spec = NAMESPACES[parts.namespace];
+    if (!spec.leaf.test(parts.leaf)) {
+      throw new Error(
+        `invalid leaf name ${JSON.stringify(parts.leaf)} for conf namespace ` +
+        `"${parts.namespace}" — ${spec.description}`,
+      );
+    }
+  }
+}
+
+module.exports = {
+  NAMESPACES,
+  splitKey,
+  validateFlatConfKeys,
+};