direct import resolution by mighdoll · Pull Request #199 · webgpu-tools/wesl-spec

mighdoll · 2026-07-06T06:59:34Z

fix for #193

replace the left-to-right segment walk with direct resolution:
the last path segment names the declared item, the preceding segments name the module.

declarations and modules naturally live in separate namespaces now

fn foo() {} and foo::bar(); do not conflict

lazy vs eager resolution is an implementation choice

clarify terms a bit

@stefnotch

- `@wildcardable` directive. publishers can mark any module not just `prelude` - `builtin_shadow` moves to publish time warning (and dropped -ing suffix) - write out scope precedence levels and error vs. warning cases. - add @stefnotch's wildcard expansion idea as future work work for publishing tool to protect against transitive version skew

just add sentence in the precedence section also drop the packag names can shadow line iit's clear enough from the table

to make clear that other names than 'prelude' are allowable

also add note that builtin_shadow client side check is only when referenced

- add `attribute*` to `import_statement` so `@diagnostic` is grammatical on imports - `module` becomes a reserved keyword

- rationale for @wildcardable syntax - rationale for @wildcardable design

and whether that's more readable depends on how many there are.

as in: `@!wildcardable;`

- rename diagnostic to cross_package_wildcard - rename diagnostic to unsuppored_wildcard - clarify suppression of builtin_shadow - clarify module level suppression generally - clarify that wildcards can be in import collections

replace the left-to-right segment walk with direct resolution: the last path segment names the declared item, the preceding segments name the module. declarations and modules naturally live in separate namespaces now - `fn foo() {}` and `foo::bar();` do not conflict lazy vs eager resolution is an implementation choice clarify terms a bit

stefnotch

Usually I'd bikeshed a lot, but I already independently implemented this.

This seems reasonable to me, from both a spec and an implementation standpoint. I approve of this.

k2d222

Two main comments:

before, we had this condition:

File not found: We assume an empty module as the current module, and continue with that.

now idk what happens when importing an intermediate module path.
It's unclear who decides to use the filesystem storage or some other storage. It's unclear that the fs storage is normative, but the others are implementation-defined.

k2d222 · 2026-07-07T12:56:22Z

+* Any other first segment must name a known package, and anchors the path at
+  that package. Tools find the known packages in the
+  [`wesl.toml`](WeslToml.md) file or through the host package manager's
+  dependencies.


is the current package name importable? I forgot what we agreed on.

There is no "current package name" in the spec at the moment. That should be a separate issue to deal with.
(Lygia wanted it after all.)

Maybe we'll do it with the same thing that was proposed here: #189 (comment) ?

AFAIR we agreed it's importable. Fixing with #189 seems reasonable.

k2d222 · 2026-07-07T13:09:17Z

 An import collection imports multiple items, and allows for nested imports.

