Skip to content

compiler: conformance cases for qualified references (specification#14) - #17

Merged
Kinflou merged 3 commits into
mainfrom
compiler/qualified-references
Nov 16, 2026
Merged

Kinflou merged 3 commits into
mainfrom
compiler/qualified-references

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Closes #14. Epic: ComlineProject/core#281. Implemented by ComlineProject/core#290. Decision: Qualified references (docs#189).

The rule the cases hold implementations to

A qualified reference starts with a name a use brought into scope, as in Rust, or with a root (package, parent, self, std, a dependency). A reference the rule refuses is an error at once, with the likely rewrite as its fix.

New group references (compiler/src/references.cue -> compiler/cases/references.json, 37 cases)

  1. A whole-namespace use brings in only its name:
    • namespace-qualified, namespace-alias-qualified: types::User and t::User build;
    • namespace-bare-refused: a bare User after use package::types is reference::not-in-scope;
    • namespace-alias-original-refused: types::User after use package::types as t is reference::qualifier-not-in-scope;
    • item-bare, braces-bare, glob-bare build; item-qualified-refused, braces-qualified-refused, glob-qualified-refused are reference::qualifier-not-in-scope;
    • no-use-bare-refused (reference::not-in-scope) and no-use-qualified-refused (reference::qualifier-not-in-scope): no use at all.
  2. A full path in a type position, no use: full-package, full-package-nested, full-parent, full-self, full-std, full-dependency; and full-own-schema-unrooted-refused (shapes::types::User without package::).
  3. Down from a name in scope: descend-namespace, descend-alias, descend-dependency build; descend-skips-a-segment-refused (api::Invoice after use package::billing).
  4. Frozen as the resolved path: resolved-item, -namespace, -descent, -alias, -full-path each reach billing::api::Invoice, and not a decoy Invoice in archive (unbounded, so an unmarked protocol using it would be bounds::unbounded); resolved-decoy is the control that reaches the decoy. existing-package-unchanged: a namespace use and models::Blob, as written before the rule, freezes the same protocols and acknowledgements as bounded/other-schema-marked.

Also decided with the user

  • Every error is reported, not only the first, among those of the schemas. Existing case changed in its expected errors: imports/bare-own-namespace now expects import::bare-own-schema-path and reference::not-in-scope (a whole-namespace use brings in only its name). No other existing case reports an extra error.
  • A config error stops before the schemas are checked, as in Rust. imports/dependency-named-std, -package, -parent and -self keep their reserved-name expectation alone; their app schema no longer holds the stray bare Blob (it is a plain struct), so each tests only the reserved name. Said in the readme.
  • A use that fails to resolve still brings its name into scope, so it never cascades: imports/unknown-first-segment is unchanged in outcome (only import::unresolved), and its description and the readme say so.
  • A name or qualifier nothing declares uses the same two codes (nowhere-bare-refused, nowhere-qualified-refused); a fix that adds a use is offered only where a declaration exists, and each description says whether one is.
  • reference::defined-twice, fix: rename one, or import with an alias. Refused: defined-twice-local-and-use, defined-twice-two-uses. Accepted with an alias: alias-resolves-local-clash, alias-resolves-two-uses.
  • use greeting on its own is accepted: descend-dependency-name.
  • parent:: and self:: mean in a type position what they mean in a use (readme).

Codes

The catalog has no diagnostics section yet, so, as in #12, the codes are the closed list in specs/compiler.cue (and its generated schema), and the readme table lists each with its fix:

  • reference::not-in-scope: a bare name nothing brought into scope. Fix: add use package::types::User, or write types::User.
  • reference::qualifier-not-in-scope: a qualified reference whose first segment is neither in scope nor a root. Fix: write User.
  • reference::defined-twice: a name a use and a declaration, or two uses, define. Fix: rename one, or import with an alias.

Three codes (the third, reference::defined-twice, above). not-in-scope and qualifier-not-in-scope are two because the two refusals have different fixes, which tooling attaches by code. Family reference:: because the error is on a type reference, not on a use (import::).

What the format can't say

  • Frozen IR and hashes. A compiler case has no field for the frozen IR or its hash, and no vector computes an IR hash from schemas (ir_hash is an input). The cases show freezing through what a spelling reaches (the decoy's bounds), and the unchanged package through its protocols' given-up sets and acknowledgements. A field for frozen references would be a format change.
  • The fix. A diagnostic is { code, severity }; the fix is in the description and the readme table, not matched.

Existing cases

Only imports/bare-own-namespace changes its expected errors; the four dependency-named-* cases change their schema text (no stray Blob) and unknown-first-segment its description, with the same outcomes as before. Everything else keeps its outcome: item uses, package::models then models::Blob, std and dependency paths stay accepted.

Checked

specs/check.sh --check is clean. The cases are not run against core: they are ahead of it (core#290), and the readme says so.

Kinflou added 3 commits November 16, 2026 09:05
A qualified reference starts with a name a use brought into scope, or with a root (package, parent, self, std, a dependency), as in Rust. New group references, and the codes reference::not-in-scope and reference::qualifier-not-in-scope.
…ares, a dependency's name as a use

Every error is reported: imports/bare-own-namespace and the four dependency-named-* cases also expect reference::not-in-scope. New code reference::defined-twice with refused and aliased cases, cases for names and qualifiers nothing declares, and use of a dependency's name alone.
@Kinflou
Kinflou marked this pull request as ready for review November 16, 2026 01:27
@Kinflou
Kinflou merged commit 0b376dd into main Nov 16, 2026
7 checks passed
@Kinflou
Kinflou deleted the compiler/qualified-references branch November 16, 2026 01:27
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.

Conformance: qualified references follow the Rust model

1 participant