Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/docs/design/editor-dependency-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion docs/docs/guides/idl/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
187 changes: 160 additions & 27 deletions docs/docs/guides/idl/use.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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
Expand Down
3 changes: 2 additions & 1 deletion docs/docs/proposals/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
32 changes: 22 additions & 10 deletions docs/docs/proposals/use-paths-and-groups/relative-use.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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:**

Expand Down
Loading