wyvrnpm 2.0.4 → 2.3.2

package/src/compat.js

@@ -0,0 +1,261 @@
+'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 ALWAYS evaluated
+ * as `exact` regardless of what the block says — cross-arch/cross-OS
+ * binaries are never ABI-compatible.
+ */
+
+const OS_ARCH_ALWAYS_EXACT = 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`.
+ * `os` and `arch` are forced to `exact`.
+ *
+ * @param {object|null|undefined} rawCompat
+ * @returns {Record<string, string>}
+ */
+function normalizeCompat(rawCompat) {
+  const result = {};
+  for (const field of DEFAULT_COMPAT_FIELDS) result[field] = 'exact';
+
+  if (!rawCompat || typeof rawCompat !== 'object') return result;
+
+  for (const [field, spec] of Object.entries(rawCompat)) {
+    if (OS_ARCH_ALWAYS_EXACT.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
+ * @returns {{
+ *   compatible: boolean,
+ *   reasons: Array<{ field: string, mode: string, consumer: any, package: any, outcome: string }>,
+ * }}
+ */
+function evaluateCompat(consumerProfile, packageProfile, rawCompat) {
+  const compat = normalizeCompat(rawCompat);
+  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,
+};

package/src/config.js

@@ -4,6 +4,8 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
+const log = require('./logger');
+
 /**
  * Returns the directory where wyvrnpm stores its config.
  *   Windows : %LOCALAPPDATA%\wyvrnpm
@@ -41,7 +43,7 @@ function readConfig() {
       defaultProfile: raw.defaultProfile  ?? 'default',
     };
   } catch {
-    console.warn('[wyvrn] Warning: could not parse config.json — using defaults');
+    log.warn('could not parse config.json — using defaults');
     return { installSources: [], publishSources: [], linkedPackages: {}, defaultProfile: 'default' };
   }
 }