@eduardbar/drift 1.3.0 → 1.4.0

package/dist/types/diff.d.ts

@@ -0,0 +1,55 @@
+import type { DriftIssue, DriftReport, FileReport } from './core.js';
+export interface FileDiff {
+    path: string;
+    scoreBefore: number;
+    scoreAfter: number;
+    scoreDelta: number;
+    newIssues: DriftIssue[];
+    resolvedIssues: DriftIssue[];
+}
+export interface DriftDiff {
+    baseRef: string;
+    projectPath: string;
+    scannedAt: string;
+    files: FileDiff[];
+    totalScoreBefore: number;
+    totalScoreAfter: number;
+    totalDelta: number;
+    newIssuesCount: number;
+    resolvedIssuesCount: number;
+}
+export interface HistoricalAnalysis {
+    commitHash: string;
+    commitDate: Date;
+    author: string;
+    message: string;
+    files: FileReport[];
+    totalScore: number;
+    averageScore: number;
+}
+export interface TrendDataPoint {
+    date: Date;
+    score: number;
+    fileCount: number;
+    avgIssuesPerFile: number;
+}
+export interface BlameAttribution {
+    author: string;
+    email: string;
+    commits: number;
+    linesChanged: number;
+    issuesIntroduced: number;
+    avgScoreImpact: number;
+}
+export interface DriftTrendReport extends DriftReport {
+    trend: TrendDataPoint[];
+    regression: {
+        slope: number;
+        intercept: number;
+        r2: number;
+    };
+}
+export interface DriftBlameReport extends DriftReport {
+    blame: BlameAttribution[];
+}
+//# sourceMappingURL=diff.d.ts.map

package/dist/types/diff.js

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

package/dist/types/plugin.d.ts

