@eslint-config-snapshot/cli 0.9.0 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eslint-config-snapshot/cli",
-  "version": "0.9.0",
+  "version": "0.14.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -29,7 +29,8 @@
   "dependencies": {
     "@inquirer/prompts": "^8.2.0",
     "commander": "^14.0.3",
+    "debug": "^4.4.3",
     "fast-glob": "^3.3.3",
-    "@eslint-config-snapshot/api": "0.9.0"
+    "@eslint-config-snapshot/api": "0.14.1"
   }
 }

package/src/commands/check.ts

@@ -0,0 +1,157 @@
+import { findConfigPath } from '@eslint-config-snapshot/api'
+
+import { countUniqueWorkspaces, decorateDiffLine, formatDiff, summarizeChanges, summarizeSnapshots } from '../formatters.js'
+import { writeEslintVersionSummary, writeRunContextHeader } from '../run-context.js'
+import {
+  type BuiltSnapshot,
+  compareSnapshotMaps,
+  computeCurrentSnapshots,
+  type GroupEslintVersions,
+  loadStoredSnapshots,
+  resolveGroupEslintVersions,
+  type SnapshotDiff,
+  writeSnapshots
+} from '../runtime.js'
+import { type TerminalIO } from '../terminal.js'
+
+export type CheckFormat = 'summary' | 'status' | 'diff'
+
+const UPDATE_HINT = 'Tip: when you intentionally accept changes, run `eslint-config-snapshot --update` to refresh the baseline.\n'
+
+export async function executeCheck(
+  cwd: string,
+  format: CheckFormat,
+  terminal: TerminalIO,
+  snapshotDir: string,
+  defaultInvocation = false
+): Promise<number> {
+  const foundConfig = await findConfigPath(cwd)
+  const storedSnapshots = await loadStoredSnapshots(cwd, snapshotDir)
+
+  if (format !== 'status') {
+    writeRunContextHeader(terminal, cwd, defaultInvocation ? 'check' : `check:${format}`, foundConfig?.path, storedSnapshots)
+    if (terminal.showProgress) {
+      terminal.subtle('🔎 Checking current ESLint configuration...\n')
+    }
+  }
+
+  if (!foundConfig) {
+    terminal.subtle(
+      'Tip: no explicit config found. Using safe built-in defaults. Run `eslint-config-snapshot init` to customize when needed.\n'
+    )
+  }
+
+  let currentSnapshots: Map<string, BuiltSnapshot>
+  try {
+    currentSnapshots = await computeCurrentSnapshots(cwd)
+  } catch (error: unknown) {
+    if (!foundConfig) {
+      terminal.write(
+        'Automatic workspace discovery could not complete with defaults.\nRun `eslint-config-snapshot init` to configure workspaces, then run `eslint-config-snapshot --update`.\n'
+      )
+      return 1
+    }
+
+    throw error
+  }
+  if (storedSnapshots.size === 0) {
+    const summary = summarizeSnapshots(currentSnapshots)
+    terminal.write(
+      `Rules found in this analysis: ${summary.groups} groups, ${summary.rules} rules (severity mix: ${summary.error} errors, ${summary.warn} warnings, ${summary.off} off).\n`
+    )
+
+    const canPromptBaseline = defaultInvocation || format === 'summary'
+    if (canPromptBaseline && terminal.isInteractive) {
+      const shouldCreateBaseline = await terminal.askYesNo(
+        'No baseline yet. Do you want to save this analyzed rule state as your baseline now? [Y/n] ',
+        true
+      )
+      if (shouldCreateBaseline) {
+        await writeSnapshots(cwd, snapshotDir, currentSnapshots)
+        const createdSummary = summarizeSnapshots(currentSnapshots)
+        terminal.write(`Great start: baseline created with ${createdSummary.groups} groups and ${createdSummary.rules} rules.\n`)
+        terminal.subtle(UPDATE_HINT)
+        return 0
+      }
+    }
+
+    terminal.write('You are almost set: no baseline snapshot found yet.\n')
+    terminal.write('Run `eslint-config-snapshot --update` to create your first baseline.\n')
+    return 1
+  }
+
+  const changes = compareSnapshotMaps(storedSnapshots, currentSnapshots)
+  const eslintVersionsByGroup = terminal.showProgress ? await resolveGroupEslintVersions(cwd) : new Map<string, string[]>()
+
+  if (format === 'status') {
+    if (changes.length === 0) {
+      terminal.write('clean\n')
+      return 0
+    }
+
+    terminal.write('changes\n')
+    terminal.subtle(UPDATE_HINT)
+    return 1
+  }
+
+  if (format === 'diff') {
+    if (changes.length === 0) {
+      terminal.write('Great news: no snapshot changes detected.\n')
+      writeEslintVersionSummary(terminal, eslintVersionsByGroup)
+      return 0
+    }
+
+    for (const change of changes) {
+      terminal.write(`${formatDiff(change.groupId, change.diff)}\n`)
+    }
+    terminal.subtle(UPDATE_HINT)
+
+    return 1
+  }
+
+  return printWhatChanged(terminal, changes, currentSnapshots, eslintVersionsByGroup)
+}
+
+function printWhatChanged(
+  terminal: TerminalIO,
+  changes: Array<{ groupId: string; diff: SnapshotDiff }>,
+  currentSnapshots: Map<string, BuiltSnapshot>,
+  eslintVersionsByGroup: GroupEslintVersions
+): number {
+  const color = terminal.colors
+  const currentSummary = summarizeSnapshots(currentSnapshots)
+  const workspaceCount = countUniqueWorkspaces(currentSnapshots)
+  const changeSummary = summarizeChanges(changes)
+
+  if (changes.length === 0) {
+    terminal.write(color.green('✅ Great news: no snapshot drift detected.\n'))
+    terminal.section('📊 Summary')
+    terminal.write(
+      `- 📦 baseline: ${currentSummary.groups} groups, ${currentSummary.rules} rules\n- 🗂️ workspaces scanned: ${workspaceCount}\n- 🎚️ severity mix: ${currentSummary.error} errors, ${currentSummary.warn} warnings, ${currentSummary.off} off\n`
+    )
+    writeEslintVersionSummary(terminal, eslintVersionsByGroup)
+    return 0
+  }
+
+  terminal.write(color.red('⚠️ Heads up: snapshot drift detected.\n'))
+  terminal.section('📊 Summary')
+  terminal.write(
+    `- changed groups: ${changes.length}\n- introduced rules: ${changeSummary.introduced}\n- removed rules: ${changeSummary.removed}\n- severity changes: ${changeSummary.severity}\n- options changes: ${changeSummary.options}\n- workspace membership changes: ${changeSummary.workspace}\n- 🗂️ workspaces scanned: ${workspaceCount}\n- current baseline: ${currentSummary.groups} groups, ${currentSummary.rules} rules\n- current severity mix: ${currentSummary.error} errors, ${currentSummary.warn} warnings, ${currentSummary.off} off\n`
+  )
+  writeEslintVersionSummary(terminal, eslintVersionsByGroup)
+  terminal.write('\n')
+
+  terminal.section('🧾 Changes')
+  for (const change of changes) {
+    terminal.write(color.bold(`group ${change.groupId}\n`))
+    const lines = formatDiff(change.groupId, change.diff).split('\n').slice(1)
+    for (const line of lines) {
+      const decorated = decorateDiffLine(line, color)
+      terminal.write(`${decorated}\n`)
+    }
+    terminal.write('\n')
+  }
+  terminal.subtle(UPDATE_HINT)
+
+  return 1
+}

