From a794e15c54914733511d94a12fe7435af25d267f Mon Sep 17 00:00:00 2001 From: Kinflou Date: Mon, 16 Nov 2026 09:05:24 +0800 Subject: [PATCH 1/3] compiler: conformance cases for qualified references (specification#14) A qualified reference starts with a name a use brought into scope, or with a root (package, parent, self, std, a dependency), as in Rust. New group references, and the codes reference::not-in-scope and reference::qualifier-not-in-scope. --- compiler/cases/references.json | 955 +++++++++++++++++++++++++++++++++ compiler/readme.md | 19 +- compiler/src/references.cue | 397 ++++++++++++++ specs/compiler.cue | 2 + specs/gen/compiler.schema.json | 8 + 5 files changed, 1379 insertions(+), 2 deletions(-) create mode 100644 compiler/cases/references.json create mode 100644 compiler/src/references.cue diff --git a/compiler/cases/references.json b/compiler/cases/references.json new file mode 100644 index 0000000..abb5898 --- /dev/null +++ b/compiler/cases/references.json @@ -0,0 +1,955 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "references", + "cases": [ + { + "id": "references/namespace-qualified", + "description": "after use package::types, types::User reaches the item", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::types\n\nstruct Account {\n owner: types::User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/namespace-bare-refused", + "description": "after use package::types a bare User is not in scope (fix: add use package::types::User, or write types::User)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::types\n\nstruct Account {\n owner: User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::not-in-scope", + "severity": "error" + } + ] + } + }, + { + "id": "references/namespace-alias-qualified", + "description": "after use package::types as t, t::User reaches the item", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::types as t\n\nstruct Account {\n owner: t::User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/namespace-alias-original-refused", + "description": "after use package::types as t, types is not in scope (fix: write t::User)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::types as t\n\nstruct Account {\n owner: types::User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::qualifier-not-in-scope", + "severity": "error" + } + ] + } + }, + { + "id": "references/item-bare", + "description": "after use package::types::User, User reaches the item", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::types::User\n\nstruct Account {\n owner: User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/item-qualified-refused", + "description": "after use package::types::User, types is not in scope (fix: write User)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::types::User\n\nstruct Account {\n owner: types::User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::qualifier-not-in-scope", + "severity": "error" + } + ] + } + }, + { + "id": "references/braces-bare", + "description": "after use package::types::{User, Order}, User reaches the item", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::types::{User, Order}\n\nstruct Account {\n owner: User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/braces-qualified-refused", + "description": "after use package::types::{User, Order}, types is not in scope (fix: write User)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::types::{User, Order}\n\nstruct Account {\n owner: types::User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::qualifier-not-in-scope", + "severity": "error" + } + ] + } + }, + { + "id": "references/glob-bare", + "description": "after use package::types::*, User reaches the item", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::types::*\n\nstruct Account {\n owner: User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/glob-qualified-refused", + "description": "after use package::types::*, types is not in scope (fix: write User)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::types::*\n\nstruct Account {\n owner: types::User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::qualifier-not-in-scope", + "severity": "error" + } + ] + } + }, + { + "id": "references/no-use-bare-refused", + "description": "a bare User with no use is not in scope (fix: add use package::types::User, or write package::types::User)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "struct Account {\n owner: User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::not-in-scope", + "severity": "error" + } + ] + } + }, + { + "id": "references/no-use-qualified-refused", + "description": "types::User with no use is not rooted in a name in scope (fix: add use package::types, or write package::types::User)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "struct Account {\n owner: types::User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::qualifier-not-in-scope", + "severity": "error" + } + ] + } + }, + { + "id": "references/full-package", + "description": "package::types::User in a field needs no use", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "struct Account {\n owner: package::types::User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/full-package-nested", + "description": "package:: reaches a schema in a directory from one beside it, in a field", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/shapes/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/shapes/api.ids", + "text": "struct Account {\n owner: package::shapes::types::User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/full-parent", + "description": "parent::common::Error in a field reaches a schema one level up from the importing schema's namespace", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/shapes/common.ids", + "text": "struct Error {\n code: u32\n}\n" + }, + { + "path": "src/shapes/api.ids", + "text": "struct Account {\n owner: parent::common::Error\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/full-self", + "description": "self::nested::Type in a field reaches a schema under the importing schema's own namespace", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Account {\n owner: self::nested::Type\n}\n" + }, + { + "path": "src/api/nested.ids", + "text": "struct Type {\n id: u32\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/full-std", + "description": "std::http::Request in a field needs no use", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Account {\n owner: std::http::Request\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/full-dependency", + "description": "a dependency's greeting::hello::Greeting in a field needs no use", + "packages": [ + { + "name": "greeting", + "config": "congregation greeting\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/hello.ids", + "text": "struct Greeting {\n text: char[max 64]\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n greeting = {\n path = \"../greeting\"\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Account {\n owner: greeting::hello::Greeting\n}\n" + } + ], + "dependencies": [ + { + "name": "greeting" + } + ] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/full-own-schema-unrooted-refused", + "description": "a full path to the package's own schema that doesn't start at package, parent or self is not rooted (fix: write package::shapes::types::User)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/shapes/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "struct Account {\n owner: shapes::types::User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::qualifier-not-in-scope", + "severity": "error" + } + ] + } + }, + { + "id": "references/descend-namespace", + "description": "after use package::billing, billing::api::Invoice reaches the nested schema", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/billing/api.ids", + "text": "struct Invoice {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::billing\n\nstruct Account {\n owner: billing::api::Invoice\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/descend-alias", + "description": "after use package::billing as b, b::api::Invoice reaches the nested schema", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/billing/api.ids", + "text": "struct Invoice {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::billing as b\n\nstruct Account {\n owner: b::api::Invoice\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/descend-dependency", + "description": "after use greeting::hello, hello::Greeting reaches the dependency's item", + "packages": [ + { + "name": "greeting", + "config": "congregation greeting\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/hello.ids", + "text": "struct Greeting {\n text: char[max 64]\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n greeting = {\n path = \"../greeting\"\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use greeting::hello\n\nstruct Account {\n owner: hello::Greeting\n}\n" + } + ], + "dependencies": [ + { + "name": "greeting" + } + ] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/descend-skips-a-segment-refused", + "description": "after use package::billing, api is not in scope (fix: write billing::api::Invoice, or use package::billing::api)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/billing/api.ids", + "text": "struct Invoice {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::billing\n\nstruct Account {\n owner: api::Invoice\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::qualifier-not-in-scope", + "severity": "error" + } + ] + } + }, + { + "id": "references/resolved-item", + "description": "use package::billing::api::Invoice, then Invoice, reaches billing::api::Invoice", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/archive.ids", + "text": "struct Invoice {\n data: string\n}\n" + }, + { + "path": "src/billing/api.ids", + "text": "struct Invoice {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::billing::api::Invoice\n\nprotocol Orders {\n function send(i: Invoice);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "Orders", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/resolved-namespace", + "description": "use package::billing::api, then api::Invoice, reaches billing::api::Invoice", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/archive.ids", + "text": "struct Invoice {\n data: string\n}\n" + }, + { + "path": "src/billing/api.ids", + "text": "struct Invoice {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::billing::api\n\nprotocol Orders {\n function send(i: api::Invoice);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "Orders", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/resolved-descent", + "description": "use package::billing, then billing::api::Invoice, reaches billing::api::Invoice", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/archive.ids", + "text": "struct Invoice {\n data: string\n}\n" + }, + { + "path": "src/billing/api.ids", + "text": "struct Invoice {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::billing\n\nprotocol Orders {\n function send(i: billing::api::Invoice);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "Orders", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/resolved-alias", + "description": "use package::billing::api as b, then b::Invoice, reaches billing::api::Invoice", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/archive.ids", + "text": "struct Invoice {\n data: string\n}\n" + }, + { + "path": "src/billing/api.ids", + "text": "struct Invoice {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::billing::api as b\n\nprotocol Orders {\n function send(i: b::Invoice);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "Orders", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/resolved-full-path", + "description": "package::billing::api::Invoice with no use reaches billing::api::Invoice", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/archive.ids", + "text": "struct Invoice {\n data: string\n}\n" + }, + { + "path": "src/billing/api.ids", + "text": "struct Invoice {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "protocol Orders {\n function send(i: package::billing::api::Invoice);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "Orders", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/resolved-decoy", + "description": "use package::archive, then archive::Invoice, reaches the unbounded Invoice, which an unmarked protocol can't use: the other cases reached billing's", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/archive.ids", + "text": "struct Invoice {\n data: string\n}\n" + }, + { + "path": "src/billing/api.ids", + "text": "struct Invoice {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::archive\n\nprotocol Orders {\n function send(i: archive::Invoice);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded", + "severity": "error" + } + ] + } + }, + { + "id": "references/existing-package-unchanged", + "description": "use package::models and models::Blob, as written before the rule, freezes the same protocols as the item use does in bounded/other-schema-marked", + "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 package::models\n\n@unverified = \"orders carry the upload\"\nprotocol Orders {\n function send(b: models::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" + } + ] + } + } + ] +} diff --git a/compiler/readme.md b/compiler/readme.md index 088b9f8..059618d 100644 --- a/compiler/readme.md +++ b/compiler/readme.md @@ -136,10 +136,25 @@ cases with `dependencies`, which are in `acceptance` and `chain`. | `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 | | `imports` | where a `use` path starts: a package's own schemas only through `package::`, `parent::` or `self::` (a bare path to one is `import::bare-own-schema-path`, in each form of a `use`), a dependency's and `std`'s paths as they were, a path matching nothing (`import::unresolved`), a schema named like a dependency, and the names a dependency can't have | +| `references` | how a type is named once imported, the Rust model: a whole-namespace `use` brings in only its name (`types::User`, and a bare `User` is `reference::not-in-scope`); a `use` of an item, `{...}` or `*` brings in the names it lists (and `types::User` after it is `reference::qualifier-not-in-scope`); a full path (`package::`, `parent::`, `self::`, `std::`, a dependency's) in a type position with no `use`; a path going down from a name in scope; each spelling reaching the same type, and a package written before the rule unchanged | | `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. +A case's `description` says what it shows, and for a refused reference the +fix its diagnostic carries (a case holds a compiler to the code and severity, +not to the fix). The `reference` codes, in +[the proposal](https://github.com/ComlineProject/docs/blob/main/docs/docs/proposals/use-paths-and-groups/relative-use.md#qualified-references): + +| Code | When | Fix | +| --- | --- | --- | +| `reference::not-in-scope` | a bare name no `use` or declaration of the file brought in: `User` after only `use package::types` | add `use package::types::User`, or write `types::User` | +| `reference::qualifier-not-in-scope` | a qualified reference whose first segment is not a name in scope or a root: `types::User` after `use package::types::User` | write `User` (or add the `use` that brings the qualifier in) | + +Each rule has a passing and a failing variant. + +The `references` group is ahead of core: its outcomes are those of the +[decision](https://github.com/ComlineProject/docs/blob/main/docs/docs/proposals/use-paths-and-groups/relative-use.md#qualified-references), +which [core#290](https://github.com/ComlineProject/core/issues/290) +implements, and core's runner fails them until then. ### To come diff --git a/compiler/src/references.cue b/compiler/src/references.cue new file mode 100644 index 0000000..5d92e63 --- /dev/null +++ b/compiler/src/references.cue @@ -0,0 +1,397 @@ +package cases + +// How a type is named once it is imported. A qualified reference starts with +// a name a `use` brought into scope, as in Rust, or with a root (`package`, +// `parent`, `self`, `std`, a dependency). Rule and decision: +// https://comlineproject.github.io/docs/proposals/use-paths-and-groups/relative-use/#qualified-references +// +// - A whole-namespace `use` brings in only its name: after +// `use package::types`, `types::User` is the way to write it, and a bare +// `User` is `reference::not-in-scope`. Fix: add `use package::types::User`, +// or write `types::User`. +// - A `use` of an item, `{ ... }` or `*` brings in the names it lists: after +// `use package::types::User`, a bare `User` and not `types::User`, which is +// `reference::qualifier-not-in-scope`. Fix: write `User`. +// - A full path works in a type position with no `use`: `package::`, +// `parent::`, `self::`, `std::` and a dependency's name are roots. +// - A path goes down from a name in scope: `billing::api::Invoice` after +// `use package::billing`. +// - A qualified reference is frozen as its resolved path, so each way of +// writing one reaches the same type. The cases can't read the frozen IR, +// so they show it by what each spelling reaches: a decoy `Invoice` in +// another schema holds an unbounded string, and the one reached holds a +// bounded one, which the protocol using it gives up nothing for. +// +// A refused reference is an error at once, with the likely rewrite as its +// fix. The fix isn't part of what a case holds a compiler to (a diagnostic is +// matched on its code and severity); it is in each case's description. + +_refTypes: """ + struct User { + id: u32 + } + + struct Order { + id: u32 + } + """ + +// A schema holding `User` as a field, whichever way the type is written. +_refHolder: { + _ref: string + text: "struct Account {\n owner: \(_ref)\n}" +} + +// A protocol using an `Invoice`, which is bounded only when it is the one in +// `billing/api`. +_refOrders: { + _ref: string + text: "protocol Orders {\n function send(i: \(_ref));\n}" +} + +_refBilling: """ + struct Invoice { + data: char[max 64] + } + """ + +// The decoy: another `Invoice`, in a schema that sorts before `billing`. +_refArchive: """ + struct Invoice { + data: string + } + """ + +_refGreeting: """ + struct Greeting { + text: char[max 64] + } + """ + +groups: references: { + // A whole-namespace `use` brings in only its name. + "namespace-qualified": { + about: "after use package::types, types::User reaches the item" + packages: app: schemas: { + types: _refTypes + api: "use package::types\n\n" + (_refHolder & {_ref: "types::User"}).text + } + build: "app" + expect: {builds: true, protocols: {}} + } + "namespace-bare-refused": { + about: "after use package::types a bare User is not in scope (fix: add use package::types::User, or write types::User)" + packages: app: schemas: { + types: _refTypes + api: "use package::types\n\n" + (_refHolder & {_ref: "User"}).text + } + build: "app" + expect: {builds: false, errors: ["reference::not-in-scope"]} + } + "namespace-alias-qualified": { + about: "after use package::types as t, t::User reaches the item" + packages: app: schemas: { + types: _refTypes + api: "use package::types as t\n\n" + (_refHolder & {_ref: "t::User"}).text + } + build: "app" + expect: {builds: true, protocols: {}} + } + "namespace-alias-original-refused": { + about: "after use package::types as t, types is not in scope (fix: write t::User)" + packages: app: schemas: { + types: _refTypes + api: "use package::types as t\n\n" + (_refHolder & {_ref: "types::User"}).text + } + build: "app" + expect: {builds: false, errors: ["reference::qualifier-not-in-scope"]} + } + + // The forms that name an item bring in the item, and not the namespace. + "item-bare": { + about: "after use package::types::User, User reaches the item" + packages: app: schemas: { + types: _refTypes + api: "use package::types::User\n\n" + (_refHolder & {_ref: "User"}).text + } + build: "app" + expect: {builds: true, protocols: {}} + } + "item-qualified-refused": { + about: "after use package::types::User, types is not in scope (fix: write User)" + packages: app: schemas: { + types: _refTypes + api: "use package::types::User\n\n" + (_refHolder & {_ref: "types::User"}).text + } + build: "app" + expect: {builds: false, errors: ["reference::qualifier-not-in-scope"]} + } + "braces-bare": { + about: "after use package::types::{User, Order}, User reaches the item" + packages: app: schemas: { + types: _refTypes + api: "use package::types::{User, Order}\n\n" + (_refHolder & {_ref: "User"}).text + } + build: "app" + expect: {builds: true, protocols: {}} + } + "braces-qualified-refused": { + about: "after use package::types::{User, Order}, types is not in scope (fix: write User)" + packages: app: schemas: { + types: _refTypes + api: "use package::types::{User, Order}\n\n" + (_refHolder & {_ref: "types::User"}).text + } + build: "app" + expect: {builds: false, errors: ["reference::qualifier-not-in-scope"]} + } + "glob-bare": { + about: "after use package::types::*, User reaches the item" + packages: app: schemas: { + types: _refTypes + api: "use package::types::*\n\n" + (_refHolder & {_ref: "User"}).text + } + build: "app" + expect: {builds: true, protocols: {}} + } + "glob-qualified-refused": { + about: "after use package::types::*, types is not in scope (fix: write User)" + packages: app: schemas: { + types: _refTypes + api: "use package::types::*\n\n" + (_refHolder & {_ref: "types::User"}).text + } + build: "app" + expect: {builds: false, errors: ["reference::qualifier-not-in-scope"]} + } + "no-use-bare-refused": { + about: "a bare User with no use is not in scope (fix: add use package::types::User, or write package::types::User)" + packages: app: schemas: { + types: _refTypes + api: (_refHolder & {_ref: "User"}).text + } + build: "app" + expect: {builds: false, errors: ["reference::not-in-scope"]} + } + "no-use-qualified-refused": { + about: "types::User with no use is not rooted in a name in scope (fix: add use package::types, or write package::types::User)" + packages: app: schemas: { + types: _refTypes + api: (_refHolder & {_ref: "types::User"}).text + } + build: "app" + expect: {builds: false, errors: ["reference::qualifier-not-in-scope"]} + } + + // A full path works in a type position without a `use`. + "full-package": { + about: "package::types::User in a field needs no use" + packages: app: schemas: { + types: _refTypes + api: (_refHolder & {_ref: "package::types::User"}).text + } + build: "app" + expect: {builds: true, protocols: {}} + } + "full-package-nested": { + about: "package:: reaches a schema in a directory from one beside it, in a field" + packages: app: schemas: { + "shapes/types": _refTypes + "shapes/api": (_refHolder & {_ref: "package::shapes::types::User"}).text + } + build: "app" + expect: {builds: true, protocols: {}} + } + "full-parent": { + about: "parent::common::Error in a field reaches a schema one level up from the importing schema's namespace" + packages: app: schemas: { + "shapes/common": "struct Error {\n code: u32\n}" + "shapes/api": (_refHolder & {_ref: "parent::common::Error"}).text + } + build: "app" + expect: {builds: true, protocols: {}} + } + "full-self": { + about: "self::nested::Type in a field reaches a schema under the importing schema's own namespace" + packages: app: schemas: { + "api": (_refHolder & {_ref: "self::nested::Type"}).text + "api/nested": "struct Type {\n id: u32\n}" + } + build: "app" + expect: {builds: true, protocols: {}} + } + "full-std": { + about: "std::http::Request in a field needs no use" + packages: app: schemas: api: (_refHolder & {_ref: "std::http::Request"}).text + build: "app" + expect: {builds: true, protocols: {}} + } + "full-dependency": { + about: "a dependency's greeting::hello::Greeting in a field needs no use" + packages: { + greeting: schemas: hello: _refGreeting + app: { + schemas: api: (_refHolder & {_ref: "greeting::hello::Greeting"}).text + dependencies: greeting: {} + } + } + build: "app" + expect: {builds: true, protocols: {}} + } + "full-own-schema-unrooted-refused": { + about: "a full path to the package's own schema that doesn't start at package, parent or self is not rooted (fix: write package::shapes::types::User)" + packages: app: schemas: { + "shapes/types": _refTypes + "api": (_refHolder & {_ref: "shapes::types::User"}).text + } + build: "app" + expect: {builds: false, errors: ["reference::qualifier-not-in-scope"]} + } + + // A path goes down from a name in scope. + "descend-namespace": { + about: "after use package::billing, billing::api::Invoice reaches the nested schema" + packages: app: schemas: { + "billing/api": _refBilling + "api": "use package::billing\n\n" + (_refHolder & {_ref: "billing::api::Invoice"}).text + } + build: "app" + expect: {builds: true, protocols: {}} + } + "descend-alias": { + about: "after use package::billing as b, b::api::Invoice reaches the nested schema" + packages: app: schemas: { + "billing/api": _refBilling + "api": "use package::billing as b\n\n" + (_refHolder & {_ref: "b::api::Invoice"}).text + } + build: "app" + expect: {builds: true, protocols: {}} + } + "descend-dependency": { + about: "after use greeting::hello, hello::Greeting reaches the dependency's item" + packages: { + greeting: schemas: hello: _refGreeting + app: { + schemas: api: "use greeting::hello\n\n" + (_refHolder & {_ref: "hello::Greeting"}).text + dependencies: greeting: {} + } + } + build: "app" + expect: {builds: true, protocols: {}} + } + "descend-skips-a-segment-refused": { + about: "after use package::billing, api is not in scope (fix: write billing::api::Invoice, or use package::billing::api)" + packages: app: schemas: { + "billing/api": _refBilling + "api": "use package::billing\n\n" + (_refHolder & {_ref: "api::Invoice"}).text + } + build: "app" + expect: {builds: false, errors: ["reference::qualifier-not-in-scope"]} + } + + // A qualified reference is frozen as its resolved path: each spelling + // reaches the `Invoice` in `billing/api`, and not the decoy in `archive`, + // which an unmarked protocol using it can't give up. + "resolved-item": { + about: "use package::billing::api::Invoice, then Invoice, reaches billing::api::Invoice" + packages: app: schemas: { + "archive": _refArchive + "billing/api": _refBilling + "api": "use package::billing::api::Invoice\n\n" + (_refOrders & {_ref: "Invoice"}).text + } + build: "app" + expect: {builds: true, protocols: Orders: given_up: [], warnings: []} + } + "resolved-namespace": { + about: "use package::billing::api, then api::Invoice, reaches billing::api::Invoice" + packages: app: schemas: { + "archive": _refArchive + "billing/api": _refBilling + "api": "use package::billing::api\n\n" + (_refOrders & {_ref: "api::Invoice"}).text + } + build: "app" + expect: {builds: true, protocols: Orders: given_up: [], warnings: []} + } + "resolved-descent": { + about: "use package::billing, then billing::api::Invoice, reaches billing::api::Invoice" + packages: app: schemas: { + "archive": _refArchive + "billing/api": _refBilling + "api": "use package::billing\n\n" + (_refOrders & {_ref: "billing::api::Invoice"}).text + } + build: "app" + expect: {builds: true, protocols: Orders: given_up: [], warnings: []} + } + "resolved-alias": { + about: "use package::billing::api as b, then b::Invoice, reaches billing::api::Invoice" + packages: app: schemas: { + "archive": _refArchive + "billing/api": _refBilling + "api": "use package::billing::api as b\n\n" + (_refOrders & {_ref: "b::Invoice"}).text + } + build: "app" + expect: {builds: true, protocols: Orders: given_up: [], warnings: []} + } + "resolved-full-path": { + about: "package::billing::api::Invoice with no use reaches billing::api::Invoice" + packages: app: schemas: { + "archive": _refArchive + "billing/api": _refBilling + "api": (_refOrders & {_ref: "package::billing::api::Invoice"}).text + } + build: "app" + expect: {builds: true, protocols: Orders: given_up: [], warnings: []} + } + "resolved-decoy": { + about: "use package::archive, then archive::Invoice, reaches the unbounded Invoice, which an unmarked protocol can't use: the other cases reached billing's" + packages: app: schemas: { + "archive": _refArchive + "billing/api": _refBilling + "api": "use package::archive\n\n" + (_refOrders & {_ref: "archive::Invoice"}).text + } + build: "app" + expect: {builds: false, errors: ["bounds::unbounded"]} + } + + // A package written before the rule: a namespace `use` and references + // qualified with the schema's namespace. Its protocols freeze as they did. + "existing-package-unchanged": { + about: "use package::models and models::Blob, as written before the rule, freezes the same protocols as the item use does in bounded/other-schema-marked" + packages: app: { + config: [_allow] + schemas: { + models: """ + struct Blob { + data: string + } + + @unverified = "the uploader streams whatever it's given" + protocol Upload { + function put(b: Blob); + } + """ + api: """ + use package::models + + @unverified = "orders carry the upload" + protocol Orders { + function send(b: models::Blob); + } + """ + } + } + build: "app" + expect: { + builds: true + protocols: { + Upload: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: "the uploader streams whatever it's given"} + } + Orders: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: "orders carry the upload"} + } + } + warnings: ["unverified::bounded-size"] + } + } +} diff --git a/specs/compiler.cue b/specs/compiler.cue index e17be4d..faed554 100644 --- a/specs/compiler.cue +++ b/specs/compiler.cue @@ -106,6 +106,8 @@ import "github.com/comlineproject/specification/catalog" close({code!: "settings::forbidden", severity!: "error"}), close({code!: "import::bare-own-schema-path", severity!: "error"}), close({code!: "import::unresolved", severity!: "error"}), + close({code!: "reference::not-in-scope", severity!: "error"}), + close({code!: "reference::qualifier-not-in-scope", severity!: "error"}), ]) #CompilerWarning: or([ diff --git a/specs/gen/compiler.schema.json b/specs/gen/compiler.schema.json index dae970a..ef8b5ea 100644 --- a/specs/gen/compiler.schema.json +++ b/specs/gen/compiler.schema.json @@ -120,6 +120,14 @@ { "code": "import::unresolved", "severity": "error" + }, + { + "code": "reference::not-in-scope", + "severity": "error" + }, + { + "code": "reference::qualifier-not-in-scope", + "severity": "error" } ] }, From 84ad410c22512d7f0863d87d5fdabb972699eb36 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Mon, 16 Nov 2026 09:17:11 +0800 Subject: [PATCH 2/3] compiler cases: report every error, defined twice, names nothing declares, a dependency's name as a use Every error is reported: imports/bare-own-namespace and the four dependency-named-* cases also expect reference::not-in-scope. New code reference::defined-twice with refused and aliased cases, cases for names and qualifiers nothing declares, and use of a dependency's name alone. --- compiler/cases/imports.json | 34 ++++- compiler/cases/references.json | 236 ++++++++++++++++++++++++++++++++- compiler/readme.md | 9 +- compiler/src/imports.cue | 16 ++- compiler/src/references.cue | 97 +++++++++++++- specs/compiler.cue | 1 + specs/gen/compiler.schema.json | 4 + 7 files changed, 373 insertions(+), 24 deletions(-) diff --git a/compiler/cases/imports.json b/compiler/cases/imports.json index 952f8d7..63364b5 100644 --- a/compiler/cases/imports.json +++ b/compiler/cases/imports.json @@ -35,7 +35,7 @@ }, { "id": "imports/bare-own-namespace", - "description": "a bare path to the package's own schema as a whole is an error", + "description": "a bare path to the package's own schema as a whole is an error, and so is the bare Blob after it, as a whole-namespace use brings in only its name: every error is reported", "packages": [ { "name": "app", @@ -60,6 +60,10 @@ { "code": "import::bare-own-schema-path", "severity": "error" + }, + { + "code": "reference::not-in-scope", + "severity": "error" } ] } @@ -512,7 +516,12 @@ "build": "app", "expect": { "builds": false, - "diagnostics": [], + "diagnostics": [ + { + "code": "reference::not-in-scope", + "severity": "error" + } + ], "error_contains": [ "reserved" ] @@ -552,7 +561,12 @@ "build": "app", "expect": { "builds": false, - "diagnostics": [], + "diagnostics": [ + { + "code": "reference::not-in-scope", + "severity": "error" + } + ], "error_contains": [ "reserved" ] @@ -592,7 +606,12 @@ "build": "app", "expect": { "builds": false, - "diagnostics": [], + "diagnostics": [ + { + "code": "reference::not-in-scope", + "severity": "error" + } + ], "error_contains": [ "reserved" ] @@ -632,7 +651,12 @@ "build": "app", "expect": { "builds": false, - "diagnostics": [], + "diagnostics": [ + { + "code": "reference::not-in-scope", + "severity": "error" + } + ], "error_contains": [ "reserved" ] diff --git a/compiler/cases/references.json b/compiler/cases/references.json index abb5898..8f7675e 100644 --- a/compiler/cases/references.json +++ b/compiler/cases/references.json @@ -31,7 +31,7 @@ }, { "id": "references/namespace-bare-refused", - "description": "after use package::types a bare User is not in scope (fix: add use package::types::User, or write types::User)", + "description": "after use package::types a bare User is not in scope: the use brings in only types (fix, offered because User is declared in types: add use package::types::User, or write types::User)", "packages": [ { "name": "app", @@ -89,7 +89,7 @@ }, { "id": "references/namespace-alias-original-refused", - "description": "after use package::types as t, types is not in scope (fix: write t::User)", + "description": "after use package::types as t only the alias t is in scope, not types, which the alias replaces (fix: write t::User)", "packages": [ { "name": "app", @@ -294,7 +294,7 @@ }, { "id": "references/no-use-bare-refused", - "description": "a bare User with no use is not in scope (fix: add use package::types::User, or write package::types::User)", + "description": "a bare User with no use is not in scope (fix, offered because User is declared in package::types: add use package::types::User, or write package::types::User)", "packages": [ { "name": "app", @@ -325,7 +325,7 @@ }, { "id": "references/no-use-qualified-refused", - "description": "types::User with no use is not rooted in a name in scope (fix: add use package::types, or write package::types::User)", + "description": "types::User with no use is not rooted in a name in scope (fix, offered because the package declares types::User: add use package::types, or write package::types::User)", "packages": [ { "name": "app", @@ -354,6 +354,192 @@ ] } }, + { + "id": "references/nowhere-bare-refused", + "description": "a bare Nowhere that no schema of the package or its dependencies declares is not in scope (no fix that adds a use is offered: nothing declares it)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::types\n\nstruct Account {\n owner: Nowhere\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::not-in-scope", + "severity": "error" + } + ] + } + }, + { + "id": "references/nowhere-qualified-refused", + "description": "nope::types::User, whose first segment matches no name in scope, root or schema, is not in scope (no fix that adds a use is offered: nothing is named nope)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/types.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "struct Account {\n owner: nope::types::User\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::qualifier-not-in-scope", + "severity": "error" + } + ] + } + }, + { + "id": "references/defined-twice-local-and-use", + "description": "use package::billing::Invoice and struct Invoice in the same schema define Invoice twice (fix: rename one, or import with an alias: use package::billing::Invoice as BillingInvoice)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/billing/api.ids", + "text": "struct Invoice {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::billing::api::Invoice\n\nstruct Invoice {\n data: char[max 64]\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::defined-twice", + "severity": "error" + } + ] + } + }, + { + "id": "references/defined-twice-two-uses", + "description": "use package::a::User and use package::b::User bring in User twice (fix: rename one, or import with an alias: use package::b::User as BUser)", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/a.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/b.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::a::User\nuse package::b::User\n\nstruct Account {\n id: u32\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "reference::defined-twice", + "severity": "error" + } + ] + } + }, + { + "id": "references/alias-resolves-local-clash", + "description": "use package::billing::api::Invoice as BillingInvoice beside a local Invoice defines each name once", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/billing/api.ids", + "text": "struct Invoice {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::billing::api::Invoice as BillingInvoice\n\nstruct Invoice {\n data: char[max 64]\n}\n\nstruct Account {\n billed: BillingInvoice\n own: Invoice\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "references/alias-resolves-two-uses", + "description": "use package::a::User beside use package::b::User as BUser defines each name once", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/a.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/b.ids", + "text": "struct User {\n id: u32\n}\n\nstruct Order {\n id: u32\n}\n" + }, + { + "path": "src/api.ids", + "text": "use package::a::User\nuse package::b::User as BUser\n\nstruct Account {\n first: User\n second: BUser\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, { "id": "references/full-package", "description": "package::types::User in a field needs no use", @@ -525,7 +711,7 @@ }, { "id": "references/full-own-schema-unrooted-refused", - "description": "a full path to the package's own schema that doesn't start at package, parent or self is not rooted (fix: write package::shapes::types::User)", + "description": "a full path to the package's own schema that doesn't start at package, parent or self is not rooted (fix, offered because the schema exists: write package::shapes::types::User)", "packages": [ { "name": "app", @@ -646,9 +832,47 @@ "diagnostics": [] } }, + { + "id": "references/descend-dependency-name", + "description": "after use greeting, a dependency's name on its own, greeting::hello::Greeting reaches the dependency's item", + "packages": [ + { + "name": "greeting", + "config": "congregation greeting\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/hello.ids", + "text": "struct Greeting {\n text: char[max 64]\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n greeting = {\n path = \"../greeting\"\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use greeting\n\nstruct Account {\n owner: greeting::hello::Greeting\n}\n" + } + ], + "dependencies": [ + { + "name": "greeting" + } + ] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, { "id": "references/descend-skips-a-segment-refused", - "description": "after use package::billing, api is not in scope (fix: write billing::api::Invoice, or use package::billing::api)", + "description": "after use package::billing, api is not in scope (fix, offered because billing::api exists: write billing::api::Invoice, or add use package::billing::api)", "packages": [ { "name": "app", diff --git a/compiler/readme.md b/compiler/readme.md index 059618d..76a4a8c 100644 --- a/compiler/readme.md +++ b/compiler/readme.md @@ -136,7 +136,7 @@ cases with `dependencies`, which are in `acceptance` and `chain`. | `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 | | `imports` | where a `use` path starts: a package's own schemas only through `package::`, `parent::` or `self::` (a bare path to one is `import::bare-own-schema-path`, in each form of a `use`), a dependency's and `std`'s paths as they were, a path matching nothing (`import::unresolved`), a schema named like a dependency, and the names a dependency can't have | -| `references` | how a type is named once imported, the Rust model: a whole-namespace `use` brings in only its name (`types::User`, and a bare `User` is `reference::not-in-scope`); a `use` of an item, `{...}` or `*` brings in the names it lists (and `types::User` after it is `reference::qualifier-not-in-scope`); a full path (`package::`, `parent::`, `self::`, `std::`, a dependency's) in a type position with no `use`; a path going down from a name in scope; each spelling reaching the same type, and a package written before the rule unchanged | +| `references` | how a type is named once imported, the Rust model: a whole-namespace `use` brings in only its name (`types::User`, and a bare `User` is `reference::not-in-scope`); a `use` of an item, `{...}` or `*` brings in the names it lists (and `types::User` after it is `reference::qualifier-not-in-scope`); a full path (`package::`, `parent::`, `self::`, `std::`, a dependency's) in a type position with no `use`; a path going down from a name in scope, a dependency's name included; a name defined twice (`reference::defined-twice`) and an alias resolving it; each spelling reaching the same type, and a package written before the rule unchanged | | `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, and for a refused reference the @@ -148,6 +148,13 @@ not to the fix). The `reference` codes, in | --- | --- | --- | | `reference::not-in-scope` | a bare name no `use` or declaration of the file brought in: `User` after only `use package::types` | add `use package::types::User`, or write `types::User` | | `reference::qualifier-not-in-scope` | a qualified reference whose first segment is not a name in scope or a root: `types::User` after `use package::types::User` | write `User` (or add the `use` that brings the qualifier in) | +| `reference::defined-twice` | a name defined twice in a file: a `use`d item and a local declaration of the same name, or two `use`s bringing in the same name | rename one, or import with an alias (`use package::b::User as BUser`) | + +Both `not-in-scope` codes also cover a name or a qualifier nothing declares +(`Nowhere`, `nope::types::User`); a fix that adds a `use` is offered only +where something declares it. Every error is reported, not only the first, so +a case that has two causes lists both codes. In a type position `parent::` +and `self::` mean what they mean in a `use`. Each rule has a passing and a failing variant. diff --git a/compiler/src/imports.cue b/compiler/src/imports.cue index aaa62cb..9eadf75 100644 --- a/compiler/src/imports.cue +++ b/compiler/src/imports.cue @@ -13,6 +13,10 @@ package cases // (the shadowing guard), and `std`, `package`, `parent` and `self` can't be a // dependency's name. Neither error has a code: the cases say what the message // contains, as the acceptance cases do. +// +// Every error is reported, not only the first: where a case's schema holds a +// bare name that nothing brought into scope, `reference::not-in-scope` is +// among its errors (see the `references` group). _impModels: """ struct Blob { @@ -40,10 +44,10 @@ groups: imports: { expect: {builds: false, errors: ["import::bare-own-schema-path"]} } "bare-own-namespace": { - about: "a bare path to the package's own schema as a whole is an error" + about: "a bare path to the package's own schema as a whole is an error, and so is the bare Blob after it, as a whole-namespace use brings in only its name: every error is reported" packages: app: schemas: {models: _impModels, api: "use models\n\n" + _impUsesBlob} build: "app" - expect: {builds: false, errors: ["import::bare-own-schema-path"]} + expect: {builds: false, errors: ["import::bare-own-schema-path", "reference::not-in-scope"]} } "bare-own-multi": { about: "a bare path with {...} to the package's own schema is an error" @@ -169,7 +173,7 @@ groups: imports: { } } build: "app" - expect: {builds: false, error_contains: ["reserved"]} + expect: {builds: false, errors: ["reference::not-in-scope"], error_contains: ["reserved"]} } "dependency-named-package": { about: "package can't be a dependency's name" @@ -181,7 +185,7 @@ groups: imports: { } } build: "app" - expect: {builds: false, error_contains: ["reserved"]} + expect: {builds: false, errors: ["reference::not-in-scope"], error_contains: ["reserved"]} } "dependency-named-parent": { about: "parent can't be a dependency's name" @@ -193,7 +197,7 @@ groups: imports: { } } build: "app" - expect: {builds: false, error_contains: ["reserved"]} + expect: {builds: false, errors: ["reference::not-in-scope"], error_contains: ["reserved"]} } "dependency-named-self": { about: "self can't be a dependency's name" @@ -205,6 +209,6 @@ groups: imports: { } } build: "app" - expect: {builds: false, error_contains: ["reserved"]} + expect: {builds: false, errors: ["reference::not-in-scope"], error_contains: ["reserved"]} } } diff --git a/compiler/src/references.cue b/compiler/src/references.cue index 5d92e63..4bd80c6 100644 --- a/compiler/src/references.cue +++ b/compiler/src/references.cue @@ -22,6 +22,16 @@ package cases // another schema holds an unbounded string, and the one reached holds a // bounded one, which the protocol using it gives up nothing for. // +// - A name defined twice, by a `use` and a declaration of the file or by two +// `use`s, is `reference::defined-twice`, as in Rust. Fix: rename one, or +// import with an alias. +// - `parent::` and `self::` mean in a type position what they mean in a `use`. +// +// Every error is reported, not only the first. A name or a qualifier that +// nothing declares is `reference::not-in-scope` or +// `reference::qualifier-not-in-scope` as well; only the fix differs, as a fix +// that adds a `use` is offered only where a declaration exists somewhere. +// // A refused reference is an error at once, with the likely rewrite as its // fix. The fix isn't part of what a case holds a compiler to (a diagnostic is // matched on its code and severity); it is in each case's description. @@ -80,7 +90,7 @@ groups: references: { expect: {builds: true, protocols: {}} } "namespace-bare-refused": { - about: "after use package::types a bare User is not in scope (fix: add use package::types::User, or write types::User)" + about: "after use package::types a bare User is not in scope: the use brings in only types (fix, offered because User is declared in types: add use package::types::User, or write types::User)" packages: app: schemas: { types: _refTypes api: "use package::types\n\n" + (_refHolder & {_ref: "User"}).text @@ -98,7 +108,7 @@ groups: references: { expect: {builds: true, protocols: {}} } "namespace-alias-original-refused": { - about: "after use package::types as t, types is not in scope (fix: write t::User)" + about: "after use package::types as t only the alias t is in scope, not types, which the alias replaces (fix: write t::User)" packages: app: schemas: { types: _refTypes api: "use package::types as t\n\n" + (_refHolder & {_ref: "types::User"}).text @@ -163,7 +173,7 @@ groups: references: { expect: {builds: false, errors: ["reference::qualifier-not-in-scope"]} } "no-use-bare-refused": { - about: "a bare User with no use is not in scope (fix: add use package::types::User, or write package::types::User)" + about: "a bare User with no use is not in scope (fix, offered because User is declared in package::types: add use package::types::User, or write package::types::User)" packages: app: schemas: { types: _refTypes api: (_refHolder & {_ref: "User"}).text @@ -172,7 +182,7 @@ groups: references: { expect: {builds: false, errors: ["reference::not-in-scope"]} } "no-use-qualified-refused": { - about: "types::User with no use is not rooted in a name in scope (fix: add use package::types, or write package::types::User)" + about: "types::User with no use is not rooted in a name in scope (fix, offered because the package declares types::User: add use package::types, or write package::types::User)" packages: app: schemas: { types: _refTypes api: (_refHolder & {_ref: "types::User"}).text @@ -181,6 +191,69 @@ groups: references: { expect: {builds: false, errors: ["reference::qualifier-not-in-scope"]} } + // A name or a qualifier that nothing declares has the same two codes, and + // no fix that adds a `use`, as there is nothing to import. + "nowhere-bare-refused": { + about: "a bare Nowhere that no schema of the package or its dependencies declares is not in scope (no fix that adds a use is offered: nothing declares it)" + packages: app: schemas: { + types: _refTypes + api: "use package::types\n\n" + (_refHolder & {_ref: "Nowhere"}).text + } + build: "app" + expect: {builds: false, errors: ["reference::not-in-scope"]} + } + "nowhere-qualified-refused": { + about: "nope::types::User, whose first segment matches no name in scope, root or schema, is not in scope (no fix that adds a use is offered: nothing is named nope)" + packages: app: schemas: { + types: _refTypes + api: (_refHolder & {_ref: "nope::types::User"}).text + } + build: "app" + expect: {builds: false, errors: ["reference::qualifier-not-in-scope"]} + } + + // A name defined twice is an error, as in Rust: a local declaration with + // the name of a `use`d item, or two `use`s bringing in the same name. An + // alias resolves the clash. + "defined-twice-local-and-use": { + about: "use package::billing::Invoice and struct Invoice in the same schema define Invoice twice (fix: rename one, or import with an alias: use package::billing::Invoice as BillingInvoice)" + packages: app: schemas: { + "billing/api": _refBilling + "api": "use package::billing::api::Invoice\n\n" + _refBilling + } + build: "app" + expect: {builds: false, errors: ["reference::defined-twice"]} + } + "defined-twice-two-uses": { + about: "use package::a::User and use package::b::User bring in User twice (fix: rename one, or import with an alias: use package::b::User as BUser)" + packages: app: schemas: { + a: _refTypes + b: _refTypes + api: "use package::a::User\nuse package::b::User\n\nstruct Account {\n id: u32\n}" + } + build: "app" + expect: {builds: false, errors: ["reference::defined-twice"]} + } + "alias-resolves-local-clash": { + about: "use package::billing::api::Invoice as BillingInvoice beside a local Invoice defines each name once" + packages: app: schemas: { + "billing/api": _refBilling + "api": "use package::billing::api::Invoice as BillingInvoice\n\n" + _refBilling + "\n\nstruct Account {\n billed: BillingInvoice\n own: Invoice\n}" + } + build: "app" + expect: {builds: true, protocols: {}} + } + "alias-resolves-two-uses": { + about: "use package::a::User beside use package::b::User as BUser defines each name once" + packages: app: schemas: { + a: _refTypes + b: _refTypes + api: "use package::a::User\nuse package::b::User as BUser\n\nstruct Account {\n first: User\n second: BUser\n}" + } + build: "app" + expect: {builds: true, protocols: {}} + } + // A full path works in a type position without a `use`. "full-package": { about: "package::types::User in a field needs no use" @@ -237,7 +310,7 @@ groups: references: { expect: {builds: true, protocols: {}} } "full-own-schema-unrooted-refused": { - about: "a full path to the package's own schema that doesn't start at package, parent or self is not rooted (fix: write package::shapes::types::User)" + about: "a full path to the package's own schema that doesn't start at package, parent or self is not rooted (fix, offered because the schema exists: write package::shapes::types::User)" packages: app: schemas: { "shapes/types": _refTypes "api": (_refHolder & {_ref: "shapes::types::User"}).text @@ -277,8 +350,20 @@ groups: references: { build: "app" expect: {builds: true, protocols: {}} } + "descend-dependency-name": { + about: "after use greeting, a dependency's name on its own, greeting::hello::Greeting reaches the dependency's item" + packages: { + greeting: schemas: hello: _refGreeting + app: { + schemas: api: "use greeting\n\n" + (_refHolder & {_ref: "greeting::hello::Greeting"}).text + dependencies: greeting: {} + } + } + build: "app" + expect: {builds: true, protocols: {}} + } "descend-skips-a-segment-refused": { - about: "after use package::billing, api is not in scope (fix: write billing::api::Invoice, or use package::billing::api)" + about: "after use package::billing, api is not in scope (fix, offered because billing::api exists: write billing::api::Invoice, or add use package::billing::api)" packages: app: schemas: { "billing/api": _refBilling "api": "use package::billing\n\n" + (_refHolder & {_ref: "api::Invoice"}).text diff --git a/specs/compiler.cue b/specs/compiler.cue index faed554..07cab4d 100644 --- a/specs/compiler.cue +++ b/specs/compiler.cue @@ -108,6 +108,7 @@ import "github.com/comlineproject/specification/catalog" close({code!: "import::unresolved", severity!: "error"}), close({code!: "reference::not-in-scope", severity!: "error"}), close({code!: "reference::qualifier-not-in-scope", severity!: "error"}), + close({code!: "reference::defined-twice", severity!: "error"}), ]) #CompilerWarning: or([ diff --git a/specs/gen/compiler.schema.json b/specs/gen/compiler.schema.json index ef8b5ea..0dc6fe0 100644 --- a/specs/gen/compiler.schema.json +++ b/specs/gen/compiler.schema.json @@ -128,6 +128,10 @@ { "code": "reference::qualifier-not-in-scope", "severity": "error" + }, + { + "code": "reference::defined-twice", + "severity": "error" } ] }, From 90a4fc520ac8b1bf6b2c028b02cabe2c4aa52be5 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Mon, 16 Nov 2026 09:25:11 +0800 Subject: [PATCH 3/3] imports cases: config errors stop before the schemas, an unresolved use still binds its name --- compiler/cases/imports.json | 38 +++++++++---------------------------- compiler/readme.md | 6 +++++- compiler/src/imports.cue | 34 +++++++++++++++++++++------------ 3 files changed, 36 insertions(+), 42 deletions(-) diff --git a/compiler/cases/imports.json b/compiler/cases/imports.json index 63364b5..11e918f 100644 --- a/compiler/cases/imports.json +++ b/compiler/cases/imports.json @@ -413,7 +413,7 @@ }, { "id": "imports/unknown-first-segment", - "description": "a bare path that is neither a dependency, std nor one of the package's schemas is unresolved, not this error", + "description": "a bare path that is neither a dependency, std nor one of the package's schemas is unresolved, not this error; the use still brings Blob into scope, so the bare Blob after it is no second error, as in Rust", "packages": [ { "name": "app", @@ -503,7 +503,7 @@ "schemas": [ { "path": "src/api.ids", - "text": "struct Upload {\n blob: Blob\n}\n" + "text": "struct Upload {\n size: u32\n}\n" } ], "dependencies": [ @@ -516,12 +516,7 @@ "build": "app", "expect": { "builds": false, - "diagnostics": [ - { - "code": "reference::not-in-scope", - "severity": "error" - } - ], + "diagnostics": [], "error_contains": [ "reserved" ] @@ -548,7 +543,7 @@ "schemas": [ { "path": "src/api.ids", - "text": "struct Upload {\n blob: Blob\n}\n" + "text": "struct Upload {\n size: u32\n}\n" } ], "dependencies": [ @@ -561,12 +556,7 @@ "build": "app", "expect": { "builds": false, - "diagnostics": [ - { - "code": "reference::not-in-scope", - "severity": "error" - } - ], + "diagnostics": [], "error_contains": [ "reserved" ] @@ -593,7 +583,7 @@ "schemas": [ { "path": "src/api.ids", - "text": "struct Upload {\n blob: Blob\n}\n" + "text": "struct Upload {\n size: u32\n}\n" } ], "dependencies": [ @@ -606,12 +596,7 @@ "build": "app", "expect": { "builds": false, - "diagnostics": [ - { - "code": "reference::not-in-scope", - "severity": "error" - } - ], + "diagnostics": [], "error_contains": [ "reserved" ] @@ -638,7 +623,7 @@ "schemas": [ { "path": "src/api.ids", - "text": "struct Upload {\n blob: Blob\n}\n" + "text": "struct Upload {\n size: u32\n}\n" } ], "dependencies": [ @@ -651,12 +636,7 @@ "build": "app", "expect": { "builds": false, - "diagnostics": [ - { - "code": "reference::not-in-scope", - "severity": "error" - } - ], + "diagnostics": [], "error_contains": [ "reserved" ] diff --git a/compiler/readme.md b/compiler/readme.md index 76a4a8c..6dd0155 100644 --- a/compiler/readme.md +++ b/compiler/readme.md @@ -153,7 +153,11 @@ not to the fix). The `reference` codes, in Both `not-in-scope` codes also cover a name or a qualifier nothing declares (`Nowhere`, `nope::types::User`); a fix that adds a `use` is offered only where something declares it. Every error is reported, not only the first, so -a case that has two causes lists both codes. In a type position `parent::` +a case that has two causes lists both codes. A config error (the +reserved dependency names) stops the build before the schemas are checked, as +in Rust, so no schema error is reported with it. A `use` that fails to resolve +(`import::unresolved`) still brings its name into scope, so it never cascades +into a `reference::not-in-scope` for the name. In a type position `parent::` and `self::` mean what they mean in a `use`. Each rule has a passing and a failing variant. diff --git a/compiler/src/imports.cue b/compiler/src/imports.cue index 9eadf75..d59e60e 100644 --- a/compiler/src/imports.cue +++ b/compiler/src/imports.cue @@ -14,9 +14,12 @@ package cases // dependency's name. Neither error has a code: the cases say what the message // contains, as the acceptance cases do. // -// Every error is reported, not only the first: where a case's schema holds a -// bare name that nothing brought into scope, `reference::not-in-scope` is -// among its errors (see the `references` group). +// Every error is reported, not only the first, among those of the schemas: a +// schema's bare name that nothing brought into scope is +// `reference::not-in-scope` besides any other error of the schema (see the +// `references` group). A config error, as the reserved dependency names, +// stops the build before the schemas are checked, as in Rust, so those cases +// hold no reference of their own. _impModels: """ struct Blob { @@ -28,6 +31,13 @@ _impModels: """ } """ +// A schema that holds no reference, for the cases a config error stops. +_impPlain: """ + struct Upload { + size: u32 + } + """ + // A schema using `Blob`, whichever way `use` brought it in. _impUsesBlob: """ struct Upload { @@ -144,7 +154,7 @@ groups: imports: { expect: {builds: true, protocols: {}} } "unknown-first-segment": { - about: "a bare path that is neither a dependency, std nor one of the package's schemas is unresolved, not this error" + about: "a bare path that is neither a dependency, std nor one of the package's schemas is unresolved, not this error; the use still brings Blob into scope, so the bare Blob after it is no second error, as in Rust" packages: app: schemas: {models: _impModels, api: "use modles::Blob\n\n" + _impUsesBlob} build: "app" expect: {builds: false, errors: ["import::unresolved"]} @@ -168,47 +178,47 @@ groups: imports: { packages: { std: schemas: api: _impModels app: { - schemas: api: _impUsesBlob + schemas: api: _impPlain dependencies: std: {} } } build: "app" - expect: {builds: false, errors: ["reference::not-in-scope"], error_contains: ["reserved"]} + expect: {builds: false, error_contains: ["reserved"]} } "dependency-named-package": { about: "package can't be a dependency's name" packages: { package: schemas: api: _impModels app: { - schemas: api: _impUsesBlob + schemas: api: _impPlain dependencies: package: {} } } build: "app" - expect: {builds: false, errors: ["reference::not-in-scope"], error_contains: ["reserved"]} + expect: {builds: false, error_contains: ["reserved"]} } "dependency-named-parent": { about: "parent can't be a dependency's name" packages: { parent: schemas: api: _impModels app: { - schemas: api: _impUsesBlob + schemas: api: _impPlain dependencies: parent: {} } } build: "app" - expect: {builds: false, errors: ["reference::not-in-scope"], error_contains: ["reserved"]} + expect: {builds: false, error_contains: ["reserved"]} } "dependency-named-self": { about: "self can't be a dependency's name" packages: { self: schemas: api: _impModels app: { - schemas: api: _impUsesBlob + schemas: api: _impPlain dependencies: self: {} } } build: "app" - expect: {builds: false, errors: ["reference::not-in-scope"], error_contains: ["reserved"]} + expect: {builds: false, error_contains: ["reserved"]} } }