Repository navigation
references: qualified references follow the Rust model (#290, #286) - #297
Merged
Merged
Conversation
added 8 commits
November 16, 2026 10:31
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
usebrings in: its alias, else the last segment of its path (use package::types as tbrings intand nottypes), or every name of a{...}or*;package,parent,self,std, a dependency's name.A whole-namespace
use(use package::types) brings in onlytypes. A qualified reference resolves its first segment that way, then walks down; a full path from a root needs nouse(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::Invoiceand an alias'sb::Invoiceall freeze asbilling::api::Invoice. A bare name freezes as written. Nothing frozen for an existing package changes (see below).Changed
compiler::references(new):Scopeis the rule over a schema's declarations and the project;check_referencesreports what it refuses, every error at once;named_typeslists the type names a schema writes, with where.usethat fails to resolve still brings its name in (use modles::Blobisimport::unresolvedand nothing else); a*that can't be resolved may bring in any name. A name from a*gives way to a declaration or anotheruseof it, as in Rust; twouses of the same thing are redundant, not an error.use greeting(a dependency's name alone),use std, anduse package::billing(a directory of schemas with none of its own) are uses now:check_importsaccepted none of them. A directory reached by a bare path isimport::bare-own-schema-path.interpret_context:check_importsandcheck_referencesboth run, both are reported (imports/bare-own-namespaceexpectsimport::bare-own-schema-pathandreference::not-in-scope), and then the schema stops, so validation never addsvalidate::unknown-typeto what they said. A config error (the reserved dependency names) still stops the build before any schema is checked.compile_declarationsrenames each qualified type to its path before the units are returned (FrozenUnit::for_each_type_mut, new, withfor_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.compile_orderand the import-cycle check read them (package::billing::api::Invoicewith nousehas to be compiled afterbilling::api),imports_foreignasks about a qualified name's schema outright and no longer also about everyusethat brings in its last segment,check_aliasesreads a qualified alias target through the scope, andstdlib::used_bymerges the std schema a fullstd::http::Requestnames with nouse.ImportLookup::reaches(name)(defaultfalse): whether a qualified type is a path to a declaration the project holds.validate_withputs 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 stillUnknown type.ProjectImports::declaring_schemafinds a qualified name's schema by its namespace first, then through the schema'suses as before (a validator calledvalidators::StringBoundsis 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::fixholds one fix, so the alternative is in the help.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 frompackage)Add `use package::types::User`: after the lastuse, 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 itreference::not-in-scope, a namespace used as a type'types' is a namespace, not a typereference::qualifier-not-in-scope'types' is not in scope, in `types::User``User` is in scope already: write `User`, orwrite `t::User`, or add `use package::types` to keep `types::User`, or the path frompackageWrite `User`,Write `t::User`,Write `billing::api::Invoice`,Write `package::types::User`: replaces the name. Offered when exactly one schema declares it under that pathreference::defined-twice'Invoice' is defined twice in this schemarename one, or import with an alias: `use package::billing::api::Invoice as BillingInvoice`Import `Invoice` as `BillingInvoice`:as <First segment><Name>after the lateruse, else the other. Not offered for a{...}, a*, a name already aliased, or an alias that is takenThe secondary label of
defined-twiceis where the other definition is. Rendered, the label of the others is their context (this schema doesn't declare 'User', and nouseof it brings 'User' in).reference::defined-twicereplaces the resolver's "a declaration shadows an import": the build refuses the clash, andResolverstill prefers the declaration when it is handed one (a dependency's IR from before the rule), asa_declaration_is_preferred_to_an_import_of_its_namesays 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::Usersaysdid you mean 'package::types::User'?and fixes touse package::types::User(the rest of the path,::*,::{...},askept). A dependency's name andstdstay as they were (did you mean 'shared'?, no fix).own_path_fixtakes the text it replaces.The resolvers
schema::ir::resolve(compat, the sizer):Schema::reachtakes 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::bringsis unchanged: reading frozen IR, it takes the wider thing an older compiler froze (a dependency's whole-namespaceuseis frozen as one import per name, which stays: dropping them would move the IR).Unresolvedowns its paths now, as a name written in an editor has no'ato borrow from.could_be_imported: stays the loose "may this be put to a lookup", with no rule of its own; what it may not accept isreaches' and the lookups', which are exact. It had to see the qualified paths, which the symbol table now holds.ProjectImports::declaring_schema: above.doc.rsScope::resolve: unchanged. A qualified name there already isIndex::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.usebrings in (validators called in@validators, constants in values and sizes, the errors a function throws) are still read byuse_brings_into_scope, where a whole-namespaceusebrings 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/specre-vendored at8a9d47d(specification#18, which fixed theresolved-*fixture:archive's decoyInvoiceis reached by a marked protocol) withvendor.sh, and thecomline-catalogrev incore/Cargo.toml; noCargo.lockis tracked. The runner is unchanged. All 99+ cases pass:imports20 of 20,references37 of 37, the newbounded/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.
tests/package/from_sources.rscross_schema_use_resolves_across_the_added_schemasuse package::types::Userandtypes::Useruse package::typesandtypes::User(the diagnostic's "or add theusethat brings the qualifier in")tests/schema/ir/imports.rstest_glob_import_allows_qualified_field_referenceuse package::types::*andtypes::User..._allows_the_bare_field_reference,User(a glob brings in the names, not the namespace). The refusal isan_item_or_a_list_does_not_bring_in_its_namespacetests/schema/ir/imports.rstest_cross_file_type_alias_keeps_its_name_via_whole_namespace_useuse package::typesand a bareUserId..._via_the_use_of_it,use package::types::UserIdtests/schema/ir/imports.rstest_unknown_namespace_is_rejected_with_a_suggestiondid you mean 'types'?'package::types::User'(core#286)tests/schema/ir/imports.rstest_a_path_that_matches_nothing_is_unresolved_not_a_bare_own_pathtests/schema/ir/type_resolution.rs(#294's)a_name_resolves_to_the_declaration_the_schema_importsuse package::p::Userandp::Userpackage::p::User, which freezes as the samep::User, and a new form:use package::pandp::User. The dependency tests wrotes0::Aafteruse package::s0::Ain a dependency; nowpackage::s0::ANo example schema was refused:
examples/imports/src/hole.idswritesant::Antafteruse package::ant.a_declaration_shadows_an_import_of_its_nameinresolve.rsis nowa_declaration_is_preferred_to_an_import_of_its_name, andnothing_is_matched_by_suffix_or_taken_firstno longer saysv1::api::Useris not in scope (it is the path of a schema;rapi::Userandx::Userare tested alongside).Frozen IR, hashes, benches
No shape hash, frozen IR, migrations expected file, golden or bench result moved:
tests/migrations(withdeps), the format gate and the bench gate pass with no change toexpected/or the ledger, and nothing was re-blessed or accepted. A whole-namespaceuseis still frozen asImport(ns)and one import per name, as before.core/formatsis 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 frompackage::,parent::,self::andstd::needing nouse, 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
useare on core#268. Where more than one schema declares the name,reference::not-in-scopeoffers no fix, only the help naming them.Not here
ImportLookup::reacheshas a default, so it builds, but a full path will read as an unknown type there until it implements it.check_referencesandScopeare public for it.relative-use.md#qualified-references), and the generated guides.comline fixacross 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.