refactor(lib): 2.0 shape & error-type ergonomics cleanups

[dekobon]

Decided (2026-06-05): nexits canonical everywhere (exit CLI alias 1 cycle, JSON key unchanged); remove the 3 unreachable MetricsError variants; FunctionSpan.name→Option<String> (drop error); add additive input() accessors to the parse errors. See the resolved-decisions comment.

Summary

A cluster of small public shape / error-type ergonomics fixes that are each a
SemVer break and so must batch into 2.0.

Findings

1. ParseMetricError / ParseLangError expose no accessor.
   ParseMetricError(String) (src/metric_set.rs) and ParseLangError
   (src/macros/mod.rs) wrap a private String; callers can only Display
   the rejected input, not recover it programmatically. Contrast
   MetricsError::LanguageDisabled(LANG), which exposes its payload. Add
   fn input(&self) -> &str (additive — could ship pre-2.0) and finalize the
   representation at 2.0.

2. MetricsError reserved variants. EmptyRoot, NonUtf8Path,
   ParseHasErrors (src/error.rs) are documented as never-produced today.
   Since the enum is #[non_exhaustive], the reserved variants buy nothing that
   #[non_exhaustive] doesn't, while forcing every exhaustive matcher to handle
   dead cases. At 2.0 either wire them up behind the strict-mode toggles they
   document, or remove them.

3. Exit-metric has three spellings. Metric::Exit (Display = "exit"),
   Metric::NAMES/JSON key = "nexits", CodeMetrics::nexits field
   (src/metric_set.rs, src/spaces.rs). Metric::Display not round-tripping
   to the canonical NAMES spelling is a footgun for anyone using Display
   output as a config key. Pick one canonical string end-to-end at 2.0.
   (Distinct from fix(cli): reconcile metric-name spelling between diff --metric and check --threshold #514, which reconciled diff --metric vs check --threshold.)

4. FunctionSpan sentinel. FunctionSpan uses name: String +
   error: bool (src/function.rs), setting name = String::new() +
   error = true on parse failure — the exact anti-pattern FuncSpace/Ops
   avoid with name: Option<String>. Change to name: Option<String> and drop
   error at 2.0.

Why 2.0-worthy

Items 2–4 are shape breaks; item 1's representation change is too (the accessor
itself is additive). Batching them keeps the 2.0 break surface coherent.

Acceptance

• Parse errors expose their rejected input.
• No documented-unreachable MetricsError variants remain (or they are wired
  up).
• One canonical exit-metric spelling across Metric, the field, and Display.
• FunctionSpan::name is Option<String>; error removed.

