Improve naga_oil parity coverage

Author: Milky2018

README.mbt.md

@@ -147,6 +147,7 @@ test "README: compose registered modules" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let composed : String = composer.compose_wgsl(
     "sprite_render/mesh2d/mesh2d.wgsl", compose_options,
@@ -194,6 +195,7 @@ test "README: bulk registry and relative imports" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let composed : String = composer.compose_wgsl(
     "shaders/effects/main.wgsl", compose_options,
@@ -264,6 +266,7 @@ test "README: scan source tree" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let composed : String = composer.compose_wgsl(
     "effects/main.wgsl", compose_options,
@@ -324,6 +327,7 @@ test "README: export single WGSL file" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let export_options : @moon_wgsl.WgslExportOptions = { root_items: ["shade"] }
   let exported : @moon_wgsl.WgslExportOutput = composer.export_wgsl_with_options(
@@ -367,6 +371,7 @@ test "README: build source catalog" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let catalog : Array[@moon_wgsl.WgslSourceCatalogEntry] = composer.build_wgsl_source_catalog(
     compose_options,
@@ -410,6 +415,7 @@ test "README: source-level redirects" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let export_options : @moon_wgsl.WgslExportOptions = { root_items: ["shade"] }
   let exported : @moon_wgsl.WgslExportOutput = composer.export_wgsl_with_options(
@@ -514,6 +520,8 @@ Important public data structures:
 - `WgslDirectives`
 - `WgslSourceFile`
 - `WgslComposeOptions`
+  Holds root compose settings: asset base, shader defs, value defs, symbol
+  redirects, and root-only `additional_imports`.
 - `WgslSymbolRedirect`
 - `WgslExportOptions`
 - `WgslExportOutput`

README.md

@@ -147,6 +147,7 @@ test "README: compose registered modules" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let composed : String = composer.compose_wgsl(
     "sprite_render/mesh2d/mesh2d.wgsl",
@@ -194,6 +195,7 @@ test "README: bulk registry and relative imports" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let composed : String = composer.compose_wgsl(
     "shaders/effects/main.wgsl",
@@ -261,6 +263,7 @@ test "README: scan source tree" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let composed : String = composer.compose_wgsl(
     "effects/main.wgsl",
@@ -320,6 +323,7 @@ test "README: export single WGSL file" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let export_options : @moon_wgsl.WgslExportOptions = {
     root_items: ["shade"],
@@ -367,6 +371,7 @@ test "README: build source catalog" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let catalog : Array[@moon_wgsl.WgslSourceCatalogEntry] =
     composer.build_wgsl_source_catalog(compose_options)
@@ -408,6 +413,7 @@ test "README: source-level redirects" {
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
   let export_options : @moon_wgsl.WgslExportOptions = {
     root_items: ["shade"],
@@ -518,6 +524,8 @@ Important public data structures:
 - `WgslDirectives`
 - `WgslSourceFile`
 - `WgslComposeOptions`
+  Holds root compose settings: asset base, shader defs, value defs, symbol
+  redirects, and root-only `additional_imports`.
 - `WgslSymbolRedirect`
 - `WgslExportOptions`
 - `WgslExportOutput`

composer.mbt

@@ -85,6 +85,48 @@ fn copy_import_definitions(
   copied
 }
 
+///|
+fn serialize_wgsl_import_definition(
+  import_definition : ImportDefinition,
+) -> String {
+  let import_path = import_definition.import_path.trim().to_string()
+  if import_path == "" {
+    return ""
+  }
+  let items : Array[String] = []
+  for item in import_definition.items {
+    let trimmed_item = item.trim().to_string()
+    if trimmed_item != "" {
+      items.push(trimmed_item)
+    }
+  }
+  if items.length() == 0 {
+    "#import \{import_path}"
+  } else {
+    let item_list = items.join(", ")
+    "#import \{import_path} \{item_list}"
+  }
+}
+
+///|
+fn prepend_wgsl_additional_imports(
+  source : String,
+  additional_imports : Array[ImportDefinition],
+) -> String {
+  let lines : Array[String] = []
+  for import_definition in additional_imports {
+    let line = serialize_wgsl_import_definition(import_definition)
+    if line != "" {
+      lines.push(line)
+    }
+  }
+  if lines.length() == 0 {
+    return source
+  }
+  let import_block = lines.join("\n")
+  "\{import_block}\n\{source}"
+}
+
 ///|
 fn copy_bool_defs(
   defs : @hashmap.HashMap[String, Bool],
@@ -126,6 +168,7 @@ priv struct WgslComposeSession {
   value_defines : @hashmap.HashMap[String, Int]
   modules : @hashmap.HashMap[String, String]
   redirects : Array[WgslSymbolRedirect]
+  additional_imports : Array[ImportDefinition]
   visited : @hashmap.HashMap[String, Bool]
   imported_item_names : @hashmap.HashMap[String, String]
   active_rel_paths : Array[String]
@@ -255,6 +298,7 @@ fn Composer::new_wgsl_compose_session(
     value_defines: copy_int_defs(options.value_defines),
     modules: self.registry.copy_import_module_paths(),
     redirects: options.redirects.copy(),
+    additional_imports: copy_import_definitions(options.additional_imports),
     visited: @hashmap.HashMap::new(),
     imported_item_names: @hashmap.HashMap::new(),
     active_rel_paths: [],
@@ -676,9 +720,16 @@ pub fn Composer::add_composable_module(
     effective_defs.remove(def_name)
   }
 
+  let source_with_additional_imports = prepend_wgsl_additional_imports(
+    desc.source,
+    additional_imports,
+  )
   let definition = ComposableModuleDefinition::{
     name: module_name,
-    sanitized_source: metadata.cleaned_source,
+    sanitized_source: prepend_wgsl_additional_imports(
+      metadata.cleaned_source,
+      additional_imports,
+    ),
     language: desc.language,
     file_path: desc.file_path,
     shader_defs,
@@ -691,7 +742,7 @@ pub fn Composer::add_composable_module(
   ignore(
     self.registry.register_source(
       registry_rel_path,
-      desc.source,
+      source_with_additional_imports,
       Some(module_name),
     ),
   )
@@ -1266,7 +1317,7 @@ fn Composer::preprocess_wgsl_source_with_path(
 }
 
 ///|
-fn Composer::load_wgsl_preprocessed_into_session(
+fn Composer::load_root_wgsl_preprocessed_into_session(
   self : Composer,
   rel : String,
   session : WgslComposeSession,
@@ -1286,7 +1337,9 @@ fn Composer::load_wgsl_preprocessed_into_session(
   session.resolved_source_files.set(normalized_rel, source)
   session.active_rel_paths.push(normalized_rel)
   let composed = self.preprocess_wgsl_source_with_path(
-    normalized_rel, source, session,
+    normalized_rel,
+    prepend_wgsl_additional_imports(source, session.additional_imports),
+    session,
   )
   session.active_rel_paths.pop() |> ignore
   composed
@@ -1299,7 +1352,7 @@ pub fn Composer::compose_wgsl(
   options : WgslComposeOptions,
 ) -> String raise ComposerError {
   let session = self.new_wgsl_compose_session(options)
-  self.load_wgsl_preprocessed_into_session(rel, session)
+  self.load_root_wgsl_preprocessed_into_session(rel, session)
 }
 
 ///|
@@ -1309,7 +1362,11 @@ pub fn Composer::compose_wgsl_source(
   options : WgslComposeOptions,
 ) -> String raise ComposerError {
   let session = self.new_wgsl_compose_session(options)
-  self.preprocess_wgsl_source_with_path("", source, session)
+  self.preprocess_wgsl_source_with_path(
+    "",
+    prepend_wgsl_additional_imports(source, session.additional_imports),
+    session,
+  )
 }
 
 ///|
@@ -1327,5 +1384,6 @@ pub fn Composer::load_wgsl_from_assets_base_required(
     defines: @hashmap.HashMap::new(),
     value_defines: default_wgsl_value_defines(),
     redirects: [],
+    additional_imports: [],
   })
 }

composer_registry_test.mbt

@@ -160,6 +160,7 @@ test "naga_oil: add_composable_module resolves imports from the composer registr
     defines: @hashmap.HashMap::new(),
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects: [],
+    additional_imports: [],
   }) catch {
     err =>
       abort(

composer_test.mbt

@@ -33,6 +33,7 @@ fn composer_test_compose_options(
     defines,
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects,
+    additional_imports: [],
   }
 }
 
@@ -334,6 +335,7 @@ test "naga_oil: composer local registry can compose without global registry stat
     defines: empty_bool_defines(),
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects: [],
+    additional_imports: [],
   }) catch {
     err =>
       abort(
@@ -383,6 +385,7 @@ test "naga_oil: add_composable_module feeds the composer compose path" {
     defines: empty_bool_defines(),
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects: [],
+    additional_imports: [],
   }) catch {
     err =>
       abort(
@@ -394,6 +397,58 @@ test "naga_oil: add_composable_module feeds the composer compose path" {
   debug_inspect(preprocessed.contains("return PI_2;"), content="true")
 }
 
+///|
+test "naga_oil: add_composable_module applies descriptor additional imports" {
+  @moon_wgsl.clear_registered_wgsl_source_registry()
+  let composer = @moon_wgsl.Composer::default()
+  composer.clear_registered_wgsl_source_registry()
+  ignore(
+    composer.add_composable_module({
+      source: "#define_import_path plugin\nfn external_scale() -> f32 {\n  return 2.0;\n}\n",
+      file_path: "shaders/demo/plugin.wgsl",
+      language: @moon_wgsl.ShaderLanguage::Wgsl,
+      as_name: None,
+      additional_imports: [],
+      shader_defs: @hashmap.HashMap::new(),
+    }),
+  ) catch {
+    err =>
+      abort("expected plugin module registration success: \{err.message()}")
+  }
+  ignore(
+    composer.add_composable_module({
+      source: "#define_import_path demo::main\nfn demo() -> f32 {\n  return plugin::external_scale();\n}\n",
+      file_path: "shaders/demo/main.wgsl",
+      language: @moon_wgsl.ShaderLanguage::Wgsl,
+      as_name: None,
+      additional_imports: [{ import_path: "plugin", items: [] }],
+      shader_defs: @hashmap.HashMap::new(),
+    }),
+  ) catch {
+    err => abort("expected main module registration success: \{err.message()}")
+  }
+  let preprocessed = composer.compose_wgsl("shaders/demo/main.wgsl", {
+    assets_base: "",
+    defines: empty_bool_defines(),
+    value_defines: @moon_wgsl.default_wgsl_value_defines(),
+    redirects: [],
+    additional_imports: [],
+  }) catch {
+    err =>
+      abort(
+        "expected additional-import-backed preprocess success: \{err.message()}",
+      )
+  }
+  debug_inspect(
+    preprocessed.contains("fn plugin__external_scale"),
+    content="true",
+  )
+  debug_inspect(
+    preprocessed.contains("plugin__external_scale()"),
+    content="true",
+  )
+}
+
 ///|
 test "naga_oil: composer can register a WGSL source tree from moonbitlang/x/fs" {
   @moon_wgsl.clear_registered_wgsl_source_registry()
@@ -410,6 +465,7 @@ test "naga_oil: composer can register a WGSL source tree from moonbitlang/x/fs"
     defines: empty_bool_defines(),
     value_defines: @moon_wgsl.default_wgsl_value_defines(),
     redirects: [],
+    additional_imports: [],
   }) catch {
     err =>
       abort("expected source-tree-backed preprocess success: \{err.message()}")

docs/moon_wgsl-issue-tracker.md

@@ -1,6 +1,6 @@
 # moon_wgsl Issue Tracker
 
-Last updated: 2026-04-15
+Last updated: 2026-04-29
 
 ## Status Legend
 
@@ -32,7 +32,19 @@ Last updated: 2026-04-15
 | `WGSL-017` | `moon ide analyze` architecture audit | Instance-scoped composition and package-level compatibility helpers still rely on raw registry maps instead of one explicit registry abstraction, so the global registry boundary remains implicit in core code. | `DONE` | Added a shared internal `WgslSourceRegistry` abstraction and moved both `Composer` and package-level compatibility helpers onto it, so global helpers now wrap an explicit singleton registry instead of being the core state model. Verified with `moon fmt && moon test` on 2026-04-15 (`66/66` passing), including a new regression that composer snapshots stay isolated from later global mutations. |
 | `WGSL-018` | `moon ide analyze` architecture audit | WGSL declaration parsing and dependency analysis are split across composer and export, so item extraction, source catalogs, and tree-shaking can drift as the language surface grows. | `DONE` | Extracted shared declaration-graph and dependency-analysis logic into `wgsl_analysis.mbt`, and routed compose-time item extraction plus export-time tree-shaking/source-map generation through the same helpers. Verified with `moon fmt && moon test` on 2026-04-15 (`66/66` passing), including a new regression that compose/export preserve the same annotated global dependencies. |
 | `WGSL-019` | `moon ide analyze` architecture audit | `composer.mbt` still owns most import-planning and namespace-rewrite helpers, leaving the primary orchestration file too large and too sticky for further features. | `DONE` | Split composer-specific import planning, namespace resolution, and alias-renaming helpers into `composer_imports.mbt`, leaving `composer.mbt` focused on public API, session setup, condition handling, and recursive orchestration. Verified with `moon fmt && moon test` on 2026-04-15 (`66/66` passing). |
+| `WGSL-020` | GitHub issue #2 | Bevy-style const declarations with trailing line comments could be merged into the following declaration and then disappear from alias rewrites/tree-shaking. | `DONE` | Fixed by treating line-comment-terminated declarations as complete declaration boundaries. Released in `0.1.3` and verified with `moon test` on 2026-04-29. |
+| `WGSL-021` | GitHub issue #3 | Mixed Bevy PBR import graphs exposed missing import-only entry preservation and nested alias/type rewrites for source-level composition. | `DONE` | Fixed by preserving import-only WGSL entry items and expanding the Bevy mixed full/item import regression suite. Released across `0.1.4` and `0.1.5`; verified with `moon test` on 2026-04-29. |
+| `WGSL-022` | GitHub issue #4 | Repeated full-module imports under a nested alias skipped cached alias redirects, leaving expressions such as `view_bindings::view` unresolved. | `DONE` | Fixed by reusing cached alias redirects when a full-module import has already been visited. Released in `0.1.6`; verified with `moon test` on 2026-04-29 (`85/85` passing). |
+| `WGSL-023` | Upstream naga_oil parity audit | The upstream compose test surface was only partially represented in local tests and not tracked as an explicit coverage matrix. | `DONE` | Added `docs/naga_oil-parity.md` with the upstream compose test/fixture matrix, source-level compatibility boundary, blocked cases, and the next architecture priorities. |
+| `WGSL-024` | Architecture review | Import syntax parsing/planning is still split between preprocessor metadata parsing and composer/module-graph import target parsing, so alias/group syntax can drift between APIs. | `TODO` | Consolidate `parse_imports` and `collect_wgsl_import_targets` around one canonical import AST/parser, then route both metadata output and recursive compose planning through that representation. |
+| `WGSL-025` | Upstream `additional_import` parity | Descriptor-level `additional_imports` exists, but source-level `compose_wgsl` / `export_wgsl_with_options` has no stable root-request API for injecting additional imports. | `DONE` | Added root-only `WgslComposeOptions.additional_imports`, wired descriptor-level additional imports into registered composable module source, and added compose/export regressions based on the upstream `add_imports` fixture shape. Full `virtual`/`override` overlay semantics remain part of `WGSL-012` because they require Naga. |
+| `WGSL-026` | Upstream `bad_identifiers` parity | Naga can sanitize invalid/reserved identifiers during IR writeback, but this source-level library currently lacks a defined identifier-sanitization layer. | `TODO` | Implement a limited source-level sanitizer for declarations/references the local analyzer can identify, and document that full parser/IR-equivalent sanitization remains outside source-only scope. |
+| `WGSL-027` | Upstream `invalid_override` parity | Redirect/override-style source-level APIs do not yet diagnose redirects that never match a local declaration, while upstream catches invalid override cases through Naga. | `TODO` | Add explicit redirect diagnostics, likely through export diagnostics or a checked compose API, without pretending to validate full Naga `virtual`/`override` semantics. |
+| `WGSL-028` | Upstream `test_shader` parity | The local parity corpus lacks a simple compute shader smoke test corresponding to upstream `compute_test.wgsl`. | `DONE` | Added `testdata/upstream_compose/compute_test` and an export smoke test that preserves the compute entry point plus imported module dependency. Verified with `moon test` on 2026-04-29. |
 
 ## Current work queue
 
-- No active `TODO` or `IN_PROGRESS` items. `WGSL-012` remains intentionally `BLOCKED` on true Naga/runtime-backed parity coverage.
+- `WGSL-024`: consolidate import parsing and planning around one canonical import AST.
+- `WGSL-026`: add a documented source-level identifier sanitizer where local parsing is sufficient.
+- `WGSL-027`: add checked redirect diagnostics for source-level override/redirect usage.
+- `WGSL-012` remains intentionally `BLOCKED` on true Naga/runtime-backed parity coverage.