@kevinrabun/judges 3.115.4 → 3.117.0

package/dist/review-conversation.js

@@ -0,0 +1,307 @@
+/**
+ * Multi-Turn Review Conversation
+ *
+ * Enables interactive, stateful review sessions where developers and
+ * the tribunal engage in a conversation about findings. This transforms
+ * the evaluation from a one-shot report into a collaborative review:
+ *
+ * - Developer asks "why?" about a finding → tribunal explains reasoning
+ * - Developer provides context → tribunal adjusts confidence
+ * - Developer requests re-evaluation → tribunal focuses on specific areas
+ * - Developer disputes a finding → tribunal logs disagreement and adjusts
+ *
+ * Designed for MCP tool sessions and VS Code extension interactions.
+ */
+// ─── Conversation Management ─────────────────────────────────────────────────
+let messageCounter = 0;
+function generateMessageId() {
+    messageCounter++;
+    return `msg_${Date.now().toString(36)}_${messageCounter.toString(36)}`;
+}
+function generateConversationId() {
+    return `conv_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * Start a new review conversation for a file evaluation.
+ */
+export function startReviewConversation(filePath, language, verdict) {
+    const now = new Date().toISOString();
+    const conversation = {
+        conversationId: generateConversationId(),
+        filePath,
+        language,
+        state: "active",
+        messages: [],
+        findings: [...verdict.findings],
+        originalVerdict: verdict,
+        developerContext: {
+            explanations: new Map(),
+            disputed: new Set(),
+            accepted: new Set(),
+            additionalContext: [],
+            focusAreas: [],
+        },
+        startedAt: now,
+        lastActivityAt: now,
+    };
+    // Add system opening message
+    addMessage(conversation, "system", "general", buildOpeningMessage(verdict));
+    return conversation;
+}
+/**
+ * Process a developer message and generate a tribunal response.
+ */
+export function processMessage(conversation, content, intent, findingRef) {
+    // Record the developer's message
+    addMessage(conversation, "developer", intent, content, findingRef);
+    // Generate tribunal response based on intent
+    let response;
+    switch (intent) {
+        case "explain":
+            response = handleExplainRequest(conversation, findingRef);
+            break;
+        case "context":
+            response = handleContextProvided(conversation, content, findingRef);
+            break;
+        case "dispute":
+            response = handleDispute(conversation, content, findingRef);
+            break;
+        case "accept":
+            response = handleAcceptance(conversation, findingRef);
+            break;
+        case "re-evaluate":
+            response = handleReEvaluateRequest(conversation, content);
+            break;
+        case "focus":
+            response = handleFocusRequest(conversation, content);
+            break;
+        case "summary":
+            response = buildConversationSummary(conversation);
+            break;
+        default:
+            response = handleGeneralMessage(conversation, content);
+            break;
+    }
+    // Record tribunal response
+    return addMessage(conversation, "tribunal", intent, response, findingRef);
+}
+/**
+ * Get the current state of outstanding findings in the conversation.
+ */
+export function getOutstandingFindings(conversation) {
+    const accepted = [];
+    const disputed = [];
+    const unaddressed = [];
+    for (const f of conversation.findings) {
+        const key = f.ruleId;
+        if (conversation.developerContext.accepted.has(key)) {
+            accepted.push(f);
+        }
+        else if (conversation.developerContext.disputed.has(key)) {
+            disputed.push(f);
+        }
+        else {
+            unaddressed.push(f);
+        }
+    }
+    return { unaddressed, accepted, disputed };
+}
+/**
+ * Check if all findings have been addressed (accepted or disputed).
+ */
+export function isConversationResolved(conversation) {
+    const { unaddressed } = getOutstandingFindings(conversation);
+    return unaddressed.length === 0;
+}
+/**
+ * Export the conversation as a reviewable markdown report.
+ */
+export function exportConversationAsMarkdown(conversation) {
+    const lines = [
+        `# Review Conversation: ${conversation.filePath}`,
+        "",
+        `**Started**: ${conversation.startedAt}`,
+        `**State**: ${conversation.state}`,
+        `**Findings**: ${conversation.findings.length}`,
+        "",
+        "---",
+        "",
+    ];
+    for (const msg of conversation.messages) {
+        const role = msg.role === "developer" ? "**Developer**" : msg.role === "tribunal" ? "**Tribunal**" : "*System*";
+        const ref = msg.findingRef ? ` (re: ${msg.findingRef})` : "";
+        lines.push(`### ${role}${ref}`);
+        lines.push(`*${msg.timestamp}* — \`${msg.intent}\``);
+        lines.push("");
+        lines.push(msg.content);
+        lines.push("");
+        lines.push("---");
+        lines.push("");
+    }
+    const { unaddressed, accepted, disputed } = getOutstandingFindings(conversation);
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(`- **Accepted**: ${accepted.length} finding(s)`);
+    lines.push(`- **Disputed**: ${disputed.length} finding(s)`);
+    lines.push(`- **Unaddressed**: ${unaddressed.length} finding(s)`);
+    return lines.join("\n");
+}
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+function addMessage(conversation, role, intent, content, findingRef) {
+    const msg = {
+        id: generateMessageId(),
+        role,
+        intent,
+        content,
+        timestamp: new Date().toISOString(),
+        findingRef,
+    };
+    conversation.messages.push(msg);
+    conversation.lastActivityAt = msg.timestamp;
+    // Check if conversation is resolved after each message
+    if (isConversationResolved(conversation)) {
+        conversation.state = "resolved";
+    }
+    return msg;
+}
+function findFinding(conversation, ref) {
+    if (!ref)
+        return undefined;
+    return conversation.findings.find((f) => f.ruleId === ref || f.title === ref);
+}
+function buildOpeningMessage(verdict) {
+    const critical = verdict.findings.filter((f) => f.severity === "critical").length;
+    const high = verdict.findings.filter((f) => f.severity === "high").length;
+    const medium = verdict.findings.filter((f) => f.severity === "medium").length;
+    const low = verdict.findings.filter((f) => f.severity === "low").length;
+    const parts = [`Code review complete. Found **${verdict.findings.length}** finding(s):`];
+    if (critical > 0)
+        parts.push(`- ${critical} critical`);
+    if (high > 0)
+        parts.push(`- ${high} high`);
+    if (medium > 0)
+        parts.push(`- ${medium} medium`);
+    if (low > 0)
+        parts.push(`- ${low} low`);
+    parts.push("");
+    parts.push("You can:");
+    parts.push("- Ask **why** a finding was flagged (`explain`)");
+    parts.push("- Provide **context** about your code (`context`)");
+    parts.push("- **Dispute** a false positive (`dispute`)");
+    parts.push("- **Accept** a finding to fix (`accept`)");
+    parts.push("- Request **re-evaluation** with new context (`re-evaluate`)");
+    return parts.join("\n");
+}
+function handleExplainRequest(conversation, ref) {
+    const finding = findFinding(conversation, ref);
+    if (!finding) {
+        // List all findings for the developer to pick
+        const list = conversation.findings
+            .map((f, i) => `${i + 1}. **${f.ruleId}** (${f.severity}): ${f.title}`)
+            .join("\n");
+        return `Which finding would you like explained?\n\n${list}`;
+    }
+    const parts = [
+        `## ${finding.ruleId}: ${finding.title}`,
+        "",
+        `**Severity**: ${finding.severity}`,
+        `**Confidence**: ${((finding.confidence ?? 0.5) * 100).toFixed(0)}%`,
+        `**Lines**: ${finding.lineNumbers?.join(", ") || "N/A"}`,
+        "",
+        finding.description,
+    ];
+    if (finding.recommendation) {
+        parts.push("", `**Recommendation**: ${finding.recommendation}`);
+    }
+    if (finding.reference) {
+        parts.push("", `**Reference**: ${finding.reference}`);
+    }
+    if (finding.provenance) {
+        parts.push("", `**Detection method**: ${finding.provenance}`);
+    }
+    return parts.join("\n");
+}
+function handleContextProvided(conversation, content, ref) {
+    conversation.developerContext.additionalContext.push(content);
+    if (ref) {
+        conversation.developerContext.explanations.set(ref, content);
+        const finding = findFinding(conversation, ref);
+        if (finding) {
+            // Reduce confidence since developer provided context
+            const oldConf = finding.confidence ?? 0.5;
+            finding.confidence = Math.max(0.1, oldConf * 0.7);
+            return `Context noted for **${ref}**. Confidence adjusted from ${(oldConf * 100).toFixed(0)}% to ${(finding.confidence * 100).toFixed(0)}%. This finding will be weighted less heavily.`;
+        }
+    }
+    return `Context recorded. This will be factored into any re-evaluation. (${conversation.developerContext.additionalContext.length} context note(s) total)`;
+}
+function handleDispute(conversation, content, ref) {
+    if (!ref) {
+        return "Please specify which finding you're disputing (e.g., by rule ID like SEC-001).";
+    }
+    conversation.developerContext.disputed.add(ref);
+    conversation.developerContext.explanations.set(ref, content);
+    const finding = findFinding(conversation, ref);
+    if (finding) {
+        finding.confidence = Math.max(0.05, (finding.confidence ?? 0.5) * 0.3);
+        return `Finding **${ref}** marked as disputed. Your reasoning has been recorded. Confidence reduced to ${(finding.confidence * 100).toFixed(0)}%. This will feed back into calibration to reduce false positives for similar patterns.`;
+    }
+    return `Dispute recorded for **${ref}**. Finding was not found in current results — it may have already been resolved.`;
+}
+function handleAcceptance(conversation, ref) {
+    if (!ref) {
+        return "Please specify which finding you accept (e.g., by rule ID like SEC-001), or say 'all' to accept all.";
+    }
+    if (ref === "all") {
+        for (const f of conversation.findings) {
+            conversation.developerContext.accepted.add(f.ruleId);
+        }
+        return `All ${conversation.findings.length} findings accepted. Good luck with the fixes!`;
+    }
+    conversation.developerContext.accepted.add(ref);
+    const { unaddressed } = getOutstandingFindings(conversation);
+    return `Finding **${ref}** accepted. ${unaddressed.length} finding(s) remaining.`;
+}
+function handleReEvaluateRequest(conversation, content) {
+    return `Re-evaluation requested. The following developer context will be applied:\n\n${conversation.developerContext.additionalContext.map((c, i) => `${i + 1}. ${c}`).join("\n")}\n\nRe-run the evaluation with this conversation's context for updated results.`;
+}
+function handleFocusRequest(conversation, content) {
+    conversation.developerContext.focusAreas.push(content);
+    return `Focus area recorded: "${content}". Re-evaluation will prioritize ${conversation.developerContext.focusAreas.join(", ")}.`;
+}
+function buildConversationSummary(conversation) {
+    const { unaddressed, accepted, disputed } = getOutstandingFindings(conversation);
+    const totalMessages = conversation.messages.length;
+    const parts = [
+        `## Conversation Summary`,
+        "",
+        `- **Total messages**: ${totalMessages}`,
+        `- **Findings**: ${conversation.findings.length}`,
+        `- **Accepted**: ${accepted.length}`,
+        `- **Disputed**: ${disputed.length}`,
+        `- **Unaddressed**: ${unaddressed.length}`,
+        `- **Context notes**: ${conversation.developerContext.additionalContext.length}`,
+        `- **State**: ${conversation.state}`,
+    ];
+    if (unaddressed.length > 0) {
+        parts.push("", "### Unaddressed Findings");
+        for (const f of unaddressed) {
+            parts.push(`- **${f.ruleId}** (${f.severity}): ${f.title}`);
+        }
+    }
+    if (disputed.length > 0) {
+        parts.push("", "### Disputed Findings");
+        for (const f of disputed) {
+            const reason = conversation.developerContext.explanations.get(f.ruleId);
+            parts.push(`- **${f.ruleId}**: ${reason || "(no reason given)"}`);
+        }
+    }
+    return parts.join("\n");
+}
+function handleGeneralMessage(conversation, _content) {
+    const { unaddressed } = getOutstandingFindings(conversation);
+    if (unaddressed.length === 0) {
+        return "All findings have been addressed. The review is complete.";
+    }
+    return `${unaddressed.length} finding(s) still need attention. You can \`explain\`, \`dispute\`, or \`accept\` each one.`;
+}

