refactor(web): consistent error schema, response envelope, and introspection endpoints

[dekobon]

Decided (2026-06-05): uniform JSON error body for all errors; uniform {id, language, <result>} envelope on every endpoint; unit query accepts true/false/1/0 (case-insensitive); add additive /v1/version + /v1/languages. See the resolved-decisions comment.

Summary

The REST surface has inconsistent error-body schemas and response envelopes
across endpoints and content types. Worth standardizing before the /v1 surface
hardens for the long term.

Findings

1. Error body differs by content type. JSON handlers emit structured
   {id, error} (big-code-analysis-web/src/web/server.rs:178,
   server.rs:334); octet-stream/plain handlers emit bare text/plain
"error: <msg>" (server.rs:299, server.rs:373); the 415/405 fallbacks
   emit yet another plain-text shape (server.rs:556). The id correlation
   field exists only in JSON responses. Error-parsing clients must special-case
   per content type.

2. Inconsistent success envelopes. /metrics returns
   {id, language, spaces} (metrics.rs:28), but /function returns
   {id, spans} (function.rs:19) and /comment returns {id, code}
   (comment.rs:18). Only /metrics echoes the detected language; clients of
   /function / /comment cannot learn which grammar was selected.

3. Asymmetric truthiness. WebMetricsInfo.unit is bool in the JSON
   payload (metrics.rs:22) but a bespoke truthy-string set
   ({"1","true","yes","on"}) in the query variant (server.rs:350).

4. No introspection. /ping returns an empty body (server.rs:427); there
   is no /v1/version or /v1/languages endpoint, unlike the Python surface
   (__version__, supported_languages(), language_extensions()). Adding
   endpoints is additive (can land pre-2.0).

Why 2.0-worthy

Items 1–3 freeze response shape; standardizing them is breaking. Item 4 is
additive. Bundling because they all concern the long-term /v1 contract (#517
versioned the routes; this hardens their payloads).

Proposed change

• Standardize one machine-readable error schema (JSON problem-details style)
  across all error responses, or explicitly document the two-shape contract.
• Consider a uniform {id, language, …} success envelope.
• Unify unit truthiness or document the split.
• Add /v1/version + /v1/languages for parity with the Python surface.

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

---

Resolution

Implemented on fix/issue-541 (commit 57c05797); all four decisions landed exactly.

