@kevinrabun/judges-cli 3.124.0

package/dist/commands/deploy-readiness.js

@@ -0,0 +1,211 @@
+/**
+ * Deploy readiness — pre-deployment checklist that validates
+ * AI-generated code is production-ready.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from "fs";
+import { join, extname } from "path";
+// ─── File Collection ────────────────────────────────────────────────────────
+const CODE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".py", ".java", ".go", ".rs"]);
+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;
+}
+function allContent(files) {
+    return files
+        .map((f) => {
+        try {
+            return readFileSync(f, "utf-8");
+        }
+        catch {
+            return "";
+        }
+    })
+        .join("\n");
+}
+// ─── Checks ─────────────────────────────────────────────────────────────────
+function runChecks(dir) {
+    const checks = [];
+    const files = collectFiles(dir);
+    const content = allContent(files);
+    // Health check endpoint
+    const hasHealthCheck = /\/(health|healthz|readyz|livez|status)\b/.test(content);
+    checks.push({
+        name: "Health check endpoint",
+        status: hasHealthCheck ? "pass" : "fail",
+        detail: hasHealthCheck ? "Health check endpoint found" : "No /health or /healthz endpoint detected",
+        category: "availability",
+    });
+    // Graceful shutdown
+    const hasGraceful = /process\.on\s*\(\s*['"]SIG(TERM|INT)['"]|graceful.?shutdown|server\.close/i.test(content);
+    checks.push({
+        name: "Graceful shutdown handler",
+        status: hasGraceful ? "pass" : "warn",
+        detail: hasGraceful ? "SIGTERM/SIGINT handler found" : "No graceful shutdown handler — may lose in-flight requests",
+        category: "availability",
+    });
+    // Environment variable validation
+    const envRefs = (content.match(/process\.env\.\w+|os\.environ|System\.getenv/g) || []).length;
+    const envValidation = /process\.env\.\w+\s*\|\||required|assert.*env|validateEnv|env\.parse/i.test(content);
+    checks.push({
+        name: "Environment variable validation",
+        status: envRefs > 0 && envValidation ? "pass" : envRefs > 0 ? "warn" : "pass",
+        detail: envRefs > 0
+            ? envValidation
+                ? `${envRefs} env vars with validation`
+                : `${envRefs} env vars but no validation at startup`
+            : "No environment variables detected",
+        category: "configuration",
+    });
+    // Rate limiting
+    const hasRateLimit = /rate.?limit|throttle|express-rate-limit|fastify-rate-limit|@nestjs\/throttler/i.test(content);
+    checks.push({
+        name: "Rate limiting",
+        status: hasRateLimit ? "pass" : "warn",
+        detail: hasRateLimit ? "Rate limiting configured" : "No rate limiting detected — vulnerable to abuse",
+        category: "security",
+    });
+    // CORS configuration
+    const hasCors = /cors\(|Access-Control-Allow-Origin|@CrossOrigin/i.test(content);
+    const permissiveCors = /cors\(\s*\)|Allow-Origin.*\*/i.test(content);
+    checks.push({
+        name: "CORS configuration",
+        status: hasCors && !permissiveCors ? "pass" : permissiveCors ? "warn" : hasCors ? "pass" : "pass",
+        detail: permissiveCors
+            ? "CORS is permissive (allow-all) — restrict origins in production"
+            : hasCors
+                ? "CORS configured"
+                : "No CORS detected (may be OK for backend-only services)",
+        category: "security",
+    });
+    // Error handling
+    const hasGlobalErrorHandler = /app\.use\s*\(\s*\(err|@ExceptionHandler|exception_handler|error_handler/i.test(content);
+    checks.push({
+        name: "Global error handler",
+        status: hasGlobalErrorHandler ? "pass" : "warn",
+        detail: hasGlobalErrorHandler
+            ? "Global error handler found"
+            : "No global error handler — uncaught errors may leak stack traces",
+        category: "reliability",
+    });
+    // Logging
+    const hasStructuredLogging = /winston|pino|bunyan|log4j|logging\.getLogger|slog\.|zerolog/i.test(content);
+    const consoleLogCount = (content.match(/console\.(log|debug)\s*\(/g) || []).length;
+    checks.push({
+        name: "Structured logging",
+        status: hasStructuredLogging ? "pass" : consoleLogCount > 10 ? "warn" : "pass",
+        detail: hasStructuredLogging
+            ? "Structured logging framework detected"
+            : `${consoleLogCount} console.log calls — use a logging framework in production`,
+        category: "observability",
+    });
+    // Connection pool limits
+    const hasPool = /pool|createPool|connectionLimit|maxConnections|max_connections/i.test(content);
+    checks.push({
+        name: "Connection pool limits",
+        status: hasPool ? "pass" : "pass",
+        detail: hasPool ? "Connection pooling configured" : "No explicit connection pool detected (may be OK)",
+        category: "performance",
+    });
+    // Dockerfile / container
+    const hasDockerfile = existsSync(join(dir, "Dockerfile")) || existsSync(join(dir, "docker-compose.yml"));
+    const hasK8sProbes = /readinessProbe|livenessProbe|startupProbe/i.test(content);
+    if (hasDockerfile) {
+        checks.push({
+            name: "Container probes",
+            status: hasK8sProbes ? "pass" : "warn",
+            detail: hasK8sProbes ? "K8s readiness/liveness probes configured" : "Dockerfile found but no K8s probes detected",
+            category: "deployment",
+        });
+    }
+    // HTTPS
+    const hasInsecureHttp = /['"]http:\/\/(?!localhost|127\.0\.0\.1)/i.test(content);
+    checks.push({
+        name: "HTTPS enforcement",
+        status: hasInsecureHttp ? "warn" : "pass",
+        detail: hasInsecureHttp ? "Insecure HTTP URLs detected — use HTTPS" : "No insecure HTTP URLs found",
+        category: "security",
+    });
+    // Timeout configuration
+    const hasTimeouts = /timeout|connectTimeout|socketTimeout|requestTimeout/i.test(content);
+    checks.push({
+        name: "Request timeouts",
+        status: hasTimeouts ? "pass" : "warn",
+        detail: hasTimeouts ? "Timeout configuration found" : "No explicit timeouts — requests may hang indefinitely",
+        category: "reliability",
+    });
+    return checks;
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runDeployReadiness(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges deploy-readiness — Pre-deployment production readiness checklist
+
+Usage:
+  judges deploy-readiness [dir]
+  judges deploy-readiness src/ --format json
+
+Options:
+  [dir]                 Directory to scan (default: .)
+  --format json         JSON output
+  --help, -h            Show this help
+
+Checks: health endpoints, graceful shutdown, env validation, rate limiting,
+CORS, error handling, logging, connection pools, container probes, HTTPS, timeouts
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    const dir = argv.find((a) => !a.startsWith("-") && argv.indexOf(a) > 0) || ".";
+    const checks = runChecks(dir);
+    const passCount = checks.filter((c) => c.status === "pass").length;
+    const warnCount = checks.filter((c) => c.status === "warn").length;
+    const failCount = checks.filter((c) => c.status === "fail").length;
+    const score = Math.round((passCount / checks.length) * 100);
+    if (format === "json") {
+        console.log(JSON.stringify({
+            checks,
+            score,
+            summary: { pass: passCount, warn: warnCount, fail: failCount },
+            timestamp: new Date().toISOString(),
+        }, null, 2));
+    }
+    else {
+        const badge = failCount > 0 ? "❌ NOT READY" : warnCount > 2 ? "⚠️  REVIEW" : "✅ READY";
+        console.log(`\n  Deploy Readiness: ${badge} (${score}%)\n  ──────────────────────────`);
+        for (const check of checks) {
+            const icon = check.status === "pass" ? "✅" : check.status === "warn" ? "⚠️" : "❌";
+            console.log(`    ${icon} ${check.name}`);
+            console.log(`        ${check.detail}`);
+        }
+        console.log(`\n    Score: ${score}% | Pass: ${passCount} | Warn: ${warnCount} | Fail: ${failCount}\n`);
+    }
+}

package/dist/commands/deprecated.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Rule deprecation lifecycle management.
+ *
+ * Provides a registry of deprecated Judges rules with migration guidance,
+ * sunset dates, and replacement rules. Emits warnings when deprecated
+ * rules appear in findings or config.
+ *
+ * Usage:
+ *   judges deprecated                        # List all deprecated rules
+ *   judges deprecated --check .judgesrc      # Check config for deprecated rules
+ *   judges deprecated --format json          # JSON output
+ */
+export interface DeprecatedRule {
+    /** The deprecated rule ID */
+    ruleId: string;
+    /** When it was deprecated (version) */
+    deprecatedIn: string;
+    /** When it will be removed (version, or "TBD") */
+    removedIn: string;
+    /** Why it was deprecated */
+    reason: string;
+    /** Replacement rule(s), if any */
+    replacements: string[];
+    /** Migration guidance */
+    migration: string;
+}
+export interface DeprecationWarning {
+    ruleId: string;
+    location: "config" | "finding";
+    message: string;
+    replacements: string[];
+}
+export declare function getDeprecatedRules(): DeprecatedRule[];
+export declare function isRuleDeprecated(ruleId: string): DeprecatedRule | undefined;
+/**
+ * Check a config for references to deprecated rules.
+ * Scans disabledRules, ruleOverrides, and customRules.
+ */
+export declare function checkConfigForDeprecated(config: Record<string, unknown>): DeprecationWarning[];
+/**
+ * Check findings for deprecated rules and annotate them.
+ */
+export declare function annotateDeprecatedFindings(findings: Array<{
+    ruleId: string;
+    [key: string]: unknown;
+}>): DeprecationWarning[];
+export declare function runDeprecatedCommand(argv: string[]): void;

package/dist/commands/deprecated.js

@@ -0,0 +1,201 @@
+/**
+ * Rule deprecation lifecycle management.
+ *
+ * Provides a registry of deprecated Judges rules with migration guidance,
+ * sunset dates, and replacement rules. Emits warnings when deprecated
+ * rules appear in findings or config.
+ *
+ * Usage:
+ *   judges deprecated                        # List all deprecated rules
+ *   judges deprecated --check .judgesrc      # Check config for deprecated rules
+ *   judges deprecated --format json          # JSON output
+ */
+// ─── Deprecated Rules Registry ──────────────────────────────────────────────
+const DEPRECATED_RULES = [
+    {
+        ruleId: "SEC-EVAL-001",
+        deprecatedIn: "3.10.0",
+        removedIn: "4.0.0",
+        reason: "Merged into SEC-INJ-001 for unified injection detection",
+        replacements: ["SEC-INJ-001"],
+        migration: "Replace SEC-EVAL-001 references in ruleOverrides with SEC-INJ-001. The new rule covers eval(), Function(), and other injection vectors.",
+    },
+    {
+        ruleId: "PERF-LOOP-001",
+        deprecatedIn: "3.15.0",
+        removedIn: "4.0.0",
+        reason: "Superseded by the more comprehensive PERF-COMPLEXITY-001 which covers loops, recursion, and algorithmic complexity",
+        replacements: ["PERF-COMPLEXITY-001"],
+        migration: "Update ruleOverrides to use PERF-COMPLEXITY-001. The new rule has more granular severity options.",
+    },
+    {
+        ruleId: "DOC-INLINE-001",
+        deprecatedIn: "3.20.0",
+        removedIn: "4.0.0",
+        reason: "Split into DOC-FUNC-001 (function docs) and DOC-CLASS-001 (class docs) for more targeted analysis",
+        replacements: ["DOC-FUNC-001", "DOC-CLASS-001"],
+        migration: "Replace DOC-INLINE-001 in ruleOverrides with DOC-FUNC-001 and/or DOC-CLASS-001 depending on your needs.",
+    },
+    {
+        ruleId: "DATA-PII-001",
+        deprecatedIn: "3.25.0",
+        removedIn: "4.0.0",
+        reason: "Replaced by DATA-001 which includes PII detection alongside other sensitive data patterns",
+        replacements: ["DATA-001"],
+        migration: "Update references from DATA-PII-001 to DATA-001. The new rule has broader coverage.",
+    },
+    {
+        ruleId: "SEC-CRYPTO-WEAK",
+        deprecatedIn: "3.30.0",
+        removedIn: "4.0.0",
+        reason: "Renamed to SEC-CRYPTO-001 for consistent naming convention",
+        replacements: ["SEC-CRYPTO-001"],
+        migration: "Simply rename SEC-CRYPTO-WEAK to SEC-CRYPTO-001 in all config references.",
+    },
+];
+// ─── Registry API ───────────────────────────────────────────────────────────
+export function getDeprecatedRules() {
+    return [...DEPRECATED_RULES];
+}
+export function isRuleDeprecated(ruleId) {
+    return DEPRECATED_RULES.find((r) => r.ruleId === ruleId);
+}
+/**
+ * Check a config for references to deprecated rules.
+ * Scans disabledRules, ruleOverrides, and customRules.
+ */
+export function checkConfigForDeprecated(config) {
+    const warnings = [];
+    // Check disabledRules
+    const disabled = (config.disabledRules || []);
+    for (const ruleId of disabled) {
+        const dep = isRuleDeprecated(ruleId);
+        if (dep) {
+            warnings.push({
+                ruleId,
+                location: "config",
+                message: `disabledRules contains deprecated rule "${ruleId}" (deprecated in v${dep.deprecatedIn}). ${dep.migration}`,
+                replacements: dep.replacements,
+            });
+        }
+    }
+    // Check ruleOverrides keys
+    const overrides = (config.ruleOverrides || {});
+    for (const ruleId of Object.keys(overrides)) {
+        const dep = isRuleDeprecated(ruleId);
+        if (dep) {
+            warnings.push({
+                ruleId,
+                location: "config",
+                message: `ruleOverrides references deprecated rule "${ruleId}" (deprecated in v${dep.deprecatedIn}). ${dep.migration}`,
+                replacements: dep.replacements,
+            });
+        }
+    }
+    // Check lockedRules
+    const locked = (config.lockedRules || []);
+    for (const ruleId of locked) {
+        const dep = isRuleDeprecated(ruleId);
+        if (dep) {
+            warnings.push({
+                ruleId,
+                location: "config",
+                message: `lockedRules contains deprecated rule "${ruleId}" (deprecated in v${dep.deprecatedIn}). ${dep.migration}`,
+                replacements: dep.replacements,
+            });
+        }
+    }
+    return warnings;
+}
+/**
+ * Check findings for deprecated rules and annotate them.
+ */
+export function annotateDeprecatedFindings(findings) {
+    const warnings = [];
+    const seen = new Set();
+    for (const finding of findings) {
+        if (seen.has(finding.ruleId))
+            continue;
+        const dep = isRuleDeprecated(finding.ruleId);
+        if (dep) {
+            seen.add(finding.ruleId);
+            warnings.push({
+                ruleId: finding.ruleId,
+                location: "finding",
+                message: `Rule "${finding.ruleId}" is deprecated since v${dep.deprecatedIn}. ${dep.reason}`,
+                replacements: dep.replacements,
+            });
+        }
+    }
+    return warnings;
+}
+// ─── CLI Runner ─────────────────────────────────────────────────────────────
+export function runDeprecatedCommand(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges deprecated — Rule deprecation lifecycle
+
+Usage:
+  judges deprecated                        List all deprecated rules
+  judges deprecated --check .judgesrc      Check config for deprecated references
+  judges deprecated --format json          JSON output
+
+Shows deprecated rules with migration guidance, replacement rules, and removal timeline.
+
+Options:
+  --check <path>     Check a .judgesrc for deprecated rule references
+  --format <fmt>     Output format: text, json
+  --help, -h         Show this help
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    const checkPath = argv.find((_a, i) => argv[i - 1] === "--check");
+    // Check config mode
+    if (checkPath) {
+        try {
+            const { readFileSync, existsSync } = require("fs");
+            if (!existsSync(checkPath)) {
+                console.log(`\n  File not found: ${checkPath}\n`);
+                return;
+            }
+            const config = JSON.parse(readFileSync(checkPath, "utf-8"));
+            const warnings = checkConfigForDeprecated(config);
+            if (format === "json") {
+                console.log(JSON.stringify({ warnings }, null, 2));
+                return;
+            }
+            console.log(`\n  Checking ${checkPath} for deprecated rules...\n`);
+            if (warnings.length === 0) {
+                console.log("  ✅ No deprecated rule references found.\n");
+            }
+            else {
+                for (const w of warnings) {
+                    console.log(`  ⚠️  ${w.message}`);
+                    if (w.replacements.length > 0) {
+                        console.log(`      → Replace with: ${w.replacements.join(", ")}`);
+                    }
+                    console.log("");
+                }
+            }
+            return;
+        }
+        catch (err) {
+            console.error(`\n  Error checking config: ${err instanceof Error ? err.message : String(err)}\n`);
+            return;
+        }
+    }
+    // List all deprecated rules
+    const rules = getDeprecatedRules();
+    if (format === "json") {
+        console.log(JSON.stringify({ deprecatedRules: rules }, null, 2));
+        return;
+    }
+    console.log("\n  Deprecated Rules\n");
+    console.log(`  ${"RULE ID".padEnd(20)}  ${"DEPRECATED IN".padEnd(15)}  ${"REMOVED IN".padEnd(12)}  REPLACEMENT(S)`);
+    console.log(`  ${"─".repeat(20)}  ${"─".repeat(15)}  ${"─".repeat(12)}  ${"─".repeat(25)}`);
+    for (const rule of rules) {
+        console.log(`  ${rule.ruleId.padEnd(20)}  v${rule.deprecatedIn.padEnd(14)}  v${rule.removedIn.padEnd(11)}  ${rule.replacements.join(", ") || "—"}`);
+    }
+    console.log(`\n  ${rules.length} deprecated rule(s). Run with --check <config> to scan your .judgesrc.\n`);
+}

package/dist/commands/deps.d.ts

@@ -0,0 +1,5 @@
+export declare function parseDepsArgs(argv: string[]): {
+    path: string;
+    format: string;
+};
+export declare function runDeps(argv: string[]): void;

package/dist/commands/deps.js

@@ -0,0 +1,122 @@
+// ─── Deps Command ────────────────────────────────────────────────────────────
+// Analyze project dependencies for supply-chain risks and vulnerabilities.
+//
+// Usage:
+//   judges deps .                              # analyze current directory
+//   judges deps --file package.json            # analyze specific manifest
+//   judges deps /path/to/project --format json # JSON output
+// ──────────────────────────────────────────────────────────────────────────────
+import { readFileSync, existsSync, readdirSync } from "fs";
+import { resolve, join, basename } from "path";
+import { analyzeDependencies } from "../evaluators/index.js";
+const MANIFEST_FILES = new Set([
+    "package.json",
+    "requirements.txt",
+    "Pipfile",
+    "pyproject.toml",
+    "Gemfile",
+    "go.mod",
+    "Cargo.toml",
+    "pom.xml",
+    "build.gradle",
+    "composer.json",
+    "pubspec.yaml",
+]);
+// ─── CLI Entry Point ────────────────────────────────────────────────────────
+export function parseDepsArgs(argv) {
+    let path = ".";
+    let format = "text";
+    for (let i = 3; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--file":
+            case "-f":
+                path = argv[++i];
+                break;
+            case "--format":
+            case "-o":
+                format = argv[++i];
+                break;
+            default:
+                if (!arg.startsWith("-"))
+                    path = arg;
+                break;
+        }
+    }
+    return { path, format };
+}
+function discoverManifests(dirPath) {
+    const abs = resolve(dirPath);
+    if (!existsSync(abs))
+        return [];
+    // If it's a file, return it directly
+    try {
+        const entries = readdirSync(abs, { withFileTypes: true });
+        const manifests = [];
+        for (const entry of entries) {
+            if (entry.isFile() && MANIFEST_FILES.has(entry.name)) {
+                manifests.push(join(abs, entry.name));
+            }
+        }
+        return manifests;
+    }
+    catch {
+        // Not a directory — treat as a single file
+        if (existsSync(abs))
+            return [abs];
+        return [];
+    }
+}
+export function runDeps(argv) {
+    const args = parseDepsArgs(argv);
+    const manifests = discoverManifests(args.path);
+    if (manifests.length === 0) {
+        console.error(`No dependency manifest files found in: ${resolve(args.path)}`);
+        console.error(`Supported: ${[...MANIFEST_FILES].join(", ")}`);
+        process.exit(1);
+    }
+    const allVerdicts = [];
+    let totalFindings = 0;
+    let worstScore = 100;
+    for (const manifest of manifests) {
+        const content = readFileSync(manifest, "utf-8");
+        const verdict = analyzeDependencies(content, basename(manifest));
+        totalFindings += verdict.findings.length;
+        if (verdict.score < worstScore)
+            worstScore = verdict.score;
+        allVerdicts.push({ file: manifest, verdict });
+    }
+    if (args.format === "json") {
+        console.log(JSON.stringify({
+            manifests: allVerdicts.map((v) => ({
+                file: v.file,
+                totalDependencies: v.verdict.totalDependencies,
+                findings: v.verdict.findings,
+                score: v.verdict.score,
+                verdict: v.verdict.verdict,
+                summary: v.verdict.summary,
+            })),
+            totalFindings,
+            worstScore,
+        }, null, 2));
+    }
+    else {
+        console.log("");
+        console.log("╔══════════════════════════════════════════════════════════════╗");
+        console.log("║          Judges Panel — Dependency Analysis                  ║");
+        console.log("╚══════════════════════════════════════════════════════════════╝");
+        console.log("");
+        for (const { file, verdict } of allVerdicts) {
+            const icon = verdict.verdict === "pass" ? "✅" : verdict.verdict === "warning" ? "⚠️ " : "❌";
+            console.log(`  ${icon} ${file}`);
+            console.log(`     ${verdict.totalDependencies} dependencies, score ${verdict.score}/100`);
+            for (const f of verdict.findings) {
+                console.log(`     [${f.severity.toUpperCase().padEnd(8)}] ${f.ruleId}: ${f.title}`);
+            }
+            console.log("");
+        }
+        console.log(`  Total: ${totalFindings} finding(s) across ${allVerdicts.length} manifest(s), worst score: ${worstScore}/100`);
+        console.log("");
+    }
+    process.exit(totalFindings > 0 && worstScore < 50 ? 1 : 0);
+}

package/dist/commands/design-audit.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Design audit — detect AI-generated code that breaks project
+ * conventions, introduces unnecessary abstractions, or creates
+ * architectural deviation from the baseline.
+ *
+ * All analysis local.
+ */
+export declare function runDesignAudit(argv: string[]): void;