@eslint-config-snapshot/cli 0.8.0 → 0.14.0

package/src/runtime.ts

@@ -0,0 +1,224 @@
+import {
+  aggregateRules,
+  assignGroupsByMatch,
+  buildSnapshot,
+  diffSnapshots,
+  discoverWorkspaces,
+  extractRulesForWorkspaceSamples,
+  type GroupAssignment,
+  hasDiff,
+  loadConfig,
+  readSnapshotFile,
+  resolveEslintVersionForWorkspace,
+  sampleWorkspaceFiles,
+  type SnapshotConfig,
+  type WorkspaceDiscovery,
+  writeSnapshotFile
+} from '@eslint-config-snapshot/api'
+import createDebug from 'debug'
+import fg from 'fast-glob'
+import { mkdir } from 'node:fs/promises'
+import path from 'node:path'
+
+const debugWorkspace = createDebug('eslint-config-snapshot:workspace')
+const debugDiff = createDebug('eslint-config-snapshot:diff')
+const debugTiming = createDebug('eslint-config-snapshot:timing')
+
+export type BuiltSnapshot = Awaited<ReturnType<typeof buildSnapshot>>
+export type StoredSnapshot = Awaited<ReturnType<typeof readSnapshotFile>>
+export type SnapshotDiff = ReturnType<typeof diffSnapshots>
+export type GroupEslintVersions = Map<string, string[]>
+export type WorkspaceAssignments = {
+  discovery: WorkspaceDiscovery
+  assignments: GroupAssignment[]
+}
+
+export async function computeCurrentSnapshots(cwd: string): Promise<Map<string, BuiltSnapshot>> {
+  const computeStartedAt = Date.now()
+  const configStartedAt = Date.now()
+  const config = await loadConfig(cwd)
+  debugTiming('phase=loadConfig elapsedMs=%d', Date.now() - configStartedAt)
+
+  const assignmentStartedAt = Date.now()
+  const { discovery, assignments } = await resolveWorkspaceAssignments(cwd, config)
+  debugTiming('phase=resolveWorkspaceAssignments elapsedMs=%d', Date.now() - assignmentStartedAt)
+  debugWorkspace('root=%s groups=%d workspaces=%d', discovery.rootAbs, assignments.length, discovery.workspacesRel.length)
+
+  const snapshots = new Map<string, BuiltSnapshot>()
+
+  for (const group of assignments) {
+    const groupStartedAt = Date.now()
+    const extractedForGroup = []
+    debugWorkspace('group=%s workspaces=%o', group.name, group.workspaces)
+
+    for (const workspaceRel of group.workspaces) {
+      const workspaceAbs = path.resolve(discovery.rootAbs, workspaceRel)
+      const sampleStartedAt = Date.now()
+      const sampled = await sampleWorkspaceFiles(workspaceAbs, config.sampling)
+      debugWorkspace(
+        'group=%s workspace=%s sampled=%d sampleElapsedMs=%d files=%o',
+        group.name,
+        workspaceRel,
+        sampled.length,
+        Date.now() - sampleStartedAt,
+        sampled
+      )
+      let extractedCount = 0
+      let lastExtractionError: string | undefined
+
+      const sampledAbs = sampled.map((sampledRel) => path.resolve(workspaceAbs, sampledRel))
+      const extractStartedAt = Date.now()
+      const results = await extractRulesForWorkspaceSamples(workspaceAbs, sampledAbs)
+      debugTiming(
+        'phase=extract group=%s workspace=%s sampled=%d elapsedMs=%d',
+        group.name,
+        workspaceRel,
+        sampledAbs.length,
+        Date.now() - extractStartedAt
+      )
+
+      for (const result of results) {
+        if (result.rules) {
+          extractedForGroup.push(result.rules)
+          extractedCount += 1
+          continue
+        }
+
+        const message = result.error instanceof Error ? result.error.message : String(result.error)
+        if (isRecoverableExtractionError(message)) {
+          lastExtractionError = message
+          continue
+        }
+
+        throw result.error ?? new Error(message)
+      }
+
+      if (extractedCount === 0) {
+        const context = lastExtractionError ? ` Last error: ${lastExtractionError}` : ''
+        throw new Error(
+          `Unable to extract ESLint config for workspace ${workspaceRel}. All sampled files were ignored or produced non-JSON output.${context}`
+        )
+      }
+
+      debugWorkspace(
+        'group=%s workspace=%s extracted=%d failed=%d',
+        group.name,
+        workspaceRel,
+        extractedCount,
+        results.length - extractedCount
+      )
+    }
+
+    const aggregated = aggregateRules(extractedForGroup)
+    snapshots.set(group.name, buildSnapshot(group.name, group.workspaces, aggregated))
+    debugWorkspace(
+      'group=%s aggregatedRules=%d groupElapsedMs=%d',
+      group.name,
+      aggregated.size,
+      Date.now() - groupStartedAt
+    )
+  }
+
+  debugTiming('phase=computeCurrentSnapshots elapsedMs=%d', Date.now() - computeStartedAt)
+  return snapshots
+}
+
+function isRecoverableExtractionError(message: string): boolean {
+  return (
+    message.startsWith('Invalid JSON from eslint --print-config') ||
+    message.startsWith('Empty ESLint print-config output') ||
+    message.includes('File ignored because of a matching ignore pattern') ||
+    message.includes('File ignored by default')
+  )
+}
+
+export async function resolveWorkspaceAssignments(cwd: string, config: SnapshotConfig): Promise<WorkspaceAssignments> {
+  const discovery = await discoverWorkspaces({ cwd, workspaceInput: config.workspaceInput })
+
+  const assignments =
+    config.grouping.mode === 'standalone'
+      ? discovery.workspacesRel.map((workspace) => ({ name: workspace, workspaces: [workspace] }))
+      : assignGroupsByMatch(discovery.workspacesRel, config.grouping.groups ?? [{ name: 'default', match: ['**/*'] }])
+
+  const allowEmptyGroups = config.grouping.allowEmptyGroups ?? false
+  if (!allowEmptyGroups) {
+    const empty = assignments.filter((group) => group.workspaces.length === 0)
+    if (empty.length > 0) {
+      throw new Error(`Empty groups are not allowed: ${empty.map((entry) => entry.name).join(', ')}`)
+    }
+  }
+
+  return { discovery, assignments }
+}
+
+export async function loadStoredSnapshots(cwd: string, snapshotDir: string): Promise<Map<string, StoredSnapshot>> {
+  const dir = path.join(cwd, snapshotDir)
+  const files = await fg('**/*.json', { cwd: dir, absolute: true, onlyFiles: true, dot: true, suppressErrors: true })
+  const snapshots = new Map<string, StoredSnapshot>()
+  const sortedFiles = [...files].sort((a, b) => a.localeCompare(b))
+
+  for (const file of sortedFiles) {
+    const snapshot = await readSnapshotFile(file)
+    snapshots.set(snapshot.groupId, snapshot)
+  }
+
+  return snapshots
+}
+
+export async function writeSnapshots(cwd: string, snapshotDir: string, snapshots: Map<string, BuiltSnapshot>): Promise<void> {
+  await mkdir(path.join(cwd, snapshotDir), { recursive: true })
+  for (const snapshot of snapshots.values()) {
+    await writeSnapshotFile(path.join(cwd, snapshotDir), snapshot)
+  }
+}
+
+export function compareSnapshotMaps(before: Map<string, StoredSnapshot>, after: Map<string, BuiltSnapshot>) {
+  const startedAt = Date.now()
+  const ids = [...new Set([...before.keys(), ...after.keys()])].sort()
+  const changes: Array<{ groupId: string; diff: SnapshotDiff }> = []
+
+  for (const id of ids) {
+    const prev =
+      before.get(id) ??
+      ({
+        formatVersion: 1,
+        groupId: id,
+        workspaces: [],
+        rules: {}
+      } as const)
+
+    const next =
+      after.get(id) ??
+      ({
+        formatVersion: 1,
+        groupId: id,
+        workspaces: [],
+        rules: {}
+      } as const)
+
+    const diff = diffSnapshots(prev, next)
+    if (hasDiff(diff)) {
+      changes.push({ groupId: id, diff })
+    }
+  }
+
+  debugDiff('groupsCompared=%d changedGroups=%d elapsedMs=%d', ids.length, changes.length, Date.now() - startedAt)
+  return changes
+}
+
+export async function resolveGroupEslintVersions(cwd: string): Promise<GroupEslintVersions> {
+  const config = await loadConfig(cwd)
+  const { discovery, assignments } = await resolveWorkspaceAssignments(cwd, config)
+  const result = new Map<string, string[]>()
+
+  for (const group of assignments) {
+    const versions = new Set<string>()
+    for (const workspaceRel of group.workspaces) {
+      const workspaceAbs = path.resolve(discovery.rootAbs, workspaceRel)
+      versions.add(resolveEslintVersionForWorkspace(workspaceAbs))
+    }
+    result.set(group.name, [...versions].sort((a, b) => a.localeCompare(b)))
+  }
+
+  return result
+}

