diff --git a/docs/docs/developer/extending/encodings.md b/docs/docs/developer/extending/encodings.md index 36663c6..b5a96d9 100644 --- a/docs/docs/developer/extending/encodings.md +++ b/docs/docs/developer/extending/encodings.md @@ -210,7 +210,7 @@ wins: 1. **The consumer's override**, in `comline.toml`. 2. **The declaring package's `map`** for that language. -If neither answers for an encoding the package uses, `comline generate` fails +If neither answers for an encoding the package uses, `comline generation` fails with one sentence per encoding: ```text diff --git a/docs/docs/developer/extending/generators.md b/docs/docs/developer/extending/generators.md index c720f9d..4c60fa0 100644 --- a/docs/docs/developer/extending/generators.md +++ b/docs/docs/developer/extending/generators.md @@ -9,7 +9,7 @@ stdout. The two official generators, Rust and TypeScript, speak the same protocol. The CLI links them in for speed, but calls them through the same -request and response types, so every `comline generate` exercises it. +request and response types, so every `comline generation` exercises it. The protocol's every field is in the [generator protocol reference](../../reference/generator-protocol.md). This page diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md index fa29261..d35938a 100755 --- a/docs/docs/getting-started.md +++ b/docs/docs/getting-started.md @@ -82,7 +82,7 @@ comline check ## Generate code ```shell -comline generate +comline generation ``` Targets come from `code_generation.languages` in `config.idp` (the scaffold @@ -101,5 +101,5 @@ Today `rust` and `typescript` are the generators. - [Overview](guides/index.md) — the whole pipeline - [IDL guide](guides/idl/index.md) — the schema language -- [Generating code](guides/codegen/generating-code.md) — the full `generate` surface +- [Generating code](guides/codegen/generating-code.md) — the full `generation` surface - [CLI reference](reference/tools/cli/index.md) — every command and flag diff --git a/docs/docs/guides/codegen/generating-code.md b/docs/docs/guides/codegen/generating-code.md index 6ef4e20..8273807 100644 --- a/docs/docs/guides/codegen/generating-code.md +++ b/docs/docs/guides/codegen/generating-code.md @@ -1,6 +1,6 @@ # Generating code -`comline generate` turns your compiled schemas into source code for a target +`comline generation` turns your compiled schemas into source code for a target language. This page is the practical guide: what it produces, how to say where it goes, and how to generate more than one version at once. @@ -15,7 +15,7 @@ Code generation is configured across two files with two different owners: | File | Owner | In version control | Purpose | |---|---|---|---| | `config.idp` | the **package author** | committed, frozen into every published version | declares *what languages* the package can be generated as | -| `comline.toml` | the **consumer** (whoever runs `generate`) | committed, never frozen | says *where* generated code goes, in what layout, for which versions | +| `comline.toml` | the **consumer** (whoever runs `comline generation`) | committed, never frozen | says *where* generated code goes, in what layout, for which versions | `config.idp` never contains an output path — where your bindings land is your call, not the package author's, so it lives in `comline.toml`. @@ -39,7 +39,7 @@ toolchain** its generated code must build on. The `= {}` is required and takes no options. See [Language versions](#language-versions) for what the version promises and how it's checked. -Declaring a language is what makes it generated: `comline generate` emits every +Declaring a language is what makes it generated: `comline generation` emits every language listed here. The entry carries no output path — where the code lands is the consumer's business, below — and a consumer who wants fewer says so with `only`. @@ -211,19 +211,19 @@ idiomatic output for a past schema shape. ## Running it ``` -comline generate [--target ] [--out ] [--layout ] [--mode ] [--dry-run] [--list] [--watch] +comline generation [--target ] [--out ] [--layout ] [--mode ] [--dry-run] [--list] [--watch] ``` -`generate` validates the project and writes the code. Unlike `comline build` it +`generation` validates the project and writes the code. Unlike `comline build` it does **not** freeze a version or write to `.comline/` — it is safe to run -repeatedly and from CI. +repeatedly and from CI. `gen` is short for `generation`. ```bash -comline generate # every configured target, per comline.toml -comline generate --target rust # just rust -comline generate --target rust --out ./bind # override this target's output root -comline generate --dry-run # report without writing anything -comline generate --watch # regenerate on schema / config change +comline generation # every configured target, per comline.toml +comline generation --target rust # just rust +comline generation --target rust --out ./bind # override this target's output root +comline generation --dry-run # report without writing anything +comline generation --watch # regenerate on schema / config change ``` Each target's files are reported as a tree: @@ -245,8 +245,8 @@ Each target's files are reported as a tree: generated at once. `--dry-run` and `--list` are independent: the first decides whether anything is written, the second how it is reported. -`comline clean` removes the generated output (the whole `out` directory when it -is a dedicated one, e.g. `generated/`). It leaves `.comline/` alone — +`comline generation clean` removes the generated output (the whole `out` directory when it +is a dedicated one, e.g. `generated/`); `--target ` removes only that language's. It leaves `.comline/` alone — `comline reset` is the command that discards the version history. ## What Rust output looks like @@ -325,7 +325,7 @@ for it. ## Gotchas -- `generate` never changes the package version. Only `build` does. +- `generation` never changes the package version. Only `build` does. - The default layout writes under `generated/`. Older CLI versions wrote flat into the project root; set `out = "."` and `layout = "{{namespace}}.{{ext}}"` for that. diff --git a/docs/docs/guides/codegen/index.md b/docs/docs/guides/codegen/index.md index d7a1eba..04c1a52 100755 --- a/docs/docs/guides/codegen/index.md +++ b/docs/docs/guides/codegen/index.md @@ -19,7 +19,7 @@ detail that the generated code is pleasant to use directly rather than only as a ## Using it -`comline generate` is the command; [Generating code](generating-code.md) is the +`comline generation` is the command; [Generating code](generating-code.md) is the full guide, and [`comline.toml`](../../reference/package/congregation/comline-toml.md) is where a consumer sets the output location, layout and mode. diff --git a/docs/docs/guides/codegen/library-generation.md b/docs/docs/guides/codegen/library-generation.md index 2318f82..442f58c 100755 --- a/docs/docs/guides/codegen/library-generation.md +++ b/docs/docs/guides/codegen/library-generation.md @@ -6,7 +6,7 @@ that source into a **package**: a manifest (`Cargo.toml`, `package.json`) and the module layout. A planned third mode, `dylib`, would compile it to a library any language's [runtime](../runtime/index.md) can load. -`comline generate`'s `mode` chooses how far generation goes. It is set per target +`comline generation`'s `mode` chooses how far generation goes. It is set per target in [`comline.toml`](../../reference/package/congregation/comline-toml.md) (`[generate] mode` or `[[generate.target]] mode`). diff --git a/docs/docs/guides/idl/protocol.md b/docs/docs/guides/idl/protocol.md index 0923e5d..77d55a3 100755 --- a/docs/docs/guides/idl/protocol.md +++ b/docs/docs/guides/idl/protocol.md @@ -255,14 +255,14 @@ that out; the schema only says *that* something is unverified and *why*: } ``` - Nobody writes this by hand: `comline add` shows what a new dependency gives - up and asks before writing it, and `comline accept billing` (or + Nobody writes this by hand: `comline deps add` shows what a new dependency gives + up and asks before writing it, and `comline deps accept billing` (or `billing::Billing`) does the same for one already declared. In the editor, the dependency's entry in `config.idp` shows the error, with a quick fix that writes the line. Until it's accepted, the build fails, printing the entry. The list is a snapshot: if a later version of the dependency gives up more, the build stops again until - `comline accept` is run again. + `comline deps accept` is run again. How a call travels between caller and implementation is the [runtime](../runtime/index.md)'s job, over a pluggable diff --git a/docs/docs/guides/idl/validator.md b/docs/docs/guides/idl/validator.md index aecb678..6f1bc14 100644 --- a/docs/docs/guides/idl/validator.md +++ b/docs/docs/guides/idl/validator.md @@ -6,7 +6,7 @@ a property or whose literal type is wrong, a missing argument for a property without a default, or an undeclared `params.*` reference all fail the build. Generated **Rust** code then [runs them](#in-generated-code). Generated TypeScript doesn't yet: it - generates the types without the checks, and `comline generate` warns. See + generates the types without the checks, and `comline generation` warns. See [TypeScript's language reference](../../reference/languages/typescript.md#code-generation). A **validator** is a named, parameterised check you attach to a diff --git a/docs/docs/guides/index.md b/docs/docs/guides/index.md index 1dcd4f0..cbb2f80 100644 --- a/docs/docs/guides/index.md +++ b/docs/docs/guides/index.md @@ -15,13 +15,13 @@ flowchart LR I --> V["validate"] V -->|"comline build"| F["freeze"] F --> CAS[(".comline/
version history")] - V -->|"comline generate"| G["generate"] + V -->|"comline generation"| G["generate"] TOML["comline.toml
where code goes"] --> G G --> OUT["generated/"] ``` `comline check` stops after validating. `comline build` freezes a version; -`comline generate` writes code without freezing anything. +`comline generation` writes code without freezing anything. ## 1. Write a schema @@ -53,7 +53,7 @@ last one. See [Versioning rules](../reference/versioning.md). ## 3. [Generate code](codegen/generating-code.md) -`comline generate` turns the schemas into source for each target language. +`comline generation` turns the schemas into source for each target language. The package declares *which* languages it supports, in `config.idp`; whoever generates decides *where* the code lands, in `comline.toml` ([the two files](codegen/generating-code.md#the-two-files)). One history can be diff --git a/docs/docs/guides/ir/cas.md b/docs/docs/guides/ir/cas.md index 364acf3..e19b8af 100755 --- a/docs/docs/guides/ir/cas.md +++ b/docs/docs/guides/ir/cas.md @@ -39,7 +39,7 @@ flowchart LR | `objects//` | One object. The 64 hex characters of its hash are split: the first two name the directory, the other 62 name the file. The file holds the object's bytes, LZ4-compressed. | | `refs/heads/main` | The hash of the newest commit, as 64 hex characters. Updated at the end of every build and release. It is the only ref. | | `FORMAT_VERSION` | The [IR format stamp](#the-ir-format-stamp) as a decimal number. | -| `deps-cache/` | Git dependencies fetched by `comline add` and by builds. A cache, not history. | +| `deps-cache/` | Git dependencies fetched by `comline deps add` and by builds. A cache, not history. | ### What to commit @@ -55,7 +55,7 @@ writes ignores only that directory: .comline/deps-cache/ ``` -`comline clean` never touches `.comline/`. `comline reset` deletes the whole +`comline generation clean` never touches `.comline/`. `comline reset` deletes the whole directory, history included, behind a typed confirmation or `--force`. See [Packages & dependencies](../packages/index.md) for the package layout. @@ -326,9 +326,9 @@ See `comline release` in the [CLI reference](../../reference/tools/cli/index.md) | `comline diff ` | Two commits' root trees, compared with the same rules as a build: schema changes, changes within a dependency's reach, config changes and the bump they call for. | | `comline inspect` | The newest build's `facts`, shown beside each protocol's wire summary. It writes nothing. See [`comline inspect`](../../reference/tools/cli/inspect.md). | | `comline doc --version ` | A built version's schema blobs, its `config` for the package name, and its `docs` headers. `--changelog-from ` adds the changes since an earlier version. See [`comline doc`](../../reference/tools/cli/doc.md) and [Documenting your schemas](../documenting.md). | -| `comline generate` | With a pinned version or `"all"`, the frozen schemas of those versions. The default, `"latest"`, reads the working tree and not the store. | +| `comline generation` | With a pinned version or `"all"`, the frozen schemas of those versions. The default, `"latest"`, reads the working tree and not the store. | -`diff`, `doc --version` and `generate` find a commit by `HEAD`, a version +`diff`, `doc --version` and `generation` find a commit by `HEAD`, a version string such as `0.3.0-dev.2`, or a commit hash (the full 64 characters, or a prefix of 4 or more that matches one commit). They walk the chain from `refs/heads/main` through each commit's first parent. diff --git a/docs/docs/guides/packages/index.md b/docs/docs/guides/packages/index.md index 8251ff5..721dbc6 100644 --- a/docs/docs/guides/packages/index.md +++ b/docs/docs/guides/packages/index.md @@ -79,7 +79,7 @@ That key is now an error that hands back the `wire` line to write instead. ## Consumer Side (`comline.toml`) Where generated code lands, in what layout, for which versions — none of which -belongs to the package author — is set by whoever runs `comline generate`, in a +belongs to the package author — is set by whoever runs `comline generation`, in a separate, non-frozen `comline.toml`. See [Generating code](../codegen/generating-code.md) and the [`comline.toml` reference](../../reference/package/congregation/comline-toml.md). @@ -154,12 +154,12 @@ reports git's own error. `config.idp`, and imports from it aren't checked until it is. More in [Dependency packages in the editor](../../design/editor-dependency-packages.md). -`comline add` writes an entry for you, after resolving the dependency (a git pin +`comline deps add` writes an entry for you, after resolving the dependency (a git pin is fetched), with its `hash` pinned to what it just compiled: ```bash -comline add shared_types ../shared-types -comline add net --git https://github.com/acme/net --commit 4f2c9e1 --version 1.2.0 +comline deps add shared_types ../shared-types +comline deps add net --git https://github.com/acme/net --commit 4f2c9e1 --version 1.2.0 ``` The rest of `config.idp` is left as written. `--no-hash` skips the pin, say for @@ -177,7 +177,7 @@ recorded versions. The `comline new` scaffold's `.gitignore` ignores only `.comline/deps-cache/`, where [git dependencies](#dependencies) are fetched. !!! warning - `comline reset` deletes `.comline/` (behind a confirmation). `comline clean` + `comline reset` deletes `.comline/` (behind a confirmation). `comline generation clean` does not — see [Versioning rules](../../reference/versioning.md#history-model). ## Publishing diff --git a/docs/docs/index.md b/docs/docs/index.md index ba90024..1b257e3 100755 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -18,7 +18,7 @@ same family as [Protocol Buffers](https://protobuf.dev/), flowchart LR S["schema
.ids files"] --> C["comline build
check and freeze"] C --> V[("version history
.comline/")] - C --> G["comline generate"] + C --> G["comline generation"] G --> R["Rust code"] G --> T["TypeScript code"] R <-->|"calls over a
transport"| T @@ -43,7 +43,7 @@ changed since the last release, so a breaking change can't ship as a patch. ### [Generated code](./guides/codegen/index.md) -`comline generate` writes idiomatic code for each target language: types, a +`comline generation` writes idiomatic code for each target language: types, a trait or interface per protocol, clients, servers and connections. Rust and TypeScript are supported today, each in two forms: source files to drop into a project, or a buildable package. diff --git a/docs/docs/languages/rust/connections.md b/docs/docs/languages/rust/connections.md index 0a077aa..2d28c6c 100644 --- a/docs/docs/languages/rust/connections.md +++ b/docs/docs/languages/rust/connections.md @@ -38,13 +38,13 @@ left out when: only once one JSON-RPC protocol in the package is client-provided; then they all do. - **The protocols on connections disagree** on the framing or the handshake. - No one connection carries them all, and `comline generate` warns, naming + No one connection carries them all, and `comline generation` warns, naming both protocols. Each protocol still gets its own dispatcher and sender. - **Only protocols from an external `std` are on a connection.** Only what the crate emits counts. When a package declares protocols but none is on a connection, -`comline generate` says so, and why. +`comline generation` says so, and why. ### Using them @@ -85,7 +85,7 @@ let sent = ChatSender::new(&mut conn).send("hi")?; ([Framing & wire format](framing-and-wire-format.md)), and the framing and handshake are the protocols'. When the protocols on connections disagree on either, no one connection carries them all, so these functions aren't - generated and `comline generate` warns why. + generated and `comline generation` warns why. - **A schema named `connection`** can't be used in `code` mode, since the file would overwrite it. diff --git a/docs/docs/languages/typescript/connections.md b/docs/docs/languages/typescript/connections.md index 070210c..f156430 100644 --- a/docs/docs/languages/typescript/connections.md +++ b/docs/docs/languages/typescript/connections.md @@ -38,13 +38,13 @@ left out when: only once one JSON-RPC protocol in the package is client-provided; then they all do. - **The protocols on connections disagree** on the framing or the handshake. - No one connection carries them all, and `comline generate` warns, naming + No one connection carries them all, and `comline generation` warns, naming both protocols. Each protocol still gets its own dispatcher and sender. - **Only protocols from an external `std` are on a connection.** Only what the package emits counts. When a package declares protocols but none is on a connection, -`comline generate` says so, and why. +`comline generation` says so, and why. ### Using them @@ -82,7 +82,7 @@ const sent = await new chat.ChatSender(conn).send({ text: "hi" }); ([Framing & wire format](framing-and-wire-format.md)); the framing and handshake are the protocols'. When the protocols on connections disagree on either, no one connection carries them all, so these functions aren't - generated and `comline generate` warns why. + generated and `comline generation` warns why. ## What codegen emits diff --git a/docs/docs/languages/typescript/framing-and-wire-format.md b/docs/docs/languages/typescript/framing-and-wire-format.md index a1e16b1..50a45c2 100644 --- a/docs/docs/languages/typescript/framing-and-wire-format.md +++ b/docs/docs/languages/typescript/framing-and-wire-format.md @@ -50,7 +50,7 @@ Two codecs ship. Every `Codec` has a `name` (used in the handshake) plus There's no MessagePack codec for TypeScript yet, so a TypeScript target can't generate a package whose `wire.format` is `msgpack@1`: `comline build` -and `comline generate` refuse it. +and `comline generation` refuse it. `u64` and `s64` (and `u128` / `s128`) are `bigint` in both codecs. diff --git a/docs/docs/reference/languages/index.md b/docs/docs/reference/languages/index.md index a9d1734..43131a3 100644 --- a/docs/docs/reference/languages/index.md +++ b/docs/docs/reference/languages/index.md @@ -14,7 +14,7 @@ language page can't claim something that isn't true. | --- | --- | | ✅ **supported** | Works. | | 🟡 **partial** | Works, with the limit the note states. | -| ⚪ **ignored** | Succeeds, but the output is what it would be without the feature: the types are right, the feature has no effect. `comline generate` warns, and so does the editor. | +| ⚪ **ignored** | Succeeds, but the output is what it would be without the feature: the types are right, the feature has no effect. `comline generation` warns, and so does the editor. | | ❌ **unsupported** | Is refused, with an error naming every use. The editor warns at each use. | A runtime's claims use the same words, about the wire: @@ -119,6 +119,9 @@ commit. A runtime's suite runs every example against it: | JSON wire format
`format-json` | ✅ supported | 🟡 partial: decoding doesn't check enum variants or integer ranges ([comline-typescript#57](https://github.com/ComlineProject/comline-typescript/issues/57)) | | MessagePack wire format
`format-msgpack` | ✅ supported | ❌ unsupported: JSON and packed@1 ship | | packed wire format
`format-packed` | ✅ supported | ✅ supported | +| packed sizes
`sizes-packed` | ✅ supported | ❔ not reported | +| MessagePack sizes
`sizes-msgpack` | ✅ supported | ❔ not reported | +| JSON sizes
`sizes-json` | ✅ supported | ❔ not reported | diff --git a/docs/docs/reference/languages/rust.md b/docs/docs/reference/languages/rust.md index c81bb97..e23ad64 100644 --- a/docs/docs/reference/languages/rust.md +++ b/docs/docs/reference/languages/rust.md @@ -62,18 +62,21 @@ Runtime `rust`. | Feature | What it covers | State | Proven by | |---|---|---|---| -| name hash
`name-hash` | FNV-1a 64 of a wire format or framing name, as the handshake carries it | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/name-hash.json) | -| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [14 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake.json) | -| envelope
`envelope` | a response's outcome: ok with a payload, an error ordinal with its body, or a provider fault | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/envelope.json) | -| datagram framing
`framing-datagram` | Comline's own binary framing of requests and responses | ✅ supported | [12 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram.json) | -| datagram@2 framing
`framing-datagram2` | the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection | ✅ supported | [16 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram2.json) | -| datagram@3 framing
`framing-datagram3` | the datagram framing that addresses a call by its protocol's and function's wire numbers, both varints (calls = by_id); replies as datagram@2 | ✅ supported | [18 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram3.json) | -| comline@2 handshake
`handshake-comline2` | the compatibility-checking handshake: its hello, answer and verdict messages, and its negotiation steps under every parameter, with every refusal reason | ✅ supported | [66 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake-comline2.json) | -| stream framing
`stream` | frames on a byte stream (TCP, a pipe): each behind a u32 little-endian length prefix, refused over the limit, by default 16 MiB (16777216 bytes) in every runtime | ✅ supported | [24 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/stream.json) | -| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [62 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-jsonrpc.json) | -| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | ✅ supported | [96 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-json.json) | -| MessagePack wire format
`format-msgpack` | values as MessagePack: a struct as an array | ✅ supported | [98 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-msgpack.json) | -| packed wire format
`format-packed` | values as packed@1: fixed-width fields back to back, varint lengths, no tags | ✅ supported | [110 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-packed.json) | +| name hash
`name-hash` | FNV-1a 64 of a wire format or framing name, as the handshake carries it | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/name-hash.json) | +| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [14 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/handshake.json) | +| envelope
`envelope` | a response's outcome: ok with a payload, an error ordinal with its body, or a provider fault | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/envelope.json) | +| datagram framing
`framing-datagram` | Comline's own binary framing of requests and responses | ✅ supported | [12 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/framing-datagram.json) | +| datagram@2 framing
`framing-datagram2` | the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection | ✅ supported | [16 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/framing-datagram2.json) | +| datagram@3 framing
`framing-datagram3` | the datagram framing that addresses a call by its protocol's and function's wire numbers, both varints (calls = by_id); replies as datagram@2 | ✅ supported | [18 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/framing-datagram3.json) | +| comline@2 handshake
`handshake-comline2` | the compatibility-checking handshake: its hello, answer and verdict messages, and its negotiation steps under every parameter, with every refusal reason | ✅ supported | [66 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/handshake-comline2.json) | +| stream framing
`stream` | frames on a byte stream (TCP, a pipe): each behind a u32 little-endian length prefix, refused over the limit, by default 16 MiB (16777216 bytes) in every runtime | ✅ supported | [24 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/stream.json) | +| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [62 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/framing-jsonrpc.json) | +| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | ✅ supported | [96 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/format-json.json) | +| MessagePack wire format
`format-msgpack` | values as MessagePack: a struct as an array | ✅ supported | [98 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/format-msgpack.json) | +| packed wire format
`format-packed` | values as packed@1: fixed-width fields back to back, varint lengths, no tags | ✅ supported | [110 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/format-packed.json) | +| packed sizes
`sizes-packed` | how many bytes each kind of value takes in packed@1, each rule proven by values written to exactly its minimum and maximum | ✅ supported | [59 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/sizes-packed.json) | +| MessagePack sizes
`sizes-msgpack` | how many bytes each kind of value takes in msgpack@1, each rule proven by values written to exactly its minimum and maximum | ✅ supported | [60 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/sizes-msgpack.json) | +| JSON sizes
`sizes-json` | how many bytes each kind of value takes in json@1, each rule proven by values written to exactly its minimum and maximum, or by a declared upper bound | ✅ supported | [57 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/sizes-json.json) | diff --git a/docs/docs/reference/languages/typescript.md b/docs/docs/reference/languages/typescript.md index e56e3e9..70c88bc 100644 --- a/docs/docs/reference/languages/typescript.md +++ b/docs/docs/reference/languages/typescript.md @@ -62,18 +62,21 @@ Runtime `typescript`. | Feature | What it covers | State | Proven by | |---|---|---|---| -| name hash
`name-hash` | FNV-1a 64 of a wire format or framing name, as the handshake carries it | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/name-hash.json) | -| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [14 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake.json) | -| envelope
`envelope` | a response's outcome: ok with a payload, an error ordinal with its body, or a provider fault | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/envelope.json) | -| datagram framing
`framing-datagram` | Comline's own binary framing of requests and responses | ✅ supported | [12 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram.json) | -| datagram@2 framing
`framing-datagram2` | the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection | ✅ supported | [16 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram2.json) | -| datagram@3 framing
`framing-datagram3` | the datagram framing that addresses a call by its protocol's and function's wire numbers, both varints (calls = by_id); replies as datagram@2 | ✅ supported | [18 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram3.json) | +| name hash
`name-hash` | FNV-1a 64 of a wire format or framing name, as the handshake carries it | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/name-hash.json) | +| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [14 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/handshake.json) | +| envelope
`envelope` | a response's outcome: ok with a payload, an error ordinal with its body, or a provider fault | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/envelope.json) | +| datagram framing
`framing-datagram` | Comline's own binary framing of requests and responses | ✅ supported | [12 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/framing-datagram.json) | +| datagram@2 framing
`framing-datagram2` | the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection | ✅ supported | [16 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/framing-datagram2.json) | +| datagram@3 framing
`framing-datagram3` | the datagram framing that addresses a call by its protocol's and function's wire numbers, both varints (calls = by_id); replies as datagram@2 | ✅ supported | [18 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/framing-datagram3.json) | | comline@2 handshake
`handshake-comline2` | the compatibility-checking handshake: its hello, answer and verdict messages, and its negotiation steps under every parameter, with every refusal reason | ❌ unsupported: Comline2Handshake runs on the Comline core (ABI 0.2), whose C and Node replays in the runtime repo prove these vectors; this harness doesn't drive the core's steps itself yet | — | | stream framing
`stream` | frames on a byte stream (TCP, a pipe): each behind a u32 little-endian length prefix, refused over the limit, by default 16 MiB (16777216 bytes) in every runtime | ❌ unsupported: no length-prefixed framing or frame limit yet: the transports are message-oriented ([comline-typescript#80](https://github.com/ComlineProject/comline-typescript/issues/80)) | — | -| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [62 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-jsonrpc.json) | -| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | 🟡 partial: decoding doesn't check enum variants or integer ranges ([comline-typescript#57](https://github.com/ComlineProject/comline-typescript/issues/57))
fails: `format-json/decode-unknown-variant`, `format-json/decode-wider-integer-overflow` | [94 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-json.json) | +| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [62 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/framing-jsonrpc.json) | +| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | 🟡 partial: decoding doesn't check enum variants or integer ranges ([comline-typescript#57](https://github.com/ComlineProject/comline-typescript/issues/57))
fails: `format-json/decode-unknown-variant`, `format-json/decode-wider-integer-overflow` | [94 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/format-json.json) | | MessagePack wire format
`format-msgpack` | values as MessagePack: a struct as an array | ❌ unsupported: JSON and packed@1 ship | — | -| packed wire format
`format-packed` | values as packed@1: fixed-width fields back to back, varint lengths, no tags | ✅ supported | [110 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-packed.json) | +| packed wire format
`format-packed` | values as packed@1: fixed-width fields back to back, varint lengths, no tags | ✅ supported | [110 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/format-packed.json) | +| packed sizes
`sizes-packed` | how many bytes each kind of value takes in packed@1, each rule proven by values written to exactly its minimum and maximum | ❔ not reported | — | +| MessagePack sizes
`sizes-msgpack` | how many bytes each kind of value takes in msgpack@1, each rule proven by values written to exactly its minimum and maximum | ❔ not reported | — | +| JSON sizes
`sizes-json` | how many bytes each kind of value takes in json@1, each rule proven by values written to exactly its minimum and maximum, or by a declared upper bound | ❔ not reported | — | diff --git a/docs/docs/reference/package/congregation/comline-toml.md b/docs/docs/reference/package/congregation/comline-toml.md index c62590f..f4ea9f8 100644 --- a/docs/docs/reference/package/congregation/comline-toml.md +++ b/docs/docs/reference/package/congregation/comline-toml.md @@ -1,6 +1,6 @@ # `comline.toml` -Consumer-owned configuration for `comline generate`: where generated code goes, +Consumer-owned configuration for `comline generation`: where generated code goes, in what layout, in what form, and for which package versions. Its `[doc]` table configures `comline doc`. It is committed, never frozen, and never part of a published package. With no `comline.toml` (or @@ -96,7 +96,7 @@ used and has no mapping is a generation error. See ### `flatten` `layout` only governs `code` mode's one-file-per-schema paths — a `lib`-mode -target ignores it entirely (`comline generate` warns if one is set) and +target ignores it entirely (`comline generation` warns if one is set) and always writes the crate's fixed internal shape (`Cargo.toml`, `src/lib.rs`, a file per schema under `src/`) rooted at `out//`, so two `lib` targets can safely share one `out` without their files colliding. @@ -166,7 +166,7 @@ and it carries its reason: validate_on_decode = { off = "the gateway validates every request first" } ``` -A bare `"off"` is refused, with that fix. `comline generate` notes each target +A bare `"off"` is refused, with that fix. `comline generation` notes each target that gives it up, with the reason, and `comline inspect` lists it after the protocols (`--json`: `validate_on_decode_given_up`). @@ -191,7 +191,7 @@ an async one instead: Every protocol is on a connection unless it's lockstep (the `datagram` framing, or JSON-RPC with no client-provided protocol); those are the same -either way, and `comline generate` warns when `async = true` changes nothing. Like +either way, and `comline generation` warns when `async = true` changes nothing. Like `external_std`, it's a consumer's choice: the same package can be generated async for one application and blocking for another. diff --git a/docs/docs/reference/package/congregation/index.md b/docs/docs/reference/package/congregation/index.md index e7fd73b..70cd666 100644 --- a/docs/docs/reference/package/congregation/index.md +++ b/docs/docs/reference/package/congregation/index.md @@ -9,14 +9,14 @@ flowchart LR A["package author"] --> IDP["config.idp
identity, languages,
dependencies, wire, settings"] IDP -->|"frozen into
every version"| CAS[(".comline/")] C["whoever generates"] --> TOML["comline.toml
output paths, layout,
mode, versions"] - CAS --> GEN["comline generate"] + CAS --> GEN["comline generation"] IDP --> GEN TOML --> GEN ``` | | [`config.idp`](config-id.md) | [`comline.toml`](comline-toml.md) | |---|---|---| -| Owner | the package author | whoever runs `comline generate` | +| Owner | the package author | whoever runs `comline generation` | | Says | what the package is: name, identity, languages it supports, dependencies, wire defaults, settings | where generated code goes, in what layout and mode, for which versions | | Frozen into versions | yes | no | | Changes the version | can | never | diff --git a/docs/docs/reference/tools/cli/index.md b/docs/docs/reference/tools/cli/index.md index 44b0e89..714e7ce 100644 --- a/docs/docs/reference/tools/cli/index.md +++ b/docs/docs/reference/tools/cli/index.md @@ -24,26 +24,33 @@ parse → resolve imports → validate → (freeze into .comline/) → (generate ``` `check` stops after validate. `build` adds the freeze step and records a version. -`generate` also stops after validate — it does **not** freeze — then writes code. +`generation` also stops after validate — it does **not** freeze — then writes code. `diff` reads two frozen versions and reports what changed. ## Commands +`deps` and `generation` are groups. `deps` has `add`, `accept`, `pin`, `remove` and `list`; `generation` is +itself the command that writes code, and has `clean` beneath it to remove it. Run +`comline deps --help` or `comline generation --help` for a group's own synopsis. + | Command | What it does | | --- | --- | | `comline new [--git]` | Scaffold `/` with `config.idp`, `comline.toml`, `src/main.ids`, `.gitignore`. `--git` also runs `git init`. | -| `comline add ` / `comline add --git --commit --version ` | Add a dependency to `config.idp`, imported as `use ::…`: resolved first (a git pin is fetched into `.comline/deps-cache/`), then written with its `hash` pinned. `--no-hash` skips the pin. If it has [`@unverified`](../../../guides/idl/protocol.md#giving-up-a-guarantee) protocols, what each gives up is shown and, on a terminal, you're asked to accept it (default no); without a terminal it refuses (exit `2`) unless `--accept-unverified`. | -| `comline accept [::] [--yes]` | Accept what a dependency's [`@unverified`](../../../guides/idl/protocol.md#giving-up-a-guarantee) protocols give up: shows each one's given-up guarantees and reason, then writes `accept_unverified` into its `config.idp` entry, leaving the rest as written. Only protocols not already accepted for exactly their current set are asked about. On a terminal you're asked (default no); without one it refuses (exit `2`) unless `--yes` (`-y`). | +| `comline deps add ` / `comline deps add --git --commit --version ` | Add a dependency to `config.idp`, imported as `use ::…`: resolved first (a git pin is fetched into `.comline/deps-cache/`), then written with its `hash` pinned. `--no-hash` skips the pin. If it has [`@unverified`](../../../guides/idl/protocol.md#giving-up-a-guarantee) protocols, what each gives up is shown and, on a terminal, you're asked to accept it (default no); without a terminal it refuses (exit `2`) unless `--accept-unverified`. | +| `comline deps accept [::] [--yes]` | Accept what a dependency's [`@unverified`](../../../guides/idl/protocol.md#giving-up-a-guarantee) protocols give up: shows each one's given-up guarantees and reason, then writes `accept_unverified` into its `config.idp` entry, leaving the rest as written. Only protocols not already accepted for exactly their current set are asked about. On a terminal you're asked (default no); without one it refuses (exit `2`) unless `--yes` (`-y`). | +| `comline deps pin [--commit --version ] [--accept-unverified]` | Re-resolve a dependency whose content changed and rewrite its `hash` to what was just compiled, so the build stops failing on the old pin; an entry without a hash gains one. Nothing is written for a dependency that doesn't resolve, and it says so when the pin is already current. `--commit` with `--version` moves a git dependency to another commit as well. If the new content gives up more through `@unverified` than the entry accepts, it asks as `deps add` does; without a terminal it refuses (exit `2`) unless `--accept-unverified`. | +| `comline deps remove [--dry-run]` | Remove a dependency's entry from `config.idp`, leaving the rest as written. Refused while a schema still imports it (each `use` is listed with its file and line), or when a schema doesn't parse, since then it can't tell. `--dry-run` shows the entry it would remove. A git dependency's checkout stays in `.comline/deps-cache/`. | +| `comline deps list [--json]` | List the declared dependencies by name: the source (path, or git URI at its commit and version), the pin (or `unpinned`) and what's accepted of its `@unverified` protocols. Read-only, and nothing is fetched. `--json` prints the same as JSON. | | `comline check` | Parse, resolve and validate. No `.comline/` write (beyond fetching git dependencies), no version bump — safe for editors, hooks, CI. | | `comline fix [--edition ] [--dry-run]` | Apply the fixes Comline attaches to what it reports about the language: add a missing `specification_version` to `config.idp`, and replace each use of a keyword or type the package's [edition](../../versioning.md#editions) deprecates or removes, when it has a replacement; uses without one are listed to change by hand. `--edition ` checks and fixes the schemas under edition `n` and moves `config.idp` to it, unless a removed word without a replacement is left (exit `1`). Moving back is refused. `--dry-run` lists the fixes and writes nothing. | | `comline inspect [--json]` | Show each protocol's format, framing and handshake, with their parameters and where each came from (`@framing`/`@handshake`, `config.idp`, or core's default), then every guarantee, held or given up, with the cause, the `@unverified` reason and whether it's accepted. No `.comline/` write. `--json` prints the same as JSON. See [comline inspect](inspect.md). | | `comline build [--watch] [--reconcile ]` | Compile, validate, and freeze a build into `.comline/` under a pre-release version (`0.3.0-dev.2`); print the changelog, the bump, and the next release. `--reconcile ` puts a head dropped in a Git merge back beside the current one, so the build [reconciles the two](../../../guides/ir/cas.md); the output says when a build reconciled. A project with [unbounded strings or lists](../../../guides/idl/types.md#every-string-and-list-has-a-maximum) fails with each position listed and the `settings` block to add; on a terminal, the build offers to write it with maxima you type in. Before freezing, proves every declared `code_generation.languages` target against this binary's generators ([Language versions](../../../guides/codegen/generating-code.md#language-versions)). Releasing is `comline release`. | -| `comline generate [--target ] [--out ] [--layout ] [--mode ] [--external-std] [--no-external-std] [--validate-on-decode ] [--dry-run] [--list] [--watch]` | Validate (no freeze), then write generated code. Wire numbers and the rest of the [facts](../../versioning.md#number) come from the last build when nothing changed since, else are worked out as the next build would assign them, provisional until a release; no build is needed. Location/layout from [`comline.toml`](../../package/congregation/comline-toml.md); targets from there or `config.idp`. A target can use an [external generator](../../../developer/extending/generators.md) (`generator = ""`) and map [encodings](../../../developer/extending/encodings.md#5-map-it-to-a-type). | +| `comline generation` (short: `gen`) `[--target ] [--out ] [--layout ] [--mode ] [--external-std] [--no-external-std] [--validate-on-decode ] [--dry-run] [--list] [--watch]` | Validate (no freeze), then write generated code. Wire numbers and the rest of the [facts](../../versioning.md#number) come from the last build when nothing changed since, else are worked out as the next build would assign them, provisional until a release; no build is needed. Location/layout from [`comline.toml`](../../package/congregation/comline-toml.md); targets from there or `config.idp`. A target can use an [external generator](../../../developer/extending/generators.md) (`generator = ""`) and map [encodings](../../../developer/extending/encodings.md#5-map-it-to-a-type). | | `comline release [1.0] [--raise --reason ] [--yes]` | Build, then release: create the version from the highest bump since the last release ([builds and releases](../../versioning.md#builds-and-releases)). `--raise patch\|minor\|major` goes higher, with a `--reason` recorded with the release; it never lowers. `1.0` makes a `0.x` package stable after showing what that commits to (its protocols, and what's worth settling first). Raising to major and `1.0` ask on a terminal; without one they refuse (exit `2`) unless `--yes` (`-y`). | | `comline diff []` | Show schema changes between two built versions. Each argument is a version (`0.2.0`), a commit hash (4+ chars), or `HEAD` (`` default). | | `comline doc [--out ] [--version ] [--changelog-from ] [--format ] [--open]` | Write the package's documentation for every version (each release, dev build and the unreleased working state), each into `///` with the changelog from the version before it: Markdown pages (an index, one page per module with its `//!` header, every declaration's `///` docs and each protocol's wire summary, a changelog, an mkdocs/zensical `nav.yml`), `--format html` for a self-contained static site with the same content, a search box, a version picker and a page comparing versions, or `--format json` for the documentation model. Built versions are cached, so a run re-renders only the unreleased state and new versions; `--version` documents one built version. Defaults from [`comline.toml`](../../package/congregation/comline-toml.md#doc)'s `[doc]`. `comline doc open []` (or `--open` after a render) opens the result with the system's default handler, rendering first if it isn't there. No `.comline/` write. See [comline doc](doc.md). | | `comline conformance --impl [--encoding ]... [--corpus ] [--timeout ] [--json]` | Run an implementation of an encoding against its vectors. The package's declared [`encodings`](../../../developer/extending/encodings.md) ship vectors beside their profiles (`profiles/x.vectors.json`); `--impl` is a process speaking the [ops protocol](../../conformance/wire.md#the-ops-protocol), run once with a cleared environment, a time limit (`--timeout`, 60 s) and a capped stdout. `--encoding` limits the run to one encoding (repeatable); `--corpus` runs a corpus laid out like the runtime's `runtime/conformance` instead, which is how the official encodings are proven. A failed or unimplemented case, or an unproven profile fact, exits `1`. `--json` prints the report as JSON on stdout instead (nothing else on stdout; the exit code is the same): `format` (`1`), `implementation` (`command` and the `version` it reported, with its `protocol`), `encodings` (each with `name`, `kind`, `listed_by_implementation`, `passed`, `total`, `facts` as `{fact, value, proven, reason}` and `cases` as `{id, outcome, detail}` where `outcome` is `pass`, `fail` or `not_implemented`), `totals` (`encodings`, `cases`, `passed`, `problems`) and `verdict` (`conforms` or `fails`). See [Formats and framings](../../../developer/extending/encodings.md#3-write-vectors-and-prove-an-implementation). | -| `comline clean [--dry-run]` | Remove generated code (the `generate` output root or files). Never touches `.comline/`. | +| `comline generation clean [--dry-run] [--target ]` | Remove what `generation` wrote: the output root, or the individual generated files. `--target ` (`-t`) removes only that language's output; a language no target matches is an error, as it is for `generation --target`. Never touches `.comline/`. | | `comline reset [--force] [--dry-run]` | **Destructive.** Delete `.comline/` — the whole version history, no undo — *and* generated code. Next `build` starts over at `0.1.0-dev.1`. On a terminal it shows how many versions will be lost and makes you type `reset`; without a terminal it refuses (exit `2`) unless `--force`. | | `comline completions ` | Print a completion script to stdout. `bash` `zsh` `fish` `powershell` `elvish`. | | `comline targets [--features [--json]]` | Print one `language#version` per line to stdout — the token syntax `config.idp`'s `code_generation.languages` expects, at the generator's floor — then the versions it handles and has verified, for every generator this binary was compiled with. Ignores `--path`: it reflects the build, not a project. `--features` also lists what each generator supports, feature by feature ([Languages](../../languages/index.md)); `--json` prints that as JSON. | @@ -60,7 +67,7 @@ in `code` mode. `--validate-on-decode collect|first` overrides whether decoding runs the schema's `@validators` (also `COMLINE_GENERATE_VALIDATE_ON_DECODE`). The default is `collect`; turning it off is a give-up written in `comline.toml` with its reason -(`{ off = "why" }`), and `generate` notes it per target. +(`{ off = "why" }`), and `generation` notes it per target. Each target's files are drawn as a tree. `--list` prints them one per line instead, with the schema each came from — and, when several package versions are generated at once, the version each line belongs to. `--dry-run` writes diff --git a/docs/docs/reference/tools/index.md b/docs/docs/reference/tools/index.md index 0bbe7c7..ec4bd95 100644 --- a/docs/docs/reference/tools/index.md +++ b/docs/docs/reference/tools/index.md @@ -2,7 +2,7 @@ | Tool | What it's for | | --- | --- | -| [`comline`](cli/index.md) | The CLI: scaffold, check, build, release, diff, generate, document. | +| [`comline`](cli/index.md) | The CLI: scaffold, check, build, release, diff, generation, document. | | [`comline inspect`](cli/inspect.md) | What each protocol resolves to on the wire, and the guarantees it keeps or gives up. | | [`comline doc`](cli/doc.md) | Documentation pages, a static site or a JSON model, for every version. | | The language server | Diagnostics, hover, completion, go-to-definition and quick fixes in `.ids`, `config.idp` and `comline.toml`, through any LSP editor. | diff --git a/docs/docs/reference/versioning.md b/docs/docs/reference/versioning.md index 1b093f9..70e2a7e 100644 --- a/docs/docs/reference/versioning.md +++ b/docs/docs/reference/versioning.md @@ -283,7 +283,7 @@ version's facts, never in the schema. whatever neither released. - **Never reused.** When an item is removed, its number is retired. A re-added item gets a new number. A renamed protocol keeps its number. -- **Generated without a build.** `comline generate` takes the numbers from +- **Generated without a build.** `comline generation` takes the numbers from the last build when the schemas haven't changed since. Otherwise it works them out as the next `comline build` would, against the last release and every retired number, and writes nothing. A package that was never built @@ -388,7 +388,7 @@ reproducible. Nothing else holds this history — there is no `publish` yet — so losing `.comline/` means the next build starts over at `0.1.0-dev.1`, with no undo. -`comline clean` leaves it alone; only **`comline reset`** deletes it, behind a +`comline generation clean` leaves it alone; only **`comline reset`** deletes it, behind a typed confirmation (or `--force`). See [the `clean` / `reset` split](../design/ir-generation.md#the-clean-reset-split). diff --git a/docs/docs/resources.md b/docs/docs/resources.md index ce0f43f..2c27214 100755 --- a/docs/docs/resources.md +++ b/docs/docs/resources.md @@ -5,7 +5,7 @@ | Repo | What | |---|---| | [`ComlineProject/core`](https://github.com/ComlineProject/core) | the compiler, IR, `.comline/` store, diff & auto-versioning | -| [`ComlineProject/cli`](https://github.com/ComlineProject/cli) | the `comline` CLI — `build`, `generate`, `diff`, `clean`, `reset` ([full guide](https://github.com/ComlineProject/cli/blob/main/docs/cli.md)) | +| [`ComlineProject/cli`](https://github.com/ComlineProject/cli) | the `comline` CLI — `build`, `generation`, `diff`, `generation clean`, `reset` ([full guide](https://github.com/ComlineProject/cli/blob/main/docs/cli.md)) | | [`ComlineProject/comline`](https://github.com/ComlineProject/comline) | runtime experiments | | [`ComlineProject/comline-vscode`](https://github.com/ComlineProject/comline-vscode) | VS Code extension | | [`ComlineProject/language-server`](https://github.com/ComlineProject/language-server) | LSP server | diff --git a/docs/docs/schemas/comline-toml/0.x.json b/docs/docs/schemas/comline-toml/0.x.json index 32fbca8..172b1f0 100644 --- a/docs/docs/schemas/comline-toml/0.x.json +++ b/docs/docs/schemas/comline-toml/0.x.json @@ -359,7 +359,7 @@ "description": "Which package versions to generate bindings for: `latest` (the working tree, the default), `all` (every committed version), or one version or a list of them, each a version string or commit hash." } }, - "description": "`comline.toml`: where `comline generate` writes code, and how. Which\nlanguages are generated comes from `config.idp`'s\n`code_generation.languages`; this file says where each one lands.", + "description": "`comline.toml`: where `comline generation` writes code, and how. Which\nlanguages are generated comes from `config.idp`'s\n`code_generation.languages`; this file says where each one lands.", "properties": { "doc": { "allOf": [ diff --git a/scripts/check-cli-drift.py b/scripts/check-cli-drift.py index 7cfcbf7..672e7d1 100755 --- a/scripts/check-cli-drift.py +++ b/scripts/check-cli-drift.py @@ -90,6 +90,17 @@ def parse_flags(help_text: str) -> set[str]: return flags - IGNORED_FLAGS +def walk(path: list[str], commands: set[str]) -> list[list[str]]: + """Every command under `path`, depth first: a group (`deps`) and each of + its subcommands (`deps add`), whose flags are their own.""" + found = [] + for command in sorted(commands): + sub = [*path, command] + found.append(sub) + found.extend(walk(sub, parse_commands(run_help(sub)))) + return found + + def documented(page: str) -> tuple[set[str], set[str]]: """Extract the commands and flags the docs mention.""" commands = set(re.findall(r"`comline ([a-z][a-z0-9-]*)", page)) @@ -127,7 +138,8 @@ def main() -> int: if not DOCS_PAGE.exists(): sys.exit(f"error: {DOCS_PAGE} not found") - doc_commands, doc_flags = documented(DOCS_PAGE.read_text(encoding="utf-8")) + page = DOCS_PAGE.read_text(encoding="utf-8") + doc_commands, doc_flags = documented(page) root_help = run_help([]) real_commands = parse_commands(root_help) @@ -140,15 +152,20 @@ def main() -> int: drift |= report("Global flags", real_globals - doc_flags, set()) all_real_flags = set(real_globals) | IGNORED_FLAGS - for command in sorted(real_commands): - own = parse_flags(run_help([command])) - GLOBAL_FLAGS + for path in walk([], real_commands): + name = " ".join(path) + # A subcommand (`comline deps add`) is checked by its full name; the + # top-level ones already were, above. + if len(path) > 1 and not re.search(rf"`comline {re.escape(name)}\b", page): + drift |= report("Commands", {name}, set()) + own = parse_flags(run_help(path)) - GLOBAL_FLAGS all_real_flags |= own # A flag absent from the whole page is undocumented. Checking # page-wide rather than per-row keeps prose that explains a flag in a # paragraph instead of the table from reading as drift. - drift |= report(f"`comline {command}`", own - doc_flags, set()) + drift |= report(f"`comline {name}`", own - doc_flags, set()) if args.verbose and own: - print(f"\n`comline {command}` documented: {', '.join(sorted(own & doc_flags))}") + print(f"\n`comline {name}` documented: {', '.join(sorted(own & doc_flags))}") # The other direction, checked once against the union: a flag the docs # still describe after the CLI dropped or renamed it. Per-command this diff --git a/scripts/sync-language-support.py b/scripts/sync-language-support.py index cde8f61..a3a6b1e 100644 --- a/scripts/sync-language-support.py +++ b/scripts/sync-language-support.py @@ -37,7 +37,7 @@ 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 \\ - --runtime-features ../runtime/runtime/conformance/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 python3 scripts/sync-language-support.py --render-reports # at build time @@ -76,8 +76,8 @@ # The wire corpus, and where each language's runtime writes its report: # (repository, path in it). -CORPUS = ("runtime", "runtime/conformance/features.json") -VECTORS = "https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/{id}.json" +CORPUS = ("runtime", "runtime/conformance/spec/features.json") +VECTORS = "https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/spec/vectors/{id}.json" RUNTIMES = { "rust": ("runtime", "runtime/conformance/reports/rust.json"), "typescript": ("comline-typescript", "runtime/conformance-report.json"), @@ -127,8 +127,13 @@ "partial": "🟡 partial", "ignored": "⚪ ignored", "unsupported": "❌ unsupported", + "not_reported": "❔ not reported", } +# A feature the corpus has and a runtime's report doesn't mention yet: its +# report predates the feature. +NOT_REPORTED = {"state": "not_reported"} + def read_json(file: Path | None, repo: str, rev: str, path: str) -> dict: if file: @@ -242,7 +247,7 @@ def runtime_matrix(corpus: dict, reports: dict[str, dict]) -> str: lines.append("|---|" + "---|" * len(reports)) for feature in corpus["features"]: row = [f"{feature['title']}
`{feature['id']}`"] - row += [state_with_detail(report["support"][feature["id"]]) for report in reports.values()] + row += [state_with_detail(report["support"].get(feature["id"], NOT_REPORTED)) for report in reports.values()] lines.append("| " + " | ".join(row) + " |") return "\n".join(lines) @@ -255,7 +260,7 @@ def runtime_table(corpus: dict, report: dict) -> str: "|---|---|---|---|", ] for feature in corpus["features"]: - claim = report["support"][feature["id"]] + claim = report["support"].get(feature["id"], NOT_REPORTED) lines.append( f"| {feature['title']}
`{feature['id']}` | {cell(feature['description'])} " f"| {runtime_state(claim)} | {runtime_proof(feature['id'], claim)} |"