@eduardbar/drift 1.3.0 → 1.4.0

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/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
+}

package/src/guard.ts

@@ -0,0 +1,324 @@
+import { existsSync, readFileSync } from 'node:fs'
+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 { buildReport } from './reporter.js'
+import type { DriftDiff, DriftReport } from './types.js'
+import type {
+  GuardBaseline,
+  GuardCheck,
+  GuardEvaluation,
+  GuardMetrics,
+  GuardOptions,
+  GuardResult,
+  GuardThresholds,
+  IssueSeverity,
+} from './guard-types.js'
+
+interface NormalizedBaseline {
+  score?: number
+  totalIssues?: number
+  bySeverity: Partial<Record<IssueSeverity, number>>
+}
+
+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 parseNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && !Number.isNaN(value) ? value : undefined
+}
+
+function normalizeBaseline(baseline: GuardBaseline): NormalizedBaseline {
+  const bySeverityFromRoot = baseline.bySeverity
+  const bySeverity = {
+    error: parseNumber(bySeverityFromRoot?.error) ?? parseNumber(baseline.errors) ?? parseNumber(baseline.summary?.errors),
+    warning: parseNumber(bySeverityFromRoot?.warning) ?? parseNumber(baseline.warnings) ?? parseNumber(baseline.summary?.warnings),
+    info: parseNumber(bySeverityFromRoot?.info) ?? parseNumber(baseline.infos) ?? parseNumber(baseline.summary?.infos),
+  }
+
+  const normalized: NormalizedBaseline = {
+    score: parseNumber(baseline.score),
+    totalIssues: parseNumber(baseline.totalIssues),
+    bySeverity,
+  }
+
+  const hasAnyAnchor =
+    normalized.score !== undefined ||
+    normalized.totalIssues !== undefined ||
+    normalized.bySeverity.error !== undefined ||
+    normalized.bySeverity.warning !== undefined ||
+    normalized.bySeverity.info !== undefined
+
+  if (!hasAnyAnchor) {
+    throw new Error('Invalid guard baseline: expected score, totalIssues, or severity counters (error/warning/info).')
+  }
+
+  return normalized
+}
+
+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,
+  }
+}
+
+function remapBaseReportPaths(baseReport: DriftReport, tempDir: string, projectPath: string): DriftReport {
+  return {
+    ...baseReport,
+    files: baseReport.files.map((file) => ({
+      ...file,
+      path: resolve(projectPath, relative(tempDir, file.path)),
+    })),
+  }
+}
+
+function countSeverityDeltaFromDiff(diff: DriftDiff): Record<IssueSeverity, number> {
+  const severityDelta: Record<IssueSeverity, number> = {
+    error: 0,
+    warning: 0,
+    info: 0,
+  }
+
+  for (const file of diff.files) {
+    for (const issue of file.newIssues) {
+      severityDelta[issue.severity] += 1
+    }
+    for (const issue of file.resolvedIssues) {
+      severityDelta[issue.severity] -= 1
+    }
+  }
+
+  return severityDelta
+}
+
+function buildMetricsFromDiff(diff: DriftDiff): GuardMetrics {
+  return {
+    scoreDelta: diff.totalDelta,
+    totalIssuesDelta: diff.newIssuesCount - diff.resolvedIssuesCount,
+    severityDelta: countSeverityDeltaFromDiff(diff),
+  }
+}
+
+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),
+    },
+  }
+}
+
+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 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,
+  }
+}

package/src/index.ts

@@ -1,23 +1,51 @@
 export { analyzeProject, analyzeFile, RULE_WEIGHTS } from './analyzer.js'
 export { buildReport, formatMarkdown } from './reporter.js'
 export { computeDiff } from './diff.js'
+export { runGuard, evaluateGuard } from './guard.js'
+export type {
+  GuardBaseline,
+  GuardThresholds,
+  GuardOptions,
+  GuardMetrics,
+  GuardCheck,
+  GuardEvaluation,
+  GuardResult,
+} from './guard-types.js'
 export { generateReview, formatReviewMarkdown } from './review.js'
+export { runDoctor } from './doctor.js'
+export type { DoctorOptions } from './doctor.js'
 export {
   buildTrustReport,
   formatTrustConsole,
   formatTrustMarkdown,
   formatTrustJson,
+  resolveTrustGatePolicy,
+  evaluateTrustGate,
   shouldFailByMaxRisk,
   shouldFailTrustGate,
   normalizeMergeRiskLevel,
   MERGE_RISK_ORDER,
 } from './trust.js'
+export type {
+  TrustGateOptions,
+  TrustGatePolicyResolutionOptions,
+  TrustGatePolicyResolutionStep,
+  TrustGateEvaluation,
+} from './trust.js'
 export {
   computeTrustKpis,
   computeTrustKpisFromReports,
   formatTrustKpiConsole,
   formatTrustKpiJson,
 } from './trust-kpi.js'
+export { toSarif, diffToSarif } from './sarif.js'
+export type {
+  SarifLevel,
+  DriftSarifRule,
+  DriftSarifResult,
+  DriftSarifRun,
+  DriftSarifLog,
+} from './sarif.js'
 export { generateArchitectureMap, generateArchitectureSvg } from './map.js'
 export type {
   DriftReport,
@@ -39,6 +67,8 @@ export type {
   MergeRiskLevel,
   DriftPlugin,
   DriftPluginRule,
+  TrustGatePolicyConfig,
+  TrustAdvancedContext,
 } from './types.js'
 export { loadHistory, saveSnapshot } from './snapshot.js'
 export type { SnapshotEntry, SnapshotHistory } from './snapshot.js'
@@ -61,6 +91,11 @@ export {
   generateSaasDashboardHtml,
 } from './saas.js'
 export type {
+  SaasUser,
+  SaasOrganization,
+  SaasWorkspace,
+  SaasRepo,
+  SaasMembership,
   SaasRole,
   SaasPlan,
   SaasPolicy,