package/dist/sast-integration.d.ts

@@ -0,0 +1,112 @@
+/**
+ * SAST Integration Layer
+ *
+ * Bridges external Static Application Security Testing tools (CodeQL, Semgrep,
+ * Bandit, ESLint security rules, etc.) into the Judges evaluation pipeline.
+ *
+ * External SAST tools complement Judges' LLM-powered tribunal by providing:
+ * - Data-flow / taint analysis (CodeQL, Semgrep Pro)
+ * - Known CVE pattern matching
+ * - Language-specific semantic analysis
+ *
+ * This module:
+ * 1. Ingests SARIF (Static Analysis Results Interchange Format) reports
+ * 2. Normalizes external findings into Judges' Finding type
+ * 3. Deduplicates against existing Judges findings
+ * 4. Merges as supplementary evidence into tribunal verdicts
+ */
+import type { Finding, Severity, TribunalVerdict } from "./types.js";
+interface SarifLog {
+    $schema?: string;
+    version: string;
+    runs: SarifRun[];
+}
+interface SarifRun {
+    tool: {
+        driver: {
+            name: string;
+            version?: string;
+            rules?: SarifRule[];
+        };
+    };
+    results: SarifResult[];
+}
+interface SarifRule {
+    id: string;
+    name?: string;
+    shortDescription?: {
+        text: string;
+    };
+    fullDescription?: {
+        text: string;
+    };
+    defaultConfiguration?: {
+        level?: "none" | "note" | "warning" | "error";
+    };
+    properties?: Record<string, unknown>;
+}
+interface SarifResult {
+    ruleId: string;
+    message: {
+        text: string;
+    };
+    level?: "none" | "note" | "warning" | "error";
+    locations?: Array<{
+        physicalLocation?: {
+            artifactLocation?: {
+                uri?: string;
+            };
+            region?: {
+                startLine?: number;
+                endLine?: number;
+                startColumn?: number;
+                endColumn?: number;
+            };
+        };
+    }>;
+    fixes?: Array<{
+        description?: {
+            text: string;
+        };
+    }>;
+    properties?: Record<string, unknown>;
+}
+export interface SastProvider {
+    /** Provider name (e.g., "codeql", "semgrep", "bandit") */
+    name: string;
+    /** Parse provider-specific output into SARIF format */
+    parseSarif(content: string): SarifLog;
+    /** Map provider rule IDs to Judges rule ID prefixes */
+    mapRuleId(providerRuleId: string): string;
+    /** Map provider severity to Judges severity */
+    mapSeverity(level: string): Severity;
+}
+/** Register a SAST provider for integration. */
+export declare function registerSastProvider(provider: SastProvider): void;
+/** Get a registered SAST provider by name. */
+export declare function getSastProvider(name: string): SastProvider | undefined;
+/** List all registered SAST providers. */
+export declare function listSastProviders(): string[];
+/**
+ * Parse a SARIF file and convert results into Judges Finding objects.
+ */
+export declare function ingestSarifFile(filePath: string, providerName?: string): {
+    findings: Finding[];
+    toolName: string;
+    toolVersion?: string;
+};
+/**
+ * Parse SARIF content string and convert results into Judges Finding objects.
+ */
+export declare function ingestSarifContent(content: string, providerName?: string): {
+    findings: Finding[];
+    toolName: string;
+    toolVersion?: string;
+};
+/**
+ * Merge external SAST findings into a tribunal verdict.
+ * Deduplicates findings that overlap with existing judge findings
+ * (same file + overlapping line range + similar rule category).
+ */
+export declare function mergeSastFindings(verdict: TribunalVerdict, sastFindings: Finding[]): TribunalVerdict;
+export {};

