@invisiblecities/sidequest-cqo/dist/utils/violation-types.d.ts

Configuration-agnostic TypeScript and ESLint orchestrator with real-time watch mode, SQLite persistence, and intelligent terminal detection

/**
 * @fileoverview Common types and interfaces for the Code Quality Orchestrator
 *
 * Defines the core data structures used across all audit engines and components
 * for consistent violation reporting and categorization.
 */
/**
 * Standard violation object used across all audit engines
 */
export interface Violation {
    /** Relative file path from project root */
    file: string;
    /** Line number where violation occurs */
    line: number;
    /** Column number (optional, for precise location) */
    column?: number;
    /** The actual code that violates the rule */
    code: string;
    /** Violation category for grouping and reporting */
    category: ViolationCategory;
    /** Severity level for prioritization */
    severity: ViolationSeverity;
    /** Source engine that detected this violation */
    source: ViolationSource;
    /** Specific rule that was violated (optional) */
    rule?: string;
    /** Human-readable description of the violation */
    message?: string;
    /** Suggested fix or action to resolve */
    fixSuggestion?: string;
}
/**
 * Violation categories for semantic grouping
 */
export type ViolationCategory = "type-alias" | "annotation" | "cast" | "record-type" | "generic-unknown" | "unknown-reference" | "branded-type" | "generic-constraint" | "module-resolution" | "unused-code" | "null-safety" | "inheritance" | "index-access" | "strict-config" | "setup-issue" | "code-quality" | "style" | "architecture" | "modernization" | "unused-vars" | "best-practices" | "legacy-type-rule" | "return-type" | "no-explicit-any" | "other-eslint" | "type-quality" | "async-issues" | "custom-script-summary" | "syntax-error" | "parse-error" | "import-error" | "complexity" | "maintainability" | "security" | "performance" | "dead-code" | "code-duplication" | "circular-dependency" | "architecture-violation" | "other";
/**
 * Configuration for crossover detection between ESLint and TypeScript
 */
export interface CrossoverConfig {
    /** Enable crossover detection and warnings */
    enabled: boolean;
    /** Warn when ESLint rules duplicate TypeScript compiler checks */
    warnOnTypeAwareRules: boolean;
    /** Warn when similar violations are found by both engines */
    warnOnDuplicateViolations: boolean;
    /** Exit with error code if crossover is detected */
    failOnCrossover: boolean;
}
/**
 * Crossover warning data
 */
export interface CrossoverWarning {
    type: "type-aware-rule" | "duplicate-violation" | "configuration-conflict";
    message: string;
    details: string;
    suggestion: string;
    severity: "warn" | "error";
    affectedRules?: string[];
    affectedFiles?: string[];
}
/**
 * Severity levels for prioritization
 */
export type ViolationSeverity = "error" | "warn" | "info";
/**
 * Source engines that can detect violations
 */
export type ViolationSource = "typescript" | "eslint" | "unused-exports" | "parser" | "complexity" | "zod-detection" | "security" | "performance" | "archaeology" | "custom";
/**
 * Configuration for audit engines
 */
export interface EngineConfig {
    /** Whether this engine is enabled */
    enabled: boolean;
    /** Engine-specific configuration options */
    options: Record<string, unknown>;
    /** Priority for execution order (lower = higher priority) */
    priority: number;
    /** Maximum time allowed for this engine to run (ms) */
    timeout?: number;
    /** Whether to continue analysis if this engine fails */
    allowFailure?: boolean;
}
/**
 * Results from an audit engine execution
 */
export interface EngineResult {
    /** Name of the engine that produced this result */
    engineName: string;
    /** Violations found by this engine */
    violations: Violation[];
    /** Execution time in milliseconds */
    executionTime: number;
    /** Whether the engine completed successfully */
    success: boolean;
    /** Error message if engine failed */
    error?: string;
    /** Additional metadata from the engine */
    metadata?: Record<string, unknown>;
}
/**
 * Overall orchestrator results
 */
export interface OrchestratorResult {
    /** All violations from all engines, deduplicated */
    violations: Violation[];
    /** Individual engine results */
    engineResults: EngineResult[];
    /** Total execution time */
    totalExecutionTime: number;
    /** Summary statistics */
    summary: ViolationSummary;
    /** Analysis timestamp */
    timestamp: string;
}
/**
 * Summary statistics for violations
 */
export interface ViolationSummary {
    /** Total number of violations */
    total: number;
    /** Breakdown by severity */
    bySeverity: Record<ViolationSeverity, number>;
    /** Breakdown by source engine */
    bySource: Record<ViolationSource, number>;
    /** Breakdown by category */
    byCategory: Record<ViolationCategory, number>;
    /** Top violated files */
    topFiles: Array<{
        file: string;
        count: number;
    }>;
}
/**
 * Watch mode event types
 */
export type WatchEvent = "file-changed" | "analysis-started" | "analysis-completed" | "violation-added" | "violation-removed" | "engine-failed" | "watch-stopped";
/**
 * Watch mode event data
 */
export interface WatchEventData {
    /** Type of event */
    type: WatchEvent;
    /** Timestamp of the event */
    timestamp: string;
    /** Event-specific payload */
    payload: unknown;
}
/**
 * Get human-readable label for violation category
 */
