@kevinrabun/judges 3.21.0 → 3.22.1

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to **@kevinrabun/judges** are documented here.
 
+## [3.22.1] — 2026-03-04
+
+### Fixed
+- **JSON Schema test for preset composability** — Updated `judgesrc.schema.json` test to reflect intentional removal of preset `enum` constraint (now free-form string for comma-separated preset composition); fixes CI failure on Node 20 + 22 matrix
+
+### Tests
+- 1006 tests passing (0 failures)
+
+## [3.22.0] — 2026-03-04
+
+### Added — P0: Trust & Accuracy Foundation
+- **V2 prefix mapping completeness** — Added 4 missing rule prefix mappings (`RES`, `SEC`, `IAC`, `AIGEN`) to `mapSpecialty()` and `mapJudgeIdFromRule()` in v2.ts, ensuring all 37 judges route correctly in V2 policy profiles
+- **Cross-file deduplication** — New `crossFileDedup()` function in dedup.ts detects project-wide duplicate findings across files using topic patterns, severity matching, and configurable tightness; integrated into project.ts evaluation pipeline
+- **Benchmark expansion** — Expanded benchmark suite from 17 to ~47 test cases covering all major vulnerability categories with balanced true-positive / false-positive samples; version now auto-read from package.json
+- **Test coverage expansion** — 481 subsystem tests (up from ~400), covering scoring, dedup, config, CLI, presets, benchmark gate, cascading config, CSV formatter, and streaming API
+
+### Added — P1: Developer Experience & Adoption
+- **CLI `--exclude` / `--include` / `--maxFiles` flags** — File filtering via glob patterns and file-count limits; integrated into `action.yml` inputs and `.judgesrc` schema; `globToRegex()`, `matchesGlob()`, `collectFiles()` utilities
+- **Preset composability** — `composePresets()` merges multiple presets with intersection for disabledJudges, union for disabledRules, and most-permissive minSeverity; CLI accepts comma-separated `--preset security,quick`
+- **API reference & plugin guide** — New `docs/api-reference.md` (comprehensive API surface) and `docs/plugin-guide.md` (custom evaluator/formatter development guide)
+
+### Added — P2: Depth & Precision
+- **Confidence tuning** — Enhanced `estimateFindingConfidence` with provenance-based boosts (AST +0.15, taint-flow +0.18, regex +0.08), domain-severity alignment (+0.04 for security-critical), and 3-tier noise caps: Tier 1 subjective judges (COMP/ETHICS/SOV/COST/DOC → 0.82), Tier 2 context-dependent (API/CONC/DB/DEPS/LOGPRIV/OBS/PERF → 0.88), Tier 3 mechanical (CACHE/CFG/COMPAT/MAINT/SWDEV/TEST → 0.92)
+- **Dedup topic expansion** — Expanded `DEDUP_TOPIC_PATTERNS` from ~27 to ~52 patterns adding auth/session, concurrency, database, logging/privacy, config/infra, dependency, resource management, and error handling domains
+- **VS Code extension depth** — 4 new settings: `judges.exclude`, `judges.include`, `judges.maxFiles`, `judges.confidenceTier` (essential/important/supplementary); confidence tier filtering in diagnostics and workspace reviews; configurable workspace eval limits
+- **CI benchmark gate** — `--gate` CLI flag with `--min-f1`, `--min-precision`, `--min-recall`, `--min-detection-rate`, `--baseline` options; `benchmarkGate()` API function with regression detection (1% tolerance); `BenchmarkGateOptions` / `BenchmarkGateResult` types
+
+### Added — P3: Ecosystem & Integration
+- **Cascading config** — Directory-level `.judgesrc` override support: `discoverCascadingConfigs()` walks up from file to project root finding configs, `mergeConfigs()` unions arrays and deep-merges ruleOverrides, `loadCascadingConfig()` convenience wrapper; enables monorepo per-package configuration
+- **Streaming / async API** — `evaluateFilesStream()` async generator yields results per file for progress UIs; `evaluateFilesBatch()` with bounded concurrency (default 4 workers) and `onProgress` callback; new `FileInput` / `FileEvaluationResult` types
+- **MCP tool expansion** — 3 new MCP tools (13 → 16 total): `benchmark_gate` (run benchmark with quality thresholds), `compare_benchmarks` (diff two benchmark runs), `evaluate_batch` (evaluate multiple files in one call with per-file results table)
+- **CSV formatter** — New `src/formatters/csv.ts` with `verdictToCsvRows()`, `verdictsToCsv()`, `findingsToCsv()` for spreadsheet / data-pipeline ingestion; header: `file,ruleId,severity,confidence,title,lines,reference`
+
+### Changed
+- Benchmark report now reads version dynamically from package.json instead of hardcoded string
+- `evaluateWithTribunal` MCP tool handlers use correct call signature (`code, language, context?, options?`)
+
+### Tests
+- 481 subsystem tests passing (102 suites), covering all new features
+- 20 new tests for P3: cascading config merge (10), CSV formatter (5), streaming/batch API (5)
+
 ## [3.21.0] — 2026-03-05
 
 ### Added — P0: GitHub Action CI/CD

