@kevinrabun/judges-cli 3.124.0

package/dist/commands/security-theater.js

@@ -0,0 +1,278 @@
+/**
+ * Security-theater — detect security-looking code that provides no actual protection.
+ */
+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", ".cs"]);
+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 issues = [];
+    let content;
+    try {
+        content = readFileSync(filepath, "utf-8");
+    }
+    catch {
+        return issues;
+    }
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*"))
+            continue;
+        // Weak password hashing
+        if (/(?:createHash|hashlib\.)\s*\(\s*['"](?:md5|sha1)['"]\s*\)/.test(line) &&
+            /password|passwd|pwd/i.test(lines.slice(Math.max(0, i - 3), i + 3).join(" "))) {
+            issues.push({
+                file: filepath,
+                line: i + 1,
+                issue: "Weak password hashing (MD5/SHA1)",
+                severity: "high",
+                detail: "MD5/SHA1 are not appropriate for password hashing — use bcrypt, scrypt, or argon2",
+            });
+        }
+        // Hardcoded encryption keys/IVs
+        if (/(?:key|iv|secret|password)\s*[:=]\s*['"][A-Za-z0-9+/=]{8,}['"]/.test(line) &&
+            /(?:cipher|encrypt|decrypt|crypto|aes|des)/i.test(lines.slice(Math.max(0, i - 5), i + 5).join(" "))) {
+            issues.push({
+                file: filepath,
+                line: i + 1,
+                issue: "Hardcoded encryption key or IV",
+                severity: "high",
+                detail: "Encryption keys/IVs must not be hardcoded — use environment variables or key management services",
+            });
+        }
+        // Wildcard CORS with auth
+        if (/['"]Access-Control-Allow-Origin['"]\s*[:,]\s*['"]\s*[*]\s*['"]/.test(line)) {
+            const nearby = lines.slice(i, Math.min(i + 10, lines.length)).join(" ");
+            if (/(?:authorization|cookie|credentials|auth)/i.test(nearby)) {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "CORS wildcard (*) with authentication",
+                    severity: "high",
+                    detail: "Access-Control-Allow-Origin: * combined with authentication bypasses same-origin policy protections",
+                });
+            }
+            else {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "CORS wildcard (*)",
+                    severity: "medium",
+                    detail: "CORS wildcard allows any origin — restrict to trusted domains unless truly public",
+                });
+            }
+        }
+        // CSRF token generated but never verified
+        if (/csrf[_-]?token|csrfToken|_csrf/i.test(line) && /generate|create|set|assign/i.test(line)) {
+            const fileContent = content;
+            if (!/csrf.*verif|verify.*csrf|csrf.*valid|csrfProtection|csurf/i.test(fileContent)) {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "CSRF token generated but never verified",
+                    severity: "high",
+                    detail: "CSRF tokens must be verified on the server side — generation alone provides no protection",
+                });
+            }
+        }
+        // Rate limiting that is too lenient
+        if (/rateLimit|rate[_-]?limit/i.test(line)) {
+            const context = lines.slice(i, Math.min(i + 5, lines.length)).join(" ");
+            const limitMatch = context.match(/(?:max|limit|windowMs|window)\s*[:=]\s*(\d+)/);
+            if (limitMatch) {
+                const val = parseInt(limitMatch[1], 10);
+                if (/max|limit/i.test(limitMatch[0]) && val >= 10000) {
+                    issues.push({
+                        file: filepath,
+                        line: i + 1,
+                        issue: "Ineffective rate limiting (limit too high)",
+                        severity: "medium",
+                        detail: `Rate limit of ${val} requests is too permissive to be protective`,
+                    });
+                }
+            }
+        }
+        // Validation without authorization
+        if (/(?:validate|sanitize|check)\s*\(\s*(?:req|request)/.test(line) || /(?:joi|yup|zod)\s*\./.test(line)) {
+            if (/(?:body|params|query)/.test(line)) {
+                const nearby = lines.slice(Math.max(0, i - 10), Math.min(i + 10, lines.length)).join(" ");
+                if (!/(?:auth|authorize|isAuthenticated|requireAuth|passport|jwt|token|session)/.test(nearby)) {
+                    issues.push({
+                        file: filepath,
+                        line: i + 1,
+                        issue: "Input validation without authorization check",
+                        severity: "medium",
+                        detail: "Validating input without checking authorization — an unauthenticated user could send valid-looking data",
+                    });
+                }
+            }
+        }
+        // Client-side only validation
+        if (/(?:disabled|readonly|hidden)\s*[=:]\s*(?:true|['"]true['"])/.test(line) &&
+            /(?:submit|form|action)/i.test(lines.slice(Math.max(0, i - 5), i + 5).join(" "))) {
+            issues.push({
+                file: filepath,
+                line: i + 1,
+                issue: "Client-side-only form restriction",
+                severity: "medium",
+                detail: "disabled/readonly/hidden form attributes can be bypassed — enforce restrictions server-side",
+            });
+        }
+        // Base64 used as encryption
+        if (/(?:btoa|atob|Buffer\.from\([^)]*,\s*['"]base64['"]|base64[_-]?encode|base64[_-]?decode)/i.test(line)) {
+            const nearby = lines.slice(Math.max(0, i - 3), i + 3).join(" ");
+            if (/(?:encrypt|secret|password|secure|protect|hide)/i.test(nearby)) {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "Base64 used as encryption",
+                    severity: "high",
+                    detail: "Base64 is encoding, not encryption — it provides zero confidentiality",
+                });
+            }
+        }
+        // SQL partial parameterization
+        if (/(?:query|execute|exec|raw)\s*\(/.test(line)) {
+            const context = lines.slice(i, Math.min(i + 3, lines.length)).join(" ");
+            if (/\$\{|\+\s*['"]/.test(context) && /[?$]/.test(context)) {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "Partially parameterized SQL query",
+                    severity: "high",
+                    detail: "Query mixes parameterized values with string concatenation — fully parameterize all inputs",
+                });
+            }
+        }
+        // Commented-out security controls
+        if (/^\s*\/\/\s*(?:app\.use\s*\(\s*(?:helmet|csrf|cors|rateLimit)|requireAuth|isAuthenticated|authorize)/.test(line)) {
+            issues.push({
+                file: filepath,
+                line: i + 1,
+                issue: "Commented-out security middleware",
+                severity: "high",
+                detail: "Security middleware is commented out — likely left disabled from debugging",
+            });
+        }
+        // JWT with 'none' algorithm
+        if (/algorithm[s]?\s*[:=]\s*\[?\s*['"]none['"]/i.test(line)) {
+            issues.push({
+                file: filepath,
+                line: i + 1,
+                issue: "JWT 'none' algorithm allowed",
+                severity: "high",
+                detail: "Allowing 'none' algorithm in JWT verification completely disables signature checking",
+            });
+        }
+        // Overly long JWT expiration
+        if (/expiresIn\s*[:=]\s*['"](\d+)([dh])['"]/.test(line)) {
+            const match = line.match(/expiresIn\s*[:=]\s*['"](\d+)([dh])['"]/);
+            if (match) {
+                const val = parseInt(match[1], 10);
+                const unit = match[2];
+                if ((unit === "d" && val > 30) || (unit === "h" && val > 720)) {
+                    issues.push({
+                        file: filepath,
+                        line: i + 1,
+                        issue: "JWT expiration too long",
+                        severity: "medium",
+                        detail: `Token expiration of ${val}${unit} is excessively long — shorter-lived tokens reduce blast radius of theft`,
+                    });
+                }
+            }
+        }
+    }
+    return issues;
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runSecurityTheater(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges security-theater — Detect security-looking code that provides no protection
+
+Usage:
+  judges security-theater [dir]
+  judges security-theater src/ --format json
+
+Options:
+  [dir]                 Directory to scan (default: .)
+  --format json         JSON output
+  --help, -h            Show this help
+
+Checks: weak password hashing, hardcoded keys/IVs, wildcard CORS with auth,
+unverified CSRF tokens, ineffective rate limiting, validation without auth,
+base64-as-encryption, partial SQL parameterization, commented-out security
+middleware, JWT 'none' algorithm, overly long JWT expiration.
+`);
+        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 allIssues = [];
+    for (const f of files)
+        allIssues.push(...analyzeFile(f));
+    const highCount = allIssues.filter((i) => i.severity === "high").length;
+    const medCount = allIssues.filter((i) => i.severity === "medium").length;
+    const score = Math.max(0, 100 - highCount * 15 - medCount * 7 - allIssues.filter((i) => i.severity === "low").length * 3);
+    if (format === "json") {
+        console.log(JSON.stringify({
+            issues: allIssues,
+            score,
+            summary: { high: highCount, medium: medCount, total: allIssues.length },
+            timestamp: new Date().toISOString(),
+        }, null, 2));
+    }
+    else {
+        const badge = score >= 80 ? "✅ GENUINE SECURITY" : score >= 50 ? "⚠️  THEATER DETECTED" : "❌ SECURITY THEATER";
+        console.log(`\n  Security-Theater: ${badge} (${score}/100)\n  ─────────────────────────────`);
+        if (allIssues.length === 0) {
+            console.log("    No security theater detected.\n");
+            return;
+        }
+        for (const issue of allIssues.slice(0, 25)) {
+            const icon = issue.severity === "high" ? "🔴" : issue.severity === "medium" ? "🟡" : "🔵";
+            console.log(`    ${icon} ${issue.issue}`);
+            console.log(`        ${issue.file}:${issue.line}`);
+            console.log(`        ${issue.detail}`);
+        }
+        if (allIssues.length > 25)
+            console.log(`    ... and ${allIssues.length - 25} more`);
+        console.log(`\n    Total: ${allIssues.length} | High: ${highCount} | Medium: ${medCount} | Score: ${score}/100\n`);
+    }
+}

package/dist/commands/setup-wizard.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Setup-wizard — Interactive guided setup for new users and teams.
+ */
+export declare function runSetupWizard(argv: string[]): void;

package/dist/commands/setup-wizard.js

@@ -0,0 +1,174 @@
+/**
+ * Setup-wizard — Interactive guided setup for new users and teams.
+ */
+import { writeFileSync, existsSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+// ─── Presets ────────────────────────────────────────────────────────────────
+const SETUP_PRESETS = {
+    "quick-start": {
+        description: "Minimal setup — evaluate files with sensible defaults",
+        config: { preset: "lenient", format: "text" },
+    },
+    "security-first": {
+        description: "Focus on security findings — strict severity thresholds",
+        config: { preset: "security-only", minSeverity: "medium", failOnFindings: true },
+    },
+    "ci-integration": {
+        description: "Optimized for CI/CD pipelines — JSON output, quality gates",
+        config: { preset: "strict", format: "sarif", failOnFindings: true, minScore: 70 },
+    },
+    "team-review": {
+        description: "Team-oriented — shared config, audit logging, PR summaries",
+        config: { preset: "strict", format: "markdown" },
+    },
+    compliance: {
+        description: "Compliance-focused — full audit trail, evidence collection",
+        config: { preset: "compliance", format: "sarif" },
+    },
+};
+// ─── CI Templates ───────────────────────────────────────────────────────────
+function generateGitHubActions(profile) {
+    return `name: Judges Code Review
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npx @kevinrabun/judges-cli eval . --preset ${profile.preset} --format sarif --fail-on-findings
+`;
+}
+function generateGitLabCI(profile) {
+    return `judges-review:
+  image: node:20
+  script:
+    - npx @kevinrabun/judges-cli eval . --preset ${profile.preset} --format sarif --fail-on-findings
+  only:
+    - merge_requests
+    - main
+`;
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runSetupWizard(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges setup-wizard — Guided setup for new users
+
+Usage:
+  judges setup-wizard                            Interactive setup
+  judges setup-wizard --profile quick-start      Use preset profile
+  judges setup-wizard --list-profiles            List available profiles
+  judges setup-wizard --generate-ci github-actions  Generate CI config
+  judges setup-wizard --init                     Create .judgesrc and CI config
+
+Profiles:
+  quick-start       Minimal setup with sensible defaults
+  security-first    Security-focused with strict thresholds
+  ci-integration    Optimized for CI/CD pipelines
+  team-review       Team-oriented with shared config
+  compliance        Full compliance with audit trails
+
+Options:
+  --profile <name>       Select a setup profile
+  --list-profiles        List all available profiles
+  --generate-ci <type>   Generate CI config (github-actions, gitlab-ci)
+  --init                 Write configuration files
+  --output <dir>         Output directory (default: current)
+  --format json          JSON output
+  --help, -h             Show this help
+
+Generates .judgesrc configuration and CI workflow files
+based on your team's needs. All data stays local.
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    if (argv.includes("--list-profiles")) {
+        if (format === "json") {
+            console.log(JSON.stringify(SETUP_PRESETS, null, 2));
+            return;
+        }
+        console.log("\n  Setup Profiles\n  ═════════════════════════════");
+        for (const [name, info] of Object.entries(SETUP_PRESETS)) {
+            console.log(`    ${name.padEnd(20)} ${info.description}`);
+        }
+        console.log();
+        return;
+    }
+    const profileName = argv.find((_a, i) => argv[i - 1] === "--profile") || "quick-start";
+    const ciType = argv.find((_a, i) => argv[i - 1] === "--generate-ci");
+    const outputDir = argv.find((_a, i) => argv[i - 1] === "--output") || ".";
+    const doInit = argv.includes("--init");
+    const preset = SETUP_PRESETS[profileName];
+    if (!preset) {
+        console.error(`Error: Unknown profile '${profileName}'. Use --list-profiles to see options.`);
+        process.exitCode = 1;
+        return;
+    }
+    const profile = {
+        preset: profileName,
+        ciSystem: ciType || "github-actions",
+        languages: [],
+        strictness: profileName === "security-first" || profileName === "compliance" ? "strict" : "moderate",
+        features: [],
+    };
+    if (ciType) {
+        const ciConfig = ciType === "gitlab-ci" ? generateGitLabCI(profile) : generateGitHubActions(profile);
+        console.log(ciConfig);
+        return;
+    }
+    if (doInit) {
+        // Write .judgesrc
+        const rcPath = join(outputDir, ".judgesrc");
+        if (!existsSync(rcPath)) {
+            writeFileSync(rcPath, JSON.stringify(preset.config, null, 2), "utf-8");
+            console.log(`Created ${rcPath}`);
+        }
+        else {
+            console.log(`${rcPath} already exists, skipping.`);
+        }
+        // Write CI config
+        const ciDir = join(outputDir, ".github", "workflows");
+        const ciPath = join(ciDir, "judges-review.yml");
+        if (!existsSync(ciPath)) {
+            mkdirSync(dirname(ciPath), { recursive: true });
+            writeFileSync(ciPath, generateGitHubActions(profile), "utf-8");
+            console.log(`Created ${ciPath}`);
+        }
+        else {
+            console.log(`${ciPath} already exists, skipping.`);
+        }
+        console.log("\nSetup complete! Next steps:");
+        console.log("  1. Run: npx @kevinrabun/judges-cli eval <file>");
+        console.log("  2. Customize .judgesrc for your needs");
+        console.log("  3. Commit the CI workflow for automated reviews");
+        return;
+    }
+    // Show setup summary
+    if (format === "json") {
+        console.log(JSON.stringify({ profile: profileName, ...preset }, null, 2));
+        return;
+    }
+    console.log(`\n  Setup Wizard — ${profileName}\n  ═════════════════════════════`);
+    console.log(`    Profile: ${profileName}`);
+    console.log(`    Description: ${preset.description}`);
+    console.log(`    Configuration:`);
+    for (const [key, value] of Object.entries(preset.config)) {
+        console.log(`      ${key}: ${value}`);
+    }
+    console.log();
+    console.log("  To apply this configuration:");
+    console.log(`    judges setup-wizard --profile ${profileName} --init`);
+    console.log();
+    console.log("  To generate CI config:");
+    console.log(`    judges setup-wizard --profile ${profileName} --generate-ci github-actions`);
+    console.log();
+}

package/dist/commands/severity-tune.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Severity-tune — Auto-calibrate severity levels based on project patterns.
+ */
+export declare function runSeverityTune(argv: string[]): void;

package/dist/commands/severity-tune.js

@@ -0,0 +1,208 @@
+/**
+ * Severity-tune — Auto-calibrate severity levels based on project patterns.
+ */
+import { readFileSync, readdirSync, statSync } from "fs";
+import { join, extname } from "path";
+// ─── Patterns with default severity ────────────────────────────────────────
+const TUNE_PATTERNS = [
+    {
+        name: "hardcoded-secret",
+        severity: "critical",
+        regex: /(?:password|secret|api_key|token)\s*[:=]\s*["'][^"']{8,}/i,
+    },
+    { name: "eval-usage", severity: "critical", regex: /\beval\s*\(/ },
+    { name: "sql-concat", severity: "critical", regex: /(?:query|execute)\s*\(\s*["'`].*\+/ },
+    { name: "xss-risk", severity: "high", regex: /innerHTML\s*=|document\.write\s*\(/ },
+    { name: "command-injection", severity: "critical", regex: /exec(?:Sync)?\s*\(\s*`[^`]*\$\{/ },
+    { name: "empty-catch", severity: "medium", regex: /catch\s*\([^)]*\)\s*\{\s*\}/ },
+    { name: "any-type", severity: "medium", regex: /:\s*any\b/ },
+    { name: "unsafe-regex", severity: "high", regex: /new\s+RegExp\s*\([^)]*\+/ },
+    { name: "deprecated-api", severity: "medium", regex: /new\s+Buffer\s*\(|\.substr\s*\(/ },
+    { name: "console-log", severity: "low", regex: /console\.log\s*\(/ },
+    { name: "todo-fixme", severity: "low", regex: /\/\/\s*(?:TODO|FIXME|HACK)\b/i },
+    { name: "magic-number", severity: "low", regex: /(?:if|return|===?)\s*(?<!\w)\d{3,}(?!\w)/ },
+    { name: "long-line", severity: "low", regex: /^.{200,}$/ },
+    { name: "nested-ternary", severity: "medium", regex: /[?][^:]*[?]/ },
+    { name: "god-function", severity: "medium", regex: /^(?:export\s+)?(?:async\s+)?function\s+\w+/ },
+];
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function collectSourceFiles(dir) {
+    const exts = new Set([".ts", ".js", ".tsx", ".jsx", ".py", ".java", ".go", ".rs", ".cs"]);
+    const files = [];
+    const skipDirs = new Set(["node_modules", ".git", "dist", "build", "coverage"]);
+    function walk(d) {
+        let entries;
+        try {
+            entries = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (skipDirs.has(name))
+                continue;
+            const full = join(d, name);
+            try {
+                const st = statSync(full);
+                if (st.isDirectory())
+                    walk(full);
+                else if (exts.has(extname(name)))
+                    files.push(full);
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    walk(dir);
+    return files;
+}
+function analyzeSeverity(files) {
+    const patternData = new Map();
+    for (const pat of TUNE_PATTERNS) {
+        patternData.set(pat.name, { occurrences: 0, files: new Set(), severity: pat.severity });
+    }
+    for (const filePath of files) {
+        let content;
+        try {
+            content = readFileSync(filePath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const lines = content.split("\n");
+        for (const pat of TUNE_PATTERNS) {
+            // Special handling for god-function: count functions > 80 lines
+            if (pat.name === "god-function") {
+                let funcCount = 0;
+                let inFunc = false;
+                let braceDepth = 0;
+                let funcLines = 0;
+                for (const line of lines) {
+                    if (pat.regex.test(line) && !inFunc) {
+                        inFunc = true;
+                        braceDepth = 0;
+                        funcLines = 0;
+                    }
+                    if (inFunc) {
+                        funcLines++;
+                        braceDepth += (line.match(/\{/g) || []).length;
+                        braceDepth -= (line.match(/\}/g) || []).length;
+                        if (braceDepth <= 0 && funcLines > 1) {
+                            if (funcLines > 80)
+                                funcCount++;
+                            inFunc = false;
+                        }
+                    }
+                }
+                if (funcCount > 0) {
+                    const data = patternData.get(pat.name);
+                    data.occurrences += funcCount;
+                    data.files.add(filePath);
+                }
+                continue;
+            }
+            let hitCount = 0;
+            for (const line of lines) {
+                if (pat.regex.test(line))
+                    hitCount++;
+            }
+            if (hitCount > 0) {
+                const data = patternData.get(pat.name);
+                data.occurrences += hitCount;
+                data.files.add(filePath);
+            }
+        }
+    }
+    // Generate tuning recommendations
+    const recommendations = [];
+    const fileCount = files.length;
+    for (const [name, data] of patternData) {
+        if (data.occurrences === 0)
+            continue;
+        const filePercent = fileCount > 0 ? (data.files.size / fileCount) * 100 : 0;
+        let suggestedSeverity = data.severity;
+        let reason = "Current severity is appropriate";
+        // If a pattern appears in >50% of files, it may be a team convention — consider lowering severity
+        if (filePercent > 50 && data.severity !== "low") {
+            suggestedSeverity = data.severity === "critical" ? "high" : data.severity === "high" ? "medium" : "low";
+            reason = `Appears in ${Math.round(filePercent)}% of files — may be a project norm. Consider lowering severity.`;
+        }
+        // If a critical/high pattern appears very rarely, keep it — it's genuinely concerning
+        else if (data.occurrences <= 2 && (data.severity === "critical" || data.severity === "high")) {
+            reason = "Rare occurrence — keep current severity to catch regressions";
+        }
+        // If low-severity pattern is pervasive, suggest ignoring
+        else if (data.severity === "low" && data.occurrences > 100) {
+            suggestedSeverity = "info";
+            reason = `${data.occurrences} occurrences — consider ignoring to reduce noise`;
+        }
+        if (suggestedSeverity !== data.severity) {
+            recommendations.push({
+                pattern: name,
+                currentSeverity: data.severity,
+                occurrences: data.occurrences,
+                filesAffected: data.files.size,
+                suggestedSeverity,
+                reason,
+            });
+        }
+    }
+    recommendations.sort((a, b) => b.occurrences - a.occurrences);
+    const summary = recommendations.length === 0
+        ? "All severity levels appear well-calibrated for this project."
+        : `${recommendations.length} severity adjustments recommended to reduce noise and improve signal.`;
+    return {
+        filesScanned: files.length,
+        patternsAnalyzed: TUNE_PATTERNS.length,
+        tuningRecommendations: recommendations,
+        summary,
+    };
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runSeverityTune(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges severity-tune — Auto-calibrate severity levels for your project
+
+Usage:
+  judges severity-tune [dir]                  Analyze and recommend adjustments
+  judges severity-tune --format json          JSON output
+
+Options:
+  [dir]                   Target directory (default: .)
+  --format json           JSON output
+  --help, -h              Show this help
+
+Analyzes your codebase to determine if default severity levels match your
+project's patterns. Recommends adjustments to reduce alert fatigue for
+pervasive patterns while maintaining sensitivity for genuine issues.
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    const dir = argv.find((a) => !a.startsWith("-") && a !== "severity-tune" && argv[argv.indexOf(a) - 1] !== "--format") || ".";
+    const files = collectSourceFiles(dir);
+    if (files.length === 0) {
+        console.log("No source files found.");
+        return;
+    }
+    const result = analyzeSeverity(files);
+    if (format === "json") {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`\n  Severity Tune\n  ─────────────────────────────`);
+    console.log(`    Files scanned: ${result.filesScanned}`);
+    console.log(`    Patterns analyzed: ${result.patternsAnalyzed}`);
+    console.log(`\n    💡 ${result.summary}`);
+    if (result.tuningRecommendations.length > 0) {
+        console.log("\n    Recommendations:");
+        for (const rec of result.tuningRecommendations) {
+            console.log(`\n      ${rec.pattern}: ${rec.currentSeverity} → ${rec.suggestedSeverity}`);
+            console.log(`        ${rec.occurrences} occurrences in ${rec.filesAffected} files`);
+            console.log(`        ${rec.reason}`);
+        }
+    }
+    console.log();
+}