@eduardbar/drift 1.3.0 → 1.5.0

package/dist/diff.js

@@ -8,6 +8,43 @@ function normalizeIssueText(value) {
         .replace(/\s+/g, ' ')
         .trim();
 }
+const SNIPPET_PREFIX_LENGTH = 80;
+function strictIssueKey(i) {
+    return `${i.rule}:${i.line}:${i.column}`;
+}
+function normalizedIssueKey(i) {
+    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, getKey, skip) {
+    const index = new Map();
+    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, index, state, getKey) {
+    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.
  *
@@ -26,58 +63,13 @@ function computeFileDiff(filePath, baseFile, currentFile) {
     const scoreDelta = scoreAfter - scoreBefore;
     const baseIssues = baseFile?.issues ?? [];
     const currentIssues = currentFile?.issues ?? [];
-    const strictIssueKey = (i) => `${i.rule}:${i.line}:${i.column}`;
-    const normalizedIssueKey = (i) => {
-        const normalizedMessage = normalizeIssueText(i.message);
-        const normalizedSnippetPrefix = normalizeIssueText(i.snippet).slice(0, 80);
-        return `${i.rule}:${i.severity}:${i.line}:${normalizedMessage}:${normalizedSnippetPrefix}`;
-    };
     const matchedBaseIndexes = new Set();
     const matchedCurrentIndexes = new Set();
-    const baseStrictIndex = new Map();
-    for (const [index, issue] of baseIssues.entries()) {
-        const key = strictIssueKey(issue);
-        const bucket = baseStrictIndex.get(key);
-        if (bucket)
-            bucket.push(index);
-        else
-            baseStrictIndex.set(key, [index]);
-    }
-    for (const [currentIndex, issue] of currentIssues.entries()) {
-        const key = strictIssueKey(issue);
-        const bucket = baseStrictIndex.get(key);
-        if (!bucket || bucket.length === 0)
-            continue;
-        const matchedIndex = bucket.shift();
-        if (matchedIndex === undefined)
-            continue;
-        matchedBaseIndexes.add(matchedIndex);
-        matchedCurrentIndexes.add(currentIndex);
-    }
-    const baseNormalizedIndex = new Map();
-    for (const [index, issue] of baseIssues.entries()) {
-        if (matchedBaseIndexes.has(index))
-            continue;
-        const key = normalizedIssueKey(issue);
-        const bucket = baseNormalizedIndex.get(key);
-        if (bucket)
-            bucket.push(index);
-        else
-            baseNormalizedIndex.set(key, [index]);
-    }
-    for (const [currentIndex, issue] of currentIssues.entries()) {
-        if (matchedCurrentIndexes.has(currentIndex))
-            continue;
-        const key = normalizedIssueKey(issue);
-        const bucket = baseNormalizedIndex.get(key);
-        if (!bucket || bucket.length === 0)
-            continue;
-        const matchedIndex = bucket.shift();
-        if (matchedIndex === undefined)
-            continue;
-        matchedBaseIndexes.add(matchedIndex);
-        matchedCurrentIndexes.add(currentIndex);
-    }
+    const matchState = { matchedBaseIndexes, matchedCurrentIndexes };
+    const baseStrictIndex = buildIssueIndex(baseIssues, strictIssueKey);
+    matchIssues(currentIssues, baseStrictIndex, matchState, strictIssueKey);
+    const baseNormalizedIndex = buildIssueIndex(baseIssues, normalizedIssueKey, matchedBaseIndexes);
+    matchIssues(currentIssues, baseNormalizedIndex, matchState, normalizedIssueKey);
     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) {

package/dist/doctor.d.ts

@@ -0,0 +1,26 @@
+import type { DriftOutputMetadata } from './types.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;
+export declare function formatDoctorJsonObject(report: DoctorReport): DoctorReportJson;
+export declare function formatDoctorJson(report: DoctorReport): string;
+export declare function runDoctor(projectPath: string, options?: DoctorOptions): Promise<number>;
+export {};
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.js

@@ -0,0 +1,140 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import kleur from 'kleur';
+import { OUTPUT_SCHEMA, withOutputMetadata } from './output-metadata.js';
+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',
+];
+function parseNodeMajor(version) {
+    const parsed = Number.parseInt(version.replace(/^v/, '').split('.')[0] ?? '0', DECIMAL_RADIX);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function detectDriftConfig(projectPath) {
+    for (const candidate of DRIFT_CONFIG_CANDIDATES) {
+        if (existsSync(join(projectPath, candidate))) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function countSourceFiles(projectPath) {
+    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) {
+    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'));
+        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) {
+    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) {
+    return withOutputMetadata(report, OUTPUT_SCHEMA.doctor);
+}
+export function formatDoctorJson(report) {
+    return JSON.stringify(formatDoctorJsonObject(report), null, 2);
+}
+export async function runDoctor(projectPath, options) {
+    const report = buildDoctorReport(projectPath);
+    if (options?.json) {
+        process.stdout.write(`${formatDoctorJson(report)}\n`);
+    }
+    else {
+        printConsoleReport(report);
+    }
+    return 0;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/format.d.ts

@@ -0,0 +1,17 @@
+declare const UNIFIED_FORMAT_VALUES: readonly ["console", "json", "markdown", "ai", "sarif"];
+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;
+}
+export declare function resolveOutputFormat(options: ResolveOutputFormatOptions): UnifiedOutputFormat;
+export {};
+//# sourceMappingURL=format.d.ts.map

package/dist/format.js

@@ -0,0 +1,45 @@
+const UNIFIED_FORMAT_VALUES = ['console', 'json', 'markdown', 'ai', 'sarif'];
+function assertSupportedFormatValue(command, format) {
+    if (UNIFIED_FORMAT_VALUES.includes(format))
+        return;
+    throw new Error(`Invalid --format '${format}' for '${command}'. Allowed values: ${UNIFIED_FORMAT_VALUES.join(', ')}.`);
+}
+function throwUnsupportedFormat(command, selected, supported) {
+    throw new Error(`Format '${selected}' is not supported for '${command}'. Supported formats: ${supported.join(', ')}.`);
+}
+function normalizeLegacyFormatSelection(command, selectedLegacyFormats) {
+    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) {
+    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;
+}
+//# sourceMappingURL=format.js.map

package/dist/guard-baseline.d.ts

@@ -0,0 +1,12 @@
+import type { GuardBaseline, IssueSeverity } from './guard-types.js';
+export interface NormalizedBaseline {
+    score?: number;
+    totalIssues?: number;
+    bySeverity: Partial<Record<IssueSeverity, number>>;
+}
+export declare function normalizeBaseline(baseline: GuardBaseline): NormalizedBaseline;
+export declare function readBaselineFromFile(projectPath: string, baselinePath?: string): {
+    baseline: NormalizedBaseline;
+    path: string;
+} | undefined;
+//# sourceMappingURL=guard-baseline.d.ts.map

package/dist/guard-baseline.js

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+function parseNumber(value) {
+    return typeof value === 'number' && !Number.isNaN(value) ? value : undefined;
+}
+function firstDefinedNumber(values) {
+    for (const value of values) {
+        const parsed = parseNumber(value);
+        if (parsed !== undefined) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+function normalizeSeverity(baseline, severity) {
+    const summaryBySeverity = baseline.summary?.[`${severity}s`];
+    return firstDefinedNumber([
+        baseline.bySeverity?.[severity],
+        severity === 'error' ? baseline.errors : undefined,
+        severity === 'warning' ? baseline.warnings : undefined,
+        severity === 'info' ? baseline.infos : undefined,
+        summaryBySeverity,
+    ]);
+}
+function hasAnchor(baseline) {
+    if (baseline.score !== undefined || baseline.totalIssues !== undefined) {
+        return true;
+    }
+    const severities = ['error', 'warning', 'info'];
+    return severities.some((severity) => baseline.bySeverity[severity] !== undefined);
+}
+export function normalizeBaseline(baseline) {
+    const normalized = {
+        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, baselinePath) {
+    const resolvedBaselinePath = resolve(projectPath, baselinePath ?? 'drift-baseline.json');
+    if (!existsSync(resolvedBaselinePath))
+        return undefined;
+    const raw = JSON.parse(readFileSync(resolvedBaselinePath, 'utf8'));
+    return {
+        baseline: normalizeBaseline(raw),
+        path: resolvedBaselinePath,
+    };
+}
+//# sourceMappingURL=guard-baseline.js.map

package/dist/guard-metrics.d.ts

@@ -0,0 +1,6 @@
+import type { DriftDiff, DriftReport } from './types.js';
+import type { GuardMetrics } from './guard-types.js';
+import type { NormalizedBaseline } from './guard-baseline.js';
+export declare function buildMetricsFromDiff(diff: DriftDiff): GuardMetrics;
+export declare function buildMetricsFromBaseline(current: DriftReport, baseline: NormalizedBaseline): GuardMetrics;
+//# sourceMappingURL=guard-metrics.d.ts.map

package/dist/guard-metrics.js

@@ -0,0 +1,39 @@
+function createSeverityDelta() {
+    return {
+        error: 0,
+        warning: 0,
+        info: 0,
+    };
+}
+function applySeverityDelta(delta, issues, direction) {
+    for (const issue of issues) {
+        delta[issue.severity] += direction;
+    }
+}
+function countSeverityDeltaFromDiff(diff) {
+    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) {
+    return {
+        scoreDelta: diff.totalDelta,
+        totalIssuesDelta: diff.newIssuesCount - diff.resolvedIssuesCount,
+        severityDelta: countSeverityDeltaFromDiff(diff),
+    };
+}
+export function buildMetricsFromBaseline(current, baseline) {
+    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),
+        },
+    };
+}
+//# sourceMappingURL=guard-metrics.js.map

package/dist/guard-types.d.ts

@@ -0,0 +1,58 @@
+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;
+//# sourceMappingURL=guard-types.d.ts.map

package/dist/guard-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=guard-types.js.map

package/dist/guard.d.ts

@@ -0,0 +1,16 @@
+import type { GuardEvaluation, GuardMetrics, GuardOptions, GuardResult, GuardResultJson, GuardThresholds } from './guard-types.js';
+interface GuardEvalInput {
+    metrics: GuardMetrics;
+    budget?: number;
+    bySeverity?: GuardThresholds;
+    enforceNoRegression: {
+        score: boolean;
+        totalIssues: boolean;
+    };
+}
+export declare function evaluateGuard(input: GuardEvalInput): GuardEvaluation;
+export declare function formatGuardJsonObject(result: GuardResult): GuardResultJson;
+export declare function formatGuardJson(result: GuardResult): string;
+export declare function runGuard(targetPath: string, options?: GuardOptions): Promise<GuardResult>;
+export {};
+//# sourceMappingURL=guard.d.ts.map