package/dist/api.d.ts

@@ -10,7 +10,7 @@
  */
 export type { Severity, Verdict, Finding, Patch, LangFamily, JudgesConfig, RuleOverride, ProjectFile, ProjectVerdict, DiffVerdict, DependencyEntry, DependencyVerdict, JudgeEvaluation, TribunalVerdict, JudgeDefinition, EvaluationContextV2, EvidenceBundleV2, SpecializedFindingV2, TribunalVerdictV2, MustFixGateOptions, MustFixGateResult, AppBuilderWorkflowResult, PlainLanguageFinding, WorkflowTask, PolicyProfile, } from "./types.js";
 export { JudgesError, ConfigError, EvaluationError, ParseError } from "./errors.js";
-export { parseConfig, defaultConfig } from "./config.js";
+export { parseConfig, defaultConfig, mergeConfigs, discoverCascadingConfigs, loadCascadingConfig } from "./config.js";
 export { JUDGES, getJudge, getJudgeSummaries } from "./judges/index.js";
 export { evaluateWithJudge, evaluateWithTribunal, evaluateProject, evaluateDiff, analyzeDependencies, enrichWithPatches, crossEvaluatorDedup, applyInlineSuppressions, runAppBuilderWorkflow, formatVerdictAsMarkdown, formatEvaluationAsMarkdown, clearEvaluationCaches, } from "./evaluators/index.js";
 export { evaluateCodeV2, evaluateProjectV2, getSupportedPolicyProfiles } from "./evaluators/v2.js";
@@ -21,6 +21,7 @@ export { LRUCache, contentHash } from "./cache.js";
 export { clearProjectCache } from "./evaluators/project.js";
 export { findingsToSarif, evaluationToSarif, verdictToSarif, validateSarifLog } from "./formatters/sarif.js";
 export type { SarifValidationError } from "./formatters/sarif.js";
+export { verdictToCsvRows, verdictsToCsv, findingsToCsv } from "./formatters/csv.js";
 export { runCli } from "./cli.js";
 export { registerPlugin, unregisterPlugin, getRegisteredPlugins, getCustomRules, getPluginJudges, evaluateCustomRules, runBeforeHooks, runAfterHooks, clearPlugins, } from "./plugins.js";
 export type { CustomRule, JudgesPlugin, PluginRegistration } from "./plugins.js";
