From 610198777e167c353642e51513add06c1fdc878c Mon Sep 17 00:00:00 2001 From: Kinflou Date: Mon, 16 Nov 2026 11:47:49 +0800 Subject: [PATCH] imports: qualified references follow the Rust model, built in core#297 Rewrites the Imports guide for the rule (core#290): what each use brings in, full paths without a use, walking down from a name in scope, aliases replacing the name, defined twice, and the three errors. Marks the proposal section built and notes the superseded 2026-10-04 design decision. --- .../docs/design/editor-dependency-packages.md | 6 +- docs/docs/guides/idl/index.md | 4 +- docs/docs/guides/idl/use.md | 187 +++++++++++++++--- docs/docs/proposals/index.md | 3 +- .../use-paths-and-groups/relative-use.md | 32 ++- 5 files changed, 192 insertions(+), 40 deletions(-) diff --git a/docs/docs/design/editor-dependency-packages.md b/docs/docs/design/editor-dependency-packages.md index ce85568..eaab3f0 100644 --- a/docs/docs/design/editor-dependency-packages.md +++ b/docs/docs/design/editor-dependency-packages.md @@ -185,7 +185,11 @@ waits for a registry. 2. **Whole-namespace imports bring names in bare.** After `use pkg::types`, both `User` and `pkg::types::User` work, as core and the editor already behave. Qualified-only was never the goal: the [`use` guide](../guides/idl/use.md) is - corrected. + corrected. *Superseded 2026-11-16 by + [qualified references](../proposals/use-paths-and-groups/relative-use.md#qualified-references) + ([core#297](https://github.com/ComlineProject/core/pull/297)): a whole-namespace + `use` brings in only its name, so after `use package::types` the type is + `types::User`, and a bare `User` needs `use package::types::User`.* 3. **Direct dependencies only, for now.** A dependency's own dependencies stay invisible to the consumer. 4. **The packages guide documents what shipped in core#50**, updated alongside diff --git a/docs/docs/guides/idl/index.md b/docs/docs/guides/idl/index.md index e11de0e..2e33b9c 100755 --- a/docs/docs/guides/idl/index.md +++ b/docs/docs/guides/idl/index.md @@ -65,4 +65,6 @@ use parent::common::* A package's own schemas are reached only through `package::`, `parent::` and `self::`, which resolve relative to the current schema; any other path means -`std` or a dependency. See [Imports](use.md). +`std` or a dependency. A type is then written with a name a `use` brought into +scope, as in Rust, or with a full path from `package`, `parent`, `self`, `std` +or a dependency's name. See [Imports](use.md). diff --git a/docs/docs/guides/idl/use.md b/docs/docs/guides/idl/use.md index 6240869..d066158 100644 --- a/docs/docs/guides/idl/use.md +++ b/docs/docs/guides/idl/use.md @@ -36,15 +36,16 @@ to another directory doesn't change what its imports say. | Form | Example | Brings in | |---|---|---| -| single item | `use package::module::Type` | one item by its full path | -| whole namespace | `use package::module` | everything in that module, bare or qualified (`Type` or `module::Type`) | -| multi | `use package::module::{A, B, C}` | several items from one module (plain names, no nesting or `as` inside the braces) | -| glob | `use package::module::*` | everything in that module | +| single item | `use package::module::Type` | the item, as `Type` | +| whole namespace | `use package::module` | only the name `module`, to qualify with: `module::Type`, and no bare `Type` | +| multi | `use package::module::{A, B, C}` | several items from one module, each by its name (plain names, no nesting or `as` inside the braces) | +| glob | `use package::module::*` | every item in that module by its name, and not `module` itself | | relative | `use parent::common::Error`, `use self::nested::Type`, `use package::types::User` | resolved against the current schema: `parent::` is one level up, `self::` the schema itself (`self::nested` is a schema under it), `package::` the package root | The first four rows show `package::`; a dependency's or `std`'s schema takes the same forms with its own name first (`use greeting::hello::{A, B}`, -`use std::http::*`). +`use std::http::*`). What each form brings in decides how a type is written +afterwards: see [Referring to what you imported](#referring-to-what-you-imported). A relative prefix works in every form, including a glob or `{ ... }` straight after it: `use parent::*` and `use parent::{Error, Page}` import from the schema @@ -74,35 +75,163 @@ fix, titled ``Write `package::types::{User, Post}` ``, that inserts `package::` the start of the path. The language server doesn't offer it yet ([language-server#122](https://github.com/ComlineProject/language-server/issues/122)), and `comline fix` doesn't apply it across a package yet -([cli#162](https://github.com/ComlineProject/cli/issues/162)). Qualified -references the import brought in don't change: they're written with the -schema's namespace (`types::User`) whichever path reached it. A path whose first segment is neither `std`, a +([cli#162](https://github.com/ComlineProject/cli/issues/162)). The fix changes +only the `use`. A path whose first segment is neither `std`, a dependency nor one of the package's own schemas is not this error but a [path that matches nothing](#when-nothing-matches). ## Referring to what you imported -After a `use`, a type can be written **bare** or **qualified**, Rust-style. The -qualified path is the schema's own namespace (`types::User`), not the path the -`use` was written with: +A type is written with a name that is **in scope**, as in Rust. A schema has in +scope: -| statement | write the type as | -|---|---| -| `use package::types::User` | `User` **or** `types::User` | -| `use package::types::{User, Post}` | `User` / `Post`, or the qualified path | -| `use package::types::*` | any name from `types`, bare or qualified | -| `use package::types` | `User` **or** `types::User` | -| `use package::types::User as Account` | `Account` **or** `types::User` — **not** bare `User` | +- what it declares itself; +- what its `use` lines bring in (the table below); +- the roots `package`, `parent`, `self` and `std`, and each dependency's name. + +| statement | brings in | write the type as | +|---|---|---| +| `use package::types::User` | `User` | `User` | +| `use package::types::{User, Post}` | `User` and `Post` | `User` / `Post` | +| `use package::types::*` | every name in `types`, not `types` | `User` | +| `use package::types` | `types`, and nothing in it | `types::User` | +| `use package::types as t` | `t`, and nothing else | `t::User` | +| `use package::types::User as Account` | `Account`, and nothing else | `Account` | + +A whole-namespace `use` brings in only its name, so the names in the namespace +are qualified with it, and a bare name needs a `use` that names it or ends in +`*`. The other way round, an item `use` brings in the item and not the +namespace it came from: after `use package::types::User`, `types` is not in +scope. + +```ids +use package::types +use package::types::Order + +struct Account { + owner: types::User // `types` is in scope + last: Order // `Order` is in scope +} +``` + +A dependency's schemas follow the same rule. `use greeting::hello::Greeting` +brings in `Greeting`, `use greeting::hello` brings in `hello` +(`hello::Greeting`), and `use greeting` brings in the dependency's own name +(`greeting::hello::Greeting`). + +### Full paths without a `use` + +A path that starts at a root works in a type position with no `use` at all: + +```ids +struct Account { + owner: package::types::User + failure: parent::common::Error + detail: self::nested::Type + request: std::http::Request + greeting: greeting::hello::Greeting // a dependency's path +} +``` + +`parent::` and `self::` mean what they mean in a `use`. The first segment says +where the type comes from: `package`, `parent` and `self` are the package's +own, `std` is the standard library, and any other name is a dependency. A path +to the package's own schema has to start at one of the three: +`shapes::types::User` is refused +([`reference::qualifier-not-in-scope`](#the-errors)), and the fix is +`package::shapes::types::User`. + +### Walking down from a name in scope + +A path can go down from a name in scope. After `use package::billing`, the +schema `billing/api` is reached as `billing::api::Invoice`; after +`use package::billing as b`, as `b::api::Invoice`. The walk starts at a name a +`use` brought in, so after `use package::billing`, `api::Invoice` is refused: +`api` is not in scope. Write `billing::api::Invoice`, or add +`use package::billing::api`. + +### One type, however it's written + +A qualified reference is compiled as its path from the package's root: +`api::Invoice` after `use package::billing::api`, `billing::api::Invoice` after +`use package::billing`, `b::Invoice` after `use package::billing::api as b` +and `package::billing::api::Invoice` with no `use` are all +`billing::api::Invoice`. Which way you write a reference doesn't change the +compiled schema, its hashes or the generated code, and tidying a file's `use` +lines doesn't either. + +### Defined twice + +A name means one thing in a file. A `use` that brings in a name the file also +declares, or two `use` lines that bring in the same name, is an error +([`reference::defined-twice`](#the-errors)); a local declaration no longer wins +quietly over an imported name. Rename one, or import with an +[alias](#alias): + +```ids +use package::billing::api::Invoice as BillingInvoice + +struct Invoice { + total: u64 +} -A dependency's schema is qualified by its own path the same way -(`use greeting::hello::Greeting` brings `greeting::hello::Greeting`). +struct Account { + billed: BillingInvoice + own: Invoice +} +``` + +A name that comes from a `*` gives way to a declaration or another `use` of +it, as in Rust, and two `use` lines of the same item aren't an error. + +### The errors + +A reference the rule refuses is an error at once, and the diagnostic gives the +likely rewrite as its fix. Every one is reported, not only the first (and a +file's bad `use` and its bad references together), and the schema then stops +there, so `validate::unknown-type` is never added on top of what they said. + +| Code | When | Fix | +|---|---|---| +| `reference::not-in-scope` | a bare name nothing in the file brought in: `User` after only `use package::types`. A namespace written as a type (`types`) is this error too | add `use package::types::User`, or write `types::User`. The help says which schema declares the name; the quick fix is offered when exactly one does, and when none does the help says nothing declares it | +| `reference::qualifier-not-in-scope` | the first segment of a qualified name isn't in scope: `types::User` after `use package::types::User`, or after `use package::types as t` (the alias replaces the name) | write `User`, or `t::User`, or add `use package::types` to keep `types::User`, or write the path from `package` | +| `reference::defined-twice` | a name a `use` brings in and the file declares, or two `use` lines bringing in the same name | rename one, or import with an alias: ``use package::billing::api::Invoice as BillingInvoice`` | + +```ids +use package::types::User + +struct Account { + // reference::qualifier-not-in-scope: `types` isn't in scope, write `User` + owner: types::User +} +``` + +```ids +use package::types + +struct Account { + // reference::not-in-scope: add `use package::types::User`, or write `types::User` + owner: User +} +``` + +A name nothing declares, and a qualifier that matches nothing, are the same two +errors; only the fix differs, as there is no `use` to add. The diagnostics +carry the rewrite as a quick fix. The language server doesn't offer these yet +([language-server#122](https://github.com/ComlineProject/language-server/issues/122)), +and `comline fix` doesn't apply them across a package yet +([cli#162](https://github.com/ComlineProject/cli/issues/162)). -A `use` never shadows a declaration in the current file: a local `struct User` -always wins over `use package::other::User`. +The rule is for the names of types. The validators a field names in +`@validators`, constants in values and sizes, and the errors a function throws +are still looked up the old way, where a whole-namespace `use` brings in every +name +([core#298](https://github.com/ComlineProject/core/issues/298)). ## Alias -`as NewName` binds the import under a new name for this file: +`as NewName` binds the import under a new name for this file, **in place of** +the original: ```ids use external::uuid::Uuid as UUID @@ -112,9 +241,13 @@ struct Session { } ``` -The alias (`UUID`) and the full path (`external::uuid::Uuid`) both work; the -original bare name (`Uuid`) does not. Aliases apply to single-item and -whole-namespace imports, not to `{ ... }` or `*`. +The alias (`UUID`) and the full path (`external::uuid::Uuid`, a dependency +being a root) both work; the original bare name (`Uuid`) does not. The same goes +for the package's own schemas: after `use package::types as t`, `t::User` and +`package::types::User` reach the item, and `types::User` is +`reference::qualifier-not-in-scope`, because the alias is what came into scope. +Aliases apply to single-item and whole-namespace imports, not to `{ ... }` or +`*`. ## When nothing matches @@ -124,7 +257,7 @@ closest match when there is one: | `use` | Error | |---|---| -| `use typse::User` (no schema `typse`, in the package or its dependencies) | `no schema in this package or its dependencies matches 'typse::User' - did you mean 'types'?` | +| `use typse::User` (no schema `typse`, in the package or its dependencies) | `no schema in this package or its dependencies matches 'typse::User' - did you mean 'package::types::User'?` | | `use package::types::Usr` (`types` has no `Usr`) | `schema 'types' doesn't declare 'Usr' - did you mean 'User'?` | Both are `import::unresolved`. `use types::User`, with `types` one of the diff --git a/docs/docs/proposals/index.md b/docs/docs/proposals/index.md index 24a8f5f..1feccae 100755 --- a/docs/docs/proposals/index.md +++ b/docs/docs/proposals/index.md @@ -170,7 +170,8 @@ parts: [relative paths](use-paths-and-groups/relative-use.md), [dependency groups](use-paths-and-groups/dependency-groups.md) and [import formatting](use-paths-and-groups/import-formatting.md). *accepted 2026-11-15; related to [core#277](https://github.com/ComlineProject/core/issues/277) and -[core#268](https://github.com/ComlineProject/core/issues/268).* +[core#268](https://github.com/ComlineProject/core/issues/268). Built: a bare own-schema path as an error +(core#285) and [qualified references](use-paths-and-groups/relative-use.md#qualified-references) (core#297).* ### Connections diff --git a/docs/docs/proposals/use-paths-and-groups/relative-use.md b/docs/docs/proposals/use-paths-and-groups/relative-use.md index be1caa6..1670903 100644 --- a/docs/docs/proposals/use-paths-and-groups/relative-use.md +++ b/docs/docs/proposals/use-paths-and-groups/relative-use.md @@ -84,13 +84,25 @@ dependency nor `std`, but the name of one of the package's own schemas, is this ## Qualified references -**Decided with the user 2026-11-15: the Rust model,** with the [answers](#qualified-references) below. Not built yet. - -**As built (core#285).** A `use` is frozen with its resolved path: `use package::types::User` is `Import("types::User")`. -After it, a field can be written `User` or `types::User`, and a qualified reference has to match a `use` of the file -exactly; `package::types::User` in a type position is not accepted. A type reference is frozen as written. So the rule -above holds in `use` lines only: `types::User` in a field looks exactly like a path into a dependency named `types`. It -is always traceable to a `use` in the same file, but a reader can't tell from the reference itself. +**Decided with the user 2026-11-15: the Rust model,** with the [answers](#qualified-references) below. + +> **Built** ([core#290](https://github.com/ComlineProject/core/issues/290), +> [core#297](https://github.com/ComlineProject/core/pull/297), 2026-11-16): `comline check` and `comline build` +> enforce the rule, with the conformance cases in the specification +> ([specification#17](https://github.com/ComlineProject/specification/pull/17), +> [#18](https://github.com/ComlineProject/specification/pull/18)). The +> [Imports guide](../../guides/idl/use.md#referring-to-what-you-imported) says how it reads, and the three +> errors are `reference::not-in-scope`, `reference::qualifier-not-in-scope` and `reference::defined-twice`. Not yet: +> the language server's quick fixes ([language-server#122](https://github.com/ComlineProject/language-server/issues/122)) +> and `comline fix` across a package ([cli#162](https://github.com/ComlineProject/cli/issues/162)); and validators, +> constants and thrown errors are still looked up the old way +> ([core#298](https://github.com/ComlineProject/core/issues/298)). + +**As built before it (core#285).** A `use` is frozen with its resolved path: `use package::types::User` is `Import("types::User")`. +After it, a field could be written `User` or `types::User`, and a qualified reference had to match a `use` of the file +exactly; `package::types::User` in a type position was not accepted. A type reference was frozen as written. So the rule +above held in `use` lines only: `types::User` in a field looked exactly like a path into a dependency named `types`. It +was always traceable to a `use` in the same file, but a reader couldn't tell from the reference itself. **The decision.** A qualified reference starts with a name a `use` brought into scope, as in Rust: @@ -109,9 +121,9 @@ segment means `std` or a dependency holds in `use` lines without an exception el - This page said the qualified references an import brought in are rewritten by the fix; there were none to rewrite, and [What the editor and the fix do](#what-the-editor-and-the-fix-do) now says so. -- `compat` and the sizer resolve a name by namespace suffix and by the first schema declaring it, not as the validator - does: [core#289](https://github.com/ComlineProject/core/issues/289). A resolver shared by the three is where the - Rust model's rule lives. +- `compat` and the sizer resolved a name by namespace suffix and by the first schema declaring it, not as the validator + does: [core#289](https://github.com/ComlineProject/core/issues/289), fixed with a resolver shared by the three + ([core#294](https://github.com/ComlineProject/core/pull/294)), which is where the Rust model's rule lives. **Answered by the user, 2026-11-15:**