@kevinrabun/judges-cli 3.124.0

package/dist/commands/notify.js

@@ -0,0 +1,324 @@
+/**
+ * `judges notify` — Webhook notification system for findings alerts.
+ *
+ * Sends evaluation results to configured webhook endpoints (Slack, Teams,
+ * generic HTTP). Users configure their own endpoints — Judges never stores
+ * or processes data on behalf of users.
+ *
+ * Usage:
+ *   judges notify --file results.json --channel slack        # Send to Slack
+ *   judges notify --file results.json --channel teams        # Send to Teams
+ *   judges notify --file results.json --channel webhook      # Generic webhook
+ *   judges eval src/app.ts --notify                          # Evaluate + notify
+ *
+ * Configuration in .judgesrc:
+ * ```json
+ * {
+ *   "notifications": {
+ *     "channels": [
+ *       { "type": "slack",   "url": "https://hooks.slack.com/..." },
+ *       { "type": "teams",   "url": "https://outlook.office.com/webhook/..." },
+ *       { "type": "webhook", "url": "https://my-server.com/judges-hook",
+ *         "headers": { "Authorization": "Bearer ..." } }
+ *     ],
+ *     "minSeverity": "medium",
+ *     "onlyOnFailure": false
+ *   }
+ * }
+ * ```
+ */
+// ─── Severity Filtering ─────────────────────────────────────────────────────
+const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+function meetsMinSeverity(findings, minSeverity) {
+    const threshold = SEVERITY_RANK[minSeverity] ?? 4;
+    return findings.filter((f) => (SEVERITY_RANK[f.severity] ?? 4) <= threshold);
+}
+// ─── Payload Construction ───────────────────────────────────────────────────
+export function buildNotificationPayload(target, verdict, filteredFindings) {
+    const summary = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+    for (const f of filteredFindings) {
+        summary[f.severity] = (summary[f.severity] || 0) + 1;
+    }
+    const topFindings = filteredFindings
+        .sort((a, b) => (SEVERITY_RANK[a.severity] ?? 4) - (SEVERITY_RANK[b.severity] ?? 4))
+        .slice(0, 10)
+        .map((f) => ({
+        ruleId: f.ruleId,
+        severity: f.severity,
+        title: f.title,
+        line: f.lineNumbers?.[0],
+    }));
+    return {
+        target,
+        verdict: verdict.overallVerdict,
+        score: verdict.overallScore,
+        summary,
+        totalFindings: filteredFindings.length,
+        topFindings,
+        timestamp: new Date().toISOString(),
+    };
+}
+// ─── Channel Formatters ─────────────────────────────────────────────────────
+function formatSlackPayload(payload) {
+    const emoji = payload.verdict === "pass" ? ":white_check_mark:" : payload.verdict === "fail" ? ":x:" : ":warning:";
+    const color = payload.verdict === "pass" ? "#36a64f" : payload.verdict === "fail" ? "#e01e5a" : "#ecb22e";
+    const findingLines = payload.topFindings
+        .map((f) => `• \`${f.ruleId}\` [${f.severity.toUpperCase()}] ${f.title}${f.line ? ` (L${f.line})` : ""}`)
+        .join("\n");
+    return {
+        attachments: [
+            {
+                color,
+                blocks: [
+                    {
+                        type: "section",
+                        text: {
+                            type: "mrkdwn",
+                            text: `${emoji} *Judges Panel — ${payload.verdict.toUpperCase()}*\n*Target:* \`${payload.target}\`\n*Score:* ${payload.score}/10 | *Findings:* ${payload.totalFindings}`,
+                        },
+                    },
+                    ...(payload.totalFindings > 0
+                        ? [
+                            {
+                                type: "section",
+                                text: {
+                                    type: "mrkdwn",
+                                    text: `*Summary:* ${Object.entries(payload.summary)
+                                        .filter(([, v]) => v > 0)
+                                        .map(([k, v]) => `${k}: ${v}`)
+                                        .join(" | ")}`,
+                                },
+                            },
+                        ]
+                        : []),
+                    ...(findingLines
+                        ? [
+                            {
+                                type: "section",
+                                text: {
+                                    type: "mrkdwn",
+                                    text: `*Top Findings:*\n${findingLines}`,
+                                },
+                            },
+                        ]
+                        : []),
+                ],
+            },
+        ],
+    };
+}
+function formatTeamsPayload(payload) {
+    const color = payload.verdict === "pass" ? "00FF00" : payload.verdict === "fail" ? "FF0000" : "FFAA00";
+    const icon = payload.verdict === "pass" ? "✅" : payload.verdict === "fail" ? "❌" : "⚠️";
+    const findingRows = payload.topFindings.map((f) => `| ${f.ruleId} | ${f.severity} | ${f.title} |`).join("\n");
+    return {
+        "@type": "MessageCard",
+        "@context": "http://schema.org/extensions",
+        themeColor: color,
+        summary: `Judges Panel — ${payload.verdict.toUpperCase()}`,
+        sections: [
+            {
+                activityTitle: `${icon} Judges Panel — ${payload.verdict.toUpperCase()}`,
+                facts: [
+                    { name: "Target", value: payload.target },
+                    { name: "Score", value: `${payload.score}/10` },
+                    { name: "Findings", value: String(payload.totalFindings) },
+                    ...Object.entries(payload.summary)
+                        .filter(([, v]) => v > 0)
+                        .map(([k, v]) => ({ name: k.charAt(0).toUpperCase() + k.slice(1), value: String(v) })),
+                ],
+                markdown: true,
+                text: payload.topFindings.length > 0
+                    ? `**Top Findings:**\n\n| Rule | Severity | Title |\n|------|----------|-------|\n${findingRows}`
+                    : "",
+            },
+        ],
+    };
+}
+function formatGenericWebhookPayload(payload) {
+    return payload;
+}
+// ─── Send Notification ──────────────────────────────────────────────────────
+export async function sendNotification(channel, payload) {
+    let body;
+    switch (channel.type) {
+        case "slack":
+            body = formatSlackPayload(payload);
+            break;
+        case "teams":
+            body = formatTeamsPayload(payload);
+            break;
+        case "webhook":
+        default:
+            body = formatGenericWebhookPayload(payload);
+            break;
+    }
+    try {
+        const response = await fetch(channel.url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(channel.headers ?? {}),
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            return { success: false, error: `HTTP ${response.status}: ${response.statusText}` };
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+// ─── Notify All Channels ────────────────────────────────────────────────────
+export async function notifyAllChannels(config, target, verdict) {
+    // Apply severity filter
+    const filtered = config.minSeverity ? meetsMinSeverity(verdict.findings, config.minSeverity) : verdict.findings;
+    // Skip if onlyOnFailure and verdict is pass
+    if (config.onlyOnFailure && verdict.overallVerdict === "pass") {
+        return;
+    }
+    // Skip if no findings after filtering and onlyOnFailure
+    if (filtered.length === 0 && config.onlyOnFailure) {
+        return;
+    }
+    const payload = buildNotificationPayload(target, verdict, filtered);
+    const results = await Promise.allSettled(config.channels.map(async (ch) => {
+        const result = await sendNotification(ch, payload);
+        return { channel: ch.name || ch.type, ...result };
+    }));
+    for (const r of results) {
+        if (r.status === "fulfilled") {
+            if (r.value.success) {
+                console.log(`  ✓ Notification sent to ${r.value.channel}`);
+            }
+            else {
+                console.error(`  ✗ Notification failed for ${r.value.channel}: ${r.value.error}`);
+            }
+        }
+        else {
+            console.error(`  ✗ Notification error: ${r.reason}`);
+        }
+    }
+}
+// ─── Config Parsing ─────────────────────────────────────────────────────────
+const VALID_SEVERITIES = new Set(["critical", "high", "medium", "low", "info"]);
+export function parseNotificationConfig(obj) {
+    if (!obj.notifications)
+        return undefined;
+    const raw = obj.notifications;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return undefined;
+    if (!Array.isArray(raw.channels))
+        return undefined;
+    const channels = [];
+    for (const ch of raw.channels) {
+        if (typeof ch !== "object" || ch === null)
+            continue;
+        const type = ch.type;
+        const url = ch.url;
+        if (!type || !url || !["slack", "teams", "webhook"].includes(type))
+            continue;
+        if (typeof url !== "string" || !url.startsWith("https://"))
+            continue;
+        channels.push({
+            type: type,
+            url,
+            headers: typeof ch.headers === "object" && ch.headers !== null ? ch.headers : undefined,
+            name: typeof ch.name === "string" ? ch.name : undefined,
+        });
+    }
+    if (channels.length === 0)
+        return undefined;
+    return {
+        channels,
+        minSeverity: typeof raw.minSeverity === "string" && VALID_SEVERITIES.has(raw.minSeverity)
+            ? raw.minSeverity
+            : undefined,
+        onlyOnFailure: typeof raw.onlyOnFailure === "boolean" ? raw.onlyOnFailure : false,
+    };
+}
+// ─── CLI Runner ─────────────────────────────────────────────────────────────
+export async function runNotify(argv) {
+    const file = argv.find((_a, i) => argv[i - 1] === "--file") || argv.find((_a, i) => argv[i - 1] === "-f");
+    const channelType = argv.find((_a, i) => argv[i - 1] === "--channel");
+    const url = argv.find((_a, i) => argv[i - 1] === "--url");
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges notify — Send evaluation results to webhook channels
+
+Usage:
+  judges notify --file results.json                    Send to configured channels
+  judges notify --file results.json --channel slack    Send to specific channel type
+  judges notify --url https://hooks.slack.com/...      Send to ad-hoc webhook
+
+Options:
+  --file, -f     Path to a Judges JSON result file
+  --channel      Channel type filter: slack | teams | webhook
+  --url          Ad-hoc webhook URL (overrides config)
+  --help, -h     Show this help
+`);
+        return;
+    }
+    // Load notification config from .judgesrc
+    const { existsSync: exists, readFileSync: readFile } = await import("fs");
+    let notifConfig;
+    for (const name of [".judgesrc", ".judgesrc.json"]) {
+        if (exists(name)) {
+            try {
+                const raw = JSON.parse(readFile(name, "utf-8"));
+                notifConfig = parseNotificationConfig(raw);
+            }
+            catch {
+                // Skip invalid config
+            }
+            break;
+        }
+    }
+    // Ad-hoc URL override
+    if (url) {
+        notifConfig = {
+            channels: [{ type: channelType || "webhook", url }],
+        };
+    }
+    if (!notifConfig || notifConfig.channels.length === 0) {
+        console.error('Error: No notification channels configured. Add "notifications" to .judgesrc or use --url.');
+        process.exit(1);
+    }
+    // Filter to specific channel type if requested
+    if (channelType && !url) {
+        notifConfig.channels = notifConfig.channels.filter((ch) => ch.type === channelType);
+        if (notifConfig.channels.length === 0) {
+            console.error(`Error: No ${channelType} channels configured.`);
+            process.exit(1);
+        }
+    }
+    if (!file) {
+        console.error("Error: --file is required. Provide a Judges JSON result file.");
+        process.exit(1);
+    }
+    if (!exists(file)) {
+        console.error(`Error: File not found: ${file}`);
+        process.exit(1);
+    }
+    try {
+        const data = JSON.parse(readFile(file, "utf-8"));
+        const verdict = {
+            overallVerdict: data.overallVerdict || data.verdict || "pass",
+            overallScore: data.overallScore || data.score || 0,
+            findings: data.findings || [],
+            evaluations: data.evaluations || [],
+            summary: data.summary || "",
+            criticalCount: data.criticalCount || 0,
+            highCount: data.highCount || 0,
+            timestamp: data.timestamp || new Date().toISOString(),
+        };
+        console.log(`Sending notifications for ${file}...`);
+        await notifyAllChannels(notifConfig, file, verdict);
+    }
+    catch (err) {
+        console.error(`Error reading results file: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+}

package/dist/commands/null-safety-audit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Null safety audit — identify null/undefined dereference risks, missing
+ * guards, and inconsistent nullability patterns.
+ */
+export declare function runNullSafetyAudit(argv: string[]): void;

package/dist/commands/null-safety-audit.js

@@ -0,0 +1,221 @@
+/**
+ * Null safety audit — identify null/undefined dereference risks, missing
+ * guards, and inconsistent nullability patterns.
+ */
+import { readFileSync, readdirSync, statSync } from "fs";
+import { join, extname } from "path";
+// ─── File Collection ────────────────────────────────────────────────────────
+const CODE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".java", ".go"]);
+function collectFiles(dir, max = 300) {
+    const files = [];
+    function walk(d) {
+        if (files.length >= max)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (files.length >= max)
+                return;
+            if (e.startsWith(".") || e === "node_modules" || e === "dist" || e === "build")
+                continue;
+            const full = join(d, e);
+            try {
+                if (statSync(full).isDirectory())
+                    walk(full);
+                else if (CODE_EXTS.has(extname(full)))
+                    files.push(full);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    walk(dir);
+    return files;
+}
+// ─── Analysis ───────────────────────────────────────────────────────────────
+function analyzeFile(filepath) {
+    const risks = [];
+    let content;
+    try {
+        content = readFileSync(filepath, "utf-8");
+    }
+    catch {
+        return risks;
+    }
+    const lines = content.split("\n");
+    const ext = extname(filepath);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Non-null assertion operator (TypeScript !)
+        if ((ext === ".ts" || ext === ".tsx") && /\w+!\.\w+/.test(line) && !/\/\//.test(line.split("!.")[0])) {
+            risks.push({
+                file: filepath,
+                line: i + 1,
+                risk: "Non-null assertion operator (!.)",
+                severity: "medium",
+                suggestion: "Replace with optional chaining (?.) or null check",
+            });
+        }
+        // Chained property access without optional chaining
+        if (/\w+\.\w+\.\w+\.\w+/.test(line) && !/\?\./.test(line) && !/import|from|require|\/\/|console/.test(line)) {
+            // Check if any intermediate could be null
+            if (/(?:result|response|data|item|user|config|options|params|body|payload)\.\w+\.\w+/.test(line)) {
+                risks.push({
+                    file: filepath,
+                    line: i + 1,
+                    risk: "Deep property access without null check",
+                    severity: "medium",
+                    suggestion: "Use optional chaining (?.) for potentially null chains",
+                });
+            }
+        }
+        // Array access without bounds check
+        if (/\w+\[\d+\]/.test(line) && !/length|\.at\(|slice|\/\//.test(line)) {
+            const block = lines.slice(Math.max(0, i - 3), i + 1).join("\n");
+            if (!/length|bounds|check|if\s*\(|\.at\(/i.test(block)) {
+                risks.push({
+                    file: filepath,
+                    line: i + 1,
+                    risk: "Array index access without bounds check",
+                    severity: "low",
+                    suggestion: "Check array length or use .at() with null check",
+                });
+            }
+        }
+        // Equality comparison with null using == instead of ===
+        if (/==\s*null\b/.test(line) && !/===\s*null/.test(line) && !/!==?\s*null/.test(line)) {
+            // == null catches both null and undefined in JS/TS, which is actually intentional in many cases
+            // Only flag if there's inconsistency
+        }
+        // Return type could be null but not documented (TypeScript)
+        if ((ext === ".ts" || ext === ".tsx") && /\):\s*\w+\s*\{/.test(line)) {
+            const funcBlock = lines.slice(i, Math.min(i + 20, lines.length)).join("\n");
+            if (/return\s+null\b|return\s+undefined\b/.test(funcBlock) &&
+                !/\|\s*null|\|\s*undefined|Maybe|Optional/.test(line)) {
+                risks.push({
+                    file: filepath,
+                    line: i + 1,
+                    risk: "Function returns null but type doesn't declare it",
+                    severity: "high",
+                    suggestion: "Add | null or | undefined to return type",
+                });
+            }
+        }
+        // Unsafe JSON.parse without try/catch
+        if (/JSON\.parse\s*\(/.test(line)) {
+            const block = lines.slice(Math.max(0, i - 5), Math.min(i + 5, lines.length)).join("\n");
+            if (!/try|catch|error/i.test(block)) {
+                risks.push({
+                    file: filepath,
+                    line: i + 1,
+                    risk: "JSON.parse without error handling",
+                    severity: "high",
+                    suggestion: "Wrap in try/catch — malformed input causes runtime crash",
+                });
+            }
+        }
+        // Destructuring without defaults
+        if (/const\s*\{[^}]+\}\s*=\s*\w+/.test(line) && !/=\s*\{/.test(line.split("=").slice(2).join("="))) {
+            const source = line.match(/=\s*(\w+)/)?.[1];
+            if (source && /result|response|data|args|params|options|config/i.test(source)) {
+                const block = lines.slice(Math.max(0, i - 3), i + 1).join("\n");
+                if (!/if\s*\(|&&|nullish|\?\?|optional/i.test(block)) {
+                    risks.push({
+                        file: filepath,
+                        line: i + 1,
+                        risk: "Destructuring potentially null value",
+                        severity: "medium",
+                        suggestion: "Add defaults or null check: const { x = default } = source ?? {}",
+                    });
+                }
+            }
+        }
+        // parseInt/parseFloat without NaN check
+        if (/(?:parseInt|parseFloat|Number)\s*\(/.test(line)) {
+            const block = lines.slice(i, Math.min(i + 3, lines.length)).join("\n");
+            if (!/isNaN|Number\.isFinite|Number\.isNaN|isFinite/i.test(block)) {
+                risks.push({
+                    file: filepath,
+                    line: i + 1,
+                    risk: "Number parsing without NaN check",
+                    severity: "low",
+                    suggestion: "Check for NaN after parsing: if (Number.isNaN(result))",
+                });
+            }
+        }
+        // Python-specific: using dict[key] instead of dict.get(key)
+        if (ext === ".py" && /\w+\[\s*['"][^'"]+['"]\s*\]/.test(line)) {
+            if (!/get\(|in\s+\w+|try|KeyError/i.test(lines.slice(Math.max(0, i - 2), i + 1).join("\n"))) {
+                risks.push({
+                    file: filepath,
+                    line: i + 1,
+                    risk: "Dict access without KeyError guard",
+                    severity: "medium",
+                    suggestion: "Use dict.get(key, default) or check with 'in'",
+                });
+            }
+        }
+    }
+    return risks;
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runNullSafetyAudit(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges null-safety-audit — Identify null/undefined dereference risks
+
+Usage:
+  judges null-safety-audit [dir]
+  judges null-safety-audit src/ --format json
+
+Options:
+  [dir]                 Directory to scan (default: .)
+  --format json         JSON output
+  --help, -h            Show this help
+
+Checks: non-null assertions, deep property chains, array bounds, undocumented null returns,
+JSON.parse without try/catch, destructuring null values, NaN checks.
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    const dir = argv.find((a) => !a.startsWith("-") && argv.indexOf(a) > 0) || ".";
+    const files = collectFiles(dir);
+    const allRisks = [];
+    for (const f of files)
+        allRisks.push(...analyzeFile(f));
+    const highCount = allRisks.filter((r) => r.severity === "high").length;
+    const medCount = allRisks.filter((r) => r.severity === "medium").length;
+    const score = Math.max(0, 100 - highCount * 8 - medCount * 3);
+    if (format === "json") {
+        console.log(JSON.stringify({
+            risks: allRisks,
+            score,
+            summary: { high: highCount, medium: medCount, total: allRisks.length },
+            timestamp: new Date().toISOString(),
+        }, null, 2));
+    }
+    else {
+        const badge = score >= 80 ? "✅ SAFE" : score >= 50 ? "⚠️  RISKS" : "❌ UNSAFE";
+        console.log(`\n  Null Safety: ${badge} (${score}/100)\n  ──────────────────────────`);
+        if (allRisks.length === 0) {
+            console.log("    No null safety risks detected.\n");
+            return;
+        }
+        for (const r of allRisks.slice(0, 25)) {
+            const icon = r.severity === "high" ? "🔴" : r.severity === "medium" ? "🟡" : "🔵";
+            console.log(`    ${icon} ${r.risk}`);
+            console.log(`        ${r.file}:${r.line}`);
+            console.log(`        → ${r.suggestion}`);
+        }
+        if (allRisks.length > 25)
+            console.log(`    ... and ${allRisks.length - 25} more`);
+        console.log(`\n    Total: ${allRisks.length} | High: ${highCount} | Medium: ${medCount} | Score: ${score}/100\n`);
+    }
+}

package/dist/commands/observability-gap.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Observability gap — detect missing metrics, traces, and structured logs
+ * at critical code paths.
+ */
+export declare function runObservabilityGap(argv: string[]): void;