@kevinrabun/judges-cli 3.124.0

package/dist/commands/override.js

@@ -0,0 +1,268 @@
+/**
+ * `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
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { resolve, dirname } from "path";
+import { matchGlobPath } from "../tools/command-safety.js";
+// ─── Store I/O ──────────────────────────────────────────────────────────────
+const OVERRIDE_FILE = ".judges-overrides.json";
+function createEmptyStore() {
+    const now = new Date().toISOString();
+    return { version: 1, overrides: [], metadata: { createdAt: now, lastUpdated: now } };
+}
+export function loadOverrideStore(dir = ".") {
+    const filePath = resolve(dir, OVERRIDE_FILE);
+    if (!existsSync(filePath))
+        return createEmptyStore();
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+        if (raw.version === 1 && Array.isArray(raw.overrides))
+            return raw;
+        return createEmptyStore();
+    }
+    catch {
+        return createEmptyStore();
+    }
+}
+export function saveOverrideStore(store, dir = ".") {
+    const filePath = resolve(dir, OVERRIDE_FILE);
+    const d = dirname(filePath);
+    if (!existsSync(d))
+        mkdirSync(d, { recursive: true });
+    store.metadata.lastUpdated = new Date().toISOString();
+    writeFileSync(filePath, JSON.stringify(store, null, 2) + "\n", "utf-8");
+}
+// ─── Override Logic ─────────────────────────────────────────────────────────
+/**
+ * Check if a finding's rule ID matches an active, non-expired override.
+ */
+export function isOverridden(ruleId, filePath, store) {
+    const now = new Date().toISOString();
+    for (const o of store.overrides) {
+        if (!o.active)
+            continue;
+        if (o.expiresAt && o.expiresAt < now)
+            continue;
+        // Match exact rule ID or wildcard prefix (e.g. "SEC-*")
+        const matches = o.ruleId === ruleId || (o.ruleId.endsWith("-*") && ruleId.startsWith(o.ruleId.slice(0, -1)));
+        if (!matches)
+            continue;
+        // If file scope is specified, check it
+        if (o.filePaths && o.filePaths.length > 0 && filePath) {
+            const normalizedFilePath = filePath.replace(/\\/g, "/");
+            const fileMatches = o.filePaths.some((pattern) => {
+                const normalizedPattern = pattern.replace(/\\/g, "/");
+                if (normalizedPattern.includes("*") || normalizedPattern.includes("?")) {
+                    return matchGlobPath(normalizedFilePath, normalizedPattern);
+                }
+                return normalizedFilePath === normalizedPattern || normalizedFilePath.startsWith(`${normalizedPattern}/`);
+            });
+            if (!fileMatches)
+                continue;
+        }
+        return o;
+    }
+    return undefined;
+}
+/**
+ * Apply overrides to a list of findings — returns findings with overridden
+ * ones removed, plus the list of overridden findings for audit.
+ */
+export function applyOverrides(findings, store, filePath) {
+    const active = [];
+    const overridden = [];
+    for (const f of findings) {
+        const match = isOverridden(f.ruleId, filePath, store);
+        if (match) {
+            overridden.push({ finding: f, override: match });
+        }
+        else {
+            active.push(f);
+        }
+    }
+    return { active, overridden };
+}
+// ─── CLI Command ────────────────────────────────────────────────────────────
+export function runOverride(argv) {
+    const subcommand = argv[3] || "list";
+    const store = loadOverrideStore();
+    switch (subcommand) {
+        case "add": {
+            let ruleId = "";
+            let reason = "";
+            let approver = "";
+            let expiresAt = "";
+            const filePaths = [];
+            for (let i = 4; i < argv.length; i++) {
+                switch (argv[i]) {
+                    case "--rule":
+                    case "-r":
+                        ruleId = argv[++i] || "";
+                        break;
+                    case "--reason":
+                        reason = argv[++i] || "";
+                        break;
+                    case "--approver":
+                        approver = argv[++i] || "";
+                        break;
+                    case "--expires":
+                        expiresAt = argv[++i] || "";
+                        break;
+                    case "--file":
+                    case "-f":
+                        filePaths.push(argv[++i] || "");
+                        break;
+                }
+            }
+            if (!ruleId) {
+                console.error('Error: --rule is required. Example: judges override add --rule SEC-001 --reason "Mitigated by WAF"');
+                process.exit(1);
+            }
+            if (!reason) {
+                console.error("Error: --reason is required. Overrides must have a justification.");
+                process.exit(1);
+            }
+            const override = {
+                ruleId,
+                reason,
+                approver: approver || undefined,
+                filePaths: filePaths.length > 0 ? filePaths : undefined,
+                createdAt: new Date().toISOString(),
+                expiresAt: expiresAt || undefined,
+                active: true,
+            };
+            store.overrides.push(override);
+            saveOverrideStore(store);
+            console.log("");
+            console.log("  ✅ Override added:");
+            console.log(`     Rule     : ${ruleId}`);
+            console.log(`     Reason   : ${reason}`);
+            if (approver)
+                console.log(`     Approver : ${approver}`);
+            if (expiresAt)
+                console.log(`     Expires  : ${expiresAt}`);
+            if (filePaths.length > 0)
+                console.log(`     Scope    : ${filePaths.join(", ")}`);
+            console.log("");
+            break;
+        }
+        case "list": {
+            const now = new Date().toISOString();
+            const active = store.overrides.filter((o) => o.active && (!o.expiresAt || o.expiresAt >= now));
+            const expired = store.overrides.filter((o) => o.active && o.expiresAt && o.expiresAt < now);
+            const revoked = store.overrides.filter((o) => !o.active);
+            console.log("");
+            console.log("╔══════════════════════════════════════════════════════════════╗");
+            console.log("║           Judges Panel — Override Registry                  ║");
+            console.log("╚══════════════════════════════════════════════════════════════╝");
+            console.log("");
+            if (active.length === 0 && expired.length === 0 && revoked.length === 0) {
+                console.log("  No overrides registered.\n");
+                break;
+            }
+            if (active.length > 0) {
+                console.log(`  Active Overrides (${active.length}):`);
+                console.log("  " + "─".repeat(58));
+                for (const o of active) {
+                    console.log(`  ${o.ruleId.padEnd(14)} ${o.reason.slice(0, 50)}`);
+                    if (o.approver)
+                        console.log(`${"".padEnd(16)} Approver: ${o.approver}`);
+                    if (o.expiresAt)
+                        console.log(`${"".padEnd(16)} Expires: ${o.expiresAt}`);
+                }
+                console.log("");
+            }
+            if (expired.length > 0) {
+                console.log(`  Expired Overrides (${expired.length}):`);
+                for (const o of expired) {
+                    console.log(`  ${o.ruleId.padEnd(14)} expired ${o.expiresAt}`);
+                }
+                console.log("");
+            }
+            if (revoked.length > 0) {
+                console.log(`  Revoked Overrides (${revoked.length}):`);
+                for (const o of revoked) {
+                    console.log(`  ${o.ruleId.padEnd(14)} revoked ${o.revokedAt || "unknown"}`);
+                }
+                console.log("");
+            }
+            break;
+        }
+        case "revoke": {
+            let ruleId = "";
+            let revokedBy = "";
+            for (let i = 4; i < argv.length; i++) {
+                switch (argv[i]) {
+                    case "--rule":
+                    case "-r":
+                        ruleId = argv[++i] || "";
+                        break;
+                    case "--by":
+                        revokedBy = argv[++i] || "";
+                        break;
+                }
+            }
+            if (!ruleId) {
+                console.error("Error: --rule is required. Example: judges override revoke --rule SEC-001");
+                process.exit(1);
+            }
+            let revoked = 0;
+            for (const o of store.overrides) {
+                if (o.ruleId === ruleId && o.active) {
+                    o.active = false;
+                    o.revokedAt = new Date().toISOString();
+                    o.revokedBy = revokedBy || undefined;
+                    revoked++;
+                }
+            }
+            if (revoked > 0) {
+                saveOverrideStore(store);
+                console.log(`  ✅ Revoked ${revoked} override(s) for ${ruleId}\n`);
+            }
+            else {
+                console.log(`  No active overrides found for ${ruleId}\n`);
+            }
+            break;
+        }
+        case "check": {
+            let filePath = "";
+            for (let i = 4; i < argv.length; i++) {
+                if (argv[i] === "--file" || argv[i] === "-f")
+                    filePath = argv[++i] || "";
+                else if (!argv[i].startsWith("-"))
+                    filePath = argv[i];
+            }
+            const now = new Date().toISOString();
+            const active = store.overrides.filter((o) => o.active && (!o.expiresAt || o.expiresAt >= now));
+            if (active.length === 0) {
+                console.log("  No active overrides.\n");
+                break;
+            }
+            console.log(`\n  Active overrides${filePath ? ` for ${filePath}` : ""}:`);
+            for (const o of active) {
+                const scopeMatch = !o.filePaths ||
+                    o.filePaths.length === 0 ||
+                    !filePath ||
+                    o.filePaths.some((pattern) => matchGlobPath(filePath, pattern));
+                const status = scopeMatch ? "✅ applies" : "⬜ out of scope";
+                console.log(`  ${o.ruleId.padEnd(14)} ${status} — ${o.reason.slice(0, 50)}`);
+            }
+            console.log("");
+            break;
+        }
+        default:
+            console.error(`Unknown override subcommand: ${subcommand}`);
+            console.error("Usage: judges override <add|list|revoke|check>");
+            process.exit(1);
+    }
+}

