@eslint-config-snapshot/api 0.9.0 → 0.14.1

package/src/sampling.ts

@@ -1,16 +1,19 @@
+import createDebug from 'debug'
 import fg from 'fast-glob'
-import picomatch from 'picomatch'
 
 import { normalizePath, sortUnique } from './core.js'
 
+const debugSampling = createDebug('eslint-config-snapshot:sampling')
+
 export type SamplingConfig = {
   maxFilesPerWorkspace: number
   includeGlobs: string[]
   excludeGlobs: string[]
-  hintGlobs: string[]
+  tokenHints?: string[] | string[][]
 }
 
 export async function sampleWorkspaceFiles(workspaceAbs: string, config: SamplingConfig): Promise<string[]> {
+  const startedAt = Date.now()
   const all = await fg(config.includeGlobs, {
     cwd: workspaceAbs,
     ignore: config.excludeGlobs,
@@ -20,46 +23,43 @@ export async function sampleWorkspaceFiles(workspaceAbs: string, config: Samplin
   })
 
   const normalized = sortUnique(all.map((entry) => normalizePath(entry)))
+  debugSampling('workspace=%s candidates=%d', workspaceAbs, normalized.length)
   if (normalized.length === 0) {
     return []
   }
 
   if (normalized.length <= config.maxFilesPerWorkspace) {
+    debugSampling('workspace=%s using all files=%d elapsedMs=%d', workspaceAbs, normalized.length, Date.now() - startedAt)
     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)
+  const selected = selectDistributed(normalized, config.maxFilesPerWorkspace, config.tokenHints)
+  debugSampling(
+    'workspace=%s selected=%d mode=token-distributed elapsedMs=%d files=%o',
+    workspaceAbs,
+    selected.length,
+    Date.now() - startedAt,
+    selected
+  )
+  return selected
 }
 
-function selectDistributed(files: string[], count: number): string[] {
+function selectDistributed(files: string[], count: number, tokenHints?: string[] | string[][]): string[] {
   if (files.length <= count) {
     return files
   }
 
+  const tokenPriorityMap = createTokenPriorityMap(tokenHints)
   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)
-  }
+  const preferred = files.filter((file) => isPreferredForLintSampling(file))
+  const nonPreferred = files.filter((file) => !isPreferredForLintSampling(file))
+
+  // First pass: pick token-diverse representatives from code files.
+  // Second pass: include non-code only when needed to fill remaining slots.
+  appendTokenRepresentatives(preferred, tokenPriorityMap, selected, selectedSet, count)
+  appendTokenRepresentatives(nonPreferred, tokenPriorityMap, selected, selectedSet, count)
 
   if (selected.length >= count) {
     return sortUnique(selected).slice(0, count)
@@ -67,8 +67,13 @@ function selectDistributed(files: string[], count: number): string[] {
 
   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)
+  const preferredRemaining = remaining.filter((file) => isPreferredForLintSampling(file))
+  const nonPreferredRemaining = remaining.filter((file) => !isPreferredForLintSampling(file))
+
+  const preferredPicked = pickUniformly(preferredRemaining, needed)
+  const afterPreferredNeed = needed - preferredPicked.length
+  const fallbackPicked = afterPreferredNeed > 0 ? pickUniformly(nonPreferredRemaining, afterPreferredNeed) : []
+  return sortUnique([...selected, ...preferredPicked, ...fallbackPicked]).slice(0, count)
 }
 
 function pickUniformly(files: string[], count: number): string[] {
@@ -85,16 +90,67 @@ function pickUniformly(files: string[], count: number): string[] {
   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)
+  // Ensure regional coverage when possible: top, middle, bottom.
+  if (count >= 3) {
+    const anchorIndices = [0, Math.floor((files.length - 1) / 2), files.length - 1]
+    for (const anchorIndex of anchorIndices) {
+      if (picked.length >= count || usedIndices.has(anchorIndex)) {
+        continue
+      }
+      usedIndices.add(anchorIndex)
+      const anchored = files[anchorIndex]
+      if (anchored !== undefined) {
+        picked.push(anchored)
+      }
+    }
+  }
+
+  for (const candidate of buildDistributedCandidates(files.length, count)) {
+    if (picked.length >= count) {
+      break
+    }
+    const safeIndex = nextFreeIndex(candidate, usedIndices, files.length)
+    if (usedIndices.has(safeIndex)) {
+      continue
+    }
     usedIndices.add(safeIndex)
-    picked.push(files[safeIndex])
+    const selected = files[safeIndex]
+    if (selected !== undefined) {
+      picked.push(selected)
+    }
+  }
+
+  if (picked.length < count) {
+    for (let index = 0; index < files.length && picked.length < count; index += 1) {
+      if (usedIndices.has(index)) {
+        continue
+      }
+      usedIndices.add(index)
+      const fallback = files[index]
+      if (fallback !== undefined) {
+        picked.push(fallback)
+      }
+    }
   }
 
   return picked
 }
 
+function buildDistributedCandidates(length: number, count: number): number[] {
+  if (length <= 0 || count <= 0) {
+    return []
+  }
+  if (count === 1) {
+    return [0]
+  }
+
+  const candidates: number[] = []
+  for (let index = 0; index < count; index += 1) {
+    candidates.push(Math.round((index * (length - 1)) / (count - 1)))
+  }
+  return candidates
+}
+
 function nextFreeIndex(candidate: number, used: Set<number>, max: number): number {
   if (!used.has(candidate)) {
     return candidate
@@ -114,23 +170,278 @@ function nextFreeIndex(candidate: number, used: Set<number>, max: number): numbe
   return candidate
 }
 
-function getPrimaryToken(file: string): string | null {
-  const parts = file.split('/')
-  const basename = parts.slice(-1)[0]
-  if (!basename) {
+function getPrimaryToken(file: string, tokenPriorityMap: Map<string, number>): string | null {
+  const parts = file.split('/').filter((entry) => entry.length > 0)
+  if (parts.length === 0) {
+    return null
+  }
+
+  const basename = parts[parts.length - 1]
+  if (basename === undefined) {
     return null
   }
-  const nameOnly = basename.replace(/\.[^.]+$/u, '')
-  const expanded = nameOnly
+  const basenameTokens = tokenizePathPart(basename, true)
+  const directoryTokensForward = parts.slice(0, -1).flatMap((entry) => tokenizePathPart(entry, false))
+  const directoryTokens: string[] = []
+  for (let index = directoryTokensForward.length - 1; index >= 0; index -= 1) {
+    const token = directoryTokensForward[index]
+    if (token !== undefined) {
+      directoryTokens.push(token)
+    }
+  }
+  const allTokens = [...basenameTokens, ...directoryTokens].filter((entry) => entry.length > 1)
+
+  const bestKnownToken = pickBestKnownToken(allTokens, tokenPriorityMap)
+  if (bestKnownToken !== null) {
+    return bestKnownToken
+  }
+
+  const fallback = allTokens.find((entry) => !GENERIC_TOKENS.has(entry))
+  return fallback ?? null
+}
+
+function tokenizePathPart(part: string, stripExtension: boolean): string[] {
+  const normalized = stripExtension ? part.replace(/\.[^.]+$/u, '') : part
+  const expanded = normalized
     .replaceAll(/([a-z])([A-Z])/gu, '$1 $2')
     .replaceAll(/[_\-.]+/gu, ' ')
     .toLowerCase()
 
-  const token = expanded
+  return expanded
     .split(/\s+/u)
-    .find((entry) => entry.length > 1 && !GENERIC_TOKENS.has(entry))
+    .filter((entry) => entry.length > 0)
+}
+
+function pickBestKnownToken(tokens: string[], tokenPriorityMap: Map<string, number>): string | null {
+  let bestToken: string | null = null
+  let bestGroupPriority = Number.POSITIVE_INFINITY
 
-  return token ?? null
+  for (const token of tokens) {
+    const normalizedToken = normalizeToken(token)
+    const groupPriority = tokenPriorityMap.get(normalizedToken)
+    if (groupPriority === undefined) {
+      continue
+    }
+    if (groupPriority < bestGroupPriority) {
+      bestGroupPriority = groupPriority
+      bestToken = normalizedToken
+    }
+  }
+
+  return bestToken
+}
+
+function normalizeToken(token: string): string {
+  if (token.endsWith('ies') && token.length > 3) {
+    return `${token.slice(0, -3)}y`
+  }
+  if (token.endsWith('s') && token.length > 3) {
+    return token.slice(0, -1)
+  }
+  return token
+}
+
+function isPreferredForLintSampling(file: string): boolean {
+  return CODE_PREFERRED_EXTENSIONS.has(getExtension(file))
+}
+
+function getExtension(file: string): string {
+  const lastDot = file.lastIndexOf('.')
+  if (lastDot === -1 || lastDot === file.length - 1) {
+    return ''
+  }
+  return file.slice(lastDot + 1).toLowerCase()
 }
 
 const GENERIC_TOKENS = new Set(['src', 'index', 'main', 'test', 'spec', 'package', 'packages', 'lib', 'dist'])
+const CODE_PREFERRED_EXTENSIONS = new Set(['ts', 'tsx', 'js', 'jsx', 'cjs', 'mjs'])
+
+const DEFAULT_TOKEN_HINT_GROUPS = [
+  [
+    'chunk',
+    'conf',
+    'config',
+    'container',
+    'controller',
+    'helpers',
+    'mock',
+    'mocks',
+    'presentation',
+    'repository',
+    'route',
+    'routes',
+    'schema',
+    'setup',
+    'spec',
+    'stories',
+    'style',
+    'styles',
+    'test',
+    'type',
+    'types',
+    'utils',
+    'view',
+    'views'
+  ],
+  [
+    'adapter',
+    'api',
+    'apis',
+    'builder',
+    'client',
+    'component',
+    'components',
+    'constants',
+    'context',
+    'core',
+    'dto',
+    'entity',
+    'entry',
+    'env',
+    'factory',
+    'fetcher',
+    'handler',
+    'hook',
+    'hooks',
+    'init',
+    'integration',
+    'interceptor',
+    'interface',
+    'layout',
+    'layouts',
+    'listener',
+    'logger',
+    'manager',
+    'mapper',
+    'meta',
+    'middleware',
+    'model',
+    'module',
+    'normalizer',
+    'options',
+    'page',
+    'pages',
+    'parser',
+    'plugin',
+    'provider',
+    'registry',
+    'resolver',
+    'router',
+    'runtime',
+    'serializer',
+    'server',
+    'service',
+    'settings',
+    'shared',
+    'slice',
+    'state',
+    'store',
+    'subscriber',
+    'theme',
+    'tracker',
+    'transform',
+    'unit',
+    'validator'
+  ],
+  [
+    'base',
+    'bundle',
+    'common',
+    'compiler',
+    'contract',
+    'definition',
+    'definitions',
+    'deserializer',
+    'event',
+    'events',
+    'fixture',
+    'fixtures',
+    'guard',
+    'internal',
+    'loader',
+    'publisher',
+    'reducer',
+    'stub',
+    'stubs',
+    'tests',
+    'util'
+  ]
+] as const
+
+function createTokenPriorityMap(input?: string[] | string[][]): Map<string, number> {
+  const groups = normalizeTokenHintGroups(input)
+  const entries: Array<[string, number]> = []
+  for (const [index, group] of groups.entries()) {
+    entries.push(...toPriorityEntries(group, index + 1))
+  }
+  return new Map<string, number>(entries)
+}
+
+function normalizeTokenHintGroups(input?: string[] | string[][]): string[][] {
+  if (!input || input.length === 0) {
+    return DEFAULT_TOKEN_HINT_GROUPS.map((group) => [...group])
+  }
+
+  if (Array.isArray(input[0])) {
+    const nested = input as string[][]
+    return nested.map((group) => group.filter((token) => token.trim().length > 0))
+  }
+
+  const flat = input as string[]
+  return [flat.filter((token) => token.trim().length > 0)]
+}
+
+function toPriorityEntries(tokens: string[], priority: number): Array<[string, number]> {
+  return tokens.map((token) => [normalizeToken(token), priority])
+}
+
+function appendTokenRepresentatives(
+  files: string[],
+  tokenPriorityMap: Map<string, number>,
+  selected: string[],
+  selectedSet: Set<string>,
+  count: number
+): void {
+  if (selected.length >= count || files.length === 0) {
+    return
+  }
+
+  const tokenToFiles = new Map<string, string[]>()
+  const tokenFirstIndex = new Map<string, number>()
+  for (const [index, file] of files.entries()) {
+    const token = getPrimaryToken(file, tokenPriorityMap)
+    if (!token) {
+      continue
+    }
+    tokenFirstIndex.set(token, Math.min(tokenFirstIndex.get(token) ?? Number.POSITIVE_INFINITY, index))
+    const current = tokenToFiles.get(token) ?? []
+    current.push(file)
+    tokenToFiles.set(token, current)
+  }
+
+  const orderedTokens = [...tokenToFiles.keys()].sort((left, right) => {
+    const leftPriority = tokenPriorityMap.get(left) ?? Number.POSITIVE_INFINITY
+    const rightPriority = tokenPriorityMap.get(right) ?? Number.POSITIVE_INFINITY
+    if (leftPriority !== rightPriority) {
+      return leftPriority - rightPriority
+    }
+    const leftIndex = tokenFirstIndex.get(left) ?? Number.POSITIVE_INFINITY
+    const rightIndex = tokenFirstIndex.get(right) ?? Number.POSITIVE_INFINITY
+    if (leftIndex !== rightIndex) {
+      return leftIndex - rightIndex
+    }
+    return left.localeCompare(right)
+  })
+
+  for (const token of orderedTokens) {
+    if (selected.length >= count) {
+      break
+    }
+    const firstFile = tokenToFiles.get(token)?.[0]
+    if (!firstFile || selectedSet.has(firstFile)) {
+      continue
+    }
+    selected.push(firstFile)
+    selectedSet.add(firstFile)
+  }
+}

package/src/snapshot.ts

@@ -1,71 +1,54 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 
-import { canonicalizeJson, compareSeverity, sortUnique } from './core.js'
+import { canonicalizeJson, sortUnique } from './core.js'
 
 import type { NormalizedRuleEntry } from './extract.js'
 
+export type SnapshotRuleEntry = NormalizedRuleEntry | NormalizedRuleEntry[]
+
 export type SnapshotFile = {
   formatVersion: 1
   groupId: string
   workspaces: string[]
-  rules: Record<string, NormalizedRuleEntry>
+  rules: Record<string, SnapshotRuleEntry>
 }
 
-export function aggregateRules(ruleMaps: readonly Map<string, NormalizedRuleEntry>[]): Map<string, NormalizedRuleEntry> {
-  const aggregated = new Map<string, NormalizedRuleEntry>()
+export function aggregateRules(ruleMaps: readonly Map<string, NormalizedRuleEntry>[]): Map<string, SnapshotRuleEntry> {
+  const aggregated = new Map<string, 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 (currentOptions === undefined && nextOptions !== undefined) {
-        aggregated.set(ruleName, canonicalizeJson(nextEntry))
-        continue
-      }
-
-      if (currentOptions !== undefined && nextOptions === undefined) {
-        continue
-      }
+      const normalizedEntry = canonicalizeJson(nextEntry)
+      const variantKey = toVariantKey(normalizedEntry)
+      const variants = aggregated.get(ruleName) ?? new Map<string, NormalizedRuleEntry>()
+      variants.set(variantKey, normalizedEntry)
+      aggregated.set(ruleName, variants)
+    }
+  }
 
-      if (currentOptions === undefined && nextOptions === undefined) {
-        continue
+  const entries = [...aggregated.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map<[string, SnapshotRuleEntry]>(([ruleName, variants]) => {
+      const sortedVariants = [...variants.values()].sort(compareVariants)
+      if (sortedVariants.length === 1) {
+        return [ruleName, sortedVariants[0]]
       }
 
-      const currentJson = JSON.stringify(currentOptions)
-      const nextJson = JSON.stringify(nextOptions)
-      if (nextJson < currentJson) {
-        aggregated.set(ruleName, canonicalizeJson(nextEntry))
-      }
-    }
-  }
+      return [ruleName, sortedVariants]
+    })
 
-  return new Map([...aggregated.entries()].sort(([a], [b]) => a.localeCompare(b)))
+  return new Map(entries)
 }
 
-export function buildSnapshot(groupId: string, workspaces: readonly string[], rules: Map<string, NormalizedRuleEntry>): SnapshotFile {
+export function buildSnapshot(groupId: string, workspaces: readonly string[], rules: Map<string, SnapshotRuleEntry>): SnapshotFile {
   const sortedRules = [...rules.entries()].sort(([a], [b]) => a.localeCompare(b))
-  const rulesObject: Record<string, NormalizedRuleEntry> = {}
+  const rulesObject: Record<string, SnapshotRuleEntry> = {}
 
   for (const [name, config] of sortedRules) {
-    rulesObject[name] = canonicalizeJson(config)
+    rulesObject[name] = isSingleRuleEntry(config)
+      ? canonicalizeJson(config)
+      : config.map((variant) => canonicalizeJson(variant)).sort(compareVariants)
   }
 
   return {
@@ -89,3 +72,17 @@ export async function readSnapshotFile(fileAbs: string): Promise<SnapshotFile> {
   const raw = await readFile(fileAbs, 'utf8')
   return JSON.parse(raw) as SnapshotFile
 }
+
+function toVariantKey(entry: NormalizedRuleEntry): string {
+  return JSON.stringify(canonicalizeJson(entry))
+}
+
+function compareVariants(a: NormalizedRuleEntry, b: NormalizedRuleEntry): number {
+  const aJson = JSON.stringify(canonicalizeJson(a))
+  const bJson = JSON.stringify(canonicalizeJson(b))
+  return aJson.localeCompare(bJson)
+}
+
+function isSingleRuleEntry(entry: SnapshotRuleEntry): entry is NormalizedRuleEntry {
+  return !Array.isArray(entry[0])
+}

package/test/config.test.ts

@@ -15,6 +15,10 @@ afterEach(async () => {
 })
 
 describe('loadConfig', () => {
+  it('includes markdown files in default sampling globs', () => {
+    expect(DEFAULT_CONFIG.sampling.includeGlobs).toContain('**/*.{js,jsx,ts,tsx,cjs,mjs,md,mdx,json,css}')
+  })
+
   it('returns defaults when no config is found', async () => {
     tmp = await mkdtemp(path.join(os.tmpdir(), 'snapshot-config-'))
     const config = await loadConfig(tmp)
@@ -69,24 +73,24 @@ describe('loadConfig', () => {
     tmp = await mkdtemp(path.join(os.tmpdir(), 'snapshot-config-'))
     await writeFile(
       path.join(tmp, '.eslint-config-snapshot.js'),
-      'export default () => ({ grouping: { mode: "standalone" }, sampling: { hintGlobs: ["src/**"] } })\n'
+      'export default () => ({ grouping: { mode: "standalone" }, sampling: { includeGlobs: ["src/**"] } })\n'
     )
 
     const config = await loadConfig(tmp)
     expect(config.grouping.mode).toBe('standalone')
-    expect(config.sampling.hintGlobs).toEqual(['src/**'])
+    expect(config.sampling.includeGlobs).toEqual(['src/**'])
   })
 
   it('executes async function exports', async () => {
     tmp = await mkdtemp(path.join(os.tmpdir(), 'snapshot-config-'))
     await writeFile(
       path.join(tmp, '.eslint-config-snapshot.mjs'),
-      'export default async () => ({ sampling: { maxFilesPerWorkspace: 3, hintGlobs: ["src/**"] } })\n'
+      'export default async () => ({ sampling: { maxFilesPerWorkspace: 3, includeGlobs: ["src/**"] } })\n'
     )
 
     const config = await loadConfig(tmp)
     expect(config.sampling.maxFilesPerWorkspace).toBe(3)
-    expect(config.sampling.hintGlobs).toEqual(['src/**'])
+    expect(config.sampling.includeGlobs).toEqual(['src/**'])
   })
 
   it('throws deterministic error when config export is invalid', async () => {

package/test/diff.test.ts

@@ -55,6 +55,54 @@ describe('diffSnapshots', () => {
 
     const diff = diffSnapshots(before, after)
     expect(diff.removedRules).toContain('offRule')
-    expect(diff.optionChanges).toEqual([{ rule: 'configured', before: { allow: false }, after: { allow: true } }])
+    expect(diff.optionChanges).toEqual([
+      {
+        rule: 'configured',
+        before: [['error', { allow: false }]],
+        after: [['error', { allow: true }]]
+      }
+    ])
+  })
+
+  it('tracks severity-set and variant changes for multi-variant rules', () => {
+    const before = {
+      formatVersion: 1 as const,
+      groupId: 'default',
+      workspaces: ['packages/a'],
+      rules: {
+        mixed: [
+          ['error', { mode: 'strict' }],
+          ['warn', { mode: 'legacy' }]
+        ] as const
+      }
+    }
+
+    const after = {
+      formatVersion: 1 as const,
+      groupId: 'default',
+      workspaces: ['packages/a'],
+      rules: {
+        mixed: [
+          ['error', { mode: 'strict' }],
+          ['off']
+        ] as const
+      }
+    }
+
+    const diff = diffSnapshots(before, after)
+    expect(diff.severityChanges).toEqual([{ rule: 'mixed', before: 'error|warn', after: 'error|off' }])
+    expect(diff.optionChanges).toEqual([
+      {
+        rule: 'mixed',
+        before: [
+          ['error', { mode: 'strict' }],
+          ['warn', { mode: 'legacy' }]
+        ],
+        after: [
+          ['error', { mode: 'strict' }],
+          ['off']
+        ]
+      }
+    ])
   })
 })