docs(stability): bring Python bindings & REST schema under the 2.0 stability contract

[dekobon]

Decided (2026-06-05): expose enum.StrEnum for languages/metrics (codegen from the LANG table; Lang.CPP == "cpp"); align analyze_batch to skip_generated=True + expose the 3 kwargs; lock Python dist/import/module names in STABILITY.md before first PyPI publish. See the resolved-decisions comment.

Summary

STABILITY.md and the #505 roadmap describe the Rust library contract and the
CLI artifact formats, but the Python bindings (big-code-analysis-py) and the
REST schema (big-code-analysis-web) are absent from the written stability
contract. Both are published surfaces; for a long-term 2.x they need an explicit
contract, especially the Python names, which cannot change after the first PyPI
publish.

Decisions to record (mostly documentation, one default)

1. Lock the Python distribution/import names (big-code-analysis dist /
   big_code_analysis import / big_code_analysis._native compiled module —
   big-code-analysis-py/pyproject.toml). The import name cannot change
   post-publish without breaking every consumer. README still says "not yet
   published on PyPI" (big-code-analysis-py/README.md) — update before publish.

2. Document the string-enum decision as intentional. supported_languages()
   → list[str], METRIC_NAMES → tuple[str, ...], AnalysisError.error_kind
   → Literal[...] (big-code-analysis-py/src/lib.rs, _native.pyi). This is
   a deliberate, good design (strings round-trip with the CLI JSON
   language/metric vocabulary; Literal gives static-checker safety without a
   runtime enum). Record it as a 2.0 stability decision rather than converting
   to enum.Enum.

3. analyze_batch default polarity (the one breaking item).
   analyze_batch hardcodes skip_generated=False
   (big-code-analysis-py/src/batch.rs:363), the inverse of analyze's True.
   Migrating a comprehension from analyze to analyze_batch silently changes
   generated-file handling. Decide at 2.0 whether the default should align with
   analyze. Exposing the three hardcoded kwargs
   (exclude_tests/allow_lossy_path/skip_generated) is additive and can land
   anytime.

Why 2.0-worthy

The name-locking and contract-documentation must precede the first stable Python
publish; the skip_generated default is breaking. The Python surface is
otherwise 2.0-ready (excellent error mapping, PEP 561 stubs, mypy --strict +
pyright gated).

Acceptance

• STABILITY.md gains a "Python bindings" section (name lock, string-enum
  rationale, error-mapping contract) and a "REST schema" section.
• analyze_batch's skip_generated default decided and documented.
• track(2.0): breaking-change roadmap for the 2.x major bump #505 roadmap references the Python/web surfaces.

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

Resolution

Implemented on fix/issue-542 (commit 3220e2a). All three resolved
decisions landed:

