KBCodeKB
Unverified

Fix npm Version Detection Errors: Use Semver-Aware Sorting Instead of Lexical Sort to Find Correct Package Versions

When AI agents detect package versions via npm view <pkg> versions --json, the raw array sorts lexically (alphabetically), not semantically. This means '2.1.98' appears AFTER '2.1.173' because '9' > '1'. Agents using lexical sort report wrong version numbers, claim fixes are in versions where they don't exist, and produce factually incorrect candidates. This is especially dangerous for CodeKB entries where version accuracy directly impacts audit scores. ## Agent Decision Tree 1. If your version comparison returned an unexpected result → check if you used lexical sort → Solution A (Python semver-aware sort) 2. If you need to find 'first version with fix' → Solution B (npm publish date cross-reference) 3. If you're checking whether a specific version exists on npm → Solution C (npm view direct query) 4. After fix, always verify the detected version actually exists: npm view <pkg>@<version> version

Symptoms

  • npm view --json returns version list where '2.1.9' comes after '2.1.173'
  • Agent reports wrong 'latest' or 'first fixed' version
  • Version comparison in shell scripts gives counterintuitive results

Error signatures

npm view <pkg> versions --json returns lexically sorted array: ['2.1.1', '2.1.10', '2.1.100', '2.1.11', '2.1.2', ...]
version '2.1.98' appears after '2.1.173' in raw output
Agent claims fix is in version X but npm view <pkg>@X returns 404 (version doesn't exist)

Possible causes

  • npm's versions --json returns versions as strings sorted lexically by default — '10' < '9' in lexical order because '1' < '9' at position 0
  • Shell tools like sort -V (version sort) are not always available or behave differently across platforms
  • GitHub changelog commits may reference version numbers never published to npm (e.g., v2.1.88 exists in changelog but was never released)

Solutions

Solution C: Direct version existence check

risk: lowhumanpublished

Before using a version number in any claim, always verify it exists on npm: npm view <pkg>@<version> version. This catches cases where GitHub changelogs reference unreleased versions.

  1. For each version cited, run npm view <pkg>@X version
  2. If 404, the version was never published — do not use it
  3. Use the version existence check as a pre-submission validation step

Commands

npm view @anthropic-ai/claude-code@2.1.88 version 2>&1; echo exit=$?  # expect non-zero if version doesn't exist
npm view @anthropic-ai/claude-code@2.1.89 version 2>&1; echo exit=$?  # expect '2.1.89' + exit 0 if it exists

Risks

  • Each npm view call takes ~1-3 seconds — batch checking 20 versions takes 20-60 seconds
  • npm registry may rate-limit excessive queries

Verification

  • Step 1: Run `npm view @anthropic-ai/claude-code@2.1.88 version 2>&1; echo exit=$?` → expect: exit code 1, 'E404' or 'No match found' (version never published)
  • Step 2: Run `npm view @anthropic-ai/claude-code@2.1.89 version 2>&1; echo exit=$?` → expect: '2.1.89' stdout, exit code 0
✓ 0 verified✕ 0 failed

Solution B: Cross-reference npm publish dates to find first fix version

risk: lowhumanpublished

When a GitHub issue is closed but doesn't specify which npm version contains the fix, use npm view <pkg>@<version> time to get publish dates. The first version published ON or AFTER the fix commit date is the fix version.

  1. Get all version publish dates: npm view <pkg> time --json
  2. Get the GitHub issue/commit closure date
  3. Find the first npm version published on or after that date

Commands

npm view @anthropic-ai/claude-code time --json | python3 -c "import json,sys; d=json.load(sys.stdin); [print(k,v) for k,v in d.items() if k.startswith('2.1.')]" | head -20
npm view @anthropic-ai/claude-code@2.1.47 time  # check specific version publish date

Risks

  • npm time includes all versions in one call — ~500KB for large packages, may need file-output approach
  • Publish date may be hours after commit — small gap is normal, days-wide gap means the fix was likely in an earlier version

Verification

  • Step 1: Run `npm view @anthropic-ai/claude-code@2.1.47 time 2>&1; echo exit=$?` → expect: '2026-02-18T...' (ISO date), exit 0
  • Step 2: Compare with GitHub commit date → expect: npm publish date on or after commit date
✓ 0 verified✕ 0 failed

Solution A: Use Python's packaging.version for semver-aware sort

risk: lowhumanpublished

Python's packaging.version.Version (or distutils.version.LooseVersion) properly parses semantic versioning. Feed the npm JSON array through a one-liner that sorts by semantic version tuples.

  1. Get versions JSON from npm
  2. Parse and sort with Python using tuple-key decomposition
  3. Verify the sorted result makes semantic sense

Commands

npm view @anthropic-ai/claude-code versions --json | python3 -c "import json,sys,re; vs=json.load(sys.stdin); [print(v) for v in sorted(vs, key=lambda v: tuple(int(p) if p.isdigit() else p for p in re.split(r'[.-]', v)))]" | tail -5

Risks

  • Pre-release tags (alpha, beta, rc) require special handling — the tuple-key approach handles them but may sort them differently than npm's intended order
  • CalVer versions (e.g., 2024.01.01) need different parsing

Verification

  • Step 1: Run `npm view @anthropic-ai/claude-code versions --json | python3 -c "import json,sys,re; vs=json.load(sys.stdin); sv=sorted(vs, key=lambda v: tuple(int(p) if p.isdigit() else p for p in re.split(r'[.-]', v))); print('Last 5 semver-sorted:', sv[-5:])" 2>&1` → expect: correctly ordered versions (e.g., ['2.1.169','2.1.170','2.1.171','2.1.172','2.1.173'])
  • Step 2: Run `npm view @anthropic-ai/claude-code versions --json | python3 -c "import json,sys; vs=json.load(sys.stdin); print('Last 5 lexical:', vs[-5:])"` → expect: WRONG order (e.g., ['2.1.9','2.1.90','2.1.97','2.1.98','2.1.99']) — proving lexical sort is broken
✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "e818c79d-208e-404f-94c4-bad96d542d2b",
  "slug": "fix-npm-version-detection-errors-use-semver-aware-sorting-instead-of-lexical-sort-to-find-correct-package-versions-s6qui2",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-npm-version-detection-errors-use-semver-aware-sorting-instead-of-lexical-sort-to-find-correct-package-versions-s6qui2"
}
← Back to all issuesPowered by CodeKB