Skip to content

references: qualified references follow the Rust model (#290, #286) - #297

Merged
Kinflou merged 8 commits into
masterfrom
qualified-references
Nov 16, 2026
Merged

Kinflou merged 8 commits into
masterfrom
qualified-references

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Closes #290, closes #286. Refs #281. Rule: Qualified references (decided 2026-11-15, the details settled 2026-11-16 in the comment on #290). Cases: ComlineProject/specification#17 (merge commit 0b376dd, part of specification#14).

The rule

A name in scope in a schema is one of

  • a declaration of the schema;
  • what a use brings in: its alias, else the last segment of its path (use package::types as t brings in t and not types), or every name of a {...} or *;
  • a root: package, parent, self, std, a dependency's name.

A whole-namespace use (use package::types) brings in only types. A qualified reference resolves its first segment that way, then walks down; a full path from a root needs no use (package::types::User, parent::common::Error, self::nested::Type, std::http::Request, greeting::hello::Greeting). A qualified reference is frozen as its resolved path from the package's root: api::Invoice, billing::api::Invoice and an alias's b::Invoice all freeze as billing::api::Invoice. A bare name freezes as written. Nothing frozen for an existing package changes (see below).

Changed

  • compiler::references (new): Scope is the rule over a schema's declarations and the project; check_references reports what it refuses, every error at once; named_types lists the type names a schema writes, with where.
    • A use that fails to resolve still brings its name in (use modles::Blob is import::unresolved and nothing else); a * that can't be resolved may bring in any name. A name from a * gives way to a declaration or another use of it, as in Rust; two uses of the same thing are redundant, not an error.
    • use greeting (a dependency's name alone), use std, and use package::billing (a directory of schemas with none of its own) are uses now: check_imports accepted none of them. A directory reached by a bare path is import::bare-own-schema-path.
  • interpret_context: check_imports and check_references both run, both are reported (imports/bare-own-namespace expects import::bare-own-schema-path and reference::not-in-scope), and then the schema stops, so validation never adds validate::unknown-type to what they said. A config error (the reserved dependency names) still stops the build before any schema is checked.
  • Freezing: compile_declarations renames each qualified type to its path before the units are returned (FrozenUnit::for_each_type_mut, new, with for_each_type). A qualified path to a declaration of the schema itself freezes as its bare name. The units of a re-exported error are the declaring schema's own and are left as they are.
  • What a schema uses now includes the schemas its full paths reach: compile_order and the import-cycle check read them (package::billing::api::Invoice with no use has to be compiled after billing::api), imports_foreign asks about a qualified name's schema outright and no longer also about every use that brings in its last segment, check_aliases reads a qualified alias target through the scope, and stdlib::used_by merges the std schema a full std::http::Request names with no use.
  • Validator: ImportLookup::reaches(name) (default false): whether a qualified type is a path to a declaration the project holds. validate_with puts those in the symbol table as imports of the schema, so the checks that follow (validate_type, could_be_imported, alias and validator targets) see them. A qualified type that isn't (billing::api::Missing) is still Unknown type.
  • ProjectImports::declaring_schema finds a qualified name's schema by its namespace first, then through the schema's uses as before (a validator called validators::StringBounds is frozen as written, not as a path).

Diagnostics

Each is an error with a span at the name, and a fix where one is safe. Diagnostic::fix holds one fix, so the alternative is in the help.

Code Message Help Fix
reference::not-in-scope 'User' is not in scope 'User' is declared in `package::types`: add `use package::types::User`, or write `types::User` (the second as the file can write it: through a namespace in scope, else from package) Add `use package::types::User` : after the last use, else before the first declaration. Offered only when exactly one schema declares a type of the name. Several: the help names them. None: the help says nothing declares it
reference::not-in-scope, a namespace used as a type 'types' is a namespace, not a type
reference::qualifier-not-in-scope 'types' is not in scope, in `types::User` `User` is in scope already: write `User`, or write `t::User`, or add `use package::types` to keep `types::User` , or the path from package Write `User` , Write `t::User` , Write `billing::api::Invoice` , Write `package::types::User` : replaces the name. Offered when exactly one schema declares it under that path
reference::defined-twice 'Invoice' is defined twice in this schema rename one, or import with an alias: `use package::billing::api::Invoice as BillingInvoice` Import `Invoice` as `BillingInvoice` : as <First segment><Name> after the later use, else the other. Not offered for a {...}, a *, a name already aliased, or an alias that is taken

The secondary label of defined-twice is where the other definition is. Rendered, the label of the others is their context (this schema doesn't declare 'User', and no use of it brings 'User' in).

reference::defined-twice replaces the resolver's "a declaration shadows an import": the build refuses the clash, and Resolver still prefers the declaration when it is handed one (a dependency's IR from before the rule), as a_declaration_is_preferred_to_an_import_of_its_name says now.

core#286

When the closest match for import::unresolved's first segment is one of the package's own schemas, the suggestion is the path that reaches it, and a fix writes it: use typse::User says did you mean 'package::types::User'? and fixes to use package::types::User (the rest of the path, ::*, ::{...}, as kept). A dependency's name and std stay as they were (did you mean 'shared'?, no fix). own_path_fix takes the text it replaces.

The resolvers

  • schema::ir::resolve (compat, the sizer): Schema::reach takes a qualified name that no import is the path of as the path it is (Reach::Path): the schema of that namespace, then its declaration, exactly, no suffix. Import::brings is unchanged: reading frozen IR, it takes the wider thing an older compiler froze (a dependency's whole-namespace use is frozen as one import per name, which stays: dropping them would move the IR). Unresolved owns its paths now, as a name written in an editor has no 'a to borrow from.
  • Validator could_be_imported: stays the loose "may this be put to a lookup", with no rule of its own; what it may not accept is reaches' and the lookups', which are exact. It had to see the qualified paths, which the symbol table now holds.
  • ProjectImports::declaring_schema: above.
  • doc.rs Scope::resolve: unchanged. A qualified name there already is Index::path, a path from the root, which is what is frozen now; a bare name is read through the frozen imports of an IR that was validated.
  • Not moved to the rule, and why: the names other than types a use brings in (validators called in @validators, constants in values and sizes, the errors a function throws) are still read by use_brings_into_scope, where a whole-namespace use brings in every name. Qualified references follow the Rust model #290 and the cases are about types; moving those is a second change (open question 2). The types an imported alias, validator or error declares, read from the declaring schema's own text (declared_alias_target, declared_validator_targets), are as that schema wrote them, not its frozen paths.

Conformance

core/tests/spec re-vendored at 8a9d47d (specification#18, which fixed the resolved-* fixture: archive's decoy Invoice is reached by a marked protocol) with vendor.sh, and the comline-catalog rev in core/Cargo.toml; no Cargo.lock is tracked. The runner is unchanged. All 99+ cases pass: imports 20 of 20, references 37 of 37, the new bounded/unreached-* cases, and the rest of the runner.

Existing tests the rule refused

Each is a file the rule's own diagnostic points at; none is weakened, ignored or loosened.

Test Wrote Now
tests/package/from_sources.rs cross_schema_use_resolves_across_the_added_schemas use package::types::User and types::User use package::types and types::User (the diagnostic's "or add the use that brings the qualifier in")
tests/schema/ir/imports.rs test_glob_import_allows_qualified_field_reference use package::types::* and types::User renamed ..._allows_the_bare_field_reference, User (a glob brings in the names, not the namespace). The refusal is an_item_or_a_list_does_not_bring_in_its_namespace
tests/schema/ir/imports.rs test_cross_file_type_alias_keeps_its_name_via_whole_namespace_use use package::types and a bare UserId renamed ..._via_the_use_of_it, use package::types::UserId
tests/schema/ir/imports.rs test_unknown_namespace_is_rejected_with_a_suggestion did you mean 'types'? 'package::types::User' (core#286)
tests/schema/ir/imports.rs test_a_path_that_matches_nothing_is_unresolved_not_a_bare_own_path no fix the #286 fix
tests/schema/ir/type_resolution.rs (#294's) a_name_resolves_to_the_declaration_the_schema_imports use package::p::User and p::User package::p::User, which freezes as the same p::User, and a new form: use package::p and p::User. The dependency tests wrote s0::A after use package::s0::A in a dependency; now package::s0::A

No example schema was refused: examples/imports/src/hole.ids writes ant::Ant after use package::ant.

a_declaration_shadows_an_import_of_its_name in resolve.rs is now a_declaration_is_preferred_to_an_import_of_its_name, and nothing_is_matched_by_suffix_or_taken_first no longer says v1::api::User is not in scope (it is the path of a schema; rapi::User and x::User are tested alongside).

Frozen IR, hashes, benches

No shape hash, frozen IR, migrations expected file, golden or bench result moved: tests/migrations (with deps), the format gate and the bench gate pass with no change to expected/ or the ledger, and nothing was re-blessed or accepted. A whole-namespace use is still frozen as Import(ns) and one import per name, as before. core/formats is untouched, so no format bump.

Tests

core/tests/schema/ir/references.rs: the fixes (applied, and what they write builds), the wording, every error at once, an unresolved import bringing its name, a qualified reference freezing as its path in five spellings (and a bare name, and an already-qualified one, as written), a full path from package::, parent::, self:: and std:: needing no use, an alias target and a function reading qualified names, and the unchanged frozen imports. stdlib.rs: a std path in a type merges its schema. resolve.rs: a qualified name is the path it is. (The decoy cases are the specification's, not repeated here.)

Open questions

Non-type names and directory globs are core#298; the per-name imports of a whole-namespace use are on core#268. Where more than one schema declares the name, reference::not-in-scope offers no fix, only the help naming them.

Not here

  • The language server's mirror (language-server#122's, for this rule): ImportLookup::reaches has a default, so it builds, but a full path will read as an unknown type there until it implements it. check_references and Scope are public for it.
  • The docs' "Not built yet" for the rule (docs, relative-use.md#qualified-references), and the generated guides.
  • comline fix across a package (cli#162): the fixes are on the diagnostics, as imports: own schemas only through package::, parent:: or self:: #285's.

CI

Draft; tests run in CI. All checks pass.

Kinflou added 8 commits November 16, 2026 10:31
…ses)

Vendors its cases: the new references group, and the imports cases that
now also expect reference::not-in-scope or no second error. core's runner
fails them until the rule is built.

Refs #281, #290.
A name in scope is a declaration of the schema, what a use brings in
(its alias, else its last segment) or a root: package, parent, self, std
or a dependency's name. A whole-namespace use brings in only its name. A
qualified reference resolves its first segment that way and walks down;
a full path from a root needs no use. It is frozen as its resolved path,
so api::Invoice, billing::api::Invoice and an alias's b::Invoice are all
billing::api::Invoice, and the frozen IR of an existing package is as it
was.

reference::not-in-scope, reference::qualifier-not-in-scope and
reference::defined-twice carry their fixes, and every error is reported.
An unresolved use still brings its name in. A dependency's name used on
its own, and a directory of schemas, are accepted as uses.

The import did-you-mean suggests package::types::User for one of the
package's own schemas (#286).

Refs #281.
…hed by a marked protocol and the bounded/unreached cases)

Drops each_spelling_reaches_billing_and_not_the_decoy_in_archive: the
references/resolved-* cases hold the same five spellings now.
@Kinflou
Kinflou marked this pull request as ready for review November 16, 2026 03:40
@Kinflou
Kinflou merged commit 69039e7 into master Nov 16, 2026
33 checks passed
@Kinflou
Kinflou deleted the qualified-references branch November 16, 2026 03:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Qualified references follow the Rust model Import "did you mean" suggests a bare own-schema path

1 participant