1. StrEnum Lang / MetricName (big_code_analysis._enums),
   generated from the live LANG::name() slugs (fix(web): /metrics language field emits non-lookup display names (c/c++, c#) #540) and
   Metric::NAMES by big-code-analysis-py/src/codegen.rs with a
   cargo test drift gate. Lang.CPP == "cpp";
   supported_languages() -> list[Lang],
   METRIC_NAMES -> tuple[MetricName, ...] (typed in the package
   facade; the _native FFI stays plain str). error_kind kept as
   a Literal. (Generator lives in the bindings crate, not enums/,
   because enums/ cannot see the fix(web): /metrics language field emits non-lookup display names (c/c++, c#) #540 slugs — see the resolution
   comment for the rationale.)
2. analyze_batch skip_generated default flipped False -> True
   to align with analyze (breaking); exclude_tests /
   allow_lossy_path / skip_generated exposed as kwargs (additive).
3. STABILITY.md gained Python-bindings (name lock, StrEnum
   contract, error mapping, PEP 561) and REST-schema (fix(web): /metrics language field emits non-lookup display names (c/c++, c#) #540/refactor(web): consistent error schema, response envelope, and introspection endpoints #541 /v1
   shape) sections, plus 2.0-horizon entries; README + book updated.

All cargo + Python gates (ruff / mypy --strict / pyright / maturin +
pytest) pass. Breaking: default flip + typed returns; additive:
StrEnums, kwargs, docs. Left open for review/merge — not closing.

[dekobon]

Resolved decisions (2026-06-05)

1. Python enums → enum.StrEnum (str subclass). Expose languages and metric
names as StrEnums (Python ≥3.12 is the floor) so Lang.CPP == "cpp" is True —
IDE autocomplete + discoverability and the values still round-trip with the
CLI/JSON #540 canonical slugs. Generate the enum from the same source as the Rust
LANG table (reuse the enums/ codegen) so it can't drift. error_kind can stay
a Literal or become a small StrEnum too. Return types shift
(supported_languages() -> list[Lang], etc.) — a typed improvement; the values
remain string-compatible.

2. analyze_batch → default skip_generated=True. Align with analyze so
switching between them is behavior-preserving (least surprise). Expose
exclude_tests / allow_lossy_path / skip_generated as real kwargs
(additive). The default flip is the only breaking part → 2.0.

3. Lock the Python names in STABILITY.md before the first PyPI publish
(plan item, no fork). Distribution big-code-analysis, import
big_code_analysis, compiled module big_code_analysis._native (doc-hidden).
The import name can't change post-publish without breaking every consumer.
Update the README ("not yet published on PyPI") at publish time. Add a "Python
bindings" section to STABILITY.md (name lock, StrEnum contract, error-mapping
contract) and a "REST schema" section (the #540/#541 /v1 shape).

StrEnum + kwargs are largely additive; the analyze_batch default flip and the
return-type changes are the 2.0-breaking pieces.

[dekobon]

Implemented on fix/issue-542 (commit 3220e2a)

All three resolved decisions landed.

1. StrEnum languages + metrics (generated, drift-gated)

• New Lang / MetricName enum.StrEnums in
  big_code_analysis._enums, generated from the live
  LANG::name() slugs (fix(web): /metrics language field emits non-lookup display names (c/c++, c#) #540) and Metric::NAMES by
  big-code-analysis-py/src/codegen.rs. A cargo test drift gate
  (enums_module_matches_checked_in) fails if the checked-in
  _enums.py diverges; regenerate with
  BCA_PY_REGEN_ENUMS=1 cargo test -p big-code-analysis-py enums_module.
• Values confirmed exactly equal to the fix(web): /metrics language field emits non-lookup display names (c/c++, c#) #540 slugs:
  Lang.CPP == "cpp", Lang.CSHARP == "csharp", Lang.TSX == "tsx",
  and set(supported_languages()) == set(Lang).
• Return types shifted: supported_languages() -> list[Lang],
  METRIC_NAMES: tuple[MetricName, ...] (typed in the package facade,
  which wraps the still-str-returning _native layer — the FFI
  boundary stays plain strings for robustness). Because StrEnum
  members are str, existing string call sites are unaffected.
• Design note / deviation: the generator lives in the bindings
  crate, not enums/. The enums/ helper keeps its own
  hand-maintained Lang list with CamelCase names and does not
  depend on big-code-analysis, so it cannot see the fix(web): /metrics language field emits non-lookup display names (c/c++, c#) #540 slugs —
  sourcing the enum there would have introduced the drift the issue
  wants to avoid. Generating from LANG::name() where the crate
  already depends on the library keeps a single source of truth.
• error_kind kept as Literal["UnsupportedLanguage", "ParseError", "IoError"] (closed set, no runtime enum needed).

2. analyze_batch alignment

• skip_generated default flipped False -> True to match analyze
  (the only breaking part). A generated file is now skipped, so the
  result list can be shorter than the input; pass
  skip_generated=False for the legacy one-element-per-input.
• Exposed exclude_tests, allow_lossy_path, skip_generated as
  real keyword-only kwargs mirroring analyze (additive).
• The Ok(None) arm now means "skipped" (omit) rather than a
  synthetic internal error.

3. STABILITY.md + name lock

• New Python bindings section: dist big-code-analysis, import
  big_code_analysis, private compiled big_code_analysis._native,
  StrEnum value==slug contract, error_kind mapping, PEP 561 typing.
• New REST schema section recording the fix(web): /metrics language field emits non-lookup display names (c/c++, c#) #540/refactor(web): consistent error schema, response envelope, and introspection endpoints #541 /v1 shape
  ({id, language} envelope, uniform {error, id} errors,
  introspection routes) — extends rather than duplicates the existing
  slug-as-single-identifier note and the book's rest.md reference.
• 2.0-horizon entries added for the batch flip / typed returns (docs(stability): bring Python bindings & REST schema under the 2.0 stability contract #542)
  and the REST reshape (refactor(web): consistent error schema, response envelope, and introspection endpoints #541).
• py README: documents the publish-time name lock (still "not yet on
  PyPI"); StrEnum + analyze_batch kwargs documented in README and the
  book Python pages.

Tests

• Rust: enums_module_matches_checked_in,
  lang_slugs_match_supported_languages,
  render_enum_rejects_non_identifier_values
  (big-code-analysis-py/src/codegen.rs).
• Python (tests/test_enums.py): Lang.CPP == "cpp" etc.,
  values == supported_languages(), Lang(member.value) is member
  round-trip, MetricName == metric vocabulary, member usable as a
  metrics= selector.
• Python (tests/test_batch.py): generated file skipped by default
  (the behaviour test that fails against the old False default —
  verified by test-via-revert), skip_generated=False restores
  one-per-input, exclude_tests / allow_lossy_path kwargs effective.

Gates run green

cargo fmt --check, cargo clippy --workspace --all-targets
(default + --all-features, -D warnings),
cargo test --workspace --all-features (all pass),
cargo doc (RUSTDOCFLAGS=-D warnings),
and the Python suite via the crate venv: ruff check,
ruff format --check, mypy --strict, pyright (0 errors),
maturin develop + pytest (201 passed, 1 xfailed). rumdl clean on
the edited Markdown.

CHANGELOG (not edited per 2.0 workflow — entry text)

• **(breaking)** analyze_batch default skip_generated flips to
  True; supported_languages() returns list[Lang] and
  METRIC_NAMES becomes tuple[MetricName, ...].
• (additive) Lang / MetricName StrEnums; analyze_batch gains
  exclude_tests / allow_lossy_path / skip_generated kwargs;
  STABILITY Python/REST sections; docs.