export declare function getCategoryLabel(category: ViolationCategory): string;
/**
 * Dead code violation details for unused exports and unreachable code
 */
export interface DeadCodeViolation extends Violation {
    category: "dead-code";
    source: "archaeology";
    /** Type of dead code detected */
    deadCodeType: "unused-export" | "unreachable-code" | "unused-import";
    /** Confidence level of detection (0-1) */
    confidence: number;
    /** Additional metadata for dead code analysis */
    metadata: {
        /** Export name (for unused exports) */
        exportName?: string;
        /** Import source (for unused imports) */
        importSource?: string;
        /** Whether this is re-exported from another module */
        isReExport?: boolean;
        /** Estimated impact of removal (low/medium/high) */
        removalImpact: "low" | "medium" | "high";
    };
}
/**
 * Code duplication violation details for duplicate code blocks
 */
export interface CodeDuplicationViolation extends Violation {
    category: "code-duplication";
    source: "archaeology";
    /** Similarity percentage (0-100) */
    similarity: number;
    /** Number of duplicated tokens */
    tokenCount: number;
    /** Other files containing similar code */
    duplicateFiles: string[];
    /** Additional metadata for duplication analysis */
    metadata: {
        /** Type of duplication detected */
        duplicationType: "exact" | "structural" | "semantic";
        /** Lines range of the duplicate block */
        duplicateLines: {
            start: number;
            end: number;
        };
        /** Suggested refactoring approach */
        refactoringApproach: "extract-function" | "extract-constant" | "extract-module" | "pattern-matching";
        /** Estimated effort to fix (low/medium/high) */
        fixEffort: "low" | "medium" | "high";
    };
}
/**
 * Comprehensive archaeology report for code quality analysis
 */
export interface ArchaeologyReport {
    /** Summary of archaeology analysis */
    summary: {
        /** Total violations found */
        totalViolations: number;
        /** Dead code violations */
        deadCodeCount: number;
        /** Code duplication violations */
        duplicationCount: number;
        /** Files analyzed */
        filesAnalyzed: number;
        /** Overall health score (0-100) */
        healthScore: number;
    };
    /** Dead code analysis results */
    deadCode: {
        /** List of unused exports */
        unusedExports: DeadCodeViolation[];
        /** Unreachable code blocks */
        unreachableCode: DeadCodeViolation[];
        /** Unused imports */
        unusedImports: DeadCodeViolation[];
        /** Total lines of dead code */
        totalDeadLines: number;
    };
    /** Code duplication analysis results */
    duplication: {
        /** Exact duplicates */
        exactDuplicates: CodeDuplicationViolation[];
        /** Structural duplicates */
        structuralDuplicates: CodeDuplicationViolation[];
        /** Duplication percentage by file */
        fileMetrics: Record<string, {
            duplicatedLines: number;
            totalLines: number;
            percentage: number;
        }>;
        /** Overall duplication percentage */
        overallDuplication: number;
    };
    /** Actionable recommendations */
    recommendations: {
        /** High-priority fixes */
        highPriority: ArchaeologyRecommendation[];
        /** Medium-priority fixes */
        mediumPriority: ArchaeologyRecommendation[];
        /** Low-priority fixes */
        lowPriority: ArchaeologyRecommendation[];
    };
    /** Technical debt metrics */
    technicalDebt: {
        /** Estimated time to fix all issues (hours) */
        estimatedFixTimeHours: number;
        /** Complexity score (1-10) */
        complexityScore: number;
        /** Maintainability index (0-100) */
        maintainabilityIndex: number;
    };
}
/**
 * Actionable recommendation for archaeology findings
 */
export interface ArchaeologyRecommendation {
    /** Type of recommendation */
    type: "remove-dead-code" | "extract-duplicate" | "refactor-structure" | "improve-imports";
    /** Description of the recommendation */
    description: string;
    /** Files affected by this recommendation */
    affectedFiles: string[];
    /** Estimated effort to implement */
    effort: "low" | "medium" | "high";
    /** Estimated impact on code quality */
    impact: "low" | "medium" | "high";
    /** Specific action steps */
    actionSteps: string[];
    /** Risk level of implementing this change */
    riskLevel: "low" | "medium" | "high";
}
/**
 * JSDoc annotation for archaeology exclusions
 *
 * @example
 * ```typescript
 * /**
 *  * @archaeology-exclude permanent "CLI entry point used by npm scripts"
 *  * @since 0.2.0
 *  *\/
 * export function generatePRD() { ... }
 *
 * /**
 *  * @archaeology-exclude temporary "Used by upcoming feature X"
 *  * @archaeology-recheck-after 0.3.0
 *  * @since 0.2.0
 *  *\/
 * export function experimentalFeature() { ... }
 * ```
 */
export interface ArchaeologyAnnotation {
    /** Type of exclusion */
    type: "permanent" | "temporary";
    /** Human-readable reason for exclusion */
    reason: string;
    /** Version when annotation was added */
    since?: string;
    /** Version after which to recheck (for temporary exclusions) */
    recheckAfter?: string;
    /** Additional metadata */
    metadata?: {
        /** Who added this annotation */
        author?: string;
        /** Related issue or PR */
        issue?: string;
        /** Expected removal date */
        expectedRemoval?: string;
    };
}
//# sourceMappingURL=violation-types.d.ts.map