feat: implement semver parsing and comparison for improved version handling

Author: LadyBluenotes

packages/intent/src/scanner.ts

@@ -199,13 +199,72 @@ function getPackageDepth(packageRoot: string, projectRoot: string): number {
   return relative(projectRoot, packageRoot).split(sep).length
 }
 
+interface ParsedSemver {
+  major: number
+  minor: number
+  patch: number
+  prerelease: Array<string | number>
+}
+
+function parseSemver(version: string): ParsedSemver | null {
+  const match =
+    /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+      version,
+    )
+  if (!match) return null
+
+  const prerelease = match[4]
+    ? match[4].split('.').map((identifier) => {
+        return /^\d+$/.test(identifier) ? Number(identifier) : identifier
+      })
+    : []
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease,
+  }
+}
+
+function comparePrereleaseIdentifiers(
+  a: string | number | undefined,
+  b: string | number | undefined,
+): number {
+  if (a === undefined) return b === undefined ? 0 : 1
+  if (b === undefined) return -1
+
+  if (typeof a === 'number' && typeof b === 'number') {
+    return a - b
+  }
+
+  if (typeof a === 'number') return -1
+  if (typeof b === 'number') return 1
+
+  return a.localeCompare(b)
+}
+
 function comparePackageVersions(a: string, b: string): number {
-  const aMatch = /^(\d+)\.(\d+)\.(\d+)/.exec(a)
-  const bMatch = /^(\d+)\.(\d+)\.(\d+)/.exec(b)
-  if (!aMatch || !bMatch) return 0
+  const parsedA = parseSemver(a)
+  const parsedB = parseSemver(b)
 
-  for (let i = 1; i <= 3; i++) {
-    const diff = Number(aMatch[i]) - Number(bMatch[i])
+  if (!parsedA || !parsedB) {
+    if (parsedA) return 1
+    if (parsedB) return -1
+    return 0
+  }
+
+  for (const key of ['major', 'minor', 'patch'] as const) {
+    const diff = parsedA[key] - parsedB[key]
+    if (diff !== 0) return diff
+  }
+
+  const length = Math.max(parsedA.prerelease.length, parsedB.prerelease.length)
+  for (let i = 0; i < length; i++) {
+    const diff = comparePrereleaseIdentifiers(
+      parsedA.prerelease[i],
+      parsedB.prerelease[i],
+    )
     if (diff !== 0) return diff
   }
 

packages/intent/tests/scanner.test.ts

@@ -416,6 +416,132 @@ describe('scanForIntents', () => {
     expect(versionWarning).toContain('across 3 versions')
     expect(versionWarning).toContain('Using 5.0.0')
   })
+
+  it('prefers stable releases over prereleases at the same depth', async () => {
+    writeJson(join(root, 'package.json'), {
+      name: 'app',
+      private: true,
+      dependencies: {
+        'consumer-a': '1.0.0',
+        'consumer-b': '1.0.0',
+      },
+    })
+
+    const consumerADir = createDir(root, 'node_modules', 'consumer-a')
+    const consumerBDir = createDir(root, 'node_modules', 'consumer-b')
+
+    writeJson(join(consumerADir, 'package.json'), {
+      name: 'consumer-a',
+      version: '1.0.0',
+      dependencies: { '@tanstack/query': '5.0.0-beta.1' },
+    })
+    writeJson(join(consumerBDir, 'package.json'), {
+      name: 'consumer-b',
+      version: '1.0.0',
+      dependencies: { '@tanstack/query': '5.0.0' },
+    })
+
+    const prereleaseDir = createDir(
+      consumerADir,
+      'node_modules',
+      '@tanstack',
+      'query',
+    )
+    const stableDir = createDir(
+      consumerBDir,
+      'node_modules',
+      '@tanstack',
+      'query',
+    )
+
+    writeJson(join(prereleaseDir, 'package.json'), {
+      name: '@tanstack/query',
+      version: '5.0.0-beta.1',
+      intent: { version: 1, repo: 'TanStack/query', docs: 'docs/' },
+    })
+    writeJson(join(stableDir, 'package.json'), {
+      name: '@tanstack/query',
+      version: '5.0.0',
+      intent: { version: 1, repo: 'TanStack/query', docs: 'docs/' },
+    })
+    writeSkillMd(createDir(prereleaseDir, 'skills', 'fetching'), {
+      name: 'fetching',
+      description: 'Prerelease query skill',
+    })
+    writeSkillMd(createDir(stableDir, 'skills', 'fetching'), {
+      name: 'fetching',
+      description: 'Stable query skill',
+    })
+
+    const result = await scanForIntents(root)
+
+    expect(result.packages).toHaveLength(1)
+    expect(result.packages[0]!.version).toBe('5.0.0')
+    expect(result.packages[0]!.packageRoot).toBe(stableDir)
+  })
+
+  it('prefers valid semver versions over invalid ones at the same depth', async () => {
+    writeJson(join(root, 'package.json'), {
+      name: 'app',
+      private: true,
+      dependencies: {
+        'consumer-a': '1.0.0',
+        'consumer-b': '1.0.0',
+      },
+    })
+
+    const consumerADir = createDir(root, 'node_modules', 'consumer-a')
+    const consumerBDir = createDir(root, 'node_modules', 'consumer-b')
+
+    writeJson(join(consumerADir, 'package.json'), {
+      name: 'consumer-a',
+      version: '1.0.0',
+      dependencies: { '@tanstack/query': 'workspace-dev' },
+    })
+    writeJson(join(consumerBDir, 'package.json'), {
+      name: 'consumer-b',
+      version: '1.0.0',
+      dependencies: { '@tanstack/query': '5.0.0' },
+    })
+
+    const invalidDir = createDir(
+      consumerADir,
+      'node_modules',
+      '@tanstack',
+      'query',
+    )
+    const validDir = createDir(
+      consumerBDir,
+      'node_modules',
+      '@tanstack',
+      'query',
+    )
+
+    writeJson(join(invalidDir, 'package.json'), {
+      name: '@tanstack/query',
+      version: 'workspace-dev',
+      intent: { version: 1, repo: 'TanStack/query', docs: 'docs/' },
+    })
+    writeJson(join(validDir, 'package.json'), {
+      name: '@tanstack/query',
+      version: '5.0.0',
+      intent: { version: 1, repo: 'TanStack/query', docs: 'docs/' },
+    })
+    writeSkillMd(createDir(invalidDir, 'skills', 'fetching'), {
+      name: 'fetching',
+      description: 'Invalid version query skill',
+    })
+    writeSkillMd(createDir(validDir, 'skills', 'fetching'), {
+      name: 'fetching',
+      description: 'Valid version query skill',
+    })
+
+    const result = await scanForIntents(root)
+
+    expect(result.packages).toHaveLength(1)
+    expect(result.packages[0]!.version).toBe('5.0.0')
+    expect(result.packages[0]!.packageRoot).toBe(validDir)
+  })
 })
 
 describe('package manager detection', () => {