package/dist/sast-integration.js

@@ -0,0 +1,215 @@
+/**
+ * SAST Integration Layer
+ *
+ * Bridges external Static Application Security Testing tools (CodeQL, Semgrep,
+ * Bandit, ESLint security rules, etc.) into the Judges evaluation pipeline.
+ *
+ * External SAST tools complement Judges' LLM-powered tribunal by providing:
+ * - Data-flow / taint analysis (CodeQL, Semgrep Pro)
+ * - Known CVE pattern matching
+ * - Language-specific semantic analysis
+ *
+ * This module:
+ * 1. Ingests SARIF (Static Analysis Results Interchange Format) reports
+ * 2. Normalizes external findings into Judges' Finding type
+ * 3. Deduplicates against existing Judges findings
+ * 4. Merges as supplementary evidence into tribunal verdicts
+ */
+import { readFileSync, existsSync } from "fs";
+const providers = new Map();
+/** Register a SAST provider for integration. */
+export function registerSastProvider(provider) {
+    providers.set(provider.name, provider);
+}
+/** Get a registered SAST provider by name. */
+export function getSastProvider(name) {
+    return providers.get(name);
+}
+/** List all registered SAST providers. */
+export function listSastProviders() {
+    return Array.from(providers.keys());
+}
+// ─── Default Providers ───────────────────────────────────────────────────────
+/** Generic SARIF provider — works with any SARIF 2.1.0 output */
+const genericSarifProvider = {
+    name: "sarif",
+    parseSarif(content) {
+        return JSON.parse(content);
+    },
+    mapRuleId(providerRuleId) {
+        return `SAST-${providerRuleId}`;
+    },
+    mapSeverity(level) {
+        switch (level) {
+            case "error":
+                return "high";
+            case "warning":
+                return "medium";
+            case "note":
+                return "low";
+            default:
+                return "medium";
+        }
+    },
+};
+/** CodeQL-specific provider */
+const codeqlProvider = {
+    name: "codeql",
+    parseSarif(content) {
+        return JSON.parse(content);
+    },
+    mapRuleId(providerRuleId) {
+        // CodeQL rules like "js/xss" → "SAST-CODEQL-JS-XSS"
+        const normalized = providerRuleId.replace(/\//g, "-").toUpperCase();
+        return `SAST-CODEQL-${normalized}`;
+    },
+    mapSeverity(level) {
+        switch (level) {
+            case "error":
+                return "critical";
+            case "warning":
+                return "high";
+            case "note":
+                return "medium";
+            default:
+                return "medium";
+        }
+    },
+};
+/** Semgrep-specific provider */
+const semgrepProvider = {
+    name: "semgrep",
+    parseSarif(content) {
+        return JSON.parse(content);
+    },
+    mapRuleId(providerRuleId) {
+        // Semgrep rules like "python.lang.security.audit.exec-detected" → "SAST-SEMGREP-EXEC-DETECTED"
+        const parts = providerRuleId.split(".");
+        const meaningful = parts.slice(-2).join("-").toUpperCase();
+        return `SAST-SEMGREP-${meaningful}`;
+    },
+    mapSeverity(level) {
+        switch (level) {
+            case "error":
+                return "high";
+            case "warning":
+                return "medium";
+            case "note":
+                return "low";
+            default:
+                return "medium";
+        }
+    },
+};
+// Register default providers
+registerSastProvider(genericSarifProvider);
+registerSastProvider(codeqlProvider);
+registerSastProvider(semgrepProvider);
+// ─── SARIF Ingestion ─────────────────────────────────────────────────────────
+/**
+ * Parse a SARIF file and convert results into Judges Finding objects.
+ */
+export function ingestSarifFile(filePath, providerName) {
+    if (!existsSync(filePath)) {
+        return { findings: [], toolName: "unknown" };
+    }
+    const content = readFileSync(filePath, "utf-8");
+    return ingestSarifContent(content, providerName);
+}
+/**
+ * Parse SARIF content string and convert results into Judges Finding objects.
+ */
+export function ingestSarifContent(content, providerName) {
+    const provider = providerName ? providers.get(providerName) : genericSarifProvider;
+    if (!provider) {
+        return { findings: [], toolName: "unknown" };
+    }
+    let sarif;
+    try {
+        sarif = provider.parseSarif(content);
+    }
+    catch {
+        return { findings: [], toolName: "unknown" };
+    }
+    const findings = [];
+    let toolName = "unknown";
+    let toolVersion;
+    for (const run of sarif.runs) {
+        toolName = run.tool.driver.name;
+        toolVersion = run.tool.driver.version;
+        const ruleMap = new Map();
+        if (run.tool.driver.rules) {
+            for (const rule of run.tool.driver.rules) {
+                ruleMap.set(rule.id, rule);
+            }
+        }
+        for (const result of run.results) {
+            const rule = ruleMap.get(result.ruleId);
+            const level = result.level || rule?.defaultConfiguration?.level || "warning";
+            const severity = provider.mapSeverity(level);
+            const ruleId = provider.mapRuleId(result.ruleId);
+            const lineNumbers = [];
+            let sourceFile;
+            if (result.locations) {
+                for (const loc of result.locations) {
+                    const region = loc.physicalLocation?.region;
+                    if (region?.startLine) {
+                        lineNumbers.push(region.startLine);
+                    }
+                    if (loc.physicalLocation?.artifactLocation?.uri) {
+                        sourceFile = loc.physicalLocation.artifactLocation.uri;
+                    }
+                }
+            }
+            const title = rule?.shortDescription?.text || rule?.name || result.ruleId;
+            const description = result.message.text || rule?.fullDescription?.text || "";
+            const fix = result.fixes?.[0]?.description?.text;
+            findings.push({
+                ruleId,
+                severity,
+                title,
+                description,
+                lineNumbers: lineNumbers.length > 0 ? lineNumbers : undefined,
+                recommendation: fix || `Address ${result.ruleId} finding from ${toolName}.`,
+                reference: `${toolName}: ${result.ruleId}`,
+                confidence: 0.9, // External SAST tools have high deterministic confidence
+                provenance: `sast-${toolName.toLowerCase()}`,
+                ...(sourceFile ? { filePath: sourceFile } : {}),
+            });
+        }
+    }
+    return { findings, toolName, toolVersion };
+}
+// ─── Merge with Tribunal Verdicts ────────────────────────────────────────────
+/**
+ * Merge external SAST findings into a tribunal verdict.
+ * Deduplicates findings that overlap with existing judge findings
+ * (same file + overlapping line range + similar rule category).
+ */
+export function mergeSastFindings(verdict, sastFindings) {
+    if (sastFindings.length === 0)
+        return verdict;
+    const existingKeys = new Set(verdict.findings.map((f) => {
+        const line = f.lineNumbers?.[0] || 0;
+        const bucket = Math.floor(line / 3) * 3;
+        return `${bucket}::${f.severity}`;
+    }));
+    const newFindings = [];
+    for (const sf of sastFindings) {
+        const line = sf.lineNumbers?.[0] || 0;
+        const bucket = Math.floor(line / 3) * 3;
+        const key = `${bucket}::${sf.severity}`;
+        // Only add if no existing finding covers roughly the same location and severity
+        if (!existingKeys.has(key)) {
+            newFindings.push(sf);
+            existingKeys.add(key);
+        }
+    }
+    if (newFindings.length === 0)
+        return verdict;
+    return {
+        ...verdict,
+        findings: [...verdict.findings, ...newFindings],
+        summary: `${verdict.summary}\n\n**SAST Supplement**: ${newFindings.length} additional finding(s) from external static analysis.`,
+    };
+}