From 93cbd0c4d69152e364e3b4adf173707ea181962b Mon Sep 17 00:00:00 2001 From: Kinflou Date: Mon, 16 Nov 2026 23:28:55 +0800 Subject: [PATCH 1/2] Read the code generators' features.json, one per generator Generation's combined features.json goes away (generation#159). Each generator publishes its own; the script fetches both and joins their generators, so the Languages pages render as before. --file and --rev become --generator NAME=FILE and --generator-rev. The pages change only in the notice line. The conformance docs now say generation holds the corpus and the harness, and each generator runs it against its own goldens. --- .github/workflows/language-support-drift.yml | 7 +- docs/docs/design/generation.md | 9 ++- docs/docs/design/runtime-repo-structure.md | 2 +- docs/docs/proposals/project-dashboard.md | 7 +- .../shared-runtime-core/verification.md | 5 +- docs/docs/proposals/target-versions.md | 5 ++ docs/docs/reference/conformance/generators.md | 52 ++++++++------ docs/docs/reference/conformance/index.md | 2 +- docs/docs/reference/conformance/reports.md | 2 +- docs/docs/reference/languages/index.md | 2 +- docs/docs/reference/languages/rust.md | 2 +- docs/docs/reference/languages/typescript.md | 2 +- scripts/sync-language-support.py | 70 +++++++++++++++++-- 13 files changed, 126 insertions(+), 41 deletions(-) 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..016e1f5 100644 --- a/docs/docs/reference/languages/rust.md +++ b/docs/docs/reference/languages/rust.md @@ -10,7 +10,7 @@ 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`. diff --git a/docs/docs/reference/languages/typescript.md b/docs/docs/reference/languages/typescript.md index d8761f5..6760591 100644 --- a/docs/docs/reference/languages/typescript.md +++ b/docs/docs/reference/languages/typescript.md @@ -10,7 +10,7 @@ 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`. 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) From d9c02c8a81ad922cda5f18ec7508a651e43205ab Mon Sep 17 00:00:00 2001 From: Kinflou Date: Mon, 16 Nov 2026 23:29:03 +0800 Subject: [PATCH 2/2] Languages: refresh the proven-by lists from the generators' current features.json Not part of the repointing: the committed pages already lagged generation master (fixtures added since the last refresh), so the drift check fails on any change to the script. Separate commit so it can be dropped and merged on its own. --- docs/docs/reference/languages/rust.md | 22 ++++++++++----------- docs/docs/reference/languages/typescript.md | 22 ++++++++++----------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/docs/reference/languages/rust.md b/docs/docs/reference/languages/rust.md index 016e1f5..33e628f 100644 --- a/docs/docs/reference/languages/rust.md +++ b/docs/docs/reference/languages/rust.md @@ -16,31 +16,31 @@ 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 6760591..ddd6229 100644 --- a/docs/docs/reference/languages/typescript.md +++ b/docs/docs/reference/languages/typescript.md @@ -16,31 +16,31 @@ 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` |