package/src/commands/print.ts

@@ -0,0 +1,58 @@
+import { findConfigPath, loadConfig } from '@eslint-config-snapshot/api'
+
+import { formatShortConfig, formatShortPrint } from '../formatters.js'
+import { writeRunContextHeader } from '../run-context.js'
+import { computeCurrentSnapshots, loadStoredSnapshots, resolveWorkspaceAssignments, type WorkspaceAssignments } from '../runtime.js'
+import { type TerminalIO } from '../terminal.js'
+
+export type PrintFormat = 'json' | 'short'
+
+export async function executePrint(cwd: string, terminal: TerminalIO, snapshotDir: string, format: PrintFormat): Promise<void> {
+  const foundConfig = await findConfigPath(cwd)
+  const storedSnapshots = await loadStoredSnapshots(cwd, snapshotDir)
+  writeRunContextHeader(terminal, cwd, `print:${format}`, foundConfig?.path, storedSnapshots)
+  if (terminal.showProgress) {
+    terminal.subtle('🔎 Checking current ESLint configuration...\n')
+  }
+  const currentSnapshots = await computeCurrentSnapshots(cwd)
+
+  if (format === 'short') {
+    terminal.write(formatShortPrint([...currentSnapshots.values()]))
+    return
+  }
+
+  const output = [...currentSnapshots.values()].map((snapshot) => ({
+    groupId: snapshot.groupId,
+    rules: snapshot.rules
+  }))
+  terminal.write(`${JSON.stringify(output, null, 2)}\n`)
+}
+
+export async function executeConfig(cwd: string, terminal: TerminalIO, snapshotDir: string, format: PrintFormat): Promise<void> {
+  const foundConfig = await findConfigPath(cwd)
+  const storedSnapshots = await loadStoredSnapshots(cwd, snapshotDir)
+  writeRunContextHeader(terminal, cwd, `config:${format}`, foundConfig?.path, storedSnapshots)
+  if (terminal.showProgress) {
+    terminal.subtle('⚙️ Resolving effective runtime configuration...\n')
+  }
+  const config = await loadConfig(cwd)
+  const resolved: WorkspaceAssignments = await resolveWorkspaceAssignments(cwd, config)
+  const payload = {
+    source: foundConfig?.path ?? 'built-in-defaults',
+    workspaceInput: config.workspaceInput,
+    workspaces: resolved.discovery.workspacesRel,
+    grouping: {
+      mode: config.grouping.mode,
+      allowEmptyGroups: config.grouping.allowEmptyGroups ?? false,
+      groups: resolved.assignments.map((entry) => ({ name: entry.name, workspaces: entry.workspaces }))
+    },
+    sampling: config.sampling
+  }
+
+  if (format === 'short') {
+    terminal.write(formatShortConfig(payload))
+    return
+  }
+
+  terminal.write(`${JSON.stringify(payload, null, 2)}\n`)
+}

