@oddessentials/odd-ai-reviewers 1.10.1 → 1.12.0

package/dist/cli/execution-plan.js

@@ -0,0 +1,260 @@
+/**
+ * Execution Plan Module (FR-001 through FR-007)
+ *
+ * Produces a single, immutable ExecutionPlan object that is the sole source of truth
+ * for all downstream code paths (dry-run, cost-only, dependency check, execution).
+ *
+ * Pipeline: Parse -> Validate -> BuildExecutionPlan -> DependencyCheck -> Execute
+ *
+ * No downstream consumer may read raw CLI flags — they operate on the plan.
+ */
+import { AGENT_REGISTRY, getAgentById, getCompatibleAgents, } from '../config/schemas.js';
+import { ConfigError, ConfigErrorCode } from '../types/errors.js';
+import { assertNever } from '../types/assert-never.js';
+/**
+ * The ONLY path to produce an exit code.
+ * No call site may hardcode an exit code number directly.
+ */
+export function exitCodeFromStatus(status) {
+    switch (status) {
+        case 'complete':
+            return 0;
+        case 'gating_failed':
+            return 1;
+        case 'config_error':
+            return 2;
+        case 'incomplete':
+            return 3;
+        default:
+            return assertNever(status);
+    }
+}
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+/**
+ * Validate --pass flag against configured passes.
+ * Throws ConfigError if unknown.
+ */
+function validatePassFilter(passFilter, passes) {
+    const match = passes.find((p) => p.name === passFilter);
+    if (!match) {
+        const available = passes.map((p) => p.name).join(', ');
+        throw new ConfigError(`Unknown pass '${passFilter}'. Available: ${available}`, ConfigErrorCode.INVALID_VALUE, { field: 'pass', expected: available, actual: passFilter });
+    }
+    if (!match.enabled) {
+        throw new ConfigError(`Pass '${passFilter}' is disabled in configuration`, ConfigErrorCode.INVALID_VALUE, { field: 'pass', actual: passFilter });
+    }
+    return match;
+}
+/**
+ * Validate --agent flag against the agent registry.
+ * Throws ConfigError if unknown.
+ */
+function validateAgentFilter(agentFilter) {
+    const entry = getAgentById(agentFilter);
+    if (!entry) {
+        const validIds = AGENT_REGISTRY.map((a) => a.id).join(', ');
+        throw new ConfigError(`Unknown agent '${agentFilter}'. Valid: ${validIds}`, ConfigErrorCode.INVALID_VALUE, { field: 'agent', expected: validIds, actual: agentFilter });
+    }
+    return entry;
+}
+/**
+ * Validate pass composition at config time.
+ * Checks for unknown agents and duplicates within passes.
+ */
+function validatePassComposition(passes) {
+    for (const pass of passes) {
+        // Check for unknown agents
+        for (const agentId of pass.agents) {
+            if (!getAgentById(agentId)) {
+                const validIds = AGENT_REGISTRY.map((a) => a.id).join(', ');
+                throw new ConfigError(`Unknown agent '${agentId}' in pass '${pass.name}'. Valid: ${validIds}`, ConfigErrorCode.INVALID_VALUE, { field: `passes.${pass.name}.agents`, expected: validIds, actual: agentId });
+            }
+        }
+        // Check for duplicates
+        const seen = new Set();
+        for (const agentId of pass.agents) {
+            if (seen.has(agentId)) {
+                throw new ConfigError(`Duplicate agent '${agentId}' in pass '${pass.name}'`, ConfigErrorCode.INVALID_VALUE, { field: `passes.${pass.name}.agents`, actual: agentId });
+            }
+            seen.add(agentId);
+        }
+    }
+}
+// =============================================================================
+// Build Execution Plan
+// =============================================================================
+/**
+ * Build an immutable execution plan from config and CLI options.
+ *
+ * Enforces all invariants:
+ * - Pass/agent validation against registry
+ * - Provider compatibility filtering
+ * - Empty-pass rule (required+empty -> ConfigError; optional+empty -> skipped)
+ * - Combined --pass + --agent narrowing (FR-007)
+ *
+ * @throws ConfigError on validation failures (exit code 2)
+ */
+export function buildExecutionPlan(options) {
+    const { config, mode, passFilter, agentFilter, provider, model, configSource } = options;
+    // 1. Validate pass composition at config time
+    validatePassComposition(config.passes);
+    // 2. Start with enabled passes
+    let candidatePasses = config.passes.filter((p) => p.enabled);
+    // 3. Apply --pass filter
+    if (passFilter) {
+        const matchedPass = validatePassFilter(passFilter, config.passes);
+        candidatePasses = [matchedPass];
+    }
+    // 4. Validate --agent filter against registry
+    if (agentFilter) {
+        validateAgentFilter(agentFilter);
+    }
+    // 5. Get compatible agents for the provider
+    const compatibleAgents = getCompatibleAgents(provider);
+    const compatibleIds = new Set(compatibleAgents.map((a) => a.id));
+    const requestedAgentId = agentFilter;
+    // 6. Build planned passes with agent filtering
+    const plannedPasses = [];
+    const skippedPasses = [];
+    for (const pass of candidatePasses) {
+        // Filter agents by provider compatibility
+        let agents = pass.agents.filter((id) => compatibleIds.has(id));
+        // Log provider-incompatible agents as excluded (non-required passes only)
+        const excludedByProvider = pass.agents.filter((id) => !compatibleIds.has(id));
+        if (excludedByProvider.length > 0 && pass.required) {
+            // Required pass with incompatible agents -> config error
+            const incompatible = excludedByProvider.join(', ');
+            throw new ConfigError(`Required pass '${pass.name}' contains agents incompatible with provider '${provider}': ${incompatible}`, ConfigErrorCode.INVALID_VALUE, { field: `passes.${pass.name}.agents`, actual: incompatible });
+        }
+        // Apply --agent filter within pass
+        if (agentFilter) {
+            const passContainsRequestedAgent = pass.agents.includes(requestedAgentId);
+            if (passFilter &&
+                passContainsRequestedAgent &&
+                !compatibleIds.has(requestedAgentId)) {
+                throw new ConfigError(`Agent '${agentFilter}' in pass '${passFilter}' is incompatible with provider '${provider}'`, ConfigErrorCode.INVALID_VALUE, { field: 'agent', actual: agentFilter });
+            }
+            const hasAgent = agents.some((id) => id === agentFilter);
+            if (hasAgent) {
+                agents = agents.filter((id) => id === agentFilter);
+            }
+            else if (passFilter) {
+                // Combined: --pass + --agent, agent not in the selected pass
+                const otherPasses = config.passes
+                    .filter((p) => p.enabled && p.agents.includes(agentFilter))
+                    .map((p) => p.name);
+                const availableIn = otherPasses.length > 0 ? ` It is available in: ${otherPasses.join(', ')}` : '';
+                throw new ConfigError(`Agent '${agentFilter}' is not configured in pass '${passFilter}'.${availableIn}`, ConfigErrorCode.INVALID_VALUE, { field: 'agent', actual: agentFilter });
+            }
+            else {
+                // Agent not in this pass, skip it (will be caught by check below if in no pass)
+                agents = [];
+            }
+        }
+        // Empty-pass rule
+        if (agents.length === 0) {
+            if (pass.required) {
+                throw new ConfigError(`Required pass '${pass.name}' has no runnable agents after filtering`, ConfigErrorCode.INVALID_VALUE, { field: `passes.${pass.name}` });
+            }
+            const reason = excludedByProvider.length > 0
+                ? `Pass '${pass.name}' skipped: no agents compatible with provider '${provider}'`
+                : `Pass '${pass.name}' skipped: no matching agents after filtering`;
+            skippedPasses.push({ name: pass.name, reason });
+            continue;
+        }
+        plannedPasses.push({
+            name: pass.name,
+            agents: agents,
+            required: pass.required,
+        });
+    }
+    // 7. If --agent was specified but found in no pass, error
+    if (agentFilter && !passFilter && plannedPasses.length === 0) {
+        // Check if the agent exists in any configured pass at all
+        const passesWithAgent = config.passes
+            .filter((p) => p.agents.includes(agentFilter))
+            .map((p) => p.name);
+        if (passesWithAgent.length === 0) {
+            throw new ConfigError(`Agent '${agentFilter}' not configured in any pass`, ConfigErrorCode.INVALID_VALUE, { field: 'agent', actual: agentFilter });
+        }
+        if (!compatibleIds.has(agentFilter)) {
+            throw new ConfigError(`Agent '${agentFilter}' is incompatible with provider '${provider}' and cannot run in configured passes: ${passesWithAgent.join(', ')}`, ConfigErrorCode.INVALID_VALUE, { field: 'agent', actual: agentFilter });
+        }
+    }
+    // 8. Assert structural invariant: no pass with empty agents
+    for (const pass of plannedPasses) {
+        if (pass.agents.length === 0) {
+            throw new Error(`Invariant violation: pass '${pass.name}' has empty agents list in execution plan`);
+        }
+    }
+    // 9. Build limits snapshot
+    const limits = {
+        maxDiffLines: config.limits.max_diff_lines,
+        maxFiles: config.limits.max_files,
+        maxTokensPerPr: config.limits.max_tokens_per_pr,
+        maxUsdPerPr: config.limits.max_usd_per_pr,
+    };
+    // 10. Build gating snapshot
+    const gating = {
+        enabled: config.gating.enabled,
+        failOnSeverity: config.gating.fail_on_severity,
+        driftGate: config.gating.drift_gate,
+    };
+    const plan = {
+        mode,
+        passes: plannedPasses,
+        skippedPasses,
+        provider: provider ?? null,
+        model: model ?? null,
+        limits,
+        gating,
+        configSource,
+        schemaVersion: config.version,
+    };
+    return plan;
+}
+// =============================================================================
+// Plan Serialization (Canonical, Redacted)
+// =============================================================================
+/**
+ * Safe-field allowlist for plan serialization.
+ * Only these fields appear in serialized output — everything else is excluded.
+ * Keys are emitted in alphabetical order at every level.
+ */
+export function serializeExecutionPlan(plan) {
+    const canonical = {
+        configSource: plan.configSource,
+        gating: {
+            driftGate: plan.gating.driftGate,
+            enabled: plan.gating.enabled,
+            failOnSeverity: plan.gating.failOnSeverity,
+        },
+        limits: {
+            maxDiffLines: plan.limits.maxDiffLines,
+            maxFiles: plan.limits.maxFiles,
+            maxTokensPerPr: plan.limits.maxTokensPerPr,
+            maxUsdPerPr: plan.limits.maxUsdPerPr,
+        },
+        mode: plan.mode,
+        model: plan.model,
+        passes: plan.passes.map((p) => ({
+            agents: [...p.agents].sort(),
+            name: p.name,
+            required: p.required,
+        })),
+        provider: plan.provider,
+        schemaVersion: plan.schemaVersion,
+        ...(plan.skippedPasses.length > 0
+            ? {
+                skippedPasses: plan.skippedPasses.map((s) => ({
+                    name: s.name,
+                    reason: s.reason,
+                })),
+            }
+            : {}),
+    };
+    return JSON.stringify(canonical, null, 2);
+}
+//# sourceMappingURL=execution-plan.js.map

