From e5ba18248d66529380ecc831630964abbb99f300 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Sun, 11 Jan 2026 18:59:28 +0000
Subject: [PATCH] docs: improve JSDoc for version comparison methods

- Update `isAtLeast`, `isAbove`, `isBelow`, `isAtMost` JSDoc to explicitly state they return `false` for invalid version strings.
- Update `is` JSDoc to explicitly warn about strict equality and lack of input normalization.
- Add journal entry in `.jules/palette.md` regarding API consistency learning.
---
 .jules/palette.md | 3 +++
 src/types.ts      | 9 +++++----
 2 files changed, 8 insertions(+), 4 deletions(-)
 create mode 100644 .jules/palette.md

diff --git a/.jules/palette.md b/.jules/palette.md
new file mode 100644
index 00000000..48ecf14f
--- /dev/null
+++ b/.jules/palette.md
@@ -0,0 +1,3 @@
+## 2026-01-03 - [API Consistency Trap]
+**Learning:** Inconsistent strictness in API methods (`is` vs `isAtLeast`) creates a hidden trap for users. `isAtLeast` normalizes inputs (strips 'v'), but `is` uses strict equality without normalization.
+**Action:** Explicitly document strictness in JSDoc to warn users and clarify invalid input behavior.
diff --git a/src/types.ts b/src/types.ts
index 4de06674..4ce5c46c 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -35,13 +35,14 @@ 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 performs a strict equality check and does not normalize the input (e.g., 'v20.0.0' != '20.0.0').
      * @param version The version to compare against (e.g., '20.0.0').
      * @returns {boolean} True if current version === target version.
      * @example
@@ -51,7 +52,7 @@ 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
      */
@@ -59,7 +60,7 @@ export interface NodeVersion {
     /**
      * 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
      */
@@ -67,7 +68,7 @@ export interface NodeVersion {
     /**
      * 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
      */