@eduardbar/drift 1.3.0 → 1.5.0

package/src/doctor.ts

@@ -0,0 +1,185 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import kleur from 'kleur'
+import type { DriftOutputMetadata } from './types.js'
+import { OUTPUT_SCHEMA, withOutputMetadata } from './output-metadata.js'
+
+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
+  }
+}
+
+export type DoctorReportJson = DoctorReport & DriftOutputMetadata
+
+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 = 20
+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 supported minimum (>=20)')}`
+  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 function formatDoctorJsonObject(report: DoctorReport): DoctorReportJson {
+  return withOutputMetadata(report, OUTPUT_SCHEMA.doctor)
+}
+
+export function formatDoctorJson(report: DoctorReport): string {
+  return JSON.stringify(formatDoctorJsonObject(report), null, 2)
+}
+
+export async function runDoctor(projectPath: string, options?: DoctorOptions): Promise<number> {
+  const report = buildDoctorReport(projectPath)
+
+  if (options?.json) {
+    process.stdout.write(`${formatDoctorJson(report)}\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/guard-baseline.ts

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { GuardBaseline, IssueSeverity } from './guard-types.js'
+
+export interface NormalizedBaseline {
+  score?: number
+  totalIssues?: number
+  bySeverity: Partial<Record<IssueSeverity, number>>
+}
+
+function parseNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && !Number.isNaN(value) ? value : undefined
+}
+
+function firstDefinedNumber(values: unknown[]): number | undefined {
+  for (const value of values) {
+    const parsed = parseNumber(value)
+    if (parsed !== undefined) {
+      return parsed
+    }
+  }
+
+  return undefined
+}
+
+function normalizeSeverity(baseline: GuardBaseline, severity: IssueSeverity): number | undefined {
+  const summaryBySeverity = baseline.summary?.[`${severity}s` as 'errors' | 'warnings' | 'infos']
+
+  return firstDefinedNumber([
+    baseline.bySeverity?.[severity],
+    severity === 'error' ? baseline.errors : undefined,
+    severity === 'warning' ? baseline.warnings : undefined,
+    severity === 'info' ? baseline.infos : undefined,
+    summaryBySeverity,
+  ])
+}
+
+function hasAnchor(baseline: NormalizedBaseline): boolean {
+  if (baseline.score !== undefined || baseline.totalIssues !== undefined) {
+    return true
+  }
+
+  const severities: IssueSeverity[] = ['error', 'warning', 'info']
+  return severities.some((severity) => baseline.bySeverity[severity] !== undefined)
+}
+
+export function normalizeBaseline(baseline: GuardBaseline): NormalizedBaseline {
+  const normalized: NormalizedBaseline = {
+    score: parseNumber(baseline.score),
+    totalIssues: parseNumber(baseline.totalIssues),
+    bySeverity: {
+      error: normalizeSeverity(baseline, 'error'),
+      warning: normalizeSeverity(baseline, 'warning'),
+      info: normalizeSeverity(baseline, 'info'),
+    },
+  }
+
+  if (!hasAnchor(normalized)) {
+    throw new Error('Invalid guard baseline: expected score, totalIssues, or severity counters (error/warning/info).')
+  }
+
+  return normalized
+}
+
+export function readBaselineFromFile(projectPath: string, baselinePath?: string): { baseline: NormalizedBaseline; path: string } | undefined {
+  const resolvedBaselinePath = resolve(projectPath, baselinePath ?? 'drift-baseline.json')
+  if (!existsSync(resolvedBaselinePath)) return undefined
+
+  const raw = JSON.parse(readFileSync(resolvedBaselinePath, 'utf8')) as GuardBaseline
+  return {
+    baseline: normalizeBaseline(raw),
+    path: resolvedBaselinePath,
+  }
+}

package/src/guard-metrics.ts

@@ -0,0 +1,52 @@
+import type { DriftDiff, DriftIssue, DriftReport } from './types.js'
+import type { GuardMetrics, IssueSeverity } from './guard-types.js'
+import type { NormalizedBaseline } from './guard-baseline.js'
+
+function createSeverityDelta(): Record<IssueSeverity, number> {
+  return {
+    error: 0,
+    warning: 0,
+    info: 0,
+  }
+}
+
+function applySeverityDelta(
+  delta: Record<IssueSeverity, number>,
+  issues: DriftIssue[],
+  direction: 1 | -1,
+): void {
+  for (const issue of issues) {
+    delta[issue.severity] += direction
+  }
+}
+
+function countSeverityDeltaFromDiff(diff: DriftDiff): Record<IssueSeverity, number> {
+  const severityDelta = createSeverityDelta()
+
+  for (const file of diff.files) {
+    applySeverityDelta(severityDelta, file.newIssues, 1)
+    applySeverityDelta(severityDelta, file.resolvedIssues, -1)
+  }
+
+  return severityDelta
+}
+
+export function buildMetricsFromDiff(diff: DriftDiff): GuardMetrics {
+  return {
+    scoreDelta: diff.totalDelta,
+    totalIssuesDelta: diff.newIssuesCount - diff.resolvedIssuesCount,
+    severityDelta: countSeverityDeltaFromDiff(diff),
+  }
+}
+
+export function buildMetricsFromBaseline(current: DriftReport, baseline: NormalizedBaseline): GuardMetrics {
+  return {
+    scoreDelta: current.totalScore - (baseline.score ?? current.totalScore),
+    totalIssuesDelta: current.totalIssues - (baseline.totalIssues ?? current.totalIssues),
+    severityDelta: {
+      error: current.summary.errors - (baseline.bySeverity.error ?? current.summary.errors),
+      warning: current.summary.warnings - (baseline.bySeverity.warning ?? current.summary.warnings),
+      info: current.summary.infos - (baseline.bySeverity.info ?? current.summary.infos),
+    },
+  }
+}

package/src/guard-types.ts

@@ -0,0 +1,66 @@
+import type { DriftAnalysisOptions, DriftDiff, DriftIssue, DriftOutputMetadata, 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
+}
+
+export type GuardResultJson = GuardResult & DriftOutputMetadata

package/src/guard.ts

@@ -0,0 +1,248 @@
+import { relative, resolve } from 'node:path'
+import { analyzeProject } from './analyzer.js'
+import { loadConfig } from './config.js'
+import { computeDiff } from './diff.js'
+import { cleanupTempDir, extractFilesAtRef } from './git.js'
+import { normalizeBaseline, readBaselineFromFile } from './guard-baseline.js'
+import { buildMetricsFromBaseline, buildMetricsFromDiff } from './guard-metrics.js'
+import { OUTPUT_SCHEMA, withOutputMetadata } from './output-metadata.js'
+import { buildReport } from './reporter.js'
+import type { DriftReport } from './types.js'
+import type {
+  GuardCheck,
+  GuardEvaluation,
+  GuardMetrics,
+  GuardOptions,
+  GuardResult,
+  GuardResultJson,
+  GuardThresholds,
+  IssueSeverity,
+} from './guard-types.js'
+import type { NormalizedBaseline } from './guard-baseline.js'
+
+interface GuardEvalInput {
+  metrics: GuardMetrics
+  budget?: number
+  bySeverity?: GuardThresholds
+  enforceNoRegression: {
+    score: boolean
+    totalIssues: boolean
+  }
+}
+
+interface GuardRuntimeState {
+  currentReport: DriftReport
+  config: Awaited<ReturnType<typeof loadConfig>>
+  projectPath: string
+}
+
+interface DiffGuardResultInput {
+  projectPath: string
+  currentReport: DriftReport
+  options: GuardOptions
+  tempDir: string
+  config: Awaited<ReturnType<typeof loadConfig>>
+  baseRef: string
+}
+
+interface BaselineGuardResultInput {
+  projectPath: string
+  currentReport: DriftReport
+  options: GuardOptions
+  baseline: NormalizedBaseline
+  baselinePath?: string
+}
+
+function remapBaseReportPaths(baseReport: DriftReport, tempDir: string, projectPath: string): DriftReport {
+  return {
+    ...baseReport,
+    files: baseReport.files.map((file) => ({
+      ...file,
+      path: resolve(projectPath, relative(tempDir, file.path)),
+    })),
+  }
+}
+
+
+interface GuardCheckInput {
+  id: string
+  actual: number
+  limit: number
+  message: string
+}
+
+function addCheck(checks: GuardCheck[], input: GuardCheckInput): void {
+  checks.push({
+    id: input.id,
+    passed: input.actual <= input.limit,
+    actual: input.actual,
+    limit: input.limit,
+    message: input.message,
+  })
+}
+
+export function evaluateGuard(input: GuardEvalInput): GuardEvaluation {
+  const checks: GuardCheck[] = []
+
+  if (input.enforceNoRegression.score) {
+    addCheck(checks, {
+      id: 'no-regression-score',
+      actual: input.metrics.scoreDelta,
+      limit: 0,
+      message: 'Score delta must be <= 0.',
+    })
+  }
+
+  if (input.enforceNoRegression.totalIssues) {
+    addCheck(checks, {
+      id: 'no-regression-total-issues',
+      actual: input.metrics.totalIssuesDelta,
+      limit: 0,
+      message: 'Total issues delta must be <= 0.',
+    })
+  }
+
+  if (typeof input.budget === 'number' && !Number.isNaN(input.budget)) {
+    addCheck(checks, {
+      id: 'budget-total-delta',
+      actual: input.metrics.scoreDelta,
+      limit: input.budget,
+      message: `Score delta must be <= budget (${input.budget}).`,
+    })
+  }
+
+  const severityThresholds = input.bySeverity
+  if (severityThresholds) {
+    const severities: IssueSeverity[] = ['error', 'warning', 'info']
+    for (const severity of severities) {
+      const threshold = severityThresholds[severity]
+      if (typeof threshold !== 'number' || Number.isNaN(threshold)) continue
+      addCheck(checks, {
+        id: `severity-${severity}`,
+        actual: input.metrics.severityDelta[severity],
+        limit: threshold,
+        message: `${severity} delta must be <= ${threshold}.`,
+      })
+    }
+  }
+
+  return {
+    passed: checks.every((check) => check.passed),
+    checks,
+  }
+}
+
+export function formatGuardJsonObject(result: GuardResult): GuardResultJson {
+  return withOutputMetadata(result, OUTPUT_SCHEMA.guard)
+}
+
+export function formatGuardJson(result: GuardResult): string {
+  return JSON.stringify(formatGuardJsonObject(result), null, 2)
+}
+
+export async function runGuard(targetPath: string, options: GuardOptions = {}): Promise<GuardResult> {
+  const runtimeState = await initializeGuardRuntime(targetPath, options)
+  const { projectPath, config, currentReport } = runtimeState
+
+  let tempDir: string | undefined
+  try {
+    if (options.baseRef) {
+      tempDir = extractFilesAtRef(projectPath, options.baseRef)
+      return createDiffGuardResult({
+        projectPath,
+        currentReport,
+        options,
+        tempDir,
+        config,
+        baseRef: options.baseRef,
+      })
+    }
+
+    const inlineBaseline = options.baseline ? normalizeBaseline(options.baseline) : undefined
+    const fileBaseline = inlineBaseline ? undefined : readBaselineFromFile(projectPath, options.baselinePath)
+    const baseline = inlineBaseline ?? fileBaseline?.baseline
+    const baselinePath = fileBaseline?.path
+
+    if (!baseline) {
+      throw new Error('Guard requires a comparison point: provide baseRef or a baseline (inline or file).')
+    }
+
+    return createBaselineGuardResult({
+      projectPath,
+      currentReport,
+      options,
+      baseline,
+      baselinePath,
+    })
+  } finally {
+    if (tempDir) cleanupTempDir(tempDir)
+  }
+}
+
+async function initializeGuardRuntime(targetPath: string, options: GuardOptions): Promise<GuardRuntimeState> {
+  const projectPath = resolve(targetPath)
+  const config = await loadConfig(projectPath)
+  const currentFiles = analyzeProject(projectPath, config, options.analysis)
+  const currentReport = buildReport(projectPath, currentFiles)
+
+  return {
+    projectPath,
+    config,
+    currentReport,
+  }
+}
+
+function createDiffGuardResult(input: DiffGuardResultInput): GuardResult {
+  const { projectPath, currentReport, options, tempDir, config, baseRef } = input
+  const baseFiles = analyzeProject(tempDir, config, options.analysis)
+  const baseReport = buildReport(tempDir, baseFiles)
+  const remappedBase = remapBaseReportPaths(baseReport, tempDir, projectPath)
+  const diff = computeDiff(remappedBase, currentReport, baseRef)
+  const metrics = buildMetricsFromDiff(diff)
+  const evaluation = evaluateGuard({
+    metrics,
+    budget: options.budget,
+    bySeverity: options.bySeverity,
+    enforceNoRegression: {
+      score: true,
+      totalIssues: true,
+    },
+  })
+
+  return {
+    scannedAt: new Date().toISOString(),
+    projectPath,
+    mode: 'diff',
+    passed: evaluation.passed,
+    baseRef,
+    metrics,
+    checks: evaluation.checks,
+    current: currentReport,
+    diff,
+  }
+}
+
+function createBaselineGuardResult(input: BaselineGuardResultInput): GuardResult {
+  const { projectPath, currentReport, options, baseline, baselinePath } = input
+  const metrics = buildMetricsFromBaseline(currentReport, baseline)
+  const evaluation = evaluateGuard({
+    metrics,
+    budget: options.budget,
+    bySeverity: options.bySeverity,
+    enforceNoRegression: {
+      score: baseline.score !== undefined,
+      totalIssues: baseline.totalIssues !== undefined,
+    },
+  })
+
+  return {
+    scannedAt: new Date().toISOString(),
+    projectPath,
+    mode: 'baseline',
+    passed: evaluation.passed,
+    baselinePath,
+    metrics,
+    checks: evaluation.checks,
+    current: currentReport,
+  }
+}