diff --git a/.github/workflows/language-support-drift.yml b/.github/workflows/language-support-drift.yml index 7288ab4..c3260e6 100644 --- a/.github/workflows/language-support-drift.yml +++ b/.github/workflows/language-support-drift.yml @@ -1,9 +1,10 @@ name: Language support drift # The Reference -> Languages pages are rendered from what the conformance -# suites prove: generation's `features.json`, and the runtime wire corpus -# with each runtime's report. This checks they're current. Like the IDL drift check it needs no Rust build, only a fetch, -# so it runs per pull request. It's kept separate from the Docs workflow, +# suites prove: each code generator's `features.json` (comline-rust's and +# comline-typescript's), and the runtime wire corpus with each runtime's +# report. This checks they're current. Like the IDL drift check it needs no +# Rust build, only a fetch, so it runs per pull request. It's kept separate from the Docs workflow, # because a fetch from another repo shouldn't be able to block a deploy. on: diff --git a/docs/docs/design/generation.md b/docs/docs/design/generation.md index f4a628a..b9dc89e 100644 --- a/docs/docs/design/generation.md +++ b/docs/docs/design/generation.md @@ -229,9 +229,12 @@ CLI-driven functions. G3 takes them the rest of the way, per the The CLI composes a `Registry` at startup via each crate's `register()`. 2. **`comline-typescript`, `comline-rust`.** ✅ Both generators extracted to their own repos (`ComlineProject/comline-typescript`, - `ComlineProject/comline-rust`); `cli` and `generation`'s conformance corpus - depend on them by git rev. `generation` is now just `comline-codegen` + - `comline-conformance`. `comline-rust`'s FFI/dylib work is still G2c. + `ComlineProject/comline-rust`); `cli` depends on them by git rev. + `generation` is now just `comline-codegen` + `comline-conformance`, the + corpus and a generator-agnostic harness. The dependency runs one way: each + generator depends on `generation` and runs the corpus against its own + goldens ([generator conformance](../reference/conformance/generators.md)). + `comline-rust`'s FFI/dylib work is still G2c. 3. **CLI features.** ✅ `comline-codegen-rust` / `-typescript` are optional deps behind `gen-rust` / `gen-typescript` (both default); `generator_registry()` `#[cfg]`-guards each `register()`. A build can drop a generator crate and its diff --git a/docs/docs/design/runtime-repo-structure.md b/docs/docs/design/runtime-repo-structure.md index 4341f4b..0a487d7 100644 --- a/docs/docs/design/runtime-repo-structure.md +++ b/docs/docs/design/runtime-repo-structure.md @@ -205,7 +205,7 @@ big-bang; each step leaves the tree working. |---|---|---|---| | 1 | **`generation` → `comline-codegen`**: strip to contract + helpers + `Registry` | code | The `rust` / `typescript` generator bodies come *out* in step 4; what's left is language-neutral. Consumed by git rev. | | 2 | **[`core ↔ target` contract doc](core-target-contract.md)** ✅ drafted | design doc | Frozen-IR format, IR→types mapping, core-runtime API surface, call-system framing, FFI/ABI. It is a public API across many repos now. | -| 3 | **Conformance corpus** — schema + expected output, standing before the *second* target repo | code | The only thing keeping generators consistent once they don't share a repo. *Codegen half started* — `generation`'s `comline-conformance` crate (hand-built `FrozenUnit` fixtures × every generator, golden-diffed). The runtime half follows once a runtime exists. | +| 3 | **Conformance corpus** — schema + expected output, standing before the *second* target repo | code | The only thing keeping generators consistent once they don't share a repo. *Codegen half done* — `generation`'s `comline-conformance` crate holds the hand-built `FrozenUnit` fixtures and a generator-agnostic harness; each generator repo runs the harness over the corpus against its own goldens and publishes its own `FEATURES.md` / `features.json` (generation depends only on core; see [Generator conformance](../reference/conformance/generators.md)). The runtime half follows once a runtime exists. | | 4 | **`comline-typescript`** — the pilot target repo | code / infra | *Done.* `ComlineProject/comline-typescript` holds `codegen/` (`comline-codegen-typescript`, extracted from `generation`) and `runtime/` (`@comline/runtime`, MPL-2.0, Node): the framing-agnostic contract, `DatagramFraming` + `JsonRpcFraming`, an in-memory `Transport`, and a `Client` / `Server` — the `Handshake` and framing wire formats byte-compatible with `comline-runtime` ([![#6](https://img.shields.io/github/pulls/detail/state/ComlineProject/comline-typescript/6?label=%236)](https://github.com/ComlineProject/comline-typescript/pull/6), [![#7](https://img.shields.io/github/pulls/detail/state/ComlineProject/comline-typescript/7?label=%237)](https://github.com/ComlineProject/comline-typescript/pull/7)). The CLI and the conformance corpus depend on the generator by git rev. Next: the generator emits `Client` / dispatcher against the package, then `libgen` (`lib` mode) and `std-extra`. CI runs a cargo job and a Node job. | | 5 | **`comline-rust`** — generator now; the rust runtime from `runtime-langs/` later | code / infra | *Generator done.* `ComlineProject/comline-rust` holds `codegen/` (`comline-codegen-rust`), extracted from `generation`; the CLI and the conformance corpus depend on it by git rev. `generation` is now just `comline-codegen` + `conformance`. The runtime lift waits for step 7 (and the FFI/dylib G2c). | | 6 | **CLI feature-gated `Registry`** — compose steps 4–5 behind `--features` | code | *Done.* `comline-codegen-rust` / `-typescript` are optional deps behind `gen-rust` / `gen-typescript` (both default); `generator_registry()` `#[cfg]`-guards each `register()`. `--no-default-features --features gen-rust` drops the other's whole dep tree. | diff --git a/docs/docs/proposals/project-dashboard.md b/docs/docs/proposals/project-dashboard.md index bef3fa8..e55d12f 100644 --- a/docs/docs/proposals/project-dashboard.md +++ b/docs/docs/proposals/project-dashboard.md @@ -71,7 +71,12 @@ Decided in round 3 (2026-11-08): history, no chart, no regression view and no way to open an older result. - **The conformance matrices are committed JSON, rendered as static tables:** - generation's - [`features.json`](https://github.com/ComlineProject/generation/blob/HEAD/features.json); + [`features.json`](https://github.com/ComlineProject/generation/blob/HEAD/features.json) + (since replaced by one per generator, in + [comline-rust](https://github.com/ComlineProject/comline-rust/blob/main/features.json) + and + [comline-typescript](https://github.com/ComlineProject/comline-typescript/blob/main/features.json); + the dashboard's `codegen` matrix reads both); - the runtime's [`reports/rust.json`](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/reports/rust.json); - TypeScript's `runtime/conformance-report.json`. diff --git a/docs/docs/proposals/shared-runtime-core/verification.md b/docs/docs/proposals/shared-runtime-core/verification.md index 6152a9b..4f94af0 100644 --- a/docs/docs/proposals/shared-runtime-core/verification.md +++ b/docs/docs/proposals/shared-runtime-core/verification.md @@ -310,7 +310,10 @@ As of the proposal, before the work in [What's built](#whats-built). `unsupported`. - **The codegen corpus** (`generation/conformance/`) checks golden output and `SUPPORT` claims. It proves what a generator emits, not what the emitted code - does on the wire. + does on the wire. (Since then generation holds only the corpus and a + generator-agnostic harness; each generator runs it against its own goldens + and publishes its own `features.json`. See + [Generator conformance](../../reference/conformance/generators.md).) - **There was no fuzzing anywhere in the org.** No repository had a fuzz target, `proptest`, `fast-check`, Jazzer or Atheris (checked on every repository's default branch, 2026-10-25). Rust has them now (runtime#37); diff --git a/docs/docs/proposals/target-versions.md b/docs/docs/proposals/target-versions.md index 89f9da0..590dbba 100644 --- a/docs/docs/proposals/target-versions.md +++ b/docs/docs/proposals/target-versions.md @@ -293,6 +293,11 @@ Shipped in three steps, October 2026: Where it differs from the text: +- **There is no combined `FEATURES.md` or `features.json` in generation.** + Generation holds the fixture corpus and a generator-agnostic harness; each + generator runs it against its own goldens and publishes its own + `FEATURES.md` and `features.json`, which the docs matrix and the Observatory + join. The text above (the conformance and matrix lines) is kept as decided. - **Rust's floor is 1.85, not 1.70.** Building the generated code at 1.70 showed the claim was never true: the runtime's dependencies (`rmp`, `rmp-serde`) use the 2024 edition, which cargo before 1.85 can't read. At diff --git a/docs/docs/reference/conformance/generators.md b/docs/docs/reference/conformance/generators.md index aa4ba50..6659362 100644 --- a/docs/docs/reference/conformance/generators.md +++ b/docs/docs/reference/conformance/generators.md @@ -1,32 +1,43 @@ # Generator conformance How each code generator's output is pinned, and how its feature support is -proven. The source of truth is the generation repository's -[`conformance/README.md`](https://github.com/ComlineProject/generation/blob/master/conformance/README.md). +proven. Generation holds the fixture corpus and a generator-agnostic harness; +each generator runs the harness against its own goldens and publishes its own +report. The source of truth for the corpus and the harness is the generation +repository's +[`conformance/README.md`](https://github.com/ComlineProject/generation/blob/master/conformance/README.md); +each generator's side is its `codegen/tests/conformance.rs` +([comline-rust](https://github.com/ComlineProject/comline-rust), +[comline-typescript](https://github.com/ComlineProject/comline-typescript)). ## Flow -1. **Fixtures.** Each fixture in `conformance/src/lib.rs` is one schema as - hand-built IR (`Vec`), not parsed source. The corpus pins IR - shape, not parser behaviour. -2. **Goldens.** Every registered generator runs over every fixture, and its - output is diffed against `tests/golden//.`. A golden is - a snapshot of what the generator does now, not what it should do: a change - in output shows up in that pull request's diff and is re-blessed - deliberately. +1. **Fixtures.** Each fixture in generation's `conformance/src/lib.rs` is one + schema as hand-built IR (`Vec`), not parsed source. The corpus + pins IR shape, not parser behaviour. A generator pins a revision of + generation, so a change to a fixture reaches it as drift in its own suite, + and its pull request carries the new goldens. +2. **Goldens.** A generator's test describes it to the harness (its language, + entry point, `SUPPORT` table and version boundaries), which runs it over + every fixture and diffs the output against the goldens the generator holds + under `codegen/tests/golden//[@]/`. A golden is a snapshot of + what the generator does now, not what it should do: a change in output + shows up in that pull request's diff and is re-blessed deliberately. 3. **Support claims.** Each generator states what it implements in its - `SUPPORT` table (`comline_codegen::features`). `support_is_proven` checks - every claim against the fixtures. + `SUPPORT` table (`comline_codegen::features`). The harness's + `support_is_proven` checks every claim against the fixtures. 4. **Outputs.** The proven table is written to `FEATURES.md` and - `features.json` at the repository root, by the same run that blesses the - goldens. + `features.json` at the generator's repository root, by the same run that + blesses its goldens. Each file has the generator's own entry in + `generators` and the same `features` list as the other generator's. 5. **Consumers.** The [Languages](../languages/index.md) pages and the - [Observatory](reports.md)'s `codegen` matrix read `features.json` from the - default branch. + [Observatory](reports.md)'s `codegen` matrix read each generator's + `features.json` from its default branch and join them into one table. ```sh -cargo test -p comline-conformance # check -CONFORMANCE_BLESS=1 cargo test -p comline-conformance # regenerate goldens and FEATURES +# in a generator's repository, here comline-rust +cargo test -p comline-codegen-rust --test conformance # check +CONFORMANCE_BLESS=1 cargo test -p comline-codegen-rust --test conformance # regenerate goldens and FEATURES ``` ## Support claims @@ -44,8 +55,9 @@ fixture. | Where | When | Checks | | --- | --- | --- | -| generation | every pull request and push (`cargo test`) | goldens match; every claim is proven; `FEATURES.md` and `features.json` are current | -| docs | weekly (`language-support-drift.yml`) | the Languages pages match `features.json`, the wire corpus and each runtime's report | +| each generator (comline-rust, comline-typescript) | every pull request and push (`cargo test`) | goldens match; every claim is proven; its `FEATURES.md` and `features.json` are current | +| generation | every pull request and push (`cargo test`) | the corpus and the harness build and pass the tests that need no generator | +| docs | weekly (`language-support-drift.yml`) | the Languages pages match both generators' `features.json`, the wire corpus and each runtime's report | Editors and the CLI surface the same table: `comline targets --features` and the language server's warnings for features a target doesn't support. diff --git a/docs/docs/reference/conformance/index.md b/docs/docs/reference/conformance/index.md index cbfb608..a5d0355 100644 --- a/docs/docs/reference/conformance/index.md +++ b/docs/docs/reference/conformance/index.md @@ -41,7 +41,7 @@ flowchart LR | Page | Proves or measures | Gate on pull requests | Published as | | --- | --- | --- | --- | | [Wire conformance](wire.md) | every runtime reproduces the wire contract byte for byte | yes: vectors current, claims proven | `reports/.json` | -| [Generator conformance](generators.md) | each generator's output, and the features it claims | yes: goldens match, claims proven | `features.json` | +| [Generator conformance](generators.md) | each generator's output, and the features it claims | yes: goldens match, claims proven | each generator's `features.json` | | [Fuzzing](fuzzing.md) | the reference's decoders are strict, canonical and panic-free; other runtimes match it on random inputs | yes: 60 s per target | `.fuzz.json` (nightly) | | [Benchmarks](benchmarks.md) | instruction counts of shared and per-repository benchmarks | yes: 1% limit plus the ledger | `.bench.json` | | [Timings, size and coverage](timings.md) | compile time, CI time, artifact sizes, test coverage | no | `.compile.json`, `.size.json`, `.coverage.json`; CI from the API | diff --git a/docs/docs/reference/conformance/reports.md b/docs/docs/reference/conformance/reports.md index 7e5f48c..fe1f077 100644 --- a/docs/docs/reference/conformance/reports.md +++ b/docs/docs/reference/conformance/reports.md @@ -62,7 +62,7 @@ and the rest still build. | Kind | Page | Sources | | --- | --- | --- | -| `conformance` | [Wire](wire.md), [Generators](generators.md) | `wire` matrix: Rust and TypeScript runtime reports; `codegen` matrix: generation's `features.json` | +| `conformance` | [Wire](wire.md), [Generators](generators.md) | `wire` matrix: Rust and TypeScript runtime reports; `codegen` matrix: comline-rust's and comline-typescript's `features.json` | | `fuzz` | [Fuzzing](fuzzing.md) | runtime, comline-typescript | | `bench` | [Benchmarks](benchmarks.md) | runtime, core, comline-typescript | | `compile` | [Timings](timings.md#compile-time) | runtime, core, cli | diff --git a/docs/docs/reference/languages/index.md b/docs/docs/reference/languages/index.md index aa274df..a8b5bfb 100644 --- a/docs/docs/reference/languages/index.md +++ b/docs/docs/reference/languages/index.md @@ -64,7 +64,7 @@ commit. A runtime's suite runs every example against it: ## Code generation, side by side - + | Feature | [rust 1.85.0](rust.md) | [typescript 5.0](typescript.md) | |---|---|---| diff --git a/docs/docs/reference/languages/rust.md b/docs/docs/reference/languages/rust.md index c4ddf25..33e628f 100644 --- a/docs/docs/reference/languages/rust.md +++ b/docs/docs/reference/languages/rust.md @@ -10,37 +10,37 @@ What the [`comline-rust`](https://github.com/ComlineProject/comline-rust) genera for each language feature, and the conformance fixtures that prove it. - + Generator `rust#1.85.0`. | Feature | What it covers | State | Proven by | |---|---|---|---| -| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `format_json`, `format_msgpack`, `bounds`, `chars` | +| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `lockstep`, `format_json`, `format_msgpack`, `bounds`, `chars`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | | enums
`enums` | `enum` declarations | ✅ supported | `enum_basic` | | optional fields
`optional-fields` | fields marked `optional` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `bounds` | -| arrays
`arrays` | variable-length arrays, `T[]` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `bounds` | +| arrays
`arrays` | variable-length arrays, `T[]` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `lockstep`, `bounds` | | fixed-length arrays
`fixed-arrays` | fixed-length arrays, `T[N]` | ✅ supported | `shapes` | | fixed arrays over 32 elements, nested
`large-fixed-arrays-nested` | a `T[N]` with N over 32 anywhere but a field's own, non-optional type: inside another array, optional, an alias, an argument or a return | ❌ unsupported: a fixed array over 32 elements renders only as a struct or error field's own, non-optional type (serde's derive stops at 32) | `large_fixed_arrays_nested` | | unions
`unions` | `union(A B ...)` types | ❌ unsupported: Rust has no anonymous sum type to render one as | `unions` | | type aliases
`type-aliases` | `type Name = ...` declarations | ✅ supported | `validators`, `validators_on_decode`, `bounds` | | constants
`constants` | `const` declarations | ✅ supported | `constant`, `shapes`, `validators`, `validators_on_decode` | -| protocols
`protocols` | `protocol` declarations and their functions | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `framing_jsonrpc`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json`, `format_msgpack` | -| errors
`errors` | `error` declarations | ✅ supported | `protocol`, `error_shapes`, `format_json`, `format_msgpack` | -| functions that throw
`throws` | functions declared with `! Error` | ✅ supported | `protocol`, `error_shapes`, `format_json`, `format_msgpack` | +| protocols
`protocols` | `protocol` declarations and their functions | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `framing_jsonrpc`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `lockstep`, `connections`, `connections_async`, `connections_jsonrpc`, `connections_default`, `format_json`, `format_msgpack`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | +| errors
`errors` | `error` declarations | ✅ supported | `protocol`, `error_shapes`, `lockstep`, `format_json`, `format_msgpack` | +| functions that throw
`throws` | functions declared with `! Error` | ✅ supported | `protocol`, `error_shapes`, `lockstep`, `format_json`, `format_msgpack` | | validators
`validators` | `@validators` on fields and type aliases, checked in generated code | ✅ supported | `validators`, `validators_on_decode` | -| imports between schemas
`imports` | `use` of another schema's declarations | ✅ supported | `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode` | -| nested namespaces
`nested-namespaces` | schemas in subdirectories (`chat::admin`) | ✅ supported | `nested_namespace`, `external_std`, `validators`, `validators_on_decode` | +| imports between schemas
`imports` | `use` of another schema's declarations | ✅ supported | `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `dependency_protocol`, `dependency_and_own_protocols` | +| nested namespaces
`nested-namespaces` | schemas in subdirectories (`chat::admin`) | ✅ supported | `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | | `lib` mode
`lib-mode` | `--mode lib`: a buildable package, not bare source files | ✅ supported | `nested_namespace`, `external_std` | | `external_std`
`external-std` | `[generate] external_std`: `std` referenced as its own package | ✅ supported | `external_std` | | `validate_on_decode`
`validate-on-decode` | `[generate] validate_on_decode`: decoding runs the checks | ✅ supported | `validators_on_decode` | | JSON-RPC framing
`framing-jsonrpc` | `@framing = "jsonrpc"` (or as the package default) | ✅ supported | `framing_jsonrpc`, `connections_jsonrpc` | | no handshake
`handshake-none` | `@handshake = "none"` (or as the package default) | ✅ supported | `handshake_none` | -| `datagram@3` framing
`framing-datagram3` | `@framing = "datagram@3"` (or as the package default): calls addressed by wire numbers | ✅ supported | `framing_datagram3`, `handshake_comline2` | -| `comline@2` handshake
`handshake-comline2` | `@handshake = "comline@2"` (or as the package default): compatibility checked by each version's facts, calls the peer lacks failing locally | ✅ supported | `handshake_comline2` | -| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@3` (the default) or `datagram@2`, or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json`, `format_msgpack` | +| `datagram@3` framing
`framing-datagram3` | `@framing = "datagram@3"` (or as the package default): calls addressed by wire numbers | ✅ supported | `framing_datagram3`, `handshake_comline2`, `connections_default`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | +| `comline@2` handshake
`handshake-comline2` | `@handshake = "comline@2"` (or as the package default): compatibility checked by each version's facts, calls the peer lacks failing locally | ✅ supported | `handshake_comline2`, `connections_default`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | +| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@3` (the default) or `datagram@2`, or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async`, `connections_jsonrpc`, `connections_default`, `format_json`, `format_msgpack`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | | `async`
`async` | `[generate] async`: connection protocols get async handlers and senders | ✅ supported | `connections_async` | -| the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async` | +| the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `lockstep`, `connections`, `connections_async`, `connections_default`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | | the `json@1` format
`format-json` | `wire.format = "json@1"` | ✅ supported | `format_json` | | the `msgpack@1` format
`format-msgpack` | `wire.format = "msgpack@1"` | ✅ supported | `format_msgpack` | | bounds
`bounds` | a maximum or exact length on a string or list (`char[max 64]`, `char[8]`, `T[max N]`), or a depth limit (`@max_depth`): checked while decoding and encoding | ✅ supported | `bounds` | diff --git a/docs/docs/reference/languages/typescript.md b/docs/docs/reference/languages/typescript.md index d8761f5..ddd6229 100644 --- a/docs/docs/reference/languages/typescript.md +++ b/docs/docs/reference/languages/typescript.md @@ -10,37 +10,37 @@ What the [`comline-typescript`](https://github.com/ComlineProject/comline-typesc for each language feature, and the conformance fixtures that prove it. - + Generator `typescript#5.0`. | Feature | What it covers | State | Proven by | |---|---|---|---| -| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `unions`, `large_fixed_arrays_nested`, `format_json`, `bounds`, `chars` | +| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `unions`, `large_fixed_arrays_nested`, `lockstep`, `format_json`, `bounds`, `chars`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | | enums
`enums` | `enum` declarations | ✅ supported | `enum_basic` | | optional fields
`optional-fields` | fields marked `optional` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `large_fixed_arrays_nested`, `bounds` | -| arrays
`arrays` | variable-length arrays, `T[]` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `large_fixed_arrays_nested`, `bounds` | +| arrays
`arrays` | variable-length arrays, `T[]` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `large_fixed_arrays_nested`, `lockstep`, `bounds` | | fixed-length arrays
`fixed-arrays` | fixed-length arrays, `T[N]` | 🟡 partial: rendered as `T[]`: the length isn't part of the type | `shapes`, `large_fixed_arrays_nested` | | fixed arrays over 32 elements, nested
`large-fixed-arrays-nested` | a `T[N]` with N over 32 anywhere but a field's own, non-optional type: inside another array, optional, an alias, an argument or a return | 🟡 partial: rendered as `T[]`: the length isn't part of the type | `large_fixed_arrays_nested` | | unions
`unions` | `union(A B ...)` types | ✅ supported | `unions` | | type aliases
`type-aliases` | `type Name = ...` declarations | ✅ supported | `validators`, `validators_on_decode`, `unions`, `bounds` | | constants
`constants` | `const` declarations | ✅ supported | `constant`, `shapes`, `validators`, `validators_on_decode` | -| protocols
`protocols` | `protocol` declarations and their functions | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `framing_jsonrpc`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json` | -| errors
`errors` | `error` declarations | ✅ supported | `protocol`, `error_shapes`, `format_json` | -| functions that throw
`throws` | functions declared with `! Error` | ✅ supported | `protocol`, `error_shapes`, `format_json` | +| protocols
`protocols` | `protocol` declarations and their functions | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `framing_jsonrpc`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `lockstep`, `connections`, `connections_async`, `connections_jsonrpc`, `connections_default`, `format_json`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | +| errors
`errors` | `error` declarations | ✅ supported | `protocol`, `error_shapes`, `lockstep`, `format_json` | +| functions that throw
`throws` | functions declared with `! Error` | ✅ supported | `protocol`, `error_shapes`, `lockstep`, `format_json` | | validators
`validators` | `@validators` on fields and type aliases, checked in generated code | ⚪ ignored: the types are generated; the checks aren't run yet ([core#96](https://github.com/ComlineProject/core/issues/96)) | `validators`, `validators_on_decode` | -| imports between schemas
`imports` | `use` of another schema's declarations | ✅ supported | `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode` | -| nested namespaces
`nested-namespaces` | schemas in subdirectories (`chat::admin`) | ✅ supported | `nested_namespace`, `external_std`, `validators`, `validators_on_decode` | +| imports between schemas
`imports` | `use` of another schema's declarations | ✅ supported | `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `dependency_protocol`, `dependency_and_own_protocols` | +| nested namespaces
`nested-namespaces` | schemas in subdirectories (`chat::admin`) | ✅ supported | `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | | `lib` mode
`lib-mode` | `--mode lib`: a buildable package, not bare source files | ✅ supported | `nested_namespace`, `external_std` | | `external_std`
`external-std` | `[generate] external_std`: `std` referenced as its own package | ✅ supported | `external_std` | | `validate_on_decode`
`validate-on-decode` | `[generate] validate_on_decode`: decoding runs the checks | ⚪ ignored: no checks are generated to run on decode yet ([core#96](https://github.com/ComlineProject/core/issues/96)) | `validators_on_decode` | | JSON-RPC framing
`framing-jsonrpc` | `@framing = "jsonrpc"` (or as the package default) | ✅ supported | `framing_jsonrpc`, `connections_jsonrpc` | | no handshake
`handshake-none` | `@handshake = "none"` (or as the package default) | ✅ supported | `handshake_none` | -| `datagram@3` framing
`framing-datagram3` | `@framing = "datagram@3"` (or as the package default): calls addressed by wire numbers | ✅ supported | `framing_datagram3`, `handshake_comline2` | -| `comline@2` handshake
`handshake-comline2` | `@handshake = "comline@2"` (or as the package default): compatibility checked by each version's facts, calls the peer lacks failing locally | ✅ supported | `handshake_comline2` | -| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@3` (the default) or `datagram@2`, or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json` | +| `datagram@3` framing
`framing-datagram3` | `@framing = "datagram@3"` (or as the package default): calls addressed by wire numbers | ✅ supported | `framing_datagram3`, `handshake_comline2`, `connections_default`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | +| `comline@2` handshake
`handshake-comline2` | `@handshake = "comline@2"` (or as the package default): compatibility checked by each version's facts, calls the peer lacks failing locally | ✅ supported | `handshake_comline2`, `connections_default`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | +| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@3` (the default) or `datagram@2`, or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async`, `connections_jsonrpc`, `connections_default`, `format_json`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | | `async`
`async` | `[generate] async`: connection protocols get async handlers and senders | ⚪ ignored: handlers and senders always return Promises: the output is async either way | `connections_async` | -| the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async` | +| the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `lockstep`, `connections`, `connections_async`, `connections_default`, `dependency_protocol`, `dependency_and_own_protocols`, `nested_protocol` | | the `json@1` format
`format-json` | `wire.format = "json@1"` | ✅ supported | `format_json` | | the `msgpack@1` format
`format-msgpack` | `wire.format = "msgpack@1"` | ❌ unsupported: `@comline/runtime` has no MessagePack codec yet | `format_msgpack` | | bounds
`bounds` | a maximum or exact length on a string or list (`char[max 64]`, `char[8]`, `T[max N]`), or a depth limit (`@max_depth`): checked while decoding and encoding | ✅ supported | `bounds` | diff --git a/scripts/sync-language-support.py b/scripts/sync-language-support.py index a3a6b1e..423112c 100644 --- a/scripts/sync-language-support.py +++ b/scripts/sync-language-support.py @@ -3,8 +3,11 @@ Two conformance suites feed the pages: -- `ComlineProject/generation`'s checks every code generator's feature claims - and writes `features.json` at its root; +- the code generators': generation holds the fixture corpus and a + generator-agnostic harness, and each generator runs it against its own + goldens and writes its own `features.json` at its repository root (see + `GENERATORS`). The two files have the same `features` list and one entry + each in `generators`; this joins them; - `ComlineProject/runtime`'s wire corpus (`runtime/conformance/`) checks every runtime's claims; each runtime writes a report (see `RUNTIMES`). @@ -36,7 +39,9 @@ python3 scripts/sync-language-support.py # rewrite the pages python3 scripts/sync-language-support.py --check # exit 1 on drift - python3 scripts/sync-language-support.py --file ../generation/features.json \\ + python3 scripts/sync-language-support.py \\ + --generator rust=../comline-rust/features.json \\ + --generator typescript=../comline-typescript/features.json \\ --runtime-features ../runtime/runtime/conformance/spec/features.json \\ --runtime-report rust=../runtime/runtime/conformance/reports/rust.json \\ --divergences typescript=../comline-typescript/runtime/known-divergences.json @@ -66,7 +71,7 @@ BUILD_TIMEOUT = 10 RAW = "https://raw.githubusercontent.com/ComlineProject/{repo}/{rev}/{path}" NOTICE = ( - "" ) RUNTIME_NOTICE = ( @@ -74,6 +79,14 @@ "scripts/sync-language-support.py - don't edit by hand. -->" ) +# Where each language's code generator publishes its features.json, on the +# repository's default branch: (repository, path in it). The order is the +# order of the columns. +GENERATORS = { + "rust": ("comline-rust", "features.json"), + "typescript": ("comline-typescript", "features.json"), +} + # The wire corpus, and where each language's runtime writes its report: # (repository, path in it). CORPUS = ("runtime", "runtime/conformance/spec/features.json") @@ -180,6 +193,27 @@ def fetch_report(repo: str, rev: str, path: str) -> dict | None: return None +def join_generators(files: dict[str, dict]) -> dict: + """What generation's combined `features.json` used to be: the `features` + list every generator's file carries, and every file's `generators`, in + `GENERATORS` order. The files must agree on the features, or the + generators were proven against different corpora.""" + first = next(iter(files)) + for name, doc in files.items(): + if doc["features"] != files[first]["features"]: + sys.exit( + f"error: {name}'s features.json lists different features than {first}'s: " + "the generators were proven against different corpora" + ) + names = [g["name"] for g in doc["generators"]] + if names != [name]: + sys.exit(f"error: {name}'s features.json should hold one generator, `{name}`, not {names}") + return { + "features": files[first]["features"], + "generators": [g for doc in files.values() for g in doc["generators"]], + } + + def link_issues(text: str) -> str: return ISSUE_RE.sub(lambda m: f"[{m[0]}](https://github.com/ComlineProject/{m[1]}/issues/{m[2]})", text) @@ -439,8 +473,18 @@ def main() -> int: help=f"write the bench and fuzz sections for the site build (default: {GENERATED.relative_to(ROOT)}); " "never fails on a fetch", ) - parser.add_argument("--file", type=Path, help="read generation's features.json from here instead of fetching it") - parser.add_argument("--rev", default="master", help="generation revision to fetch (default: master)") + parser.add_argument( + "--generator", + action="append", + default=[], + metavar="NAME=FILE", + help="read generator NAME's features.json from FILE instead of fetching it (repeatable)", + ) + parser.add_argument( + "--generator-rev", + default="main", + help="revision of the generator repositories to fetch (default: main)", + ) parser.add_argument("--runtime-features", type=Path, help="read the wire corpus's features.json from here") parser.add_argument( "--runtime-report", @@ -465,6 +509,11 @@ def main() -> int: ) args = parser.parse_args() + local_generators = dict(arg.split("=", 1) for arg in args.generator) + for name in local_generators: + if name not in GENERATORS: + sys.exit(f"error: unknown generator `{name}` (known: {', '.join(GENERATORS)})") + local_reports = dict(arg.split("=", 1) for arg in args.runtime_report) for name in local_reports: if name not in RUNTIMES: @@ -485,7 +534,14 @@ def main() -> int: render_reports(args.render_reports, args.runtime_rev, local) return 0 - report = read_json(args.file, "generation", args.rev, "features.json") + report = join_generators( + { + name: read_json( + Path(local_generators[name]) if name in local_generators else None, repo, args.generator_rev, path + ) + for name, (repo, path) in GENERATORS.items() + } + ) corpus = read_json(args.runtime_features, CORPUS[0], args.runtime_rev, CORPUS[1]) runtimes = { name: read_json(Path(local_reports[name]) if name in local_reports else None, repo, args.runtime_rev, path)