@eduardbar/drift 1.2.0 → 1.4.0

package/src/config.ts

@@ -3,6 +3,22 @@ import { join, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import type { DriftConfig } from './types.js'
 
+function normalizeLegacyConfig(config: DriftConfig): DriftConfig {
+  if (config.modules !== undefined) {
+    return config
+  }
+
+  const legacyModules = config.moduleBoundaries ?? config.boundaries
+  if (!legacyModules || legacyModules.length === 0) {
+    return config
+  }
+
+  return {
+    ...config,
+    modules: legacyModules,
+  }
+}
+
 /**
  * Load drift.config.ts / .js / .json from the given project root.
  * Returns undefined if no config file is found.
@@ -27,7 +43,8 @@ export async function loadConfig(projectRoot: string): Promise<DriftConfig | und
 
       if (ext === 'json') {
         const { readFileSync } = await import('node:fs')
-        return JSON.parse(readFileSync(candidate, 'utf-8')) as DriftConfig
+        const rawConfig = JSON.parse(readFileSync(candidate, 'utf-8')) as DriftConfig
+        return normalizeLegacyConfig(rawConfig)
       }
 
       // .ts / .js — dynamic import via file URL
@@ -35,7 +52,7 @@ export async function loadConfig(projectRoot: string): Promise<DriftConfig | und
       const mod = await import(fileUrl)
       const config: DriftConfig = mod.default ?? mod
 
-      return config
+      return normalizeLegacyConfig(config)
     } catch { // drift-ignore
       // drift-ignore: catch-swallow — config is optional; load failure is non-fatal
     }

package/src/diff.ts

@@ -1,9 +1,78 @@
 import type { DriftReport, DriftDiff, FileDiff, DriftIssue } from './types.js'
 
+function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, '/')
+}
+
+function normalizeIssueText(value: string): string {
+  return value
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+const SNIPPET_PREFIX_LENGTH = 80
+
+interface IssueMatchState {
+  matchedBaseIndexes: Set<number>
+  matchedCurrentIndexes: Set<number>
+}
+
+function strictIssueKey(i: DriftIssue): string {
+  return `${i.rule}:${i.line}:${i.column}`
+}
+
+function normalizedIssueKey(i: DriftIssue): string {
+  const normalizedMessage = normalizeIssueText(i.message)
+  const normalizedSnippetPrefix = normalizeIssueText(i.snippet).slice(0, SNIPPET_PREFIX_LENGTH)
+  return `${i.rule}:${i.severity}:${i.line}:${normalizedMessage}:${normalizedSnippetPrefix}`
+}
+
+function buildIssueIndex(
+  issues: DriftIssue[],
+  getKey: (issue: DriftIssue) => string,
+  skip?: Set<number>,
+): Map<string, number[]> {
+  const index = new Map<string, number[]>()
+  for (const [idx, issue] of issues.entries()) {
+    if (skip?.has(idx)) continue
+    const key = getKey(issue)
+    const bucket = index.get(key)
+    if (bucket) bucket.push(idx)
+    else index.set(key, [idx])
+  }
+  return index
+}
+
+function matchIssues(
+  currentIssues: DriftIssue[],
+  index: Map<string, number[]>,
+  state: IssueMatchState,
+  getKey: (issue: DriftIssue) => string,
+): void {
+  for (const [currentIndex, issue] of currentIssues.entries()) {
+    if (state.matchedCurrentIndexes.has(currentIndex)) continue
+    const bucket = index.get(getKey(issue))
+    if (!bucket || bucket.length === 0) continue
+
+    const matchedIndex = bucket.shift()
+    if (matchedIndex === undefined) continue
+
+    state.matchedBaseIndexes.add(matchedIndex)
+    state.matchedCurrentIndexes.add(currentIndex)
+  }
+}
+
 /**
  * Compute the diff between two DriftReports.
  *
- * Issues are matched by (rule + line + column) as a unique key within a file.
+ * Issues are matched in two passes:
+ * 1) strict location key (rule + line + column)
+ * 2) normalized content key (rule + severity + line + message + snippet)
+ *
+ * This keeps deterministic matching while preventing false churn caused by
+ * cross-platform line ending changes and small column offset noise.
  * A "new" issue exists in `current` but not in `base`.
  * A "resolved" issue exists in `base` but not in `current`.
  */
@@ -19,13 +88,18 @@ function computeFileDiff(
   const baseIssues = baseFile?.issues ?? []
   const currentIssues = currentFile?.issues ?? []
 
-  const issueKey = (i: DriftIssue) => `${i.rule}:${i.line}:${i.column}`
+  const matchedBaseIndexes = new Set<number>()
+  const matchedCurrentIndexes = new Set<number>()
+  const matchState = { matchedBaseIndexes, matchedCurrentIndexes }
+
+  const baseStrictIndex = buildIssueIndex(baseIssues, strictIssueKey)
+  matchIssues(currentIssues, baseStrictIndex, matchState, strictIssueKey)
 
-  const baseKeys = new Set(baseIssues.map(issueKey))
-  const currentKeys = new Set(currentIssues.map(issueKey))
+  const baseNormalizedIndex = buildIssueIndex(baseIssues, normalizedIssueKey, matchedBaseIndexes)
+  matchIssues(currentIssues, baseNormalizedIndex, matchState, normalizedIssueKey)
 
-  const newIssues = currentIssues.filter(i => !baseKeys.has(issueKey(i)))
-  const resolvedIssues = baseIssues.filter(i => !currentKeys.has(issueKey(i)))
+  const newIssues = currentIssues.filter((_, index) => !matchedCurrentIndexes.has(index))
+  const resolvedIssues = baseIssues.filter((_, index) => !matchedBaseIndexes.has(index))
 
   if (scoreDelta !== 0 || newIssues.length > 0 || resolvedIssues.length > 0) {
     return {
@@ -48,12 +122,12 @@ export function computeDiff(
 ): DriftDiff {
   const fileDiffs: FileDiff[] = []
 
-  const baseByPath = new Map(base.files.map(f => [f.path, f]))
-  const currentByPath = new Map(current.files.map(f => [f.path, f]))
+  const baseByPath = new Map(base.files.map(f => [normalizePath(f.path), f]))
+  const currentByPath = new Map(current.files.map(f => [normalizePath(f.path), f]))
 
   const allPaths = new Set([
-    ...base.files.map(f => f.path),
-    ...current.files.map(f => f.path),
+    ...base.files.map(f => normalizePath(f.path)),
+    ...current.files.map(f => normalizePath(f.path)),
   ])
 
   for (const filePath of allPaths) {

package/src/doctor.ts

@@ -0,0 +1,173 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import kleur from 'kleur'
+
+export interface DoctorOptions {
+  json?: boolean
+}
+
+interface DoctorReport {
+  targetPath: string
+  node: {
+    version: string
+    major: number
+    supported: boolean
+  }
+  project: {
+    packageJsonFound: boolean
+    esm: boolean
+    tsconfigFound: boolean
+    sourceFilesCount: number
+    lowMemorySuggested: boolean
+    driftConfigFile: string | null
+  }
+}
+
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx'])
+const IGNORED_DIRECTORIES = new Set(['node_modules', '.git', 'dist', '.next', 'coverage'])
+const DECIMAL_RADIX = 10
+const MIN_SUPPORTED_NODE_MAJOR = 18
+const LOW_MEMORY_SOURCE_FILE_THRESHOLD = 500
+const DRIFT_CONFIG_CANDIDATES = [
+  'drift.config.ts',
+  'drift.config.js',
+  'drift.config.mjs',
+  'drift.config.cjs',
+  'drift.config.json',
+] as const
+
+function parseNodeMajor(version: string): number {
+  const parsed = Number.parseInt(version.replace(/^v/, '').split('.')[0] ?? '0', DECIMAL_RADIX)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+function detectDriftConfig(projectPath: string): string | null {
+  for (const candidate of DRIFT_CONFIG_CANDIDATES) {
+    if (existsSync(join(projectPath, candidate))) {
+      return candidate
+    }
+  }
+  return null
+}
+
+function countSourceFiles(projectPath: string): number {
+  let total = 0
+  const stack = [projectPath]
+
+  while (stack.length > 0) {
+    const currentDir = stack.pop()
+    if (!currentDir) continue
+
+    const entries = readdirSync(currentDir, { withFileTypes: true })
+    for (const entry of entries) {
+      if (entry.isDirectory() && !IGNORED_DIRECTORIES.has(entry.name)) {
+        stack.push(join(currentDir, entry.name))
+        continue
+      }
+
+      if (entry.isDirectory()) {
+        continue
+      }
+
+      if (!entry.isFile()) continue
+
+      const lastDot = entry.name.lastIndexOf('.')
+      if (lastDot === -1) continue
+
+      const extension = entry.name.slice(lastDot)
+      if (SOURCE_EXTENSIONS.has(extension)) {
+        total += 1
+      }
+    }
+  }
+
+  return total
+}
+
+function buildDoctorReport(projectPath: string): DoctorReport {
+  const nodeMajor = parseNodeMajor(process.version)
+  const packageJsonPath = join(projectPath, 'package.json')
+  const packageJsonFound = existsSync(packageJsonPath)
+
+  let esm = false
+  if (packageJsonFound) {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { type?: string }
+    esm = parsed.type === 'module'
+  }
+
+  const sourceFilesCount = countSourceFiles(projectPath)
+
+  return {
+    targetPath: projectPath,
+    node: {
+      version: process.version,
+      major: nodeMajor,
+      supported: nodeMajor >= MIN_SUPPORTED_NODE_MAJOR,
+    },
+    project: {
+      packageJsonFound,
+      esm,
+      tsconfigFound: existsSync(join(projectPath, 'tsconfig.json')),
+      sourceFilesCount,
+      lowMemorySuggested: sourceFilesCount > LOW_MEMORY_SOURCE_FILE_THRESHOLD,
+      driftConfigFile: detectDriftConfig(projectPath),
+    },
+  }
+}
+
+function printConsoleReport(report: DoctorReport): void {
+  const icons = {
+    check: kleur.green('✓'),
+    warn: kleur.yellow('⚠'),
+    error: kleur.red('✗'),
+    info: kleur.cyan('ℹ'),
+  }
+
+  process.stdout.write('\n')
+  process.stdout.write(`${kleur.bold().white('drift doctor')} ${kleur.gray('- environment diagnostics')}\n\n`)
+
+  const nodeStatus = report.node.supported
+    ? `${icons.check} ${kleur.green('Node runtime supported')}`
+    : `${icons.warn} ${kleur.yellow('Node runtime below recommended minimum (>=18)')}`
+  process.stdout.write(`${nodeStatus} ${kleur.gray(`(${report.node.version})`)}\n`)
+
+  if (report.project.packageJsonFound) {
+    process.stdout.write(`${icons.check} package.json found\n`)
+    process.stdout.write(`${icons.info} ESM mode: ${report.project.esm ? kleur.green('yes') : kleur.yellow('no')}\n`)
+  } else {
+    process.stdout.write(`${icons.warn} package.json not found\n`)
+    process.stdout.write(`${icons.info} ESM mode: ${kleur.gray('unknown')}\n`)
+  }
+
+  if (report.project.tsconfigFound) {
+    process.stdout.write(`${icons.check} tsconfig.json found\n`)
+  } else {
+    process.stdout.write(`${icons.warn} tsconfig.json not found\n`)
+  }
+
+  process.stdout.write(`${icons.info} Source files (.ts/.tsx/.js/.jsx): ${report.project.sourceFilesCount}\n`)
+
+  if (report.project.lowMemorySuggested) {
+    process.stdout.write(`${icons.warn} Large codebase detected, consider ${kleur.bold('--low-memory')}\n`)
+  }
+
+  if (report.project.driftConfigFile) {
+    process.stdout.write(`${icons.check} Drift config: ${report.project.driftConfigFile}\n`)
+  } else {
+    process.stdout.write(`${icons.warn} Drift config not found (drift.config.*)\n`)
+  }
+
+  process.stdout.write('\n')
+}
+
+export async function runDoctor(projectPath: string, options?: DoctorOptions): Promise<number> {
+  const report = buildDoctorReport(projectPath)
+
+  if (options?.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  } else {
+    printConsoleReport(report)
+  }
+
+  return 0
+}

package/src/format.ts

@@ -0,0 +1,81 @@
+const UNIFIED_FORMAT_VALUES = ['console', 'json', 'markdown', 'ai', 'sarif'] as const
+
+type UnifiedOutputFormat = (typeof UNIFIED_FORMAT_VALUES)[number]
+
+type LegacyAlias = {
+  flag: string
+  used?: boolean
+  mapsTo: UnifiedOutputFormat
+}
+
+interface ResolveOutputFormatOptions {
+  command: string
+  format?: string
+  supported: readonly UnifiedOutputFormat[]
+  legacyAliases?: LegacyAlias[]
+  onWarning?: (message: string) => void
+}
+
+function assertSupportedFormatValue(command: string, format: string): asserts format is UnifiedOutputFormat {
+  if ((UNIFIED_FORMAT_VALUES as readonly string[]).includes(format)) return
+  throw new Error(
+    `Invalid --format '${format}' for '${command}'. Allowed values: ${UNIFIED_FORMAT_VALUES.join(', ')}.`,
+  )
+}
+
+function throwUnsupportedFormat(command: string, selected: UnifiedOutputFormat, supported: readonly UnifiedOutputFormat[]): never {
+  throw new Error(
+    `Format '${selected}' is not supported for '${command}'. Supported formats: ${supported.join(', ')}.`,
+  )
+}
+
+function normalizeLegacyFormatSelection(command: string, selectedLegacyFormats: UnifiedOutputFormat[]): UnifiedOutputFormat | undefined {
+  if (selectedLegacyFormats.length === 0) return undefined
+
+  const uniqueFormats = [...new Set(selectedLegacyFormats)]
+  if (uniqueFormats.length > 1) {
+    throw new Error(
+      `Conflicting legacy format flags for '${command}': ${uniqueFormats.join(' vs ')}. Use a single format option.`,
+    )
+  }
+
+  return uniqueFormats[0]
+}
+
+export function resolveOutputFormat(options: ResolveOutputFormatOptions): UnifiedOutputFormat {
+  const { command, format, supported, onWarning } = options
+  const legacyAliases = options.legacyAliases ?? []
+
+  for (const alias of legacyAliases) {
+    if (!alias.used) continue
+    onWarning?.(`Warning: --${alias.flag} is deprecated for '${command}'. Use --format ${alias.mapsTo} instead.`)
+  }
+
+  const selectedLegacyFormat = normalizeLegacyFormatSelection(
+    command,
+    legacyAliases.filter((alias) => alias.used).map((alias) => alias.mapsTo),
+  )
+
+  const selectedFormat = format?.trim()
+  if (selectedFormat) {
+    assertSupportedFormatValue(command, selectedFormat)
+    if (selectedLegacyFormat && selectedLegacyFormat !== selectedFormat) {
+      throw new Error(
+        `Conflicting format flags for '${command}': --format ${selectedFormat} and legacy alias for ${selectedLegacyFormat}.`,
+      )
+    }
+
+    if (!supported.includes(selectedFormat)) {
+      throwUnsupportedFormat(command, selectedFormat, supported)
+    }
+
+    return selectedFormat
+  }
+
+  const resolvedFromLegacy = selectedLegacyFormat ?? 'console'
+  if (!supported.includes(resolvedFromLegacy)) {
+    throwUnsupportedFormat(command, resolvedFromLegacy, supported)
+  }
+
+  return resolvedFromLegacy
+}

package/src/git.ts

@@ -63,6 +63,18 @@ function extractFile(projectPath: string, ref: string, filePath: string, tempDir
   writeFileSync(destPath, content, 'utf-8')
 }
 
+function extractArchiveAtRef(projectPath: string, ref: string, tempDir: string): boolean {
+  try {
+    execSync(
+      `git archive --format=tar ${ref} | tar -x -C "${tempDir}"`,
+      { cwd: projectPath, stdio: 'pipe' }
+    )
+    return true
+  } catch {
+    return false
+  }
+}
+
 export function extractFilesAtRef(projectPath: string, ref: string): string {
   verifyGitRepo(projectPath)
   verifyRefExists(projectPath, ref)
@@ -76,6 +88,10 @@ export function extractFilesAtRef(projectPath: string, ref: string): string {
   const tempDir = join(tmpdir(), `drift-diff-${randomUUID()}`)
   mkdirSync(tempDir, { recursive: true })
 
+  if (extractArchiveAtRef(projectPath, ref, tempDir)) {
+    return tempDir
+  }
+
   for (const filePath of tsFiles) {
     extractFile(projectPath, ref, filePath, tempDir)
   }

package/src/guard-types.ts

@@ -0,0 +1,64 @@
+import type { DriftAnalysisOptions, DriftDiff, DriftIssue, DriftReport } from './types.js'
+
+export type IssueSeverity = DriftIssue['severity']
+
+export interface GuardBaseline {
+  score?: number
+  totalIssues?: number
+  errors?: number
+  warnings?: number
+  infos?: number
+  bySeverity?: Partial<Record<IssueSeverity, number>>
+  summary?: {
+    errors?: number
+    warnings?: number
+    infos?: number
+  }
+}
+
+export interface GuardThresholds {
+  error?: number
+  warning?: number
+  info?: number
+}
+
+export interface GuardOptions {
+  baseRef?: string
+  baselinePath?: string
+  baseline?: GuardBaseline
+  budget?: number
+  bySeverity?: GuardThresholds
+  analysis?: DriftAnalysisOptions
+}
+
+export interface GuardMetrics {
+  scoreDelta: number
+  totalIssuesDelta: number
+  severityDelta: Record<IssueSeverity, number>
+}
+
+export interface GuardCheck {
+  id: string
+  passed: boolean
+  actual: number
+  limit: number
+  message: string
+}
+
+export interface GuardEvaluation {
+  passed: boolean
+  checks: GuardCheck[]
+}
+
+export interface GuardResult {
+  scannedAt: string
+  projectPath: string
+  mode: 'diff' | 'baseline'
+  passed: boolean
+  baseRef?: string
+  baselinePath?: string
+  metrics: GuardMetrics
+  checks: GuardCheck[]
+  current: DriftReport
+  diff?: DriftDiff
+}