package/src/commands/update.ts

@@ -0,0 +1,49 @@
+import { findConfigPath } from '@eslint-config-snapshot/api'
+
+import { countUniqueWorkspaces, summarizeSnapshots } from '../formatters.js'
+import { writeEslintVersionSummary, writeRunContextHeader } from '../run-context.js'
+import { computeCurrentSnapshots, loadStoredSnapshots, resolveGroupEslintVersions, writeSnapshots } from '../runtime.js'
+import { type TerminalIO } from '../terminal.js'
+
+export async function executeUpdate(cwd: string, terminal: TerminalIO, snapshotDir: string, printSummary: boolean): Promise<number> {
+  const foundConfig = await findConfigPath(cwd)
+  const storedSnapshots = await loadStoredSnapshots(cwd, snapshotDir)
+  writeRunContextHeader(terminal, cwd, 'update', foundConfig?.path, storedSnapshots)
+  if (terminal.showProgress) {
+    terminal.subtle('🔎 Checking current ESLint configuration...\n')
+  }
+
+  if (!foundConfig) {
+    terminal.subtle(
+      'Tip: no explicit config found. Using safe built-in defaults. Run `eslint-config-snapshot init` to customize when needed.\n'
+    )
+  }
+
+  let currentSnapshots
+  try {
+    currentSnapshots = await computeCurrentSnapshots(cwd)
+  } catch (error: unknown) {
+    if (!foundConfig) {
+      terminal.write(
+        'Automatic workspace discovery could not complete with defaults.\nRun `eslint-config-snapshot init` to configure workspaces, then run `eslint-config-snapshot --update`.\n'
+      )
+      return 1
+    }
+
+    throw error
+  }
+  await writeSnapshots(cwd, snapshotDir, currentSnapshots)
+
+  if (printSummary) {
+    const summary = summarizeSnapshots(currentSnapshots)
+    const workspaceCount = countUniqueWorkspaces(currentSnapshots)
+    const eslintVersionsByGroup = terminal.showProgress ? await resolveGroupEslintVersions(cwd) : new Map<string, string[]>()
+    terminal.section('📊 Summary')
+    terminal.write(
+      `Baseline updated: ${summary.groups} groups, ${summary.rules} rules.\nWorkspaces scanned: ${workspaceCount}.\nSeverity mix: ${summary.error} errors, ${summary.warn} warnings, ${summary.off} off.\n`
+    )
+    writeEslintVersionSummary(terminal, eslintVersionsByGroup)
+  }
+
+  return 0
+}

package/src/formatters.ts