1. Uniform JSON error body — single json_error helper; every error (JSON, octet-stream, 415/405/404) returns {error, id} + correct status. id always present (empty when absent). (breaking)
2. Uniform success envelope — /function + /comment gain id + language (fix(web): /metrics language field emits non-lookup display names (c/c++, c#) #540 slug via guess_language→LANG::name()), matching /metrics. (breaking)
3. unit query flag — true/false/1/0 case-insensitive, else HTTP 400 JSON; dropped yes/on. (breaking)
4. Introspection — GET /v1/version (server + library) and GET /v1/languages (slugs + extensions from the LANG table), plus unprefixed aliases. Added big_code_analysis::VERSION. (additive)

Docs (book commands/rest.md, STABILITY.md) updated; new + updated tests in server_tests.rs; full workspace fmt/clippy/test clean. Self-scan baseline refreshed for the resulting server.rs/lib.rs metric growth. Left open for the integration-branch merge.

[dekobon]

Resolved decisions (2026-06-05)

1. Uniform JSON error body for ALL errors. Every error response — including
on octet-stream/plain endpoints and the 415/405 resource fallbacks — returns a
machine-readable JSON body, e.g. {"error": "<message>", "id": "<echoed-if-present>"},
with the correct HTTP status. Clients parse one error shape regardless of the
success content-type. id is included when the request carried one (empty/omitted
otherwise).

2. Uniform success envelope {id, language, <result>}. Add id + the
detected language to /function and /comment (their result keys spans /
code stay). Every endpoint returns a predictable wrapper and reports which
grammar was selected. (language uses the #540 canonical slug.)

3. unit query flag → normal bool semantics. The query variant accepts
true/false plus 1/0, case-insensitive; anything else is a clear 400.
Mirrors the JSON bool; drop the yes/on leniency. Document the accepted
forms.

4. Introspection endpoints (additive). Add GET /v1/version (server +
library version) and GET /v1/languages (supported languages + extensions,
using the #540 slugs) for parity with the Python surface (__version__,
supported_languages(), language_extensions()). Additive — may ship before
2.0; the alias /version//languages mirrors the existing /ping unprefixed
alias.

Items 1–3 reshape the frozen /v1 payloads (breaking → 2.0); item 4 is additive.
Builds on #517 (which versioned the routes). Coordinate the error/envelope JSON
with the #532 DTO layer if metric payloads are involved.

[dekobon]

Implemented on fix/issue-541 (commit 57c05797), forked from the 2.0 integration branch fix/batch-2026-06-06.

Per-item changes

1. Uniform JSON error body (breaking). All error paths now route through a single json_error(status, error, id) helper emitting {"error": <msg>, "id": <echoed>}. Replaced the bare text/plain error: … bodies on the octet-stream /comment and /metrics endpoints, the text/plain body on /function plain, and the plain bodies on the 415/405 resource fallbacks and the app-level 404. id is always present: the echoed correlation id on JSON endpoints, empty string elsewhere (documented).

2. Uniform success envelope (breaking). /function and /comment JSON responses now carry id + language (their result keys spans / code unchanged), matching /metrics's {id, language, spaces}. language is the #540 canonical slug, routed through guess_language → LANG::name(). The comment endpoint reports the guessed language (e.g. cpp), not the internal ccomment grammar swap.

3. unit query flag → normal bool (breaking). New parse_unit_flag helper: accepts true/false and 1/0 case-insensitively; absent defaults to false; anything else (incl. the dropped yes/on) → HTTP 400 with the uniform JSON error body. Documented in WebMetricsInfo.

4. Introspection endpoints (additive). GET /v1/version → {server, library} (server from env!("CARGO_PKG_VERSION"), library from the new big_code_analysis::VERSION). GET /v1/languages → {languages: [{name, extensions}]} sourced from the LANG table (into_enum_iter + extensions + is_enabled filter, mirroring Python's supported_languages()/language_extensions()), never hardcoded. Unprefixed /version and /languages aliases added, mirroring /ping.

Tests (in server_tests.rs)

• test_web_error_body_uniform_across_endpoints — JSON, octet-stream, 415, 405 all parse as {error, id} with the right status (core regression guard).
• test_web_function_envelope_carries_id_and_language_slug / ..._comment_... — assert id, language == "cpp", and the result key.
• test_web_metrics_plain_unit_flag_accepts_bool_forms (true/TRUE/True/1 clear nested spaces; false/FALSE/0/absent keep them) and ..._rejects_non_bool (yes/on/bogus → 400 JSON).
• test_web_version_endpoint_reports_server_and_library, test_web_languages_endpoint_lists_slugs_and_extensions (asserts cpp slug + cpp extension), test_web_introspection_endpoints_reject_post_with_405 — all covering the /v1 + unprefixed aliases.
• Updated existing comment/function expectations for the new language field and the JSON error shape.

Validation

cargo fmt --check, cargo clippy --workspace --all-targets --all-features -D warnings, and cargo test --workspace --all-features all clean (70 web tests pass). Docs updated: book commands/rest.md (error schema, envelopes, unit forms, new endpoints) and STABILITY.md (slug across all analysis endpoints). Self-scan baseline refreshed for the legitimate server.rs sloc and lib.rs halstead growth.

Note: a pre-existing self-scan red on src/count.rs (nargs = 10 > 7) exists on the integration branch independent of this change; left untouched.

Not closing — leaving for the integration-branch merge.