feat: add version conflict detection and reporting in CLI output

Author: LadyBluenotes

packages/intent/src/cli.ts

@@ -78,6 +78,27 @@ async function cmdList(args: Array<string>): Promise<void> {
   ])
   printTable(['PACKAGE', 'VERSION', 'SKILLS', 'REQUIRES'], rows)
 
+  if (result.conflicts.length > 0) {
+    console.log(`
+Version conflicts:
+`)
+    for (const conflict of result.conflicts) {
+      const otherVariants = conflict.variants.filter(
+        (variant) => variant.packageRoot !== conflict.chosen.packageRoot,
+      )
+      console.log(
+        `  ${conflict.packageName} -> using ${conflict.chosen.version}`,
+      )
+      console.log(`    chosen: ${conflict.chosen.packageRoot}`)
+      for (const variant of otherVariants) {
+        console.log(
+          `    also found: ${variant.version} at ${variant.packageRoot}`,
+        )
+      }
+      console.log()
+    }
+  }
+
   // Skills detail
   const allSkills = result.packages.map((p) => p.skills)
   const nameWidth = computeSkillNameWidth(allSkills)

packages/intent/src/scanner.ts

@@ -8,11 +8,13 @@ import {
   resolveDepDir,
 } from './utils.js'
 import type {
+  InstalledVariant,
   IntentConfig,
   IntentPackage,
   NodeModulesScanTarget,
   ScanResult,
   SkillEntry,
+  VersionConflict,
 } from './types.js'
 import type { Dirent } from 'node:fs'
 