@@ -0,0 +1,256 @@
+import type { SnapshotDiff, SnapshotRuleEntry } from '@eslint-config-snapshot/api'
+
+export type RuleEntry = [severity: 'off' | 'warn' | 'error'] | [severity: 'off' | 'warn' | 'error', options: unknown]
+export type RuleObject = Record<string, SnapshotRuleEntry>
+
+export type SnapshotLike = {
+  groupId: string
+  workspaces: string[]
+  rules: RuleObject
+}
+
+export function formatDiff(groupId: string, diff: SnapshotDiff): string {
+  const lines = [`group: ${groupId}`]
+
+  addListSection(lines, 'introduced rules', diff.introducedRules)
+  addListSection(lines, 'removed rules', diff.removedRules)
+
+  if (diff.severityChanges.length > 0) {
+    lines.push('severity changed:')
+    for (const change of diff.severityChanges) {
+      lines.push(`  - ${change.rule}: ${change.before} -> ${change.after}`)
+    }
+  }
+
+  const optionChanges = getDisplayOptionChanges(diff)
+  if (optionChanges.length > 0) {
+    lines.push('options changed:')
+    for (const change of optionChanges) {
+      lines.push(`  - ${change.rule}: ${formatValue(change.before)} -> ${formatValue(change.after)}`)
+    }
+  }
+
+  addListSection(lines, 'workspaces added', diff.workspaceMembershipChanges.added)
+  addListSection(lines, 'workspaces removed', diff.workspaceMembershipChanges.removed)
+
+  return lines.join('\n')
+}
+
+export function getDisplayOptionChanges(diff: SnapshotDiff): SnapshotDiff['optionChanges'] {
+  const removedRules = new Set(diff.removedRules)
+  const severityChangedRules = new Set(diff.severityChanges.map((change) => change.rule))
+  return diff.optionChanges.filter((change) => !removedRules.has(change.rule) && !severityChangedRules.has(change.rule))
+}
+
+function addListSection(lines: string[], title: string, values: string[]): void {
+  if (values.length === 0) {
+    return
+  }
+
+  lines.push(`${title}:`)
+  for (const value of values) {
+    lines.push(`  - ${value}`)
+  }
+}
+
+function formatValue(value: unknown): string {
+  const serialized = JSON.stringify(value)
+  return serialized === undefined ? 'undefined' : serialized
+}
+
+export function summarizeChanges(changes: Array<{ groupId: string; diff: SnapshotDiff }>) {
+  let introduced = 0
+  let removed = 0
+  let severity = 0
+  let options = 0
+  let workspace = 0
+  for (const change of changes) {
+    introduced += change.diff.introducedRules.length
+    removed += change.diff.removedRules.length
+    severity += change.diff.severityChanges.length
+    options += getDisplayOptionChanges(change.diff).length
+    workspace += change.diff.workspaceMembershipChanges.added.length + change.diff.workspaceMembershipChanges.removed.length
+  }
+  return { introduced, removed, severity, options, workspace }
+}
+
+export function summarizeSnapshots(snapshots: Map<string, SnapshotLike>) {
+  const { rules, error, warn, off } = countRuleSeverities([...snapshots.values()].map((snapshot) => snapshot.rules))
+  return { groups: snapshots.size, rules, error, warn, off }
+}
+
+export function countUniqueWorkspaces(snapshots: Map<string, SnapshotLike>): number {
+  const workspaces = new Set<string>()
+  for (const snapshot of snapshots.values()) {
+    for (const workspace of snapshot.workspaces) {
+      workspaces.add(workspace)
+    }
+  }
+  return workspaces.size
+}
+
+export function decorateDiffLine(
+  line: string,
+  color: { green: (text: string) => string; red: (text: string) => string; yellow: (text: string) => string }
+): string {
+  if (line.startsWith('introduced rules:') || line.startsWith('workspaces added:')) {
+    return color.green(`+ ${line}`)
+  }
+  if (line.startsWith('removed rules:') || line.startsWith('workspaces removed:')) {
+    return color.red(`- ${line}`)
+  }
+  if (line.startsWith('severity changed:') || line.startsWith('options changed:')) {
+    return color.yellow(`~ ${line}`)
+  }
+  return line
+}
+
+export function formatShortPrint(snapshots: SnapshotLike[]): string {
+  const lines: string[] = []
+  const sorted = [...snapshots].sort((a, b) => a.groupId.localeCompare(b.groupId))
+
+  for (const snapshot of sorted) {
+    const ruleNames = Object.keys(snapshot.rules).sort()
+    const severityCounts = { error: 0, warn: 0, off: 0 }
+
+    for (const name of ruleNames) {
+      const severity = getPrimarySeverity(snapshot.rules[name])
+      if (severity) {
+        severityCounts[severity] += 1
+      }
+    }
+
+    lines.push(
+      `group: ${snapshot.groupId}`,
+      `workspaces (${snapshot.workspaces.length}): ${snapshot.workspaces.length > 0 ? snapshot.workspaces.join(', ') : '(none)'}`,
+      `rules (${ruleNames.length}): error ${severityCounts.error}, warn ${severityCounts.warn}, off ${severityCounts.off}`
+    )
+
+    for (const ruleName of ruleNames) {
+      const entry = snapshot.rules[ruleName]
+      if (!entry) {
+        continue
+      }
+      if (!Array.isArray(entry[0])) {
+        const singleEntry = entry as RuleEntry
+        const suffix = singleEntry.length > 1 ? ` ${JSON.stringify(singleEntry[1])}` : ''
+        lines.push(`${ruleName}: ${singleEntry[0]}${suffix}`)
+        continue
+      }
+
+      const variants = entry as RuleEntry[]
+      lines.push(`${ruleName}: ${JSON.stringify(variants)}`)
+    }
+  }
+
+  return `${lines.join('\n')}\n`
+}
+
+export function formatShortConfig(payload: {
+  source: string
+  workspaceInput: unknown
+  workspaces: string[]
+  grouping: { mode: string; allowEmptyGroups: boolean; groups: Array<{ name: string; workspaces: string[] }> }
+  sampling: unknown
+}): string {
+  const lines: string[] = [
+    `source: ${payload.source}`,
+    `workspaces (${payload.workspaces.length}): ${payload.workspaces.join(', ') || '(none)'}`,
+    `grouping mode: ${payload.grouping.mode} (allow empty: ${payload.grouping.allowEmptyGroups})`
+  ]
+  for (const group of payload.grouping.groups) {
+    lines.push(`group ${group.name} (${group.workspaces.length}): ${group.workspaces.join(', ') || '(none)'}`)
+  }
+  lines.push(`workspaceInput: ${JSON.stringify(payload.workspaceInput)}`, `sampling: ${JSON.stringify(payload.sampling)}`)
+  return `${lines.join('\n')}\n`
+}
+
+export function formatCommandDisplayLabel(commandLabel: string): string {
+  switch (commandLabel) {
+    case 'check':
+    case 'check:summary': {
+      return 'Check drift against baseline (summary)'
+    }
+    case 'check:diff': {
+      return 'Check drift against baseline (detailed diff)'
+    }
+    case 'check:status': {
+      return 'Check drift against baseline (status only)'
+    }
+    case 'update': {
+      return 'Update baseline snapshot'
+    }
+    case 'print:json': {
+      return 'Print aggregated rules (JSON)'
+    }
+    case 'print:short': {
+      return 'Print aggregated rules (short view)'
+    }
+    case 'config:json': {
+      return 'Show effective runtime config (JSON)'
+    }
+    case 'config:short': {
+      return 'Show effective runtime config (short view)'
+    }
+    case 'init': {
+      return 'Initialize local configuration'
+    }
+    case 'help': {
+      return 'Show CLI help'
+    }
+    default: {
+      return commandLabel
+    }
+  }
+}
+
+export function formatStoredSnapshotSummary(storedSnapshots: Map<string, SnapshotLike>): string {
+  if (storedSnapshots.size === 0) {
+    return 'none'
+  }
+
+  const summary = summarizeSnapshots(storedSnapshots)
+  return `${summary.groups} groups, ${summary.rules} rules (severity mix: ${summary.error} errors, ${summary.warn} warnings, ${summary.off} off)`
+}
+
+export function countRuleSeverities(ruleObjects: RuleObject[]) {
+  let rules = 0
+  let error = 0
+  let warn = 0
+  let off = 0
+
+  for (const rulesObject of ruleObjects) {
+    for (const entry of Object.values(rulesObject)) {
+      rules += 1
+      const severity = getPrimarySeverity(entry)
+      if (severity === 'error') {
+        error += 1
+      } else if (severity === 'warn') {
+        warn += 1
+      } else {
+        off += 1
+      }
+    }
+  }
+
+  return { rules, error, warn, off }
+}
+
+function getPrimarySeverity(entry: SnapshotRuleEntry | undefined): 'off' | 'warn' | 'error' | undefined {
+  if (!entry) {
+    return undefined
+  }
+
+  if (!Array.isArray(entry[0])) {
+    return (entry as RuleEntry)[0]
+  }
+
+  const variants = entry as RuleEntry[]
+  if (variants.some((variant) => variant[0] === 'error')) {
+    return 'error'
+  }
+  if (variants.some((variant) => variant[0] === 'warn')) {
+    return 'warn'
+  }
+  return 'off'
+}