package/src/terminal.ts

@@ -0,0 +1,178 @@
+import { createInterface } from 'node:readline'
+
+type Colorizer = {
+  green: (text: string) => string
+  yellow: (text: string) => string
+  red: (text: string) => string
+  bold: (text: string) => string
+  dim: (text: string) => string
+}
+
+export type RunTimer = {
+  label: string
+  startedAtMs: number
+  pausedMs: number
+  pauseStartedAtMs: number | undefined
+}
+
+export class TerminalIO {
+  private readonly color = createColorizer()
+  private activeRunTimer: RunTimer | undefined
+
+  get isTTY(): boolean {
+    return process.stdout.isTTY === true
+  }
+
+  get isInteractive(): boolean {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true
+  }
+
+  get showProgress(): boolean {
+    if (process.env.ESLINT_CONFIG_SNAPSHOT_NO_PROGRESS === '1') {
+      return false
+    }
+    return this.isTTY
+  }
+
+  get colors(): Colorizer {
+    return this.color
+  }
+
+  write(text: string): void {
+    process.stdout.write(text)
+  }
+
+  error(text: string): void {
+    process.stderr.write(text)
+  }
+
+  subtle(text: string): void {
+    this.write(this.color.dim(text))
+  }
+
+  section(title: string): void {
+    this.write(`${this.color.bold(title)}\n`)
+  }
+
+  success(text: string): void {
+    this.write(this.color.green(text))
+  }
+
+  warning(text: string): void {
+    this.write(this.color.yellow(text))
+  }
+
+  danger(text: string): void {
+    this.write(this.color.red(text))
+  }
+
+  bold(text: string): string {
+    return this.color.bold(text)
+  }
+
+  beginRun(label: string): void {
+    if (!this.showProgress) {
+      this.activeRunTimer = undefined
+      return
+    }
+
+    this.activeRunTimer = {
+      label,
+      startedAtMs: Date.now(),
+      pausedMs: 0,
+      pauseStartedAtMs: undefined
+    }
+  }
+
+  endRun(exitCode: number, logTiming: (timer: RunTimer, elapsedMs: number) => void): void {
+    if (!this.activeRunTimer || !this.showProgress) {
+      return
+    }
+
+    if (this.activeRunTimer.pauseStartedAtMs !== undefined) {
+      this.activeRunTimer.pausedMs += Date.now() - this.activeRunTimer.pauseStartedAtMs
+      this.activeRunTimer.pauseStartedAtMs = undefined
+    }
+
+    const elapsedMs = Math.max(0, Date.now() - this.activeRunTimer.startedAtMs - this.activeRunTimer.pausedMs)
+    logTiming(this.activeRunTimer, elapsedMs)
+    const seconds = (elapsedMs / 1000).toFixed(2)
+    this.subtle(exitCode === 0 ? `⏱️ Finished in ${seconds}s\n` : `⏱️ Finished with errors in ${seconds}s\n`)
+    this.activeRunTimer = undefined
+  }
+
+  pauseRun(): void {
+    if (!this.activeRunTimer || this.activeRunTimer.pauseStartedAtMs !== undefined) {
+      return
+    }
+    this.activeRunTimer.pauseStartedAtMs = Date.now()
+  }
+
+  resumeRun(): void {
+    if (!this.activeRunTimer || this.activeRunTimer.pauseStartedAtMs === undefined) {
+      return
+    }
+    this.activeRunTimer.pausedMs += Date.now() - this.activeRunTimer.pauseStartedAtMs
+    this.activeRunTimer.pauseStartedAtMs = undefined
+  }
+
+  async withPausedRunTimer<T>(task: () => Promise<T>): Promise<T> {
+    this.pauseRun()
+    try {
+      return await task()
+    } finally {
+      this.resumeRun()
+    }
+  }
+
+  async askYesNo(prompt: string, defaultYes: boolean): Promise<boolean> {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    try {
+      const answerRaw = await this.askQuestion(rl, prompt)
+      const answer = answerRaw.trim().toLowerCase()
+      if (answer.length === 0) {
+        return defaultYes
+      }
+
+      return answer === 'y' || answer === 'yes'
+    } finally {
+      rl.close()
+    }
+  }
+
+  private async askQuestion(rl: ReturnType<typeof createInterface>, prompt: string): Promise<string> {
+    this.pauseRun()
+    return new Promise((resolve) => {
+      rl.question(prompt, (answer) => {
+        this.resumeRun()
+        resolve(answer)
+      })
+    })
+  }
+}
+
+export function resolveInvocationLabel(argv: string[]): string {
+  const commandToken = argv.find((entry) => !entry.startsWith('-'))
+  if (commandToken) {
+    return commandToken
+  }
+  if (argv.includes('-u') || argv.includes('--update')) {
+    return 'update'
+  }
+  if (argv.includes('-h') || argv.includes('--help')) {
+    return 'help'
+  }
+  return 'check'
+}
+
+function createColorizer(): Colorizer {
+  const enabled = process.stdout.isTTY && process.env.NO_COLOR === undefined && process.env.TERM !== 'dumb'
+  const wrap = (code: string, text: string) => (enabled ? `\u001B[${code}m${text}\u001B[0m` : text)
+  return {
+    green: (text: string) => wrap('32', text),
+    yellow: (text: string) => wrap('33', text),
+    red: (text: string) => wrap('31', text),
+    bold: (text: string) => wrap('1', text),
+    dim: (text: string) => wrap('2', text)
+  }
+}

