@kevinrabun/judges-cli 3.124.0

package/dist/context/context-snippets.d.ts

@@ -0,0 +1,15 @@
+import { EmbeddingCache } from "./embedding-cache.js";
+export interface ContextOptions {
+    chunkSize?: number;
+    overlap?: number;
+    maxSnippets?: number;
+    embeddingCache?: EmbeddingCache;
+    embeddingSalt?: string;
+}
+/**
+ * Naive chunker for code/docs. Returns plain text chunks; embeddings computed for ranking.
+ */
+export declare function buildContextSnippets(text: string, opts?: ContextOptions): Promise<Array<{
+    snippet: string;
+    score: number;
+}>>;

package/dist/context/context-snippets.js

@@ -0,0 +1,36 @@
+import { getOrCreateEmbedding, EmbeddingCache, FallbackEmbeddingProvider } from "./embedding-cache.js";
+const DEFAULT_CHUNK_SIZE = 1200; // chars (~300 tokens)
+const DEFAULT_OVERLAP = 200;
+const DEFAULT_MAX_SNIPPETS = 5;
+/**
+ * Naive chunker for code/docs. Returns plain text chunks; embeddings computed for ranking.
+ */
+export async function buildContextSnippets(text, opts = {}) {
+    const chunkSize = opts.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    const overlap = opts.overlap ?? DEFAULT_OVERLAP;
+    const maxSnippets = opts.maxSnippets ?? DEFAULT_MAX_SNIPPETS;
+    const cache = opts.embeddingCache ?? new EmbeddingCache();
+    const provider = new FallbackEmbeddingProvider();
+    const chunks = [];
+    for (let i = 0; i < text.length; i += chunkSize - overlap) {
+        chunks.push(text.slice(i, i + chunkSize));
+    }
+    // Compute simple scores using fallback embeddings (dot product with a centroid)
+    const centroid = await getOrCreateEmbedding(cache, provider, text, opts.embeddingSalt);
+    const centroidVec = centroid.embedding;
+    const scored = [];
+    for (const c of chunks) {
+        const chunkEmbedding = await getOrCreateEmbedding(cache, provider, c, opts.embeddingSalt);
+        const score = dot(centroidVec, chunkEmbedding.embedding);
+        scored.push({ snippet: c, score });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, maxSnippets);
+}
+function dot(a, b) {
+    const len = Math.min(a.length, b.length);
+    let sum = 0;
+    for (let i = 0; i < len; i++)
+        sum += a[i] * b[i];
+    return sum;
+}

package/dist/context/embedding-cache.d.ts

