@kevinrabun/judges 3.115.0 → 3.115.2

package/dist/commands/kb.js

@@ -0,0 +1,228 @@
+/**
+ * Team knowledge base — store team decisions about rules, exceptions,
+ * known patterns, and contextual knowledge that informs evaluations.
+ *
+ * Stored locally in .judges-kb.json.
+ */
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { userInfo } from "os";
+const KB_FILE = ".judges-kb.json";
+// ─── Core ───────────────────────────────────────────────────────────────────
+function loadDb(file = KB_FILE) {
+    if (!existsSync(file))
+        return { entries: [] };
+    return JSON.parse(readFileSync(file, "utf-8"));
+}
+function saveDb(db, file = KB_FILE) {
+    writeFileSync(file, JSON.stringify(db, null, 2));
+}
+function genId() {
+    return `kb-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+export function addKbEntry(opts) {
+    const db = loadDb();
+    const entry = {
+        id: genId(),
+        rulePattern: opts.rulePattern,
+        decision: opts.decision,
+        reason: opts.reason,
+        approvedBy: opts.approvedBy,
+        createdIso: new Date().toISOString(),
+        scope: opts.scope,
+        tags: opts.tags,
+        active: true,
+    };
+    if (opts.expiresIn) {
+        const exp = new Date();
+        exp.setDate(exp.getDate() + opts.expiresIn);
+        entry.expiresIso = exp.toISOString();
+    }
+    db.entries.push(entry);
+    saveDb(db);
+    return entry;
+}
+export function archiveKbEntry(id) {
+    const db = loadDb();
+    const entry = db.entries.find((e) => e.id === id);
+    if (!entry)
+        return false;
+    entry.active = false;
+    saveDb(db);
+    return true;
+}
+export function searchKb(query) {
+    const db = loadDb();
+    const q = query.toLowerCase();
+    return db.entries.filter((e) => e.active &&
+        (e.rulePattern.toLowerCase().includes(q) ||
+            e.reason.toLowerCase().includes(q) ||
+            e.decision.includes(q) ||
+            e.tags?.some((t) => t.toLowerCase().includes(q))));
+}
+export function getApplicableEntries(ruleId) {
+    const db = loadDb();
+    const now = Date.now();
+    return db.entries.filter((e) => {
+        if (!e.active)
+            return false;
+        if (e.expiresIso && new Date(e.expiresIso).getTime() < now)
+            return false;
+        return ruleId === e.rulePattern || ruleId.startsWith(e.rulePattern);
+    });
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runKnowledgeBase(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges kb — Team knowledge base for rule decisions and exceptions
+
+Usage:
+  judges kb --add --rule AUTH-003 --decision not-applicable --reason "Stateless microservices" --approved-by "Team Lead"
+  judges kb --search AUTH               Search knowledge base
+  judges kb --check SEC-001             Check if rule has KB entries
+  judges kb --list                      List all active entries
+  judges kb --archive <id>              Archive an entry
+  judges kb --stats                     Show KB statistics
+
+Options:
+  --add                 Add new KB entry
+  --rule <pattern>      Rule ID or prefix
+  --decision <type>     not-applicable | accepted-risk | deferred | exception | custom-guidance
+  --reason <text>       Reason for decision
+  --approved-by <name>  Who approved
+  --scope <glob>        File scope
+  --tags <list>         Comma-separated tags
+  --expires-in <days>   Auto-expire after N days
+  --search <query>      Search KB
+  --check <rule-id>     Check for KB entries on a rule
+  --list                List all active entries
+  --archive <id>        Archive an entry
+  --stats               Show statistics
+  --format json         JSON output
+  --help, -h            Show this help
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    // Add entry
+    if (argv.includes("--add")) {
+        const rulePattern = argv.find((_a, i) => argv[i - 1] === "--rule");
+        const decision = argv.find((_a, i) => argv[i - 1] === "--decision");
+        const reason = argv.find((_a, i) => argv[i - 1] === "--reason");
+        const approvedBy = argv.find((_a, i) => argv[i - 1] === "--approved-by") || userInfo().username || "unknown";
+        const scope = argv.find((_a, i) => argv[i - 1] === "--scope");
+        const tagsStr = argv.find((_a, i) => argv[i - 1] === "--tags");
+        const expiresStr = argv.find((_a, i) => argv[i - 1] === "--expires-in");
+        if (!rulePattern || !decision || !reason) {
+            console.error("Error: --rule, --decision, and --reason required");
+            process.exit(1);
+        }
+        const entry = addKbEntry({
+            rulePattern,
+            decision,
+            reason,
+            approvedBy,
+            scope,
+            tags: tagsStr ? tagsStr.split(",").map((s) => s.trim()) : undefined,
+            expiresIn: expiresStr ? parseInt(expiresStr, 10) : undefined,
+        });
+        if (format === "json") {
+            console.log(JSON.stringify(entry, null, 2));
+        }
+        else {
+            console.log(`  ✅ KB entry created: ${entry.id}`);
+            console.log(`     ${entry.rulePattern}: ${entry.decision} — ${entry.reason}`);
+        }
+        return;
+    }
+    // Search
+    const searchQuery = argv.find((_a, i) => argv[i - 1] === "--search");
+    if (searchQuery) {
+        const results = searchKb(searchQuery);
+        if (format === "json") {
+            console.log(JSON.stringify(results, null, 2));
+        }
+        else if (results.length === 0) {
+            console.log(`\n  No KB entries matching "${searchQuery}".\n`);
+        }
+        else {
+            console.log(`\n  ${results.length} KB entry(ies) matching "${searchQuery}"\n  ──────────────────`);
+            for (const e of results) {
+                console.log(`    ${e.rulePattern.padEnd(15)} ${e.decision.padEnd(18)} ${e.reason}`);
+                console.log(`      Approved by ${e.approvedBy} on ${e.createdIso.split("T")[0]}`);
+            }
+            console.log("");
+        }
+        return;
+    }
+    // Check specific rule
+    const checkRule = argv.find((_a, i) => argv[i - 1] === "--check");
+    if (checkRule) {
+        const entries = getApplicableEntries(checkRule);
+        if (format === "json") {
+            console.log(JSON.stringify(entries, null, 2));
+        }
+        else if (entries.length === 0) {
+            console.log(`\n  No KB entries for ${checkRule}.\n`);
+        }
+        else {
+            console.log(`\n  KB entries for ${checkRule}:`);
+            for (const e of entries) {
+                console.log(`    ${e.decision}: ${e.reason} (${e.approvedBy})`);
+            }
+            console.log("");
+        }
+        return;
+    }
+    // Archive
+    const archiveId = argv.find((_a, i) => argv[i - 1] === "--archive");
+    if (archiveId) {
+        if (archiveKbEntry(archiveId)) {
+            console.log(`  Archived: ${archiveId}`);
+        }
+        else {
+            console.error(`  Not found: ${archiveId}`);
+        }
+        return;
+    }
+    // Stats
+    if (argv.includes("--stats")) {
+        const db = loadDb();
+        const active = db.entries.filter((e) => e.active);
+        const byDecision = {};
+        for (const e of active) {
+            byDecision[e.decision] = (byDecision[e.decision] || 0) + 1;
+        }
+        if (format === "json") {
+            console.log(JSON.stringify({ total: db.entries.length, active: active.length, byDecision }, null, 2));
+        }
+        else {
+            console.log(`\n  Knowledge Base\n  ──────────────`);
+            console.log(`  Total: ${db.entries.length} (${active.length} active)\n`);
+            for (const [d, c] of Object.entries(byDecision)) {
+                console.log(`    ${d.padEnd(20)} ${c}`);
+            }
+            console.log("");
+        }
+        return;
+    }
+    // Default: list all
+    const db = loadDb();
+    const active = db.entries.filter((e) => e.active);
+    if (active.length === 0) {
+        console.log("\n  Knowledge base is empty. Use --add to create an entry.\n");
+        return;
+    }
+    if (format === "json") {
+        console.log(JSON.stringify(active, null, 2));
+    }
+    else {
+        console.log(`\n  Team Knowledge Base (${active.length} active)\n  ──────────────────────`);
+        for (const e of active) {
+            const exp = e.expiresIso ? ` (expires ${e.expiresIso.split("T")[0]})` : "";
+            console.log(`    ${e.id}  ${e.rulePattern.padEnd(15)} ${e.decision}${exp}`);
+            console.log(`      ${e.reason} — ${e.approvedBy}`);
+        }
+        console.log("");
+    }
+}

package/dist/commands/learn.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Developer learning path — personalized, structured learning
+ * based on a developer's finding history.
+ *
+ * Uses .judges-scores/ and .judges-learn/ for progress.
+ */
+interface LearningModule {
+    id: string;
+    title: string;
+    category: string;
+    difficulty: "beginner" | "intermediate" | "advanced";
+    concepts: string[];
+    exercises: string[];
+    completed: boolean;
+    completedAt?: string;
+}
+interface LearningPath {
+    author: string;
+    modules: LearningModule[];
+    progress: number;
+    streak: number;
+    lastActivity: string;
+}
+export declare function completeModule(author: string, moduleId: string): LearningPath;
+export declare function runLearn(argv: string[]): void;
+export {};

package/dist/commands/learn.js

@@ -0,0 +1,288 @@
+/**
+ * Developer learning path — personalized, structured learning
+ * based on a developer's finding history.
+ *
+ * Uses .judges-scores/ and .judges-learn/ for progress.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+const LEARN_DIR = ".judges-learn";
+// ─── Module library ─────────────────────────────────────────────────────────
+const MODULE_LIBRARY = [
+    {
+        id: "sec-input-validation",
+        title: "Input Validation Fundamentals",
+        category: "SEC",
+        difficulty: "beginner",
+        concepts: [
+            "All user input is untrusted",
+            "Validate on the server side, not just client",
+            "Use allowlists over denylists",
+            "Sanitize before use, not after",
+        ],
+        exercises: [
+            "Write a function that validates email format using regex",
+            "Create a middleware that rejects requests with unexpected Content-Type",
+            "Implement parameter validation for a REST API endpoint",
+        ],
+    },
+    {
+        id: "sec-injection-prevention",
+        title: "Injection Attack Prevention",
+        category: "INJECT",
+        difficulty: "intermediate",
+        concepts: [
+            "Parameterized queries prevent SQL injection",
+            "Template literals in queries are dangerous",
+            "Context-aware output encoding for XSS",
+            "Command injection via child_process",
+        ],
+        exercises: [
+            "Refactor a string-concatenation query to use parameterized queries",
+            "Identify injection vectors in a sample Express handler",
+            "Write a safe exec() wrapper with argument allowlisting",
+        ],
+    },
+    {
+        id: "auth-session-management",
+        title: "Authentication & Session Management",
+        category: "AUTH",
+        difficulty: "intermediate",
+        concepts: [
+            "Never store passwords in plaintext",
+            "Use bcrypt/argon2 with proper salt rounds",
+            "Session tokens must be cryptographically random",
+            "Implement token rotation and expiry",
+        ],
+        exercises: [
+            "Implement password hashing with bcrypt",
+            "Create a session management module with expiry",
+            "Build a JWT refresh token rotation flow",
+        ],
+    },
+    {
+        id: "crypto-fundamentals",
+        title: "Cryptography Best Practices",
+        category: "CRYPTO",
+        difficulty: "advanced",
+        concepts: [
+            "AES-256-GCM for symmetric encryption",
+            "RSA-2048+ or ECDSA for asymmetric",
+            "Never reuse IVs/nonces",
+            "Key derivation with PBKDF2 or scrypt",
+        ],
+        exercises: [
+            "Replace MD5 hash with SHA-256 in a codebase",
+            "Implement AES-256-GCM encryption/decryption",
+            "Create a key rotation mechanism",
+        ],
+    },
+    {
+        id: "error-handling",
+        title: "Error Handling & Information Leakage",
+        category: "ERR",
+        difficulty: "beginner",
+        concepts: [
+            "Never expose stack traces to users",
+            "Log errors server-side with context",
+            "Use error boundaries in frontend code",
+            "Return safe, generic error messages",
+        ],
+        exercises: [
+            "Implement a centralized error handler with safe responses",
+            "Add structured logging to an existing error flow",
+            "Create error boundaries for a React component tree",
+        ],
+    },
+    {
+        id: "perf-database",
+        title: "Database Performance Patterns",
+        category: "PERF",
+        difficulty: "intermediate",
+        concepts: [
+            "N+1 queries waste resources",
+            "Use eager loading or batch queries",
+            "Index frequently queried columns",
+            "Paginate large result sets",
+        ],
+        exercises: [
+            "Identify and fix N+1 queries in an ORM-based app",
+            "Add pagination to an API endpoint",
+            "Profile and add missing database indexes",
+        ],
+    },
+    {
+        id: "ssrf-prevention",
+        title: "Server-Side Request Forgery Prevention",
+        category: "SSRF",
+        difficulty: "advanced",
+        concepts: [
+            "Validate and restrict outbound URLs",
+            "Block requests to internal/private IP ranges",
+            "Use URL allowlists for external integrations",
+            "DNS rebinding attacks bypass naive checks",
+        ],
+        exercises: [
+            "Implement URL validation with private IP blocking",
+            "Create an HTTP client wrapper with domain allowlisting",
+            "Write tests for SSRF edge cases (DNS rebinding, redirects)",
+        ],
+    },
+    {
+        id: "secure-config",
+        title: "Secure Configuration Management",
+        category: "SEC",
+        difficulty: "beginner",
+        concepts: [
+            "Never commit secrets to version control",
+            "Use environment variables for configuration",
+            "Principle of least privilege for service accounts",
+            "Review default configurations for security",
+        ],
+        exercises: [
+            "Set up dotenv with proper .gitignore rules",
+            "Audit a project for hardcoded credentials",
+            "Create a secrets management checklist",
+        ],
+    },
+];
+// ─── Core ───────────────────────────────────────────────────────────────────
+function ensureDir() {
+    if (!existsSync(LEARN_DIR))
+        mkdirSync(LEARN_DIR, { recursive: true });
+}
+function sanitizeFilename(author) {
+    return author.replace(/[^a-zA-Z0-9._-]/g, "_").toLowerCase();
+}
+function loadPath(author) {
+    ensureDir();
+    const file = join(LEARN_DIR, `${sanitizeFilename(author)}.json`);
+    if (!existsSync(file)) {
+        return {
+            author,
+            modules: MODULE_LIBRARY.map((m) => ({ ...m, completed: false })),
+            progress: 0,
+            streak: 0,
+            lastActivity: new Date().toISOString(),
+        };
+    }
+    return JSON.parse(readFileSync(file, "utf-8"));
+}
+function savePath(path) {
+    ensureDir();
+    const file = join(LEARN_DIR, `${sanitizeFilename(path.author)}.json`);
+    writeFileSync(file, JSON.stringify(path, null, 2));
+}
+export function completeModule(author, moduleId) {
+    const path = loadPath(author);
+    const mod = path.modules.find((m) => m.id === moduleId);
+    if (mod && !mod.completed) {
+        mod.completed = true;
+        mod.completedAt = new Date().toISOString();
+        path.streak++;
+    }
+    path.progress = Math.round((path.modules.filter((m) => m.completed).length / path.modules.length) * 100);
+    path.lastActivity = new Date().toISOString();
+    savePath(path);
+    return path;
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runLearn(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges learn — Personalized developer learning paths
+
+Usage:
+  judges learn --author "jane@company.com"
+  judges learn --author "jane@company.com" --module sec-input-validation
+  judges learn --author "jane@company.com" --complete sec-input-validation
+  judges learn --catalog
+
+Options:
+  --author <email>       Developer email/identifier
+  --module <id>          Show a specific module
+  --complete <id>        Mark a module as completed
+  --catalog              Show full module catalog
+  --format json          JSON output
+  --help, -h             Show this help
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    // Catalog
+    if (argv.includes("--catalog")) {
+        if (format === "json") {
+            console.log(JSON.stringify(MODULE_LIBRARY, null, 2));
+        }
+        else {
+            console.log(`\n  Learning Module Catalog (${MODULE_LIBRARY.length})\n  ──────────────────────────`);
+            for (const m of MODULE_LIBRARY) {
+                console.log(`    [${m.difficulty.padEnd(12)}] ${m.id.padEnd(25)} ${m.title}`);
+            }
+            console.log("");
+        }
+        return;
+    }
+    const author = argv.find((_a, i) => argv[i - 1] === "--author");
+    if (!author) {
+        console.error("  Use --author <email> or --catalog. --help for usage.");
+        return;
+    }
+    // Complete module
+    const completeId = argv.find((_a, i) => argv[i - 1] === "--complete");
+    if (completeId) {
+        const path = completeModule(author, completeId);
+        const mod = path.modules.find((m) => m.id === completeId);
+        if (!mod) {
+            console.error(`  ❌ Module not found: ${completeId}`);
+            return;
+        }
+        console.log(`  ✅ Completed: ${mod.title}`);
+        console.log(`     Progress: ${path.progress}% (${path.modules.filter((m) => m.completed).length}/${path.modules.length})`);
+        return;
+    }
+    // Show specific module
+    const moduleId = argv.find((_a, i) => argv[i - 1] === "--module");
+    if (moduleId) {
+        const mod = MODULE_LIBRARY.find((m) => m.id === moduleId);
+        if (!mod) {
+            console.error(`  ❌ Module not found: ${moduleId}`);
+            return;
+        }
+        if (format === "json") {
+            console.log(JSON.stringify(mod, null, 2));
+        }
+        else {
+            console.log(`\n  Module: ${mod.title}`);
+            console.log(`  Category: ${mod.category} | Difficulty: ${mod.difficulty}`);
+            console.log(`  ──────────────────────────────`);
+            console.log("\n  Concepts:");
+            for (const c of mod.concepts)
+                console.log(`    • ${c}`);
+            console.log("\n  Exercises:");
+            mod.exercises.forEach((e, i) => console.log(`    ${i + 1}. ${e}`));
+            console.log("");
+        }
+        return;
+    }
+    // Show learning path
+    const path = loadPath(author);
+    if (format === "json") {
+        console.log(JSON.stringify(path, null, 2));
+    }
+    else {
+        console.log(`\n  Learning Path — ${author}`);
+        console.log(`  Progress: ${path.progress}% | Streak: ${path.streak} modules`);
+        console.log(`  ──────────────────────────────`);
+        for (const m of path.modules) {
+            const icon = m.completed ? "✅" : "⬜";
+            console.log(`    ${icon} [${m.difficulty.padEnd(12)}] ${m.id.padEnd(25)} ${m.title}`);
+        }
+        const next = path.modules.find((m) => !m.completed);
+        if (next) {
+            console.log(`\n  Next up: ${next.title} (${next.difficulty})`);
+            console.log(`  Run: judges learn --author "${author}" --module ${next.id}`);
+        }
+        console.log("");
+    }
+}

package/dist/commands/learning-path.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Learning path — generates personalized developer learning
+ * modules from recurring finding patterns, tracking skill
+ * progression over time.
+ *
+ * All data stored locally.
+ */
+export declare function runLearningPath(argv: string[]): void;