@opencodereview/core 1.9.1

package/dist/sla/tracker.js

@@ -0,0 +1,151 @@
+/**
+ * SLA Tracker
+ *
+ * Tracks scan performance against SLA targets.
+ * Provides timeout checking and metric collection.
+ *
+ * Usage:
+ * ```ts
+ * const tracker = new SLATracker(SLALevel.L2_STANDARD, 47);
+ * tracker.start();
+ *
+ * // During scan — check if we should degrade
+ * const check = tracker.checkTimeout();
+ * if (check.shouldDegrade) {
+ *   // Skip remaining Tier 2/3 detectors
+ * }
+ *
+ * // After scan — collect final metrics
+ * const metrics = tracker.finalize(issues, detectorsUsed, detectorsTotal);
+ * ```
+ */
+import { SLALevel, SLA_TARGET_DURATIONS, SLA_AI_ANALYSIS, } from './types.js';
+export class SLATracker {
+    startTime = 0;
+    level;
+    fileCount;
+    _degraded = false;
+    _degradeReason;
+    /**
+     * @param level - SLA level for this scan
+     * @param fileCount - Number of files to scan (used for scaling target duration)
+     */
+    constructor(level, fileCount = 100) {
+        this.level = level;
+        this.fileCount = Math.max(1, fileCount);
+    }
+    /**
+     * Start the SLA timer.
+     */
+    start() {
+        this.startTime = Date.now();
+        this._degraded = false;
+        this._degradeReason = undefined;
+    }
+    /**
+     * Get elapsed time since start (ms).
+     */
+    get elapsedMs() {
+        if (this.startTime === 0)
+            return 0;
+        return Date.now() - this.startTime;
+    }
+    /**
+     * Calculate the target duration for the actual file count.
+     * Scales linearly from the per-100-files target.
+     * Minimum target is 1 second regardless of file count.
+     */
+    get targetDurationMs() {
+        const baseDuration = SLA_TARGET_DURATIONS[this.level];
+        return Math.max(1000, Math.ceil((this.fileCount / 100) * baseDuration));
+    }
+    /**
+     * Check if the scan is exceeding the SLA target.
+     * Returns whether degradation should occur.
+     *
+     * Degradation threshold: 80% of target time consumed → recommend degrading.
+     * This gives detectors remaining 20% to wrap up.
+     */
+    checkTimeout() {
+        const elapsed = this.elapsedMs;
+        const target = this.targetDurationMs;
+        const threshold = target * 0.8; // 80% threshold
+        if (elapsed >= threshold) {
+            const reason = `Elapsed ${elapsed}ms exceeds 80% of target ${target}ms for SLA ${this.level}`;
+            return {
+                shouldDegrade: true,
+                reason,
+                elapsedMs: elapsed,
+                targetMs: target,
+            };
+        }
+        return {
+            shouldDegrade: false,
+            reason: `Within target: ${elapsed}ms / ${target}ms`,
+            elapsedMs: elapsed,
+            targetMs: target,
+        };
+    }
+    /**
+     * Mark this scan as degraded.
+     */
+    markDegraded(reason) {
+        this._degraded = true;
+        this._degradeReason = reason;
+    }
+    /**
+     * Collect final SLA metrics after the scan completes.
+     */
+    finalize(issues, detectorsUsed, detectorsTotal) {
+        const scanDurationMs = this.elapsedMs;
+        const targetDurationMs = this.targetDurationMs;
+        // Count issues by severity
+        const counts = countBySeverity(issues);
+        return {
+            level: this.level,
+            scanDurationMs,
+            filesScanned: this.fileCount,
+            detectorsUsed,
+            detectorsTotal,
+            aiAnalysis: SLA_AI_ANALYSIS[this.level],
+            issuesFound: issues.length,
+            criticalCount: counts.critical,
+            highCount: counts.high,
+            mediumCount: counts.medium,
+            lowCount: counts.low,
+            infoCount: counts.info,
+            targetDurationMs,
+            withinTarget: scanDurationMs <= targetDurationMs,
+            degraded: this._degraded,
+            degradeReason: this._degradeReason,
+        };
+    }
+}
+// ─── Helpers ───────────────────────────────────────────────────────
+function countBySeverity(issues) {
+    const counts = {
+        critical: 0,
+        high: 0,
+        medium: 0,
+        low: 0,
+        info: 0,
+    };
+    for (const issue of issues) {
+        counts[issue.severity] = (counts[issue.severity] ?? 0) + 1;
+    }
+    return counts;
+}
+// ─── SLA Level Helpers ─────────────────────────────────────────────
+/**
+ * Parse an SLA level string to enum value.
+ */
+export function parseSLALevel(value) {
+    const upper = value.toUpperCase();
+    switch (upper) {
+        case 'L1': return SLALevel.L1_FAST;
+        case 'L2': return SLALevel.L2_STANDARD;
+        case 'L3': return SLALevel.L3_DEEP;
+        default: return SLALevel.L2_STANDARD;
+    }
+}
+//# sourceMappingURL=tracker.js.map

