Strict descriptions + endpoint-libs 2.0 lockstep

[pathscale]

Note

Unblocked. pathscale/endpoint-libs#41 is merged and endpoint-libs 2.0.0-alpha.1 is published to crates.io. The temporary [patch.crates-io] override has been removed (bb41d73) and the dependency now resolves from the registry. Ready to merge.

Two independent pieces of work that happened to share a working tree, committed separately.

1. Strict descriptions (b856571)

Descriptions in the RON are not cosmetic. An endpoint description is the MCP tool description an agent reads to decide whether to call the tool; enum-variant descriptions are emitted into generated JSON schemas and doc comments. A blank one produces a tool an agent cannot use correctly and a doc page that says nothing — with no signal at generation time.

Generation now fails on missing or whitespace-only descriptions for endpoints (EndpointSchema and EndpointSchemaList) and enum variants (Enum and EnumList). Violations are collected across all files and reported together, so one run tells you everything to fix rather than one item per run. Each line names the file, service and item:

Error: Empty-description validation failed for 2 item(s). ...
./config/010_test.ron: service 'testApi' endpoint 'BadEndpoint': missing or empty description
./config/020_enums.ron: enum 'userRole' variant 'Guest': missing or empty description

--allow-empty-descriptions restores the previous behaviour for consumers not ready to annotate everything.

Also stops emitting an empty /// line for blank descriptions, which tripped clippy::empty_docs downstream. Fixed in both enum-emitting paths — EnumElement::to_rust_decl (RON enum definitions) and Type::to_rust_decl (shared Type::Enum) — which are separate near-identical code paths, hence a test for each.

Struct fields are deliberately not validated: Field.description is #[serde(skip)] upstream, so a RON file cannot express one.

2. Error-code validation (9c710a2)

ErrorCodeList was falling through a catch-all _ => {} arm. That looked like an oversight rather than a decision — the test asserting the exclusion was named ..._ignores_structs_and_error_codes but only exercised structs, and its comment justified only the struct case.

Error-code descriptions are load-bearing the same way: they become the doc comments on the generated EnumErrorCode variants and the third column of docs/error_codes/error_codes.md. A blank one yields an error a caller cannot interpret from either artifact.

• Blank error-code descriptions are now reported, naming the code and its number.
• The catch-all is replaced with an explicit Struct | StructList arm, so a future Definition variant becomes a compile error here rather than another silent gap — the same failure mode this commit fixes.
• The misnamed test is split into ..._ignores_structs and a new ..._flags_blank_error_codes.
• The top-level failure message now names all three validated kinds; it previously understated what runs.

3. endpoint-libs 2.0 lockstep (d9e67c3, bb41d73)

2.0 makes several schema-model types #[non_exhaustive] so OpenAPI/AsyncAPI emission can ship as a 2.1 minor rather than a 3.0. That forbids struct literals and exhaustive matches from outside that crate, breaking endpoint-gen in three places:

• From<EndpointSchemaElement> for EndpointSchema was a field-by-field copy. Now a move of the inner schema — what it always meant, and it stops silently dropping fields added later (it would have dropped the new meta field).
• The Type match in to_rust_ref gains a wildcard arm that panics with an actionable message. Panicking is right: emitting Rust for an unknown type would produce silently wrong generated code.
• A test constructing EndpointErrorSchema by literal now uses the constructor added upstream for this purpose.

Verification

Not just unit tests — the real CLI was driven against scratch RON files:

• strict mode fails with a blank endpoint description and a blank enum variant, both listed
• strict mode fails with a blank error-code description, naming code and number
• --allow-empty-descriptions generates successfully
• generated model.rs has a doc comment on the documented variant, no doc line on the blank one, and zero bare /// lines
• documented error-code text appears in both error_codes.md and the generated model
• 11 tests green, clippy clean (-D warnings)

b856571 was verified to build and test green against published endpoint-libs 1.9.0 before the lockstep commit was applied, so the feature stands on its own. The final state is verified against the published 2.0.0-alpha.1 from crates.io, not a local path.

Note the exact-version pin is deliberate: 2.0.0-alpha.1 is a pre-release, and a plain "2.0" requirement would not match it.

🤖 Generated with Claude Code