track(2.0): breaking-change roadmap for the 2.x major bump

[dekobon]

Summary

Tracking issue for the 2.x major bump. A major bump is the only SemVer
window in which the breaking changes below may land. This collects:

1. the loose ends already documented in
   STABILITY.md under "On the 2.0 horizon", and
2. additional candidates surfaced by a pre-2.0 project review (linked under
   Review findings below).

2.0 is not scheduled; this is the staging ground so nothing is forgotten
when it is cut. All issues here are filed against the 2.0 milestone.

Known loose ends (from STABILITY.md)

• Mark the per-metric Stats structs #[non_exhaustive] so field
  additions stop being a strict-SemVer shape break.
• Remove the deprecated metrics / metrics_with_options shims (in
  favour of analyze).
• Decide the fate of the remaining #[doc(hidden)] extension traits
  (ParserTrait, the per-metric compute traits, Parser<T>, Filter):
  delete or formally expose. The hidden state is a holding pattern.
• Land the clean metric-value re-baseline note in the 2.0
  CHANGELOG entry, folding in every value drift accumulated across 1.x
  so consumers have one diff to reason about across the major boundary.
• FilesData / ConcurrentRunner reshape into a terminal file-set
  processor (refactor(cli): single anchored walk seam — library globsets are dead and files are double-stat'd after #489 #495 — already closed; confirm it is reflected at 2.0).

Review findings (filed separately)

Core library API:

• fix(tools): guess_language returns unbound-lifetime &'a str (latent unsoundness) #506 — guess_language returns an unbound-lifetime &'a str (latent
  unsoundness; tighten to &'static str or drop the tuple element) (bug) — ✅ landed on main
• refactor(api): normalize &LANG-by-value and drop Java-style get_ getter prefixes #507 — normalize &LANG-by-value and drop Java-style get_ getter
  prefixes across LANG / LanguageInfo / ParserTrait
• feat(lang): implement Display/FromStr/Hash for the LANG enum #508 — implement Display / FromStr / Hash for LANG — ✅ landed on main
• refactor(lib): get_ops/metrics_from_tree still key identity off a lossy path #509 — get_ops / metrics_from_tree still key identity off a lossy
  path; add a Source-based seam and deprecate the path-positional form

Core architecture (2.0-gated):

• refactor(checker): reshape Checker trait (default predicates, is_primitive(&Node), narrow bounds) #520 — reshape the Checker trait: default bodies for trivial
  predicates (kills per-language stub boilerplate), is_primitive(&Node)
  instead of is_primitive(u16), narrow count_specific_ancestors's
  bound from ParserTrait to Checker

Metrics & output:

• refactor(output): normalize metric JSON/YAML key naming across all Stats #510 — normalize metric JSON/YAML key naming across all Stats
  (sum/average/min/max scheme; misleading nom.functions /
  nargs.total_functions; npa/npm average-as-ratio; abc magnitude
  asymmetry; serialize_struct names)
• fix(halstead): n1/N1/n2/N2 keys are case-only-distinct (CSV/header collisions) #511 — Halstead n1/N1/n2/N2 case-only-distinct keys collide for
  case-insensitive consumers (CSV/env) (bug)
• refactor(metrics): unify average-divisor guarding and denominator convention #512 — unify average-divisor guarding and per-space-vs-per-function
  denominator convention (re-baseline)

CLI:

• refactor(cli): unify output-format selection across subcommands #513 — unify output-format selection across subcommands (flag vs
  positional, -O vs --format, enum consolidation)
• fix(cli): reconcile metric-name spelling between diff --metric and check --threshold #514 — reconcile metric-name spelling between diff --metric and
  check --threshold — ✅ landed on main
• feat(cli): give --ls/--le descriptive long names; reconsider global scope #518 — give --ls/--le descriptive long names; reconsider global

Web (not strictly 2.0-gated — schema/HTTP, not library SemVer):

• feat(web): version REST routes (/v1) before 2.0; revisit Option-in-200 errors #517 — version REST routes (/v1) before 2.0; revisit
  Option-in-200-body error idiom

Filed without the 2.0 milestone (fix anytime — not breaking):

• ✅ fix(web): content-type guards reject 'application/json; charset=utf-8' (silent 404) #515 — web content-type guards reject application/json; charset=utf-8
  (silent 404) (bug) — closed, landed on main
• refactor(web): replace eprintln! error logging with tracing/log #516 — replace eprintln! web error logging with tracing/log
• fix(groovy): closure bodies don't count toward cognitive lambda nesting #519 — (bug) Groovy closure bodies don't count toward cognitive lambda
  nesting (cross-language parity violation; metric fix, lands pre-2.0)
• ✅ perf(node): has_sibling allocates a TreeCursor per call on the JS/TS hot path #521 — perf: Node::has_sibling allocates a TreeCursor per call on the
  JS/TS hot path — closed, landed on main
• ✅ perf(spaces): Elixir per-node source scan runs regardless of metric selection #522 — perf: Elixir per-node source scan runs regardless of metric
  selection — closed, landed on main
• ✅ refactor(node): children() iterator desyncs length (child_count) from data (cursor) #523 — Node::children() iterator desyncs length from data (latent
  dup-yield) — closed, landed on main
