From efb734323252ab912e8829768e9195b3910c13d4 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Wed, 11 Nov 2026 10:36:01 +0800 Subject: [PATCH 1/2] compiler: conformance cases for given-up guarantees (core#224) Schema graphs as data with the outcome a compiler must reproduce: the guarantees each protocol gives up and who acknowledged them, and the diagnostics a build reports. Written compactly in compiler/src, generated into compiler/cases/*.json, held to specs/compiler.cue and specs/compiler.jq by specs/check.sh. --- README.md | 6 + compiler/cases/acceptance.json | 270 +++++++++++++++++++++++ compiler/cases/bounded.json | 376 ++++++++++++++++++++++++++++++++ compiler/cases/chain.json | 289 +++++++++++++++++++++++++ compiler/cases/keyed.json | 183 ++++++++++++++++ compiler/cases/marker.json | 251 +++++++++++++++++++++ compiler/cases/package.json | 384 +++++++++++++++++++++++++++++++++ compiler/readme.md | 174 +++++++++++++++ compiler/src/acceptance.cue | 135 ++++++++++++ compiler/src/bounded.cue | 222 +++++++++++++++++++ compiler/src/chain.cue | 150 +++++++++++++ compiler/src/keyed.cue | 111 ++++++++++ compiler/src/lib.cue | 110 ++++++++++ compiler/src/marker.cue | 125 +++++++++++ compiler/src/package.cue | 176 +++++++++++++++ specs/check.sh | 37 +++- specs/compiler.cue | 117 ++++++++++ specs/compiler.jq | 91 ++++++++ specs/gen/compiler.schema.json | 358 ++++++++++++++++++++++++++++++ specs/readme.md | 5 +- 20 files changed, 3567 insertions(+), 3 deletions(-) create mode 100644 compiler/cases/acceptance.json create mode 100644 compiler/cases/bounded.json create mode 100644 compiler/cases/chain.json create mode 100644 compiler/cases/keyed.json create mode 100644 compiler/cases/marker.json create mode 100644 compiler/cases/package.json create mode 100644 compiler/readme.md create mode 100644 compiler/src/acceptance.cue create mode 100644 compiler/src/bounded.cue create mode 100644 compiler/src/chain.cue create mode 100644 compiler/src/keyed.cue create mode 100644 compiler/src/lib.cue create mode 100644 compiler/src/marker.cue create mode 100644 compiler/src/package.cue create mode 100644 specs/compiler.cue create mode 100644 specs/compiler.jq create mode 100644 specs/gen/compiler.schema.json diff --git a/README.md b/README.md index 1df1fa0..6dbe619 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,9 @@ will read it. - `vectors/.json`: that feature's cases. - [`benches/`](benches/README.md): the benchmarks every runtime runs, in the same value encoding. +- [`compiler/`](compiler/readme.md): compiler conformance cases, schema + graphs with the guarantees they give up and the diagnostics a build must + report, for a compiler or any tool that judges a package. - [`specs/`](specs/readme.md): the format of each of these files, in CUE, and the JSON Schemas generated from it, which each file names in `$schema`. @@ -422,6 +425,9 @@ profile states it until live cross-runtime calls can prove it (see below). ## Implementing the spec +A compiler or another tool that judges packages vendors `compiler/cases/` +instead, and runs it as [`compiler/readme.md`](compiler/readme.md) says. + Vendor `features.json`, `vectors/` and `profiles/` at a pinned commit of this repository, and `specs/gen/` too if you want their `$schema` to resolve; a reader ignores it. `catalog/gen/catalog.json` holds the names and their diff --git a/compiler/cases/acceptance.json b/compiler/cases/acceptance.json new file mode 100644 index 0000000..3a31d6c --- /dev/null +++ b/compiler/cases/acceptance.json @@ -0,0 +1,270 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "acceptance", + "cases": [ + { + "id": "acceptance/not-accepted", + "description": "an unverified protocol of a dependency has to be accepted", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the 2009 gateway\"\nprotocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing" + } + ] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Billing` is unverified, giving up schema agreement and encoding agreement", + "the 2009 gateway" + ] + } + }, + { + "id": "acceptance/accepted", + "description": "accepted for exactly what it gives up, it builds", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the 2009 gateway\"\nprotocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n accept_unverified = { Billing = [\"schema_agreement\", \"encoding_agreement\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing", + "accept_unverified": { + "Billing": [ + "schema_agreement", + "encoding_agreement" + ] + } + } + ] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "acceptance/accepted-for-less", + "description": "accepted for less than it gives up, it stops again", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the 2009 gateway\"\nprotocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n accept_unverified = { Billing = [\"schema_agreement\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing", + "accept_unverified": { + "Billing": [ + "schema_agreement" + ] + } + } + ] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Billing` now gives up schema agreement and encoding agreement", + "it was accepted for schema agreement" + ] + } + }, + { + "id": "acceptance/accepted-for-more", + "description": "accepted for more than it gives up, it stops too: the set has to match exactly", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the 2009 gateway\"\nprotocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n accept_unverified = { Billing = [\"schema_agreement\", \"encoding_agreement\", \"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing", + "accept_unverified": { + "Billing": [ + "schema_agreement", + "encoding_agreement", + "bounded_size" + ] + } + } + ] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Billing` now gives up schema agreement and encoding agreement" + ] + } + }, + { + "id": "acceptance/package-reasons-shown", + "description": "what the package said once is what the consumer is shown to accept", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway only speaks one encoding\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing" + } + ] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Billing` is unverified, giving up schema agreement and encoding agreement", + "schema agreement \"the gateway pins schemas by contract\"", + "encoding agreement \"the gateway only speaks one encoding\"" + ] + } + }, + { + "id": "acceptance/judged-by-its-own-package", + "description": "a dependency is judged by its own package's settings and default handshake, not the consumer's", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nhandshake = \"none\"\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = \"the 2009 gateway\"\nprotocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n accept_unverified = { Billing = [\"schema_agreement\", \"encoding_agreement\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing", + "accept_unverified": { + "Billing": [ + "schema_agreement", + "encoding_agreement" + ] + } + } + ] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + } + ] +} diff --git a/compiler/cases/bounded.json b/compiler/cases/bounded.json new file mode 100644 index 0000000..bcf203a --- /dev/null +++ b/compiler/cases/bounded.json @@ -0,0 +1,376 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "bounded", + "cases": [ + { + "id": "bounded/string-unmarked", + "description": "a string without a maximum is an error where no marker gives bounded size up", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function put(s: string);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded", + "severity": "error" + } + ] + } + }, + { + "id": "bounded/list-unmarked", + "description": "a list without a maximum is an error too", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function put(xs: u8[]);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded", + "severity": "error" + } + ] + } + }, + { + "id": "bounded/bounded", + "description": "a string and a list with maximums give nothing up", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function put(s: char[max 64], xs: u8[max 16]);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "bounded/string-marked", + "description": "a marked protocol gives bounded_size up for a string without a maximum", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = \"the uploader streams whatever it's given\"\nprotocol P {\n function put(s: string);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "the uploader streams whatever it's given" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::bounded-size", + "severity": "warning" + } + ] + } + }, + { + "id": "bounded/keyed-for-something-else", + "description": "a keyed marker that doesn't list bounded_size doesn't cover a string without a maximum", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = { version_honesty = \"not this\" }\nprotocol P {\n function put(s: string);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-guarantee", + "severity": "error" + } + ] + } + }, + { + "id": "bounded/recursion-unmarked", + "description": "a type that contains itself without @max_depth is an error", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Node {\n optional next: Node\n}\n\nprotocol P {\n function f(n: Node);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded-depth", + "severity": "error" + } + ] + } + }, + { + "id": "bounded/recursion-marked", + "description": "a marked protocol gives bounded_size up for a type that contains itself without @max_depth", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Node {\n optional next: Node\n}\n\n@unverified = \"trees are small in practice\"\nprotocol P {\n function f(n: Node);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "trees are small in practice" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::bounded-size", + "severity": "warning" + } + ] + } + }, + { + "id": "bounded/recursion-max-depth", + "description": "a type that contains itself under @max_depth gives nothing up", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@max_depth = 4\nstruct Node {\n optional next: Node\n}\n\nprotocol P {\n function f(n: Node);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "bounded/other-schema-unmarked", + "description": "a type from another schema that holds a string without a maximum is unbounded where an unmarked protocol uses it", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/models.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + }, + { + "path": "src/api.ids", + "text": "use models::Blob\n\nprotocol Orders {\n function send(b: Blob);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded", + "severity": "error" + } + ] + } + }, + { + "id": "bounded/other-schema-marked", + "description": "a marked protocol using it gives bounded_size up, as the one that declares it does", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/models.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + }, + { + "path": "src/api.ids", + "text": "use models::Blob\n\n@unverified = \"orders carry the upload\"\nprotocol Orders {\n function send(b: Blob);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "Upload", + "given_up": [ + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "the uploader streams whatever it's given" + } + ] + }, + { + "name": "Orders", + "given_up": [ + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "orders carry the upload" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::bounded-size", + "severity": "warning" + } + ] + } + }, + { + "id": "bounded/other-schema-bounded", + "description": "a type bounded where it is declared is bounded where it is used", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/models.ids", + "text": "struct Blob {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use models::Blob\n\nprotocol Orders {\n function send(b: Blob);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "Orders", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [] + } + } + ] +} diff --git a/compiler/cases/chain.json b/compiler/cases/chain.json new file mode 100644 index 0000000..6a36334 --- /dev/null +++ b/compiler/cases/chain.json @@ -0,0 +1,289 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "chain", + "cases": [ + { + "id": "chain/unmarked-is-unbounded", + "description": "a type that holds another package's unbounded value, two packages away, is unbounded where an unmarked protocol uses it", + "packages": [ + { + "name": "a", + "config": "congregation a\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "b", + "config": "congregation b\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n a = {\n path = \"../a\"\n accept_unverified = { Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use a::api::Blob\n\nstruct Wrapper {\n blob: Blob\n}\n\n@unverified = \"wrapping uploads\"\nprotocol Wrap {\n function wrap(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "a", + "accept_unverified": { + "Upload": [ + "bounded_size" + ] + } + } + ] + }, + { + "name": "c", + "config": "congregation c\nspecification_version = 1\ndependencies = {\n b = {\n path = \"../b\"\n accept_unverified = { Wrap = [\"bounded_size\"] Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use b::api::Wrapper\n\nprotocol Orders {\n function send(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "b", + "accept_unverified": { + "Wrap": [ + "bounded_size" + ], + "Upload": [ + "bounded_size" + ] + } + } + ] + } + ], + "build": "c", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded", + "severity": "error" + } + ] + } + }, + { + "id": "chain/marked-gives-up", + "description": "a marked protocol using it gives bounded_size up, for its own consumers to accept", + "packages": [ + { + "name": "a", + "config": "congregation a\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "b", + "config": "congregation b\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n a = {\n path = \"../a\"\n accept_unverified = { Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use a::api::Blob\n\nstruct Wrapper {\n blob: Blob\n}\n\n@unverified = \"wrapping uploads\"\nprotocol Wrap {\n function wrap(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "a", + "accept_unverified": { + "Upload": [ + "bounded_size" + ] + } + } + ] + }, + { + "name": "c", + "config": "congregation c\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n b = {\n path = \"../b\"\n accept_unverified = { Wrap = [\"bounded_size\"] Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use b::api::Wrapper\n\n@unverified = \"orders carry the upload\"\nprotocol Orders {\n function send(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "b", + "accept_unverified": { + "Wrap": [ + "bounded_size" + ], + "Upload": [ + "bounded_size" + ] + } + } + ] + } + ], + "build": "c", + "expect": { + "protocols": [ + { + "name": "Orders", + "given_up": [ + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "orders carry the upload" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::bounded-size", + "severity": "warning" + } + ] + } + }, + { + "id": "chain/acceptance-needs-every-link", + "description": "accepting b's protocol is not enough: a's, which b's package contains, is accepted too", + "packages": [ + { + "name": "a", + "config": "congregation a\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "b", + "config": "congregation b\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n a = {\n path = \"../a\"\n accept_unverified = { Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use a::api::Blob\n\nstruct Wrapper {\n blob: Blob\n}\n\n@unverified = \"wrapping uploads\"\nprotocol Wrap {\n function wrap(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "a", + "accept_unverified": { + "Upload": [ + "bounded_size" + ] + } + } + ] + }, + { + "name": "c", + "config": "congregation c\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n b = {\n path = \"../b\"\n accept_unverified = { Wrap = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use b::api::Wrapper\n\n@unverified = \"orders carry the upload\"\nprotocol Orders {\n function send(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "b", + "accept_unverified": { + "Wrap": [ + "bounded_size" + ] + } + } + ] + } + ], + "build": "c", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Upload` is unverified, giving up bounded size" + ] + } + }, + { + "id": "chain/middle-doesnt-accept-the-first", + "description": "b's own build fails when it doesn't accept a's protocol, so building c does", + "packages": [ + { + "name": "a", + "config": "congregation a\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "b", + "config": "congregation b\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n a = {\n path = \"../a\"\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use a::api::Blob\n\nstruct Wrapper {\n blob: Blob\n}\n\n@unverified = \"wrapping uploads\"\nprotocol Wrap {\n function wrap(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "a" + } + ] + }, + { + "name": "c", + "config": "congregation c\nspecification_version = 1\ndependencies = {\n b = {\n path = \"../b\"\n accept_unverified = { Wrap = [\"bounded_size\"] Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use b::api::Wrapper\n\nprotocol Orders {\n function send(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "b", + "accept_unverified": { + "Wrap": [ + "bounded_size" + ], + "Upload": [ + "bounded_size" + ] + } + } + ] + } + ], + "build": "c", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Upload` is unverified, giving up bounded size" + ] + } + } + ] +} diff --git a/compiler/cases/keyed.json b/compiler/cases/keyed.json new file mode 100644 index 0000000..42e1f4f --- /dev/null +++ b/compiler/cases/keyed.json @@ -0,0 +1,183 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "keyed", + "cases": [ + { + "id": "keyed/exact-set", + "description": "a reason for each guarantee given up, and no others", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = {\n schema_agreement = \"the gateway predates Comline\",\n encoding_agreement = \"the gateway only speaks one encoding\"\n}\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "protocol", + "reason": "the gateway predates Comline" + }, + { + "guarantee": "encoding_agreement", + "scope": "protocol", + "reason": "the gateway only speaks one encoding" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "keyed/unknown-guarantee", + "description": "a key that is no guarantee's id is an error", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = {\n schema_agreement = \"the gateway predates Comline\",\n encoding_agreement = \"the gateway only speaks one encoding\",\n bounded_sise = \"a typo\"\n}\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::unknown-guarantee", + "severity": "error" + } + ] + } + }, + { + "id": "keyed/missing-guarantee", + "description": "a guarantee given up and not listed is an error", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = { schema_agreement = \"the gateway predates Comline\" }\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-guarantee", + "severity": "error" + } + ] + } + }, + { + "id": "keyed/not-given-up", + "description": "a guarantee listed and not given up is a warning, and not frozen", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = {\n schema_agreement = \"the gateway predates Comline\",\n encoding_agreement = \"the gateway only speaks one encoding\",\n version_honesty = \"just in case\"\n}\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::not-given-up", + "severity": "warning" + }, + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "keyed/duplicate-guarantee", + "description": "a guarantee listed twice is an error", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = {\n schema_agreement = \"the gateway predates Comline\",\n encoding_agreement = \"the gateway only speaks one encoding\",\n schema_agreement = \"again\"\n}\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::duplicate-guarantee", + "severity": "error" + } + ] + } + } + ] +} diff --git a/compiler/cases/marker.json b/compiler/cases/marker.json new file mode 100644 index 0000000..5cbbe84 --- /dev/null +++ b/compiler/cases/marker.json @@ -0,0 +1,251 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "marker", + "cases": [ + { + "id": "marker/gate-off", + "description": "@unverified is refused where the package's settings don't allow it", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the gateway predates Comline\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "settings::forbidden", + "severity": "error" + } + ] + } + }, + { + "id": "marker/missing-marker", + "description": "a protocol with no handshake gives up two guarantees and has to say why", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-marker", + "severity": "error" + } + ] + } + }, + { + "id": "marker/plain-marker", + "description": "one reason covers everything a protocol gives up, and it is frozen as the set", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the gateway predates Comline\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "protocol", + "reason": "the gateway predates Comline" + }, + { + "guarantee": "encoding_agreement", + "scope": "protocol", + "reason": "the gateway predates Comline" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "marker/package-handshake-unmarked", + "description": "the package's default handshake counts: a protocol that takes none has to say why", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-marker", + "severity": "error" + } + ] + } + }, + { + "id": "marker/package-handshake-marked", + "description": "the marker covers what the package's default handshake gives up", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = \"legacy\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "protocol", + "reason": "legacy" + }, + { + "guarantee": "encoding_agreement", + "scope": "protocol", + "reason": "legacy" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "marker/missing-reason", + "description": "a marker with a blank reason is an error", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \" \"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-reason", + "severity": "error" + } + ] + } + }, + { + "id": "marker/nothing-given-up", + "description": "a marker where nothing is given up is a warning, and freezes nothing", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = \"just in case\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::nothing-given-up", + "severity": "warning" + } + ] + } + } + ] +} diff --git a/compiler/cases/package.json b/compiler/cases/package.json new file mode 100644 index 0000000..2b8d112 --- /dev/null +++ b/compiler/cases/package.json @@ -0,0 +1,384 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "package", + "cases": [ + { + "id": "package/keyed-covers-inherited", + "description": "the package says why for a protocol that takes the package's handshake", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + }, + { + "guarantee": "encoding_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "package/plain-covers-inherited", + "description": "the plain form covers every guarantee a package setting gives up", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = \"the gateway pins schemas by contract\"\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + }, + { + "guarantee": "encoding_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "package/own-handshake-not-covered", + "description": "a protocol with its own @handshake isn't covered by the package", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n\n@handshake = \"none\"\nprotocol Q {\n function g();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-marker", + "severity": "error" + } + ] + } + }, + { + "id": "package/own-handshake-marked", + "description": "a protocol with its own @handshake says why itself; the package covers the other", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n\n@handshake = \"none\"\n@unverified = \"Q talks to the gateway directly\"\nprotocol Q {\n function g();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + }, + { + "guarantee": "encoding_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + } + ] + }, + { + "name": "Q", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "protocol", + "reason": "Q talks to the gateway directly" + }, + { + "guarantee": "encoding_agreement", + "scope": "protocol", + "reason": "Q talks to the gateway directly" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "package/wrong-scope", + "description": "bounded_size can't be acknowledged at package scope", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nunverified = { bounded_size = \"the gateway pins schemas by contract\" }\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::wrong-scope", + "severity": "error" + } + ] + } + }, + { + "id": "package/not-given-up", + "description": "a guarantee the package lists and no protocol gives up through it is a warning", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::not-given-up", + "severity": "warning" + } + ] + } + }, + { + "id": "package/gate-off", + "description": "the package's unverified is held to the same gate as the marker", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "settings::forbidden", + "severity": "error" + } + ] + } + }, + { + "id": "package/adds-bounded-size", + "description": "a marker says why for bounded_size, which the package can't; the package says the rest", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = { bounded_size = \"the uploader streams whatever it's given\" }\nprotocol P {\n function put(s: string);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement", + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + }, + { + "guarantee": "encoding_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + }, + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "the uploader streams whatever it's given" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + }, + { + "code": "unverified::bounded-size", + "severity": "warning" + } + ] + } + }, + { + "id": "package/bounded-size-not-covered", + "description": "the package covering the handshake doesn't cover an unbounded string", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function put(s: string);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded", + "severity": "error" + } + ] + } + } + ] +} diff --git a/compiler/readme.md b/compiler/readme.md new file mode 100644 index 0000000..0045c42 --- /dev/null +++ b/compiler/readme.md @@ -0,0 +1,174 @@ +# Compiler conformance cases + +Schema graphs as data, each with the outcome any compiler must reproduce: +core, the language server, or another tool, the way a runtime must reproduce +the [vectors](../README.md#the-corpus)' bytes. The cases say which guarantees a +protocol gives up, who acknowledged them and why, and which errors and +warnings a build reports, for the rules of +[the proposal](https://github.com/ComlineProject/docs/blob/proposals/shared-vocabulary/docs/docs/proposals/shared-vocabulary/granular-unverified.md) +that core implements today. They are +[core#224](https://github.com/ComlineProject/core/issues/224)'s, and the +outcomes are those of core at `d1b678a`. + +| What | Where | +| --- | --- | +| The cases, one JSON file a group | [`cases/.json`](cases) | +| The format of a file, in CUE, and as JSON Schema | [`specs/compiler.cue`](../specs/compiler.cue), [`specs/gen/compiler.schema.json`](../specs/gen/compiler.schema.json) | +| The cases' source, which the JSON is generated from | [`src/`](src) | +| What the schema can't say, checked by `jq` | [`specs/compiler.jq`](../specs/compiler.jq) | + +`specs/check.sh` regenerates `cases/` from `src/` and vets it, and CI runs it +with `--check`, which fails when a file is stale. Edit `src/`, never `cases/`. + +## A case + +```json +{ + "id": "marker/missing-marker", + "description": "a protocol with no handshake gives up two guarantees and has to say why", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-marker", + "severity": "error" + } + ] + } +} +``` + +- **`id`** is `/`, the group being the file's. An id is stable, + as a vector's is. +- **`description`** is one line. +- **`packages`** are the packages of the case: the one to build and those it + depends on, directly or not. Each has a `name`, which is its congregation's, + its directory's and how its dependants say it in `use`; its `config.idp` as + `config`, whole; its `schemas`, each a `path` under the package + (`src/.ids`, as on disk) and its `text`; and its `dependencies`: + the packages it depends on by path (`../`) and, for each, what the + config accepts of its unverified protocols (`accept_unverified`, a protocol + and the guarantee ids it gives up). The config text declares the same: the + compiler reads that, and `dependencies` restates it so a runner can lay the + packages out and a check can hold them to each other without reading + `config.idp`. A package never depends on itself or in a cycle. +- **`build`** names the package to build. +- **`expect`** is the outcome, below. + +Texts are written as they are, with the newlines JSON escapes. In a schema's +annotation a dictionary's entries are separated by commas +(`@unverified = { a = "..." , b = "..." }`); in `config.idp` by whitespace. + +### What is expected + +**`builds`** says whether the package builds. + +For a build that **succeeds**: + +- **`protocols`** lists every protocol of the package built, not those of its + dependencies, and no others, each with: + - **`given_up`**: the guarantee ids it gives up, the set frozen with it. + An order says nothing. A protocol that gives up nothing has `[]`. + - **`acknowledged`**, where the case asserts it: for each guarantee listed, + the **`scope`** it was acknowledged at, `protocol` (the protocol's own + `@unverified`, which wins where both say) or `package` (`config.idp`'s + `unverified`, which core freezes with the protocol as + `unverified_package`), and the **`reason`** shown for it. A guarantee not + listed isn't asserted. Only a guarantee given up is listed. +- **`diagnostics`** are the warnings the build reports for the package's own + schemas and config, and no others: a warning of a dependency is its authors' + to act on, and is not the case's. + +For a build that **fails**: + +- **`diagnostics`** are the errors with a code, and no others. +- **`error_contains`**, for an error without a code, lists text its message + contains. Core reports a dependency that isn't accepted as a plain error. + The substrings are minimal and as stable as core's wording; they are + **provisional**, and go when those errors get codes. +- A failing build says why with one or the other. It has no `protocols`, and + no warnings: they aren't reported once a build fails. + +A diagnostic is `{ "code", "severity" }`, matched on both and never on message +text, as a set: each once, in any order. The codes the corpus uses are a +closed list in [`specs/compiler.cue`](../specs/compiler.cue): a rule's code +that isn't there has no case yet. A case is written so that its outcome has +one cause, so which stage of a compiler stops the build first doesn't matter. + +## Running a case + +For each case in each file of `cases/`: + +1. Write every package into its own directory, side by side: + `//config.idp` from `config`, and each schema at its `path` + under `//`. +2. Build the package named by `build`, as `comline build` would resolve its + dependencies from the paths its config declares, and no further (no + fetching, no code generation). +3. Compare: whether it built, then per `expect`. The frozen set and the + acknowledgements are what the build froze with each protocol; the + diagnostics are what it reported, by code and severity. + +A tool that can only compile one package's sources in memory can't run the +cases with `dependencies`, which are in `acceptance` and `chain`. + +## The corpus + +| Group | Covers | +| --- | --- | +| `marker` | the gate (`annotations.unverified.allowed`); a marker required where a protocol gives something up (its own `@handshake`, the package's default); its reason; a marker where nothing is given up | +| `keyed` | `@unverified = { = "" }`: the exact set, an unknown id, a missing one, one listed that isn't given up, one listed twice | +| `package` | `unverified` in `config.idp`: the keyed and plain forms covering what a protocol takes from the package's settings; a protocol with its own `@handshake` not covered; `unverified::wrong-scope` for `bounded_size`; a guarantee no protocol gives up through it; the gate; a marker adding `bounded_size` | +| `bounded` | `bounded_size`: a string or list without a maximum, a type that contains itself without `@max_depth`, a type from another schema of the package that holds one, each unmarked (an error) and marked (given up), and the bounded variants | +| `acceptance` | a dependency's unverified protocols accepted under it in `config.idp`: not at all, exactly, for less, for more; the reasons the consumer is shown; the dependency judged by its own package | +| `chain` | three packages, `c` depending on `b` depending on `a`: a type holding `a`'s unbounded value, used in `c`; and the acceptance resolving `b` asks for `a`'s protocols too | + +A case's `description` says what it shows. Each rule has a passing and a +failing variant. + +### To come + +Cases for rules core doesn't implement yet, which go in when it does: +acknowledgements at the inner scopes (function, argument, field and type), +an outer scope covering an inner one, `strict`, pinning an acceptance to a +chain of packages and its invalidation, and failing closed. + +## Taking the cases + +Vendor `compiler/cases/*.json` at a pinned revision of this repository, as core +does the size vectors (`core/tests/spec/`): a `REV` file with the commit, a +`vendor.sh --check` in CI that fails when the copy differs from it, and a test +that the `REV` is the `comline-catalog` revision core is pinned to, since the +cases name guarantees as the catalog does. `specs/gen/compiler.schema.json` is +the format as JSON Schema, for a reader that wants it; a reader ignores the +`$schema` each file names. + +The files of a group are never split or renamed, and ids don't change. A +group or a case may be added, and a case's expected outcome changed, only as +the compiler's behaviour changes, in a pull request that says so. + +## Writing a case + +Cases are written in [`src/`](src), in CUE, where a package's files are +multi-line strings and a protocol's expected outcome a struct; the comment +at the top of [`src/lib.cue`](src/lib.cue) says how it becomes JSON. Run +`specs/check.sh` to regenerate `cases/`. + +A case should have one cause: where two things are wrong at once, which one a +tool reports first can differ, so it isn't a good case. Derive the outcome from +the compiler's tests and code, and state in the pull request any you aren't +sure of. diff --git a/compiler/src/acceptance.cue b/compiler/src/acceptance.cue new file mode 100644 index 0000000..98077a1 --- /dev/null +++ b/compiler/src/acceptance.cue @@ -0,0 +1,135 @@ +package cases + +// Dependency acceptance: every unverified protocol of a dependency has to be +// accepted by the consumer, under the dependency in its `config.idp`, for +// exactly the guarantees it gives up. It is an error without a code, so these +// cases say what the message contains. + +// A package whose `Billing` runs no handshake, marked. +_billing: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = "the 2009 gateway" + protocol Billing { + function charge(); + } + """ +} + +_consumerSchema: """ + struct A { + x: u32 + } + """ + +groups: acceptance: { + "not-accepted": { + about: "an unverified protocol of a dependency has to be accepted" + packages: { + billing: _billing + app: {schemas: api: _consumerSchema, dependencies: billing: {}} + } + build: "app" + expect: { + builds: false + error_contains: [ + "protocol `Billing` is unverified, giving up schema agreement and encoding agreement", + "the 2009 gateway", + ] + } + } + "accepted": { + about: "accepted for exactly what it gives up, it builds" + packages: { + billing: _billing + app: { + schemas: api: _consumerSchema + dependencies: billing: accept: Billing: ["schema_agreement", "encoding_agreement"] + } + } + build: "app" + expect: {builds: true, protocols: {}} + } + "accepted-for-less": { + about: "accepted for less than it gives up, it stops again" + packages: { + billing: _billing + app: { + schemas: api: _consumerSchema + dependencies: billing: accept: Billing: ["schema_agreement"] + } + } + build: "app" + expect: { + builds: false + error_contains: [ + "protocol `Billing` now gives up schema agreement and encoding agreement", + "it was accepted for schema agreement", + ] + } + } + "accepted-for-more": { + about: "accepted for more than it gives up, it stops too: the set has to match exactly" + packages: { + billing: _billing + app: { + schemas: api: _consumerSchema + dependencies: billing: accept: Billing: ["schema_agreement", "encoding_agreement", "bounded_size"] + } + } + build: "app" + expect: { + builds: false + error_contains: ["protocol `Billing` now gives up schema agreement and encoding agreement"] + } + } + "package-reasons-shown": { + about: "what the package said once is what the consumer is shown to accept" + packages: { + billing: { + config: ["handshake = \"none\"", """ + unverified = { + schema_agreement = "the gateway pins schemas by contract" + encoding_agreement = "the gateway only speaks one encoding" + } + """, _allow] + schemas: api: """ + protocol Billing { + function charge(); + } + """ + } + app: {schemas: api: _consumerSchema, dependencies: billing: {}} + } + build: "app" + expect: { + builds: false + error_contains: [ + "protocol `Billing` is unverified, giving up schema agreement and encoding agreement", + "schema agreement \"the gateway pins schemas by contract\"", + "encoding agreement \"the gateway only speaks one encoding\"", + ] + } + } + "judged-by-its-own-package": { + about: "a dependency is judged by its own package's settings and default handshake, not the consumer's" + packages: { + billing: { + config: ["handshake = \"none\"", _allow] + schemas: api: """ + @unverified = "the 2009 gateway" + protocol Billing { + function charge(); + } + """ + } + app: { + schemas: api: _consumerSchema + dependencies: billing: accept: Billing: ["schema_agreement", "encoding_agreement"] + } + } + build: "app" + expect: {builds: true, protocols: {}} + } +} diff --git a/compiler/src/bounded.cue b/compiler/src/bounded.cue new file mode 100644 index 0000000..5878955 --- /dev/null +++ b/compiler/src/bounded.cue @@ -0,0 +1,222 @@ +package cases + +// Bounded size: every string, list and nesting a protocol reaches has a +// maximum, or the protocol gives up `bounded_size` with `@unverified`. + +_streams: "the uploader streams whatever it's given" + +// A type another schema of the package declares, held by a protocol there +// that is marked, so the string without a maximum is its to give up. +_models: """ + struct Blob { + data: string + } + + @unverified = "\(_streams)" + protocol Upload { + function put(b: Blob); + } + """ + +groups: bounded: { + "string-unmarked": { + about: "a string without a maximum is an error where no marker gives bounded size up" + packages: app: schemas: api: """ + protocol P { + function put(s: string); + } + """ + build: "app" + expect: {builds: false, errors: ["bounds::unbounded"]} + } + "list-unmarked": { + about: "a list without a maximum is an error too" + packages: app: schemas: api: """ + protocol P { + function put(xs: u8[]); + } + """ + build: "app" + expect: {builds: false, errors: ["bounds::unbounded"]} + } + "bounded": { + about: "a string and a list with maximums give nothing up" + packages: app: schemas: api: """ + protocol P { + function put(s: char[max 64], xs: u8[max 16]); + } + """ + build: "app" + expect: { + builds: true + protocols: P: given_up: [] + warnings: [] + } + } + "string-marked": { + about: "a marked protocol gives bounded_size up for a string without a maximum" + packages: app: { + config: [_allow] + schemas: api: """ + @unverified = "\(_streams)" + protocol P { + function put(s: string); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: _streams} + } + warnings: ["unverified::bounded-size"] + } + } + "keyed-for-something-else": { + about: "a keyed marker that doesn't list bounded_size doesn't cover a string without a maximum" + packages: app: { + config: [_allow] + schemas: api: """ + @unverified = { version_honesty = "not this" } + protocol P { + function put(s: string); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-guarantee"]} + } + "recursion-unmarked": { + about: "a type that contains itself without @max_depth is an error" + packages: app: schemas: api: """ + struct Node { + optional next: Node + } + + protocol P { + function f(n: Node); + } + """ + build: "app" + expect: {builds: false, errors: ["bounds::unbounded-depth"]} + } + "recursion-marked": { + about: "a marked protocol gives bounded_size up for a type that contains itself without @max_depth" + packages: app: { + config: [_allow] + schemas: api: """ + struct Node { + optional next: Node + } + + @unverified = "trees are small in practice" + protocol P { + function f(n: Node); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: "trees are small in practice"} + } + warnings: ["unverified::bounded-size"] + } + } + "recursion-max-depth": { + about: "a type that contains itself under @max_depth gives nothing up" + packages: app: schemas: api: """ + @max_depth = 4 + struct Node { + optional next: Node + } + + protocol P { + function f(n: Node); + } + """ + build: "app" + expect: { + builds: true + protocols: P: given_up: [] + warnings: [] + } + } + "other-schema-unmarked": { + about: "a type from another schema that holds a string without a maximum is unbounded where an unmarked protocol uses it" + packages: app: { + config: [_allow] + schemas: { + models: _models + api: """ + use models::Blob + + protocol Orders { + function send(b: Blob); + } + """ + } + } + build: "app" + expect: {builds: false, errors: ["bounds::unbounded"]} + } + "other-schema-marked": { + about: "a marked protocol using it gives bounded_size up, as the one that declares it does" + packages: app: { + config: [_allow] + schemas: { + models: _models + api: """ + use models::Blob + + @unverified = "orders carry the upload" + protocol Orders { + function send(b: Blob); + } + """ + } + } + build: "app" + expect: { + builds: true + protocols: { + Upload: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: _streams} + } + Orders: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: "orders carry the upload"} + } + } + warnings: ["unverified::bounded-size"] + } + } + "other-schema-bounded": { + about: "a type bounded where it is declared is bounded where it is used" + packages: app: schemas: { + models: """ + struct Blob { + data: char[max 64] + } + """ + api: """ + use models::Blob + + protocol Orders { + function send(b: Blob); + } + """ + } + build: "app" + expect: { + builds: true + protocols: Orders: given_up: [] + warnings: [] + } + } +} diff --git a/compiler/src/chain.cue b/compiler/src/chain.cue new file mode 100644 index 0000000..b44d3f4 --- /dev/null +++ b/compiler/src/chain.cue @@ -0,0 +1,150 @@ +package cases + +// Three packages: `c` depends on `b`, which depends on `a`. `a`'s `Blob` +// holds a string without a maximum that only its own marked `Upload` +// reaches; `b` holds it in `Wrapper`, which only its own marked `Wrap` +// reaches; `c` uses `Wrapper` in `Orders`. +// +// Resolving a dependency takes accepting every unverified protocol of its +// package and of the packages it depends on, as its own build saw them: `c` +// accepts `Upload` as well as `Wrap`. + +_a: { + config: [_allow] + schemas: api: """ + struct Blob { + data: string + } + + @unverified = "the uploader streams whatever it's given" + protocol Upload { + function put(b: Blob); + } + """ +} + +// `b`, which depends on `a`. +_b: { + config: [_allow] + schemas: api: """ + use a::api::Blob + + struct Wrapper { + blob: Blob + } + + @unverified = "wrapping uploads" + protocol Wrap { + function wrap(w: Wrapper); + } + """ + dependencies: a: {} +} + +// `b` accepting `a`'s `Upload`. +_bAccepting: _b & {dependencies: a: accept: Upload: ["bounded_size"]} + +groups: chain: { + "unmarked-is-unbounded": { + about: "a type that holds another package's unbounded value, two packages away, is unbounded where an unmarked protocol uses it" + packages: { + a: _a + b: _bAccepting + c: { + schemas: api: """ + use b::api::Wrapper + + protocol Orders { + function send(w: Wrapper); + } + """ + dependencies: b: accept: { + Wrap: ["bounded_size"] + Upload: ["bounded_size"] + } + } + } + build: "c" + expect: {builds: false, errors: ["bounds::unbounded"]} + } + "marked-gives-up": { + about: "a marked protocol using it gives bounded_size up, for its own consumers to accept" + packages: { + a: _a + b: _bAccepting + c: { + config: [_allow] + schemas: api: """ + use b::api::Wrapper + + @unverified = "orders carry the upload" + protocol Orders { + function send(w: Wrapper); + } + """ + dependencies: b: accept: { + Wrap: ["bounded_size"] + Upload: ["bounded_size"] + } + } + } + build: "c" + expect: { + builds: true + protocols: Orders: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: "orders carry the upload"} + } + warnings: ["unverified::bounded-size"] + } + } + "acceptance-needs-every-link": { + about: "accepting b's protocol is not enough: a's, which b's package contains, is accepted too" + packages: { + a: _a + b: _bAccepting + c: { + config: [_allow] + schemas: api: """ + use b::api::Wrapper + + @unverified = "orders carry the upload" + protocol Orders { + function send(w: Wrapper); + } + """ + dependencies: b: accept: Wrap: ["bounded_size"] + } + } + build: "c" + expect: { + builds: false + error_contains: ["protocol `Upload` is unverified, giving up bounded size"] + } + } + "middle-doesnt-accept-the-first": { + about: "b's own build fails when it doesn't accept a's protocol, so building c does" + packages: { + a: _a + b: _b + c: { + schemas: api: """ + use b::api::Wrapper + + protocol Orders { + function send(w: Wrapper); + } + """ + dependencies: b: accept: { + Wrap: ["bounded_size"] + Upload: ["bounded_size"] + } + } + } + build: "c" + expect: { + builds: false + error_contains: ["protocol `Upload` is unverified, giving up bounded size"] + } + } +} diff --git a/compiler/src/keyed.cue b/compiler/src/keyed.cue new file mode 100644 index 0000000..52e7e60 --- /dev/null +++ b/compiler/src/keyed.cue @@ -0,0 +1,111 @@ +package cases + +// The keyed form, `@unverified = { = "" }`: a reason for +// each guarantee given up, under its id in the catalog. In a schema, the +// entries are separated by commas. +groups: keyed: { + "exact-set": { + about: "a reason for each guarantee given up, and no others" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = { + schema_agreement = "the gateway predates Comline", + encoding_agreement = "the gateway only speaks one encoding" + } + protocol P { + function f(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "protocol", reason: "the gateway predates Comline"} + encoding_agreement: {scope: "protocol", reason: "the gateway only speaks one encoding"} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "unknown-guarantee": { + about: "a key that is no guarantee's id is an error" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = { + schema_agreement = "the gateway predates Comline", + encoding_agreement = "the gateway only speaks one encoding", + bounded_sise = "a typo" + } + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::unknown-guarantee"]} + } + "missing-guarantee": { + about: "a guarantee given up and not listed is an error" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = { schema_agreement = "the gateway predates Comline" } + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-guarantee"]} + } + "not-given-up": { + about: "a guarantee listed and not given up is a warning, and not frozen" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = { + schema_agreement = "the gateway predates Comline", + encoding_agreement = "the gateway only speaks one encoding", + version_honesty = "just in case" + } + protocol P { + function f(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: given_up: ["schema_agreement", "encoding_agreement"] + warnings: ["unverified::not-given-up", "unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "duplicate-guarantee": { + about: "a guarantee listed twice is an error" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = { + schema_agreement = "the gateway predates Comline", + encoding_agreement = "the gateway only speaks one encoding", + schema_agreement = "again" + } + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::duplicate-guarantee"]} + } +} diff --git a/compiler/src/lib.cue b/compiler/src/lib.cue new file mode 100644 index 0000000..f2fad88 --- /dev/null +++ b/compiler/src/lib.cue @@ -0,0 +1,110 @@ +package cases + +import ( + "list" + "strings" +) + +// The cases are written here, compactly, and `specs/check.sh` exports them as +// `compiler/cases/.json`, in the shape `specs/compiler.cue` gives +// (`#CompilerCases`). That is the file runners read; this is its source. +// +// A source case differs from its JSON in being easier to write: +// +// - `packages` is a struct by package name. A package's `config.idp` is +// `congregation ` and `specification_version = 1`, then each line of +// `config`, then the `dependencies` it declares by path (`../`), +// each with the unverified protocols it accepts. A schema is written +// under its namespace, `api` for `src/api.ids`. Every file ends in a +// newline. +// - `expect.protocols` is a struct by protocol name, and `acknowledged` one +// by guarantee. `errors` and `warnings` are codes, and become the +// `diagnostics`. + +// The package setting that lets a protocol say `@unverified`. +_allow: "settings = { annotations = { unverified = { allowed = true } } }" + +#Case: { + about!: string + packages!: [string]: { + config: [...string] | *[] + schemas: [string]: string + dependencies: [string]: {accept?: [string]: [...string]} + } + build!: string + expect!: { + builds!: bool + protocols?: [string]: { + given_up!: [...string] + acknowledged?: [string]: {scope!: "protocol" | "package", reason?: string} + } + errors?: [...string] + warnings?: [...string] + error_contains?: [...string] + } +} + +// Each group file declares `groups: : : #Case`. +groups: [string]: [string]: #Case + +// A package's `dependencies` block, which declares each by path and lists +// the unverified protocols it accepts. +_dependencies: { + deps: [string]: {accept?: [string]: [...string]} + text: strings.Join([for d, v in deps { + "dependencies = {\n \(d) = {\n path = \"../\(d)\"\n\(_accept[d]) }\n}\n" + }], "") + _accept: { + for d, v in deps { + (d): strings.Join([if v.accept != _|_ { + " accept_unverified = { " + strings.Join([for proto, ids in v.accept { + "\(proto) = [" + strings.Join([for id in ids {"\"\(id)\""}], ", ") + "]" + }], " ") + " }\n" + }], "") + } + } +} + +// What a case is as JSON. +out: { + for G, _ in groups {(G): { + $schema: "../../specs/gen/compiler.schema.json" + group: G + cases: [for n, c in groups[G] { + id: "\(G)/\(n)" + description: c.about + packages: [for name, p in c.packages { + let d = _dependencies & {deps: p.dependencies} + "name": name + config: strings.Join(list.Concat([["congregation \(name)", "specification_version = 1"], p.config]), "\n") + "\n" + d.text + schemas: [for path, text in p.schemas {"path": "src/\(path).ids", "text": text + "\n"}] + dependencies: [for dep, v in p.dependencies { + name: dep + if v.accept != _|_ {accept_unverified: v.accept} + }] + }] + build: c.build + expect: { + builds: c.expect.builds + if c.expect.protocols != _|_ { + protocols: [for name, p in c.expect.protocols { + "name": name + given_up: p.given_up + if p.acknowledged != _|_ { + acknowledged: [for g, a in p.acknowledged { + guarantee: g + scope: a.scope + if a.reason != _|_ {reason: a.reason} + }] + } + }] + } + diagnostics: list.Concat([ + if c.expect.errors != _|_ {[for e in c.expect.errors {code: e, severity: "error"}]}, + if c.expect.warnings != _|_ {[for w in c.expect.warnings {code: w, severity: "warning"}]}, + ]) + if c.expect.error_contains != _|_ {error_contains: c.expect.error_contains} + } + }] + }} +} diff --git a/compiler/src/marker.cue b/compiler/src/marker.cue new file mode 100644 index 0000000..f0e9647 --- /dev/null +++ b/compiler/src/marker.cue @@ -0,0 +1,125 @@ +package cases + +groups: marker: { + "gate-off": { + about: "@unverified is refused where the package's settings don't allow it" + packages: app: schemas: api: """ + @handshake = "none" + @unverified = "the gateway predates Comline" + protocol P { + function f(); + } + """ + build: "app" + expect: {builds: false, errors: ["settings::forbidden"]} + } + "missing-marker": { + about: "a protocol with no handshake gives up two guarantees and has to say why" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-marker"]} + } + "plain-marker": { + about: "one reason covers everything a protocol gives up, and it is frozen as the set" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = "the gateway predates Comline" + protocol P { + function f(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "protocol", reason: "the gateway predates Comline"} + encoding_agreement: {scope: "protocol", reason: "the gateway predates Comline"} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "package-handshake-unmarked": { + about: "the package's default handshake counts: a protocol that takes none has to say why" + packages: app: { + config: ["handshake = \"none\"", _allow] + schemas: api: """ + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-marker"]} + } + "package-handshake-marked": { + about: "the marker covers what the package's default handshake gives up" + packages: app: { + config: ["handshake = \"none\"", _allow] + schemas: api: """ + @unverified = "legacy" + protocol P { + function f(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "protocol", reason: "legacy"} + encoding_agreement: {scope: "protocol", reason: "legacy"} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "missing-reason": { + about: "a marker with a blank reason is an error" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = " " + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-reason"]} + } + "nothing-given-up": { + about: "a marker where nothing is given up is a warning, and freezes nothing" + packages: app: { + config: [_allow] + schemas: api: """ + @unverified = "just in case" + protocol P { + function f(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: given_up: [] + warnings: ["unverified::nothing-given-up"] + } + } +} diff --git a/compiler/src/package.cue b/compiler/src/package.cue new file mode 100644 index 0000000..d9e498d --- /dev/null +++ b/compiler/src/package.cue @@ -0,0 +1,176 @@ +package cases + +// The package's own `unverified`, in `config.idp`: why the package gives up +// what its own settings give up, once for every protocol that takes them. +// In `config.idp`, a dictionary's entries are separated by whitespace. + +_why: "the gateway pins schemas by contract" +_noHandshake: "handshake = \"none\"" +_packageKeyed: """ + unverified = { + schema_agreement = "\(_why)" + encoding_agreement = "\(_why)" + } + """ +_bare: """ + protocol P { + function f(); + } + """ + +groups: package: { + "keyed-covers-inherited": { + about: "the package says why for a protocol that takes the package's handshake" + packages: app: {config: [_noHandshake, _packageKeyed, _allow], schemas: api: _bare} + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "package", reason: _why} + encoding_agreement: {scope: "package", reason: _why} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "plain-covers-inherited": { + about: "the plain form covers every guarantee a package setting gives up" + packages: app: { + config: [_noHandshake, "unverified = \"\(_why)\"", _allow] + schemas: api: _bare + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "package", reason: _why} + encoding_agreement: {scope: "package", reason: _why} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "own-handshake-not-covered": { + about: "a protocol with its own @handshake isn't covered by the package" + packages: app: { + config: [_noHandshake, _packageKeyed, _allow] + schemas: api: """ + protocol P { + function f(); + } + + @handshake = "none" + protocol Q { + function g(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-marker"]} + } + "own-handshake-marked": { + about: "a protocol with its own @handshake says why itself; the package covers the other" + packages: app: { + config: [_noHandshake, _packageKeyed, _allow] + schemas: api: """ + protocol P { + function f(); + } + + @handshake = "none" + @unverified = "Q talks to the gateway directly" + protocol Q { + function g(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: { + P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "package", reason: _why} + encoding_agreement: {scope: "package", reason: _why} + } + } + Q: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "protocol", reason: "Q talks to the gateway directly"} + encoding_agreement: {scope: "protocol", reason: "Q talks to the gateway directly"} + } + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "wrong-scope": { + about: "bounded_size can't be acknowledged at package scope" + packages: app: { + config: ["unverified = { bounded_size = \"\(_why)\" }", _allow] + schemas: api: _bare + } + build: "app" + expect: {builds: false, errors: ["unverified::wrong-scope"]} + } + "not-given-up": { + about: "a guarantee the package lists and no protocol gives up through it is a warning" + packages: app: {config: [_packageKeyed, _allow], schemas: api: _bare} + build: "app" + expect: { + builds: true + protocols: P: given_up: [] + warnings: ["unverified::not-given-up"] + } + } + "gate-off": { + about: "the package's unverified is held to the same gate as the marker" + packages: app: {config: [_noHandshake, _packageKeyed], schemas: api: _bare} + build: "app" + expect: {builds: false, errors: ["settings::forbidden"]} + } + "adds-bounded-size": { + about: "a marker says why for bounded_size, which the package can't; the package says the rest" + packages: app: { + config: [_noHandshake, _packageKeyed, _allow] + schemas: api: """ + @unverified = { bounded_size = "the uploader streams whatever it's given" } + protocol P { + function put(s: string); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement", "bounded_size"] + acknowledged: { + schema_agreement: {scope: "package", reason: _why} + encoding_agreement: {scope: "package", reason: _why} + bounded_size: {scope: "protocol", reason: "the uploader streams whatever it's given"} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement", "unverified::bounded-size"] + } + } + "bounded-size-not-covered": { + about: "the package covering the handshake doesn't cover an unbounded string" + packages: app: { + config: [_noHandshake, _packageKeyed, _allow] + schemas: api: """ + protocol P { + function put(s: string); + } + """ + } + build: "app" + expect: {builds: false, errors: ["bounds::unbounded"]} + } +} diff --git a/specs/check.sh b/specs/check.sh index 7e961e2..e9eaa21 100755 --- a/specs/check.sh +++ b/specs/check.sh @@ -2,8 +2,9 @@ # Generates gen/*.schema.json (and benches/bench.schema.json, which ships with # the benches so a vendored copy of them is whole) from the specs, and # features.json, catalog/gen/catalog.json and rust/src/catalog.rs from the -# catalog, and vets every corpus file against them (and, with jq, holds the -# size rules to their vectors). `--check` fails instead of +# catalog, and compiler/cases/*.json from compiler/src, and vets every corpus +# file against them (and, with jq, holds the size rules to their vectors and the +# compiler cases to what their schema can't say). `--check` fails instead of # writing when a generated file is stale. set -eu cd "$(dirname "$0")" @@ -36,6 +37,7 @@ vet() { # ... } generate Bench ../benches/bench.schema.json +generate CompilerCases gen/compiler.schema.json generate Features gen/features.schema.json generate Profile gen/profile.schema.json generate Report gen/report.schema.json @@ -73,6 +75,21 @@ else rust_catalog > ../rust/src/catalog.rs fi +# The compiler cases, written compactly in compiler/src, as the JSON runners +# read (compiler/readme.md): one file per group. +groups=$(cue eval ../compiler/src -e 'strings.Join([for g, _ in groups {g}], "\n")' --out text) +for group in $groups; do + if $check; then + if ! cue export ../compiler/src -e "out.\"$group\"" | cmp -s - "../compiler/cases/$group.json"; then + echo "../compiler/cases/$group.json is out of date: run specs/check.sh" >&2 + failed=1 + fi + else + mkdir -p ../compiler/cases + cue export ../compiler/src -e "out.\"$group\"" -o "../compiler/cases/$group.json" -f + fi +done + # profiles/ and vectors/ hold exactly what the catalog names. same_names() { # if [ "$(printf '%s\n' "$2" | sort)" != "$(printf '%s\n' "$3" | sort)" ]; then @@ -85,6 +102,8 @@ names_in() { # } same_names profiles "$(cue export ../catalog -e 'strings.Join(sets.profiled, "\n")' --out text)" "$(names_in ../profiles)" same_names vectors "$(cue export ../catalog -e 'strings.Join(sets.features, "\n")' --out text)" "$(names_in ../vectors)" +# compiler/cases/ holds exactly the groups compiler/src declares. +same_names "compiler cases" "$groups" "$(names_in ../compiler/cases)" for file in ../profiles/*.json; do if ! cue vet -c -d '#OfficialProfile' ../catalog "json:" "$file"; then echo "$file isn't the profile the catalog gives its encoding" >&2 @@ -117,6 +136,19 @@ vet Bench $(ls ../benches/*.json | grep -v '/bench\.schema\.json$') vet Features ../features.json vet Profile ../profiles/*.json vet Vectors ../vectors/*.json +vet CompilerCases ../compiler/cases/*.json + +# What the compiler cases' schema can't say (`specs/compiler.jq`). +for file in ../compiler/cases/*.json; do + if ! problems=$(jq -r -f compiler.jq "$file"); then + echo "$file can't be read as compiler cases" >&2 + failed=1 + elif [ -n "$problems" ]; then + echo "$file has problems:" >&2 + echo "$problems" >&2 + failed=1 + fi +done # `reports/` and `support/` live in each runtime's repository, which vets them # against its vendored copy of these specs. @@ -138,6 +170,7 @@ through() { # ... through ../benches/bench.schema.json ../benches/connection.json ../benches/framings.json ../benches/handshake.json through gen/features.schema.json ../features.json through gen/profile.schema.json ../profiles/*.json +through gen/compiler.schema.json ../compiler/cases/*.json through gen/vectors.schema.json ../vectors/envelope.json ../vectors/framing-*.json ../vectors/handshake*.json \ ../vectors/name-hash.json ../vectors/stream.json diff --git a/specs/compiler.cue b/specs/compiler.cue new file mode 100644 index 0000000..9c7a736 --- /dev/null +++ b/specs/compiler.cue @@ -0,0 +1,117 @@ +package conformance + +import "github.com/comlineproject/specification/catalog" + +// `compiler/cases/.json`: compiler conformance cases. Each is a schema +// graph as data, with the outcome any compiler must reproduce for it: the +// way runtimes reproduce the vectors' bytes. `compiler/readme.md` says what +// a case holds and how a compiler runs one. +#CompilerCases: close({ + $schema?: string + // The file's name: every case's id is `/`. + group!: =~"^[a-z0-9-]+$" + cases!: [...#CompilerCase] +}) + +#CompilerCase: close({ + id!: #CaseId + // One line. + description!: =~"^[^\n]+$" + // The case's packages: one to build, and the ones it depends on, directly + // or not. Each is a directory named after it, side by side. + packages!: [#CompilerPackage, ...#CompilerPackage] + // The package to build: one of `packages`. + build!: #CompilerPackageName + expect!: #CompilerExpect +}) + +// A package's name is its congregation's, its directory's and the name +// its dependants use it by in `use`. +#CompilerPackageName: =~"^[a-z][a-z0-9_]*$" + +#CompilerPackage: close({ + name!: #CompilerPackageName + // `config.idp`, whole. + config!: string + // The schema files, `src/.ids`. + schemas!: [...close({ + path!: =~"^src/([a-z][a-z0-9_]*/)*[a-z][a-z0-9_]*\\.ids$" + text!: string + })] + // The packages this one depends on by path (`../`), as `config` + // declares them. Restated here so a runner can lay the packages out, and + // a check can hold them to `config`, without reading `config.idp`. + dependencies!: [...close({ + name!: #CompilerPackageName + // What `config` accepts of the dependency's unverified protocols: a + // protocol's name and the guarantees it gives up, which have to be + // exactly its set. + accept_unverified?: [string]: [...#CompilerGuarantee] + })] +}) + +// A guarantee's id in the catalog. +#CompilerGuarantee: or([for id, _ in catalog.guarantees {id}]) + +// What building the package gives. A build that succeeds says what each of +// its protocols gives up, and its warnings; one that fails, its errors, as +// codes where they have one and else as text. +#CompilerExpect: #CompilerBuilds | #CompilerFails + +#CompilerBuilds: close({ + builds!: true + // Every protocol of the package built, and no others. + protocols!: [...#CompilerProtocol] + // The warnings, and no others. + diagnostics!: [...#CompilerWarning] +}) + +#CompilerFails: close({ + builds!: false + // The errors, and no others, of those that have a code. + diagnostics!: [...#CompilerError] + // For an error without a code: text its message contains. Provisional, + // until such errors get codes. + error_contains?: [string, ...string] +}) + +#CompilerProtocol: close({ + name!: =~"^[A-Z][A-Za-z0-9]*$" + // The guarantees it gives up, as a set: what is frozen with it. + given_up!: [...#CompilerGuarantee] + // Who acknowledged some of what it gives up, and the reason shown for it, + // where the case asserts it: guarantees it doesn't list aren't asserted. + acknowledged?: [...close({ + guarantee!: #CompilerGuarantee + // Where the acknowledgement was written: on the protocol, or in + // `config.idp` for the package. + scope!: catalog.#Scope & ("package" | "protocol") + reason?: string + })] +}) + +// A diagnostic is matched on its code and severity, not its message. The +// vocabulary is closed; a code not here has no case yet. +#CompilerDiagnostic: #CompilerError | #CompilerWarning + +#CompilerError: or([ + close({code!: "unverified::missing-marker", severity!: "error"}), + close({code!: "unverified::missing-reason", severity!: "error"}), + close({code!: "unverified::unknown-guarantee", severity!: "error"}), + close({code!: "unverified::duplicate-guarantee", severity!: "error"}), + close({code!: "unverified::missing-guarantee", severity!: "error"}), + close({code!: "unverified::wrong-scope", severity!: "error"}), + close({code!: "bounds::unbounded", severity!: "error"}), + close({code!: "bounds::unbounded-depth", severity!: "error"}), + close({code!: "settings::forbidden", severity!: "error"}), +]) + +#CompilerWarning: or([ + close({code!: "unverified::not-given-up", severity!: "warning"}), + close({code!: "unverified::nothing-given-up", severity!: "warning"}), + close({code!: "unverified::schema-agreement", severity!: "warning"}), + close({code!: "unverified::encoding-agreement", severity!: "warning"}), + close({code!: "unverified::encoding-conformance", severity!: "warning"}), + close({code!: "unverified::bounded-size", severity!: "warning"}), + close({code!: "unverified::version-honesty", severity!: "warning"}), +]) diff --git a/specs/compiler.jq b/specs/compiler.jq new file mode 100644 index 0000000..c4ce27c --- /dev/null +++ b/specs/compiler.jq @@ -0,0 +1,91 @@ +# Holds a compiler conformance file (`compiler/cases/.json`) to what +# its schema (`#CompilerCases`) can't say: `specs/check.sh` runs this on +# each file, and fails on any line it prints. +# +# - every case's id is `/`, and ids are unique; +# - the case's package names are unique, `build` and every dependency name +# one of them (not the package itself), and the dependencies have no cycle; +# - a package's schema paths are unique, and its `config` declares each +# dependency by path (`../`), and accepts what `accept_unverified` +# says; +# - `expect` names each protocol of the package built, once, and no +# others; a protocol's given-up guarantees and its acknowledged ones are +# sets, and only those given up are acknowledged; +# - an acknowledgement's reason is written in the package built; +# - diagnostics are unique; +# - a build that fails says why: an error with a code, or text it contains. + +def protocols_of($package): + [$package.schemas[].text | scan("(?m)^protocol ([A-Za-z0-9_]+)") | .[0]]; + +def duplicates: group_by(.) | map(select(length > 1) | .[0]); + +# Packages that remain after dropping the ones whose dependencies are all gone, +# until none is left or none can go: the cycle, if any. +def stuck($packages): + reduce range(0; $packages | length + 1) as $_ ( + $packages; + . as $left + | ($left | map(.name)) as $names + | map(select(any(.dependencies[].name; . as $d | $names | index($d)))) + ); + +. as $file +| .cases[] +| . as $case +| ($case.id) as $id +| ( + (if ($id | startswith($file.group + "/")) then empty else "\($id): not in group \($file.group)" end), + ($case.packages | map(.name)) as $names + | ( + ($names | duplicates | map("\($id): package \(.) twice") | .[]), + (if ($names | index($case.build)) then empty else "\($id): builds \($case.build), which is no package" end), + ($case.packages[] | . as $p + | ( + ($p.dependencies[] | .name as $d + | (if $d == $p.name then "\($id): \($p.name) depends on itself" + elif ($names | index($d)) then empty + else "\($id): \($p.name) depends on \($d), which is no package" end), + (if ($p.config | contains("path = \"../\($d)\"")) then empty + else "\($id): \($p.name)'s config doesn't declare \($d) by path" end), + ((.accept_unverified // {}) | to_entries[] + | (.key as $protocol | .value as $ids + | (if ($p.config | contains("\($protocol) = [" + ($ids | map("\"\(.)\"") | join(", ")) + "]")) + then empty + else "\($id): \($p.name)'s config doesn't accept \($protocol) for \($ids | join(", "))" end), + (if ($ids | length) == ($ids | unique | length) then empty + else "\($id): \($p.name) accepts a guarantee of \($protocol) twice" end)))), + ($p.schemas | map(.path) | duplicates | map("\($id): \($p.name) has \(.) twice") | .[]) + )), + (if (stuck($case.packages) | length) > 0 + then "\($id): packages depend on each other in a cycle: \(stuck($case.packages) | map(.name) | join(", "))" + else empty end), + ($case.packages[] | select(.name == $case.build) as $built + | $case.expect as $expect + | ( + ($expect.diagnostics | map(.code) | duplicates | map("\($id): diagnostic \(.) twice") | .[]), + (if $expect.builds then + (protocols_of($built) | sort) as $declared + | ($expect.protocols | map(.name) | sort) as $listed + | (if $declared == $listed then empty + else "\($id): expects protocols \($listed | join(", ")), and \($built.name) declares \($declared | join(", "))" end), + ($expect.protocols[] + | . as $protocol + | (if (.given_up | length) == (.given_up | unique | length) then empty + else "\($id): \($protocol.name) gives up a guarantee twice" end), + ((.acknowledged // []) | map(.guarantee) as $acknowledged + | (if ($acknowledged | length) == ($acknowledged | unique | length) then empty + else "\($id): \($protocol.name) acknowledges a guarantee twice" end), + ($acknowledged[] | select(. as $g | $protocol.given_up | index($g) | not) + | "\($id): \($protocol.name) acknowledges \(.), which it doesn't give up")), + ((.acknowledged // [])[] | select(.reason != null) + | . as $a + | if ($built.schemas | any(.text | contains($a.reason))) or ($built.config | contains($a.reason)) then empty + else "\($id): \($protocol.name)'s reason for \($a.guarantee) isn't written in \($built.name)" end)) + else + (if ($expect.diagnostics | length) > 0 or (($expect.error_contains // []) | length) > 0 then empty + else "\($id): fails and says neither an error nor text it contains" end) + end) + )) + ) + ) diff --git a/specs/gen/compiler.schema.json b/specs/gen/compiler.schema.json new file mode 100644 index 0000000..5613bbd --- /dev/null +++ b/specs/gen/compiler.schema.json @@ -0,0 +1,358 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$defs": { + "CaseId": { + "type": "string", + "description": "A vector case's id: `/`.", + "pattern": "^[a-z0-9.@_-]+/[a-z0-9.@_-]+$" + }, + "CompilerBuilds": { + "type": "object", + "additionalProperties": false, + "properties": { + "builds": { + "const": true + }, + "diagnostics": { + "type": "array", + "description": "The warnings, and no others.", + "items": { + "$ref": "#/$defs/CompilerWarning" + } + }, + "protocols": { + "type": "array", + "description": "Every protocol of the package built, and no others.", + "items": { + "$ref": "#/$defs/CompilerProtocol" + } + } + }, + "required": [ + "builds", + "diagnostics", + "protocols" + ] + }, + "CompilerCase": { + "type": "object", + "additionalProperties": false, + "properties": { + "build": { + "description": "The package to build: one of `packages`.", + "$ref": "#/$defs/CompilerPackageName" + }, + "description": { + "type": "string", + "description": "One line.", + "pattern": "^[^\n]+$" + }, + "expect": { + "$ref": "#/$defs/CompilerExpect" + }, + "id": { + "$ref": "#/$defs/CaseId" + }, + "packages": { + "type": "array", + "description": "The case's packages: one to build, and the ones it depends on, directly\nor not. Each is a directory named after it, side by side.", + "items": { + "$ref": "#/$defs/CompilerPackage" + }, + "prefixItems": [ + { + "$ref": "#/$defs/CompilerPackage" + } + ], + "minItems": 1 + } + }, + "required": [ + "build", + "description", + "expect", + "id", + "packages" + ] + }, + "CompilerError": { + "enum": [ + { + "code": "unverified::missing-marker", + "severity": "error" + }, + { + "code": "unverified::missing-reason", + "severity": "error" + }, + { + "code": "unverified::unknown-guarantee", + "severity": "error" + }, + { + "code": "unverified::duplicate-guarantee", + "severity": "error" + }, + { + "code": "unverified::missing-guarantee", + "severity": "error" + }, + { + "code": "unverified::wrong-scope", + "severity": "error" + }, + { + "code": "bounds::unbounded", + "severity": "error" + }, + { + "code": "bounds::unbounded-depth", + "severity": "error" + }, + { + "code": "settings::forbidden", + "severity": "error" + } + ] + }, + "CompilerExpect": { + "description": "What building the package gives. A build that succeeds says what each of\nits protocols gives up, and its warnings; one that fails, its errors, as\ncodes where they have one and else as text.", + "anyOf": [ + { + "$ref": "#/$defs/CompilerBuilds" + }, + { + "$ref": "#/$defs/CompilerFails" + } + ] + }, + "CompilerFails": { + "type": "object", + "additionalProperties": false, + "properties": { + "builds": { + "const": false + }, + "diagnostics": { + "type": "array", + "description": "The errors, and no others, of those that have a code.", + "items": { + "$ref": "#/$defs/CompilerError" + } + }, + "error_contains": { + "type": "array", + "description": "For an error without a code: text its message contains. Provisional,\nuntil such errors get codes.", + "items": { + "type": "string" + }, + "prefixItems": [ + { + "type": "string" + } + ], + "minItems": 1 + } + }, + "required": [ + "builds", + "diagnostics" + ] + }, + "CompilerGuarantee": { + "description": "A guarantee's id in the catalog.", + "enum": [ + "schema_agreement", + "encoding_agreement", + "encoding_conformance", + "version_honesty", + "bounded_size" + ] + }, + "CompilerPackage": { + "type": "object", + "additionalProperties": false, + "properties": { + "config": { + "type": "string", + "description": "`config.idp`, whole." + }, + "dependencies": { + "type": "array", + "description": "The packages this one depends on by path (`../`), as `config`\ndeclares them. Restated here so a runner can lay the packages out, and\na check can hold them to `config`, without reading `config.idp`.", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "accept_unverified": { + "type": "object", + "description": "What `config` accepts of the dependency's unverified protocols: a\nprotocol's name and the guarantees it gives up, which have to be\nexactly its set.", + "additionalProperties": { + "type": "array", + "items": { + "$ref": "#/$defs/CompilerGuarantee" + } + } + }, + "name": { + "$ref": "#/$defs/CompilerPackageName" + } + }, + "required": [ + "name" + ] + } + }, + "name": { + "$ref": "#/$defs/CompilerPackageName" + }, + "schemas": { + "type": "array", + "description": "The schema files, `src/.ids`.", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "path": { + "type": "string", + "pattern": "^src/([a-z][a-z0-9_]*/)*[a-z][a-z0-9_]*\\.ids$" + }, + "text": { + "type": "string" + } + }, + "required": [ + "path", + "text" + ] + } + } + }, + "required": [ + "config", + "dependencies", + "name", + "schemas" + ] + }, + "CompilerPackageName": { + "type": "string", + "description": "A package's name is its congregation's, its directory's and the name\nits dependants use it by in `use`.", + "pattern": "^[a-z][a-z0-9_]*$" + }, + "CompilerProtocol": { + "type": "object", + "additionalProperties": false, + "properties": { + "acknowledged": { + "type": "array", + "description": "Who acknowledged some of what it gives up, and the reason shown for it,\nwhere the case asserts it: guarantees it doesn't list aren't asserted.", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "guarantee": { + "$ref": "#/$defs/CompilerGuarantee" + }, + "reason": { + "type": "string" + }, + "scope": { + "description": "Where the acknowledgement was written: on the protocol, or in\n`config.idp` for the package.", + "$ref": "#/$defs/Scope", + "enum": [ + "package", + "protocol" + ] + } + }, + "required": [ + "guarantee", + "scope" + ] + } + }, + "given_up": { + "type": "array", + "description": "The guarantees it gives up, as a set: what is frozen with it.", + "items": { + "$ref": "#/$defs/CompilerGuarantee" + } + }, + "name": { + "type": "string", + "pattern": "^[A-Z][A-Za-z0-9]*$" + } + }, + "required": [ + "given_up", + "name" + ] + }, + "CompilerWarning": { + "enum": [ + { + "code": "unverified::not-given-up", + "severity": "warning" + }, + { + "code": "unverified::nothing-given-up", + "severity": "warning" + }, + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-conformance", + "severity": "warning" + }, + { + "code": "unverified::bounded-size", + "severity": "warning" + }, + { + "code": "unverified::version-honesty", + "severity": "warning" + } + ] + }, + "Scope": { + "enum": [ + "package", + "protocol", + "function", + "argument", + "field", + "type" + ] + } + }, + "type": "object", + "description": "`compiler/cases/.json`: compiler conformance cases. Each is a schema\ngraph as data, with the outcome any compiler must reproduce for it: the\nway runtimes reproduce the vectors' bytes. `compiler/readme.md` says what\na case holds and how a compiler runs one.", + "additionalProperties": false, + "properties": { + "$schema": { + "type": "string" + }, + "cases": { + "type": "array", + "items": { + "$ref": "#/$defs/CompilerCase" + } + }, + "group": { + "type": "string", + "description": "The file's name: every case's id is `/`.", + "pattern": "^[a-z0-9-]+$" + } + }, + "required": [ + "cases", + "group" + ] +} diff --git a/specs/readme.md b/specs/readme.md index b01fc8f..6cb220a 100644 --- a/specs/readme.md +++ b/specs/readme.md @@ -8,6 +8,7 @@ runtime that vendors `benches/` alone has it. | Definition | Files | Spec | | --- | --- | --- | | `#Bench` | `benches/*.json` | [`bench.cue`](bench.cue) | +| `#CompilerCases` | `compiler/cases/*.json` | [`compiler.cue`](compiler.cue) | | `#Features` | `features.json` | [`features.cue`](features.cue) | | `#Profile` | `profiles/*.json` | [`profile.cue`](profile.cue) | | `#Report` | `reports/.json`, in each runtime's repository | [`report.cue`](report.cue) | @@ -29,7 +30,9 @@ catalog, and vets every file. It also checks that `profiles/` and `vectors/` hold exactly what the catalog names, and, with [`jq`](https://jqlang.github.io/jq/) ([`sizes.jq`](sizes.jq)), that each format's size rules are proven by its size vectors: every rule lists cases that exist and show it, every case proves -a rule, and every witness is as long as its case says. CI runs `./check.sh --check`, which fails +a rule, and every witness is as long as its case says. It generates +`../compiler/cases/` from `../compiler/src/` (the [compiler cases](../compiler/readme.md)), +and, with [`compiler.jq`](compiler.jq), holds them to what their schema can't say. CI runs `./check.sh --check`, which fails instead when a generated file is stale. It needs [`cue`](https://cuelang.org) at the version `.github/workflows/check.yml` pins. From 9e590a2846f3f14bfe8a28c9485a76c5482a1563 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Wed, 11 Nov 2026 19:49:50 +0800 Subject: [PATCH 2/2] compiler cases: recurse through a bounded array, as an optional field doesn't end a cycle yet --- compiler/cases/bounded.json | 6 +++--- compiler/src/bounded.cue | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/compiler/cases/bounded.json b/compiler/cases/bounded.json index bcf203a..41da32b 100644 --- a/compiler/cases/bounded.json +++ b/compiler/cases/bounded.json @@ -163,7 +163,7 @@ "schemas": [ { "path": "src/api.ids", - "text": "struct Node {\n optional next: Node\n}\n\nprotocol P {\n function f(n: Node);\n}\n" + "text": "struct Node {\n kids: Node[max 4]\n}\n\nprotocol P {\n function f(n: Node);\n}\n" } ], "dependencies": [] @@ -190,7 +190,7 @@ "schemas": [ { "path": "src/api.ids", - "text": "struct Node {\n optional next: Node\n}\n\n@unverified = \"trees are small in practice\"\nprotocol P {\n function f(n: Node);\n}\n" + "text": "struct Node {\n kids: Node[max 4]\n}\n\n@unverified = \"trees are small in practice\"\nprotocol P {\n function f(n: Node);\n}\n" } ], "dependencies": [] @@ -232,7 +232,7 @@ "schemas": [ { "path": "src/api.ids", - "text": "@max_depth = 4\nstruct Node {\n optional next: Node\n}\n\nprotocol P {\n function f(n: Node);\n}\n" + "text": "@max_depth = 4\nstruct Node {\n kids: Node[max 4]\n}\n\nprotocol P {\n function f(n: Node);\n}\n" } ], "dependencies": [] diff --git a/compiler/src/bounded.cue b/compiler/src/bounded.cue index 5878955..0449776 100644 --- a/compiler/src/bounded.cue +++ b/compiler/src/bounded.cue @@ -92,7 +92,7 @@ groups: bounded: { about: "a type that contains itself without @max_depth is an error" packages: app: schemas: api: """ struct Node { - optional next: Node + kids: Node[max 4] } protocol P { @@ -108,7 +108,7 @@ groups: bounded: { config: [_allow] schemas: api: """ struct Node { - optional next: Node + kids: Node[max 4] } @unverified = "trees are small in practice" @@ -132,7 +132,7 @@ groups: bounded: { packages: app: schemas: api: """ @max_depth = 4 struct Node { - optional next: Node + kids: Node[max 4] } protocol P {