@kevinrabun/judges 3.115.1 → 3.115.3

package/dist/commands/help.js

@@ -0,0 +1,302 @@
+/**
+ * `judges help [topic]` — contextual help and getting-started guides.
+ *
+ * Provides quick, actionable guidance for each major capability area.
+ * Run without arguments to see all available topics.
+ */
+const TOPICS = {
+    "getting-started": {
+        title: "Getting Started",
+        summary: "First steps with Judges Panel",
+        body: `
+  Quick Start
+  ───────────
+  1. Evaluate a single file:
+       judges eval server.ts
+
+  2. Scan an entire directory:
+       judges eval src/
+
+  3. Generate a config file:
+       judges init
+
+  4. Use a preset for CI:
+       judges eval src/ --preset security
+
+  5. Auto-fix findings:
+       judges eval src/ --fix
+
+  Common Flags
+  ────────────
+    --format json|sarif|html|markdown   Output format
+    --fix                               Apply auto-fix patches
+    --baseline .judges-baseline.json    Suppress known findings
+    --incremental                       Cache results for unchanged files
+    --changed-only                      Only scan git-changed files
+    --quiet                             Suppress progress output
+    --explain                           Show CWE/OWASP context for findings
+`,
+    },
+    feedback: {
+        title: "Feedback & False Positive Reporting",
+        summary: "How to improve accuracy with feedback",
+        body: `
+  Providing Feedback
+  ──────────────────
+  Feedback trains Judges to reduce false positives over time.
+
+  CLI:
+    judges feedback add --rule SEC-001 --verdict fp --comment "Not exploitable"
+    judges feedback add --rule AUTH-003 --verdict tp
+    judges feedback list
+    judges feedback stats
+
+  VS Code:
+    Click the thumbs-up/down icons on any finding's code action menu.
+    Feedback is stored in .judges-feedback.json in your workspace.
+
+  Verdicts:
+    tp         True positive (real issue)
+    fp         False positive (not a real issue)
+    wontfix    Acknowledged but won't fix
+
+  Your feedback is stored locally and never sent externally.
+  Configure a DataAdapter in .judgesrc to share feedback with your team.
+`,
+    },
+    calibration: {
+        title: "Calibration & Confidence Tuning",
+        summary: "How to tune judge accuracy for your codebase",
+        body: `
+  Auto-Calibration
+  ────────────────
+    judges tune             Run auto-calibration on your feedback data
+    judges tune --dry-run   Preview what would change
+
+  Calibration Dashboard
+  ─────────────────────
+    judges calibration-dashboard          Open interactive HTML dashboard
+    judges calibration-dashboard --output report.html
+
+  How It Works
+  ────────────
+  Judges uses your feedback (tp/fp verdicts) to adjust confidence thresholds
+  per rule. Rules with many false positives get their confidence reduced;
+  rules with consistent true positives are boosted.
+
+  Team Sharing
+  ────────────
+  Calibration profiles are stored in .judges-calibration.json.
+  Commit this to your repo so team members benefit from shared tuning.
+`,
+    },
+    ci: {
+        title: "CI/CD Integration",
+        summary: "Setting up Judges in CI pipelines",
+        body: `
+  Generate CI Config
+  ──────────────────
+    judges ci-templates              Show all available templates
+    judges ci-templates --github     GitHub Actions workflow
+    judges ci-templates --gitlab     GitLab CI config
+    judges ci-templates --azure      Azure Pipelines config
+    judges ci-templates --bitbucket  Bitbucket Pipelines config
+
+  Recommended CI Setup
+  ────────────────────
+  1. Create a baseline to suppress existing findings:
+       judges baseline create --dir src/
+
+  2. Run incremental scans in PRs:
+       judges eval src/ --changed-only --fail-on-findings --format sarif
+
+  3. Upload SARIF to GitHub Code Scanning:
+       - uses: github/codeql-action/upload-sarif@v3
+         with:
+           sarif_file: judges-report.sarif.json
+
+  Environment Variables
+  ─────────────────────
+    JUDGES_CACHE_DIR    Custom cache directory (default: .judges-cache)
+    JUDGES_NO_COLOR     Disable colored output
+    JUDGES_CONFIG       Path to .judgesrc config file
+`,
+    },
+    presets: {
+        title: "Presets & Configuration",
+        summary: "Using and composing evaluation presets",
+        body: `
+  Available Presets
+  ────────────────
+    judges eval --preset security       Security-focused evaluation
+    judges eval --preset quality        Code quality focus
+    judges eval --preset compliance     Compliance & governance
+    judges eval --preset full           All judges enabled
+
+  List All Presets
+  ────────────────
+    judges config presets
+
+  Composing Presets
+  ────────────────
+  In .judgesrc, you can compose multiple presets:
+    {
+      "presets": ["security", "quality"],
+      "disabledRules": ["DOC-001"],
+      "minSeverity": "medium"
+    }
+
+  Custom Config (.judgesrc)
+  ────────────────────────
+    judges init                    Generate a starter .judgesrc
+    judges config validate         Validate your config
+    judges doctor                  Diagnose configuration issues
+`,
+    },
+    plugins: {
+        title: "Plugins & Custom Rules",
+        summary: "Extending Judges with custom rules and plugins",
+        body: `
+  Creating a Plugin
+  ─────────────────
+    judges scaffold-plugin my-rules    Generate a plugin template
+
+  Plugin Structure
+  ────────────────
+    my-rules/
+      package.json        # name, version, "judges-plugin" keyword
+      index.js            # exports { rules: [...] }
+
+  Installing Plugins
+  ──────────────────
+  Add to .judgesrc:
+    {
+      "plugins": ["@myorg/judges-plugin-custom"]
+    }
+
+  Community Patterns
+  ──────────────────
+    judges community-patterns          Browse community rule patterns
+
+  See docs/plugin-guide.md for the full authoring guide.
+`,
+    },
+    "data-adapter": {
+        title: "Data Adapters (Team Storage)",
+        summary: "Configure external storage for team-wide sharing",
+        body: `
+  What Are Data Adapters?
+  ──────────────────────
+  By default, Judges stores feedback, findings, and metrics as local JSON
+  files. Data Adapters let your team share this data via your own backend.
+
+  Judges never hosts or processes your data — you bring your own storage.
+
+  Configuration (.judgesrc)
+  ────────────────────────
+  Local filesystem (default):
+    {
+      "dataAdapter": { "type": "filesystem" }
+    }
+
+  HTTP backend (your own API):
+    {
+      "dataAdapter": {
+        "type": "http",
+        "url": "https://your-team-api.example.com/judges",
+        "headers": {
+          "Authorization": "Bearer \${JUDGES_API_TOKEN}"
+        }
+      }
+    }
+
+  Environment variables in header values are resolved automatically.
+  The HTTP adapter uses standard REST endpoints:
+    GET  /feedback       Load feedback store
+    PUT  /feedback       Save feedback store
+    GET  /findings       Load finding store
+    PUT  /findings       Save finding store
+`,
+    },
+    "security-ids": {
+        title: "CWE & OWASP Identifiers",
+        summary: "How findings map to CWE and OWASP standards",
+        body: `
+  Structured Security IDs
+  ──────────────────────
+  Every finding is automatically enriched with CWE and OWASP identifiers
+  based on its rule prefix and specific rule ID.
+
+  Examples:
+    SEC-001  →  CWE-89 (SQL Injection), OWASP A03:2021
+    AUTH-001 →  CWE-798 (Hard-coded Credentials), OWASP A07:2021
+    XSS-*    →  CWE-79 (Cross-site Scripting), OWASP A03:2021
+    SSRF-*   →  CWE-918 (Server-Side Request Forgery), OWASP A10:2021
+
+  These IDs appear in:
+    - SARIF output (as rule tags)
+    - JSON output (cweIds / owaspIds fields)
+    - The --explain flag output
+    - VS Code extension hover details
+
+  Use --format sarif for tool integration with GitHub Code Scanning,
+  SonarQube, Snyk, and other platforms that consume CWE/OWASP data.
+`,
+    },
+    metrics: {
+        title: "Metrics & ROI Tracking",
+        summary: "Measuring the value Judges provides",
+        body: `
+  Quick Metrics
+  ─────────────
+    judges metrics                    Summary to stdout
+    judges metrics --format json      Machine-readable output
+    judges metrics --since 30d        Last 30 days only
+
+  Visual Dashboard
+  ────────────────
+    judges metrics-dashboard                  Generate HTML dashboard
+    judges metrics-dashboard --output dash.html
+
+  What's Tracked
+  ─────────────
+    - Findings detected / fixed / open / false-positive
+    - Auto-fix adoption rate
+    - Estimated time saved (conservative industry averages)
+    - Trend direction (improving / stable / degrading)
+    - Fix rates by severity
+
+  All metrics are computed from local data. Configure a DataAdapter
+  to aggregate metrics across your team (see: judges help data-adapter).
+`,
+    },
+};
+// ─── Runner ─────────────────────────────────────────────────────────────────
+export function runHelp(argv) {
+    const topic = argv.find((a, i) => i > 2 && !a.startsWith("-"))?.toLowerCase();
+    if (!topic) {
+        printTopicList();
+        return;
+    }
+    const entry = TOPICS[topic];
+    if (!entry) {
+        console.error(`  Unknown help topic: "${topic}"\n`);
+        printTopicList();
+        process.exit(1);
+    }
+    console.log("");
+    console.log(`  ${entry.title}`);
+    console.log(`  ${"─".repeat(entry.title.length)}`);
+    console.log(entry.body);
+}
+function printTopicList() {
+    console.log("");
+    console.log("  Judges Panel — Help Topics");
+    console.log("  ──────────────────────────");
+    console.log("");
+    const maxKey = Math.max(...Object.keys(TOPICS).map((k) => k.length));
+    for (const [key, { summary }] of Object.entries(TOPICS)) {
+        console.log(`    judges help ${key.padEnd(maxKey)}   ${summary}`);
+    }
+    console.log("");
+}

