@kevinrabun/judges-cli 3.124.0

package/dist/commands/org-policy.js

@@ -0,0 +1,207 @@
+/**
+ * Org policy — defines, validates, and enforces organization-wide
+ * policy manifests that cascade into per-repo .judgesrc files.
+ *
+ * All data stored locally.
+ */
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+// ─── Default Policy ─────────────────────────────────────────────────────────
+const DEFAULT_POLICY = {
+    name: "default",
+    version: "1.0.0",
+    minSeverity: "medium",
+    requiredJudges: [],
+    bannedRules: [],
+    maxSuppressionsPerRepo: 50,
+    requiredPreset: "",
+    enforcedOptions: {},
+    lastUpdated: new Date().toISOString(),
+};
+// ─── Compliance Check ───────────────────────────────────────────────────────
+function checkCompliance(policy) {
+    const violations = [];
+    const warnings = [];
+    // Check .judgesrc exists
+    if (!existsSync(".judgesrc")) {
+        violations.push("Missing .judgesrc configuration file");
+    }
+    else {
+        try {
+            const config = JSON.parse(readFileSync(".judgesrc", "utf-8"));
+            // Check min severity
+            if (policy.minSeverity) {
+                const sevOrder = ["critical", "high", "medium", "low", "info"];
+                const policyIdx = sevOrder.indexOf(policy.minSeverity);
+                const configIdx = sevOrder.indexOf(config.minSeverity || "low");
+                if (configIdx > policyIdx) {
+                    violations.push(`minSeverity '${config.minSeverity || "low"}' is less strict than policy requirement '${policy.minSeverity}'`);
+                }
+            }
+            // Check required judges
+            const disabledJudges = config.disabledJudges || [];
+            for (const required of policy.requiredJudges) {
+                if (disabledJudges.includes(required)) {
+                    violations.push(`Required judge '${required}' is disabled in .judgesrc`);
+                }
+            }
+            // Check banned rules
+            const enabledRules = config.ruleOverrides ? Object.keys(config.ruleOverrides) : [];
+            for (const banned of policy.bannedRules) {
+                if (enabledRules.includes(banned)) {
+                    warnings.push(`Banned rule '${banned}' has overrides in .judgesrc`);
+                }
+            }
+            // Check preset
+            if (policy.requiredPreset && config.preset !== policy.requiredPreset) {
+                violations.push(`Required preset '${policy.requiredPreset}' not configured (found: '${config.preset || "none"}')`);
+            }
+        }
+        catch {
+            violations.push("Invalid .judgesrc — cannot parse JSON");
+        }
+    }
+    // Check suppressions count
+    if (existsSync(".judges-suppressions.json")) {
+        try {
+            const supps = JSON.parse(readFileSync(".judges-suppressions.json", "utf-8"));
+            const count = Array.isArray(supps) ? supps.length : supps.suppressions?.length || 0;
+            if (count > policy.maxSuppressionsPerRepo) {
+                violations.push(`Suppressions count (${count}) exceeds policy limit (${policy.maxSuppressionsPerRepo})`);
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return {
+        compliant: violations.length === 0,
+        violations,
+        warnings,
+        checkedAt: new Date().toISOString(),
+    };
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+const STORE = ".judges-org-policy";
+export function runOrgPolicy(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges org-policy — Organization-wide policy management
+
+Usage:
+  judges org-policy --init
+  judges org-policy --check
+  judges org-policy --show
+  judges org-policy --set-required-judges "owasp-judge,crypto-judge"
+  judges org-policy --set-min-severity medium
+
+Options:
+  --init                Create default org policy file
+  --check               Check repo compliance against org policy
+  --show                Show current org policy
+  --set-required-judges Comma-separated list of required judge IDs
+  --set-banned-rules    Comma-separated list of banned rule IDs
+  --set-min-severity    Minimum severity level
+  --set-preset          Required preset name
+  --set-max-suppressions Maximum allowed suppressions per repo
+  --format json         JSON output
+  --help, -h            Show this help
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    const policyPath = join(STORE, "org-policy.json");
+    // Init
+    if (argv.includes("--init")) {
+        if (!existsSync(STORE))
+            mkdirSync(STORE, { recursive: true });
+        if (existsSync(policyPath)) {
+            console.log("  Org policy already exists. Edit directly or use --set-* options.");
+            return;
+        }
+        writeFileSync(policyPath, JSON.stringify(DEFAULT_POLICY, null, 2));
+        console.log(`  Initialized org policy at ${policyPath}`);
+        return;
+    }
+    // Load policy
+    let policy;
+    if (existsSync(policyPath)) {
+        policy = JSON.parse(readFileSync(policyPath, "utf-8"));
+    }
+    else {
+        if (!argv.includes("--init")) {
+            console.log("  No org policy found. Run --init to create one.");
+            return;
+        }
+        policy = DEFAULT_POLICY;
+    }
+    // Set options
+    let modified = false;
+    const reqJudges = argv.find((_a, i) => argv[i - 1] === "--set-required-judges");
+    if (reqJudges) {
+        policy.requiredJudges = reqJudges.split(",");
+        modified = true;
+    }
+    const bannedRules = argv.find((_a, i) => argv[i - 1] === "--set-banned-rules");
+    if (bannedRules) {
+        policy.bannedRules = bannedRules.split(",");
+        modified = true;
+    }
+    const minSev = argv.find((_a, i) => argv[i - 1] === "--set-min-severity");
+    if (minSev) {
+        policy.minSeverity = minSev;
+        modified = true;
+    }
+    const preset = argv.find((_a, i) => argv[i - 1] === "--set-preset");
+    if (preset) {
+        policy.requiredPreset = preset;
+        modified = true;
+    }
+    const maxSupp = argv.find((_a, i) => argv[i - 1] === "--set-max-suppressions");
+    if (maxSupp) {
+        policy.maxSuppressionsPerRepo = parseInt(maxSupp, 10);
+        modified = true;
+    }
+    if (modified) {
+        policy.lastUpdated = new Date().toISOString();
+        if (!existsSync(STORE))
+            mkdirSync(STORE, { recursive: true });
+        writeFileSync(policyPath, JSON.stringify(policy, null, 2));
+        console.log("  Org policy updated.");
+    }
+    // Check compliance
+    if (argv.includes("--check")) {
+        const result = checkCompliance(policy);
+        if (format === "json") {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(`\n  Org Policy Compliance\n  ──────────────────────────`);
+            console.log(`  Status: ${result.compliant ? "✅ Compliant" : "❌ Non-compliant"}\n`);
+            for (const v of result.violations)
+                console.log(`    ❌ ${v}`);
+            for (const w of result.warnings)
+                console.log(`    ⚠️  ${w}`);
+            if (result.compliant && result.warnings.length === 0)
+                console.log(`    All checks passed`);
+            console.log("");
+        }
+        return;
+    }
+    // Show
+    if (argv.includes("--show") || !modified) {
+        if (format === "json") {
+            console.log(JSON.stringify(policy, null, 2));
+        }
+        else {
+            console.log(`\n  Org Policy: ${policy.name} v${policy.version}`);
+            console.log(`  ──────────────────────────`);
+            console.log(`    Min severity:       ${policy.minSeverity}`);
+            console.log(`    Required preset:    ${policy.requiredPreset || "(none)"}`);
+            console.log(`    Required judges:    ${policy.requiredJudges.length > 0 ? policy.requiredJudges.join(", ") : "(none)"}`);
+            console.log(`    Banned rules:       ${policy.bannedRules.length > 0 ? policy.bannedRules.join(", ") : "(none)"}`);
+            console.log(`    Max suppressions:   ${policy.maxSuppressionsPerRepo}`);
+            console.log(`    Last updated:       ${policy.lastUpdated}\n`);
+        }
+    }
+}

package/dist/commands/over-abstraction.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Over-abstraction — detect unnecessary abstractions and premature generalization from AI.
+ */
+export declare function runOverAbstraction(argv: string[]): void;

package/dist/commands/over-abstraction.js

@@ -0,0 +1,307 @@
+/**
+ * Over-abstraction — detect unnecessary abstractions and premature generalization from AI.
+ */
+import { readFileSync, readdirSync, statSync } from "fs";
+import { join, extname } from "path";
+// ─── File Collection ────────────────────────────────────────────────────────
+const CODE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx"]);
+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;
+}
+// ─── Cross-file data ────────────────────────────────────────────────────────
+function buildUsageIndex(files) {
+    const usageCount = new Map();
+    const allContent = new Map();
+    for (const f of files) {
+        try {
+            allContent.set(f, readFileSync(f, "utf-8"));
+        }
+        catch {
+            /* skip */
+        }
+    }
+    // Count how many files reference each exported name
+    for (const [_file, content] of allContent) {
+        const exportNames = [
+            ...content.matchAll(/export\s+(?:default\s+)?(?:function|class|const|let|var|type|interface|enum|abstract\s+class)\s+(\w+)/g),
+        ].map((m) => m[1]);
+        for (const name of exportNames) {
+            let count = 0;
+            for (const [otherFile, otherContent] of allContent) {
+                if (otherFile === _file)
+                    continue;
+                if (new RegExp(`\\b${name}\\b`).test(otherContent))
+                    count++;
+            }
+            usageCount.set(name, count);
+        }
+    }
+    return usageCount;
+}
+// ─── Analysis ───────────────────────────────────────────────────────────────
+function analyzeFile(filepath, usageCount, allContents) {
+    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];
+        // Abstract class with single subclass
+        if (/(?:export\s+)?abstract\s+class\s+(\w+)/.test(line)) {
+            const className = line.match(/abstract\s+class\s+(\w+)/)?.[1];
+            if (className) {
+                let subclassCount = 0;
+                for (const [_f, c] of allContents) {
+                    const extends_ = (c.match(new RegExp(`extends\\s+${className}\\b`, "g")) || []).length;
+                    subclassCount += extends_;
+                }
+                if (subclassCount <= 1) {
+                    issues.push({
+                        file: filepath,
+                        line: i + 1,
+                        issue: "Abstract class with single implementation",
+                        severity: "medium",
+                        detail: `\`${className}\` has ${subclassCount} subclass(es) — abstract base is premature; inline into the concrete class`,
+                    });
+                }
+            }
+        }
+        // Interface with single implementation
+        if (/(?:export\s+)?interface\s+(\w+)\s*\{/.test(line)) {
+            const ifaceName = line.match(/interface\s+(\w+)/)?.[1];
+            if (ifaceName &&
+                !ifaceName.endsWith("Props") &&
+                !ifaceName.endsWith("Options") &&
+                !ifaceName.endsWith("Config")) {
+                let implCount = 0;
+                for (const [_f, c] of allContents) {
+                    if (new RegExp(`implements\\s+${ifaceName}\\b`).test(c))
+                        implCount++;
+                    if (new RegExp(`:\\s*${ifaceName}\\b`).test(c))
+                        implCount++;
+                }
+                const uses = usageCount.get(ifaceName) || 0;
+                if (implCount <= 1 && uses <= 1 && !/export/.test(line)) {
+                    issues.push({
+                        file: filepath,
+                        line: i + 1,
+                        issue: "Interface used only once",
+                        severity: "low",
+                        detail: `\`${ifaceName}\` has single implementation and minimal usage — may be premature abstraction`,
+                    });
+                }
+            }
+        }
+        // Generic type parameter used in one instantiation
+        if (/(?:function|class)\s+\w+\s*<(\w+)/.test(line)) {
+            const genericParam = line.match(/<(\w+)(?:\s+extends)?/)?.[1];
+            if (genericParam && genericParam !== "T") {
+                // This is a heuristic — single-letter generics are normal
+                const body = lines.slice(i, Math.min(i + 30, lines.length)).join("\n");
+                const usages = (body.match(new RegExp(`\\b${genericParam}\\b`, "g")) || []).length;
+                if (usages <= 2) {
+                    issues.push({
+                        file: filepath,
+                        line: i + 1,
+                        issue: "Generic type parameter barely used",
+                        severity: "low",
+                        detail: `Generic \`<${genericParam}>\` used only ${usages} times in body — concrete type may suffice`,
+                    });
+                }
+            }
+        }
+        // Factory function that creates only one type
+        if (/(?:function|const)\s+create(\w+)\s*(?:=\s*\(|\()/.test(line)) {
+            const factoryName = line.match(/(?:function|const)\s+(create\w+)/)?.[1];
+            if (factoryName) {
+                const block = lines.slice(i, Math.min(i + 20, lines.length)).join("\n");
+                const newCount = (block.match(/new\s+\w+/g) || []).length;
+                const returnCount = (block.match(/return\s+(?:new\s+)?\w+/g) || []).length;
+                if (newCount === 1 && returnCount <= 1) {
+                    issues.push({
+                        file: filepath,
+                        line: i + 1,
+                        issue: "Factory that creates single type",
+                        severity: "low",
+                        detail: `\`${factoryName}\` creates one concrete type — factory pattern adds unnecessary indirection`,
+                    });
+                }
+            }
+        }
+        // Wrapper function that only delegates
+        if (/(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/.test(line)) {
+            const funcName = line.match(/function\s+(\w+)/)?.[1];
+            const block = lines
+                .slice(i + 1, Math.min(i + 5, lines.length))
+                .join("\n")
+                .trim();
+            // Function body is just "return otherFunc(args)" or similar
+            if (/^(?:\{?\s*)?return\s+\w+\s*\([^)]*\)\s*;?\s*\}?\s*$/.test(block)) {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "Wrapper function with no added logic",
+                    severity: "medium",
+                    detail: `\`${funcName}\` only delegates to another function — remove the wrapper and call directly`,
+                });
+            }
+        }
+        // Config object for single value
+        if (/(?:interface|type)\s+(\w*Config\w*|\w*Options\w*)\s*[={]/.test(line)) {
+            const configName = line.match(/(?:interface|type)\s+(\w+)/)?.[1];
+            if (configName) {
+                let depth = 0;
+                let end = i;
+                let started = false;
+                for (let j = i; j < Math.min(i + 20, lines.length); j++) {
+                    for (const ch of lines[j]) {
+                        if (ch === "{") {
+                            depth++;
+                            started = true;
+                        }
+                        if (ch === "}")
+                            depth--;
+                    }
+                    if (started && depth <= 0) {
+                        end = j;
+                        break;
+                    }
+                }
+                const body = lines.slice(i + 1, end).join("\n");
+                const fieldCount = (body.match(/\w+\s*[?:]?\s*:/g) || []).length;
+                if (fieldCount === 1) {
+                    issues.push({
+                        file: filepath,
+                        line: i + 1,
+                        issue: "Config type with single field",
+                        severity: "low",
+                        detail: `\`${configName}\` has only 1 field — pass the value directly instead of wrapping in config object`,
+                    });
+                }
+            }
+        }
+        // Strategy pattern with single strategy
+        if (/(?:Strategy|Handler|Provider|Adapter)\s*[{<\]]/.test(line) && /interface|type/.test(line)) {
+            const patternName = line.match(/(\w+(?:Strategy|Handler|Provider|Adapter))/)?.[1];
+            if (patternName) {
+                let implCount = 0;
+                for (const [_f, c] of allContents) {
+                    if (new RegExp(`implements\\s+${patternName}\\b`).test(c))
+                        implCount++;
+                    if (new RegExp(`class\\s+\\w+${patternName.replace(/^I/, "")}\\b`).test(c))
+                        implCount++;
+                }
+                if (implCount <= 1) {
+                    issues.push({
+                        file: filepath,
+                        line: i + 1,
+                        issue: "Pattern interface with single implementation",
+                        severity: "medium",
+                        detail: `\`${patternName}\` has ${implCount} implementation(s) — strategy/adapter pattern is premature`,
+                    });
+                }
+            }
+        }
+    }
+    return issues;
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runOverAbstraction(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges over-abstraction — Detect unnecessary abstractions from AI-generated code
+
+Usage:
+  judges over-abstraction [dir]
+  judges over-abstraction src/ --format json
+
+Options:
+  [dir]                 Directory to scan (default: .)
+  --format json         JSON output
+  --help, -h            Show this help
+
+Checks: abstract classes with single subclass, single-implementation interfaces,
+barely-used generics, single-type factories, delegation-only wrappers,
+single-field config types, single-impl strategy/adapter patterns.
+`);
+        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 usageCount = buildUsageIndex(files);
+    const allContents = new Map();
+    for (const f of files) {
+        try {
+            allContents.set(f, readFileSync(f, "utf-8"));
+        }
+        catch {
+            /* skip */
+        }
+    }
+    const allIssues = [];
+    for (const f of files)
+        allIssues.push(...analyzeFile(f, usageCount, allContents));
+    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 * 10 - medCount * 5 - allIssues.filter((i) => i.severity === "low").length * 2);
+    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 ? "✅ LEAN" : score >= 50 ? "⚠️  OVER-BUILT" : "❌ OVER-ENGINEERED";
+        console.log(`\n  Over-Abstraction: ${badge} (${score}/100)\n  ─────────────────────────────`);
+        if (allIssues.length === 0) {
+            console.log("    No over-abstraction 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/override.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `judges override` — Structured exception/override workflow for gating.
+ *
+ * When the PR gate blocks a merge, developers can log a justified override
+ * rather than disabling the entire check. Overrides are tracked in an
+ * auditable log (.judges-overrides.json) with required justification.
+ *
+ * Usage:
+ *   judges override add --rule SEC-001 --reason "Mitigated by WAF" --approver "jane@co.com"
+ *   judges override list                       # Show active overrides
+ *   judges override revoke --rule SEC-001      # Revoke an override
+ *   judges override check --file src/app.ts    # Check if findings have applicable overrides
+ */
+export interface Override {
+    /** Rule ID being overridden (e.g. "SEC-001") or prefix (e.g. "SEC-*") */
+    ruleId: string;
+    /** Required: why this override is justified */
+    reason: string;
+    /** Who approved the override */
+    approver?: string;
+    /** Optional: scope to specific file paths (glob patterns) */
+    filePaths?: string[];
+    /** When the override was created */
+    createdAt: string;
+    /** Optional expiry date — override expires after this date */
+    expiresAt?: string;
+    /** Whether the override is currently active */
+    active: boolean;
+    /** When it was revoked (if applicable) */
+    revokedAt?: string;
+    /** Who revoked it */
+    revokedBy?: string;
+}
+export interface OverrideStore {
+    version: 1;
+    overrides: Override[];
+    metadata: {
+        createdAt: string;
+        lastUpdated: string;
+    };
+}
+export declare function loadOverrideStore(dir?: string): OverrideStore;
+export declare function saveOverrideStore(store: OverrideStore, dir?: string): void;
+/**
+ * Check if a finding's rule ID matches an active, non-expired override.
+ */
+export declare function isOverridden(ruleId: string, filePath: string | undefined, store: OverrideStore): Override | undefined;
+/**
+ * Apply overrides to a list of findings — returns findings with overridden
+ * ones removed, plus the list of overridden findings for audit.
+ */
+export declare function applyOverrides<T extends {
+    ruleId: string;
+}>(findings: T[], store: OverrideStore, filePath?: string): {
+    active: T[];
+    overridden: Array<{
+        finding: T;
+        override: Override;
+    }>;
+};
+export declare function runOverride(argv: string[]): void;