@@ -0,0 +1,30 @@
+export interface EmbeddingProvider {
+    embed(text: string): Promise<number[]>;
+}
+export interface EmbeddingChunk {
+    hash: string;
+    embedding: number[];
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+/** Simple SHA1 hash for cache keys (content + salt/context). */
+export declare function hashKey(text: string, salt?: string): string;
+/**
+ * In-memory embedding cache (can be backed by disk later). Lightweight and
+ * dependency-free; callers can persist via JSON if desired.
+ */
+export declare class EmbeddingCache {
+    private cache;
+    get(key: string): EmbeddingChunk | undefined;
+    set(key: string, value: EmbeddingChunk): void;
+    clear(): void;
+}
+/**
+ * Trivial embedding provider (fallback) — returns normalized character code vector.
+ * Not semantically meaningful but keeps the pipeline working when no provider is configured.
+ */
+export declare class FallbackEmbeddingProvider implements EmbeddingProvider {
+    embed(text: string): Promise<number[]>;
+}
+/** Retrieve or compute an embedding, with caching. */
+export declare function getOrCreateEmbedding(cache: EmbeddingCache, provider: EmbeddingProvider, text: string, salt?: string): Promise<EmbeddingChunk>;

package/dist/context/embedding-cache.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+/** Simple SHA1 hash for cache keys (content + salt/context). */
+export function hashKey(text, salt) {
+    return createHash("sha1")
+        .update(text + (salt ?? ""))
+        .digest("hex");
+}
+/**
+ * In-memory embedding cache (can be backed by disk later). Lightweight and
+ * dependency-free; callers can persist via JSON if desired.
+ */
+export class EmbeddingCache {
+    cache = new Map();
+    get(key) {
+        return this.cache.get(key);
+    }
+    set(key, value) {
+        this.cache.set(key, value);
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+/**
+ * Trivial embedding provider (fallback) — returns normalized character code vector.
+ * Not semantically meaningful but keeps the pipeline working when no provider is configured.
+ */
+export class FallbackEmbeddingProvider {
+    async embed(text) {
+        const vec = new Array(32).fill(0);
+        for (let i = 0; i < text.length; i++) {
+            vec[i % vec.length] += text.charCodeAt(i);
+        }
+        const norm = Math.sqrt(vec.reduce((s, v) => s + v * v, 0)) || 1;
+        return vec.map((v) => v / norm);
+    }
+}
+/** Retrieve or compute an embedding, with caching. */
+export async function getOrCreateEmbedding(cache, provider, text, salt) {
+    const key = hashKey(text, salt);
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const embedding = await provider.embed(text);
+    const chunk = { hash: key, embedding, text };
+    cache.set(key, chunk);
+    return chunk;
+}

package/dist/data-adapter.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Pluggable Data Adapter — Storage Abstraction Layer
+ *
+ * Judges never directly holds or processes user data. Instead, this module
+ * defines a `DataAdapter` interface that abstracts all persistence operations.
+ * Users can configure their own backend by providing a custom adapter
+ * (REST API, database, cloud storage, etc.) via `.judgesrc` or programmatic
+ * registration.
+ *
+ * The default adapter (`FileSystemAdapter`) uses local `.judges-*.json` files
+ * in the project directory — no data leaves the developer's machine unless
+ * they explicitly configure an external adapter.
+ */
+import type { FeedbackStore } from "./commands/feedback.js";
+import type { FindingStore } from "./finding-lifecycle.js";
+/**
+ * Storage adapter interface. All data persistence flows through this so
+ * users can plug in their own backends (REST, DB, cloud, etc.).
+ */
+export interface DataAdapter {
+    /** Adapter name for diagnostics */
+    readonly name: string;
+    loadFeedback(projectDir: string): Promise<FeedbackStore>;
+    saveFeedback(store: FeedbackStore, projectDir: string): Promise<void>;
+    loadFindings(projectDir: string): Promise<FindingStore>;
+    saveFindings(store: FindingStore, projectDir: string): Promise<void>;
+    loadSnapshots(projectDir: string): Promise<SnapshotData>;
+    saveSnapshots(data: SnapshotData, projectDir: string): Promise<void>;
+    loadMetrics(projectDir: string): Promise<MetricsData>;
+    loadJson<T>(key: string, projectDir: string): Promise<T | undefined>;
+    saveJson<T>(key: string, data: T, projectDir: string): Promise<void>;
+}
+/** Snapshot data shape (matches SnapshotStore from snapshot.ts) */
+export interface SnapshotData {
+    version: 1;
+    snapshots: Array<{
+        timestamp: string;
+        totalFindings: number;
+        bySeverity: Record<string, number>;
+        byJudge: Record<string, number>;
+        score: number;
+        verdict: string;
+        label?: string;
+    }>;
+    metadata: {
+        createdAt: string;
+        lastUpdated: string;
+        totalRuns: number;
+    };
+}
+/** Metrics aggregate shape */
+export interface MetricsData {
+    feedbackStore?: FeedbackStore;
+    findingStore?: FindingStore;
+    snapshotData?: SnapshotData;
+}
+export declare class FileSystemAdapter implements DataAdapter {
+    readonly name = "filesystem";
+    loadFeedback(projectDir: string): Promise<FeedbackStore>;
+    saveFeedback(store: FeedbackStore, projectDir: string): Promise<void>;
+    loadFindings(projectDir: string): Promise<FindingStore>;
+    saveFindings(store: FindingStore, projectDir: string): Promise<void>;
+    loadSnapshots(projectDir: string): Promise<SnapshotData>;
+    saveSnapshots(data: SnapshotData, projectDir: string): Promise<void>;
+    loadMetrics(projectDir: string): Promise<MetricsData>;
+    loadJson<T>(key: string, projectDir: string): Promise<T | undefined>;
+    saveJson<T>(key: string, data: T, projectDir: string): Promise<void>;
+}
+/**
+ * HTTP adapter that sends data to a user-hosted REST endpoint.
+ * Users deploy their own backend — judges never processes the data itself.
+ *
+ * Configuration in .judgesrc:
+ * ```json
+ * {
+ *   "dataAdapter": {
+ *     "type": "http",
+ *     "url": "https://my-company-judges.internal/api",
+ *     "headers": { "Authorization": "Bearer ${JUDGES_API_KEY}" }
+ *   }
+ * }
+ * ```
+ */
+export declare class HttpAdapter implements DataAdapter {
+    readonly name = "http";
+    private readonly baseUrl;
+    private readonly headers;
+    constructor(config: {
+        url: string;
+        headers?: Record<string, string>;
+    });
+    loadFeedback(projectDir: string): Promise<FeedbackStore>;
+    saveFeedback(store: FeedbackStore, projectDir: string): Promise<void>;
+    loadFindings(projectDir: string): Promise<FindingStore>;
+    saveFindings(store: FindingStore, projectDir: string): Promise<void>;
+    loadSnapshots(projectDir: string): Promise<SnapshotData>;
+    saveSnapshots(data: SnapshotData, projectDir: string): Promise<void>;
+    loadMetrics(projectDir: string): Promise<MetricsData>;
+    loadJson<T>(key: string, projectDir: string): Promise<T | undefined>;
+    saveJson<T>(key: string, data: T, projectDir: string): Promise<void>;
+    private get;
+    private put;
+}
+/** Get the currently active data adapter. */
+export declare function getDataAdapter(): DataAdapter;
+/** Set the active data adapter. */
+export declare function setDataAdapter(adapter: DataAdapter): void;
+/**
+ * Create a data adapter from `.judgesrc` configuration.
+ *
+ * Config shape:
+ * ```json
+ * { "dataAdapter": { "type": "filesystem" } }     // default
+ * { "dataAdapter": { "type": "http", "url": "...", "headers": { ... } } }
+ * ```
+ */
+export declare function createAdapterFromConfig(config: DataAdapterConfig): DataAdapter;
+/** Data adapter config shape in .judgesrc */
+export interface DataAdapterConfig {
+    type: "filesystem" | "http";
+    url?: string;
+    headers?: Record<string, string>;
+}

package/dist/data-adapter.js

@@ -0,0 +1,212 @@
+/**
+ * Pluggable Data Adapter — Storage Abstraction Layer
+ *
+ * Judges never directly holds or processes user data. Instead, this module
+ * defines a `DataAdapter` interface that abstracts all persistence operations.
+ * Users can configure their own backend by providing a custom adapter
+ * (REST API, database, cloud storage, etc.) via `.judgesrc` or programmatic
+ * registration.
+ *
+ * The default adapter (`FileSystemAdapter`) uses local `.judges-*.json` files
+ * in the project directory — no data leaves the developer's machine unless
+ * they explicitly configure an external adapter.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { resolve, dirname } from "path";
+// ─── Default File System Adapter ────────────────────────────────────────────
+const DEFAULT_FILES = {
+    feedback: ".judges-feedback.json",
+    findings: ".judges-findings.json",
+    snapshots: ".judges-snapshots.json",
+};
+export class FileSystemAdapter {
+    name = "filesystem";
+    async loadFeedback(projectDir) {
+        return loadJsonFile(resolve(projectDir, DEFAULT_FILES.feedback)) ?? createEmptyFeedbackStore();
+    }
+    async saveFeedback(store, projectDir) {
+        store.metadata.lastUpdated = new Date().toISOString();
+        saveJsonFile(resolve(projectDir, DEFAULT_FILES.feedback), store);
+    }
+    async loadFindings(projectDir) {
+        return (loadJsonFile(resolve(projectDir, DEFAULT_FILES.findings)) ?? {
+            version: "1.0.0",
+            lastRunAt: new Date().toISOString(),
+            runNumber: 0,
+            findings: [],
+        });
+    }
+    async saveFindings(store, projectDir) {
+        saveJsonFile(resolve(projectDir, DEFAULT_FILES.findings), store);
+    }
+    async loadSnapshots(projectDir) {
+        return loadJsonFile(resolve(projectDir, DEFAULT_FILES.snapshots)) ?? createEmptySnapshotData();
+    }
+    async saveSnapshots(data, projectDir) {
+        data.metadata.lastUpdated = new Date().toISOString();
+        saveJsonFile(resolve(projectDir, DEFAULT_FILES.snapshots), data);
+    }
+    async loadMetrics(projectDir) {
+        const [feedbackStore, findingStore, snapshotData] = await Promise.all([
+            this.loadFeedback(projectDir),
+            this.loadFindings(projectDir),
+            this.loadSnapshots(projectDir),
+        ]);
+        return { feedbackStore, findingStore, snapshotData };
+    }
+    async loadJson(key, projectDir) {
+        return loadJsonFile(resolve(projectDir, `.judges-${key}.json`));
+    }
+    async saveJson(key, data, projectDir) {
+        saveJsonFile(resolve(projectDir, `.judges-${key}.json`), data);
+    }
+}
+// ─── HTTP Adapter (user-hosted backend) ─────────────────────────────────────
+/**
+ * HTTP adapter that sends data to a user-hosted REST endpoint.
+ * Users deploy their own backend — judges never processes the data itself.
+ *
+ * Configuration in .judgesrc:
+ * ```json
+ * {
+ *   "dataAdapter": {
+ *     "type": "http",
+ *     "url": "https://my-company-judges.internal/api",
+ *     "headers": { "Authorization": "Bearer ${JUDGES_API_KEY}" }
+ *   }
+ * }
+ * ```
+ */
+export class HttpAdapter {
+    name = "http";
+    baseUrl;
+    headers;
+    constructor(config) {
+        this.baseUrl = config.url.replace(/\/+$/, "");
+        this.headers = { "Content-Type": "application/json", ...config.headers };
+    }
+    async loadFeedback(projectDir) {
+        return ((await this.get(`/feedback?project=${encodeURIComponent(projectDir)}`)) ??
+            createEmptyFeedbackStore());
+    }
+    async saveFeedback(store, projectDir) {
+        await this.put(`/feedback?project=${encodeURIComponent(projectDir)}`, store);
+    }
+    async loadFindings(projectDir) {
+        return ((await this.get(`/findings?project=${encodeURIComponent(projectDir)}`)) ?? {
+            version: "1.0.0",
+            lastRunAt: new Date().toISOString(),
+            runNumber: 0,
+            findings: [],
+        });
+    }
+    async saveFindings(store, projectDir) {
+        await this.put(`/findings?project=${encodeURIComponent(projectDir)}`, store);
+    }
+    async loadSnapshots(projectDir) {
+        return ((await this.get(`/snapshots?project=${encodeURIComponent(projectDir)}`)) ??
+            createEmptySnapshotData());
+    }
+    async saveSnapshots(data, projectDir) {
+        await this.put(`/snapshots?project=${encodeURIComponent(projectDir)}`, data);
+    }
+    async loadMetrics(projectDir) {
+        return (await this.get(`/metrics?project=${encodeURIComponent(projectDir)}`)) ?? {};
+    }
+    async loadJson(key, projectDir) {
+        return this.get(`/data/${encodeURIComponent(key)}?project=${encodeURIComponent(projectDir)}`);
+    }
+    async saveJson(key, data, projectDir) {
+        await this.put(`/data/${encodeURIComponent(key)}?project=${encodeURIComponent(projectDir)}`, data);
+    }
+    async get(path) {
+        try {
+            const resp = await fetch(`${this.baseUrl}${path}`, { headers: this.headers });
+            if (!resp.ok)
+                return undefined;
+            return (await resp.json());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async put(path, data) {
+        await fetch(`${this.baseUrl}${path}`, {
+            method: "PUT",
+            headers: this.headers,
+            body: JSON.stringify(data),
+        });
+    }
+}
+// ─── Adapter Registry ───────────────────────────────────────────────────────
+let activeAdapter = new FileSystemAdapter();
+/** Get the currently active data adapter. */
+export function getDataAdapter() {
+    return activeAdapter;
+}
+/** Set the active data adapter. */
+export function setDataAdapter(adapter) {
+    activeAdapter = adapter;
+}
+/**
+ * Create a data adapter from `.judgesrc` configuration.
+ *
+ * Config shape:
+ * ```json
+ * { "dataAdapter": { "type": "filesystem" } }     // default
+ * { "dataAdapter": { "type": "http", "url": "...", "headers": { ... } } }
+ * ```
+ */
+export function createAdapterFromConfig(config) {
+    switch (config.type) {
+        case "http":
+            if (!config.url)
+                throw new Error("HTTP data adapter requires 'url' in dataAdapter config");
+            return new HttpAdapter({
+                url: resolveEnvVars(config.url),
+                headers: config.headers
+                    ? Object.fromEntries(Object.entries(config.headers).map(([k, v]) => [k, resolveEnvVars(v)]))
+                    : undefined,
+            });
+        case "filesystem":
+        default:
+            return new FileSystemAdapter();
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function loadJsonFile(filePath) {
+    if (!existsSync(filePath))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function saveJsonFile(filePath, data) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+function createEmptyFeedbackStore() {
+    const now = new Date().toISOString();
+    return {
+        version: 1,
+        entries: [],
+        metadata: { createdAt: now, lastUpdated: now, totalSubmissions: 0 },
+    };
+}
+function createEmptySnapshotData() {
+    const now = new Date().toISOString();
+    return {
+        version: 1,
+        snapshots: [],
+        metadata: { createdAt: now, lastUpdated: now, totalRuns: 0 },
+    };
+}
+/** Resolve `${ENV_VAR}` patterns in config strings. */
+function resolveEnvVars(str) {
+    return str.replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "");
+}

package/dist/dedup.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Cross-Evaluator Deduplication
+ *
+ * Extracted from the evaluators monolith. Uses union-find to cluster findings
+ * from different evaluators that flag the same line(s) for the same root cause,
+ * keeping the highest-severity instance and annotating cross-references.
+ *
+ * Also provides cross-file deduplication for project-level analysis, merging
+ * identical-topic findings across different files into single consolidated entries.
+ */
+import type { Finding, Severity } from "./types.js";
+export declare function severityRank(severity: Severity): number;
+/**
+ * Deduplicate findings across evaluators. When different judges flag the same
+ * line(s) for the same root cause, keeps the highest-severity instance and
+ * annotates it with cross-references to the other rule IDs.
+ *
+ * Uses union-find to cluster findings that share any (topic, lineNumber) pair,
+ * then picks the best finding from each cluster.
+ */
+export declare function crossEvaluatorDedup(findings: Finding[]): Finding[];
+/**
+ * Deduplicate non-absence findings across files in project-level analysis.
+ *
+ * When the same concrete issue (e.g., sql-injection, xss, hardcoded-secret) is
+ * identified with the SAME rule ID in multiple files, the finding is likely a
+ * repeated pattern rather than independent vulnerabilities. This function
+ * consolidates those into a single representative finding annotated with the
+ * list of affected files and combined line counts.
+ *
+ * Only groups findings that share BOTH a known topic AND the same ruleId.
+ * Findings with fallback topics (no known-pattern match) are left as-is since
+ * fallback topic collisions are unreliable.
+ *
+ * @param fileFindings Array of per-file findings with their source file paths
+ * @returns Deduplicated findings with file-count annotations
+ */
+export declare function crossFileDedup(fileFindings: Array<{
+    path: string;
+    findings: Finding[];
+}>): Finding[];
+/**
+ * Diff result comparing two sets of findings.
+ */
+export interface FindingDiff {
+    /** Findings present in current but not in previous (new issues) */
+    newFindings: Finding[];
+    /** Findings present in previous but not in current (resolved) */
+    fixedFindings: Finding[];
+    /** Findings present in both runs */
+    recurringFindings: Finding[];
+    /** Summary statistics */
+    stats: {
+        totalPrevious: number;
+        totalCurrent: number;
+        newCount: number;
+        fixedCount: number;
+        recurringCount: number;
+        /** Net change: positive means more findings, negative means fewer */
+        delta: number;
+    };
+}
+/**
+ * Compare two sets of findings to identify new, fixed, and recurring issues.
+ * Useful for tracking regression between evaluation runs.
+ *
+ * @param previous  - Findings from the previous run
+ * @param current   - Findings from the current run
+ * @param filePath  - Optional file path context (used when findings lack filePath)
+ * @returns Diff with new, fixed, and recurring findings plus stats
+ */
+export declare function diffFindings(previous: Finding[], current: Finding[], filePath?: string): FindingDiff;
+/**
+ * Format a finding diff as human-readable text.
+ */
+export declare function formatFindingDiff(diff: FindingDiff): string;
+export interface NetChangeGateOptions {
+    /** Pass if this PR fixed at least this many more findings than it introduced. Defaults to 0 (break-even). */
+    minNetFixed?: number;
+    /** When true, new critical/high findings cause failure regardless of net change. Defaults to true. */
+    blockOnNewHighSeverity?: boolean;
+}
+export interface NetChangeGateResult {
+    /** Whether the gate passed: the PR's net impact is positive */
+    passed: boolean;
+    /** Net findings resolved (positive = net improvement, negative = net regression) */
+    netFixed: number;
+    /** Number of new findings introduced */
+    introduced: number;
+    /** Number of existing findings resolved */
+    resolved: number;
+    /** New critical/high findings that caused a block (if blockOnNewHighSeverity) */
+    blockers: Finding[];
+    /** Human-readable summary */
+    summary: string;
+}
+/**
+ * Evaluate whether a PR's net change is positive — i.e., it fixed more
+ * findings than it introduced. Designed for CI pipelines where teams want to
+ * enforce a "leave the codebase better than you found it" policy.
+ *
+ * @param diff - The FindingDiff from comparing baseline vs current findings
+ * @param options - Gate configuration
+ */
+export declare function evaluateNetChangeGate(diff: FindingDiff, options?: NetChangeGateOptions): NetChangeGateResult;