@@ -36,6 +37,8 @@ export { findingToDiagnostic, findingsToDiagnostics, findingsToCodeActions, form
 export type { Diagnostic, DiagnosticSeverity, Position, Range, CodeAction, PublishDiagnosticsParams, } from "./formatters/diagnostics.js";
 export { compareCapabilities, formatComparisonReport, formatFullComparisonMatrix, TOOL_PROFILES, CAPABILITY_MATRIX, } from "./comparison.js";
 export type { ToolProfile, ToolCapability, ComparisonResult } from "./comparison.js";
+export { runBenchmarkSuite, benchmarkGate, formatBenchmarkReport } from "./commands/benchmark.js";
+export type { BenchmarkResult, BenchmarkGateOptions, BenchmarkGateResult } from "./commands/benchmark.js";
 export { getLanguagePack, listLanguagePacks, suggestPack, LANGUAGE_PACKS } from "./commands/language-packs.js";
 export { formatSmartOutput, formatSmartSingleJudge } from "./commands/smart-output.js";
 export type { SmartOutputOptions } from "./commands/smart-output.js";
@@ -62,4 +65,42 @@ export declare function evaluateCode(code: string, language: string, options?: E
 export declare function evaluateCodeSingleJudge(judgeId: string, code: string, language: string, options?: EvaluationOptions): JudgeEvaluation;
 export { filterFalsePositiveHeuristics } from "./evaluators/false-positive-review.js";
 export type { FpFilterResult } from "./evaluators/false-positive-review.js";
+export interface FileInput {
+    /** Relative or absolute file path */
+    path: string;
+    /** Source code content */
+    code: string;
+    /** Programming language */
+    language: string;
+}
+export interface FileEvaluationResult {
+    /** File path that was evaluated */
+    path: string;
+    /** Tribunal verdict for this file */
+    verdict: TribunalVerdict;
+    /** Index in the input sequence */
+    index: number;
+}
+/**
+ * Async generator that evaluates files one at a time, yielding results
+ * as they complete. Useful for progress reporting and streaming UIs.
+ *
+ * @example
+ * ```ts
+ * for await (const result of evaluateFilesStream(files)) {
+ *   console.log(`${result.path}: ${result.verdict.overallScore}/100`);
+ * }
+ * ```
+ */
+export declare function evaluateFilesStream(files: FileInput[], options?: EvaluationOptions): AsyncGenerator<FileEvaluationResult>;
+/**
+ * Evaluate multiple files in parallel with bounded concurrency.
+ * Returns results in the order files were provided.
+ *
+ * @param files       - Array of file inputs to evaluate
+ * @param concurrency - Maximum parallel evaluations (default: 4)
+ * @param options     - Evaluation options
+ * @param onProgress  - Optional callback for progress reporting
+ */
+export declare function evaluateFilesBatch(files: FileInput[], concurrency?: number, options?: EvaluationOptions, onProgress?: (completed: number, total: number) => void): Promise<FileEvaluationResult[]>;
 //# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -11,7 +11,7 @@
 // ─── Errors ──────────────────────────────────────────────────────────────────
 export { JudgesError, ConfigError, EvaluationError, ParseError } from "./errors.js";
 // ─── Config ──────────────────────────────────────────────────────────────────
-export { parseConfig, defaultConfig } from "./config.js";
+export { parseConfig, defaultConfig, mergeConfigs, discoverCascadingConfigs, loadCascadingConfig } from "./config.js";
 // ─── Judge Registry ──────────────────────────────────────────────────────────
 export { JUDGES, getJudge, getJudgeSummaries } from "./judges/index.js";
 // ─── Core Evaluation Functions ───────────────────────────────────────────────
@@ -29,6 +29,7 @@ export { LRUCache, contentHash } from "./cache.js";
 export { clearProjectCache } from "./evaluators/project.js";
 // ─── Formatters ──────────────────────────────────────────────────────────────
 export { findingsToSarif, evaluationToSarif, verdictToSarif, validateSarifLog } from "./formatters/sarif.js";
+export { verdictToCsvRows, verdictsToCsv, findingsToCsv } from "./formatters/csv.js";
 // ─── CLI ─────────────────────────────────────────────────────────────────────
 export { runCli } from "./cli.js";
 // ─── Plugin API ──────────────────────────────────────────────────────────────
@@ -45,6 +46,8 @@ export { loadFixHistory, saveFixHistory, computeFixStats, recordFixAccepted, rec
 export { findingToDiagnostic, findingsToDiagnostics, findingsToCodeActions, formatForProblemMatcher, formatAsJsonRpc, } from "./formatters/diagnostics.js";
 // ─── Comparison Benchmarks ───────────────────────────────────────────────────
 export { compareCapabilities, formatComparisonReport, formatFullComparisonMatrix, TOOL_PROFILES, CAPABILITY_MATRIX, } from "./comparison.js";
+// ─── Benchmark Gate ──────────────────────────────────────────────────────────
+export { runBenchmarkSuite, benchmarkGate, formatBenchmarkReport } from "./commands/benchmark.js";
 // ─── Language Packs ──────────────────────────────────────────────────────────
 export { getLanguagePack, listLanguagePacks, suggestPack, LANGUAGE_PACKS } from "./commands/language-packs.js";
 // ─── Smart Output ────────────────────────────────────────────────────────────
@@ -82,4 +85,49 @@ export function evaluateCodeSingleJudge(judgeId, code, language, options) {
 }
 // ─── False-Positive Heuristic Filter ─────────────────────────────────────────
 export { filterFalsePositiveHeuristics } from "./evaluators/false-positive-review.js";
+/**
+ * Async generator that evaluates files one at a time, yielding results
+ * as they complete. Useful for progress reporting and streaming UIs.
+ *
+ * @example
+ * ```ts
+ * for await (const result of evaluateFilesStream(files)) {
+ *   console.log(`${result.path}: ${result.verdict.overallScore}/100`);
+ * }
+ * ```
+ */
+export async function* evaluateFilesStream(files, options) {
+    for (let i = 0; i < files.length; i++) {
+        const file = files[i];
+        const verdict = evaluateWithTribunal(file.code, file.language, undefined, options);
+        yield { path: file.path, verdict, index: i };
+    }
+}
+/**
+ * Evaluate multiple files in parallel with bounded concurrency.
+ * Returns results in the order files were provided.
+ *
+ * @param files       - Array of file inputs to evaluate
+ * @param concurrency - Maximum parallel evaluations (default: 4)
+ * @param options     - Evaluation options
+ * @param onProgress  - Optional callback for progress reporting
+ */
+export async function evaluateFilesBatch(files, concurrency = 4, options, onProgress) {
+    const results = new Array(files.length);
+    let completed = 0;
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < files.length) {
+            const i = nextIndex++;
+            const file = files[i];
+            const verdict = evaluateWithTribunal(file.code, file.language, undefined, options);
+            results[i] = { path: file.path, verdict, index: i };
+            completed++;
+            onProgress?.(completed, files.length);
+        }
+    }
+    const workers = Array.from({ length: Math.min(concurrency, files.length) }, () => worker());
+    await Promise.all(workers);
+    return results;
+}
 //# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA+BH,gFAAgF;AAChF,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEpF,gFAAgF;AAChF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEtH,gFAAgF;AAChF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAExE,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAE/B,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAEnG,gFAAgF;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,gFAAgF;AAChF,OAAO,EACL,iCAAiC,EACjC,8BAA8B,EAC9B,gCAAgC,EAChC,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAEhC,gFAAgF;AAChF,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,gFAAgF;AAChF,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE7G,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAErF,gFAAgF;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,gFAAgF;AAChF,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,cAAc,CAAC;AAGtB,+EAA+E;AAC/E,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAG1E,+EAA+E;AAC/E,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAGrG,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGrH,gFAAgF;AAChF,OAAO,EACL,cAAc,EACd,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,gFAAgF;AAChF,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,GAChB,MAAM,6BAA6B,CAAC;AAUrC,gFAAgF;AAChF,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,EAC1B,aAAa,EACb,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAGzB,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAGlG,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE/G,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAGvF,gFAAgF;AAEhF,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAGhF,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,QAAgB,EAAE,OAA2B;IACtF,OAAO,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAe,EACf,IAAY,EACZ,QAAgB,EAChB,OAA2B;IAE3B,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,eAAe,CAAC,mBAAmB,OAAO,GAAG,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AACtE,CAAC;AAED,gFAAgF;AAEhF,OAAO,EAAE,6BAA6B,EAAE,MAAM,uCAAuC,CAAC;AAuBtF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,mBAAmB,CACxC,KAAkB,EAClB,OAA2B;IAE3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QACnF,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC/C,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAkB,EAClB,WAAW,GAAG,CAAC,EACf,OAA2B,EAC3B,UAAuD;IAEvD,MAAM,OAAO,GAA2B,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChE,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,UAAU,MAAM;QACnB,OAAO,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,CAAC,GAAG,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACtB,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;YACnF,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;YACpD,SAAS,EAAE,CAAC;YACZ,UAAU,EAAE,CAAC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5F,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cli.d.ts

@@ -19,5 +19,18 @@
  *   judges hook install                                   # install pre-commit
  *   judges eval --help                                    # show help
  */
+/**
+ * Simple glob pattern matching (supports *, **, and ?).
+ * Matches against relative file paths using forward slashes.
+ */
+export declare function globToRegex(pattern: string): RegExp;
+export declare function matchesGlob(filePath: string, patterns: string[]): boolean;
+interface CollectOptions {
+    exclude?: string[];
+    include?: string[];
+    maxFiles?: number;
+}
+export declare function collectFiles(target: string, options?: CollectOptions): string[];
 export declare function runCli(argv: string[]): Promise<void>;
+export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AA8gBH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA0Z1D"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAqWH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAcnD;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAQzE;AAiBD,UAAU,cAAc;IACtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,EAAE,CAiBnF;AA+LD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAma1D"}

