@eduardbar/drift 1.4.0 → 1.5.0

package/scripts/check-performance-budget.mjs

@@ -0,0 +1,360 @@
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import { pathToFileURL } from 'node:url'
+
+const BUDGET_SCHEMA_VERSION = 'drift-perf-budget/v1'
+const BENCHMARK_RESULT_SCHEMA = 'drift-perf-check-result/v1'
+const DEFAULT_BUDGET_PATH = 'benchmarks/perf-budget.v1.json'
+const DEFAULT_RESULT_PATH = '.drift-perf/benchmark-latest.json'
+const TASK_IDS = ['scan', 'review', 'trust']
+
+function runGit(cwd, args) {
+  return spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+  })
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    budgetPath: DEFAULT_BUDGET_PATH,
+    resultPath: DEFAULT_RESULT_PATH,
+    benchmarkResultPath: undefined,
+  }
+
+  let index = 0
+  while (index < argv.length) {
+    const token = argv[index]
+    if (token === '--budget') {
+      const next = argv[index + 1]
+      if (!next) throw new Error('--budget requires a value')
+      parsed.budgetPath = next
+      index += 2
+      continue
+    }
+
+    if (token === '--out') {
+      const next = argv[index + 1]
+      if (!next) throw new Error('--out requires a value')
+      parsed.resultPath = next
+      index += 2
+      continue
+    }
+
+    if (token === '--result') {
+      const next = argv[index + 1]
+      if (!next) throw new Error('--result requires a value')
+      parsed.benchmarkResultPath = next
+      index += 2
+      continue
+    }
+
+    throw new Error(`Unknown argument: ${token}`)
+  }
+
+  return parsed
+}
+
+function readJson(filePath) {
+  return JSON.parse(readFileSync(filePath, 'utf8'))
+}
+
+function asNonNegativeNumber(value, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${label} must be a non-negative number`)
+  }
+  return value
+}
+
+function validateBudgetSchema(budget) {
+  if (budget?.schemaVersion !== BUDGET_SCHEMA_VERSION) {
+    throw new Error(`Unsupported budget schemaVersion. Expected '${BUDGET_SCHEMA_VERSION}'`)
+  }
+
+  for (const taskId of TASK_IDS) {
+    const taskBudget = budget?.tasks?.[taskId]
+    if (!taskBudget) {
+      throw new Error(`Missing budget entry for task '${taskId}'`)
+    }
+    asNonNegativeNumber(taskBudget.maxMedianMs, `tasks.${taskId}.maxMedianMs`)
+    asNonNegativeNumber(taskBudget.maxRssMb, `tasks.${taskId}.maxRssMb`)
+  }
+
+  asNonNegativeNumber(budget?.tolerance?.runtimePct ?? 0, 'tolerance.runtimePct')
+  asNonNegativeNumber(budget?.tolerance?.memoryPct ?? 0, 'tolerance.memoryPct')
+
+  asNonNegativeNumber(budget?.benchmark?.warmupRuns, 'benchmark.warmupRuns')
+  const measuredRuns = asNonNegativeNumber(budget?.benchmark?.measuredRuns, 'benchmark.measuredRuns')
+  if (measuredRuns < 1) {
+    throw new Error('benchmark.measuredRuns must be at least 1')
+  }
+}
+
+function benchmarkTaskMap(benchmarkResult) {
+  const map = new Map()
+  for (const taskResult of benchmarkResult?.results ?? []) {
+    map.set(taskResult.name, taskResult)
+  }
+  return map
+}
+
+export function evaluatePerformanceBudget(budget, benchmarkResult) {
+  validateBudgetSchema(budget)
+
+  const runtimeToleranceFactor = 1 + ((budget?.tolerance?.runtimePct ?? 0) / 100)
+  const memoryToleranceFactor = 1 + ((budget?.tolerance?.memoryPct ?? 0) / 100)
+  const byTask = benchmarkTaskMap(benchmarkResult)
+  const failures = []
+  const checks = []
+
+  for (const taskId of TASK_IDS) {
+    const taskBudget = budget.tasks[taskId]
+    const measured = byTask.get(taskId)
+    if (!measured) {
+      failures.push(`Benchmark output is missing task '${taskId}'`)
+      continue
+    }
+
+    const medianMs = asNonNegativeNumber(measured.medianMs, `results.${taskId}.medianMs`)
+    const maxRssMb = asNonNegativeNumber(measured.maxRssMb, `results.${taskId}.maxRssMb`)
+    const allowedMedianMs = taskBudget.maxMedianMs * runtimeToleranceFactor
+    const allowedMaxRssMb = taskBudget.maxRssMb * memoryToleranceFactor
+
+    const runtimePassed = medianMs <= allowedMedianMs
+    const memoryPassed = maxRssMb <= allowedMaxRssMb
+
+    checks.push({
+      task: taskId,
+      measured: { medianMs, maxRssMb },
+      budget: {
+        maxMedianMs: taskBudget.maxMedianMs,
+        maxRssMb: taskBudget.maxRssMb,
+        allowedMedianMs,
+        allowedMaxRssMb,
+      },
+      passed: runtimePassed && memoryPassed,
+      runtimePassed,
+      memoryPassed,
+    })
+
+    if (!runtimePassed) {
+      failures.push(
+        `${taskId}: median runtime ${medianMs.toFixed(2)}ms exceeds allowed ${allowedMedianMs.toFixed(2)}ms (budget ${taskBudget.maxMedianMs}ms + tolerance ${budget.tolerance.runtimePct}%)`,
+      )
+    }
+
+    if (!memoryPassed) {
+      failures.push(
+        `${taskId}: max RSS ${maxRssMb.toFixed(2)}MB exceeds allowed ${allowedMaxRssMb.toFixed(2)}MB (budget ${taskBudget.maxRssMb}MB + tolerance ${budget.tolerance.memoryPct}%)`,
+      )
+    }
+  }
+
+  return {
+    ok: failures.length === 0,
+    failures,
+    checks,
+  }
+}
+
+function createBenchmarkArgs(rootDir, budgetPath, budget, outputPath) {
+  const tsxLoaderPath = resolve(rootDir, 'node_modules', 'tsx', 'dist', 'loader.mjs')
+  if (!existsSync(tsxLoaderPath)) {
+    throw new Error(`Missing tsx loader at ${tsxLoaderPath}. Run npm ci first.`)
+  }
+
+  const benchmarkEntry = resolve(rootDir, 'src', 'benchmark.ts')
+  const tsxLoaderSpecifier = pathToFileURL(tsxLoaderPath).href
+
+  const benchmark = resolveBenchmarkContext(rootDir, budget)
+  const args = [
+    '--import',
+    tsxLoaderSpecifier,
+    benchmarkEntry,
+    '--scan-path',
+    benchmark.scanPath,
+    '--review-path',
+    benchmark.reviewPath,
+    '--trust-path',
+    benchmark.trustPath,
+    '--base',
+    String(benchmark.baseRef),
+    '--warmup',
+    String(benchmark.warmupRuns),
+    '--runs',
+    String(benchmark.measuredRuns),
+    '--json-out',
+    outputPath,
+  ]
+
+  return {
+    budgetPath,
+    benchmarkEntry,
+    args,
+    cleanup: benchmark.cleanup,
+  }
+}
+
+function createCommittedFixtureRepo(rootDir, fixturePath) {
+  const resolvedFixturePath = resolve(rootDir, fixturePath)
+  if (!existsSync(resolvedFixturePath)) {
+    throw new Error(`Benchmark fixture path does not exist: ${resolvedFixturePath}`)
+  }
+
+  const tempRepo = mkdtempSync(join(tmpdir(), 'drift-perf-fixture-'))
+  cpSync(resolvedFixturePath, tempRepo, { recursive: true })
+
+  const init = runGit(tempRepo, ['init'])
+  if (init.status !== 0) {
+    throw new Error(`Failed to initialize git fixture repository: ${init.stderr ?? ''}`)
+  }
+
+  const add = runGit(tempRepo, ['add', '.'])
+  if (add.status !== 0) {
+    throw new Error(`Failed to stage git fixture files: ${add.stderr ?? ''}`)
+  }
+
+  const commit = runGit(tempRepo, [
+    '-c',
+    'user.name=drift-ci',
+    '-c',
+    'user.email=drift-ci@example.com',
+    'commit',
+    '-m',
+    'fixture baseline',
+  ])
+
+  if (commit.status !== 0) {
+    throw new Error(`Failed to commit git fixture baseline: ${commit.stderr ?? ''}`)
+  }
+
+  return {
+    repoPath: tempRepo,
+    cleanup: () => {
+      rmSync(tempRepo, { recursive: true, force: true })
+    },
+  }
+}
+
+function resolveBenchmarkContext(rootDir, budget) {
+  const benchmark = budget?.benchmark ?? {}
+  const warmupRuns = benchmark.warmupRuns
+  const measuredRuns = benchmark.measuredRuns
+
+  if (typeof benchmark.fixturePath === 'string' && benchmark.fixturePath.trim().length > 0) {
+    const fixtureRepo = createCommittedFixtureRepo(rootDir, benchmark.fixturePath)
+    return {
+      scanPath: fixtureRepo.repoPath,
+      reviewPath: fixtureRepo.repoPath,
+      trustPath: fixtureRepo.repoPath,
+      baseRef: 'HEAD',
+      warmupRuns,
+      measuredRuns,
+      cleanup: fixtureRepo.cleanup,
+    }
+  }
+
+  if (!benchmark.scanPath || !benchmark.reviewPath || !benchmark.trustPath || !benchmark.baseRef) {
+    throw new Error('benchmark must provide fixturePath or scanPath/reviewPath/trustPath/baseRef')
+  }
+
+  return {
+    scanPath: resolve(rootDir, benchmark.scanPath),
+    reviewPath: resolve(rootDir, benchmark.reviewPath),
+    trustPath: resolve(rootDir, benchmark.trustPath),
+    baseRef: benchmark.baseRef,
+    warmupRuns,
+    measuredRuns,
+    cleanup: undefined,
+  }
+}
+
+function runBenchmark(rootDir, budgetPath, budget, resultPath) {
+  mkdirSync(dirname(resultPath), { recursive: true })
+
+  const benchmark = createBenchmarkArgs(rootDir, budgetPath, budget, resultPath)
+  const execution = spawnSync(process.execPath, benchmark.args, {
+    cwd: rootDir,
+    encoding: 'utf8',
+  })
+
+  if (benchmark.cleanup) {
+    benchmark.cleanup()
+  }
+
+  if (execution.status !== 0) {
+    const errorOutput = `${execution.stdout ?? ''}${execution.stderr ?? ''}`.trim()
+    throw new Error(`Benchmark command failed (${benchmark.benchmarkEntry}):\n${errorOutput}`)
+  }
+
+  if (!existsSync(resultPath)) {
+    throw new Error(`Benchmark did not produce expected JSON output at ${resultPath}`)
+  }
+
+  return readJson(resultPath)
+}
+
+export function runPerformanceBudgetCheck(rootDir = process.cwd(), argv = process.argv.slice(2)) {
+  const parsed = parseArgs(argv)
+  const budgetPath = resolve(rootDir, parsed.budgetPath)
+  const resultPath = resolve(rootDir, parsed.resultPath)
+  const budget = readJson(budgetPath)
+
+  const benchmarkResult = parsed.benchmarkResultPath
+    ? readJson(resolve(rootDir, parsed.benchmarkResultPath))
+    : runBenchmark(rootDir, budgetPath, budget, resultPath)
+
+  const gateResultPath = resolve(dirname(resultPath), 'perf-gate-result.json')
+
+  const evaluation = evaluatePerformanceBudget(budget, benchmarkResult)
+  const gateResult = {
+    schemaVersion: BENCHMARK_RESULT_SCHEMA,
+    generatedAt: new Date().toISOString(),
+    budgetFile: budgetPath,
+    budgetVersion: budget.budgetVersion,
+    benchmarkFile: parsed.benchmarkResultPath ? resolve(rootDir, parsed.benchmarkResultPath) : resultPath,
+    ok: evaluation.ok,
+    checks: evaluation.checks,
+    failures: evaluation.failures,
+  }
+
+  mkdirSync(dirname(resultPath), { recursive: true })
+  const gateResultSerialized = `${JSON.stringify(gateResult, null, 2)}\n`
+  writeFileSync(gateResultPath, gateResultSerialized, 'utf8')
+
+  if (!parsed.benchmarkResultPath) {
+    process.stdout.write(`Performance benchmark generated: ${resultPath}\n`)
+  }
+  process.stdout.write(`Performance gate report: ${gateResultPath}\n`)
+
+  process.stdout.write(`Performance budget version: ${budget.budgetVersion}\n`)
+  for (const check of evaluation.checks) {
+    process.stdout.write(
+      `- ${check.task}: median ${check.measured.medianMs.toFixed(2)}ms (<= ${check.budget.allowedMedianMs.toFixed(2)}ms), max RSS ${check.measured.maxRssMb.toFixed(2)}MB (<= ${check.budget.allowedMaxRssMb.toFixed(2)}MB)\n`,
+    )
+  }
+
+  if (!evaluation.ok) {
+    process.stderr.write('Performance budget check failed:\n')
+    for (const failure of evaluation.failures) {
+      process.stderr.write(`- ${failure}\n`)
+    }
+    process.exitCode = 1
+    return gateResult
+  }
+
+  process.stdout.write('Performance budget check passed.\n')
+  return gateResult
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    runPerformanceBudgetCheck()
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    process.stderr.write(`Performance budget check failed: ${message}\n`)
+    process.exit(1)
+  }
+}

package/scripts/check-runtime-policy.mjs

@@ -0,0 +1,66 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const EXPECTED_ENGINE_RANGE = '^20.0.0 || ^22.0.0'
+const EXPECTED_NODE_MATRIX = '["20", "22"]'
+const EXPECTED_README_RUNTIME = '**Runtime:** Node.js 20.x and 22.x (LTS)'
+const EXPECTED_INIT_TEMPLATE_NODE_VERSION = 'node-version: 20'
+
+function readRepoFile(relativePath) {
+  return readFileSync(join(process.cwd(), relativePath), 'utf8')
+}
+
+function assertIncludes(content, expected, errorMessage) {
+  if (!content.includes(expected)) {
+    throw new Error(errorMessage)
+  }
+}
+
+function main() {
+  const packageJson = JSON.parse(readRepoFile('package.json'))
+  const engineRange = packageJson?.engines?.node
+
+  if (engineRange !== EXPECTED_ENGINE_RANGE) {
+    throw new Error(
+      `Invalid package.json engines.node: expected "${EXPECTED_ENGINE_RANGE}", got "${String(engineRange)}"`,
+    )
+  }
+
+  const qualityWorkflow = readRepoFile('.github/workflows/quality.yml')
+  assertIncludes(
+    qualityWorkflow,
+    `node_versions: '${EXPECTED_NODE_MATRIX}'`,
+    `quality.yml must declare node_versions: '${EXPECTED_NODE_MATRIX}'`,
+  )
+
+  const reusableWorkflow = readRepoFile('.github/workflows/reusable-quality-checks.yml')
+  assertIncludes(
+    reusableWorkflow,
+    `default: '${EXPECTED_NODE_MATRIX}'`,
+    `reusable-quality-checks.yml must declare default: '${EXPECTED_NODE_MATRIX}'`,
+  )
+
+  const initTemplate = readRepoFile('src/init.ts')
+  assertIncludes(
+    initTemplate,
+    EXPECTED_INIT_TEMPLATE_NODE_VERSION,
+    `src/init.ts workflow template must include: ${EXPECTED_INIT_TEMPLATE_NODE_VERSION}`,
+  )
+
+  const readme = readRepoFile('README.md')
+  assertIncludes(
+    readme,
+    EXPECTED_README_RUNTIME,
+    `README runtime line must include: ${EXPECTED_README_RUNTIME}`,
+  )
+
+  const lockfile = readRepoFile('package-lock.json')
+  assertIncludes(lockfile, '"node_modules/commander"', 'package-lock must include commander entry')
+  assertIncludes(lockfile, '"node": ">=20"', 'commander dependency requires Node >=20; runtime policy cannot be lower')
+
+  process.stdout.write(
+    `Runtime policy check passed: engines.node=${EXPECTED_ENGINE_RANGE}, matrix=${EXPECTED_NODE_MATRIX}, docs aligned.\n`,
+  )
+}
+
+main()

package/src/benchmark.ts

@@ -24,10 +24,14 @@ interface TaskResult {
   warmupRuns: number
   measuredRuns: number
   samplesMs: number[]
+  samplesRssMb: number[]
   medianMs: number
   meanMs: number
   minMs: number
   maxMs: number
+  medianRssMb: number
+  meanRssMb: number
+  maxRssMb: number
 }
 
 interface BenchmarkOutput {
@@ -129,6 +133,10 @@ function formatMs(ms: number): string {
   return ms.toFixed(2)
 }
 
+function bytesToMb(bytes: number): number {
+  return bytes / (1024 * 1024)
+}
+
 async function runTask(
   name: TaskResult['name'],
   warmupRuns: number,
@@ -140,22 +148,31 @@ async function runTask(
   }
 
   const samplesMs: number[] = []
+  const samplesRssMb: number[] = []
   for (let i = 0; i < measuredRuns; i += 1) {
+    const rssBefore = process.memoryUsage().rss
     const started = performance.now()
     await task()
     samplesMs.push(performance.now() - started)
+    const rssAfter = process.memoryUsage().rss
+    samplesRssMb.push(bytesToMb(Math.max(rssBefore, rssAfter)))
   }
 
   const total = samplesMs.reduce((sum, sample) => sum + sample, 0)
+  const totalRss = samplesRssMb.reduce((sum, sample) => sum + sample, 0)
   return {
     name,
     warmupRuns,
     measuredRuns,
     samplesMs,
+    samplesRssMb,
     medianMs: median(samplesMs),
     meanMs: total / samplesMs.length,
     minMs: Math.min(...samplesMs),
     maxMs: Math.max(...samplesMs),
+    medianRssMb: median(samplesRssMb),
+    meanRssMb: totalRss / samplesRssMb.length,
+    maxRssMb: Math.max(...samplesRssMb),
   }
 }
 

package/src/cli.ts

@@ -14,7 +14,7 @@ import { printConsole, printDiff } from './printer.js'
 import { loadConfig } from './config.js'
 import { extractFilesAtRef, cleanupTempDir } from './git.js'
 import { computeDiff } from './diff.js'
-import { runGuard } from './guard.js'
+import { formatGuardJson, runGuard } from './guard.js'
 import { generateHtmlReport } from './report.js'
 import { generateBadge } from './badge.js'
 import { emitCIAnnotations, printCISummary } from './ci.js'
@@ -412,7 +412,7 @@ addResourceOptions(
       })
 
       if (options.json) {
-        process.stdout.write(JSON.stringify(result, null, 2) + '\n')
+        process.stdout.write(`${formatGuardJson(result)}\n`)
       } else {
         printGuardSummary(result)
       }

package/src/doctor.ts

@@ -1,6 +1,8 @@
 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
@@ -23,10 +25,12 @@ interface DoctorReport {
   }
 }
 
+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 = 18
+const MIN_SUPPORTED_NODE_MAJOR = 20
 const LOW_MEMORY_SOURCE_FILE_THRESHOLD = 500
 const DRIFT_CONFIG_CANDIDATES = [
   'drift.config.ts',
@@ -128,7 +132,7 @@ function printConsoleReport(report: DoctorReport): void {
 
   const nodeStatus = report.node.supported
     ? `${icons.check} ${kleur.green('Node runtime supported')}`
-    : `${icons.warn} ${kleur.yellow('Node runtime below recommended minimum (>=18)')}`
+    : `${icons.warn} ${kleur.yellow('Node runtime below supported minimum (>=20)')}`
   process.stdout.write(`${nodeStatus} ${kleur.gray(`(${report.node.version})`)}\n`)
 
   if (report.project.packageJsonFound) {
@@ -160,11 +164,19 @@ function printConsoleReport(report: DoctorReport): void {
   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(`${JSON.stringify(report, null, 2)}\n`)
+    process.stdout.write(`${formatDoctorJson(report)}\n`)
   } else {
     printConsoleReport(report)
   }

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

@@ -1,4 +1,4 @@
-import type { DriftAnalysisOptions, DriftDiff, DriftIssue, DriftReport } from './types.js'
+import type { DriftAnalysisOptions, DriftDiff, DriftIssue, DriftOutputMetadata, DriftReport } from './types.js'
 
 export type IssueSeverity = DriftIssue['severity']
 
@@ -62,3 +62,5 @@ export interface GuardResult {
   current: DriftReport
   diff?: DriftDiff
 }
+
+export type GuardResultJson = GuardResult & DriftOutputMetadata