vibecheck-ai 2.0.1 → 5.0.0

package/dist/scanner/index.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Unified Scanner Types
+ *
+ * Single source of truth for all finding types across all engines.
+ */
+type Severity = 'critical' | 'high' | 'medium' | 'low';
+type Category = 'credentials' | 'security' | 'fake-features' | 'hallucinations' | 'mock-data' | 'code-quality' | 'dead-ui' | 'drift' | 'import-graph' | 'runtime-verify';
+type Confidence = 'certain' | 'likely' | 'possible';
+interface Finding {
+    /** Unique finding ID (e.g., SEC001-file-line) */
+    id: string;
+    /** Rule ID from the catalog (e.g., SEC001, HAL003) */
+    ruleId: string;
+    /** Which engine produced this finding */
+    engine: string;
+    /** Finding category */
+    category: Category;
+    /** Severity level */
+    severity: Severity;
+    /** Confidence level */
+    confidence: Confidence;
+    /** Numeric confidence score 0-100 */
+    confidenceScore: number;
+    /** File path (relative to project root) */
+    file: string;
+    /** Line number */
+    line: number;
+    /** Column number */
+    column?: number;
+    /** End line (for multi-line findings) */
+    endLine?: number;
+    /** The offending code snippet */
+    code: string;
+    /** Short message */
+    message: string;
+    /** Why this matters (user-facing) */
+    why: string;
+    /** How to fix */
+    fix: string;
+    /** Whether this can be auto-fixed */
+    autoFixable: boolean;
+    /** Tags for filtering */
+    tags: string[];
+    /** CWE ID if applicable */
+    cwe?: string;
+    /** Whether this was verified by a second pass */
+    verified: boolean;
+    /** Context around the finding for dedup */
+    _dedup?: string;
+}
+interface ScanOptions {
+    /** Project root directory */
+    projectRoot: string;
+    /** Specific files to scan */
+    files?: string[];
+    /** File patterns to include */
+    include?: string[];
+    /** File patterns to exclude */
+    exclude?: string[];
+    /** Severity threshold */
+    severityThreshold?: Severity;
+    /** Enable incremental scanning (only changed files) */
+    incremental?: boolean;
+    /** Enable parallel engine execution */
+    parallel?: boolean;
+    /** Max parallel workers */
+    workers?: number;
+    /** Engine timeout (ms) */
+    engineTimeout?: number;
+    /** Include test files in scan */
+    includeTests?: boolean;
+    /** Engines to enable (defaults to all) */
+    engines?: string[];
+    /** Progress callback */
+    onProgress?: (progress: ScanProgress) => void;
+    /** Finding callback (streaming) */
+    onFinding?: (finding: Finding) => void;
+}
+interface ScanProgress {
+    phase: 'loading' | 'classifying' | 'scanning' | 'deduplicating' | 'complete';
+    engine?: string;
+    processed: number;
+    total: number;
+    percentage: number;
+    elapsedMs: number;
+}
+interface ScanReport {
+    /** Unique scan ID */
+    scanId: string;
+    /** Timestamp */
+    timestamp: string;
+    /** All findings (deduplicated, sorted by severity) */
+    findings: Finding[];
+    /** Summary */
+    summary: {
+        totalFiles: number;
+        filesScanned: number;
+        totalFindings: number;
+        bySeverity: Record<Severity, number>;
+        byCategory: Record<string, number>;
+        byEngine: Record<string, number>;
+        autoFixable: number;
+        suppressedDuplicates: number;
+    };
+    /** Health score (0-100) */
+    healthScore: number;
+    /** Per-engine results */
+    engineResults: EngineResult[];
+    /** Performance metrics */
+    metrics: {
+        durationMs: number;
+        filesPerSecond: number;
+        engineTimings: Record<string, number>;
+    };
+}
+interface EngineResult {
+    engine: string;
+    findings: number;
+    durationMs: number;
+    success: boolean;
+    error?: string;
+}
+interface FileContext {
+    /** Relative path */
+    path: string;
+    /** Absolute path */
+    absolutePath: string;
+    /** File content */
+    content: string;
+    /** Lines split for per-line scanning */
+    lines: string[];
+    /** File extension */
+    ext: string;
+    /** Content hash for caching */
+    hash: string;
+    /** Path classification */
+    classification: PathClassification;
+}
+type PathCategory = 'user_code' | 'test' | 'third_party' | 'generated' | 'build_output' | 'config' | 'documentation';
+interface PathClassification {
+    category: PathCategory;
+    reason: string;
+    excludeByDefault: boolean;
+    isCriticalPath: boolean;
+}
+interface ScanEngine {
+    /** Engine name */
+    name: string;
+    /** Engine description */
+    description: string;
+    /** Run the engine against loaded files */
+    scan(files: Map<string, FileContext>, options: ScanOptions): Promise<Finding[]>;
+}
+interface FixResult {
+    /** The finding that was fixed */
+    findingId: string;
+    /** Rule ID */
+    ruleId: string;
+    /** File that was modified */
+    file: string;
+    /** Line number */
+    line: number;
+    /** Original code */
+    original: string;
+    /** Replacement code */
+    replacement: string;
+    /** Whether the fix was actually applied (false in dry-run) */
+    applied: boolean;
+    /** Description of the fix */
+    description: string;
+}
+interface FixReport {
+    /** Total fixable findings */
+    totalFixable: number;
+    /** Number of fixes applied */
+    applied: number;
+    /** Number of fixes skipped (e.g. file changed) */
+    skipped: number;
+    /** Individual fix results */
+    fixes: FixResult[];
+    /** Duration */
+    durationMs: number;
+}
+
+/**
+ * Auto-Fix Engine
+ *
+ * Applies automated fixes for findings marked with autoFixable: true.
+ *
+ * Supported fixes:
+ *   - QLT001: Remove console.log/debug/trace statements
+ *   - QLT002: Remove debugger statements
+ *   - QLT004: Remove unused imports (basic)
+ *   - SEC009: Replace Math.random() with crypto.randomUUID()
+ *   - IG004/HAL006: Add missing env vars to .env.example
+ *
+ * Supports --dry-run mode to preview changes without writing.
+ * Fixes are applied bottom-up (highest line first) to avoid offset drift.
+ */
+
+interface FixOptions {
+    /** Findings to fix (only autoFixable ones are processed) */
+    findings: Finding[];
+    /** Project root directory */
+    projectRoot: string;
+    /** If true, show what would change without writing */
+    dryRun: boolean;
+}
+/**
+ * Apply auto-fixes for all fixable findings.
+ *
+ * Fixes are grouped by file and applied bottom-up to avoid line offset drift.
+ */
+declare function applyFixes(options: FixOptions): FixReport;
+
+/**
+ * Rule Catalog
+ *
+ * Every rule has a human-readable "why" and "fix" so users understand
+ * exactly what's wrong and how to fix it.
+ *
+ * Source: FOUR (v3.5.1) rule catalog, expanded with CORE + CLI5 rules
+ */
+interface RuleDefinition {
+    ruleId: string;
+    name: string;
+    category: string;
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    description: string;
+    why: string;
+    fix: string;
+    tags: string[];
+    autoFixable: boolean;
+    cwe?: string;
+}
+declare const RULE_CATALOG: Record<string, RuleDefinition>;
+declare function getRuleOrDefault(ruleId: string): RuleDefinition;
+
+/**
+ * Path Classifier
+ *
+ * Categorizes files for smart filtering. Reduces false positives by
+ * understanding file context (test vs prod, generated vs authored, etc.)
+ *
+ * Source: FOUR (v3.5.1) path-classifier, enhanced
+ */
+
+declare function classifyPath(relativePath: string): PathClassification;
+
+/**
+ * VibeCheck Unified Scanner
+ *
+ * The most accurate AI code scanner on the market.
+ *
+ * Combines 6 specialized engines running in parallel:
+ *   1. Credentials — hardcoded secrets, API keys, tokens (20 patterns)
+ *   2. Security — injection, XSS, SSRF, prototype pollution (30 patterns)
+ *   3. Fake Features — stubs, fake success, auth bypass, silent failures (25+ patterns)
+ *   4. Hallucinations — fake packages, ghost routes, placeholder URLs (13 patterns)
+ *   5. Dead UI — dead links, noop handlers, coming soon, disabled without reason (5 checks)
+ *   6. Code Quality — debug code, type safety, mock data (18 patterns)
+ *
+ * Plus:
+ *   - PathClassifier for smart file filtering (from FOUR v3.5.1)
+ *   - Rule Catalog with human-readable "why" + "fix" for every finding
+ *   - Cross-engine deduplication with confidence boosting
+ *   - Severity escalation for critical-path files (api/, auth/, payment/)
+ *
+ * Architecture:
+ *   Files → Classify → [6 Engines in parallel] → Deduplicate → Score → Report
+ */
+
+declare const ALL_ENGINES: ScanEngine[];
+declare function scan(options: ScanOptions): Promise<ScanReport>;
+declare function fix(options: ScanOptions & {
+    dryRun?: boolean;
+}): Promise<{
+    report: ScanReport;
+    fixReport: FixReport;
+}>;
+
+export { ALL_ENGINES, type FileContext, type Finding, type FixReport, RULE_CATALOG, type ScanEngine, type ScanOptions, type ScanReport, applyFixes, classifyPath, fix, getRuleOrDefault, scan };