Skip to content

Bind failed imports to error items instead of blocking their names - #437

Merged
Rigidity merged 10 commits into
mainfrom
rigidity/429-error-bindings
Nov 19, 2026
Merged

Rigidity merged 10 commits into
mainfrom
rigidity/429-error-bindings

Conversation

@Rigidity

@Rigidity Rigidity commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #429.

When an import fails, its name is now bound to an error item (like rustc's Res::Err) instead of being blocked. A use of an error item is silently unresolved, and other imports bring it in like any other item, through super::*, super::X, project::, paths and globs. So follow-on errors disappear without tracking where a block came from. On every existing snapshot the diagnostics are unchanged, except for one improvement. Fuzzing turned up a few more changes, all listed below. One of them reports errors that main hid, and it's the first item under "For you to decide".

Design

What an error item is. It's a fresh Symbol::Unresolved (for values and modules) or Type::Unresolved (for types), recorded in Compiler::error_items. A failed named import gets one for each namespace it fails in:

  • every namespace, if its path doesn't resolve or its name isn't found;
  • the namespaces of the private items, if it found only private items.

Error items aren't recorded as import declarations, so lints never see them. LSP completions skip them, along with a sibling file that one hides.

When it's made. At the settle step, once nothing else can be resolved and nothing waits, and after private re-exports are reported.

  • The failures of the last pass become final then, together with their errors (ImportCache::failed), and the error items are bound. An item with the name could still be found before that point, so nothing is bound earlier.
  • An error item only fills a name that nothing else brought in, so it never replaces a real binding.
  • Every declaration is known before the first resolve_imports run, so the error items made in that run are final too. Signatures are compiled between the two runs, so they already see them.

Globs and super::*. A glob brings in error items like other items: super::* brings in all of them, and a glob with a path brings in the exported ones.

  • An error item only fills an empty name. Error items are only made once real resolution has settled, so nothing real arrives after one. So a name is never ambiguous between an error item and a real item.
  • A named import shadows a glob, as before.
  • If two globs bring in error items for one name, the name is exported if either glob exports it, and both globs count as bringing it in.

Which failures are reported.

  • Links. An import links to the failed imports behind the error items it finds where it fails, or resolves through them (error_links).
  • Kept per scope. What an error item stands for is kept separately for each scope it's bound in (error_origins, keyed by scope and item). A glob brings in the same item everywhere, so what explains a name in one module mustn't leak into another.
  • Copied and merged. An import that binds an error item copies what it stands for from the scope where it found it. Two error items that meet in one name (two failed imports of the name, or two globs' error items) each explain what finds it. A glob's error item doesn't explain a named import's failure, because the named import shadows the glob.
  • What's reported. The reported failures are those in strongly connected components of the links that link to no other component (reported_failures). A chain reports its start. Every member of a cycle, such as import A::B; import B::A; or import X::X;, is still reported.

Type checking and codegen. compile_path returns PathResult::Unresolved, with no diagnostic, for an error item, or for a name with an error item in any namespace.

  • Every error item comes from a failed import.
  • Every chain of links ends in a component that's reported.
  • So a program with an error item always has an error reported, and never reaches codegen. 4,000 more random programs (below) hit no internal errors.

What's removed, and what isn't

Removed:

  • Blocks in scopes: Scope::block, retain_block_origins, is_blocked, block_origins and blocked, with the per-namespace blocked maps. scope.rs: 408 → 338 lines.
  • Block lookups in the compiler: Compiler::is_blocked_in and block_origins_in, and the block checks in sibling_item, sibling_items, resolve_item_in and the enclosed-prelude lint. compiler.rs: 1252 → 1226 lines.
  • Passing blocks on: FailedName and passing blocks through super::* and super::X (error items travel by themselves), plus block, failing_imports, record_blocked_import, Base::block_origins, Base::find and blocked_imports.
  • failure_is_reported and reached_through_blocks, which were roughly quadratic in the number of failing imports. They're replaced by one SCC pass, which shares its closed-component helper with stuck_lookups.
  • The cleanup that private re-export recovery needed: forget_unresolved_path; dropping PrivateSymbol, PrivateType and PrivateModule errors once they no longer apply; and the ImportError::UnresolvedPath, PrivateSymbol and PrivateType variants. A failure's errors now live in its Failure.
  • One restart point: the settle step had three restarts (report private re-exports, block failed names, remove stale blocks). It now has two (report private re-exports, bind error items).

Overall, the non-test code in the crates loses 91 lines (526 added, 617 removed). imports.rs is slightly shorter (1996 → 1980 lines), since it now does what the scopes and the compiler did for blocks.

Kept:

  • The failure graph. Cycles need some graph. Without one, import A::B; import B::A; would resolve through each other's error items and report nothing. What's left is a linear SCC pass over links taken from error items, with no stored block origins.
  • The export-anyway recovery for private re-exports (report_private_reexports, with its waits rule for chains).
    • An error item can't stand in here. A module that re-exports its own private item (const X: Int = 1; export X;) already has the item under that name, so there's no empty name to bind.
    • The recovery now runs in both resolution runs, before any failure is final. So nothing has failed for good because of a private re-export when it's recovered, and none of the cleanup above is needed.
  • The pass limit from Bound the number of passes in resolve_imports #431. Its doc comment lists the current settle steps. Fuzzing measured at most 2 × imports + 2 passes (never more), so the doc's measurements still hold.

Diagnostic changes

These drop errors that follow from another error that's still reported, unless the item says otherwise.

  • failed_import_origins_a and _z: import super::a::X;, where a has export nope::X;, is no longer reported as Unresolved import X. The exported error item explains it. Both name orders agree.
  • Uses in another namespace. A use of a failed import's name as a value is no longer reported as finding a type with the same name (Expected symbol, but found type), and the same holds the other way round. Test: failed_names_in_another_namespace.
  • Exported failed imports. Importing or using their names from other modules, including through globs, no longer reports Unresolved import, Undeclared symbol or Undeclared type. Tests: exported_failed_imports, and the exported_failed_names_through_globs_a/_z pair.
  • Private items next to an exported failed import of the same name. mod m { type X = Int; export nope::X; } followed by import m::X; no longer reports the private type. Had nope::X resolved, the import would have brought that in, with no error, as in Rust. Test: private_items_beside_exported_failed_imports.
  • Error items in a named import's other namespaces. import m::x; finds m's function x and the error items of m's failed export nope::x;. So import x::d::x; is explained, and its Cannot subpath non-module symbol is gone. Test: failed_names_merged_through_named_imports.
  • Chains through globs whose error items meet. Main reported some imports in a chain that only fails because another glob's import failed. Fix that import and the chain resolves. Tests: failed_globs_beside_named_imports_a/_z, and failed_names_through_globs.
  • Private re-exports reaching glob importers. Take mod d { export X; const X: Int = 1; } followed by export d::*;. The recovery now runs before glob importers are final, so the glob passes X on. A use of X as a type then reports Expected type, but found symbol X instead of Undeclared type X, and the glob's Unused import * warning goes away. Test: private_reexports_through_globs.
  • Added: a named import that shadows a glob of the name now reports its own failure. For example, mod d { import X; import super::*; } when the root's import X; failed. The named import shadows the glob, so it fails even when the root has a real X, and main reports it then too. Main only hid it when the root's import had failed as well. Test: failed_names_through_globs.
  • Added: cycles through an exported failed import report each member, like other cycles. Examples: export mod b { import a::d; mod a { export super::d; } } and export mod f { import super::f::a; export a; }. In both, each import fails only because of the other. Main reported one member, because it never linked the last name of a path. Test: failed_import_cycles_through_exports.

Other new tests:

  • failed_imports_of_one_name_a/_z: two failed imports of one name, one of them exported.
  • failed_glob_cycles_a/_z: a cycle reported whichever glob brings its error item in first.
  • failed_names_through_globs_of_other_modules: a merge in one module doesn't explain a failure in another.
  • failed_path_segments_in_another_namespace, and failed_module_names_used_as_types.
  • private_failed_names_through_exported_globs: a glob that re-exports a module's items doesn't export its private error items.
  • Four LSP completion tests.

Comments and test names that described blocks now describe error items. The blocked_* snapshot files keep their names.

Fuzzing

I generated random programs with up to 5 nested inline modules. They use named, glob, super, project, exported and failing imports, private items and re-exports, and they use the imported names in bodies and signatures. In the project runs, some top-level modules move into sibling files. Each program was compared with origin/main, and compiled again with its module names permuted, as #393's renaming fuzzer does. The names are one letter, so locations don't move.

Final runs on the head of this branch, on fresh seeds, against origin/main at the same base:

Run Programs Crashes or timeouts Order-dependent Differ from main Only drop errors Add errors
single file 3000 0 0 576 450 126
with sibling files 3000 0 0 506 429 77
  • Dropped errors. I reduced samples of each kind. Each was a follow-on of an error that's still reported, in one of the categories above.
  • Added errors. I reduced every added error from two earlier runs and samples from the later ones. Each was either a named import that shadows a glob, or a cycle through an exported failed import (the two "Added" items above). The first is most of the count. The generator writes import X; next to import super::*; often, so real code should hit it much less.
  • Order dependence. Three cases came up during review and are fixed, and each has an _a/_z test: whether a name's error item was exported; origins kept on the item rather than per scope; and an export lost when two globs' error items met. An earlier run found one program whose results depend on module names, and main's results for it do too. The final runs found none.
  • Review rounds. Five rounds of review, the last a full round over the whole branch after the per-scope redesign. The reviewers ran over 20,000 more programs on other seeds, plus mutants of each mechanism. Every mechanism the change adds has a test that fails without it, except the error-item guard in check_forced_lookups. No reviewer could reach it, and its comment says it's only a guard.

For you to decide

  • A named import that shadows a glob now reports its own failure. In 4,000 fuzzed programs, about 3% gained such an error. Main reports the same import whenever the name it shadows is real, and hid it only when that name had also failed, so I went with reporting it. To keep main's output instead, let a glob's error item explain a named import's failure too. That reintroduces a cross-module merge, and a reviewer showed the merge hiding independent failures in other modules.
  • Exported error items are visible from other modules. Most of the improvements come from this, as does the cycle-through-export change. The alternative treats every error item as absent outside its module, which keeps main's behaviour for both. That's a small change: skip exported error items in named_items, lookup_segment and globs, and drop the link in NamedItems::Public. But it brings back those follow-on errors.
  • The export-anyway recovery stays, for the reason above.

Note

Medium Risk

This changes how import resolution handles failed imports, which every program with an import error goes through. A program without a failed import never binds an error item; the only change for it is that private re-exports are recovered in the first resolution run as well as the second. Every existing snapshot and unit test is unchanged except the one listed improvement, and the fuzzing found no crashes and no new order dependence.

  • Import resolution (compile/imports.rs): error items replace blocks; Failure records final failures; per-scope origins and an SCC pass (reported_failures) replace failure_is_reported; private re-exports are recovered before failures are final, without the error cleanup.
  • Scopes and lookups (rue-hir scope.rs, compiler.rs, compile/path.rs): blocks are removed; error items are found silently; sibling files that an item hides aren't completed.
  • LSP (rue-lsp): completions skip error items.
  • Tests: 19 new snapshot tests, 4 LSP tests, and updated comments.

- Bind error items through one helper, and with `bind`, for failed imports, paths through error items and glob imports
- Drop the per-import cache of error items, which was never hit, and the clone of the failures each settle step
- Share the closed strongly connected components between stuck lookups and reported failures
- Drop checks for private error items in import paths and named imports, which never see them before their failures are final, and the entrypoint check, which no lint could observe
- Test the origins that a named import merges, and that completions skip failed imports
- Only merge a glob import's error item into one that another glob brought in, since a named import that shadows the glob fails on its own
- Don't offer a sibling file after `super::` when the file has an item with its name
- Bind error items with `bind` in one branch, and drop the glob's second error-item branch and the unreachable binding for paths through error items
- Test failures at a path segment that another namespace's error item explains, and private re-exports reaching glob importers
- An error item that a glob import brings in is the same item in every module, so merging origins on the item changed what explained it everywhere, which hid unrelated failures and made cycles depend on module names. Origins are now kept per scope, and copied along when an import binds the item
- Merge a glob's error item only into one that a glob import bound, rather than skipping whenever any named import of the name exists
- Link only error items in the scope where a name is looked up, and drop the unused `Base::find`
- Test glob cycles and globs beside named imports in both name orders, failures that a merge in another module doesn't explain, and a merge that changes which failures are reported
When a second glob import brought in an error item where one was already bound by a glob, it merged origins but didn't export the binding or count as bringing it in, so whether the name was exported depended on which glob import ran first, and so on module names.
@Rigidity
Rigidity force-pushed the rigidity/429-error-bindings branch from 5c98244 to 8960cda Compare November 19, 2026 07:38
- Compute what a glob import exports once per item, and export a glob-imported error item through `bind`
- Drop the copy of origins when a glob binds an error item, which its next pass makes anyway, so it isn't done for every real item a glob binds
- Build the failure graph from failed imports alone, since error items only stand for them
- Test that a glob doesn't export another module's private error item, and a failed module name used as a type
@Rigidity
Rigidity merged commit 0900047 into main Nov 19, 2026
6 checks passed
@Rigidity
Rigidity deleted the rigidity/429-error-bindings branch November 19, 2026 08:37
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.

Bind failed imports to an error item instead of blocking their names

1 participant