@eslint-config-snapshot/api 0.1.0

package/src/config.ts

@@ -0,0 +1,139 @@
+import { cosmiconfig } from 'cosmiconfig'
+import path from 'node:path'
+
+
+export type SnapshotConfig = {
+  workspaceInput:
+    | {
+        mode: 'discover'
+      }
+    | {
+        mode: 'manual'
+        rootAbs?: string
+        workspaces: string[]
+      }
+  grouping: {
+    mode: 'match' | 'standalone'
+    allowEmptyGroups?: boolean
+    groups?: Array<{
+      name: string
+      match: string[]
+    }>
+  }
+  sampling: {
+    maxFilesPerWorkspace: number
+    includeGlobs: string[]
+    excludeGlobs: string[]
+    hintGlobs: string[]
+  }
+}
+
+export const DEFAULT_CONFIG: SnapshotConfig = {
+  workspaceInput: { mode: 'discover' },
+  grouping: {
+    mode: 'match',
+    groups: [{ name: 'default', match: ['**/*'] }]
+  },
+  sampling: {
+    maxFilesPerWorkspace: 8,
+    includeGlobs: ['**/*.{js,jsx,ts,tsx,cjs,mjs}'],
+    excludeGlobs: ['**/node_modules/**', '**/dist/**'],
+    hintGlobs: []
+  }
+}
+
+const SPEC_SEARCH_PLACES = [
+  '.eslint-config-snapshot.js',
+  '.eslint-config-snapshot.cjs',
+  '.eslint-config-snapshot.mjs',
+  'eslint-config-snapshot.config.js',
+  'eslint-config-snapshot.config.cjs',
+  'eslint-config-snapshot.config.mjs',
+  'package.json',
+  '.eslint-config-snapshotrc',
+  '.eslint-config-snapshotrc.json',
+  '.eslint-config-snapshotrc.yaml',
+  '.eslint-config-snapshotrc.yml',
+  '.eslint-config-snapshotrc.js',
+  '.eslint-config-snapshotrc.cjs',
+  '.eslint-config-snapshotrc.mjs'
+]
+
+export async function loadConfig(cwd?: string): Promise<SnapshotConfig> {
+  const found = await findConfigPath(cwd)
+  if (!found) {
+    return DEFAULT_CONFIG
+  }
+
+  return found.config
+}
+
+export async function findConfigPath(
+  cwd?: string
+): Promise<{ path: string; config: SnapshotConfig } | null> {
+  const root = path.resolve(cwd ?? process.cwd())
+  const explorer = cosmiconfig('eslint-config-snapshot', {
+    searchPlaces: SPEC_SEARCH_PLACES,
+    stopDir: root
+  })
+
+  const result = await explorer.search(root)
+  if (!result) {
+    return null
+  }
+
+  const maybeConfig = await loadUserConfig(result.config)
+
+  const config: SnapshotConfig = {
+    ...DEFAULT_CONFIG,
+    ...maybeConfig,
+    grouping: {
+      ...DEFAULT_CONFIG.grouping,
+      ...maybeConfig.grouping
+    },
+    sampling: {
+      ...DEFAULT_CONFIG.sampling,
+      ...maybeConfig.sampling
+    }
+  }
+
+  return {
+    path: result.filepath,
+    config
+  }
+}
+
+async function loadUserConfig(rawConfig: unknown): Promise<Partial<SnapshotConfig>> {
+  const resolved = typeof rawConfig === 'function' ? await rawConfig() : rawConfig
+  if (resolved === null || resolved === undefined) {
+    return {}
+  }
+
+  if (typeof resolved !== 'object' || Array.isArray(resolved)) {
+    throw new TypeError('Invalid config export: expected object, function, or async function returning an object')
+  }
+
+  return resolved as Partial<SnapshotConfig>
+}
+
+export type ConfigPreset = 'minimal' | 'full'
+
+export function getConfigScaffold(preset: ConfigPreset = 'minimal'): string {
+  if (preset === 'minimal') {
+    return 'export default {}\n'
+  }
+
+  return `export default {
+  workspaceInput: { mode: 'discover' },
+  grouping: {
+    mode: 'match',
+    groups: [{ name: 'default', match: ['**/*'] }]
+  },
+  sampling: {
+    maxFilesPerWorkspace: 8,
+    includeGlobs: ['**/*.{js,jsx,ts,tsx,cjs,mjs}'],
+    excludeGlobs: ['**/node_modules/**', '**/dist/**'],
+    hintGlobs: []
+  }
+}\n`
+}