package/test/cli.integration.test.ts

@@ -84,7 +84,7 @@ describe.sequential('cli integration', () => {
       workspaces: ['packages/ws-a', 'packages/ws-b'],
       rules: {
         eqeqeq: ['error', 'always'],
-        'no-console': ['error'],
+        'no-console': [['error'], ['warn']],
         'no-debugger': ['off']
       }
     })
@@ -130,7 +130,7 @@ describe.sequential('cli integration', () => {
 workspaces (2): packages/ws-a, packages/ws-b
 rules (3): error 2, warn 0, off 1
 eqeqeq: error "always"
-no-console: error
+no-console: [["error"],["warn"]]
 no-debugger: off
 `
     )
@@ -211,8 +211,7 @@ no-debugger: off
   sampling: {
     maxFilesPerWorkspace: 8,
     includeGlobs: ['**/*.ts'],
-    excludeGlobs: ['**/node_modules/**'],
-    hintGlobs: []
+    excludeGlobs: ['**/node_modules/**']
   }
 }
 `
@@ -251,8 +250,7 @@ no-debugger: off
   sampling: {
     maxFilesPerWorkspace: 8,
     includeGlobs: ['**/*.ts'],
-    excludeGlobs: ['**/node_modules/**'],
-    hintGlobs: []
+    excludeGlobs: ['**/node_modules/**']
   }
 }
 `

package/test/cli.npm-isolated.integration.test.ts

@@ -103,7 +103,7 @@ describe('cli npm-isolated integration', () => {
       workspaces: ['packages/ws-a', 'packages/ws-b'],
       rules: {
         eqeqeq: ['error', 'always'],
-        'no-console': ['error'],
+        'no-console': [['error'], ['warn']],
         'no-debugger': ['off']
       }
     })

package/test/cli.pnpm-isolated.integration.test.ts

@@ -141,7 +141,7 @@ describe('cli pnpm-isolated integration', () => {
       workspaces: ['packages/ws-a', 'packages/ws-b'],
       rules: {
         eqeqeq: ['error', 'always'],
-        'no-console': ['error'],
+        'no-console': [['error'], ['warn']],
         'no-debugger': ['off']
       }
     })

package/test/cli.terminal.integration.test.ts

@@ -132,7 +132,7 @@ describe('cli terminal invocation', () => {
     const compare = run(['compare'])
     expect(compare.status).toBe(1)
     expect(compare.stdout).toBe(
-      'group: default\noptions changed:\n  - eqeqeq: "always" -> "smart"\nTip: when you intentionally accept changes, run `eslint-config-snapshot --update` to refresh the baseline.\n'
+      'group: default\noptions changed:\n  - eqeqeq: [["error","always"]] -> [["error","smart"]]\nTip: when you intentionally accept changes, run `eslint-config-snapshot --update` to refresh the baseline.\n'
     )
     expect(compare.stderr).toBe('')
   })
@@ -185,7 +185,12 @@ describe('cli terminal invocation', () => {
         "always"
       ],
       "no-console": [
-        "error"
+        [
+          "error"
+        ],
+        [
+          "warn"
+        ]
       ],
       "no-debugger": [
         "off"
@@ -206,7 +211,7 @@ describe('cli terminal invocation', () => {
 workspaces (2): packages/ws-a, packages/ws-b
 rules (3): error 2, warn 0, off 1
 eqeqeq: error "always"
-no-console: error
+no-console: [["error"],["warn"]]
 no-debugger: off
 `
     )