• ✅ build(deps): exact-pin tree-sitter-kotlin-ng and CI-guard enums/ grammar-pin lockstep #524 — exact-pin tree-sitter-kotlin-ng; CI-guard enums/ grammar-pin
  lockstep (dependencies) — closed, landed on main
• ✅ build(deps): drop num meta-crate; hoist csv/tempfile into [workspace.dependencies] #525 — drop the num meta-crate; hoist csv/tempfile to workspace deps
  (dependencies) — closed, landed on main
• ✅ docs: stale supported-languages lists (phantom C/Mozcpp; deb/rpm omit 5 langs) #526 — stale supported-languages lists (phantom C/Mozcpp; deb/rpm omit
  5 langs) (documentation) — closed, landed on main

Second-pass review findings (2026-06-05)

A fresh pre-2.0 review across the public Rust API, serialized output schema,
CLI grammar, REST surface, Python bindings, and cross-language metrics surfaced
the following, none overlapping the items above. All filed against the 2.0
milestone except where noted additive.

Bug (fix before the 2.0 re-baseline so values fold in cleanly):

• fix(cognitive): PHP double-counts two-word else if form #529 — (bug) PHP cognitive double-counts the two-word else if form
  (5.0 vs the correct 3.0; isolated to cognitive)

Serialized output schema:

• refactor(output): serialize integer-valued metrics as integers, not f64 #530 — integer-valued metrics are typed f64 and serialize as floats
  ("sloc":5.0); four formats disagree; CBOR bloat
• refactor(output): uniform non-finite & precision policy at the serialize boundary #531 — no uniform non-finite (NaN/Inf→silent JSON null) or precision
  policy at the serialize boundary
• feat(lib): implement Deserialize on the serialization-root types #532 — implement Deserialize on the serialization-root types (the
  library can't read its own output)
• refactor(output): normalize AstNode dump key casing; name the Span tuple #535 — normalize AstNode dump key casing (Type/TextValue/…); name
  the Span 4-tuple
• test(output): add round-trip coverage for TOML/YAML/CBOR formats #543 — add round-trip test coverage for TOML/YAML/CBOR (additive;
  de-risks refactor(output): serialize integer-valued metrics as integers, not f64 #530/refactor(output): uniform non-finite & precision policy at the serialize boundary #531)

Core library API:

• refactor(lib): hide builder-type internal fields (Source/MetricsOptions/MetricsCfg) #533 — hide builder-type internal pub fields
  (Source/MetricsOptions/MetricsCfg)
• refactor(lib): tidy internal-plumbing visibility (Cursor/Callback/LanguageInfo/Node) #534 — tidy internal-plumbing visibility (Cursor is dead public surface;
  Callback/LanguageInfo require a doc-hidden ParserTrait)
• refactor(lib): 2.0 shape & error-type ergonomics cleanups #536 — 2.0 shape & error ergonomics: parse-error accessors, reserved
  MetricsError variants, exit/nexits triple-spelling, FunctionSpan
