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
10 changes: 3 additions & 7 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,13 @@ members = [
# The per-language generators graduated to their own repos (rollout steps 4–5):
# `codegen-typescript` → ComlineProject/comline-typescript,
# `codegen-rust` → ComlineProject/comline-rust.
# They depend on this workspace (`comline-codegen`, and `comline-conformance`'s
# corpus and harness, with the goldens they check kept in their own repos),
# and this workspace depends on neither.
# The `lib-gen/{lua,luau,c,python}` stubs still use the old `comline::…` crate
# path and are unwired — each becomes its own `comline-<lang>` repo when it
# lands. See design/generation.md.

# `comline-conformance` dev-deps the generator crates from their own repos,
# which in turn git-dep `comline-codegen` from *this* repo. Point that back at
# the in-repo crate so the build has one `comline-codegen`, not several.
# (Same-repo path — CI-safe.)
[patch."https://github.com/ComlineProject/generation"]
comline-codegen = { path = "codegen" }

# Local iteration against a sibling `core` checkout — uncomment to build
# `comline-core` from the working tree instead of the pinned git rev. Re-comment
# before pushing; CI has no sibling checkout.
Expand Down
37 changes: 0 additions & 37 deletions FEATURES.md

This file was deleted.

10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,12 @@

## Feature support

What each generator implements, and the conformance fixtures that prove it:
[`FEATURES.md`](FEATURES.md) (also as [`features.json`](features.json)). Both
are generated by the conformance suite; see
[`conformance/README.md`](conformance/README.md#feature-support).
What each generator implements, and the conformance fixtures that prove it, is
in the generator's own repository, which checks it with the corpus and harness
here: `FEATURES.md` (also as `features.json`) in
[`comline-rust`](https://github.com/ComlineProject/comline-rust) and
[`comline-typescript`](https://github.com/ComlineProject/comline-typescript).
See [`conformance/README.md`](conformance/README.md).

## `comline.toml`

Expand Down
9 changes: 5 additions & 4 deletions codegen/src/features.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,11 @@
//! - each generator's claims: a `SUPPORT` table of [`Support`] per feature,
//! handed to [`crate::Registry::register`].
//!
//! The claims are proven, not trusted: `comline-conformance` checks every
//! one against the corpus (a supported feature generates and matches its
//! golden; an ignored one generates exactly what it would without it; an
//! unsupported one is refused). The same detector and tables drive the
//! The claims are proven, not trusted: `comline-conformance`'s harness, run by
//! each generator's own suite, checks every one against the corpus (a
//! supported feature generates and matches its golden; an ignored one
//! generates exactly what it would without it; an unsupported one is
//! refused). The same detector and tables drive the
//! CLI's pre-generation check, `comline targets --features`, the editor's
//! warnings, and the rendered matrix ([`markdown`], [`json`]).

Expand Down
6 changes: 3 additions & 3 deletions codegen/src/modules.rs
Original file line number Diff line number Diff line change
Expand Up @@ -401,9 +401,9 @@ mod tests {
///
/// A shared abstraction is only worth having if it reproduces what it
/// replaces. These assert the exact layouts the committed conformance
/// goldens hold for the `nested_namespace` fixture — `generation`'s
/// `conformance/tests/golden/nested_namespace/{rust,typescript}/` — so a
/// divergence shows up here rather than as golden drift in another repo.
/// goldens hold for the `nested_namespace` fixture — `comline-rust`'s and
/// `comline-typescript`'s `codegen/tests/golden/nested_namespace/<lang>/` —
/// so a divergence shows up here rather than as golden drift in another repo.
#[cfg(test)]
mod parity {
use super::tests_support::*;
Expand Down
16 changes: 8 additions & 8 deletions conformance/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,19 @@ edition = "2021"
license = "GPL-3.0-only"
publish = false

# The codegen conformance corpus: canonical `FrozenUnit` fixtures + golden
# generated output per target language. Catches generator drift and
# cross-language inconsistency, especially as the per-language generators move
# to their own repos. See design/runtime-repo-structure.md (rollout step 3).
# The codegen conformance corpus: canonical `FrozenUnit` fixtures, and the
# generator-agnostic harness that runs a generator over them and checks its
# golden output. The per-language generators live in their own repos and
# depend on this crate - never the other way, so a core change is pinned here
# first and then in each generator, with no round back. See
# design/runtime-repo-structure.md (rollout step 3).

[dependencies]
comline-core = { git = "https://github.com/ComlineProject/core", rev = "69039e7ab05953760bb7a6818f61e98c14b43922" }
# Not dev-only: a `Fixture` states the `Mode` it exercises, so the contract
# types are part of the corpus's own public shape.
comline-codegen = { path = "../codegen" }

[dev-dependencies]
# The harness's own: a generator's entry point returns `eyre::Result`, and the
# feature report is JSON.
eyre = "0.6.8"
serde_json = "1.0"
comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "9aaf1079d743315de784745d616cded42648b840" }
comline-codegen-typescript = { git = "https://github.com/ComlineProject/comline-typescript", rev = "82fec7191722e6680fead8d180b49fea480ee2a0" }
59 changes: 48 additions & 11 deletions conformance/README.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,59 @@
# comline-conformance

The codegen conformance corpus. Rollout step 3 of
`design/runtime-repo-structure.md`.
The codegen conformance corpus and the harness that runs a generator over it.
Rollout step 3 of `design/runtime-repo-structure.md`.

Each fixture in `src/lib.rs` is one schema as a hand-built `Vec<FrozenUnit>`
(not parsed — the corpus pins IR shape, not parser behaviour). `tests/` runs
every registered generator over every fixture and diffs the output against the
checked-in goldens under `tests/golden/<fixture>/<lang>.<ext>`.
Each fixture in `src/lib.rs` is one package as hand-built `Vec<FrozenUnit>`s
(not parsed - the corpus pins IR shape, not parser behaviour). `src/harness.rs`
is the generator-agnostic half: given a `Generator` (its entry point, its
`SUPPORT` table, its `VERSIONS`) it runs the generator over every fixture, at
each of its version boundaries, and diffs the output against golden files.

## Where the generators and their goldens live

Not here. A generator is a repository of its own
([`comline-rust`](https://github.com/ComlineProject/comline-rust),
[`comline-typescript`](https://github.com/ComlineProject/comline-typescript))
that depends on this crate and runs the harness in its own test suite, against
goldens it holds under `codegen/tests/golden/<fixture>/<lang>[@<boundary>]/`.
The dependency goes one way: a generator depends on generation, generation
depends on core, and nothing here depends on a generator. So a change to core
is pinned in generation, then in each generator, and nowhere does it come back.

What stays here is what needs no generator: the corpus itself, the harness, and
the tests of what every generator shares on the requests they get
(`tests/dependency_protocols.rs`, `tests/nested_protocols.rs`).

A generator wires the harness up like this (see either repo's
`codegen/tests/conformance.rs`):

```rust
const GENERATOR: Generator = Generator {
language: "rust",
generate: comline_codegen_rust::generate_rust,
register: comline_codegen_rust::register,
support: comline_codegen_rust::SUPPORT,
versions: comline_codegen_rust::VERSIONS,
};
```

and calls `harness::corpus_matches_golden`, `harness::support_is_proven` and
`harness::the_protocol_generates_what_the_generator_does`. In the generator's
repository:

```sh
cargo test -p comline-conformance # check
CONFORMANCE_BLESS=1 cargo test -p comline-conformance # regenerate goldens
cargo test -p comline-codegen-rust --test conformance # check
CONFORMANCE_BLESS=1 cargo test -p comline-codegen-rust --test conformance # regenerate goldens
```

A blessed golden is **a snapshot of what the generator does now**, not a
statement of what it *should* do. When a generator changes, the diff shows up in
that change's PR and the golden is re-blessed deliberately.

A change to a fixture here changes every generator's output for it, and shows
up as drift in each generator's suite when it pins the new revision: the
generator's PR carries the new goldens.

## Feature support

Each generator states what it implements in its `SUPPORT` table
Expand All @@ -29,8 +66,8 @@ against this corpus:
- an **unsupported** one is refused, with an error naming the feature.

A claim no fixture can back fails the suite, so a new feature comes with a
fixture. The result is written to [`FEATURES.md`](../FEATURES.md) and
[`features.json`](../features.json) at the repository root, regenerated by the
same `CONFORMANCE_BLESS=1` run as the goldens.
fixture. The result is written to the generator's own `FEATURES.md` and
`features.json` at its repository root, regenerated by the same
`CONFORMANCE_BLESS=1` run as its goldens.

See `ComlineProject/docs` → Design → *The `core` ↔ target contract*.
Loading
Loading