@@ -337,7 +342,7 @@ no-debugger: off
       `export default {
   workspaceInput: { mode: 'manual', workspaces: ['packages/ws-a'] },
   grouping: { mode: 'match', allowEmptyGroups: false, groups: [{ name: 'never', match: ['ops/**'] }] },
-  sampling: { maxFilesPerWorkspace: 8, includeGlobs: ['**/*.ts'], excludeGlobs: ['**/node_modules/**'], hintGlobs: [] }
+  sampling: { maxFilesPerWorkspace: 8, includeGlobs: ['**/*.ts'], excludeGlobs: ['**/node_modules/**'] }
 }
 `
     )
@@ -360,7 +365,7 @@ no-debugger: off
           'eslint-config-snapshot': {
             workspaceInput: { mode: 'manual', workspaces: ['packages/ws-a'] },
             grouping: { mode: 'match', groups: [{ name: 'default', match: ['**/*'] }] },
-            sampling: { maxFilesPerWorkspace: 8, includeGlobs: ['**/*.ts'], excludeGlobs: ['**/node_modules/**'], hintGlobs: [] }
+            sampling: { maxFilesPerWorkspace: 8, includeGlobs: ['**/*.ts'], excludeGlobs: ['**/node_modules/**'] }
           }
         },
         null,

