🎨 Palette: Improve JSDoc for version comparison methods

.changeset/palette-jsdoc-fix.md

@@ -0,0 +1,5 @@
+---
+"node-version": patch
+---
+
+Improve JSDoc for version comparison methods to clarify input validation and return values.

.jules/palette.md

@@ -0,0 +1,3 @@
+## 2026-01-03 - API Consistency and Documentation
+**Learning:** In this library, the `is()` comparison method performs strict equality checks (expecting exact matches) while other methods like `isAtLeast()` normalize inputs (handling 'v' prefixes). This inconsistency is a potential "gotcha" for developers consuming the API.
+**Action:** When designing or maintaining API surfaces with comparison logic, ensure consistent input handling across all methods, or explicitly document deviations in JSDoc to prevent developer confusion.

src/types.ts

@@ -35,13 +35,17 @@ export interface NodeVersion {
     /**
      * Check if the current Node version is at least the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version >= target version.
+     * @returns {boolean} True if current version >= target version. Returns false for invalid version strings.
      * @example
      * version.isAtLeast('18.0.0'); // true if current is 20.0.0
      */
     isAtLeast(version: string): boolean;
     /**
      * Check if the current Node version matches the specified version.
+     *
+     * @note This method performs a strict string comparison and does not normalize the input
+     * (e.g., it does not strip 'v' prefixes).
+     *
      * @param version The version to compare against (e.g., '20.0.0').
      * @returns {boolean} True if current version === target version.
      * @example
@@ -51,23 +55,23 @@ export interface NodeVersion {
     /**
      * Check if the current Node version is strictly greater than the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version > target version.
+     * @returns {boolean} True if current version > target version. Returns false for invalid version strings.
      * @example
      * version.isAbove('18.0.0'); // true if current is 20.0.0
      */
     isAbove(version: string): boolean;
     /**
      * Check if the current Node version is strictly less than the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version < target version.
+     * @returns {boolean} True if current version < target version. Returns false for invalid version strings.
      * @example
      * version.isBelow('22.0.0'); // true if current is 20.0.0
      */
     isBelow(version: string): boolean;
     /**
      * Check if the current Node version is at most the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version <= target version.
+     * @returns {boolean} True if current version <= target version. Returns false for invalid version strings.
      * @example
      * version.isAtMost('22.0.0'); // true if current is 20.0.0
      */