package/dist/commands/hook-install.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hook install — install and configure git hooks for pre-commit
+ * and pre-push evaluation with Judges.
+ *
+ * Supports husky, simple-git-hooks, and direct .git/hooks installation.
+ */
+export interface HookConfig {
+    /** Hook type: pre-commit or pre-push */
+    hook: "pre-commit" | "pre-push";
+    /** Only evaluate staged files */
+    stagedOnly: boolean;
+    /** Fail on findings of this severity or higher */
+    failSeverity: string;
+    /** Timeout in seconds */
+    timeout: number;
+    /** Run in parallel */
+    parallel: boolean;
+    /** Use smart judge selection */
+    smartSelect: boolean;
+}
+export declare function runHookInstall(argv: string[]): void;

package/dist/commands/hook-install.js

@@ -0,0 +1,142 @@
+/**
+ * Hook install — install and configure git hooks for pre-commit
+ * and pre-push evaluation with Judges.
+ *
+ * Supports husky, simple-git-hooks, and direct .git/hooks installation.
+ */
+// ─── Hook Scripts ───────────────────────────────────────────────────────────
+function generateHookScript(config) {
+    const flags = [];
+    if (config.stagedOnly)
+        flags.push("--staged-only");
+    if (config.failSeverity !== "info")
+        flags.push(`--min-severity ${config.failSeverity}`);
+    flags.push("--fail-on-findings");
+    flags.push("--summary");
+    return `#!/bin/sh
+# Judges ${config.hook} hook
+# Auto-generated by: judges hook-install
+
+# Skip if JUDGES_SKIP_HOOK is set
+if [ -n "$JUDGES_SKIP_HOOK" ]; then
+  echo "Judges: hook skipped (JUDGES_SKIP_HOOK is set)"
+  exit 0
+fi
+
+# Timeout protection (${config.timeout}s)
+timeout_cmd=""
+if command -v timeout > /dev/null 2>&1; then
+  timeout_cmd="timeout ${config.timeout}"
+fi
+
+echo "🔍 Judges: evaluating..."
+$timeout_cmd npx judges eval ${flags.join(" ")} 2>&1
+exit_code=$?
+
+if [ $exit_code -ne 0 ] && [ $exit_code -ne 124 ]; then
+  echo ""
+  echo "❌ Judges: findings detected. Fix or skip with JUDGES_SKIP_HOOK=1"
+  exit 1
+fi
+
+if [ $exit_code -eq 124 ]; then
+  echo "⚠️  Judges: evaluation timed out (${config.timeout}s). Proceeding."
+fi
+`;
+}
+// ─── Installation Methods ───────────────────────────────────────────────────
+function installDirect(hookType, script) {
+    const { writeFileSync, mkdirSync, chmodSync, existsSync } = require("fs");
+    const { join } = require("path");
+    const hooksDir = join(".git", "hooks");
+    if (!existsSync(".git")) {
+        console.error("Error: not a git repository");
+        return false;
+    }
+    mkdirSync(hooksDir, { recursive: true });
+    const hookPath = join(hooksDir, hookType);
+    writeFileSync(hookPath, script, { mode: 0o755 });
+    try {
+        chmodSync(hookPath, 0o755);
+    }
+    catch {
+        /* Windows */
+    }
+    console.log(`  ✅ Installed ${hookPath}`);
+    return true;
+}
+function installHusky(hookType, script) {
+    const { existsSync, writeFileSync, mkdirSync } = require("fs");
+    const { join } = require("path");
+    if (!existsSync(".husky")) {
+        console.log("  Husky directory not found. Creating .husky/");
+        mkdirSync(".husky", { recursive: true });
+    }
+    const hookPath = join(".husky", hookType);
+    writeFileSync(hookPath, script, { mode: 0o755 });
+    console.log(`  ✅ Installed ${hookPath} (husky)`);
+    return true;
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runHookInstall(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges hook-install — Install git hooks for automatic code review
+
+Usage:
+  judges hook-install                        Install pre-commit hook
+  judges hook-install --hook pre-push        Install pre-push hook
+  judges hook-install --method husky         Use husky for hook management
+
+Options:
+  --hook <type>        Hook type: pre-commit (default) or pre-push
+  --method <method>    Installation: direct (default), husky
+  --severity <level>   Fail on findings of this severity+ (default: high)
+  --timeout <seconds>  Timeout in seconds (default: 60)
+  --no-staged-only     Evaluate all files, not just staged
+  --uninstall          Remove the hook
+  --show               Show current hook script without installing
+  --help, -h           Show this help
+
+Environment:
+  JUDGES_SKIP_HOOK=1   Skip the hook for a single commit
+`);
+        return;
+    }
+    const hookType = (argv.find((_a, i) => argv[i - 1] === "--hook") || "pre-commit");
+    const method = argv.find((_a, i) => argv[i - 1] === "--method") || "direct";
+    const severity = argv.find((_a, i) => argv[i - 1] === "--severity") || "high";
+    const timeoutStr = argv.find((_a, i) => argv[i - 1] === "--timeout");
+    const timeout = timeoutStr ? parseInt(timeoutStr, 10) : 60;
+    if (argv.includes("--uninstall")) {
+        const { unlinkSync, existsSync } = require("fs");
+        const { join } = require("path");
+        const paths = [join(".git", "hooks", hookType), join(".husky", hookType)];
+        for (const p of paths) {
+            if (existsSync(p)) {
+                unlinkSync(p);
+                console.log(`  ✅ Removed ${p}`);
+            }
+        }
+        return;
+    }
+    const config = {
+        hook: hookType,
+        stagedOnly: !argv.includes("--no-staged-only"),
+        failSeverity: severity,
+        timeout,
+        parallel: true,
+        smartSelect: true,
+    };
+    const script = generateHookScript(config);
+    if (argv.includes("--show")) {
+        console.log(script);
+        return;
+    }
+    if (method === "husky") {
+        installHusky(hookType, script);
+    }
+    else {
+        installDirect(hookType, script);
+    }
+}

package/dist/commands/hook.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `judges hook` — Install/uninstall pre-commit git hooks.
+ *
+ * Usage:
+ *   judges hook install                 # Install pre-commit hook
+ *   judges hook uninstall               # Remove pre-commit hook
+ */
+export declare function runHook(argv: string[]): void;

package/dist/commands/hook.js

@@ -0,0 +1,145 @@
+/**
+ * `judges hook` — Install/uninstall pre-commit git hooks.
+ *
+ * Usage:
+ *   judges hook install                 # Install pre-commit hook
+ *   judges hook uninstall               # Remove pre-commit hook
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, chmodSync } from "fs";
+import { join, resolve } from "path";
+// ─── Hook Content ───────────────────────────────────────────────────────────
+const HOOK_MARKER = "# judges-panel-hook";
+function generateHookScript() {
+    return `#!/usr/bin/env sh
+${HOOK_MARKER}
+# Judges Panel pre-commit hook — evaluate staged files in a single pass.
+
+# Check if npx is available
+if ! command -v npx >/dev/null 2>&1; then
+  echo "  ⚠️  npx not found — skipping pre-commit review"
+  exit 0
+fi
+
+# Single-pass evaluation of all staged files
+npx -y @kevinrabun/judges-cli eval . --staged-only --summary --fail-on-findings
+EXIT_CODE=$?
+
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo ""
+  echo "  ⛔ Judges found critical issues. Commit blocked."
+  echo "  Run 'npx -y @kevinrabun/judges-cli eval . --staged-only' to see details."
+  echo "  Run 'npx -y @kevinrabun/judges-cli fix <file> --apply' to auto-fix."
+  echo "  Use 'git commit --no-verify' to bypass."
+  echo ""
+  exit 1
+fi
+`;
+}
+// ─── Find Git Hooks Directory ───────────────────────────────────────────────
+function findGitHooksDir(cwd) {
+    // Check for Husky first
+    const huskyDir = join(cwd, ".husky");
+    if (existsSync(huskyDir))
+        return huskyDir;
+    // Check for .git/hooks
+    const gitHooksDir = join(cwd, ".git", "hooks");
+    if (existsSync(join(cwd, ".git")))
+        return gitHooksDir;
+    return undefined;
+}
+// ─── Main Hook Command ─────────────────────────────────────────────────────
+export function runHook(argv) {
+    const subcommand = argv[3]; // install, uninstall
+    const cwd = resolve(".");
+    if (!subcommand || subcommand === "install") {
+        installHook(cwd);
+    }
+    else if (subcommand === "uninstall") {
+        uninstallHook(cwd);
+    }
+    else {
+        console.error(`Unknown hook subcommand: ${subcommand}`);
+        console.error("Usage: judges hook install | judges hook uninstall");
+        process.exit(1);
+    }
+}
+function installHook(cwd) {
+    const hooksDir = findGitHooksDir(cwd);
+    if (!hooksDir) {
+        console.error("Error: Not a git repository (no .git directory found).");
+        console.error("Run this command from the root of a git repository.");
+        process.exit(1);
+    }
+    // Ensure hooks directory exists
+    if (!existsSync(hooksDir)) {
+        mkdirSync(hooksDir, { recursive: true });
+    }
+    const hookPath = join(hooksDir, "pre-commit");
+    if (existsSync(hookPath)) {
+        const existing = readFileSync(hookPath, "utf-8");
+        if (existing.includes(HOOK_MARKER)) {
+            console.log("\n  ℹ  Judges pre-commit hook is already installed.\n");
+            process.exit(0);
+        }
+        // Append to existing hook
+        const appended = existing.trimEnd() + "\n\n" + generateHookScript();
+        writeFileSync(hookPath, appended, "utf-8");
+        try {
+            chmodSync(hookPath, 0o755);
+        }
+        catch {
+            /* Windows */
+        }
+        console.log("\n  ✅ Judges hook appended to existing pre-commit hook.");
+        console.log(`  Location: ${hookPath}\n`);
+    }
+    else {
+        writeFileSync(hookPath, generateHookScript(), "utf-8");
+        try {
+            chmodSync(hookPath, 0o755);
+        }
+        catch {
+            /* Windows */
+        }
+        console.log("\n  ✅ Judges pre-commit hook installed.");
+        console.log(`  Location: ${hookPath}\n`);
+    }
+    console.log("  Staged files will be evaluated before each commit.");
+    console.log("  Use 'git commit --no-verify' to bypass.\n");
+    process.exit(0);
+}
+function uninstallHook(cwd) {
+    const hooksDir = findGitHooksDir(cwd);
+    if (!hooksDir) {
+        console.error("Error: Not a git repository.");
+        process.exit(1);
+    }
+    const hookPath = join(hooksDir, "pre-commit");
+    if (!existsSync(hookPath)) {
+        console.log("\n  ℹ  No pre-commit hook found. Nothing to uninstall.\n");
+        process.exit(0);
+    }
+    const content = readFileSync(hookPath, "utf-8");
+    if (!content.includes(HOOK_MARKER)) {
+        console.log("\n  ℹ  Pre-commit hook exists but was not installed by Judges.\n");
+        process.exit(0);
+    }
+    // Remove the judges block
+    const lines = content.split("\n");
+    const markerIndex = lines.findIndex((l) => l.includes(HOOK_MARKER));
+    if (markerIndex <= 1) {
+        // Entire file is the judges hook — remove it
+        unlinkSync(hookPath);
+        console.log("\n  ✅ Judges pre-commit hook removed.\n");
+    }
+    else {
+        // Remove from marker to end (judges block is at the end)
+        const cleaned = lines
+            .slice(0, markerIndex - 1)
+            .join("\n")
+            .trimEnd() + "\n";
+        writeFileSync(hookPath, cleaned, "utf-8");
+        console.log("\n  ✅ Judges section removed from pre-commit hook.\n");
+    }
+    process.exit(0);
+}

package/dist/commands/iac-lint.d.ts

@@ -0,0 +1,7 @@
+/**
+ * IaC lint — dedicated linting for Dockerfiles, Kubernetes
+ * manifests, and Helm charts for security misconfigurations.
+ *
+ * All analysis local.
+ */
+export declare function runIacLint(argv: string[]): void;