package/test/fixtures/npm-isolated-template/eslint-config-snapshot.config.mjs

@@ -10,7 +10,6 @@ export default {
   sampling: {
     maxFilesPerWorkspace: 8,
     includeGlobs: ['**/*.ts'],
-    excludeGlobs: ['**/node_modules/**', '**/dist/**'],
-    hintGlobs: []
+    excludeGlobs: ['**/node_modules/**', '**/dist/**']
   }
 }

package/test/fixtures/repo/eslint-config-snapshot.config.mjs

@@ -10,7 +10,6 @@ export default {
   sampling: {
     maxFilesPerWorkspace: 8,
     includeGlobs: ['**/*.ts'],
-    excludeGlobs: ['**/node_modules/**'],
-    hintGlobs: []
+    excludeGlobs: ['**/node_modules/**']
   }
 }

package/test/formatters.unit.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+
+import { formatCommandDisplayLabel, formatDiff, summarizeSnapshots } from '../src/formatters.js'
+
+describe('output helpers', () => {
+  it('formats friendly command labels', () => {
+    expect(formatCommandDisplayLabel('check')).toBe('Check drift against baseline (summary)')
+    expect(formatCommandDisplayLabel('print:short')).toBe('Print aggregated rules (short view)')
+    expect(formatCommandDisplayLabel('custom')).toBe('custom')
+  })
+
+  it('formats nested diff sections', () => {
+    const formatted = formatDiff('default', {
+      introducedRules: ['a'],
+      removedRules: ['b'],
+      severityChanges: [{ rule: 'c', before: 'error', after: 'off' }],
+      optionChanges: [{ rule: 'd', before: { a: true }, after: { a: false } }],
+      workspaceMembershipChanges: { added: ['packages/new'], removed: ['packages/old'] }
+    })
+    expect(formatted).toContain('group: default')
+    expect(formatted).toContain('introduced rules:')
+    expect(formatted).toContain('removed rules:')
+    expect(formatted).toContain('severity changed:')
+    expect(formatted).toContain('options changed:')
+    expect(formatted).toContain('workspaces added:')
+  })
+
+  it('summarizes snapshot severities', () => {
+    const summary = summarizeSnapshots(
+      new Map([
+        [
+          'default',
+          {
+            groupId: 'default',
+            workspaces: ['packages/a'],
+            rules: {
+              a: ['error'],
+              b: ['warn'],
+              c: ['off']
+            }
+          }
+        ]
+      ])
+    )
+    expect(summary).toEqual({ groups: 1, rules: 3, error: 1, warn: 1, off: 1 })
+  })
+})