-### Import resolution algorithm
+A wildcard import imports all top-level declarations from a module. Submodule names and submodule contents are not imported. A wildcard must follow a module path; a bare `import *;` is an error. A wildcard may also appear as a member of an import collection, applying to the module path before the braces (see [Import bindings](#import-bindings)).


It looks like the direct import resolution no longer warrants that intermediate submodule exist, i.e import lygia::math::abs is a valid module path, but import lygia::math is not. Is that the case?

Yes, exactly. Intermediate submodules are no longer necessary.

if so then there are some wording tweaks to do. For instance: import foo::bar::* is only valid if foo::bar is a full path to a module. But import foo::bar is valid even if foo::bar is only an intermediate path (not a valid module), because then I can do bar::baz::decl().

k2d222 · 2026-07-07T13:13:27Z

+[Resolving a declaration path](#resolving-a-declaration-path).
 The root folder, or the root module, needs to be provided to the linker. This is currently a linker-specific API, and may change once we introduce a `wesl.toml`.

 Linkers should fall back to `.wgsl` files when a `.wesl` file cannot be found.


k2d222 · 2026-07-07T13:19:57Z

can we move sec. rationale and alternatives here.

I was sorely tempted, but seemed better as a separate PR.

k2d222 · 2026-07-07T13:31:39Z

 ## Filesystem Resolution
-To resolve a module on a filesystem, one follows the algorithm above.
+To resolve a module on a filesystem, one follows the mapping in
+[Resolving a declaration path](#resolving-a-declaration-path).


not just that: we start with a filesystem path prefix provided by the linker or wesl.toml, we append the segments from the mapping above, and then we suffix the last segment with .wesl or .wgsl. That's the complete fs path.

Conflict resolution per 193-into-187 merge checklist: - keep the public import re-export paragraph in the grammar section; take direct-imports' module attribute wording - replace the old import walk algorithm with the new 'Resolving a declaration path' model from direct-imports - reattach public import re-exports to item lookup in the new resolution section - carry over the resolution-vs-visibility paragraph and the wildcard visibility-skip rule after the resolution rules - point Filesystem Resolution at the new resolution section - keep the Visibility.md re-exports link in the wildcardable recommendations Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- demote the "tools can enumerate resolutions" paragraph to a [!NOTE] - clarify intermediate paths don't need to be modules

mighdoll · 2026-07-08T06:50:18Z

Two main comments:

before, we had this condition:

File not found: We assume an empty module as the current module, and continue with that.

now idk what happens when importing an intermediate module path.

It's unclear who decides to use the filesystem storage or some other storage. It's unclear that the fs storage is normative, but the others are implementation-defined.

See if it's more clear now on #199. 🤞

k2d222 · 2026-07-08T09:23:29Z

the conflicts between 199 and 197 make it hard to review. I say let't merge this and we can adjust the minute details in followup PRs.

stefnotch · 2026-07-08T09:28:29Z

@k2d222 Am happy with that. Alternatively we could play around with rebasing.

stefnotch · 2026-07-08T09:47:30Z

Okay, I tried out the rebase. Relatively straightforward with jj, but it would be a force push and it would affect the #187 pull request. Which, if I remember correctly, git does not like at all.

So I vote in favour of ~~everyone adopting jj~~ just merging this and fixing the issues afterwards.

stefnotch and others added 26 commits April 22, 2026 15:58

Add glob imports

071d6db

Update glob imports

0e146af

move wildcardable motivation and advanced mode higher

ae56930

move builtin_shadow to client side warning

216457c

rm forward compatibility section

8fcb4a7

just add sentence in the precedence section also drop the packag names can shadow line iit's clear enough from the table

no waffling about library publish tool expansion

f4940e2

change wgsl_test module to 'expect'

a1ec6c8

to make clear that other names than 'prelude' are allowable

add supressible diagnostics section

b758d95

fix outline level for scope precedence

abfb0e7

restore builtin_shadow publisher side check

81e06f4

also add note that builtin_shadow client side check is only when referenced

clarify wildcard clash case

7d4bfd0

clarify precedence means wildcard updates are also safe

9e46adf

switch to @wildcardable module; syntax

2a21505

- add `attribute*` to `import_statement` so `@diagnostic` is grammatical on imports - `module` becomes a reserved keyword

add ImportsDesign explainer

1a46cd8

- rationale for @wildcardable syntax - rationale for @wildcardable design

direct imports are more traceable

b58f43b

and whether that's more readable depends on how many there are.

clarify at most one 'module' per file

983259d

rm client side builtin_shadow for separate PR

eb455ad

clarify where wildcard_shadow appears

fa9e837

clarify error location in table

946d64d

@! syntax for module attributes

ca3c45b

as in: `@!wildcardable;`

revise based on PR feedback

66df0b7

rm some zero width characters

78ff4d1

note prohibiting import *;

cb61e0c

revise based on latest k2d222 comments / agent review

9feb566

- rename diagnostic to cross_package_wildcard - rename diagnostic to unsuppored_wildcard - clarify suppression of builtin_shadow - clarify module level suppression generally - clarify that wildcards can be in import collections

github-project-automation Bot added this to specs and docs Jul 6, 2026

github-project-automation Bot moved this to Todo in specs and docs Jul 6, 2026

mighdoll changed the title ~~direct import resolution per #193~~ direct import resolution Jul 6, 2026

stefnotch reviewed Jul 6, 2026

View reviewed changes

Comment thread Imports.md

stefnotch reviewed Jul 6, 2026

View reviewed changes

Comment thread Imports.md

stefnotch approved these changes Jul 6, 2026

View reviewed changes

stefnotch requested a review from k2d222 July 7, 2026 05:55

k2d222 requested changes Jul 7, 2026

View reviewed changes

mighdoll added a commit that referenced this pull request Jul 8, 2026

address k2d222 comments on #199:

9a381df

- demote the "tools can enumerate resolutions" paragraph to a [!NOTE] - clarify intermediate paths don't need to be modules

Uh oh!

Conversation

mighdoll commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stefnotch left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

k2d222 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mighdoll commented Jul 8, 2026

Uh oh!

k2d222 commented Jul 8, 2026

Uh oh!

stefnotch commented Jul 8, 2026

Uh oh!

stefnotch commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mighdoll commented Jul 6, 2026 •

edited

Loading

stefnotch left a comment •

edited

Loading

k2d222 left a comment •

edited

Loading