@credentum/semver-explain 0.0.1

package/README.md

@@ -0,0 +1,83 @@
+# semver-explain
+
+Explain semver ranges in plain English. The `cronstrue` for version constraints.
+
+```typescript
+import { explain } from '@credentum/semver-explain';
+
+explain('^1.2.3');
+// => ">=1.2.3 <2.0.0 — Compatible with 1.2.3, allowing minor and patch updates"
+
+explain('~1.2.3');
+// => ">=1.2.3 <1.3.0 — Approximately 1.2.3, allowing only patch updates"
+
+explain('1.2.x');
+// => ">=1.2.0 <1.3.0 — Any patch version within 1.2"
+
+explain('>=1.0.0 <2.0.0');
+// => ">=1.0.0 and <2.0.0"
+
+explain('^1.2.3 || ^2.0.0');
+// => ">=1.2.3 <2.0.0 — Compatible with 1.2.3 | OR | >=2.0.0 <3.0.0 — Compatible with 2.0.0"
+```
+
+## Installation
+
+```bash
+npm install @credentum/semver-explain
+```
+
+## Why?
+
+Every team using npm encounters semver ranges. The `^` and `~` operators are unintuitive — even experienced developers confuse them. The answer is always a StackOverflow search:
+
+- ["What's the difference between tilde(~) and caret(^)?"](https://stackoverflow.com/questions/22343224) — **2.1M views**
+- ["What does ^0.0.1 mean?"](https://stackoverflow.com/questions/22137778) — 200K+ views
+- `semver` on npm — 498M weekly downloads, but no explain function
+
+`cronstrue` converts cron to English (3.5M/week). No equivalent exists for semver. Until now.
+
+## API
+
+### `explain(range: string): string`
+
+Converts a semver range string into a human-readable English explanation.
+
+**Supports all npm semver range syntax:**
+
+| Input | Output |
+|-------|--------|
+| `1.2.3` | `1.2.3 — Exactly version 1.2.3` |
+| `^1.2.3` | `>=1.2.3 <2.0.0 — Compatible with 1.2.3, allowing minor and patch updates` |
+| `^0.2.3` | `>=0.2.3 <0.3.0 — Compatible with 0.2.3, allowing only patch updates` |
+| `^0.0.3` | `>=0.0.3 <0.0.4 — Only version 0.0.3 (caret on 0.0.x is exact)` |
+| `~1.2.3` | `>=1.2.3 <1.3.0 — Approximately 1.2.3, allowing only patch updates` |
+| `~1.2` | `>=1.2.0 <1.3.0 — Any patch version within 1.2` |
+| `~0.2` | `>=0.2.0 <0.3.0 — Any patch version within 0.2` |
+| `1.x` | `>=1.0.0 <2.0.0 — Any version starting with 1` |
+| `1.2.x` | `>=1.2.0 <1.3.0 — Any patch version within 1.2` |
+| `*` | `Any version` |
+| `>=1.2.3` | `>=1.2.3` |
+| `1.2.3 - 2.3.4` | `>=1.2.3 <=2.3.4 — Between 1.2.3 and 2.3.4, inclusive` |
+| `>=1.0.0 <2.0.0` | `>=1.0.0 and <2.0.0` |
+| `^1 \|\| ^2` | Explains each branch separated by ` \| OR \| ` |
+
+### `expandRange(range: string): string`
+
+Returns only the expanded comparator form without the English description. Useful for tooling.
+
+```typescript
+import { expandRange } from '@credentum/semver-explain';
+
+expandRange('^1.2.3');  // ">=1.2.3 <2.0.0"
+expandRange('~1.2.3');  // ">=1.2.3 <1.3.0"
+expandRange('1.2.x');   // ">=1.2.0 <1.3.0"
+```
+
+## Zero Dependencies
+
+Pure TypeScript. No dependency on the `semver` package. Implements range expansion from the [node-semver specification](https://github.com/npm/node-semver#ranges) directly.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * semver-explain — Explain semver ranges in plain English.
+ * Zero dependencies. Pure functions.
+ *
+ * Implements range expansion per the node-semver specification:
+ * https://github.com/npm/node-semver#ranges
+ */
+/**
+ * Explain a semver range in plain English.
+ *
+ * Supports all npm semver range syntax:
+ * - Exact: 1.2.3
+ * - Caret: ^1.2.3
+ * - Tilde: ~1.2.3
+ * - X-ranges: 1.x, 1.2.*, *
+ * - Hyphen: 1.2.3 - 2.3.4
+ * - Comparators: >=1.0.0, <2.0.0
+ * - Compound: >=1.0.0 <2.0.0
+ * - Union: ^1 || ^2
+ *
+ * @param range - A semver range string
+ * @returns Human-readable explanation
+ */
+export declare function explain(range: string): string;
+/**
+ * Return only the expanded comparator form, without the English description.
+ *
+ * @param range - A semver range string
+ * @returns Expanded comparator string (e.g. ">=1.2.3 <2.0.0")
+ */
+export declare function expandRange(range: string): string;

package/index.js

@@ -0,0 +1,363 @@
+/**
+ * semver-explain — Explain semver ranges in plain English.
+ * Zero dependencies. Pure functions.
+ *
+ * Implements range expansion per the node-semver specification:
+ * https://github.com/npm/node-semver#ranges
+ */
+/**
+ * Parse a version string like "1.2.3" into a Version object.
+ * Missing components default to 0.
+ */
+function parseVersion(v) {
+    const parts = v.split(".");
+    return {
+        major: parseInt(parts[0], 10) || 0,
+        minor: parts.length > 1 ? parseInt(parts[1], 10) || 0 : 0,
+        patch: parts.length > 2 ? parseInt(parts[2], 10) || 0 : 0,
+    };
+}
+/** Format a Version back to string */
+function fmt(v) {
+    return `${v.major}.${v.minor}.${v.patch}`;
+}
+/** Count how many numeric parts were provided (1, 2, or 3) */
+function partCount(v) {
+    const stripped = v.replace(/^[v=\s]+/, "");
+    return stripped.split(".").length;
+}
+/**
+ * Expand a caret range (^) to its comparator bounds.
+ *
+ * Per node-semver spec:
+ * - ^1.2.3  => >=1.2.3 <2.0.0  (leftmost non-zero is major)
+ * - ^0.2.3  => >=0.2.3 <0.3.0  (leftmost non-zero is minor)
+ * - ^0.0.3  => >=0.0.3 <0.0.4  (leftmost non-zero is patch)
+ * - ^1.2.x  => >=1.2.0 <2.0.0
+ * - ^0.0.x  => >=0.0.0 <0.1.0
+ * - ^0.0    => >=0.0.0 <0.1.0
+ * - ^1.x    => >=1.0.0 <2.0.0
+ * - ^0.x    => >=0.0.0 <1.0.0
+ */
+function expandCaret(raw) {
+    const body = raw.replace(/^[v=\s]+/, "");
+    const parts = body.split(".");
+    const hasX = parts.some((p) => p === "x" || p === "X" || p === "*");
+    const numParts = parts.length;
+    // Replace x/X/* with 0 for parsing
+    const cleaned = parts.map((p) => p === "x" || p === "X" || p === "*" ? "0" : p);
+    const major = parseInt(cleaned[0], 10) || 0;
+    const minor = numParts > 1 ? parseInt(cleaned[1], 10) || 0 : 0;
+    const patch = numParts > 2 ? parseInt(cleaned[2], 10) || 0 : 0;
+    const lower = `${major}.${minor}.${patch}`;
+    let upper;
+    let description;
+    if (major !== 0) {
+        upper = `${major + 1}.0.0`;
+        if (minor === 0 && patch === 0) {
+            description = `Compatible with ${major}.x, allowing minor and patch updates`;
+        }
+        else {
+            description = `Compatible with ${lower}, allowing minor and patch updates`;
+        }
+    }
+    else if (minor !== 0) {
+        upper = `0.${minor + 1}.0`;
+        description = `Compatible with ${lower}, allowing only patch updates`;
+    }
+    else if (patch !== 0 && !hasX) {
+        upper = `0.0.${patch + 1}`;
+        description = `Only version ${lower} (caret on 0.0.x is exact)`;
+    }
+    else if (hasX && numParts >= 2 && cleaned[1] === "0") {
+        // ^0.0.x or ^0.0
+        upper = "0.1.0";
+        description = `Any patch version within 0.0`;
+    }
+    else if (hasX || numParts === 1) {
+        upper = `${major + 1}.0.0`;
+        description = `Any version starting with ${major}`;
+    }
+    else {
+        // ^0.0.0
+        upper = "0.1.0";
+        description = `Any patch version within 0.0`;
+    }
+    return { lower, upper, description };
+}
+/**
+ * Expand a tilde range (~) to its comparator bounds.
+ *
+ * Per node-semver spec:
+ * - ~1.2.3  => >=1.2.3 <1.3.0  (patch-level changes allowed)
+ * - ~1.2    => >=1.2.0 <1.3.0  (same as 1.2.x)
+ * - ~1      => >=1.0.0 <2.0.0  (same as 1.x)
+ * - ~0.2.3  => >=0.2.3 <0.3.0
+ */
+function expandTilde(raw) {
+    const body = raw.replace(/^[v=\s]+/, "");
+    const parts = body.split(".");
+    const numParts = parts.length;
+    const major = parseInt(parts[0], 10) || 0;
+    const minor = numParts > 1 ? parseInt(parts[1], 10) || 0 : 0;
+    const patch = numParts > 2 ? parseInt(parts[2], 10) || 0 : 0;
+    const lower = `${major}.${minor}.${patch}`;
+    if (numParts === 1) {
+        // ~1 => >=1.0.0 <2.0.0
+        return {
+            lower,
+            upper: `${major + 1}.0.0`,
+            description: `Any version starting with ${major}`,
+        };
+    }
+    // ~1.2.3 or ~1.2 => >=1.2.x <1.3.0
+    const upper = `${major}.${minor + 1}.0`;
+    if (patch === 0) {
+        return {
+            lower,
+            upper,
+            description: `Any patch version within ${major}.${minor}`,
+        };
+    }
+    return {
+        lower,
+        upper,
+        description: `Approximately ${lower}, allowing only patch updates`,
+    };
+}
+/**
+ * Expand an x-range (1.x, 1.2.x, *, x) to its comparator bounds.
+ */
+function expandXRange(raw) {
+    const body = raw.replace(/^[v=\s]+/, "").trim();
+    // Pure wildcard
+    if (body === "*" || body === "x" || body === "X" || body === "") {
+        return { lower: "", upper: "", description: "Any version" };
+    }
+    const parts = body.split(".");
+    const major = parseInt(parts[0], 10);
+    if (isNaN(major)) {
+        return { lower: "", upper: "", description: "Any version" };
+    }
+    // 1.x or 1.*
+    if (parts.length === 1 ||
+        (parts.length >= 2 &&
+            (parts[1] === "x" || parts[1] === "X" || parts[1] === "*"))) {
+        return {
+            lower: `${major}.0.0`,
+            upper: `${major + 1}.0.0`,
+            description: `Any version starting with ${major}`,
+        };
+    }
+    // 1.2.x or 1.2.*
+    const minor = parseInt(parts[1], 10) || 0;
+    if (parts.length >= 3 &&
+        (parts[2] === "x" || parts[2] === "X" || parts[2] === "*")) {
+        return {
+            lower: `${major}.${minor}.0`,
+            upper: `${major}.${minor + 1}.0`,
+            description: `Any patch version within ${major}.${minor}`,
+        };
+    }
+    // Shouldn't reach here, but handle gracefully
+    return {
+        lower: `${major}.${minor}.0`,
+        upper: `${major}.${minor + 1}.0`,
+        description: `Any patch version within ${major}.${minor}`,
+    };
+}
+/**
+ * Expand a hyphen range (A - B) to its comparator bounds.
+ *
+ * Per node-semver spec:
+ * - 1.2.3 - 2.3.4  => >=1.2.3 <=2.3.4
+ * - 1.2 - 2.3.4    => >=1.2.0 <=2.3.4
+ * - 1.2.3 - 2.3    => >=1.2.3 <2.4.0
+ * - 1.2.3 - 2      => >=1.2.3 <3.0.0
+ */
+function expandHyphen(left, right) {
+    const lBody = left.replace(/^[v=\s]+/, "").trim();
+    const rBody = right.replace(/^[v=\s]+/, "").trim();
+    const lv = parseVersion(lBody);
+    const rv = parseVersion(rBody);
+    const rParts = partCount(rBody);
+    const lower = fmt(lv);
+    if (rParts === 3) {
+        // Full version on right: inclusive upper bound
+        return {
+            expanded: `>=${lower} <=${fmt(rv)}`,
+            description: `Between ${lower} and ${fmt(rv)}, inclusive`,
+        };
+    }
+    // Partial version on right: exclusive upper bound on next increment
+    let upper;
+    if (rParts === 2) {
+        upper = `${rv.major}.${rv.minor + 1}.0`;
+    }
+    else {
+        upper = `${rv.major + 1}.0.0`;
+    }
+    return {
+        expanded: `>=${lower} <${upper}`,
+        description: `Between ${lower} and ${rBody}`,
+    };
+}
+/**
+ * Check if a string is a simple comparator (>=, <=, >, <, =).
+ */
+function isComparator(token) {
+    return /^(>=|<=|>|<|=)\s*\d/.test(token.trim());
+}
+/**
+ * Explain a single simple range (no OR unions).
+ * This handles: exact, caret, tilde, x-range, hyphen, and comparators.
+ */
+function explainSimple(range) {
+    const trimmed = range.trim();
+    if (trimmed === "" || trimmed === "*") {
+        return "Any version";
+    }
+    // Hyphen range: "A - B"
+    const hyphenMatch = trimmed.match(/^([v=\s]*[\dx.*X]+(?:\.[\dx.*X]+)*)\s+-\s+([v=\s]*[\dx.*X]+(?:\.[\dx.*X]+)*)$/);
+    if (hyphenMatch) {
+        const { expanded, description } = expandHyphen(hyphenMatch[1], hyphenMatch[2]);
+        return `${expanded} \u2014 ${description}`;
+    }
+    // Caret range
+    if (trimmed.startsWith("^")) {
+        const body = trimmed.slice(1);
+        const { lower, upper, description } = expandCaret(body);
+        return `>=${lower} <${upper} \u2014 ${description}`;
+    }
+    // Tilde range
+    if (trimmed.startsWith("~")) {
+        const body = trimmed.slice(1);
+        const { lower, upper, description } = expandTilde(body);
+        return `>=${lower} <${upper} \u2014 ${description}`;
+    }
+    // X-range (contains x, X, or * in version parts)
+    if (/[xX*]/.test(trimmed) || /^\d+$/.test(trimmed)) {
+        // Single number like "1" is treated as 1.x.x
+        if (/^\d+$/.test(trimmed)) {
+            const major = parseInt(trimmed, 10);
+            return `>=${major}.0.0 <${major + 1}.0.0 \u2014 Any version starting with ${major}`;
+        }
+        const { lower, upper, description } = expandXRange(trimmed);
+        if (lower === "" && upper === "") {
+            return description;
+        }
+        return `>=${lower} <${upper} \u2014 ${description}`;
+    }
+    // Compound comparators (space-separated, e.g. ">=1.0.0 <2.0.0")
+    const tokens = trimmed.split(/\s+/);
+    if (tokens.length > 1 && tokens.every((t) => isComparator(t))) {
+        return tokens.join(" and ");
+    }
+    // Single comparator (>=, <=, >, <, =)
+    if (isComparator(trimmed)) {
+        const normalized = trimmed.replace(/^=\s*/, "");
+        if (trimmed.startsWith("=")) {
+            return `${normalized} \u2014 Exactly version ${normalized}`;
+        }
+        return trimmed;
+    }
+    // Exact version (e.g. "1.2.3")
+    if (/^\d+\.\d+\.\d+/.test(trimmed)) {
+        return `${trimmed} \u2014 Exactly version ${trimmed}`;
+    }
+    // Partial version without x (e.g. "1.2")
+    if (/^\d+\.\d+$/.test(trimmed)) {
+        const major = parseInt(trimmed.split(".")[0], 10);
+        const minor = parseInt(trimmed.split(".")[1], 10);
+        return `>=${major}.${minor}.0 <${major}.${minor + 1}.0 \u2014 Any patch version within ${trimmed}`;
+    }
+    // Fallback: return as-is
+    return trimmed;
+}
+/**
+ * Explain a semver range in plain English.
+ *
+ * Supports all npm semver range syntax:
+ * - Exact: 1.2.3
+ * - Caret: ^1.2.3
+ * - Tilde: ~1.2.3
+ * - X-ranges: 1.x, 1.2.*, *
+ * - Hyphen: 1.2.3 - 2.3.4
+ * - Comparators: >=1.0.0, <2.0.0
+ * - Compound: >=1.0.0 <2.0.0
+ * - Union: ^1 || ^2
+ *
+ * @param range - A semver range string
+ * @returns Human-readable explanation
+ */
+export function explain(range) {
+    if (typeof range !== "string") {
+        return "Invalid range";
+    }
+    const trimmed = range.trim();
+    if (trimmed === "") {
+        return "Any version";
+    }
+    // Split on || for OR unions
+    const branches = trimmed.split(/\s*\|\|\s*/);
+    if (branches.length === 1) {
+        return explainSimple(branches[0]);
+    }
+    // Multiple branches: explain each, join with OR
+    return branches.map((b) => explainSimple(b)).join(" | OR | ");
+}
+/**
+ * Return only the expanded comparator form, without the English description.
+ *
+ * @param range - A semver range string
+ * @returns Expanded comparator string (e.g. ">=1.2.3 <2.0.0")
+ */
+export function expandRange(range) {
+    if (typeof range !== "string") {
+        return "Invalid range";
+    }
+    const trimmed = range.trim();
+    if (trimmed === "" || trimmed === "*") {
+        return "*";
+    }
+    // Split on || for OR unions
+    const branches = trimmed.split(/\s*\|\|\s*/);
+    const expanded = branches.map((branch) => {
+        const b = branch.trim();
+        // Hyphen range
+        const hyphenMatch = b.match(/^([v=\s]*[\dx.*X]+(?:\.[\dx.*X]+)*)\s+-\s+([v=\s]*[\dx.*X]+(?:\.[\dx.*X]+)*)$/);
+        if (hyphenMatch) {
+            return expandHyphen(hyphenMatch[1], hyphenMatch[2]).expanded;
+        }
+        // Caret
+        if (b.startsWith("^")) {
+            const { lower, upper } = expandCaret(b.slice(1));
+            return `>=${lower} <${upper}`;
+        }
+        // Tilde
+        if (b.startsWith("~")) {
+            const { lower, upper } = expandTilde(b.slice(1));
+            return `>=${lower} <${upper}`;
+        }
+        // X-range
+        if (/[xX*]/.test(b)) {
+            const { lower, upper } = expandXRange(b);
+            if (lower === "" && upper === "")
+                return "*";
+            return `>=${lower} <${upper}`;
+        }
+        // Single number (1 => 1.x.x)
+        if (/^\d+$/.test(b)) {
+            const major = parseInt(b, 10);
+            return `>=${major}.0.0 <${major + 1}.0.0`;
+        }
+        // Partial version (1.2 => 1.2.x)
+        if (/^\d+\.\d+$/.test(b)) {
+            const [maj, min] = b.split(".").map(Number);
+            return `>=${maj}.${min}.0 <${maj}.${min + 1}.0`;
+        }
+        // Already a comparator or exact version
+        return b;
+    });
+    return expanded.join(" || ");
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@credentum/semver-explain",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Explain semver ranges in plain English. The cronstrue for version constraints.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "keywords": [
+    "semver",
+    "explain",
+    "human-readable",
+    "version",
+    "range",
+    "caret",
+    "tilde",
+    "npm",
+    "package.json"
+  ],
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}