package/dist/sla/tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../../src/sla/tracker.ts"],"names":[],"mappings":"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"}

package/dist/sla/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * SLA Type Definitions
+ *
+ * Defines SLA levels, metrics, and target thresholds for
+ * Open Code Review scanning performance.
+ */
+export declare enum SLALevel {
+    /** ≤10s/100files, no AI, ≥80% accuracy */
+    L1_FAST = "L1",
+    /** ≤30s/100files, optional local AI, ≥85% accuracy */
+    L2_STANDARD = "L2",
+    /** ≤120s/100files, local+remote AI, ≥90% accuracy */
+    L3_DEEP = "L3"
+}
+/**
+ * Target duration per 100 files for each SLA level (in milliseconds).
+ */
+export declare const SLA_TARGET_DURATIONS: Record<SLALevel, number>;
+/**
+ * AI analysis type for each SLA level.
+ */
+export declare const SLA_AI_ANALYSIS: Record<SLALevel, 'none' | 'local' | 'local+remote'>;
+/**
+ * Target accuracy for each SLA level.
+ */
+export declare const SLA_ACCURACY_TARGETS: Record<SLALevel, number>;
+export interface SLAMetrics {
+    /** SLA level used for this scan */
+    level: SLALevel;
+    /** Total scan duration in milliseconds */
+    scanDurationMs: number;
+    /** Number of files scanned */
+    filesScanned: number;
+    /** Number of detectors that actually ran */
+    detectorsUsed: number;
+    /** Total number of available detectors */
+    detectorsTotal: number;
+    /** Type of AI analysis used */
+    aiAnalysis: 'none' | 'local' | 'local+remote';
+    /** Total issues found */
+    issuesFound: number;
+    /** Issue counts by severity */
+    criticalCount: number;
+    highCount: number;
+    mediumCount: number;
+    lowCount: number;
+    infoCount: number;
+    /** Target duration for the file count (scaled from per-100-files target) */
+    targetDurationMs: number;
+    /** Whether scan completed within target duration */
+    withinTarget: boolean;
+    /** Whether the scan was degraded due to timeout */
+    degraded: boolean;
+    /** Reason for degradation (if any) */
+    degradeReason?: string;
+}
+export interface SLATimeoutCheck {
+    /** Whether the current scan should degrade to a lower tier */
+    shouldDegrade: boolean;
+    /** Human-readable reason */
+    reason: string;
+    /** Elapsed time in ms */
+    elapsedMs: number;
+    /** Target time in ms */
+    targetMs: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sla/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sla/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,oBAAY,QAAQ;IAClB,0CAA0C;IAC1C,OAAO,OAAO;IACd,sDAAsD;IACtD,WAAW,OAAO;IAClB,qDAAqD;IACrD,OAAO,OAAO;CACf;AAID;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAIzD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,cAAc,CAI/E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAIzD,CAAC;AAIF,MAAM,WAAW,UAAU;IACzB,mCAAmC;IACnC,KAAK,EAAE,QAAQ,CAAC;IAEhB,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;IAEvB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;IAErB,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IAEtB,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;IAEvB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,cAAc,CAAC;IAE9C,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IAEpB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAElB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC;IAEzB,oDAAoD;IACpD,YAAY,EAAE,OAAO,CAAC;IAEtB,mDAAmD;IACnD,QAAQ,EAAE,OAAO,CAAC;IAElB,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAC;IACvB,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/sla/types.js

@@ -0,0 +1,42 @@
+/**
+ * SLA Type Definitions
+ *
+ * Defines SLA levels, metrics, and target thresholds for
+ * Open Code Review scanning performance.
+ */
+// ─── SLA Level ─────────────────────────────────────────────────────
+export var SLALevel;
+(function (SLALevel) {
+    /** ≤10s/100files, no AI, ≥80% accuracy */
+    SLALevel["L1_FAST"] = "L1";
+    /** ≤30s/100files, optional local AI, ≥85% accuracy */
+    SLALevel["L2_STANDARD"] = "L2";
+    /** ≤120s/100files, local+remote AI, ≥90% accuracy */
+    SLALevel["L3_DEEP"] = "L3";
+})(SLALevel || (SLALevel = {}));
+// ─── SLA Target Durations ──────────────────────────────────────────
+/**
+ * Target duration per 100 files for each SLA level (in milliseconds).
+ */
+export const SLA_TARGET_DURATIONS = {
+    [SLALevel.L1_FAST]: 10_000, // 10s / 100 files
+    [SLALevel.L2_STANDARD]: 30_000, // 30s / 100 files
+    [SLALevel.L3_DEEP]: 120_000, // 120s / 100 files
+};
+/**
+ * AI analysis type for each SLA level.
+ */
+export const SLA_AI_ANALYSIS = {
+    [SLALevel.L1_FAST]: 'none',
+    [SLALevel.L2_STANDARD]: 'local',
+    [SLALevel.L3_DEEP]: 'local+remote',
+};
+/**
+ * Target accuracy for each SLA level.
+ */
+export const SLA_ACCURACY_TARGETS = {
+    [SLALevel.L1_FAST]: 0.80,
+    [SLALevel.L2_STANDARD]: 0.85,
+    [SLALevel.L3_DEEP]: 0.90,
+};
+//# sourceMappingURL=types.js.map

package/dist/sla/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sla/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,sEAAsE;AAEtE,MAAM,CAAN,IAAY,QAOX;AAPD,WAAY,QAAQ;IAClB,0CAA0C;IAC1C,0BAAc,CAAA;IACd,sDAAsD;IACtD,8BAAkB,CAAA;IAClB,qDAAqD;IACrD,0BAAc,CAAA;AAChB,CAAC,EAPW,QAAQ,KAAR,QAAQ,QAOnB;AAED,sEAAsE;AAEtE;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6B;IAC5D,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,EAAM,kBAAkB;IAClD,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,kBAAkB;IAClD,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,EAAK,mBAAmB;CACpD,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAwD;IAClF,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM;IAC1B,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO;IAC/B,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc;CACnC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6B;IAC5D,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI;IACxB,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI;IAC5B,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI;CACzB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Open Code Review V3 — Unified Type Definitions
+ *
+ * Core types shared across all modules: detectors, scoring engine,
+ * SLA framework, config system, and language adapters.
+ *
+ * @since 0.3.0
+ */
+/**
+ * Classification of AI-specific defect patterns.
+ * These categories represent issues unique to AI-generated code
+ * that traditional linters typically don't cover.
+ */
+export declare enum AIDefectCategory {
+    /** AI references non-existent packages, APIs, or methods */
+    HALLUCINATION = "hallucination",
+    /** AI uses outdated/deprecated APIs from training data */
+    STALE_KNOWLEDGE = "stale-knowledge",
+    /** AI loses context across long outputs, causing inconsistencies */
+    CONTEXT_LOSS = "context-loss",
+    /** AI generates code with security vulnerabilities */
+    SECURITY_ANTIPATTERN = "security",
+    /** AI over-engineers solutions with unnecessary complexity */
+    OVER_ENGINEERING = "over-engineering",
+    /** AI leaves incomplete implementations (TODO, stubs, empty catch) */
+    INCOMPLETE_IMPL = "incomplete",
+    /** AI generates type-unsafe code (excessive any, unsafe casts) */
+    TYPE_SAFETY = "type-safety",
+    /** AI generates code with missing/incorrect error handling */
+    ERROR_HANDLING = "error-handling",
+    /** AI duplicates logic that should be extracted */
+    DUPLICATION = "duplication",
+    /** AI leaks training data patterns (license headers, example code) */
+    TRAINING_LEAK = "training-leak"
+}
+/** Severity levels for detected issues, from most to least critical */
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+/** Deduction points per severity level */
+export declare const SEVERITY_DEDUCTIONS: Record<Severity, number>;
+/**
+ * Unified Issue format — standard output for ALL detectors.
+ * Every detected problem is represented as a UnifiedIssue.
+ */
+export interface UnifiedIssue {
+    /** Unique issue ID (e.g. "hallucination:1") */
+    id: string;
+    /** Name of the detector that found this issue */
+    detector: string;
+    /** Issue sub-type (e.g. "phantom-package", "empty-catch") */
+    type?: string;
+    /** AI defect category */
+    category: AIDefectCategory;
+    /** Severity level */
+    severity: Severity;
+    /** Human-readable description */
+    message: string;
+    /** File path */
+    file: string;
+    /** Line number (1-based) */
+    line: number;
+    /** Column number (1-based, optional) */
+    column?: number;
+    /** End line (optional, for range) */
+    endLine?: number;
+    /** End column (optional, for range) */
+    endColumn?: number;
+    /** Source code snippet around the issue */
+    source?: string;
+    /** Suggested fix description */
+    suggestion?: string;
+    /** Structured fix info */
+    fix?: {
+        description: string;
+        autoFixable: boolean;
+    };
+    /** Attribution: root cause and frequency */
+    attribution?: {
+        rootCause: string;
+        frequency: 'common' | 'occasional' | 'rare';
+    };
+    /** Reference links */
+    references?: string[] | {
+        urls: string[];
+        cweId?: string;
+    };
+    /** Whether auto-fixable */
+    autoFixable?: boolean;
+    /** Effort to fix */
+    fixEffort?: 'trivial' | 'small' | 'medium' | 'large';
+    /** Detection confidence (0.0-1.0) */
+    confidence?: number;
+    /** Detection source */
+    detectionSource?: 'static' | 'ai' | 'both';
+}
+/** Result of a detector run on a single file */
+export interface DetectorResult {
+    detector: string;
+    file: string;
+    issues: UnifiedIssue[];
+    durationMs: number;
+}
+/** Context passed to detectors during analysis */
+export interface AnalysisContext {
+    projectRoot: string;
+    config: import('./config/types.js').AICVConfig;
+    astCache: Map<string, unknown>;
+    registryCache: Map<string, {
+        exists: boolean;
+        checkedAt: number;
+    }>;
+}
+/**
+ * Unified Detector interface — all V3 detectors implement this.
+ *
+ * Tiers:
+ *   1 = Fast (regex/AST, <0.5s/100 files) — always enabled
+ *   2 = Deep (type-aware, <5s/100 files) — default enabled
+ *   3 = AI (LLM analysis) — opt-in with --ai flag
+ *
+ * Detectors may implement either or both:
+ *   - detect(files): simplified batch interface (Worker A pattern)
+ *   - analyze(filePath, source, ctx): per-file with context (Architecture doc pattern)
+ */
+export interface Detector {
+    /** Detector identifier */
+    readonly name: string;
+    /** Semantic version */
+    readonly version: string;
+    /** Execution tier: 1=fast, 2=deep, 3=AI */
+    readonly tier: 1 | 2 | 3;
+    /**
+     * Batch detection on multiple files.
+     * @param files Array of file analysis inputs
+     * @returns Array of unified issues found
+     */
+    detect(files: FileAnalysis[]): Promise<UnifiedIssue[]>;
+}
+/** Supported language identifiers */
+export type SupportedLanguage = 'typescript' | 'javascript' | 'python' | 'java' | 'go' | 'kotlin';
+/**
+ * Input for detector analysis — represents a single file to be analyzed.
+ * The `ast` field is optional and populated by the LanguageAdapter if available.
+ */
+export interface FileAnalysis {
+    /** Absolute or relative file path */
+    path: string;
+    /** Full file content */
+    content: string;
+    /** Programming language identifier */
+    language: SupportedLanguage | string;
+    /** Parsed AST (language-specific, populated by LanguageAdapter) */
+    ast?: unknown;
+}
+/** Grade levels for V3 scoring */
+export type Grade = 'A+' | 'A' | 'B' | 'C' | 'D' | 'F';
+/** Scoring dimension identifier */
+export type ScoringDimensionId = 'aiFaithfulness' | 'codeFreshness' | 'contextCoherence' | 'implementationQuality';
+/** V3 scoring dimension names (short form) */
+export type ScoringDimension = 'faithfulness' | 'freshness' | 'coherence' | 'quality';
+/** Scoring dimension configuration */
+export interface ScoringDimensionConfig {
+    weight: number;
+    name: string;
+}
+/** V3 scoring dimension weights (must sum to 100) */
+export declare const SCORING_WEIGHTS: Record<ScoringDimension, number>;
+/**
+ * Maps each AIDefectCategory to its primary scoring dimension.
+ * Used by the scoring engine to route issues to the correct dimension.
+ */
+export declare const CATEGORY_DIMENSION_MAP: Record<AIDefectCategory, ScoringDimension>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,69 @@
+/**
+ * Open Code Review V3 — Unified Type Definitions
+ *
+ * Core types shared across all modules: detectors, scoring engine,
+ * SLA framework, config system, and language adapters.
+ *
+ * @since 0.3.0
+ */
+// ─── AI Defect Categories ──────────────────────────────────────────
+/**
+ * Classification of AI-specific defect patterns.
+ * These categories represent issues unique to AI-generated code
+ * that traditional linters typically don't cover.
+ */
+export var AIDefectCategory;
+(function (AIDefectCategory) {
+    /** AI references non-existent packages, APIs, or methods */
+    AIDefectCategory["HALLUCINATION"] = "hallucination";
+    /** AI uses outdated/deprecated APIs from training data */
+    AIDefectCategory["STALE_KNOWLEDGE"] = "stale-knowledge";
+    /** AI loses context across long outputs, causing inconsistencies */
+    AIDefectCategory["CONTEXT_LOSS"] = "context-loss";
+    /** AI generates code with security vulnerabilities */
+    AIDefectCategory["SECURITY_ANTIPATTERN"] = "security";
+    /** AI over-engineers solutions with unnecessary complexity */
+    AIDefectCategory["OVER_ENGINEERING"] = "over-engineering";
+    /** AI leaves incomplete implementations (TODO, stubs, empty catch) */
+    AIDefectCategory["INCOMPLETE_IMPL"] = "incomplete";
+    /** AI generates type-unsafe code (excessive any, unsafe casts) */
+    AIDefectCategory["TYPE_SAFETY"] = "type-safety";
+    /** AI generates code with missing/incorrect error handling */
+    AIDefectCategory["ERROR_HANDLING"] = "error-handling";
+    /** AI duplicates logic that should be extracted */
+    AIDefectCategory["DUPLICATION"] = "duplication";
+    /** AI leaks training data patterns (license headers, example code) */
+    AIDefectCategory["TRAINING_LEAK"] = "training-leak";
+})(AIDefectCategory || (AIDefectCategory = {}));
+/** Deduction points per severity level */
+export const SEVERITY_DEDUCTIONS = {
+    critical: 15,
+    high: 10,
+    medium: 5,
+    low: 2,
+    info: 0,
+};
+/** V3 scoring dimension weights (must sum to 100) */
+export const SCORING_WEIGHTS = {
+    faithfulness: 35,
+    freshness: 25,
+    coherence: 20,
+    quality: 20,
+};
+/**
+ * Maps each AIDefectCategory to its primary scoring dimension.
+ * Used by the scoring engine to route issues to the correct dimension.
+ */
+export const CATEGORY_DIMENSION_MAP = {
+    [AIDefectCategory.HALLUCINATION]: 'faithfulness',
+    [AIDefectCategory.STALE_KNOWLEDGE]: 'freshness',
+    [AIDefectCategory.CONTEXT_LOSS]: 'coherence',
+    [AIDefectCategory.SECURITY_ANTIPATTERN]: 'faithfulness',
+    [AIDefectCategory.OVER_ENGINEERING]: 'quality',
+    [AIDefectCategory.INCOMPLETE_IMPL]: 'quality',
+    [AIDefectCategory.TYPE_SAFETY]: 'quality',
+    [AIDefectCategory.ERROR_HANDLING]: 'quality',
+    [AIDefectCategory.DUPLICATION]: 'quality',
+    [AIDefectCategory.TRAINING_LEAK]: 'faithfulness',
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,sEAAsE;AAEtE;;;;GAIG;AACH,MAAM,CAAN,IAAY,gBAqBX;AArBD,WAAY,gBAAgB;IAC1B,4DAA4D;IAC5D,mDAA+B,CAAA;IAC/B,0DAA0D;IAC1D,uDAAmC,CAAA;IACnC,oEAAoE;IACpE,iDAA6B,CAAA;IAC7B,sDAAsD;IACtD,qDAAiC,CAAA;IACjC,8DAA8D;IAC9D,yDAAqC,CAAA;IACrC,sEAAsE;IACtE,kDAA8B,CAAA;IAC9B,kEAAkE;IAClE,+CAA2B,CAAA;IAC3B,8DAA8D;IAC9D,qDAAiC,CAAA;IACjC,mDAAmD;IACnD,+CAA2B,CAAA;IAC3B,sEAAsE;IACtE,mDAA+B,CAAA;AACjC,CAAC,EArBW,gBAAgB,KAAhB,gBAAgB,QAqB3B;AAOD,0CAA0C;AAC1C,MAAM,CAAC,MAAM,mBAAmB,GAA6B;IAC3D,QAAQ,EAAE,EAAE;IACZ,IAAI,EAAE,EAAE;IACR,MAAM,EAAE,CAAC;IACT,GAAG,EAAE,CAAC;IACN,IAAI,EAAE,CAAC;CACC,CAAC;AAgJX,qDAAqD;AACrD,MAAM,CAAC,MAAM,eAAe,GAAqC;IAC/D,YAAY,EAAE,EAAE;IAChB,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;CACH,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAA+C;IAChF,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,cAAc;IAChD,CAAC,gBAAgB,CAAC,eAAe,CAAC,EAAE,WAAW;IAC/C,CAAC,gBAAgB,CAAC,YAAY,CAAC,EAAE,WAAW;IAC5C,CAAC,gBAAgB,CAAC,oBAAoB,CAAC,EAAE,cAAc;IACvD,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,EAAE,SAAS;IAC9C,CAAC,gBAAgB,CAAC,eAAe,CAAC,EAAE,SAAS;IAC7C,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,SAAS;IACzC,CAAC,gBAAgB,CAAC,cAAc,CAAC,EAAE,SAAS;IAC5C,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,SAAS;IACzC,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,cAAc;CACxC,CAAC"}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@opencodereview/core",
+  "version": "1.9.1",
+  "description": "Core detection engine for AI-generated code validation",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./scanner": {
+      "import": "./dist/scanner/index.js",
+      "types": "./dist/scanner/index.d.ts"
+    },
+    "./detectors/v4": {
+      "import": "./dist/detectors/v4/index.js",
+      "types": "./dist/detectors/v4/index.d.ts"
+    },
+    "./i18n": {
+      "import": "./dist/i18n/index.js",
+      "types": "./dist/i18n/index.d.ts"
+    },
+    "./config": {
+      "import": "./dist/config/v4-config.js",
+      "types": "./dist/config/v4-config.d.ts"
+    },
+    "./reporter": {
+      "import": "./dist/reporter/index.js",
+      "types": "./dist/reporter/index.d.ts"
+    },
+    "./reporter/v4-terminal": {
+      "import": "./dist/reporter/v4-terminal.js",
+      "types": "./dist/reporter/v4-terminal.d.ts"
+    },
+    "./scorer": {
+      "import": "./dist/scorer/scoring-engine.js",
+      "types": "./dist/scorer/scoring-engine.d.ts"
+    },
+    "./scorer/v4-adapter": {
+      "import": "./dist/scorer/v4-adapter.js",
+      "types": "./dist/scorer/v4-adapter.d.ts"
+    },
+    "./ai/v4": {
+      "import": "./dist/ai/v4/index.js",
+      "types": "./dist/ai/v4/index.d.ts"
+    },
+    "./ir": {
+      "import": "./dist/ir/index.js",
+      "types": "./dist/ir/index.d.ts"
+    },
+    "./parser": {
+      "import": "./dist/parser/index.js",
+      "types": "./dist/parser/index.d.ts"
+    },
+    "./registry": {
+      "import": "./dist/registry/index.js",
+      "types": "./dist/registry/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ai",
+    "code-quality",
+    "hallucination-detection",
+    "ci-cd",
+    "quality-gate"
+  ],
+  "author": "Raye Deng <fengsen.deng@gmail.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "dependencies": {
+    "acorn": "^8.11.0",
+    "acorn-walk": "^8.3.0",
+    "glob": "^10.3.0",
+    "oxc-parser": "^0.117.0",
+    "tree-sitter-wasms": "^0.1.13",
+    "web-tree-sitter": "^0.24.7",
+    "yaml": "^2.8.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/"
+  }
+}