wyvrnpm 2.10.2 → 2.12.2

package/src/version-range.js

@@ -1,301 +1,301 @@
-'use strict';
-
-/**
- * Version range parsing and matching for 4-part `major.minor.patch.build`
- * versions.
- *
- * Accepts three range syntaxes in addition to the existing exact and
- * `"latest"` strings:
- *
- *   "^1.2.3.4"        major-pinned  : >= 1.2.3.4  <  2.0.0.0
- *   "~1.2.3.4"        minor-pinned  : >= 1.2.3.4  <  1.3.0.0
- *   ">=1.2.3.4 <2.0"  explicit      : one or more space-separated comparators
- *                                     among >=, >, <=, <, =
- *
- * `parseRange(s)` classifies the input; `matchesRange(v, parsed)`
- * evaluates a candidate version; `pickHighestInRange(versions, parsed)`
- * selects the best match; `intersectRanges(a, b)` combines two ranges
- * (returns null when the intersection is empty).
- *
- * See claude/PLAN-VERSION-RANGES.md for the full design.
- */
-
-const VERSION_RE = /^\d+\.\d+\.\d+\.\d+$/;
-
-/**
- * Compare two 4-part versions numerically. Missing trailing components
- * default to 0 so `compareVersions("1.2", "1.2.0.0") === 0`, though the
- * parser elsewhere always emits fully-qualified 4-part strings.
- *
- * @param {string} a
- * @param {string} b
- * @returns {-1|0|1}
- */
-function compareVersions(a, b) {
-  const partsOf = (s) => s.split('.').map((n) => parseInt(n, 10) || 0);
-  const pa = partsOf(a);
-  const pb = partsOf(b);
-  const len = Math.max(pa.length, pb.length);
-  for (let i = 0; i < len; i++) {
-    const x = pa[i] ?? 0;
-    const y = pb[i] ?? 0;
-    if (x < y) return -1;
-    if (x > y) return 1;
-  }
-  return 0;
-}
-
-function bumpMajor(v) {
-  const [maj] = v.split('.').map((n) => parseInt(n, 10) || 0);
-  return `${maj + 1}.0.0.0`;
-}
-
-function bumpMinor(v) {
-  const [maj, min] = v.split('.').map((n) => parseInt(n, 10) || 0);
-  return `${maj}.${min + 1}.0.0`;
-}
-
-/**
- * Parse a dependency version string into a structured spec. Exact versions
- * and `"latest"` pass through unchanged; `^` / `~` / comparator strings
- * become `{ kind: 'range', min, max }` specs.
- *
- * `min` and `max` are each `{ op: '>=' | '>' | null, v: string } | null`
- * (null means unbounded on that side — an open upper bound, etc.).
- *
- * Throws on malformed input with a user-friendly multi-line error that
- * lists the supported syntaxes.
- *
- * @param {string} spec
- * @returns {{ kind: 'exact', version: string }
- *         | { kind: 'tag',   tag:    'latest' }
- *         | { kind: 'range', raw: string,
- *             min: { op: '>='|'>', v: string } | null,
- *             max: { op: '<='|'<', v: string } | null,
- *             exact?: string }}
- */
-function parseRange(spec) {
-  if (typeof spec !== 'string' || spec.length === 0) {
-    throw new Error(malformedRangeMessage(spec, 'version spec must be a non-empty string'));
-  }
-  const s = spec.trim();
-
-  if (s === 'latest') return { kind: 'tag', tag: 'latest' };
-
-  // `linked:` is handled by resolve.js directly — not our concern.
-  if (s.startsWith('linked:')) return { kind: 'linked', raw: s };
-
-  if (VERSION_RE.test(s)) return { kind: 'exact', version: s };
-
-  // Caret / tilde — require a full 4-part version as the operand.
-  if (s[0] === '^' || s[0] === '~') {
-    const op = s[0];
-    const v  = s.slice(1).trim();
-    if (!VERSION_RE.test(v)) {
-      throw new Error(malformedRangeMessage(spec, `${op} prefix requires a 4-part version`));
-    }
-    return {
-      kind: 'range',
-      raw:  s,
-      min:  { op: '>=', v },
-      max:  { op: '<',  v: op === '^' ? bumpMajor(v) : bumpMinor(v) },
-    };
-  }
-
-  // Explicit comparator form: one or more of {>=, >, <=, <, =} each followed
-  // by a 4-part version, space-separated.
-  if (/^[<>=]/.test(s)) {
-    const tokens = s.split(/\s+/);
-    let min = null;
-    let max = null;
-    let exact = null;
-    for (const tok of tokens) {
-      const m = tok.match(/^(>=|<=|>|<|=)(\d+\.\d+\.\d+\.\d+)$/);
-      if (!m) {
-        throw new Error(malformedRangeMessage(spec, `unrecognised comparator "${tok}"`));
-      }
-      const [, op, v] = m;
-      if (op === '=') {
-        if (exact && exact !== v) {
-          throw new Error(malformedRangeMessage(spec, `conflicting = comparators (${exact} vs ${v})`));
-        }
-        exact = v;
-      } else if (op === '>=' || op === '>') {
-        if (!min || compareVersions(v, min.v) > 0 || (compareVersions(v, min.v) === 0 && op === '>')) {
-          min = { op, v };
-        }
-      } else {
-        if (!max || compareVersions(v, max.v) < 0 || (compareVersions(v, max.v) === 0 && op === '<')) {
-          max = { op, v };
-        }
-      }
-    }
-    if (exact) return { kind: 'exact', version: exact };
-    if (!min && !max) {
-      throw new Error(malformedRangeMessage(spec, 'no comparators parsed'));
-    }
-    return { kind: 'range', raw: s, min, max };
-  }
-
-  throw new Error(malformedRangeMessage(spec, 'unknown version syntax'));
-}
-
-function malformedRangeMessage(spec, why) {
-  return (
-    `cannot parse dependency version ${JSON.stringify(spec)}: ${why}\n` +
-    `  supported syntaxes:\n` +
-    `    "1.2.3.4"                    exact version\n` +
-    `    "latest"                     latest-published tag\n` +
-    `    "^1.2.3.4"                   major-pinned range (>= 1.2.3.4 < 2.0.0.0)\n` +
-    `    "~1.2.3.4"                   minor-pinned range (>= 1.2.3.4 < 1.3.0.0)\n` +
-    `    ">=1.2.3.4 <2.0.0.0"         explicit range (>=, >, <=, <, = separated by spaces)`
-  );
-}
-
-/**
- * Returns true if `version` satisfies every bound in `parsed`. Exact-kind
- * specs require byte-equal; tag/linked specs always return false here
- * because they are handled upstream.
- *
- * @param {string} version
- * @param {ReturnType<typeof parseRange>} parsed
- * @returns {boolean}
- */
-function matchesRange(version, parsed) {
-  if (!parsed) return false;
-  if (parsed.kind === 'exact') return version === parsed.version;
-  if (parsed.kind !== 'range') return false;
-  if (parsed.min) {
-    const cmp = compareVersions(version, parsed.min.v);
-    if (parsed.min.op === '>=' && cmp < 0) return false;
-    if (parsed.min.op === '>'  && cmp <= 0) return false;
-  }
-  if (parsed.max) {
-    const cmp = compareVersions(version, parsed.max.v);
-    if (parsed.max.op === '<=' && cmp > 0) return false;
-    if (parsed.max.op === '<'  && cmp >= 0) return false;
-  }
-  return true;
-}
-
-/**
- * Pick the highest version from `publishedVersions` that satisfies
- * `parsed`. Returns null when no version matches. Input is not mutated.
- *
- * @param {string[]} publishedVersions
- * @param {ReturnType<typeof parseRange>} parsed
- * @returns {string|null}
- */
-function pickHighestInRange(publishedVersions, parsed) {
-  if (!Array.isArray(publishedVersions) || publishedVersions.length === 0) return null;
-  const matches = publishedVersions.filter((v) => matchesRange(v, parsed));
-  if (matches.length === 0) return null;
-  matches.sort(compareVersions);
-  return matches[matches.length - 1];
-}
-
-/**
- * Intersect two parsed range specs. Exact specs are treated as the degenerate
- * range `[v, v]`. Returns a new range spec or null when the intersection is
- * empty.
- *
- * `tag` and `linked` kinds cannot participate in intersection — the caller
- * must resolve them to exact first. We throw rather than silently ignore.
- *
- * @param {ReturnType<typeof parseRange>} a
- * @param {ReturnType<typeof parseRange>} b
- * @returns {{ kind: 'range'|'exact', ... }|null}
- */
-function intersectRanges(a, b) {
-  const liftExact = (spec) => spec.kind === 'exact'
-    ? { kind: 'range', raw: spec.version, min: { op: '>=', v: spec.version }, max: { op: '<=', v: spec.version } }
-    : spec;
-
-  if (!a || !b) throw new Error('intersectRanges: null spec');
-  if (a.kind === 'tag' || a.kind === 'linked' || b.kind === 'tag' || b.kind === 'linked') {
-    throw new Error('intersectRanges: tag/linked must be resolved before intersection');
-  }
-
-  const ra = liftExact(a);
-  const rb = liftExact(b);
-
-  // Tighter min (higher value; strictly-greater beats equal under gte).
-  const tighterMin = pickTighter(ra.min, rb.min, 'min');
-  // Tighter max (lower value; strictly-less beats equal under lte).
-  const tighterMax = pickTighter(ra.max, rb.max, 'max');
-
-  if (tighterMin && tighterMax) {
-    const cmp = compareVersions(tighterMin.v, tighterMax.v);
-    if (cmp > 0) return null;
-    if (cmp === 0) {
-      // Both bounds reference the same version. Feasible only if both are
-      // inclusive; otherwise the point is excluded.
-      if (tighterMin.op !== '>=' || tighterMax.op !== '<=') return null;
-      return { kind: 'exact', version: tighterMin.v };
-    }
-  }
-
-  return {
-    kind: 'range',
-    raw:  `${ra.raw ?? 'range'} ∩ ${rb.raw ?? 'range'}`,
-    min:  tighterMin,
-    max:  tighterMax,
-  };
-}
-
-function pickTighter(a, b, kind) {
-  if (!a) return b;
-  if (!b) return a;
-  const cmp = compareVersions(a.v, b.v);
-  if (kind === 'min') {
-    if (cmp > 0) return a;
-    if (cmp < 0) return b;
-    // equal: strictly-greater is tighter than gte
-    return a.op === '>' ? a : b;
-  } else {
-    if (cmp < 0) return a;
-    if (cmp > 0) return b;
-    return a.op === '<' ? a : b;
-  }
-}
-
-/**
- * Human-readable rendering for error messages. Exact and tag kinds pass
- * through unchanged; ranges render as the original raw string when
- * available, else as a comparator reconstruction.
- *
- * @param {ReturnType<typeof parseRange>} parsed
- * @returns {string}
- */
-function rangeToString(parsed) {
-  if (!parsed) return '(unparsed)';
-  if (parsed.kind === 'exact') return parsed.version;
-  if (parsed.kind === 'tag')   return parsed.tag;
-  if (parsed.kind === 'linked') return parsed.raw;
-  if (parsed.raw && !parsed.raw.includes('∩')) return parsed.raw;
-  const parts = [];
-  if (parsed.min) parts.push(`${parsed.min.op}${parsed.min.v}`);
-  if (parsed.max) parts.push(`${parsed.max.op}${parsed.max.v}`);
-  return parts.join(' ');
-}
-
-/**
- * Convenience predicate used by the resolver: does this spec require
- * range-based resolution (as opposed to exact / latest / linked)?
- */
-function isRangeSpec(spec) {
-  try {
-    const parsed = parseRange(spec);
-    return parsed.kind === 'range';
-  } catch { return false; }
-}
-
-module.exports = {
-  parseRange,
-  matchesRange,
-  pickHighestInRange,
-  intersectRanges,
-  rangeToString,
-  isRangeSpec,
-  compareVersions,
-};
+'use strict';
+
+/**
+ * Version range parsing and matching for 4-part `major.minor.patch.build`
+ * versions.
+ *
+ * Accepts three range syntaxes in addition to the existing exact and
+ * `"latest"` strings:
+ *
+ *   "^1.2.3.4"        major-pinned  : >= 1.2.3.4  <  2.0.0.0
+ *   "~1.2.3.4"        minor-pinned  : >= 1.2.3.4  <  1.3.0.0
+ *   ">=1.2.3.4 <2.0"  explicit      : one or more space-separated comparators
+ *                                     among >=, >, <=, <, =
+ *
+ * `parseRange(s)` classifies the input; `matchesRange(v, parsed)`
+ * evaluates a candidate version; `pickHighestInRange(versions, parsed)`
+ * selects the best match; `intersectRanges(a, b)` combines two ranges
+ * (returns null when the intersection is empty).
+ *
+ * See claude/PLAN-VERSION-RANGES.md for the full design.
+ */
+
+const VERSION_RE = /^\d+\.\d+\.\d+\.\d+$/;
+
+/**
+ * Compare two 4-part versions numerically. Missing trailing components
+ * default to 0 so `compareVersions("1.2", "1.2.0.0") === 0`, though the
+ * parser elsewhere always emits fully-qualified 4-part strings.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1|0|1}
+ */
+function compareVersions(a, b) {
+  const partsOf = (s) => s.split('.').map((n) => parseInt(n, 10) || 0);
+  const pa = partsOf(a);
+  const pb = partsOf(b);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+function bumpMajor(v) {
+  const [maj] = v.split('.').map((n) => parseInt(n, 10) || 0);
+  return `${maj + 1}.0.0.0`;
+}
+
+function bumpMinor(v) {
+  const [maj, min] = v.split('.').map((n) => parseInt(n, 10) || 0);
+  return `${maj}.${min + 1}.0.0`;
+}
+
+/**
+ * Parse a dependency version string into a structured spec. Exact versions
+ * and `"latest"` pass through unchanged; `^` / `~` / comparator strings
+ * become `{ kind: 'range', min, max }` specs.
+ *
+ * `min` and `max` are each `{ op: '>=' | '>' | null, v: string } | null`
+ * (null means unbounded on that side — an open upper bound, etc.).
+ *
+ * Throws on malformed input with a user-friendly multi-line error that
+ * lists the supported syntaxes.
+ *
+ * @param {string} spec
+ * @returns {{ kind: 'exact', version: string }
+ *         | { kind: 'tag',   tag:    'latest' }
+ *         | { kind: 'range', raw: string,
+ *             min: { op: '>='|'>', v: string } | null,
+ *             max: { op: '<='|'<', v: string } | null,
+ *             exact?: string }}
+ */
+function parseRange(spec) {
+  if (typeof spec !== 'string' || spec.length === 0) {
+    throw new Error(malformedRangeMessage(spec, 'version spec must be a non-empty string'));
+  }
+  const s = spec.trim();
+
+  if (s === 'latest') return { kind: 'tag', tag: 'latest' };
+
+  // `linked:` is handled by resolve.js directly — not our concern.
+  if (s.startsWith('linked:')) return { kind: 'linked', raw: s };
+
+  if (VERSION_RE.test(s)) return { kind: 'exact', version: s };
+
+  // Caret / tilde — require a full 4-part version as the operand.
+  if (s[0] === '^' || s[0] === '~') {
+    const op = s[0];
+    const v  = s.slice(1).trim();
+    if (!VERSION_RE.test(v)) {
+      throw new Error(malformedRangeMessage(spec, `${op} prefix requires a 4-part version`));
+    }
+    return {
+      kind: 'range',
+      raw:  s,
+      min:  { op: '>=', v },
+      max:  { op: '<',  v: op === '^' ? bumpMajor(v) : bumpMinor(v) },
+    };
+  }
+
+  // Explicit comparator form: one or more of {>=, >, <=, <, =} each followed
+  // by a 4-part version, space-separated.
+  if (/^[<>=]/.test(s)) {
+    const tokens = s.split(/\s+/);
+    let min = null;
+    let max = null;
+    let exact = null;
+    for (const tok of tokens) {
+      const m = tok.match(/^(>=|<=|>|<|=)(\d+\.\d+\.\d+\.\d+)$/);
+      if (!m) {
+        throw new Error(malformedRangeMessage(spec, `unrecognised comparator "${tok}"`));
+      }
+      const [, op, v] = m;
+      if (op === '=') {
+        if (exact && exact !== v) {
+          throw new Error(malformedRangeMessage(spec, `conflicting = comparators (${exact} vs ${v})`));
+        }
+        exact = v;
+      } else if (op === '>=' || op === '>') {
+        if (!min || compareVersions(v, min.v) > 0 || (compareVersions(v, min.v) === 0 && op === '>')) {
+          min = { op, v };
+        }
+      } else {
+        if (!max || compareVersions(v, max.v) < 0 || (compareVersions(v, max.v) === 0 && op === '<')) {
+          max = { op, v };
+        }
+      }
+    }
+    if (exact) return { kind: 'exact', version: exact };
+    if (!min && !max) {
+      throw new Error(malformedRangeMessage(spec, 'no comparators parsed'));
+    }
+    return { kind: 'range', raw: s, min, max };
+  }
+
+  throw new Error(malformedRangeMessage(spec, 'unknown version syntax'));
+}
+
+function malformedRangeMessage(spec, why) {
+  return (
+    `cannot parse dependency version ${JSON.stringify(spec)}: ${why}\n` +
+    `  supported syntaxes:\n` +
+    `    "1.2.3.4"                    exact version\n` +
+    `    "latest"                     latest-published tag\n` +
+    `    "^1.2.3.4"                   major-pinned range (>= 1.2.3.4 < 2.0.0.0)\n` +
+    `    "~1.2.3.4"                   minor-pinned range (>= 1.2.3.4 < 1.3.0.0)\n` +
+    `    ">=1.2.3.4 <2.0.0.0"         explicit range (>=, >, <=, <, = separated by spaces)`
+  );
+}
+
+/**
+ * Returns true if `version` satisfies every bound in `parsed`. Exact-kind
+ * specs require byte-equal; tag/linked specs always return false here
+ * because they are handled upstream.
+ *
+ * @param {string} version
+ * @param {ReturnType<typeof parseRange>} parsed
+ * @returns {boolean}
+ */
+function matchesRange(version, parsed) {
+  if (!parsed) return false;
+  if (parsed.kind === 'exact') return version === parsed.version;
+  if (parsed.kind !== 'range') return false;
+  if (parsed.min) {
+    const cmp = compareVersions(version, parsed.min.v);
+    if (parsed.min.op === '>=' && cmp < 0) return false;
+    if (parsed.min.op === '>'  && cmp <= 0) return false;
+  }
+  if (parsed.max) {
+    const cmp = compareVersions(version, parsed.max.v);
+    if (parsed.max.op === '<=' && cmp > 0) return false;
+    if (parsed.max.op === '<'  && cmp >= 0) return false;
+  }
+  return true;
+}
+
+/**
+ * Pick the highest version from `publishedVersions` that satisfies
+ * `parsed`. Returns null when no version matches. Input is not mutated.
+ *
+ * @param {string[]} publishedVersions
+ * @param {ReturnType<typeof parseRange>} parsed
+ * @returns {string|null}
+ */
+function pickHighestInRange(publishedVersions, parsed) {
+  if (!Array.isArray(publishedVersions) || publishedVersions.length === 0) return null;
+  const matches = publishedVersions.filter((v) => matchesRange(v, parsed));
+  if (matches.length === 0) return null;
+  matches.sort(compareVersions);
+  return matches[matches.length - 1];
+}
+
+/**
+ * Intersect two parsed range specs. Exact specs are treated as the degenerate
+ * range `[v, v]`. Returns a new range spec or null when the intersection is
+ * empty.
+ *
+ * `tag` and `linked` kinds cannot participate in intersection — the caller
+ * must resolve them to exact first. We throw rather than silently ignore.
+ *
+ * @param {ReturnType<typeof parseRange>} a
+ * @param {ReturnType<typeof parseRange>} b
+ * @returns {{ kind: 'range'|'exact', ... }|null}
+ */
+function intersectRanges(a, b) {
+  const liftExact = (spec) => spec.kind === 'exact'
+    ? { kind: 'range', raw: spec.version, min: { op: '>=', v: spec.version }, max: { op: '<=', v: spec.version } }
+    : spec;
+
+  if (!a || !b) throw new Error('intersectRanges: null spec');
+  if (a.kind === 'tag' || a.kind === 'linked' || b.kind === 'tag' || b.kind === 'linked') {
+    throw new Error('intersectRanges: tag/linked must be resolved before intersection');
+  }
+
+  const ra = liftExact(a);
+  const rb = liftExact(b);
+
+  // Tighter min (higher value; strictly-greater beats equal under gte).
+  const tighterMin = pickTighter(ra.min, rb.min, 'min');
+  // Tighter max (lower value; strictly-less beats equal under lte).
+  const tighterMax = pickTighter(ra.max, rb.max, 'max');
+
+  if (tighterMin && tighterMax) {
+    const cmp = compareVersions(tighterMin.v, tighterMax.v);
+    if (cmp > 0) return null;
+    if (cmp === 0) {
+      // Both bounds reference the same version. Feasible only if both are
+      // inclusive; otherwise the point is excluded.
+      if (tighterMin.op !== '>=' || tighterMax.op !== '<=') return null;
+      return { kind: 'exact', version: tighterMin.v };
+    }
+  }
+
+  return {
+    kind: 'range',
+    raw:  `${ra.raw ?? 'range'} ∩ ${rb.raw ?? 'range'}`,
+    min:  tighterMin,
+    max:  tighterMax,
+  };
+}
+
+function pickTighter(a, b, kind) {
+  if (!a) return b;
+  if (!b) return a;
+  const cmp = compareVersions(a.v, b.v);
+  if (kind === 'min') {
+    if (cmp > 0) return a;
+    if (cmp < 0) return b;
+    // equal: strictly-greater is tighter than gte
+    return a.op === '>' ? a : b;
+  } else {
+    if (cmp < 0) return a;
+    if (cmp > 0) return b;
+    return a.op === '<' ? a : b;
+  }
+}
+
+/**
+ * Human-readable rendering for error messages. Exact and tag kinds pass
+ * through unchanged; ranges render as the original raw string when
+ * available, else as a comparator reconstruction.
+ *
+ * @param {ReturnType<typeof parseRange>} parsed
+ * @returns {string}
+ */
+function rangeToString(parsed) {
+  if (!parsed) return '(unparsed)';
+  if (parsed.kind === 'exact') return parsed.version;
+  if (parsed.kind === 'tag')   return parsed.tag;
+  if (parsed.kind === 'linked') return parsed.raw;
+  if (parsed.raw && !parsed.raw.includes('∩')) return parsed.raw;
+  const parts = [];
+  if (parsed.min) parts.push(`${parsed.min.op}${parsed.min.v}`);
+  if (parsed.max) parts.push(`${parsed.max.op}${parsed.max.v}`);
+  return parts.join(' ');
+}
+
+/**
+ * Convenience predicate used by the resolver: does this spec require
+ * range-based resolution (as opposed to exact / latest / linked)?
+ */
+function isRangeSpec(spec) {
+  try {
+    const parsed = parseRange(spec);
+    return parsed.kind === 'range';
+  } catch { return false; }
+}
+
+module.exports = {
+  parseRange,
+  matchesRange,
+  pickHighestInRange,
+  intersectRanges,
+  rangeToString,
+  isRangeSpec,
+  compareVersions,
+};