package/src/core.ts

@@ -0,0 +1,55 @@
+export type JsonPrimitive = null | boolean | number | string
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue }
+
+export function normalizePath(input: string): string {
+  const withSlashes = input.replaceAll('\\', '/')
+  const collapsed = withSlashes.replaceAll(/\/+/g, '/')
+  const withoutTrailing = collapsed.endsWith('/') ? collapsed.slice(0, -1) : collapsed
+  return withoutTrailing === '' ? '.' : withoutTrailing
+}
+
+export function sortUnique(list: readonly string[]): string[] {
+  return [...new Set(list.map((item) => normalizePath(item)))].sort()
+}
+
+export function canonicalizeJson<T>(value: T): T {
+  if (value === null || value === undefined) {
+    return value
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => canonicalizeJson(entry)) as T
+  }
+
+  if (typeof value === 'object') {
+    const record = value as Record<string, unknown>
+    const result: Record<string, unknown> = {}
+    for (const key of Object.keys(record).sort()) {
+      const entry = record[key]
+      if (entry !== undefined) {
+        result[key] = canonicalizeJson(entry)
+      }
+    }
+    return result as T
+  }
+
+  return value
+}
+
+export function compareSeverity(a: string, b: string): number {
+  const rank: Record<string, number> = { off: 0, warn: 1, error: 2 }
+  return rank[a] - rank[b]
+}
+
+export function normalizeSeverity(value: unknown): 'off' | 'warn' | 'error' {
+  if (value === 0 || value === 'off') {
+    return 'off'
+  }
+  if (value === 1 || value === 'warn') {
+    return 'warn'
+  }
+  if (value === 2 || value === 'error') {
+    return 'error'
+  }
+  throw new Error(`Unsupported severity: ${String(value)}`)
+}

package/src/diff.ts

@@ -0,0 +1,103 @@
+import { canonicalizeJson, sortUnique } from './core.js'
+
+import type { SnapshotFile } from './snapshot.js'
+
+export type RuleSeverityChange = {
+  rule: string
+  before: string
+  after: string
+}
+
+export type RuleOptionChange = {
+  rule: string
+  before: unknown
+  after: unknown
+}
+
+export type WorkspaceMembershipChange = {
+  added: string[]
+  removed: string[]
+}
+
+export type SnapshotDiff = {
+  introducedRules: string[]
+  removedRules: string[]
+  severityChanges: RuleSeverityChange[]
+  optionChanges: RuleOptionChange[]
+  workspaceMembershipChanges: WorkspaceMembershipChange
+}
+
+export function diffSnapshots(before: SnapshotFile, after: SnapshotFile): SnapshotDiff {
+  const beforeRules = before.rules
+  const afterRules = after.rules
+
+  const beforeNames = Object.keys(beforeRules).sort()
+  const afterNames = Object.keys(afterRules).sort()
+
+  const introducedRules = afterNames.filter((name) => !beforeNames.includes(name))
+  const removedRules = beforeNames.filter((name) => !afterNames.includes(name))
+
+  const severityChanges: RuleSeverityChange[] = []
+  const optionChanges: RuleOptionChange[] = []
+
+  for (const name of beforeNames.filter((entry) => afterNames.includes(entry))) {
+    const oldEntry = beforeRules[name]
+    const newEntry = afterRules[name]
+
+    if (oldEntry[0] !== newEntry[0]) {
+      severityChanges.push({
+        rule: name,
+        before: oldEntry[0],
+        after: newEntry[0]
+      })
+    }
+
+    const oldOptions = oldEntry.length > 1 ? canonicalizeJson(oldEntry[1]) : undefined
+    const newOptions = newEntry.length > 1 ? canonicalizeJson(newEntry[1]) : undefined
+
+    if (oldEntry[0] === 'off' || newEntry[0] === 'off') {
+      // Treat off->off option removal/addition as removed/introduced config intent.
+      if (oldEntry[0] === 'off' && newEntry[0] === 'off') {
+        if (oldOptions !== undefined && newOptions === undefined) {
+          removedRules.push(name)
+        } else if (oldOptions === undefined && newOptions !== undefined) {
+          introducedRules.push(name)
+        }
+      }
+      continue
+    }
+
+    if (JSON.stringify(oldOptions) !== JSON.stringify(newOptions)) {
+      optionChanges.push({
+        rule: name,
+        before: oldOptions,
+        after: newOptions
+      })
+    }
+  }
+
+  const beforeWorkspaces = sortUnique(before.workspaces)
+  const afterWorkspaces = sortUnique(after.workspaces)
+
+  return {
+    introducedRules: sortUnique(introducedRules),
+    removedRules: sortUnique(removedRules),
+    severityChanges,
+    optionChanges,
+    workspaceMembershipChanges: {
+      added: afterWorkspaces.filter((ws) => !beforeWorkspaces.includes(ws)),
+      removed: beforeWorkspaces.filter((ws) => !afterWorkspaces.includes(ws))
+    }
+  }
+}
+
+export function hasDiff(diff: SnapshotDiff): boolean {
+  return (
+    diff.introducedRules.length > 0 ||
+    diff.removedRules.length > 0 ||
+    diff.severityChanges.length > 0 ||
+    diff.optionChanges.length > 0 ||
+    diff.workspaceMembershipChanges.added.length > 0 ||
+    diff.workspaceMembershipChanges.removed.length > 0
+  )
+}

