wyvrnpm 2.11.0 → 2.12.2

package/src/compat.js

@@ -1,273 +1,273 @@
-'use strict';
-
-/**
- * Declarative compatibility evaluator for v2 build profiles.
- *
- * Publishers declare a `compatibility` block in their package's `wyvrn.json`
- * stating which profile fields must match exactly vs which may differ.
- * At install time, when no exact profileHash match exists, this module
- * evaluates each registry-side build against the consumer's profile and
- * picks a compatible one if any.
- *
- * The block format is per-field: either a string shorthand or an object.
- *
- *   "compatibility": {
- *     "compiler.cppstd":   "lte",
- *     "compiler.runtime":  "exact",
- *     "compiler.version":  "exact-or-newer"
- *   }
- *
- *   equivalent object form (allows future extensions):
- *
- *   "compatibility": {
- *     "compiler.cppstd":   { "mode": "lte" }
- *   }
- *
- * Modes:
- *   exact           | Package and consumer values must be equal.
- *   any             | Field is ignored.
- *   lte             | Package value ≤ consumer value (consumer is at least as
- *                   | new/high — e.g. cppstd=20 package usable by cppstd=23).
- *   gte             | Package value ≥ consumer value (symmetry; rarely useful).
- *   exact-or-newer  | Semantically identical to `lte` at MVP — kept as a
- *                   | distinct name because it reads naturally for compiler
- *                   | version fields and leaves room for future "same major"
- *                   | semantics without renaming.
- *
- * Missing fields default to `exact`. `os` and `arch` are normally forced
- * to `exact` regardless of what the block says — cross-arch/cross-OS
- * binaries are never ABI-compatible. The one exception is
- * `kind: "HeaderOnlyLib"`: header-only packages ship no binary, so the
- * publisher's declared modes for `os`/`arch` are respected. Binary kinds
- * (`StaticLib`, `DynamicLib`, `ConsoleApp`, …) keep the hard guarantee.
- */
-
-const OS_ARCH_FIELDS = new Set(['os', 'arch']);
-
-const DEFAULT_COMPAT_FIELDS = [
-  'os',
-  'arch',
-  'compiler',
-  'compiler.version',
-  'compiler.cppstd',
-  'compiler.runtime',
-];
-
-const VALID_MODES = new Set(['exact', 'any', 'lte', 'gte', 'exact-or-newer']);
-
-/**
- * Normalise a raw compatibility block into `{ field → mode }`.
- * Missing fields fall back to `exact`. Unknown modes fall back to `exact`.
- *
- * For binary kinds (`StaticLib`, `DynamicLib`, `ConsoleApp`, …) `os` and
- * `arch` are forced to `exact` — publisher-declared modes are silently
- * dropped because cross-arch binaries are never ABI-safe. For
- * `kind: "HeaderOnlyLib"` the publisher's declared modes are respected,
- * since there is no binary to be ABI-incompatible with.
- *
- * @param {object|null|undefined} rawCompat
- * @param {string|null|undefined} [packageKind]  Package manifest `kind` field.
- * @returns {Record<string, string>}
- */
-function normalizeCompat(rawCompat, packageKind) {
-  const result = {};
-  for (const field of DEFAULT_COMPAT_FIELDS) result[field] = 'exact';
-
-  if (!rawCompat || typeof rawCompat !== 'object') return result;
-
-  const headerOnly = packageKind === 'HeaderOnlyLib';
-
-  for (const [field, spec] of Object.entries(rawCompat)) {
-    if (!headerOnly && OS_ARCH_FIELDS.has(field)) continue;
-    const mode = typeof spec === 'string' ? spec : (spec && spec.mode);
-    if (mode && VALID_MODES.has(mode)) result[field] = mode;
-  }
-  return result;
-}
-
-/**
- * Return the default compatibility block — all fields `exact`.
- * Used by `publish` when the source manifest lacks a block.
- * @returns {Record<string, string>}
- */
-function defaultCompatBlock() {
-  const result = {};
-  for (const field of DEFAULT_COMPAT_FIELDS) result[field] = 'exact';
-  return result;
-}
-
-/**
- * Evaluate a single field under a given mode.
- *
- * @returns {'match'|'compat-lte'|'compat-gte'|'compat-newer'|'compat-any'|'incompatible'}
- */
-function evaluateField(mode, consumerVal, packageVal) {
-  switch (mode) {
-    case 'any':
-      return 'compat-any';
-
-    case 'exact':
-      return consumerVal === packageVal ? 'match' : 'incompatible';
-
-    case 'lte': {
-      if (consumerVal === packageVal) return 'match';
-      const c = Number(consumerVal);
-      const p = Number(packageVal);
-      if (Number.isFinite(c) && Number.isFinite(p)) {
-        return p <= c ? 'compat-lte' : 'incompatible';
-      }
-      return 'incompatible';
-    }
-
-    case 'gte': {
-      if (consumerVal === packageVal) return 'match';
-      const c = Number(consumerVal);
-      const p = Number(packageVal);
-      if (Number.isFinite(c) && Number.isFinite(p)) {
-        return p >= c ? 'compat-gte' : 'incompatible';
-      }
-      return 'incompatible';
-    }
-
-    case 'exact-or-newer': {
-      if (consumerVal === packageVal) return 'match';
-      const c = Number(consumerVal);
-      const p = Number(packageVal);
-      if (Number.isFinite(c) && Number.isFinite(p)) {
-        return c >= p ? 'compat-newer' : 'incompatible';
-      }
-      return 'incompatible';
-    }
-
-    default:
-      // Unknown mode → fail safe
-      return 'incompatible';
-  }
-}
-
-/**
- * Evaluate a package's compatibility block against a consumer's profile.
- *
- * If either `consumerProfile` or `packageProfile` carries an `options`
- * sub-object, options participate in compatibility: every option present
- * on either side is evaluated, with mode `exact` by default. The compat
- * block may override a specific option's mode via `options.<name>` (for
- * example `"options.shared": "any"` to say "this build has no ABI
- * dependence on `shared`"). See PLAN-OPTIONS §3.5.
- *
- * @param {Record<string, any>}         consumerProfile  may include `options: {...}`
- * @param {Record<string, any>}         packageProfile   may include `options: {...}`
- * @param {object|null|undefined}       rawCompat        compatibility block from the package manifest
- * @param {string|null|undefined}       [packageKind]    package manifest `kind` field — unlocks `os`/`arch` modes for HeaderOnlyLib
- * @returns {{
- *   compatible: boolean,
- *   reasons: Array<{ field: string, mode: string, consumer: any, package: any, outcome: string }>,
- * }}
- */
-function evaluateCompat(consumerProfile, packageProfile, rawCompat, packageKind) {
-  const compat = normalizeCompat(rawCompat, packageKind);
-  const reasons = [];
-  let compatible = true;
-
-  for (const [field, mode] of Object.entries(compat)) {
-    // `options.<name>` keys in the compat block are handled below,
-    // together with any options present on either profile.
-    if (field.startsWith('options.')) continue;
-
-    const cVal = consumerProfile[field];
-    const pVal = packageProfile[field];
-    const outcome = evaluateField(mode, cVal, pVal);
-    reasons.push({ field, mode, consumer: cVal, package: pVal, outcome });
-    if (outcome === 'incompatible') compatible = false;
-  }
-
-  // Evaluate every option the consumer or package declares. Default mode
-  // is `exact`; the compat block may relax to `any` (and the other modes
-  // work when the values are numeric strings). Forward-compat: an option
-  // present on one side only is treated as `incompatible` under exact —
-  // the recipe shapes differ.
-  const consumerOpts = consumerProfile.options ?? {};
-  const packageOpts  = packageProfile.options  ?? {};
-  const optionKeys = new Set([...Object.keys(consumerOpts), ...Object.keys(packageOpts)]);
-  for (const name of optionKeys) {
-    const field = `options.${name}`;
-    const mode  = compat[field] ?? 'exact';
-    const cVal  = consumerOpts[name];
-    const pVal  = packageOpts[name];
-    const outcome = evaluateField(mode, cVal, pVal);
-    reasons.push({ field, mode, consumer: cVal, package: pVal, outcome });
-    if (outcome === 'incompatible') compatible = false;
-  }
-
-  return { compatible, reasons };
-}
-
-/**
- * Deterministic tiebreaker when multiple compatible candidates exist.
- *
- *   1. Prefer candidates whose `compiler` matches the consumer's.
- *   2. Prefer the highest numeric `compiler.version`.
- *   3. Prefer candidates whose `compiler.runtime` matches the consumer's.
- *   4. Prefer the lexicographically earliest profile hash (stable fallback).
- *
- * @param {Array<{ profileHash: string, packageProfile: Record<string, any>, reasons: Array<any> }>} candidates
- * @param {Record<string, string|null>} consumerProfile
- * @returns {object|null}  The preferred candidate (or null if list is empty).
- */
-function pickBestCandidate(candidates, consumerProfile) {
-  if (!candidates || candidates.length === 0) return null;
-  if (candidates.length === 1) return candidates[0];
-
-  const sorted = candidates.slice().sort((a, b) => {
-    const compilerA = a.packageProfile.compiler === consumerProfile.compiler ? 0 : 1;
-    const compilerB = b.packageProfile.compiler === consumerProfile.compiler ? 0 : 1;
-    if (compilerA !== compilerB) return compilerA - compilerB;
-
-    const verA = Number(a.packageProfile['compiler.version']) || 0;
-    const verB = Number(b.packageProfile['compiler.version']) || 0;
-    if (verA !== verB) return verB - verA; // descending
-
-    const runtimeA = a.packageProfile['compiler.runtime'] === consumerProfile['compiler.runtime'] ? 0 : 1;
-    const runtimeB = b.packageProfile['compiler.runtime'] === consumerProfile['compiler.runtime'] ? 0 : 1;
-    if (runtimeA !== runtimeB) return runtimeA - runtimeB;
-
-    return a.profileHash < b.profileHash ? -1 : 1;
-  });
-
-  return sorted[0];
-}
-
-/**
- * Render a reasons array into a compact human-readable summary — used for
- * the "chose candidate X because …" log line at install time.
- *
- * @param {Array<{ field, mode, consumer, package, outcome }>} reasons
- * @returns {string}
- */
-function summarizeReasons(reasons) {
-  return reasons
-    .filter((r) => r.outcome !== 'compat-any' || r.mode !== 'any') // skip trivial any
-    .map((r) => {
-      switch (r.outcome) {
-        case 'match':         return `${r.field}=${r.consumer}`;
-        case 'compat-lte':    return `${r.field} ${r.package}→${r.consumer} (lte)`;
-        case 'compat-gte':    return `${r.field} ${r.package}←${r.consumer} (gte)`;
-        case 'compat-newer':  return `${r.field} ${r.package}→${r.consumer} (newer)`;
-        case 'compat-any':    return `${r.field}=* (any)`;
-        case 'incompatible':  return `${r.field} INCOMPAT (need ${r.consumer}, have ${r.package})`;
-        default:              return `${r.field} ${r.outcome}`;
-      }
-    })
-    .join(', ');
-}
-
-module.exports = {
-  normalizeCompat,
-  defaultCompatBlock,
-  evaluateCompat,
-  evaluateField,
-  pickBestCandidate,
-  summarizeReasons,
-  DEFAULT_COMPAT_FIELDS,
-  VALID_MODES,
-};
+'use strict';
+
+/**
+ * Declarative compatibility evaluator for v2 build profiles.
+ *
+ * Publishers declare a `compatibility` block in their package's `wyvrn.json`
+ * stating which profile fields must match exactly vs which may differ.
+ * At install time, when no exact profileHash match exists, this module
+ * evaluates each registry-side build against the consumer's profile and
+ * picks a compatible one if any.
+ *
+ * The block format is per-field: either a string shorthand or an object.
+ *
+ *   "compatibility": {
+ *     "compiler.cppstd":   "lte",
+ *     "compiler.runtime":  "exact",
+ *     "compiler.version":  "exact-or-newer"
+ *   }
+ *
+ *   equivalent object form (allows future extensions):
+ *
+ *   "compatibility": {
+ *     "compiler.cppstd":   { "mode": "lte" }
+ *   }
+ *
+ * Modes:
+ *   exact           | Package and consumer values must be equal.
+ *   any             | Field is ignored.
+ *   lte             | Package value ≤ consumer value (consumer is at least as
+ *                   | new/high — e.g. cppstd=20 package usable by cppstd=23).
+ *   gte             | Package value ≥ consumer value (symmetry; rarely useful).
+ *   exact-or-newer  | Semantically identical to `lte` at MVP — kept as a
+ *                   | distinct name because it reads naturally for compiler
+ *                   | version fields and leaves room for future "same major"
+ *                   | semantics without renaming.
+ *
+ * Missing fields default to `exact`. `os` and `arch` are normally forced
+ * to `exact` regardless of what the block says — cross-arch/cross-OS
+ * binaries are never ABI-compatible. The one exception is
+ * `kind: "HeaderOnlyLib"`: header-only packages ship no binary, so the
+ * publisher's declared modes for `os`/`arch` are respected. Binary kinds
+ * (`StaticLib`, `DynamicLib`, `ConsoleApp`, …) keep the hard guarantee.
+ */
+
+const OS_ARCH_FIELDS = new Set(['os', 'arch']);
+
+const DEFAULT_COMPAT_FIELDS = [
+  'os',
+  'arch',
+  'compiler',
+  'compiler.version',
+  'compiler.cppstd',
+  'compiler.runtime',
+];
+
+const VALID_MODES = new Set(['exact', 'any', 'lte', 'gte', 'exact-or-newer']);
+
+/**
+ * Normalise a raw compatibility block into `{ field → mode }`.
+ * Missing fields fall back to `exact`. Unknown modes fall back to `exact`.
+ *
+ * For binary kinds (`StaticLib`, `DynamicLib`, `ConsoleApp`, …) `os` and
+ * `arch` are forced to `exact` — publisher-declared modes are silently
+ * dropped because cross-arch binaries are never ABI-safe. For
+ * `kind: "HeaderOnlyLib"` the publisher's declared modes are respected,
+ * since there is no binary to be ABI-incompatible with.
+ *
+ * @param {object|null|undefined} rawCompat
+ * @param {string|null|undefined} [packageKind]  Package manifest `kind` field.
+ * @returns {Record<string, string>}
+ */
+function normalizeCompat(rawCompat, packageKind) {
+  const result = {};
+  for (const field of DEFAULT_COMPAT_FIELDS) result[field] = 'exact';
+
+  if (!rawCompat || typeof rawCompat !== 'object') return result;
+
+  const headerOnly = packageKind === 'HeaderOnlyLib';
+
+  for (const [field, spec] of Object.entries(rawCompat)) {
+    if (!headerOnly && OS_ARCH_FIELDS.has(field)) continue;
+    const mode = typeof spec === 'string' ? spec : (spec && spec.mode);
+    if (mode && VALID_MODES.has(mode)) result[field] = mode;
+  }
+  return result;
+}
+
+/**
+ * Return the default compatibility block — all fields `exact`.
+ * Used by `publish` when the source manifest lacks a block.
+ * @returns {Record<string, string>}
+ */
+function defaultCompatBlock() {
+  const result = {};
+  for (const field of DEFAULT_COMPAT_FIELDS) result[field] = 'exact';
+  return result;
+}
+
+/**
+ * Evaluate a single field under a given mode.
+ *
+ * @returns {'match'|'compat-lte'|'compat-gte'|'compat-newer'|'compat-any'|'incompatible'}
+ */
+function evaluateField(mode, consumerVal, packageVal) {
+  switch (mode) {
+    case 'any':
+      return 'compat-any';
+
+    case 'exact':
+      return consumerVal === packageVal ? 'match' : 'incompatible';
+
+    case 'lte': {
+      if (consumerVal === packageVal) return 'match';
+      const c = Number(consumerVal);
+      const p = Number(packageVal);
+      if (Number.isFinite(c) && Number.isFinite(p)) {
+        return p <= c ? 'compat-lte' : 'incompatible';
+      }
+      return 'incompatible';
+    }
+
+    case 'gte': {
+      if (consumerVal === packageVal) return 'match';
+      const c = Number(consumerVal);
+      const p = Number(packageVal);
+      if (Number.isFinite(c) && Number.isFinite(p)) {
+        return p >= c ? 'compat-gte' : 'incompatible';
+      }
+      return 'incompatible';
+    }
+
+    case 'exact-or-newer': {
+      if (consumerVal === packageVal) return 'match';
+      const c = Number(consumerVal);
+      const p = Number(packageVal);
+      if (Number.isFinite(c) && Number.isFinite(p)) {
+        return c >= p ? 'compat-newer' : 'incompatible';
+      }
+      return 'incompatible';
+    }
+
+    default:
+      // Unknown mode → fail safe
+      return 'incompatible';
+  }
+}
+
+/**
+ * Evaluate a package's compatibility block against a consumer's profile.
+ *
+ * If either `consumerProfile` or `packageProfile` carries an `options`
+ * sub-object, options participate in compatibility: every option present
+ * on either side is evaluated, with mode `exact` by default. The compat
+ * block may override a specific option's mode via `options.<name>` (for
+ * example `"options.shared": "any"` to say "this build has no ABI
+ * dependence on `shared`"). See PLAN-OPTIONS §3.5.
+ *
+ * @param {Record<string, any>}         consumerProfile  may include `options: {...}`
+ * @param {Record<string, any>}         packageProfile   may include `options: {...}`
+ * @param {object|null|undefined}       rawCompat        compatibility block from the package manifest
+ * @param {string|null|undefined}       [packageKind]    package manifest `kind` field — unlocks `os`/`arch` modes for HeaderOnlyLib
+ * @returns {{
+ *   compatible: boolean,
+ *   reasons: Array<{ field: string, mode: string, consumer: any, package: any, outcome: string }>,
+ * }}
+ */
+function evaluateCompat(consumerProfile, packageProfile, rawCompat, packageKind) {
+  const compat = normalizeCompat(rawCompat, packageKind);
+  const reasons = [];
+  let compatible = true;
+
+  for (const [field, mode] of Object.entries(compat)) {
+    // `options.<name>` keys in the compat block are handled below,
+    // together with any options present on either profile.
+    if (field.startsWith('options.')) continue;
+
+    const cVal = consumerProfile[field];
+    const pVal = packageProfile[field];
+    const outcome = evaluateField(mode, cVal, pVal);
+    reasons.push({ field, mode, consumer: cVal, package: pVal, outcome });
+    if (outcome === 'incompatible') compatible = false;
+  }
+
+  // Evaluate every option the consumer or package declares. Default mode
+  // is `exact`; the compat block may relax to `any` (and the other modes
+  // work when the values are numeric strings). Forward-compat: an option
+  // present on one side only is treated as `incompatible` under exact —
+  // the recipe shapes differ.
+  const consumerOpts = consumerProfile.options ?? {};
+  const packageOpts  = packageProfile.options  ?? {};
+  const optionKeys = new Set([...Object.keys(consumerOpts), ...Object.keys(packageOpts)]);
+  for (const name of optionKeys) {
+    const field = `options.${name}`;
+    const mode  = compat[field] ?? 'exact';
+    const cVal  = consumerOpts[name];
+    const pVal  = packageOpts[name];
+    const outcome = evaluateField(mode, cVal, pVal);
+    reasons.push({ field, mode, consumer: cVal, package: pVal, outcome });
+    if (outcome === 'incompatible') compatible = false;
+  }
+
+  return { compatible, reasons };
+}
+
+/**
+ * Deterministic tiebreaker when multiple compatible candidates exist.
+ *
+ *   1. Prefer candidates whose `compiler` matches the consumer's.
+ *   2. Prefer the highest numeric `compiler.version`.
+ *   3. Prefer candidates whose `compiler.runtime` matches the consumer's.
+ *   4. Prefer the lexicographically earliest profile hash (stable fallback).
+ *
+ * @param {Array<{ profileHash: string, packageProfile: Record<string, any>, reasons: Array<any> }>} candidates
+ * @param {Record<string, string|null>} consumerProfile
+ * @returns {object|null}  The preferred candidate (or null if list is empty).
+ */
+function pickBestCandidate(candidates, consumerProfile) {
+  if (!candidates || candidates.length === 0) return null;
+  if (candidates.length === 1) return candidates[0];
+
+  const sorted = candidates.slice().sort((a, b) => {
+    const compilerA = a.packageProfile.compiler === consumerProfile.compiler ? 0 : 1;
+    const compilerB = b.packageProfile.compiler === consumerProfile.compiler ? 0 : 1;
+    if (compilerA !== compilerB) return compilerA - compilerB;
+
+    const verA = Number(a.packageProfile['compiler.version']) || 0;
+    const verB = Number(b.packageProfile['compiler.version']) || 0;
+    if (verA !== verB) return verB - verA; // descending
+
+    const runtimeA = a.packageProfile['compiler.runtime'] === consumerProfile['compiler.runtime'] ? 0 : 1;
+    const runtimeB = b.packageProfile['compiler.runtime'] === consumerProfile['compiler.runtime'] ? 0 : 1;
+    if (runtimeA !== runtimeB) return runtimeA - runtimeB;
+
+    return a.profileHash < b.profileHash ? -1 : 1;
+  });
+
+  return sorted[0];
+}
+
+/**
+ * Render a reasons array into a compact human-readable summary — used for
+ * the "chose candidate X because …" log line at install time.
+ *
+ * @param {Array<{ field, mode, consumer, package, outcome }>} reasons
+ * @returns {string}
+ */
+function summarizeReasons(reasons) {
+  return reasons
+    .filter((r) => r.outcome !== 'compat-any' || r.mode !== 'any') // skip trivial any
+    .map((r) => {
+      switch (r.outcome) {
+        case 'match':         return `${r.field}=${r.consumer}`;
+        case 'compat-lte':    return `${r.field} ${r.package}→${r.consumer} (lte)`;
+        case 'compat-gte':    return `${r.field} ${r.package}←${r.consumer} (gte)`;
+        case 'compat-newer':  return `${r.field} ${r.package}→${r.consumer} (newer)`;
+        case 'compat-any':    return `${r.field}=* (any)`;
+        case 'incompatible':  return `${r.field} INCOMPAT (need ${r.consumer}, have ${r.package})`;
+        default:              return `${r.field} ${r.outcome}`;
+      }
+    })
+    .join(', ');
+}
+
+module.exports = {
+  normalizeCompat,
+  defaultCompatBlock,
+  evaluateCompat,
+  evaluateField,
+  pickBestCandidate,
+  summarizeReasons,
+  DEFAULT_COMPAT_FIELDS,
+  VALID_MODES,
+};