package/dist/commands/ownership-map.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Ownership map — generate and validate code ownership coverage from
+ * CODEOWNERS, git history, and module boundaries.
+ */
+export declare function runOwnershipMap(argv: string[]): void;

package/dist/commands/ownership-map.js

@@ -0,0 +1,217 @@
+/**
+ * Ownership map — generate and validate code ownership coverage from
+ * CODEOWNERS, git history, and module boundaries.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from "fs";
+import { join, extname, relative } from "path";
+import { matchGlobPath, runGit } from "../tools/command-safety.js";
+// ─── CODEOWNERS Parsing ─────────────────────────────────────────────────────
+function parseCodeowners(dir) {
+    const candidates = [join(dir, "CODEOWNERS"), join(dir, ".github", "CODEOWNERS"), join(dir, "docs", "CODEOWNERS")];
+    for (const path of candidates) {
+        if (existsSync(path)) {
+            const content = readFileSync(path, "utf-8");
+            const entries = [];
+            for (const line of content.split("\n")) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith("#"))
+                    continue;
+                const parts = trimmed.split(/\s+/);
+                if (parts.length >= 2) {
+                    entries.push({ pattern: parts[0], owners: parts.slice(1) });
+                }
+            }
+            return entries;
+        }
+    }
+    return [];
+}
+// ─── File Collection ────────────────────────────────────────────────────────
+const CODE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".java", ".go", ".rs", ".cs", ".rb"]);
+function collectSourceFiles(dir, max = 500) {
+    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 matchesPattern(filepath, pattern) {
+    return matchGlobPath(filepath, pattern) || filepath.startsWith(pattern) || filepath === pattern;
+}
+function getRecentAuthors(dir, filepath, months = 6) {
+    try {
+        const since = new Date();
+        since.setMonth(since.getMonth() - months);
+        const dateStr = since.toISOString().split("T")[0];
+        const output = runGit(["log", `--since=${dateStr}`, "--format=%ae", "--", filepath], {
+            cwd: dir,
+            timeout: 5000,
+        });
+        if (!output)
+            return [];
+        return [...new Set(output.split("\n"))];
+    }
+    catch {
+        return [];
+    }
+}
+function analyze(dir) {
+    const gaps = [];
+    const entries = parseCodeowners(dir);
+    const files = collectSourceFiles(dir);
+    if (entries.length === 0) {
+        gaps.push({
+            path: "CODEOWNERS",
+            issue: "No CODEOWNERS file",
+            severity: "high",
+            detail: "Create a CODEOWNERS file to formalize code ownership",
+        });
+        return { gaps, stats: { total: files.length, owned: 0, orphaned: files.length, stale: 0 } };
+    }
+    let owned = 0;
+    let orphaned = 0;
+    let stale = 0;
+    // Check top-level directories for ownership
+    const dirs = new Set();
+    for (const f of files) {
+        const rel = relative(dir, f).replace(/\\/g, "/");
+        const topDir = rel.split("/")[0];
+        dirs.add(topDir);
+        // Check if file has an owner
+        const hasOwner = entries.some((e) => matchesPattern(rel, e.pattern));
+        if (hasOwner) {
+            owned++;
+        }
+        else {
+            orphaned++;
+            if (orphaned <= 15) {
+                gaps.push({
+                    path: rel,
+                    issue: "No code owner",
+                    severity: "medium",
+                    detail: "File has no matching CODEOWNERS entry",
+                });
+            }
+        }
+    }
+    if (orphaned > 15) {
+        gaps.push({
+            path: "(multiple)",
+            issue: `${orphaned - 15} more unowned files`,
+            severity: "medium",
+            detail: "Add broader patterns to CODEOWNERS",
+        });
+    }
+    // Check for stale owners (paths with owner but no recent commits)
+    for (const entry of entries) {
+        const matchingFiles = files.filter((f) => matchesPattern(relative(dir, f).replace(/\\/g, "/"), entry.pattern));
+        if (matchingFiles.length === 0) {
+            gaps.push({
+                path: entry.pattern,
+                issue: "CODEOWNERS pattern matches no files",
+                severity: "low",
+                detail: `Pattern "${entry.pattern}" → ${entry.owners.join(", ")} matches nothing`,
+            });
+            continue;
+        }
+        // Sample one file for recency
+        const sample = matchingFiles[0];
+        const authors = getRecentAuthors(dir, sample);
+        if (authors.length === 0) {
+            stale++;
+            gaps.push({
+                path: entry.pattern,
+                issue: "Stale ownership",
+                severity: "medium",
+                detail: `No commits in 6 months for "${entry.pattern}" (owners: ${entry.owners.join(", ")})`,
+            });
+        }
+    }
+    // Check for overlapping patterns
+    for (let i = 0; i < entries.length; i++) {
+        for (let j = i + 1; j < entries.length; j++) {
+            const iFiles = files.filter((f) => matchesPattern(relative(dir, f).replace(/\\/g, "/"), entries[i].pattern));
+            const jFiles = files.filter((f) => matchesPattern(relative(dir, f).replace(/\\/g, "/"), entries[j].pattern));
+            const overlap = iFiles.filter((f) => jFiles.includes(f));
+            if (overlap.length > 0) {
+                gaps.push({
+                    path: `${entries[i].pattern} ∩ ${entries[j].pattern}`,
+                    issue: "Overlapping ownership patterns",
+                    severity: "low",
+                    detail: `${overlap.length} files match both patterns — later pattern takes precedence`,
+                });
+            }
+        }
+    }
+    return { gaps, stats: { total: files.length, owned, orphaned, stale } };
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runOwnershipMap(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges ownership-map — Generate and validate code ownership coverage
+
+Usage:
+  judges ownership-map [dir]
+  judges ownership-map --format json
+
+Options:
+  [dir]                 Directory to scan (default: .)
+  --format json         JSON output
+  --help, -h            Show this help
+
+Checks: CODEOWNERS coverage, orphaned files, stale owners, overlapping 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 { gaps, stats } = analyze(dir);
+    const coveragePct = stats.total > 0 ? Math.round((stats.owned / stats.total) * 100) : 100;
+    const score = Math.max(0, coveragePct - stats.stale * 5);
+    if (format === "json") {
+        console.log(JSON.stringify({ gaps, stats, coverage: coveragePct, score, timestamp: new Date().toISOString() }, null, 2));
+    }
+    else {
+        const badge = coveragePct >= 90 ? "✅ GOOD" : coveragePct >= 60 ? "⚠️  PARTIAL" : "❌ LOW";
+        console.log(`\n  Ownership Coverage: ${badge} (${coveragePct}%)\n  ──────────────────────────────`);
+        console.log(`    Total files: ${stats.total} | Owned: ${stats.owned} | Orphaned: ${stats.orphaned} | Stale: ${stats.stale}\n`);
+        if (gaps.length === 0) {
+            console.log("    No ownership issues detected.\n");
+            return;
+        }
+        for (const g of gaps) {
+            const icon = g.severity === "high" ? "🔴" : g.severity === "medium" ? "🟡" : "🔵";
+            console.log(`    ${icon} ${g.issue}`);
+            console.log(`        ${g.path}`);
+            console.log(`        ${g.detail}`);
+        }
+        console.log(`\n    Score: ${score}/100\n`);
+    }
+}

package/dist/commands/parity.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `judges parity` — Language pattern parity audit.
+ *
+ * Audits the language-pattern library to identify gaps where a pattern
+ * concept exists for some languages but not others, helping maintainers
+ * prioritise pattern-writing effort.
+ *
+ * Usage:
+ *   judges parity                          # text table
+ *   judges parity --json                   # JSON output
+ *   judges parity --lang python            # filter to one language
+ */
+import type { LangFamily } from "../types.js";
+export interface PatternEntry {
+    name: string;
+    languages: LangFamily[];
+    missingLanguages: LangFamily[];
+    coverage: number;
+}
+export interface ParityReport {
+    patterns: PatternEntry[];
+    languageCoverage: Record<string, {
+        covered: number;
+        total: number;
+        pct: number;
+    }>;
+    overallCoverage: number;
+}
+export declare function analyzePatternParity(filterLang?: LangFamily): ParityReport;
+export declare function runParity(argv: string[]): void;