Skip to content

refactor!: remove catalog-generated typed constructors from the public API - #316

Merged
Teakowa merged 2 commits into
mainfrom
feat/remove-typed-constructors-311
Sep 27, 2026
Merged

Teakowa merged 2 commits into
mainfrom
feat/remove-typed-constructors-311

Conversation

@e54-bot

@e54-bot e54-bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Closes #311. Parent: #252.

Change

  • Delete crates/workshop-rs/build.rs and the include! of its output in program.rs, plus the serde_json build-dependency. The 474 generated constructors (215 on Action, 259 on Value) are removed rather than kept crate-private, because no crate code used them.
  • Action::call / Value::call are 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: tests/typed_api.rs is replaced by public_api::catalog_actions_and_values_are_built_by_canonical_id. It builds damage (a 3-parameter action), teleport with vector, and setSlowMotion(countOf(array(4, 5, 6))) (array is the only variadic value) through call. It then validates the program, emits it, re-parses it, and checks both roundtrip::equivalent and each reparsed id and argument.
  • build.rs used to panic when a catalog entry had params but no paramNames. The runtime loader falls back to params in that case, so I moved the check into catalog::builtin_entries_with_parameters_declare_reviewed_parameter_names, which parses the embedded catalog::CATALOG_DATA.
  • Docs: compatibility-facades.md gains 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 which Value shape to use for null / eventPlayer (the variants) versus other catalog values (call). I also updated the ADR-0008 status and both ADR indexes (docs/README.md now also lists the previously missing ADR-0014 and ADR-0015), and dropped "typed APIs" from the param_names doc 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 with call using 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![]) (what empty_array() built) counts as 7 elements in a Custom String slot, while Value::call("emptyArray", []) and the parsed Empty Array count 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 distinct Action::* / Value::* methods, and all of them point into the generated out/typed_api.rs. No other lint fails.
  • Rustdoc JSON on this branch: the only inherent methods left are Action::{disabled, call} and Value::{number, string, global_variable, player_variable, call}.
  • Catalog-only edit test: add a second parameter to setSlowMotion in catalog.json (6+/2− lines, not committed):
    • on this branch: cargo semver-checks --baseline-rev HEAD reports "196 pass, no semver update required". A rustdoc JSON diff shows every item unchanged except the value string of the existing catalog::CATALOG_DATA: &str (the embedded catalog). Its type is unchanged.
    • on v0.9.1: the same edit fails method_parameter_count_changed for Action::set_slow_motion, needing a major version.
  • cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings
  • cargo test --workspace --all-targets: 231 lib (3 ignored), 9 catalog-gen, 102 integration (103 on main, 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 --check

Review 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 the paramNames test, and tidying the public API test.

Notes

  • No downstream migration is needed. As stated in Remove catalog-generated typed constructors from the public API before 1.0 #311, opy-rs, Wright, and deltin-rs only use call.
  • Existing behavior, unchanged here: roundtrip::equivalent treats Value::call("eventPlayer", []) / Value::call("null", []) as different from Value::EventPlayer / Value::Null, although they emit the same text. The test uses the variants the parser produces.

View in Indent
Tag @indent to continue the conversation here.

Teakowa and others added 2 commits September 27, 2026 18:21
…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>
@Teakowa
Teakowa enabled auto-merge (squash) September 27, 2026 10:53
@Teakowa
Teakowa merged commit 359df0c into main Sep 27, 2026
8 checks passed
@Teakowa
Teakowa deleted the feat/remove-typed-constructors-311 branch September 27, 2026 10:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Remove catalog-generated typed constructors from the public API before 1.0

2 participants