@@ -212,7 +214,7 @@ function comparePackageVersions(a: string, b: string): number {
 
 function formatVariantWarning(
   name: string,
-  variants: Array<{ version: string; packageRoot: string }>,
+  variants: Array<InstalledVariant>,
   chosen: IntentPackage,
 ): string | null {
   const uniqueVersions = new Set(variants.map((variant) => variant.version))
@@ -225,6 +227,24 @@ function formatVariantWarning(
   return `Found ${variants.length} installed variants of ${name} across ${uniqueVersions.size} versions (${details}). Using ${chosen.version} from ${chosen.packageRoot}.`
 }
 
+function toVersionConflict(
+  packageName: string,
+  variants: Array<InstalledVariant>,
+  chosen: IntentPackage,
+): VersionConflict | null {
+  const uniqueVersions = new Set(variants.map((variant) => variant.version))
+  if (uniqueVersions.size <= 1) return null
+
+  return {
+    packageName,
+    chosen: {
+      version: chosen.version,
+      packageRoot: chosen.packageRoot,
+    },
+    variants,
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main scanner
 // ---------------------------------------------------------------------------
@@ -238,6 +258,7 @@ export async function scanForIntents(root?: string): Promise<ScanResult> {
 
   const packages: Array<IntentPackage> = []
   const warnings: Array<string> = []
+  const conflicts: Array<VersionConflict> = []
   const nodeModules: ScanResult['nodeModules'] = {
     local: {
       path: nodeModulesDir,
@@ -473,13 +494,18 @@ export async function scanForIntents(root?: string): Promise<ScanResult> {
   }
 
   if (!nodeModules.local.exists && !nodeModules.global.exists) {
-    return { packageManager, packages, warnings, nodeModules }
+    return { packageManager, packages, warnings, conflicts, nodeModules }
   }
 
   for (const pkg of packages) {
     const variants = packageVariants.get(pkg.name)
     if (!variants) continue
 
+    const conflict = toVersionConflict(pkg.name, [...variants.values()], pkg)
+    if (conflict) {
+      conflicts.push(conflict)
+    }
+
     const warning = formatVariantWarning(pkg.name, [...variants.values()], pkg)
     if (warning) {
       warnings.push(warning)
@@ -489,5 +515,5 @@ export async function scanForIntents(root?: string): Promise<ScanResult> {
   // Sort by dependency order
   const sorted = topoSort(packages)
 
-  return { packageManager, packages: sorted, warnings, nodeModules }
+  return { packageManager, packages: sorted, warnings, conflicts, nodeModules }
 }

packages/intent/src/types.ts

@@ -17,6 +17,7 @@ export interface ScanResult {
   packageManager: 'npm' | 'pnpm' | 'yarn' | 'bun' | 'unknown'
   packages: Array<IntentPackage>
   warnings: Array<string>
+  conflicts: Array<VersionConflict>
   nodeModules: {
     local: NodeModulesScanTarget
     global: NodeModulesScanTarget
@@ -39,6 +40,17 @@ export interface IntentPackage {
   packageRoot: string
 }
 
+export interface InstalledVariant {
+  version: string
+  packageRoot: string
+}
+
+export interface VersionConflict {
+  packageName: string
+  chosen: InstalledVariant
+  variants: Array<InstalledVariant>
+}
+
 export interface SkillEntry {
   name: string
   path: string

packages/intent/tests/cli.test.ts

@@ -122,6 +122,7 @@ describe('cli commands', () => {
     const output = logSpy.mock.calls.at(-1)?.[0]
     const parsed = JSON.parse(String(output)) as {
       packages: Array<{ name: string; version: string; packageRoot: string }>
+      conflicts: Array<{ packageName: string }>
       warnings: Array<string>
     }
 
@@ -132,9 +133,69 @@ describe('cli commands', () => {
       version: '0.5.2',
       packageRoot: pkgDir,
     })
+    expect(parsed.conflicts).toEqual([])
     expect(parsed.warnings).toEqual([])
   })
 
+  it('explains which package version was chosen when conflicts exist', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'intent-cli-conflicts-'))
+    tempDirs.push(root)
+
+    writeJson(join(root, 'package.json'), {
+      name: 'app',
+      private: true,
+      dependencies: {
+        'consumer-a': '1.0.0',
+        'consumer-b': '1.0.0',
+      },
+    })
+
+    const consumerADir = join(root, 'node_modules', 'consumer-a')
+    const consumerBDir = join(root, 'node_modules', 'consumer-b')
+    const queryV4Dir = join(consumerADir, 'node_modules', '@tanstack', 'query')
+    const queryV5Dir = join(consumerBDir, 'node_modules', '@tanstack', 'query')
+
+    writeJson(join(consumerADir, 'package.json'), {
+      name: 'consumer-a',
+      version: '1.0.0',
+      dependencies: { '@tanstack/query': '4.0.0' },
+    })
+    writeJson(join(consumerBDir, 'package.json'), {
+      name: 'consumer-b',
+      version: '1.0.0',
+      dependencies: { '@tanstack/query': '5.0.0' },
+    })
+    writeJson(join(queryV4Dir, 'package.json'), {
+      name: '@tanstack/query',
+      version: '4.0.0',
+      intent: { version: 1, repo: 'TanStack/query', docs: 'docs/' },
+    })
+    writeJson(join(queryV5Dir, 'package.json'), {
+      name: '@tanstack/query',
+      version: '5.0.0',
+      intent: { version: 1, repo: 'TanStack/query', docs: 'docs/' },
+    })
+    writeSkillMd(join(queryV4Dir, 'skills', 'fetching'), {
+      name: 'fetching',
+      description: 'Query v4 skill',
+    })
+    writeSkillMd(join(queryV5Dir, 'skills', 'fetching'), {
+      name: 'fetching',
+      description: 'Query v5 skill',
+    })
+
+    process.chdir(root)
+
+    const exitCode = await main(['list'])
+    const output = logSpy.mock.calls.flat().join('\n')
+
+    expect(exitCode).toBe(0)
+    expect(output).toContain('Version conflicts:')
+    expect(output).toContain('@tanstack/query -> using 5.0.0')
+    expect(output).toContain(`chosen: ${queryV5Dir}`)
+    expect(output).toContain(`also found: 4.0.0 at ${queryV4Dir}`)
+  })
+
   it('validates a well-formed skills directory', async () => {
     const root = mkdtempSync(join(tmpdir(), 'intent-cli-validate-'))
     tempDirs.push(root)