package/src/extract.ts

@@ -0,0 +1,119 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+import { canonicalizeJson, normalizeSeverity } from './core.js'
+
+export type NormalizedRuleEntry = [severity: 'off' | 'warn' | 'error'] | [severity: 'off' | 'warn' | 'error', options: unknown]
+
+export type ExtractedWorkspaceRules = Map<string, NormalizedRuleEntry>
+
+export function resolveEslintBinForWorkspace(workspaceAbs: string): string {
+  const anchor = path.join(workspaceAbs, '__snapshot_anchor__.cjs')
+  const req = createRequire(anchor)
+  try {
+    return req.resolve('eslint/bin/eslint.js')
+  } catch {
+    try {
+      const eslintEntry = req.resolve('eslint')
+      const eslintRoot = findPackageRoot(eslintEntry)
+      const packageJsonPath = path.join(eslintRoot, 'package.json')
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { bin?: string | Record<string, string> }
+      const relativeBin = resolveBinPath(packageJson.bin)
+      const binAbs = path.resolve(eslintRoot, relativeBin)
+
+      if (existsSync(binAbs)) {
+        return binAbs
+      }
+    } catch {
+      // ignore fallback errors and throw deterministic workspace-scoped message below
+    }
+
+    throw new Error(`Unable to resolve eslint from workspace: ${workspaceAbs}`)
+  }
+}
+
+function resolveBinPath(bin: string | Record<string, string> | undefined): string {
+  if (typeof bin === 'string') {
+    return bin
+  }
+
+  if (typeof bin?.eslint === 'string') {
+    return bin.eslint
+  }
+
+  return 'bin/eslint.js'
+}
+
+function findPackageRoot(entryAbs: string): string {
+  let current = path.dirname(entryAbs)
+  while (true) {
+    const packageJsonPath = path.join(current, 'package.json')
+    if (existsSync(packageJsonPath)) {
+      return current
+    }
+
+    const parent = path.dirname(current)
+    if (parent === current) {
+      throw new Error('Package root not found')
+    }
+    current = parent
+  }
+}
+
+export function extractRulesFromPrintConfig(workspaceAbs: string, fileAbs: string): ExtractedWorkspaceRules {
+  const eslintBin = resolveEslintBinForWorkspace(workspaceAbs)
+  const proc = spawnSync(process.execPath, [eslintBin, '--print-config', fileAbs], {
+    cwd: workspaceAbs,
+    encoding: 'utf8'
+  })
+
+  if (proc.status !== 0) {
+    throw new Error(`Failed to run eslint --print-config for ${fileAbs}`)
+  }
+
+  const stdout = proc.stdout.trim()
+  if (stdout.length === 0 || stdout === 'undefined') {
+    throw new Error(`Empty ESLint print-config output for ${fileAbs}`)
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(stdout)
+  } catch {
+    throw new Error(`Invalid JSON from eslint --print-config for ${fileAbs}`)
+  }
+
+  const rules = (parsed as { rules?: Record<string, unknown> }).rules ?? {}
+  const normalized = new Map<string, NormalizedRuleEntry>()
+
+  for (const [ruleName, ruleConfig] of Object.entries(rules)) {
+    normalized.set(ruleName, normalizeRuleEntry(ruleConfig))
+  }
+
+  return normalized
+}
+
+function normalizeRuleEntry(raw: unknown): NormalizedRuleEntry {
+  if (Array.isArray(raw)) {
+    if (raw.length === 0) {
+      throw new Error('Rule configuration array cannot be empty')
+    }
+
+    const severity = normalizeSeverity(raw[0])
+    const rest = raw.slice(1).map((item) => canonicalizeJson(item))
+
+    if (rest.length === 0) {
+      return [severity]
+    }
+
+    if (rest.length === 1) {
+      return [severity, rest[0]]
+    }
+
+    return [severity, canonicalizeJson(rest)]
+  }
+
+  return [normalizeSeverity(raw)]
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { canonicalizeJson, compareSeverity, normalizePath, normalizeSeverity, sortUnique } from './core.js'
+export type { JsonPrimitive, JsonValue } from './core.js'
+
+export { assignGroupsByMatch, discoverWorkspaces } from './workspace.js'
+export type { GroupAssignment, GroupDefinition, WorkspaceDiscovery, WorkspaceInput } from './workspace.js'
+
+export { sampleWorkspaceFiles } from './sampling.js'
+export type { SamplingConfig } from './sampling.js'
+
+export { extractRulesFromPrintConfig, resolveEslintBinForWorkspace } from './extract.js'
+export type { ExtractedWorkspaceRules, NormalizedRuleEntry } from './extract.js'
+
+export { aggregateRules, buildSnapshot, readSnapshotFile, writeSnapshotFile } from './snapshot.js'
+export type { SnapshotFile } from './snapshot.js'
+
+export { diffSnapshots, hasDiff } from './diff.js'
+export type { RuleOptionChange, RuleSeverityChange, SnapshotDiff, WorkspaceMembershipChange } from './diff.js'
+
+export { DEFAULT_CONFIG, findConfigPath, getConfigScaffold, loadConfig } from './config.js'
+export type { ConfigPreset, SnapshotConfig } from './config.js'

package/src/sampling.ts

@@ -0,0 +1,136 @@
+import fg from 'fast-glob'
+import picomatch from 'picomatch'
+
+import { normalizePath, sortUnique } from './core.js'
+
+export type SamplingConfig = {
+  maxFilesPerWorkspace: number
+  includeGlobs: string[]
+  excludeGlobs: string[]
+  hintGlobs: string[]
+}
+
+export async function sampleWorkspaceFiles(workspaceAbs: string, config: SamplingConfig): Promise<string[]> {
+  const all = await fg(config.includeGlobs, {
+    cwd: workspaceAbs,
+    ignore: config.excludeGlobs,
+    onlyFiles: true,
+    dot: true,
+    unique: true
+  })
+
+  const normalized = sortUnique(all.map((entry) => normalizePath(entry)))
+  if (normalized.length === 0) {
+    return []
+  }
+
+  if (normalized.length <= config.maxFilesPerWorkspace) {
+    return normalized
+  }
+
+  if (config.hintGlobs.length === 0) {
+    return selectDistributed(normalized, config.maxFilesPerWorkspace)
+  }
+
+  const hinted = normalized.filter((entry) => config.hintGlobs.some((pattern) => picomatch(pattern, { dot: true })(entry)))
+  const notHinted = normalized.filter((entry) => !hinted.includes(entry))
+
+  return selectDistributed([...hinted, ...notHinted], config.maxFilesPerWorkspace)
+}
+
+function selectDistributed(files: string[], count: number): string[] {
+  if (files.length <= count) {
+    return files
+  }
+
+  const selected: string[] = []
+  const selectedSet = new Set<string>()
+
+  // First pass: attempt token diversity using simple filename tokenization.
+  const tokenSeen = new Set<string>()
+  for (const file of files) {
+    if (selected.length >= count) {
+      break
+    }
+    const token = getPrimaryToken(file)
+    if (!token || tokenSeen.has(token)) {
+      continue
+    }
+    tokenSeen.add(token)
+    selected.push(file)
+    selectedSet.add(file)
+  }
+
+  if (selected.length >= count) {
+    return sortUnique(selected).slice(0, count)
+  }
+
+  const remaining = files.filter((file) => !selectedSet.has(file))
+  const needed = count - selected.length
+  const spaced = pickUniformly(remaining, needed)
+  return sortUnique([...selected, ...spaced]).slice(0, count)
+}
+
+function pickUniformly(files: string[], count: number): string[] {
+  if (count <= 0 || files.length === 0) {
+    return []
+  }
+  if (files.length <= count) {
+    return files
+  }
+  if (count === 1) {
+    return [files[0]]
+  }
+
+  const picked: string[] = []
+  const usedIndices = new Set<number>()
+
+  for (let index = 0; index < count; index += 1) {
+    const raw = Math.round((index * (files.length - 1)) / (count - 1))
+    const safeIndex = nextFreeIndex(raw, usedIndices, files.length)
+    usedIndices.add(safeIndex)
+    picked.push(files[safeIndex])
+  }
+
+  return picked
+}
+
+function nextFreeIndex(candidate: number, used: Set<number>, max: number): number {
+  if (!used.has(candidate)) {
+    return candidate
+  }
+
+  for (let delta = 1; delta < max; delta += 1) {
+    const forward = candidate + delta
+    if (forward < max && !used.has(forward)) {
+      return forward
+    }
+    const backward = candidate - delta
+    if (backward >= 0 && !used.has(backward)) {
+      return backward
+    }
+  }
+
+  return candidate
+}
+
+function getPrimaryToken(file: string): string | null {
+  const parts = file.split('/')
+  const basename = parts.slice(-1)[0]
+  if (!basename) {
+    return null
+  }
+  const nameOnly = basename.replace(/\.[^.]+$/u, '')
+  const expanded = nameOnly
+    .replaceAll(/([a-z])([A-Z])/gu, '$1 $2')
+    .replaceAll(/[_\-.]+/gu, ' ')
+    .toLowerCase()
+
+  const token = expanded
+    .split(/\s+/u)
+    .find((entry) => entry.length > 1 && !GENERIC_TOKENS.has(entry))
+
+  return token ?? null
+}
+
+const GENERIC_TOKENS = new Set(['src', 'index', 'main', 'test', 'spec', 'package', 'packages', 'lib', 'dist'])

package/src/snapshot.ts

@@ -0,0 +1,76 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { canonicalizeJson, compareSeverity, sortUnique } from './core.js'
+
+import type { NormalizedRuleEntry } from './extract.js'
+
+export type SnapshotFile = {
+  formatVersion: 1
+  groupId: string
+  workspaces: string[]
+  rules: Record<string, NormalizedRuleEntry>
+}
+
+export function aggregateRules(ruleMaps: readonly Map<string, NormalizedRuleEntry>[]): Map<string, NormalizedRuleEntry> {
+  const aggregated = new Map<string, NormalizedRuleEntry>()
+
+  for (const rules of ruleMaps) {
+    for (const [ruleName, nextEntry] of rules.entries()) {
+      const currentEntry = aggregated.get(ruleName)
+      if (!currentEntry) {
+        aggregated.set(ruleName, canonicalizeJson(nextEntry))
+        continue
+      }
+
+      const severityCmp = compareSeverity(nextEntry[0], currentEntry[0])
+      if (severityCmp > 0) {
+        aggregated.set(ruleName, canonicalizeJson(nextEntry))
+        continue
+      }
+
+      if (severityCmp < 0) {
+        continue
+      }
+
+      const currentOptions = currentEntry.length > 1 ? canonicalizeJson(currentEntry[1]) : undefined
+      const nextOptions = nextEntry.length > 1 ? canonicalizeJson(nextEntry[1]) : undefined
+
+      if (JSON.stringify(currentOptions) !== JSON.stringify(nextOptions)) {
+        throw new Error(`Conflicting rule options for ${ruleName} at severity ${currentEntry[0]}`)
+      }
+    }
+  }
+
+  return new Map([...aggregated.entries()].sort(([a], [b]) => a.localeCompare(b)))
+}
+
+export function buildSnapshot(groupId: string, workspaces: readonly string[], rules: Map<string, NormalizedRuleEntry>): SnapshotFile {
+  const sortedRules = [...rules.entries()].sort(([a], [b]) => a.localeCompare(b))
+  const rulesObject: Record<string, NormalizedRuleEntry> = {}
+
+  for (const [name, config] of sortedRules) {
+    rulesObject[name] = canonicalizeJson(config)
+  }
+
+  return {
+    formatVersion: 1,
+    groupId,
+    workspaces: sortUnique(workspaces),
+    rules: rulesObject
+  }
+}
+
+export async function writeSnapshotFile(snapshotDirAbs: string, snapshot: SnapshotFile): Promise<string> {
+  await mkdir(snapshotDirAbs, { recursive: true })
+  const filePath = path.join(snapshotDirAbs, `${snapshot.groupId}.json`)
+  await mkdir(path.dirname(filePath), { recursive: true })
+  const payload = JSON.stringify(snapshot, null, 2)
+  await writeFile(filePath, `${payload}\n`, 'utf8')
+  return filePath
+}
+
+export async function readSnapshotFile(fileAbs: string): Promise<SnapshotFile> {
+  const raw = await readFile(fileAbs, 'utf8')
+  return JSON.parse(raw) as SnapshotFile
+}