driftdetect-dashboard 0.8.1 → 0.8.2

package/dist/server/drift-data-reader.d.ts

@@ -0,0 +1,522 @@
+/**
+ * DriftDataReader
+ *
+ * Reads and parses data from the .drift/ folder structure.
+ * Provides methods for accessing patterns, violations, files, and configuration.
+ *
+ * OPTIMIZED: Uses DataLake for fast reads with pre-computed views.
+ * Falls back to direct file reading when lake data is unavailable.
+ *
+ * @requirements 1.6 - THE Dashboard_Server SHALL read pattern and violation data from the existing `.drift/` folder structure
+ * @requirements 8.1 - THE Dashboard_Server SHALL expose GET `/api/patterns` to list all patterns
+ * @requirements 8.2 - THE Dashboard_Server SHALL expose GET `/api/patterns/:id` to get pattern details with locations
+ * @requirements 8.6 - THE Dashboard_Server SHALL expose GET `/api/violations` to list all violations
+ * @requirements 8.7 - THE Dashboard_Server SHALL expose GET `/api/files` to get the file tree
+ * @requirements 8.8 - THE Dashboard_Server SHALL expose GET `/api/files/:path` to get patterns and violations for a specific file
+ * @requirements 8.9 - THE Dashboard_Server SHALL expose GET `/api/stats` to get overview statistics
+ */
+import type { PatternStatus, PatternCategory, Severity } from 'driftdetect-core';
+export interface PatternQuery {
+    category?: string;
+    status?: string;
+    minConfidence?: number;
+    search?: string;
+}
+export interface ViolationQuery {
+    severity?: string;
+    file?: string;
+    patternId?: string;
+    search?: string;
+}
+/**
+ * Pattern representation for the dashboard API
+ */
+export interface DashboardPattern {
+    id: string;
+    name: string;
+    category: string;
+    subcategory: string;
+    status: PatternStatus;
+    description: string;
+    confidence: {
+        score: number;
+        level: string;
+    };
+    locationCount: number;
+    outlierCount: number;
+    severity: string;
+    metadata: {
+        firstSeen: string;
+        lastSeen: string;
+        tags?: string[] | undefined;
+    };
+}
+/**
+ * Pattern with full location details for the dashboard API
+ */
+export interface DashboardPatternWithLocations extends DashboardPattern {
+    locations: SemanticLocation[];
+    outliers: OutlierWithDetails[];
+}
+/**
+ * Semantic location for the dashboard
+ */
+export interface SemanticLocation {
+    file: string;
+    range: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+}
+/**
+ * Outlier with reason details
+ */
+export interface OutlierWithDetails extends SemanticLocation {
+    reason: string;
+    deviationScore?: number | undefined;
+}
+/**
+ * Violation representation for the dashboard API
+ */
+export interface DashboardViolation {
+    id: string;
+    patternId: string;
+    patternName: string;
+    severity: string;
+    file: string;
+    range: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+    message: string;
+    expected: string;
+    actual: string;
+}
+/**
+ * File tree node for hierarchical file structure
+ * @requirements 8.7 - GET `/api/files` to get the file tree
+ */
+export interface FileTreeNode {
+    name: string;
+    path: string;
+    type: 'file' | 'directory';
+    children?: FileTreeNode[];
+    patternCount?: number;
+    violationCount?: number;
+    severity?: Severity;
+}
+/**
+ * File details with patterns and violations
+ * @requirements 8.8 - GET `/api/files/:path` to get patterns and violations for a specific file
+ */
+export interface FileDetails {
+    path: string;
+    language: string;
+    lineCount: number;
+    patterns: Array<{
+        id: string;
+        name: string;
+        category: PatternCategory;
+        locations: SemanticLocation[];
+    }>;
+    violations: DashboardViolation[];
+}
+/**
+ * Drift configuration
+ * @requirements 8.10, 8.11 - Configuration management
+ */
+export interface DriftConfig {
+    version: string;
+    detectors: DetectorConfigEntry[];
+    severityOverrides: Record<string, Severity>;
+    ignorePatterns: string[];
+    watchOptions?: {
+        debounce: number;
+        categories?: PatternCategory[];
+    };
+}
+/**
+ * Detector configuration entry
+ */
+export interface DetectorConfigEntry {
+    id: string;
+    name: string;
+    enabled: boolean;
+    category: PatternCategory;
+    options?: Record<string, unknown>;
+}
+/**
+ * Dashboard statistics
+ * @requirements 8.9 - GET `/api/stats` to get overview statistics
+ */
+export interface DashboardStats {
+    healthScore: number;
+    patterns: {
+        total: number;
+        byStatus: Record<PatternStatus, number>;
+        byCategory: Record<PatternCategory, number>;
+    };
+    violations: {
+        total: number;
+        bySeverity: Record<Severity, number>;
+    };
+    files: {
+        total: number;
+        scanned: number;
+    };
+    detectors: {
+        active: number;
+        total: number;
+    };
+    lastScan: string | null;
+}
+/**
+ * Contract representation for the dashboard API
+ */
+export interface DashboardContract {
+    id: string;
+    method: string;
+    endpoint: string;
+    status: string;
+    backend: {
+        file: string;
+        line: number;
+        framework: string;
+        responseFields: Array<{
+            name: string;
+            type: string;
+            optional: boolean;
+        }>;
+    };
+    frontend: Array<{
+        file: string;
+        line: number;
+        library: string;
+        responseType?: string;
+        responseFields: Array<{
+            name: string;
+            type: string;
+            optional: boolean;
+        }>;
+    }>;
+    mismatches: Array<{
+        fieldPath: string;
+        mismatchType: string;
+        description: string;
+        severity: string;
+    }>;
+    mismatchCount: number;
+    confidence: {
+        score: number;
+        level: string;
+    };
+    metadata: {
+        firstSeen: string;
+        lastSeen: string;
+        verifiedAt?: string;
+    };
+}
+/**
+ * Contract statistics for the dashboard
+ */
+export interface DashboardContractStats {
+    totalContracts: number;
+    byStatus: Record<string, number>;
+    byMethod: Record<string, number>;
+    totalMismatches: number;
+    mismatchesByType: Record<string, number>;
+}
+/**
+ * A snapshot of a single pattern's state at a point in time
+ */
+export interface PatternSnapshot {
+    patternId: string;
+    patternName: string;
+    category: PatternCategory;
+    confidence: number;
+    locationCount: number;
+    outlierCount: number;
+    complianceRate: number;
+    status: PatternStatus;
+}
+/**
+ * Category summary in a snapshot
+ */
+export interface CategorySummary {
+    patternCount: number;
+    avgConfidence: number;
+    totalLocations: number;
+    totalOutliers: number;
+    complianceRate: number;
+}
+/**
+ * A full snapshot of all patterns at a point in time
+ */
+export interface HistorySnapshot {
+    timestamp: string;
+    date: string;
+    patterns: PatternSnapshot[];
+    summary: {
+        totalPatterns: number;
+        avgConfidence: number;
+        totalLocations: number;
+        totalOutliers: number;
+        overallComplianceRate: number;
+        byCategory: Record<string, CategorySummary>;
+    };
+}
+/**
+ * A detected regression or improvement
+ */
+export interface PatternTrend {
+    patternId: string;
+    patternName: string;
+    category: PatternCategory;
+    type: 'regression' | 'improvement' | 'stable';
+    metric: 'confidence' | 'compliance' | 'outliers';
+    previousValue: number;
+    currentValue: number;
+    change: number;
+    changePercent: number;
+    severity: 'critical' | 'warning' | 'info';
+    firstSeen: string;
+    details: string;
+}
+/**
+ * Aggregated trends for the dashboard
+ */
+export interface TrendSummary {
+    period: '7d' | '30d' | '90d';
+    startDate: string;
+    endDate: string;
+    regressions: PatternTrend[];
+    improvements: PatternTrend[];
+    stable: number;
+    overallTrend: 'improving' | 'declining' | 'stable';
+    healthDelta: number;
+    categoryTrends: Record<string, {
+        trend: 'improving' | 'declining' | 'stable';
+        avgConfidenceChange: number;
+        complianceChange: number;
+    }>;
+}
+export declare class DriftDataReader {
+    private readonly driftDir;
+    private readonly patternsDir;
+    private readonly dataLake;
+    private lakeInitialized;
+    constructor(driftDir: string);
+    /**
+     * Get the drift directory path
+     */
+    get directory(): string;
+    /**
+     * Initialize the data lake (lazy initialization)
+     */
+    private initializeLake;
+    /**
+     * Get all patterns, optionally filtered
+     * OPTIMIZED: Uses DataLake pattern shards for fast category-based queries
+     *
+     * @requirements 8.1 - List all patterns
+     */
+    getPatterns(query?: PatternQuery): Promise<DashboardPattern[]>;
+    /**
+     * Get patterns from DataLake (optimized path)
+     */
+    private getPatternsFromLake;
+    /**
+     * Get a single pattern by ID with all locations
+     *
+     * @requirements 8.2 - Get pattern details with locations
+     */
+    getPattern(id: string): Promise<DashboardPatternWithLocations | null>;
+    /**
+     * Get all violations, optionally filtered
+     *
+     * Violations are derived from pattern outliers.
+     *
+     * @requirements 8.6 - List all violations
+     */
+    getViolations(query?: ViolationQuery): Promise<DashboardViolation[]>;
+    /**
+     * Get dashboard statistics
+     * OPTIMIZED: Uses DataLake status view for instant response
+     * @requirements 8.9 - GET `/api/stats` to get overview statistics
+     */
+    getStats(): Promise<DashboardStats>;
+    /**
+     * Convert StatusView from DataLake to DashboardStats
+     */
+    private statusViewToStats;
+    /**
+     * Get the file tree structure
+     * @requirements 8.7 - GET `/api/files` to get the file tree
+     */
+    getFileTree(): Promise<FileTreeNode[]>;
+    /**
+     * Get details for a specific file
+     * @requirements 8.8 - GET `/api/files/:path` to get patterns and violations for a specific file
+     */
+    getFileDetails(filePath: string): Promise<FileDetails | null>;
+    /**
+     * Get configuration
+     * @requirements 8.10 - GET `/api/config` to get configuration
+     */
+    getConfig(): Promise<DriftConfig>;
+    /**
+     * Update configuration
+     * @requirements 8.11 - PUT `/api/config` to update configuration
+     */
+    updateConfig(partial: Partial<DriftConfig>): Promise<void>;
+    /**
+     * Approve a pattern - changes status to 'approved'
+     * @requirements 4.4 - Approve pattern
+     * @requirements 8.3 - POST `/api/patterns/:id/approve` to approve a pattern
+     */
+    approvePattern(id: string): Promise<void>;
+    /**
+     * Ignore a pattern - changes status to 'ignored'
+     * @requirements 4.5 - Ignore pattern
+     * @requirements 8.4 - POST `/api/patterns/:id/ignore` to ignore a pattern
+     */
+    ignorePattern(id: string): Promise<void>;
+    /**
+     * Delete a pattern - removes from storage
+     * @requirements 4.6 - Delete pattern
+     * @requirements 8.5 - DELETE `/api/patterns/:id` to delete a pattern
+     */
+    deletePattern(id: string): Promise<void>;
+    /**
+     * Convert a StoredPattern to DashboardPattern
+     */
+    private storedToDashboardPattern;
+    /**
+     * Convert a StoredPattern to DashboardPatternWithLocations
+     */
+    private storedToDashboardPatternWithLocations;
+    /**
+     * Convert an outlier to a violation
+     */
+    private outlierToViolation;
+    /**
+     * Filter patterns based on query
+     */
+    private filterPatterns;
+    /**
+     * Filter violations based on query
+     */
+    private filterViolations;
+    /**
+     * Calculate health score based on violations and patterns
+     *
+     * Health score formula:
+     * - Base score starts at 100
+     * - Deduct for violations by severity (error: -10, warning: -3, info: -1, hint: 0)
+     * - Bonus for approved patterns (shows intentional architecture)
+     * - Clamp to 0-100
+     */
+    private calculateHealthScore;
+    /**
+     * Build a hierarchical file tree from file information
+     */
+    private buildFileTree;
+    /**
+     * Sort file tree: directories first, then alphabetically
+     */
+    private sortFileTree;
+    /**
+     * Compare severity levels
+     * Returns positive if a > b, negative if a < b, 0 if equal
+     */
+    private compareSeverity;
+    /**
+     * Get programming language from file path
+     */
+    private getLanguageFromPath;
+    /**
+     * Change pattern status (move between status directories)
+     */
+    private changePatternStatus;
+    /**
+     * Find a pattern's location in the file system
+     */
+    private findPatternLocation;
+    /**
+     * Get default configuration
+     */
+    private getDefaultConfig;
+    /**
+     * Get code snippet from a file at a specific line with context
+     */
+    getCodeSnippet(filePath: string, line: number, contextLines?: number): Promise<{
+        code: string;
+        startLine: number;
+        endLine: number;
+        language: string;
+    } | null>;
+    /**
+     * Get all contracts, optionally filtered
+     */
+    getContracts(query?: {
+        status?: string;
+        method?: string;
+        hasMismatches?: boolean;
+        search?: string;
+    }): Promise<DashboardContract[]>;
+    /**
+     * Get a single contract by ID
+     */
+    getContract(id: string): Promise<DashboardContract | null>;
+    /**
+     * Get contract statistics
+     */
+    getContractStats(): Promise<DashboardContractStats>;
+    /**
+     * Verify a contract
+     */
+    verifyContract(id: string): Promise<void>;
+    /**
+     * Ignore a contract
+     */
+    ignoreContract(id: string): Promise<void>;
+    /**
+     * Change contract status
+     */
+    private changeContractStatus;
+    /**
+     * Filter contracts based on query
+     */
+    private filterContracts;
+    /**
+     * Get trend summary for pattern regressions and improvements
+     * OPTIMIZED: Uses DataLake trends view for instant response
+     */
+    getTrends(period?: '7d' | '30d' | '90d'): Promise<TrendSummary | null>;
+    /**
+     * Convert TrendsView from DataLake to TrendSummary
+     * TrendsView has: generatedAt, period, overallTrend, healthDelta, regressions, improvements, stableCount, categoryTrends
+     */
+    private trendsViewToSummary;
+    /**
+     * Get historical snapshots for charting
+     */
+    getSnapshots(limit?: number): Promise<HistorySnapshot[]>;
+    /**
+     * Calculate trend summary between two snapshots
+     */
+    private calculateTrendSummary;
+}
+//# sourceMappingURL=drift-data-reader.d.ts.map