@@ -0,0 +1,41 @@
+import type { SourceFile } from 'ts-morph';
+import type { DriftConfig } from './app.js';
+import type { DriftIssue } from './core.js';
+export interface PluginRuleContext {
+    projectRoot: string;
+    filePath: string;
+    config?: DriftConfig;
+}
+export interface DriftPluginRule {
+    id?: string;
+    name: string;
+    severity?: DriftIssue['severity'];
+    weight?: number;
+    detect: (file: SourceFile, context: PluginRuleContext) => DriftIssue[];
+    fix?: (issue: DriftIssue, file: SourceFile, context: PluginRuleContext) => DriftIssue | void;
+}
+export interface DriftPlugin {
+    name: string;
+    apiVersion?: number;
+    capabilities?: Record<string, string | number | boolean>;
+    rules: DriftPluginRule[];
+}
+export interface LoadedPlugin {
+    id: string;
+    plugin: DriftPlugin;
+}
+export interface PluginLoadError {
+    pluginId: string;
+    pluginName?: string;
+    ruleId?: string;
+    code?: string;
+    message: string;
+}
+export interface PluginLoadWarning {
+    pluginId: string;
+    pluginName?: string;
+    ruleId?: string;
+    code?: string;
+    message: string;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/types/plugin.js

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

package/dist/types/trust.d.ts

@@ -0,0 +1,120 @@
+import type { DriftIssue, DriftOutputMetadata } from './core.js';
+export type MergeRiskLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+export interface TrustGatePolicyPreset {
+    branch: string;
+    enabled?: boolean;
+    minTrust?: number;
+    maxRisk?: MergeRiskLevel;
+}
+export interface TrustGatePolicyPack {
+    enabled?: boolean;
+    minTrust?: number;
+    maxRisk?: MergeRiskLevel;
+}
+export interface TrustGatePolicyConfig {
+    enabled?: boolean;
+    minTrust?: number;
+    maxRisk?: MergeRiskLevel;
+    presets?: TrustGatePolicyPreset[];
+    policyPacks?: Record<string, TrustGatePolicyPack>;
+}
+export interface TrustReason {
+    label: string;
+    detail: string;
+    impact: number;
+}
+export interface TrustFixPriority {
+    rank: number;
+    rule: string;
+    severity: DriftIssue['severity'];
+    occurrences: number;
+    estimated_trust_gain: number;
+    effort: 'low' | 'medium' | 'high';
+    suggestion: string;
+    confidence?: 'low' | 'medium' | 'high';
+    explanation?: string;
+    systemic?: boolean;
+}
+export interface TrustAdvancedComparison {
+    source: 'previous-trust-json' | 'snapshot-history';
+    trend: 'improving' | 'regressing' | 'stable';
+    summary: string;
+    trust_delta?: number;
+    previous_trust_score?: number;
+    previous_merge_risk?: MergeRiskLevel;
+    snapshot_score_delta?: number;
+    snapshot_label?: string;
+    snapshot_timestamp?: string;
+}
+export interface TrustAdvancedContext {
+    comparison?: TrustAdvancedComparison;
+    team_guidance: string[];
+}
+export interface TrustDiffContext {
+    baseRef: string;
+    status: 'improved' | 'regressed' | 'neutral';
+    scoreDelta: number;
+    newIssues: number;
+    resolvedIssues: number;
+    filesChanged: number;
+    penalty: number;
+    bonus: number;
+    netImpact: number;
+}
+export interface DriftTrustReport {
+    scannedAt: string;
+    targetPath: string;
+    trust_score: number;
+    merge_risk: MergeRiskLevel;
+    top_reasons: TrustReason[];
+    fix_priorities: TrustFixPriority[];
+    diff_context?: TrustDiffContext;
+    advanced_context?: TrustAdvancedContext;
+}
+export type DriftTrustReportJson = DriftTrustReport & DriftOutputMetadata;
+export interface TrustKpiDiagnostic {
+    level: 'warning' | 'error';
+    code: 'path-not-found' | 'path-not-supported' | 'read-failed' | 'parse-failed' | 'invalid-shape' | 'invalid-diff-context';
+    message: string;
+    file?: string;
+}
+export interface TrustScoreStats {
+    average: number | null;
+    median: number | null;
+    min: number | null;
+    max: number | null;
+}
+export interface TrustDiffTrendSummary {
+    available: boolean;
+    samples: number;
+    statusDistribution: {
+        improved: number;
+        regressed: number;
+        neutral: number;
+    };
+    scoreDelta: {
+        average: number | null;
+        median: number | null;
+    };
+    issues: {
+        newTotal: number;
+        resolvedTotal: number;
+        netNew: number;
+    };
+}
+export interface TrustKpiReport {
+    generatedAt: string;
+    input: string;
+    files: {
+        matched: number;
+        parsed: number;
+        malformed: number;
+    };
+    prsEvaluated: number;
+    mergeRiskDistribution: Record<MergeRiskLevel, number>;
+    trustScore: TrustScoreStats;
+    highRiskRatio: number | null;
+    diffTrend: TrustDiffTrendSummary;
+    diagnostics: TrustKpiDiagnostic[];
+}
+//# sourceMappingURL=trust.d.ts.map

package/dist/types/trust.js

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

package/dist/types.d.ts

@@ -1,366 +1,9 @@
-import type { SourceFile } from 'ts-morph';
-export interface DriftIssue {
-    rule: string;
-    severity: 'error' | 'warning' | 'info';
-    message: string;
-    line: number;
-    column: number;
-    snippet: string;
-}
-export interface FileReport {
-    path: string;
-    issues: DriftIssue[];
-    score: number;
-}
-export interface DriftReport {
-    scannedAt: string;
-    targetPath: string;
-    files: FileReport[];
-    totalIssues: number;
-    totalScore: number;
-    totalFiles: number;
-    summary: {
-        errors: number;
-        warnings: number;
-        infos: number;
-        byRule: Record<string, number>;
-    };
-    quality: RepoQualityScore;
-    maintenanceRisk: MaintenanceRiskMetrics;
-}
-export interface RepoQualityScore {
-    overall: number;
-    dimensions: {
-        architecture: number;
-        complexity: number;
-        'ai-patterns': number;
-        testing: number;
-    };
-}
-export interface RiskHotspot {
-    file: string;
-    driftScore: number;
-    complexityIssues: number;
-    hasNearbyTests: boolean;
-    changeFrequency: number;
-    risk: number;
-    reasons: string[];
-}
-export interface MaintenanceRiskMetrics {
-    score: number;
-    level: 'low' | 'medium' | 'high' | 'critical';
-    hotspots: RiskHotspot[];
-    signals: {
-        highComplexityFiles: number;
-        filesWithoutNearbyTests: number;
-        frequentChangeFiles: number;
-    };
-}
-export interface AIOutput {
-    summary: {
-        score: number;
-        grade: string;
-        total_issues: number;
-        files_affected: number;
-        files_clean: number;
-        ai_likelihood: number;
-        ai_code_smell_score: number;
-    };
-    files_suspected: Array<{
-        path: string;
-        ai_likelihood: number;
-        triggers: string[];
-    }>;
-    priority_order: AIIssue[];
-    maintenance_risk: MaintenanceRiskMetrics;
-    quality: RepoQualityScore;
-    context_for_ai: {
-        project_type: string;
-        scan_path: string;
-        rules_detected: string[];
-        recommended_action: string;
-    };
-}
-export interface AIIssue {
-    rank: number;
-    file: string;
-    line: number;
-    rule: string;
-    severity: string;
-    message: string;
-    snippet: string;
-    fix_suggestion: string;
-    effort: 'low' | 'medium' | 'high';
-}
-export type MergeRiskLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
-export interface TrustGatePolicyPreset {
-    branch: string;
-    enabled?: boolean;
-    minTrust?: number;
-    maxRisk?: MergeRiskLevel;
-}
-export interface TrustGatePolicyPack {
-    enabled?: boolean;
-    minTrust?: number;
-    maxRisk?: MergeRiskLevel;
-}
-export interface TrustGatePolicyConfig {
-    enabled?: boolean;
-    minTrust?: number;
-    maxRisk?: MergeRiskLevel;
-    presets?: TrustGatePolicyPreset[];
-    policyPacks?: Record<string, TrustGatePolicyPack>;
-}
-export interface TrustReason {
-    label: string;
-    detail: string;
-    impact: number;
-}
-export interface TrustFixPriority {
-    rank: number;
-    rule: string;
-    severity: DriftIssue['severity'];
-    occurrences: number;
-    estimated_trust_gain: number;
-    effort: 'low' | 'medium' | 'high';
-    suggestion: string;
-    confidence?: 'low' | 'medium' | 'high';
-    explanation?: string;
-    systemic?: boolean;
-}
-export interface TrustAdvancedComparison {
-    source: 'previous-trust-json' | 'snapshot-history';
-    trend: 'improving' | 'regressing' | 'stable';
-    summary: string;
-    trust_delta?: number;
-    previous_trust_score?: number;
-    previous_merge_risk?: MergeRiskLevel;
-    snapshot_score_delta?: number;
-    snapshot_label?: string;
-    snapshot_timestamp?: string;
-}
-export interface TrustAdvancedContext {
-    comparison?: TrustAdvancedComparison;
-    team_guidance: string[];
-}
-export interface TrustDiffContext {
-    baseRef: string;
-    status: 'improved' | 'regressed' | 'neutral';
-    scoreDelta: number;
-    newIssues: number;
-    resolvedIssues: number;
-    filesChanged: number;
-    penalty: number;
-    bonus: number;
-    netImpact: number;
-}
-export interface DriftTrustReport {
-    scannedAt: string;
-    targetPath: string;
-    trust_score: number;
-    merge_risk: MergeRiskLevel;
-    top_reasons: TrustReason[];
-    fix_priorities: TrustFixPriority[];
-    diff_context?: TrustDiffContext;
-    advanced_context?: TrustAdvancedContext;
-}
-export interface TrustKpiDiagnostic {
-    level: 'warning' | 'error';
-    code: 'path-not-found' | 'path-not-supported' | 'read-failed' | 'parse-failed' | 'invalid-shape' | 'invalid-diff-context';
-    message: string;
-    file?: string;
-}
-export interface TrustScoreStats {
-    average: number | null;
-    median: number | null;
-    min: number | null;
-    max: number | null;
-}
-export interface TrustDiffTrendSummary {
-    available: boolean;
-    samples: number;
-    statusDistribution: {
-        improved: number;
-        regressed: number;
-        neutral: number;
-    };
-    scoreDelta: {
-        average: number | null;
-        median: number | null;
-    };
-    issues: {
-        newTotal: number;
-        resolvedTotal: number;
-        netNew: number;
-    };
-}
-export interface TrustKpiReport {
-    generatedAt: string;
-    input: string;
-    files: {
-        matched: number;
-        parsed: number;
-        malformed: number;
-    };
-    prsEvaluated: number;
-    mergeRiskDistribution: Record<MergeRiskLevel, number>;
-    trustScore: TrustScoreStats;
-    highRiskRatio: number | null;
-    diffTrend: TrustDiffTrendSummary;
-    diagnostics: TrustKpiDiagnostic[];
-}
-/**
- * Layer definition for architectural boundary enforcement.
- */
-export interface LayerDefinition {
-    name: string;
-    patterns: string[];
-    canImportFrom: string[];
-}
-/**
- * Module boundary definition for cross-boundary enforcement.
- */
-export interface ModuleBoundary {
-    name: string;
-    root: string;
-    allowedExternalImports?: string[];
-}
-/**
- * Optional project-level configuration for drift.
- * Place in drift.config.ts (or .js / .json) at the project root.
- */
-export interface DriftConfig {
-    layers?: LayerDefinition[];
-    modules?: ModuleBoundary[];
-    plugins?: string[];
-    performance?: DriftPerformanceConfig;
-    architectureRules?: {
-        controllerNoDb?: boolean;
-        serviceNoHttp?: boolean;
-        maxFunctionLines?: number;
-    };
-    saas?: {
-        freeUserThreshold?: number;
-        maxRunsPerWorkspacePerMonth?: number;
-        maxReposPerWorkspace?: number;
-        retentionDays?: number;
-        strictActorEnforcement?: boolean;
-        maxWorkspacesPerOrganizationByPlan?: {
-            free?: number;
-            sponsor?: number;
-            team?: number;
-            business?: number;
-        };
-    };
-    trustGate?: TrustGatePolicyConfig;
-}
-export interface DriftPerformanceConfig {
-    lowMemory?: boolean;
-    chunkSize?: number;
-    maxFiles?: number;
-    maxFileSizeKb?: number;
-    includeSemanticDuplication?: boolean;
-}
-export interface DriftAnalysisOptions {
-    lowMemory?: boolean;
-    chunkSize?: number;
-    maxFiles?: number;
-    maxFileSizeKb?: number;
-    includeSemanticDuplication?: boolean;
-}
-export interface PluginRuleContext {
-    projectRoot: string;
-    filePath: string;
-    config?: DriftConfig;
-}
-export interface DriftPluginRule {
-    id?: string;
-    name: string;
-    severity?: DriftIssue['severity'];
-    weight?: number;
-    detect: (file: SourceFile, context: PluginRuleContext) => DriftIssue[];
-    fix?: (issue: DriftIssue, file: SourceFile, context: PluginRuleContext) => DriftIssue | void;
-}
-export interface DriftPlugin {
-    name: string;
-    apiVersion?: number;
-    capabilities?: Record<string, string | number | boolean>;
-    rules: DriftPluginRule[];
-}
-export interface LoadedPlugin {
-    id: string;
-    plugin: DriftPlugin;
-}
-export interface PluginLoadError {
-    pluginId: string;
-    pluginName?: string;
-    ruleId?: string;
-    code?: string;
-    message: string;
-}
-export interface PluginLoadWarning {
-    pluginId: string;
-    pluginName?: string;
-    ruleId?: string;
-    code?: string;
-    message: string;
-}
-export interface FileDiff {
-    path: string;
-    scoreBefore: number;
-    scoreAfter: number;
-    scoreDelta: number;
-    newIssues: DriftIssue[];
-    resolvedIssues: DriftIssue[];
-}
-export interface DriftDiff {
-    baseRef: string;
-    projectPath: string;
-    scannedAt: string;
-    files: FileDiff[];
-    totalScoreBefore: number;
-    totalScoreAfter: number;
-    totalDelta: number;
-    newIssuesCount: number;
-    resolvedIssuesCount: number;
-}
-/** Historical analysis data for a single commit */
-export interface HistoricalAnalysis {
-    commitHash: string;
-    commitDate: Date;
-    author: string;
-    message: string;
-    files: FileReport[];
-    totalScore: number;
-    averageScore: number;
-}
-/** Trend data point for score evolution */
-export interface TrendDataPoint {
-    date: Date;
-    score: number;
-    fileCount: number;
-    avgIssuesPerFile: number;
-}
-/** Blame attribution data */
-export interface BlameAttribution {
-    author: string;
-    email: string;
-    commits: number;
-    linesChanged: number;
-    issuesIntroduced: number;
-    avgScoreImpact: number;
-}
-/** Extended DriftReport with historical context */
-export interface DriftTrendReport extends DriftReport {
-    trend: TrendDataPoint[];
-    regression: {
-        slope: number;
-        intercept: number;
-        r2: number;
-    };
-}
-/** Extended DriftReport with blame data */
-export interface DriftBlameReport extends DriftReport {
-    blame: BlameAttribution[];
-}
+export type { DriftIssue, FileReport, RepoQualityScore, RiskHotspot, MaintenanceRiskMetrics, AIIssue, AIOutput, AIOutputJson, DriftReport, DriftReportJson, DriftOutputMetadata, } from './types/core.js';
+export type { MergeRiskLevel, TrustGatePolicyPreset, TrustGatePolicyPack, TrustGatePolicyConfig, TrustReason, TrustFixPriority, TrustAdvancedComparison, TrustAdvancedContext, TrustDiffContext, DriftTrustReport, DriftTrustReportJson, TrustKpiDiagnostic, TrustScoreStats, TrustDiffTrendSummary, TrustKpiReport, } from './types/trust.js';
+export type { LayerDefinition, ModuleBoundary, DriftPerformanceConfig, DriftAnalysisOptions, } from './types/config.js';
+export type { DriftConfig } from './types/app.js';
+export type { PluginRuleContext, DriftPluginRule, DriftPlugin, LoadedPlugin, PluginLoadError, PluginLoadWarning, } from './types/plugin.js';
+export type { FileDiff, DriftDiff, HistoricalAnalysis, TrendDataPoint, BlameAttribution, DriftTrendReport, DriftBlameReport, } from './types/diff.js';
+export type { GuardBaseline, GuardThresholds, GuardOptions, GuardMetrics, GuardCheck, GuardEvaluation, GuardResult, } from './guard-types.js';
+export type { SarifLevel, DriftSarifRule, DriftSarifResult, DriftSarifRun, DriftSarifLog, } from './sarif.js';
 //# sourceMappingURL=types.d.ts.map

package/docs/release-notes-draft.md

@@ -0,0 +1,40 @@
+# Release Notes Draft (S5)
+
+## Scope
+
+This draft covers the latest trust-core and SARIF-related changes prepared for release packaging.
+
+## What changed
+
+- Added/solidified release-facing CLI capabilities:
+  - `init` for project scaffolding and baseline bootstrap.
+  - `doctor` for environment diagnostics.
+  - `guard` for non-regression enforcement by diff or baseline.
+- Consolidated output format behavior around `--format` and preserved legacy aliases for compatibility.
+- Added SARIF output coverage across critical commands (`scan`, `ci`, `diff`, `review`, `trust`).
+- Aligned CI and action v2 contract expectations with SARIF-enabled workflows.
+- Expanded tests and docs to reduce release risk in CLI output contracts.
+
+## User impact
+
+- Teams can ingest drift findings in SARIF-native tooling without custom adapters.
+- Trust/review automation in PRs is more consistent thanks to normalized output contracts.
+- Onboarding and guardrail setup are faster with `init`, `doctor`, and `guard`.
+
+## Risks and watch points
+
+- SARIF consumers may still differ in strictness; validate in at least one real CI environment.
+- Legacy alias paths (`--json`, `--comment`, `--markdown`) depend on compatibility behavior and should remain covered by tests.
+- Trust/reporting flows rely on artifact path conventions in CI; keep workflow and docs synchronized.
+
+## Minimal validation before tag
+
+- Smoke no-build commands:
+  - `scan --format sarif`
+  - `ci --format sarif`
+  - `trust --format sarif`
+  - `review --format sarif` (or `diff --format sarif` fallback)
+- Targeted tests:
+  - `tests/cli-sarif.test.ts`
+  - `tests/format.test.ts`
+  - `tests/sarif.test.ts`

package/docs/rules-catalog.md

@@ -0,0 +1,49 @@
+# drift rules catalog (current)
+
+Source of truth: `RULE_WEIGHTS` in `src/analyzer.ts`.
+
+This catalog reflects the current repository state and includes all rule IDs currently weighted/scored by drift.
+
+| id | severity | weight | phase/origin | note |
+|---|---|---:|---|---|
+| `large-file` | error | 20 | phase0-basic | file exceeds size threshold |
+| `large-function` | error | 15 | phase0-basic | function exceeds line threshold |
+| `debug-leftover` | warning | 10 | phase0-basic | debug console calls / TODO-like leftovers |
+| `dead-code` | warning | 8 | phase0-basic | unused named imports in file |
+| `duplicate-function-name` | error | 18 | phase0-basic | repeated function names in same file |
+| `comment-contradiction` | warning | 12 | comments rule | comment restates obvious code intent |
+| `no-return-type` | info | 5 | phase0-basic | missing explicit return type |
+| `catch-swallow` | warning | 10 | phase0-basic | empty catch blocks |
+| `magic-number` | info | 3 | magic rule | numeric literals used directly |
+| `any-abuse` | warning | 8 | phase0-basic | explicit `any` usage |
+| `high-complexity` | error | 15 | phase1-complexity | high cyclomatic complexity |
+| `deep-nesting` | warning | 12 | nesting rule | nested control flow too deep |
+| `too-many-params` | warning | 8 | nesting rule | function has too many parameters |
+| `high-coupling` | warning | 10 | coupling rule | too many module dependencies |
+| `promise-style-mix` | warning | 7 | promise rule | mixed async/await and then/catch styles |
+| `unused-export` | warning | 8 | phase2-crossfile | export not imported elsewhere |
+| `dead-file` | warning | 10 | phase2-crossfile | file not imported by project |
+| `unused-dependency` | warning | 6 | phase2-crossfile | package.json dependency unused in sources |
+| `circular-dependency` | error | 14 | phase3-arch | circular import graph edges |
+| `layer-violation` | error | 16 | phase3-arch (config-driven) | invalid import direction across configured layers |
+| `cross-boundary-import` | warning | 10 | phase3-arch (config-driven) | invalid import across configured modules/boundaries |
+| `controller-no-db` | warning | 11 | phase3-configurable | controller imports DB/repository concerns directly |
+| `service-no-http` | warning | 11 | phase3-configurable | service imports/uses HTTP transport concerns |
+| `max-function-lines` | warning | 9 | phase3-configurable | function/method exceeds configured max lines |
+| `over-commented` | info | 4 | phase5-ai | excessive comments heuristic |
+| `hardcoded-config` | warning | 10 | phase5-ai | hardcoded URLs/secrets/config literals |
+| `inconsistent-error-handling` | warning | 8 | phase5-ai | mixed error-handling styles |
+| `unnecessary-abstraction` | warning | 7 | phase5-ai | wrappers/abstractions with little value |
+| `naming-inconsistency` | warning | 6 | phase5-ai | mixed naming conventions |
+| `ai-code-smell` | warning | 12 | analyzer meta-rule | aggregated AI-smell signal from multiple heuristics |
+| `semantic-duplication` | warning | 12 | phase8-semantic | AST fingerprint identifies equivalent functions |
+| `plugin-error` | warning | 4 | plugin diagnostics | plugin load/contract/runtime failure surfaced as issue |
+| `plugin-warning` | info | 0 | plugin diagnostics | non-fatal plugin validation warning |
+| `analysis-skip-max-files` | info | 0 | analysis guardrail diagnostics | file skipped due to `maxFiles` limit |
+| `analysis-skip-file-size` | info | 0 | analysis guardrail diagnostics | file skipped due to `maxFileSizeKb` limit |
+
+## Notes
+
+- Config-driven rules require matching config blocks to execute (`layers`, `modules`/legacy aliases, `architectureRules`).
+- `plugin-*` and `analysis-skip-*` are diagnostic rules emitted as issues and included in scoring with their configured weights.
+- Total rule IDs currently defined: **35**.