name: Option<String>
• refactor(lib): CountCfg/FindCfg leak Arc<Mutex>/Arc<[String]> representation #537 — CountCfg/FindCfg leak Arc<Mutex<…>>/Arc<[String]>
  (companion to the refactor(cli): single anchored walk seam — library globsets are dead and files are double-stat'd after #489 #495 reshape)

CLI:

• refactor(cli): cross-subcommand parity (only-filter naming, --output/--strip-prefix on diff family) #538 — cross-subcommand parity (only-filter naming; --output/
  --strip-prefix on the diff family)
• docs(cli): unify/clarify list-merge semantics (--paths-from union vs manifest replace) #539 — clarify/unify list-merge semantics (--paths-from union vs
  manifest replace)

Web & Python (published surfaces, newly represented here):

• fix(web): /metrics language field emits non-lookup display names (c/c++, c#) #540 — /metrics language emits non-lookup display names
  (c/c++, c#) that disagree with the Python surface
• refactor(web): consistent error schema, response envelope, and introspection endpoints #541 — consistent REST error schema, response envelope, and introspection
  endpoints
• docs(stability): bring Python bindings & REST schema under the 2.0 stability contract #542 — bring the Python bindings & REST schema under the written 2.0
  stability contract (name-lock before first PyPI publish; analyze_batch
  default polarity)

Acceptance

• Every checkbox above resolved or explicitly deferred with rationale.
• STABILITY.md "On the 2.0 horizon" section emptied/updated.
• CHANGELOG 2.0.0 section lists every (breaking) change and the
  value re-baseline.

[dekobon]

Filed the pre-2.0 review findings as individual issues against the 2.0
milestone and linked them in the body above.

Bugs worth attention regardless of the 2.0 timeline:

• fix(tools): guess_language returns unbound-lifetime &'a str (latent unsoundness) #506 — guess_language's unbound output lifetime (only sound today because
  every arm happens to be 'static).
• fix(halstead): n1/N1/n2/N2 keys are case-only-distinct (CSV/header collisions) #511 — Halstead n1/N1/n2/N2 case-only keys silently collide in
  case-insensitive CSV/env consumers.
• fix(web): content-type guards reject 'application/json; charset=utf-8' (silent 404) #515 — web rejects application/json; charset=utf-8 with a bodyless 404
  (not 2.0-gated; can ship now).

The largest single win is #510 (output key-naming normalization): the
serialized JSON is the documented-stable surface, so the inconsistent
sum/average/min/max spellings can only be unified at the major bump.

Review scope covered the core library API, all per-metric Stats + output
serializers, and the CLI / web / Python crates. The Python bindings were in
good shape — no 2.0-blocking findings there.

[dekobon]

Second review wave (core AST architecture, per-language metric mirroring,
docs/build hygiene) added the following:

2.0-gated: #520 (Checker trait reshape — the biggest "add-a-language"
ergonomics win).

Bugs / fixes that should land pre-2.0 (not breaking):

• fix(groovy): closure bodies don't count toward cognitive lambda nesting #519 — Groovy closures invisible to cognitive lambda-nesting (verified:
  Java/Kotlin/JS/etc. all have the lambda += 1 arm Groovy lacks). This is
  a cross-language parity violation per lesson build(deps): update tree-sitter-python requirement from =0.23.6 to =0.25.0 in /enums #11.
• build(deps): exact-pin tree-sitter-kotlin-ng and CI-guard enums/ grammar-pin lockstep #524 — tree-sitter-kotlin-ng is the only grammar not exact-pinned; a
  dependabot minor bump can silently shift Kotlin metric values.

Perf (whole-repo hot path): #521 (has_sibling cursor alloc, the same
#217 pattern, missed), #522 (Elixir double source-scan per node).

Robustness/hygiene: #523 (children() iterator length/data desync),
#525 (drop num meta-crate), #526 (stale supported-languages lists).

The per-language modules are otherwise unusually well-mirrored — a
dedicated cross-language parity suite already guards ternary/safe-nav/
boolean-sequence/receiver-exclusion handling. The only genuine divergence
found was the Groovy closure gap (#519).