Per-language metric registry + cognitive complexity

[ElbertePlinio]

Parent: #6

Add cognitive complexity as a per-function metric, and introduce the metric registry it needs.

Why

Cyclomatic complexity counts branches; it cannot tell a 30-arm dispatch from a 5-level nest. Two real cases from the prova-clara scan (details in #6):

• src/lib/server/env.ts:107 validateProductionServerEnv — complexity 54, a flat sequence of guard clauses.
• src/lib/assessment-context/diff.ts:48 summarizeProfileField — complexity 30, a switch with independent arms.

Both are readable and both fail today. Cognitive complexity penalizes nesting and continuity breaks instead, and would score both near zero. Same reason Rust consumers need per-repo complexity overrides for large match expressions. Already listed as a v2 candidate in docs/spec.md.

Spec first

AGENTS.md makes docs/spec.md the contract, and cognitive complexity is underspecified by name alone — without one pinned algorithm the golden fixtures become arbitrary. PR 1 is spec-only and carries all the judgment:

• Which nodes increment, which nest, and by how much.
• else / elif / catch chain handling.
• Sequences of like logical operators (one increment per sequence, not per operator).
• Recursion.
• One explicit rule table per language: js_decision, dart_decision, rust_decision, python_decision, go_decision equivalents.
• Svelte template rules, defined independently — they cannot inherit the TS rules.

Metric registry

Limits is a fixed struct of four usize fields and add_violations walks a hard-coded array, so there is no way to add a metric that exists for only some languages. Building the registry alongside cognitive complexity is cheaper than retrofitting it, and it unblocks later per-language checks (explicit any / as assertions for TS, unwrap() for Rust, bare except: for Python, ignored errors for Go, ! assertions for Dart). Those are follow-ups, not scope here.

Implementation notes

• Add a separate traversal beside measure_node in crates/core/src/language.rs. Do not extend it — cyclomatic and cognitive deliberately count different things.
• New field on FunctionMetrics; extend Score and measure_function.
• crates/core/src/config.rs: Limits, LimitOverrides, validate_keys, validate_language_keys, Config::limits_for. The strict validator must admit the new key.
• crates/core/src/scan.rs: emit in add_violations.
• config.default.json: limits.cognitive (default 15, pending the rollout decision in Metric expansion: cognitive complexity and Svelte template scoping #6).
• Every tests/fixtures/<language>/expected.json gains a cognitive value, including the negative cases AGENTS.md requires (operator inside a string literal, unbraced else <loop>, _ when guard).
• Output format, JSON shape (Violation.metric), and exit codes are unchanged.

Checklist

• PR 1: docs/spec.md — cognitive complexity section, algorithm pinned per language
• PR 2: metric registry
• PR 2: cognitive traversal + FunctionMetrics field
• PR 2: config schema, validator, per-language overrides, default limit
• PR 2: golden fixtures for every language incl. negative cases
• Verify validateProductionServerEnv and summarizeProfileField pass on defaults
• Verify Rust match cases no longer need per-repo overrides
• PR/review

Validation

cargo test --workspace --locked --all-targets
cargo clippy --workspace --all-targets -- -D warnings
cargo llvm-cov
cargo run -- check crates
complexity-gate check --format json ~/Projects/Personal/prova-clara/src   # before/after comparison

Risks

• Determinism is the main one: one algorithm, pinned in the spec, committed in fixtures. No per-language improvisation during implementation.
• Hook latency: linear in AST size, computed in a second walk. Measure before merge.
• Diff size is large. If it grows further during implementation, split the registry into its own PR.

Status: Planned
Next action: write the spec section

[ElbertePlinio]

Acceptance criteria corrected after measurement (full data in the #6 comment).

This issue claimed both motivating functions should pass on default limits once cognitive complexity lands. Only one will:

• diff.ts:48 summarizeProfileField (cyclomatic 30) — a switch scores +1 for the whole switch under cognitive complexity regardless of arm count, so it drops to low single digits. Genuine false positive, genuinely fixed. Same mechanism that retires the Rust big-match overrides, which remains the strongest argument for this issue.
• env.ts:107 validateProductionServerEnv (cyclomatic 54) — 54 sequential if guards each still increment under cognitive complexity, so it lands near 54 and still fails. That is probably the right answer: 54 distinct validations in one sub-100-line function is a table or a loop waiting to happen.

Revised acceptance:

• summarizeProfileField passes on default limits
• Rust match-heavy code no longer needs per-repo complexity overrides
• validateProductionServerEnv passes — flat repetition is a real refactor, not a metric artifact

Also: a cheap substitute for this issue (nesting-weighted complexity, score += 1 + depth) was prototyped and rejected — it scores validateProductionServerEnv 5th-highest of 17,414 functions and no threshold separates flat from nested. Full cognitive complexity is the only remaining candidate. Details in #6.

Scope note: the metric registry in this issue is no longer a prerequisite for #9. bool_ops needs no registry, and widget_depth is the only language-specific metric planned — consider building it as a Dart-specific field and extracting a registry when a second one appears.