refactor!: remove catalog-generated typed constructors from the public API - #316
Merged
Merged
Conversation
…c API Catalog ids and parameter lists no longer shape Rust public items, so catalog-only updates can ship as minor releases. Catalog actions and values are built with Action::call / Value::call. Closes #311 Co-authored-by: Indent <noreply@indent.com>
Address review of #316: state which Value shapes the parser produces for null, eventPlayer, vector, array, and emptyArray; narrow the catalog-only change claim to Rust item names, signatures, and types; correct the #[doc(hidden)] rationale; list ADR-0014 and ADR-0015 in the docs index; read the embedded catalog in the paramNames test; tidy the public API test. Co-authored-by: Indent <noreply@indent.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #311. Parent: #252.
Change
crates/workshop-rs/build.rsand theinclude!of its output inprogram.rs, plus theserde_jsonbuild-dependency. The 474 generated constructors (215 onAction, 259 onValue) are removed rather than kept crate-private, because no crate code used them.Action::call/Value::callare how you build catalog actions and values. The hand-written constructors (Action::disabled,Value::number,string,global_variable,player_variable) and the public enum variants stay.tests/typed_api.rsis replaced bypublic_api::catalog_actions_and_values_are_built_by_canonical_id. It buildsdamage(a 3-parameter action),teleportwithvector, andsetSlowMotion(countOf(array(4, 5, 6)))(arrayis the only variadic value) throughcall. It then validates the program, emits it, re-parses it, and checks bothroundtrip::equivalentand each reparsed id and argument.build.rsused to panic when a catalog entry hadparamsbut noparamNames. The runtime loader falls back toparamsin that case, so I moved the check intocatalog::builtin_entries_with_parameters_declare_reviewed_parameter_names, which parses the embeddedcatalog::CATALOG_DATA.compatibility-facades.mdgains a "Catalog-backed actions and values" section. ADR-0016 records the decision and supersedes ADR-0008 decision 5, following the ADR convention of not rewriting accepted ADRs. Both documents say whichValueshape to use fornull/eventPlayer(the variants) versus other catalog values (call). I also updated the ADR-0008 status and both ADR indexes (docs/README.mdnow also lists the previously missing ADR-0014 and ADR-0015), and dropped "typed APIs" from theparam_namesdoc comments.Contract continuity
Every generated method either called
Self::call(<id>, [args in parameter order])or built a variant directly:null→Value::Null,eventPlayer→Value::EventPlayer,vector→Value::Vector,array/emptyArray→Value::Array. You can build the first kind withcallusing the same id and argument order. The variants are still public.Value::call("vector" | "array" | "emptyArray", …)produces the same shape the parser produces for those values. The one observable difference when migrating:Value::Array(vec![])(whatempty_array()built) counts as 7 elements in aCustom Stringslot, whileValue::call("emptyArray", [])and the parsedEmpty Arraycount 6. Vector and non-empty array counts are identical either way.Validation
cargo semver-checks -p workshop-rs --baseline-rev v0.9.1: 1 of 196 checks fails,inherent_method_missing. It lists 474 distinctAction::*/Value::*methods, and all of them point into the generatedout/typed_api.rs. No other lint fails.Action::{disabled, call}andValue::{number, string, global_variable, player_variable, call}.setSlowMotionincatalog.json(6+/2− lines, not committed):cargo semver-checks --baseline-rev HEADreports "196 pass, no semver update required". A rustdoc JSON diff shows every item unchanged except the value string of the existingcatalog::CATALOG_DATA: &str(the embedded catalog). Its type is unchanged.v0.9.1: the same edit failsmethod_parameter_count_changedforAction::set_slow_motion, needing a major version.cargo fmt --all --check,cargo clippy --workspace --all-targets -- -D warningscargo test --workspace --all-targets: 231 lib (3 ignored), 9 catalog-gen, 102 integration (103 onmain, minus the 3 removed typed-constructor tests, plus 2 new), 15 CLI lib, 15 CLI integration. No existing assertion was changed.cargo run -p workshop-rs --bin workshop-catalog-gen -- check,git diff --checkReview follow-up
An independent review (approve with nits) led to the second commit: documenting the special-value shapes above, narrowing the catalog-only-change claim to Rust item names, signatures, and types, correcting the
#[doc(hidden)]rationale in ADR-0016, reading the embedded catalog in theparamNamestest, and tidying the public API test.Notes
call.roundtrip::equivalenttreatsValue::call("eventPlayer", [])/Value::call("null", [])as different fromValue::EventPlayer/Value::Null, although they emit the same text. The test uses the variants the parser produces.Tag
@indentto continue the conversation here.