package/test/init.unit.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+
+import { buildRecommendedConfigFromAssignments } from '../src/init.js'
+
+describe('init module', () => {
+  it('returns empty config when no explicit assignments are provided', () => {
+    const config = buildRecommendedConfigFromAssignments(['packages/a', 'packages/b'], new Map())
+    expect(config).toEqual({})
+  })
+
+  it('builds static groups followed by dynamic catch-all', () => {
+    const config = buildRecommendedConfigFromAssignments(
+      ['packages/a', 'packages/b', 'packages/c'],
+      new Map([
+        ['packages/b', 2],
+        ['packages/c', 1]
+      ])
+    )
+
+    expect(config).toEqual({
+      grouping: {
+        mode: 'match',
+        groups: [
+          { name: 'group-1', match: ['packages/c'] },
+          { name: 'group-2', match: ['packages/b'] },
+          { name: 'default', match: ['**/*'] }
+        ]
+      }
+    })
+  })
+})

package/test/runtime.unit.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest'
+
+import { compareSnapshotMaps } from '../src/runtime.js'
+
+describe('runtime helpers', () => {
+  it('detects changed groups deterministically', () => {
+    const before = new Map([
+      [
+        'default',
+        {
+          formatVersion: 1 as const,
+          groupId: 'default',
+          workspaces: ['packages/a'],
+          rules: { a: ['error'] as const }
+        }
+      ]
+    ])
+
+    const after = new Map([
+      [
+        'default',
+        {
+          formatVersion: 1 as const,
+          groupId: 'default',
+          workspaces: ['packages/a'],
+          rules: { a: ['off'] as const }
+        }
+      ]
+    ])
+
+    const changes = compareSnapshotMaps(before, after)
+    expect(changes).toHaveLength(1)
+    expect(changes[0]?.groupId).toBe('default')
+    expect(changes[0]?.diff.severityChanges).toHaveLength(1)
+  })
+})

package/test/ui.unit.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+
+import { resolveInvocationLabel } from '../src/terminal.js'
+
+describe('terminal module', () => {
+  it('resolves command labels deterministically', () => {
+    expect(resolveInvocationLabel(['check'])).toBe('check')
+    expect(resolveInvocationLabel(['--update'])).toBe('update')
+    expect(resolveInvocationLabel(['--help'])).toBe('help')
+    expect(resolveInvocationLabel([])).toBe('check')
+  })
+})