diff --git a/Imports.md b/Imports.md index 4988291..a75c212 100644 --- a/Imports.md +++ b/Imports.md @@ -22,6 +22,10 @@ import my::geom::sphere::{ draw, default_radius as foobar }; // Imports a whole module. Use it with `bevy_ui::name` import bevy_ui; + +// Import all items from another module +import bevy::prelude::*; +import wgsl_test::expect::*; ``` These can then be used anywhere in the source code. @@ -66,7 +70,7 @@ translation_unit: | import_statement* global_directive* global_decl* import_statement: -| 'import' import_relative? (import_collection | import_path_or_item) ';' +| attribute* 'import' import_relative? (import_collection | import_path_or_item) ';' import_relative: | 'package' '::' | 'super' '::' ('super' '::')* @@ -74,6 +78,7 @@ import_relative: import_path_or_item: | ident '::' (import_collection | import_path_or_item) | ident ('as' ident)? +| '*' import_collection: | '{' (import_path_or_item) (',' (import_path_or_item))* ','? '}' @@ -91,6 +96,25 @@ An item import imports a single item. The item can be renamed with the `as` keyw An import collection imports multiple items, and allows for nested imports. +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 resolution algorithm](#import-resolution-algorithm)). + +WESL also extends WGSL's `global_directive` rule with a *module attribute*: a `@!`-prefixed attribute that carries module-level metadata. It is used by `@!wildcardable` (see [Wildcard imports](#wildcard-imports)) and reserved for future module-level metadata. + +```ebnf +global_directive: +| ... // existing WGSL forms +| module_attribute_directive + +module_attribute_directive: +| '@' '!' ident_pattern_token argument_expression_list? ';' +``` + +A module attribute is written like a WGSL `attribute` with a `!` immediately +after the `@`, and is terminated with `;`; `ident_pattern_token` and +`argument_expression_list` are the WGSL rules. Like other global directives, +module attributes appear after any imports and before any global declarations, +and apply to the module they appear in. + ### Import resolution algorithm To resolve the import, the recursive structure is flattened out. This means turning every `import_collection` into multiple separate imports, ending with the items. @@ -102,6 +126,17 @@ import a::c::d; import a::c::e as f; ``` +A wildcard may appear as a member of an import collection: +`import foo::{a::b, *};` becomes + +```wesl +import foo::a::b; +import foo::*; +``` + +The wildcard imports only `foo`'s own top-level declarations: the sibling +branch reaching into submodule `foo::a` doesn't widen it. + Then, one iterates over each segment from left to right, and looks it up one by one. 1. We start with the first segment. @@ -111,8 +146,9 @@ Then, one iterates over each segment from left to right, and looks it up one by 2. We take that as the "current module". 3. We repeatedly look at the next segment. 1. Item in current module: Take that item. We must be at the last segment, otherwise it's an error. - 2. (Else if re-exported or inline module in current module: We continue with that module.) - 3. Else go to `current module path/ident.wesl` + 2. Wildcard import: Take all items in the current module. + 3. (Else if re-exported or inline module in current module: We continue with that module.) + 4. Else go to `current module path/ident.wesl` * File found: We take that file as the current module. * File not found: We assume an empty module as the current module, and continue with that. * (Re-exporting changes the path.) @@ -121,10 +157,7 @@ Then, one iterates over each segment from left to right, and looks it up one by To get an absolute path to a module, one follows the algorithm above. In step 1, one takes the known absolute path of the `super` module, or the package. The absolute path of the `super` module is always known, since the first loaded WESL file must always be the root module, and children are only discovered from there. -Once the import has been resolved, the last segment, or its alias, is brought into scope. - -The order of the scopes is "user declarations and imported items > package names > predeclared items". -This lets WGSL add more predeclared items without breaking existing WESL code. Package names can shadow predeclared items, but we recommend that authors avoid doing that. +Once the import has been resolved, the last segment, or its `as` alias, is brought into scope. ### Example @@ -245,6 +278,199 @@ const b = a + 1; Basic linker implementations do not need to check for this. Generating broken code and letting the underlying shader compiler throw an error is fine. +## Wildcard imports + +Wildcard imports bring all items from another module into the importing module's +scope. + +Users can wildcard import: +- from any other module in the local package. +- from any external library module where the library author has added a + `@!wildcardable` annotation. + +Wildcard importing brings some stability risk when the imported module adds to +its API. The newly introduced names may conflict with other names in the +importer's namespace (from local definitions and other imports), leading to +compiler warnings or errors. To help mitigate this risk, WESL provides a +`@!wildcardable` annotation that library authors can place on modules that are +designed for wildcard importing. + +Advanced users who wish to wildcard import from external modules not marked as +`@!wildcardable` can do so by suppressing `unsupported_wildcard` (see +[Suppressible diagnostics](#suppressible-diagnostics)). + +```wesl +// wildcard import from a @!wildcardable external +import bevy::prelude::*; +import wgsl_test::expect::*; + +// wildcard import from within the local package +import package::utils::*; +import super::fun::*; +``` + +### `@!wildcardable` annotation + +Library authors mark modules they intend for library consumers to wildcard +import with the `@!wildcardable;` module attribute (see [Grammar](#grammar)): + +```wesl +// math.wesl (in a library) +@!wildcardable; + +fn dot2(a: vec2f, b: vec2f) -> f32 { return a.x*b.x + a.y*b.y; } +fn cross2(a: vec2f, b: vec2f) -> f32 { return a.x*b.y - a.y*b.x; } +``` + +### Recommendations for `@!wildcardable` modules + +Because every name in a `@!wildcardable` module is a potential collision in +importer code, library authors should curate these modules carefully. + +**Add hesitantly.** Additions to a `@!wildcardable` module are semver minor +version bumps but can break users who have local declarations or import other +`@!wildcardable` modules. +- **Bundle** additions into a major release when one is upcoming. +- **Document** additions clearly in changelogs so downstream users debugging + unexpected name resolution can trace them. + +**Compose with re-exports.** See [Re-exports](#re-exports) (TBD) to collect +items from other modules into a single `@!wildcardable` module for user +convenience. + +**Avoid generic names.** Prefer domain-specific names. Common names like +`Buffer`, `Config`, `Result`, `Vec`, etc. are more likely to collide with user +applications. + +**Don't shadow WGSL builtins.** Names like `vec3`, `clamp`, `inverseSqrt` have +expected semantics that oughtn't be implicitly overridden with wildcards. +Similarly, avoid experimental Naga/Dawn/Safari builtins. +- The `builtin_shadow` diagnostic flags this (see + [Suppressible diagnostics](#suppressible-diagnostics)). +- If a future WGSL update adds a conflicting builtin name, plan to update the + `@!wildcardable` module to rename the conflicting item. + +### Library-to-library wildcard imports + +Libraries that wildcard import from other libraries raise special concerns. If a +user's package manager chooses a newer version of the imported-from library, +the user may see a conflict in library code they don't expect to modify. + +Cross-package wildcard imports in library code +trigger the `cross_package_wildcard` diagnostic, a suppressible error. Library +authors can suppress the diagnostic with +`@diagnostic(off, cross_package_wildcard)` on the import statement, e.g. when +wildcard importing from external packages they control. + +**Optional: publish-time wildcard expansion.** Library publishing tools may +also offer to expand wildcards to named imports in the published version of a +module, snapshotting the names at publish time: + +```wesl +// source +import bevy::prelude::*; +``` + +```wesl +// published artifact +import bevy::prelude::{Color, Mesh, Transform, /* snapshot at publish time */}; +``` + +Expansion pins the imported names so that a newer version of the imported-from +library can't introduce conflicts into already-published code. + +## Import errors and warnings + +WESL emits errors for name collisions and for unsupported wildcard imports, +and warnings for shadowing that could surprise readers. Genuine +collisions cannot be suppressed; other diagnostics are suppressible via +`@diagnostic`. + +| Situation | Behavior | +| --- | --- | +| Local declaration conflicts with named import | Error | +| Named import conflicts with named import | Error | +| Wildcard import conflicts with wildcard import (when name is referenced) | Error | +| Wildcard import from a non-`@!wildcardable` external module | Error (`unsupported_wildcard`) on the import; suppressible | +| Cross-package wildcard import in library code | Error (`cross_package_wildcard`) on the import; suppressible | +| Local declaration or named import shadows a wildcard-imported name | Warning (`wildcard_shadow`) on the shadowing declaration or import; suppressible | +| `@!wildcardable` module exports an item shadowing a WGSL builtin | Warning (`builtin_shadow`) on the shadowing declaration; suppressible | + +When multiple wildcard imports are in scope, the same name may be exported by +more than one module. If every wildcard resolves the name to the same +declaration, references are unambiguous and no error occurs. A name that could +refer to two different declarations is a dormant conflict: an error occurs +only where the name is referenced: + +```wesl +import foo::*; // exports clashing_zap +import bar::*; // exports a different clashing_zap + +fn main() { + let x = clashing_zap(); // error: ambiguous between foo::clashing_zap and bar::clashing_zap +} +``` + +The fix is to disambiguate with a named import (`import foo::clashing_zap;`, +or `import foo::{clashing_zap, *};` to keep the wildcard) or an +[inline module path](#inline-usage) (`foo::clashing_zap()`). + +### Suppressible diagnostics + +Each diagnostic below can be suppressed at the site indicated with a +`@diagnostic` attribute, or module-wide with WGSL's +[global diagnostic directive](https://www.w3.org/TR/WGSL/#global-diagnostic-directive), +e.g. `diagnostic(off, wildcard_shadow);`. + +- **`unsupported_wildcard`** fires on a wildcard import from an external module + that doesn't support wildcard import (not marked `@!wildcardable`). Suppress + with `@diagnostic(off, unsupported_wildcard)` on the import statement to + accept the upgrade risk that future versions of the imported module may add + conflicting names. The suppression has no effect on an import from a + `@!wildcardable` module, where the diagnostic never fires. + +- **`wildcard_shadow`** is a warning that fires on a local declaration or named + import that shadows a name brought in by a wildcard import. The shadowing is + allowed: the local declaration or named import wins by precedence + (see [Scope precedence](#scope-precedence)). Suppressing the warning with + `@diagnostic(off, wildcard_shadow)` on the shadowing declaration or import + statement changes only the reporting, not the resolution. + +- **`cross_package_wildcard`** is a suppressible error that fires on a + cross-package wildcard import in library code (see + [Library-to-library wildcard imports](#library-to-library-wildcard-imports)). + Suppress with `@diagnostic(off, cross_package_wildcard)` on the import + statement. + +- **`builtin_shadow`** is a warning that fires in a `@!wildcardable` module, + on a top-level declaration whose name shadows a WGSL builtin such as `vec3` + or `clamp`, whether or not any module wildcard imports it. Suppress with + `@diagnostic(off, builtin_shadow)` on the offending declaration if the + override is intentional. + +## Scope precedence + +When a name could resolve to items at multiple precedence levels, the +highest-precedence one wins. The table in +[Import errors and warnings](#import-errors-and-warnings) describes whether +such a resolution is silent, produces a warning, or produces an error. + +1. user declarations and named imports (non-wildcard) +2. wildcard-imported names +3. package names +4. predeclared items (WGSL builtins) + +User declarations and named imports share the top precedence level: a conflict +between them is an error, so at most one candidate can exist at that level. + +Predeclared items rank lowest so that future WGSL spec revisions can add new +builtins without breaking existing shaders: any name already bound at a higher +level continues to resolve as before. Wildcard-imported names rank below user +declarations and named imports for the analogous reason: additions to a +`@!wildcardable` module won't silently change resolution at call sites that +already have a local or named binding for the same name. Wildcard imports bring +in only the imported module's top-level declarations, not package names. + ## Directives Under discussion, see: @@ -268,19 +494,19 @@ This only refers to the exact module that an element is in, and not any of the p Example: ```wgsl -​​​​// main.wesl: -​​​​import foo::bar; -​​​​fn main() { bar(); } - -​​​​// foo.wesl: -​​​​import zig::zag; -​​​​const_assert(1 > 0); // included in link because bar is used -​​​​fn bar() { } -​​​​fn miz() { zag() } - -​​​​// zig.wesl: -​​​​const_assert(2 < 0); // not included in link -​​​​fn zag() { } +// main.wesl: +import foo::bar; +fn main() { bar(); } + +// foo.wesl: +import zig::zag; +const_assert(1 > 0); // included in link because bar is used +fn bar() { } +fn miz() { zag() } + +// zig.wesl: +const_assert(2 < 0); // not included in link +fn zag() { } ``` Example diff --git a/ImportsDesign.md b/ImportsDesign.md new file mode 100644 index 0000000..1a395db --- /dev/null +++ b/ImportsDesign.md @@ -0,0 +1,92 @@ +# Imports Design + +This document records design decisions behind WESL's import system. The +normative spec lives in [Imports.md](Imports.md). + +## Why the `@!` module attribute form? + +`@!wildcardable` is module-level metadata. WESL will likely want module-level +annotations for other module-scoped features, and libraries and users will want +a place to attach their own metadata to a whole module. A general-purpose syntax +for module metadata avoids inventing one ad-hoc form per feature. + +`@!wildcardable` mirrors the item-level attribute convention (`@group`, +`@binding`, `@if`, `@diagnostic`, ...), but the `!` marks the attribute as +scoped to the whole module. Unlike an item attribute, it doesn't attach to a +following element, so a trailing `;` terminates it. + +Module attributes sit below the imports so that they can use imported +names (for example a hypothetical `@!play_version(2);`). + +See [`@!wildcardable` annotation](Imports.md#wildcardable-annotation) for the +normative spec. + +## Aren't wildcards an anti-pattern? + +Many language communities discourage wildcard imports. TypeScript, Go, Zig, and +Carbon disallow wildcards entirely or restrict them to narrow cases. Java and +Rust permit them syntactically but discourage broad use by convention; Rust's +`prelude` modules are one curated pattern in that style. The general concerns +are practical: + +- **Traceability.** Direct imports make it obvious where a name comes from. + Wildcards push that work onto the reader, the language server, or the + compiler's name-resolution diagnostics. +- **API stability.** Adding a public item to a wildcard-imported module can + conflict with downstream declarations or with other wildcard imports. Stacked + wildcards across a dependency tree can create conflicts the end user neither + caused nor can easily fix. + +The WESL environment adds further concerns: + +- **Cross-ecosystem publishing.** WESL libraries can be published into multiple + host ecosystems (npm, crates, etc.), and the language's stability rules have + to work for all of them. npm in particular treats minor/patch breakage as an + upstream bug, so wildcard-driven conflicts on additive package updates would + be read there as buggy packages, not as users accepting a WESL-specific + tradeoff. The defaults can't be split per-ecosystem; even libraries that + aren't actively cross-published inherit the same rules. +- **Mixed-language ownership.** In host applications, dependency updates are + often routine maintenance handled by someone other than the shader author. A + wildcard conflict can land on a teammate who did not cause it and may not be + best positioned to fix shader-side breakage. +- **Shader test coverage.** Shader test coverage is often thinner than + application-code coverage, and some failures are visual or runtime-dependent. + Fewer tests and WGSL's comparatively small type system mean that wildcard + conflicts are less likely to be caught at the moment a dependency is updated. +- **Single namespace.** WGSL has a single namespace for types and values, and no + namespace construct or object-style surface to limit the scope of wildcarded + names after import. There are fewer places for names to coexist harmlessly. + +These concerns motivate guardrails for WESL wildcard defaults. + +## Wildcards in WESL: when to allow, when to gate + +WESL keeps wildcards available because some libraries are designed to feel +pervasive. Game engines, test frameworks, and math libraries expect a +domain-specific API where prefixing every call with `test::expect::` or similar +would obscure the shader rather than help it. Concise import syntax matters even +where an IDE can autocomplete: not every editor has a language server, and long +import blocks add noise regardless of how they were typed. + +But the concerns in +[Aren't wildcards an anti-pattern?](#arent-wildcards-an-anti-pattern) still +apply, especially across package boundaries. WESL's defaults try to keep the +benefits while limiting the risk: + +- **Not every public module suits wildcards.** Modules with a fast-growing API + or with generic names (`Buffer`, `Result`) are fine to import by name but + hazardous to wildcard. +- **Authors can signal which modules are curated for wildcards.** An explicit + `@!wildcardable` marker lets library authors tell consumers (and tools) which + modules they've designed for wildcard use. It also gives tooling a hook for + lints around generic names, builtin shadowing, churn-prone additions, etc. +- **Defaults shape the ecosystem.** Red/yellow squiggles and linter messages + teach safe wildcard practice to new and part-time shader authors more reliably + than community blogs or documentation. +- **Advanced users are not blocked.** Within a package, wildcard imports are + unrestricted; externally, wildcard-importing a non-`@!wildcardable` module is + possible via + [standard diagnostic controls](Imports.md#suppressible-diagnostics). The + default tunes the path of least resistance, but doesn't block users who + intentionally accept the risk.