Part of the pre-2.0 review (#505).

---

Resolution

Implemented on fix/issue-536 (commit fe588965), batched into the 2.0 integration branch. See the resolution comment for full per-item detail.

• Item 1 (breaking): Metric::Exit -> Metric::Nexits, Display -> "nexits"; exit is a hidden FromStr alias for one cycle (not in NAMES). Field/JSON key already nexits, so serialized output is unchanged.
• Item 2 (breaking, partial): Removed NonUtf8Path + ParseHasErrors (never constructed). EmptyRoot kept -- it is still constructed at two defensive .ok_or(MetricsError::EmptyRoot)? guards (src/ops.rs, src/spaces.rs); per the STOP rule, a live error path is not deleted silently. Enum stays #[non_exhaustive].
• Item 3 (breaking): FunctionSpan.name -> Option<String>, error dropped; wire::FunctionSpan DTO + From synced; web /function shape and tests updated.
• Item 4 (additive): input(&self) -> &str on ParseMetricError and ParseLangError.

Full workspace tests + fmt/clippy/doc/xtask/self-scan gates pass; no snapshot drift. Issue left open for the integration branch / acceptance review.

[dekobon]

Resolved decisions (2026-06-05)

1. Exit metric → nexits everywhere. Rename Metric::Exit→Metric::Nexits
and its Display "exit"→"nexits"; the CLI accepts nexits as the canonical
metric name with exit kept as a hidden alias for one cycle. The field and
JSON key are already nexits, so serialized output is unchanged and the
spelling now matches the nargs/nom/npa/npm/nexits "number-of" family.
(Reconciles the split #514 left between Metric::Exit/CLI and the nexits key.)

2. MetricsError → remove the unreachable variants. Drop EmptyRoot,
NonUtf8Path, ParseHasErrors (documented as never produced). The enum stays
#[non_exhaustive], so any future strict mode can re-add them without a break.
Shrinks the surface exhaustive matchers must cover; no behavior change. Keep
LanguageDisabled(LANG).

3. FunctionSpan → name: Option<String>, drop error: bool. Replace the
name="" + error=true sentinel pair with None on parse failure, matching
FuncSpace/Ops. Update the serialized shape accordingly (and the #532 DTO).

4. Parse-error accessors (additive). Add fn input(&self) -> &str to
ParseMetricError and ParseLangError so callers can recover the rejected
string programmatically (today it's Display-only). This part is additive and
may ship before 2.0; the representation is otherwise frozen at 2.0.

Items 1–3 are SemVer-breaking → 2.0. The Metric enum rename and the
FunctionSpan shape change must be cross-referenced against the #532 DTO layer.

[dekobon]

Resolved on fix/issue-536 (commit fe588965), batched into the 2.0 integration branch.

Per-item resolution

1. Exit metric -> nexits (breaking). Renamed Metric::Exit -> Metric::Nexits and its Display "exit" -> "nexits". exit is kept as a hidden FromStr alias for one cycle (deliberately absent from Metric::NAMES, so help/error listings show only nexits). The CodeMetrics::nexits field and JSON key were already nexits, so serialized metric output is byte-for-byte unchanged -- confirmed by zero snapshot churn across the full workspace run (no .snap.new, parent or submodule).

2. MetricsError prune (breaking, partial). Removed NonUtf8Path and ParseHasErrors -- verified never constructed anywhere in the workspace (only doc/match references). The enum stays #[non_exhaustive], so a future strict mode can re-add them without a break.

Deviation from the literal three-variant list, per the prompt's STOP rule. EmptyRoot is constructed at two live sites: src/ops.rs and src/spaces.rs, both let mut state = state_stack.pop().ok_or(MetricsError::EmptyRoot)?;. These are documented-unreachable defensive guards, but they are real construction expressions; removing the variant would require rewriting those .ok_or(...) fallbacks, i.e. deleting a live error path. The task instruction was explicit: "if any IS constructed, STOP and report it rather than deleting a live error path." So EmptyRoot was kept alongside LanguageDisabled(LANG). If you want EmptyRoot gone too, that needs a deliberate decision on what those two guard sites should do when the stack is empty (panic-free fallback vs. a different variant) -- happy to follow up.

3. FunctionSpan (breaking). name: String + error: bool -> name: Option<String> (None on parse failure), error dropped -- matching FuncSpace/Ops. The #532 wire::FunctionSpan DTO and its From were synced; serialized output now drops error and emits name: null on failure. Web /function endpoint emits the new shape (it serializes Vec<FunctionSpan> through the wire DTO); web unit tests updated.

4. Parse-error accessors (additive). Added pub fn input(&self) -> &str to ParseMetricError (src/metric_set.rs) and ParseLangError (src/macros/mod.rs), returning the rejected string by borrow.

Out of scope (left untouched)

MetricKind (src/suppression.rs) keeps its own Exit/"exit" suppression-vocabulary spelling. It is a separate enum, not in the four resolved decisions, and its nexits -> exit alias is independently documented; the in-source suppress-file(... exit ...) markers continue to work (self-scan gates pass).

Tests

• Metric::Nexits.to_string() == "nexits"; "nexits" and the hidden "exit" alias both parse to Metric::Nexits; nexits in NAMES, exit not; Display->FromStr round-trip (existing, still green).
• wire::FunctionSpan JSON round-trip for Some/None name, asserting no error key and name: null on failure.
• ParseMetricError::input() / ParseLangError::input() return the rejected string.
• Full cargo test --workspace --all-features: all pass, zero failures, zero snapshot drift.
• cargo fmt --check, clippy --all-targets (default + --all-features), doc -D warnings, cargo xtask (man-pages clean, no metric-name enumeration changed), make self-scan + make self-scan-headroom all green.

CHANGELOG (for ## [Unreleased], integration branch)

• Items 1-3 are (breaking); item 4 is additive. nexits serialized output unchanged.

[dekobon]

Item 2 — final decision: keep EmptyRoot

The resolved-decisions comment listed EmptyRoot, NonUtf8Path, and
ParseHasErrors for removal as "documented as never produced." On
implementation, only NonUtf8Path and ParseHasErrors are genuinely
dead — both were removed.

EmptyRoot is different: it is constructed at two live
forward-compat guards (src/ops.rs:309, src/spaces.rs:1212 via
.ok_or(MetricsError::EmptyRoot)?) and pinned by the #262 regression
test. It is unreachable in practice today but is a deliberately
retained defensive error path, not dead code. Removing it would delete a
tested guard and force those sites to panic or invent another error.

Decision (confirmed 2026-06-06): keep EmptyRoot. The enum stays
#[non_exhaustive]. The two genuinely-unreachable variants are gone;
the acceptance criterion ("no documented-unreachable variants remain")
is met for those, while EmptyRoot is retained by design.