package/dist/cli.js

@@ -36,7 +36,7 @@ import { runBaseline } from "./commands/baseline.js";
 import { runCompletions } from "./commands/completions.js";
 import { runDocs } from "./commands/docs.js";
 import { generateGitLabCi, generateAzurePipelines, generateBitbucketPipelines } from "./commands/ci-templates.js";
-import { getPreset, listPresets } from "./presets.js";
+import { getPreset, listPresets, composePresets } from "./presets.js";
 import { parseConfig } from "./config.js";
 import { applyPatches } from "./commands/fix.js";
 import { runFeedback } from "./commands/feedback.js";
@@ -105,6 +105,9 @@ function parseCliArgs(argv) {
         verbose: false,
         quiet: false,
         fix: false,
+        exclude: [],
+        include: [],
+        maxFiles: undefined,
     };
     // First non-flag arg is the command
     let i = 2; // skip node + script
@@ -168,6 +171,17 @@ function parseCliArgs(argv) {
             case "--fix":
                 args.fix = true;
                 break;
+            case "--exclude":
+            case "-x":
+                args.exclude.push(argv[++i]);
+                break;
+            case "--include":
+            case "-i":
+                args.include.push(argv[++i]);
+                break;
+            case "--max-files":
+                args.maxFiles = parseInt(argv[++i], 10);
+                break;
             default:
                 // If it looks like a file path (not a flag), treat as --file
                 if (!arg.startsWith("-") && !args.file) {
@@ -217,7 +231,11 @@ EVAL OPTIONS:
   --summary                  Show one-line summary instead of full output
   --config, -c <path>        Path to .judgesrc config file
   --preset, -p <name>        Use a named preset (strict, lenient, security-only, startup, compliance, performance)
+                             Compose presets with commas: --preset security-only,performance
   --min-score <n>            Fail if score drops below threshold (0-100)
+  --exclude, -x <glob>       Exclude files matching glob pattern (repeatable)
+  --include, -i <glob>       Only include files matching glob pattern (repeatable)
+  --max-files <n>            Maximum number of files to analyze in directory mode
   --no-color                 Disable colored output
   --verbose                  Show detailed evaluation information
   --quiet                    Suppress non-essential output
@@ -265,6 +283,9 @@ EXAMPLES:
   judges eval --preset security-only src/app.ts
   judges eval --config .judgesrc src/app.ts
   judges eval --min-score 80 src/app.ts
+  judges eval src/ --exclude "**/*.test.ts" --exclude "**/__mocks__/**"
+  judges eval src/ --include "**/*.py" --include "**/*.ts"
+  judges eval src/ --max-files 50
   judges init
   judges fix src/app.ts --apply
   judges watch src/
@@ -309,9 +330,49 @@ function readCode(filePath) {
     console.error("Usage: judges eval --file <path> or cat file | judges eval --language <lang>");
     process.exit(1);
 }
+// ─── Glob Matching ──────────────────────────────────────────────────────────
+/**
+ * Simple glob pattern matching (supports *, **, and ?).
+ * Matches against relative file paths using forward slashes.
+ */
+export function globToRegex(pattern) {
+    // Normalize to forward slashes
+    let p = pattern.replace(/\\/g, "/");
+    // Escape regex chars except * and ?
+    p = p.replace(/[.+^${}()|[\]]/g, "\\$&");
+    // ** matches any path segment(s)
+    p = p.replace(/\*\*/g, "{{GLOBSTAR}}");
+    // * matches anything except /
+    p = p.replace(/\*/g, "[^/]*");
+    // ? matches any single char except /
+    p = p.replace(/\?/g, "[^/]");
+    // Restore globstar
+    p = p.replace(/\{\{GLOBSTAR\}\}/g, ".*");
+    return new RegExp(`^${p}$`, "i");
+}
+export function matchesGlob(filePath, patterns) {
+    if (patterns.length === 0)
+        return false;
+    const normalized = filePath.replace(/\\/g, "/");
+    return patterns.some((pat) => {
+        const re = globToRegex(pat);
+        // Match against full path or just the filename
+        return re.test(normalized) || re.test(normalized.split("/").pop() || "");
+    });
+}
 // ─── Glob / Multi-File Resolution ───────────────────────────────────────────
 const SUPPORTED_EXTENSIONS = new Set(Object.keys(EXT_TO_LANG));
-function collectFiles(target) {
+const DEFAULT_SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    "__pycache__",
+    "target",
+    "vendor",
+]);
+export function collectFiles(target, options = {}) {
     const resolved = resolve(target);
     if (!existsSync(resolved))
         return [];
@@ -320,26 +381,47 @@ function collectFiles(target) {
         return [resolved];
     if (stat.isDirectory()) {
         const files = [];
-        walkDir(resolved, files);
+        walkDir(resolved, resolved, files, options);
+        if (options.maxFiles && files.length > options.maxFiles) {
+            return files.slice(0, options.maxFiles);
+        }
         return files;
     }
     return [];
 }
-function walkDir(dir, results) {
+function walkDir(dir, root, results, options) {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
         const fullPath = join(dir, entry.name);
+        const relPath = relative(root, fullPath);
         // Skip common non-source directories
         if (entry.isDirectory()) {
-            if (["node_modules", ".git", "dist", "build", ".next", "__pycache__", "target", "vendor"].includes(entry.name))
+            if (DEFAULT_SKIP_DIRS.has(entry.name))
+                continue;
+            // Check if directory matches an exclude pattern
+            if (options.exclude && matchesGlob(relPath + "/", options.exclude))
                 continue;
-            walkDir(fullPath, results);
+            walkDir(fullPath, root, results, options);
         }
         else if (entry.isFile()) {
-            const ext = extname(entry.name);
-            if (SUPPORTED_EXTENSIONS.has(ext)) {
-                results.push(fullPath);
+            // Apply exclude patterns
+            if (options.exclude && matchesGlob(relPath, options.exclude))
+                continue;
+            // Apply include patterns — if include patterns are specified, ONLY include matching files
+            if (options.include && options.include.length > 0) {
+                if (!matchesGlob(relPath, options.include))
+                    continue;
+            }
+            else {
+                // Default: only include files with supported extensions
+                const ext = extname(entry.name);
+                if (!SUPPORTED_EXTENSIONS.has(ext))
+                    continue;
             }
+            results.push(fullPath);
+            // Early exit if we've hit maxFiles
+            if (options.maxFiles && results.length >= options.maxFiles)
+                return;
         }
     }
 }
@@ -612,7 +694,15 @@ export async function runCli(argv) {
         // ── Multi-file / directory mode ──────────────────────────────────────
         const target = args.file;
         if (target && isDirectory(target)) {
-            const files = collectFiles(target);
+            // Merge exclude/include from config if not overridden by CLI
+            const excludePatterns = args.exclude.length > 0 ? args.exclude : (evalConfig?.exclude ?? []);
+            const includePatterns = args.include.length > 0 ? args.include : (evalConfig?.include ?? []);
+            const maxFilesLimit = args.maxFiles ?? evalConfig?.maxFiles;
+            const files = collectFiles(target, {
+                exclude: excludePatterns,
+                include: includePatterns,
+                maxFiles: maxFilesLimit,
+            });
             if (files.length === 0) {
                 console.error(`No supported source files found in: ${target}`);
                 process.exit(1);
@@ -882,17 +972,32 @@ function printSummaryLine(verdict, score, findings) {
 // ─── Config / Preset Loader ────────────────────────────────────────────────
 function loadEvalConfig(args) {
     let config;
-    // 1. Load from preset
+    // 1. Load from preset (supports comma-separated composition: "security-only,performance")
     if (args.preset) {
-        const preset = getPreset(args.preset);
-        if (!preset) {
-            console.error(`Unknown preset: ${args.preset}`);
-            console.error(`Available: ${listPresets()
-                .map((p) => p.name)
-                .join(", ")}`);
-            process.exit(1);
+        const presetNames = args.preset.split(",").map((n) => n.trim());
+        if (presetNames.length === 1) {
+            const preset = getPreset(presetNames[0]);
+            if (!preset) {
+                console.error(`Unknown preset: ${presetNames[0]}`);
+                console.error(`Available: ${listPresets()
+                    .map((p) => p.name)
+                    .join(", ")}`);
+                process.exit(1);
+            }
+            config = { ...preset.config };
+        }
+        else {
+            // Multi-preset composition
+            const composed = composePresets(presetNames);
+            if (!composed) {
+                console.error(`No valid presets found in: ${args.preset}`);
+                console.error(`Available: ${listPresets()
+                    .map((p) => p.name)
+                    .join(", ")}`);
+                process.exit(1);
+            }
+            config = { ...composed.config };
         }
-        config = { ...preset.config };
     }
     // 2. Load from --config file (overrides preset)
     if (args.config) {