package/dist/cli/execution-plan.js.map

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

package/dist/config/schemas.d.ts

@@ -5,25 +5,41 @@
  * Extracted from config.ts to improve modularity.
  */
 import { z } from 'zod';
+/**
+ * Metadata for a single agent in the canonical registry.
+ * Schema validation, CLI help, docs tables, and error messages all derive from this.
+ */
+export interface AgentRegistryEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly requiresExternalTool: boolean;
+    readonly requiresApiKey: boolean;
+    readonly builtIn: boolean;
+    readonly compatibleProviders: readonly string[] | 'all';
+}
+/**
+ * Canonical agent registry — the sole authority for agent identity.
+ * Adding a new agent without updating this registry is impossible because
+ * AgentSchema is derived from it.
+ */
+export declare const AGENT_REGISTRY: readonly AgentRegistryEntry[];
+/**
+ * Look up an agent by ID from the registry.
+ */
+export declare function getAgentById(id: string): AgentRegistryEntry | undefined;
+/**
+ * Get agents compatible with a given provider.
+ * Returns all agents if provider is null/undefined.
+ */
+export declare function getCompatibleAgents(provider: string | null | undefined): AgentRegistryEntry[];
 export declare const AgentSchema: z.ZodEnum<{
-    control_flow: "control_flow";
-    semgrep: "semgrep";
-    reviewdog: "reviewdog";
-    opencode: "opencode";
-    pr_agent: "pr_agent";
-    local_llm: "local_llm";
-    ai_semantic_review: "ai_semantic_review";
+    [x: string]: string;
 }>;
 export declare const PassSchema: z.ZodObject<{
     name: z.ZodString;
     agents: z.ZodArray<z.ZodEnum<{
-        control_flow: "control_flow";
-        semgrep: "semgrep";
-        reviewdog: "reviewdog";
-        opencode: "opencode";
-        pr_agent: "pr_agent";
-        local_llm: "local_llm";
-        ai_semantic_review: "ai_semantic_review";
+        [x: string]: string;
     }>>;
     enabled: z.ZodDefault<z.ZodBoolean>;
     required: z.ZodDefault<z.ZodBoolean>;
@@ -120,6 +136,50 @@ export declare const ProviderSchema: z.ZodEnum<{
     "azure-openai": "azure-openai";
     ollama: "ollama";
 }>;
+export declare const SuppressionRuleSchema: z.ZodObject<{
+    rule: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    file: z.ZodOptional<z.ZodString>;
+    severity: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>>;
+    reason: z.ZodString;
+    breadth_override: z.ZodOptional<z.ZodBoolean>;
+    breadth_override_reason: z.ZodOptional<z.ZodString>;
+    approved_by: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SuppressionsSchema: z.ZodObject<{
+    rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        rule: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+        file: z.ZodOptional<z.ZodString>;
+        severity: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+            info: "info";
+        }>>;
+        reason: z.ZodString;
+        breadth_override: z.ZodOptional<z.ZodBoolean>;
+        breadth_override_reason: z.ZodOptional<z.ZodString>;
+        approved_by: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    disable_matchers: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "express-error-mw": "express-error-mw";
+        "ts-unused-prefix": "ts-unused-prefix";
+        "exhaustive-switch": "exhaustive-switch";
+        "react-query-dedup": "react-query-dedup";
+        "promise-allsettled-order": "promise-allsettled-order";
+        "safe-local-file-read": "safe-local-file-read";
+        "exhaustive-type-narrowed-switch": "exhaustive-type-narrowed-switch";
+        "error-object-xss": "error-object-xss";
+        "thin-wrapper-stdlib": "thin-wrapper-stdlib";
+    }>>>;
+    security_override_allowlist: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type SuppressionRule = z.infer<typeof SuppressionRuleSchema>;
+export type Suppressions = z.infer<typeof SuppressionsSchema>;
 export declare const ConfigSchema: z.ZodObject<{
     version: z.ZodDefault<z.ZodNumber>;
     trusted_only: z.ZodDefault<z.ZodBoolean>;
@@ -133,13 +193,7 @@ export declare const ConfigSchema: z.ZodObject<{
     passes: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         agents: z.ZodArray<z.ZodEnum<{
-            control_flow: "control_flow";
-            semgrep: "semgrep";
-            reviewdog: "reviewdog";
-            opencode: "opencode";
-            pr_agent: "pr_agent";
-            local_llm: "local_llm";
-            ai_semantic_review: "ai_semantic_review";
+            [x: string]: string;
         }>>;
         enabled: z.ZodDefault<z.ZodBoolean>;
         required: z.ZodDefault<z.ZodBoolean>;
@@ -272,6 +326,34 @@ export declare const ConfigSchema: z.ZodObject<{
         "azure-openai": "azure-openai";
         ollama: "ollama";
     }>>;
+    suppressions: z.ZodOptional<z.ZodObject<{
+        rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            rule: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+            file: z.ZodOptional<z.ZodString>;
+            severity: z.ZodOptional<z.ZodEnum<{
+                error: "error";
+                warning: "warning";
+                info: "info";
+            }>>;
+            reason: z.ZodString;
+            breadth_override: z.ZodOptional<z.ZodBoolean>;
+            breadth_override_reason: z.ZodOptional<z.ZodString>;
+            approved_by: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        disable_matchers: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            "express-error-mw": "express-error-mw";
+            "ts-unused-prefix": "ts-unused-prefix";
+            "exhaustive-switch": "exhaustive-switch";
+            "react-query-dedup": "react-query-dedup";
+            "promise-allsettled-order": "promise-allsettled-order";
+            "safe-local-file-read": "safe-local-file-read";
+            "exhaustive-type-narrowed-switch": "exhaustive-type-narrowed-switch";
+            "error-object-xss": "error-object-xss";
+            "thin-wrapper-stdlib": "thin-wrapper-stdlib";
+        }>>>;
+        security_override_allowlist: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Config = z.infer<typeof ConfigSchema>;
 export type Pass = z.infer<typeof PassSchema>;

package/dist/config/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/config/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,WAAW;;;;;;;;EAQtB,CAAC;AAEH,eAAO,MAAM,UAAU;;;;;;;;;;;;;iBAUrB,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;iBAavB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;iBAMhC,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;iBAM7B,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;iBAG1B,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;;iBAKvB,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;iBAGzB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;iBAG5B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY;;iBAGvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;EAA4D,CAAC;AAExF,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8BvB,CAAC;AAGH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/config/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC;CACzD;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,kBAAkB,EAgE9C,CAAC;AAKX;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEvE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB,EAAE,CAK7F;AAGD,eAAO,MAAM,WAAW;;EAAoB,CAAC;AAE7C,eAAO,MAAM,UAAU;;;;;;;iBAUrB,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;iBAavB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;iBAMhC,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;iBAM7B,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;iBAG1B,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;;iBAKvB,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;iBAGzB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;iBAG5B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY;;iBAGvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;EAA4D,CAAC;AAmBxF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;iBAuE/B,CAAC;AAEJ,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAU3B,CAAC;AAEL,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCvB,CAAC;AAGH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/config/schemas.js

@@ -6,16 +6,95 @@
  */
 import { z } from 'zod';
 import { ControlFlowConfigSchema } from '../agents/control_flow/types.js';
-// Schema definitions
-export const AgentSchema = z.enum([
-    'semgrep',
-    'reviewdog',
-    'opencode',
-    'pr_agent',
-    'local_llm',
-    'ai_semantic_review',
-    'control_flow',
-]);
+/**
+ * Canonical agent registry — the sole authority for agent identity.
+ * Adding a new agent without updating this registry is impossible because
+ * AgentSchema is derived from it.
+ */
+export const AGENT_REGISTRY = [
+    {
+        id: 'semgrep',
+        name: 'Semgrep',
+        description: 'Static analysis via Semgrep CLI',
+        requiresExternalTool: true,
+        requiresApiKey: false,
+        builtIn: false,
+        compatibleProviders: 'all',
+    },
+    {
+        id: 'reviewdog',
+        name: 'Reviewdog',
+        description: 'Lint aggregation via Reviewdog CLI',
+        requiresExternalTool: true,
+        requiresApiKey: false,
+        builtIn: false,
+        compatibleProviders: 'all',
+    },
+    {
+        id: 'opencode',
+        name: 'OpenCode',
+        description: 'AI code review via cloud LLM',
+        requiresExternalTool: false,
+        requiresApiKey: true,
+        builtIn: false,
+        compatibleProviders: ['anthropic', 'openai', 'azure-openai'],
+    },
+    {
+        id: 'pr_agent',
+        name: 'PR Agent',
+        description: 'AI pull request analysis via cloud LLM',
+        requiresExternalTool: false,
+        requiresApiKey: true,
+        builtIn: false,
+        compatibleProviders: ['anthropic', 'openai', 'azure-openai'],
+    },
+    {
+        id: 'local_llm',
+        name: 'Local LLM',
+        description: 'AI code review via local Ollama model',
+        requiresExternalTool: false,
+        requiresApiKey: false,
+        builtIn: false,
+        compatibleProviders: ['ollama'],
+    },
+    {
+        id: 'ai_semantic_review',
+        name: 'AI Semantic Review',
+        description: 'Semantic analysis via cloud LLM',
+        requiresExternalTool: false,
+        requiresApiKey: true,
+        builtIn: false,
+        compatibleProviders: ['anthropic', 'openai', 'azure-openai'],
+    },
+    {
+        id: 'control_flow',
+        name: 'Control Flow',
+        description: 'Built-in TypeScript control flow analysis',
+        requiresExternalTool: false,
+        requiresApiKey: false,
+        builtIn: true,
+        compatibleProviders: 'all',
+    },
+];
+/** All valid agent IDs, derived from the registry */
+const AGENT_IDS = AGENT_REGISTRY.map((a) => a.id);
+/**
+ * Look up an agent by ID from the registry.
+ */
+export function getAgentById(id) {
+    return AGENT_REGISTRY.find((a) => a.id === id);
+}
+/**
+ * Get agents compatible with a given provider.
+ * Returns all agents if provider is null/undefined.
+ */
+export function getCompatibleAgents(provider) {
+    if (!provider)
+        return [...AGENT_REGISTRY];
+    return AGENT_REGISTRY.filter((a) => a.compatibleProviders === 'all' || a.compatibleProviders.includes(provider));
+}
+// Schema definitions — AgentSchema derived from registry
+export const AgentSchema = z.enum(AGENT_IDS);
 export const PassSchema = z.object({
     name: z.string(),
     agents: z.array(AgentSchema),
@@ -87,6 +166,92 @@ export const ModelsSchema = z.object({
  * Required when multiple provider keys are present with MODEL set.
  */
 export const ProviderSchema = z.enum(['anthropic', 'openai', 'azure-openai', 'ollama']);
+// =============================================================================
+// Suppression Schema (FR-022)
+// =============================================================================
+/** Valid matcher IDs for disable_matchers */
+const VALID_MATCHER_IDS = [
+    'express-error-mw',
+    'ts-unused-prefix',
+    'exhaustive-switch',
+    'react-query-dedup',
+    'promise-allsettled-order',
+    'safe-local-file-read',
+    'exhaustive-type-narrowed-switch',
+    'error-object-xss',
+    'thin-wrapper-stdlib',
+];
+export const SuppressionRuleSchema = z
+    .object({
+    /** Glob pattern against finding.ruleId */
+    rule: z.string().optional(),
+    /** Anchored regex pattern against finding.message */
+    message: z.string().optional(),
+    /** Glob pattern against finding.file */
+    file: z.string().optional(),
+    /** Exact match against finding.severity */
+    severity: z.enum(['error', 'warning', 'info']).optional(),
+    /** Mandatory audit reason */
+    reason: z.string().min(1),
+    /** Allow broad suppression (>20 matches in CI) */
+    breadth_override: z.boolean().optional(),
+    /** Justification for breadth override */
+    breadth_override_reason: z.string().optional(),
+    /** Person or team who approved the override */
+    approved_by: z.string().optional(),
+})
+    .refine((rule) => rule.rule !== undefined || rule.message !== undefined || rule.file !== undefined, { message: 'Suppression rule must specify at least one of: rule, message, file' })
+    .refine((rule) => {
+    if (rule.message === undefined)
+        return true;
+    if (rule.message.length === 0)
+        return false;
+    // FR-022: Message patterns MUST be fully anchored (^ and $).
+    if (!(rule.message.startsWith('^') && rule.message.endsWith('$')))
+        return false;
+    // Reject blanket patterns that match everything (^.*$, ^.+$, ^.{0,}$)
+    const blanketPatterns = ['^.*$', '^.+$', '^.{0,}$'];
+    if (blanketPatterns.includes(rule.message))
+        return false;
+    return true;
+}, {
+    message: "Message pattern must be fully anchored (^...$) and not a blanket match. Use '^specific pattern$' for exact match or '^.*specific.*$' for substring.",
+})
+    .refine((rule) => {
+    if (rule.rule === undefined)
+        return true;
+    // Reject blanket rule globs that match all rule IDs
+    const blanketGlobs = ['*', '**', '**/*'];
+    return !blanketGlobs.includes(rule.rule);
+}, { message: "Rule glob must be scoped (e.g., 'semantic/*'), not a blanket '*'." })
+    .refine((rule) => {
+    if (rule.file === undefined)
+        return true;
+    // Reject blanket file globs that match all files
+    const blanketGlobs = ['*', '**', '**/*', '**/**'];
+    return !blanketGlobs.includes(rule.file);
+}, { message: "File glob must be scoped (e.g., 'tests/**'), not a blanket '**'." })
+    .refine((rule) => {
+    if (!rule.breadth_override)
+        return true;
+    return (rule.breadth_override_reason !== undefined &&
+        rule.breadth_override_reason.length > 0 &&
+        rule.approved_by !== undefined &&
+        rule.approved_by.length > 0);
+}, {
+    message: 'breadth_override requires both breadth_override_reason and approved_by to be specified',
+});
+export const SuppressionsSchema = z
+    .object({
+    rules: z.array(SuppressionRuleSchema).default([]),
+    /** Matcher IDs to disable in the framework convention filter */
+    disable_matchers: z.array(z.enum(VALID_MATCHER_IDS)).default([]),
+    /** Rule reasons authorized to suppress error-severity findings with breadth override */
+    security_override_allowlist: z.array(z.string()).default([]),
+})
+    .refine((s) => s.rules.length <= 50, {
+    message: 'Maximum 50 suppression rules allowed',
+});
 export const ConfigSchema = z.object({
     version: z.number().default(1),
     trusted_only: z.boolean().default(true),
@@ -117,5 +282,7 @@ export const ConfigSchema = z.object({
      * REQUIRED when multiple provider keys are present AND MODEL is set (prevents ambiguity).
      */
     provider: ProviderSchema.optional(),
+    /** User-configurable finding suppressions (FR-022) */
+    suppressions: SuppressionsSchema.optional(),
 });
 //# sourceMappingURL=schemas.js.map