Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .github/workflows/language-support-drift.yml
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
9 changes: 6 additions & 3 deletions docs/docs/design/generation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/design/runtime-repo-structure.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<Proto>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. |
Expand Down
7 changes: 6 additions & 1 deletion docs/docs/proposals/project-dashboard.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
5 changes: 4 additions & 1 deletion docs/docs/proposals/shared-runtime-core/verification.md
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
5 changes: 5 additions & 0 deletions docs/docs/proposals/target-versions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
52 changes: 32 additions & 20 deletions docs/docs/reference/conformance/generators.md
Original file line number Diff line number Diff line change
@@ -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<FrozenUnit>`), 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/<fixture>/<lang>.<ext>`. 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<FrozenUnit>`), 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/<fixture>/<lang>[@<boundary>]/`. 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
Expand All @@ -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.
2 changes: 1 addition & 1 deletion docs/docs/reference/conformance/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<lang>.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 | `<lang>.fuzz.json` (nightly) |
| [Benchmarks](benchmarks.md) | instruction counts of shared and per-repository benchmarks | yes: 1% limit plus the ledger | `<name>.bench.json` |
| [Timings, size and coverage](timings.md) | compile time, CI time, artifact sizes, test coverage | no | `<name>.compile.json`, `.size.json`, `.coverage.json`; CI from the API |
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/reference/conformance/reports.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/reference/languages/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ commit. A runtime's suite runs every example against it:
## Code generation, side by side

<!-- matrix:start -->
<!-- Rendered from ComlineProject/generation's features.json by scripts/sync-language-support.py - don't edit by hand. -->
<!-- Rendered from each code generator's features.json by scripts/sync-language-support.py - don't edit by hand. -->

| Feature | [rust 1.85.0](rust.md) | [typescript 5.0](typescript.md) |
|---|---|---|
Expand Down
Loading
Loading