Skip to content

imports: qualified references follow the Rust model (core#290) - #193

Merged
Kinflou merged 1 commit into
mainfrom
docs/qualified-references
Nov 16, 2026
Merged

Kinflou merged 1 commit into
mainfrom
docs/qualified-references

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 16, 2026

Copy link
Copy Markdown
Member

Closes #191

Rewrites guides/idl/use.md for the rule that shipped in core#297 (core#290, merged as 69039e7). The accepted and refused forms, and the diagnostic codes, are the ones in the specification's compiler/src/references.cue (specification#17, #18).

In use.md:

  • The path-forms table: a whole-namespace use brings in only its name, a glob brings in the names and not the namespace.
  • "Referring to what you imported": the Rust model, with a table of what each use brings in and how to write the type after it (a dependency too, use greeting included).
  • Full paths without a use (package::, parent::, self::, std::, a dependency's name), walking down from a name in scope, and one type however it is written (frozen as its resolved path).
  • Aliases replace the name: after use package::types as t, types::User is refused.
  • "Defined twice", replacing "a local declaration always wins".
  • The three errors, reference::not-in-scope, reference::qualifier-not-in-scope and reference::defined-twice, with when each happens and its fix, and every error being reported at once.
  • The use typse::User suggestion is now package::types::User (core#286).
  • Stated as not done yet: the language server's quick fixes (language-server#122), comline fix across a package (cli#162), and non-type names (validators, constants, thrown errors) still read the old way (core#298).

Elsewhere:

  • proposals/use-paths-and-groups/relative-use.md: the Qualified references section is marked built, with links to core#290 and core#297, in the > **Built** form of schema-compatibility.md; the "as built" paragraph about core#285 is now in the past tense; core#289 is noted as fixed by core#294.
  • proposals/index.md: the entry says what of the proposal is built.
  • design/editor-dependency-packages.md: decision 2 (whole-namespace imports bring names in bare) is marked superseded, since it is the opposite of the rule.
  • guides/idl/index.md: one sentence on how a type is written after a use.

Checked and left alone: every other use in an ids block in the docs (guides/idl/index.md, validator.md, const.md, the std examples) is an item or { ... } use followed by bare names, which the rule accepts. The docs have no diagnostics reference page, so there is nowhere else to add the three codes.

Not run locally; the docs build runs in CI.

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.
@Kinflou
Kinflou marked this pull request as ready for review November 16, 2026 04:30
@Kinflou
Kinflou merged commit 671176b into main Nov 16, 2026
8 checks passed
@Kinflou
Kinflou deleted the docs/qualified-references branch November 16, 2026 04:30
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.

Docs: qualified references follow the Rust model

1 participant