@galacean/engine-shader-compiler 2.0.0-alpha.52 → 2.0.0-alpha.53

package/README.md

@@ -7,6 +7,7 @@ npm install @galacean/engine-shader-compiler
 ## Usage
 
 ```typescript
+import { Shader, ShaderFactory, WebGLEngine } from "@galacean/engine";
 import { ShaderCompiler } from "@galacean/engine-shader-compiler";
 
 // Create shader compiler
@@ -20,20 +21,55 @@ const engine = await WebGLEngine.create({ canvas: "canvas", shaderCompiler });
 // Create shader by galacean shader code directly
 const shader = Shader.create(galaceanShaderCode);
 
+// Register project chunks before creating shaders that include them
+ShaderFactory.registerInclude("ShaderLibrary/UserCommon.glsl", userCommonSource);
+const shaderWithIncludes = Shader.create(galaceanShaderCodeWithIncludes);
+
 .......
 
 // Run engine
 engine.run()
 ```
 
-There are two versions of the shader compiler: `Release` and `Verbose`. The `Verbose` version offers more user-friendly diagnostic information for debugging shader compilation errors, while the Release version provides superior performance.
+Authoring diagnostics are provided separately by `@galacean/engine-shader-analyzer`; the runtime compiler does not include analyzer diagnostics.
+
+`Shader.create()` never needs a filesystem path. Include paths are resolved against logical keys registered through `ShaderFactory.registerInclude()`:
+
+| Registered key | Current logical shader | `#include` | Result |
+| --- | --- | --- | --- |
+| `User/Math.glsl` | no loader metadata | `"User/Math.glsl"` or `"/User/Math.glsl"` | `User/Math.glsl` |
+| `User/Math.glsl` | no loader metadata | `"./User/Math.glsl"` | `User/Math.glsl` |
+| `Assets/Shaders/Math.glsl` | `Assets/Shaders/PBR.shader` | `"./Math.glsl"` | `Assets/Shaders/Math.glsl` |
+| `Assets/Shared/Math.glsl` | `Assets/Shaders/PBR.shader` | `"../Shared/Math.glsl"` | `Assets/Shared/Math.glsl` |
+
+The asset loader supplies the current logical shader location internally. Moving a shader folder remains valid when the shader asset and its registered include keys move together. Disk paths do not define the logical root.
 
-you can use `Verbose` version by import:
+## Precompile
 
-```ts
-import { ShaderCompiler } from "@galacean/engine-shader-compiler/verbose";
+Import `ShaderPrecompiler` from `@galacean/engine-shader-compiler/precompile` to generate `.shaderc` data in memory. The CLI writes this data to files.
+
+Compile a directory tree to `.shaderc` artifacts:
+
+```sh
+shader-compiler-precompile Assets/Shaders build/shaders --clean --emit-index
 ```
 
+The input directory is the logical registry root. A shader at `PBR/Root.shader` resolves `./Common.glsl` to `PBR/Common.glsl`; `/Shared/Math.glsl` and `Shared/Math.glsl` both resolve to `Shared/Math.glsl` below the input root. Compilation failures exit non-zero and prevent Rollup builds using the plugin from succeeding.
+
+Inherited helper calls use forward declarations while overriding function bodies keep their original macro context. GLES can move ordinary struct signature dependencies ahead of those declarations. If this requires moving a type with conditional fields, macro-dependent array bounds, or across macro/precision changes, code generation reports `UnsupportedForwardDeclaration` with source context and rejects the pass. This is a GLES backend limitation; authoring analysis can still accept the source, and future backends can provide their own declaration ordering.
+
+GLES also moves replacement uniforms, struct declarations, and their enclosing conditions ahead of inherited references when their macro and precision context remains unchanged. Mutually exclusive functions that need different signatures at a shared forward-declaration site, and declarations that cross a macro or precision change, report `UnsupportedForwardDeclaration`.
+
+When static inheritance coverage remains unknown, the instruction stream selects declarations using the actual macro state at their original source positions. The active declaration in the narrowest ShaderLab scope wins; macro directives still execute in source order. This applies to functions, uniforms, ordinary structs, and generated IO declarations. Forward declarations and moved types retain the ownership of their original declarations.
+
+`ShaderCompiler.generate()` returns these variant-selectable instruction streams alongside unselected `vertex` and `fragment` text for inspection. The text views alone do not contain deferred ownership and must not be re-encoded as a substitute for the returned instructions. Engine `ShaderPass` consumes the instructions to produce final GLSL. `.shaderc` preserves them as JSON; use matching compiler and engine versions when shipping artifacts. Existing instruction opcodes retain their numeric values.
+
+## Declaration dependencies
+
+The neutral parser records exact struct dependencies at each type occurrence, including possible macro replacement types. Macro-dependent types retain conservative semantic typing; their dependency identities do not select a runtime macro variant. GLES consumes these facts while generating reachable declarations, including helper signatures and nested struct fields, without a second declaration-tree scan.
+
+Global emission is deduplicated by declaration identity. Same-named structs, functions, and uniforms in different macro branches remain separate candidates, retain their original guards and positions, and can discover further dependencies during generation. Backend-owned return lowering preserves control flow by emitting a block when a single return becomes an output assignment followed by an exit.
+
 ## CFG Grammar conflict detection
 
 The Galacean shader syntax is defined using Context-Free Grammar (CFG) and is documented within the `\*.y` file. When modifications to the shader syntax are required, it is recommended to make changes to the existing CFG syntax file, and employ [Bison](https://www.gnu.org/software/bison/manual/bison.html) to detect any potential grammar conflicts.

package/bundler/cli.js

@@ -1,20 +1,48 @@
 #!/usr/bin/env node
-import { parseArgs } from 'node:util';
-import fs from 'node:fs';
-import path from 'node:path';
-import { createRequire } from 'node:module';
-import { pathToFileURL } from 'node:url';
+'use strict';
 
-/** Normalize to forward slashes (Windows uses `\`; downstream regex/keys assume `/`). */ function normalizePath(p) {
-    return p.split(path.sep).join("/");
+var node_util = require('node:util');
+var fs = require('node:fs');
+var path = require('node:path');
+var node_module = require('node:module');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n["default"] = e;
+  return Object.freeze(n);
+}
+
+var fs__default = /*#__PURE__*/_interopDefaultLegacy(fs);
+var path__default = /*#__PURE__*/_interopDefaultLegacy(path);
+
+/**
+ * Converts a filesystem path to the slash-separated form used by shader asset keys.
+ * @param p - Filesystem path.
+ * @returns Slash-separated path.
+ */ function normalizePath(p) {
+    return p.split(path__default["default"].sep).join("/");
 }
 /** Recursively find all files with a given extension. */ function findFiles(dir, ext) {
     const results = [];
-    if (!fs.existsSync(dir)) return results;
-    for (const entry of fs.readdirSync(dir, {
+    if (!fs__default["default"].existsSync(dir)) return results;
+    for (const entry of fs__default["default"].readdirSync(dir, {
         withFileTypes: true
     })){
-        const fullPath = path.join(dir, entry.name);
+        const fullPath = path__default["default"].join(dir, entry.name);
         if (entry.isDirectory()) {
             results.push(...findFiles(fullPath, ext));
         } else if (entry.name.endsWith(ext)) {
@@ -37,13 +65,17 @@ import { pathToFileURL } from 'node:url';
 }
 /** Remove empty parent directories upward from `startDir` until `stopDir` is hit. */ function pruneEmptyDirs(startDir, stopDir) {
     let dir = startDir;
-    while(dir !== stopDir && fs.existsSync(dir) && fs.readdirSync(dir).length === 0){
-        fs.rmdirSync(dir);
-        dir = path.dirname(dir);
+    while(dir !== stopDir && fs__default["default"].existsSync(dir) && fs__default["default"].readdirSync(dir).length === 0){
+        fs__default["default"].rmdirSync(dir);
+        dir = path__default["default"].dirname(dir);
     }
 }
-// One-shot mode exits non-zero on failure so CI breaks; watch mode logs and keeps running.
-async function precompile(options) {
+/**
+ * Precompiles shaders once or starts incremental watch mode.
+ * @param options - Source, output, cleanup, watch, and artifact-generation options.
+ * @returns After a one-shot compile finishes or a watch has been installed.
+ * @throws Error when a one-shot compile has failures or the source tree is invalid.
+ */ async function precompile(options) {
     const { failed } = await runFull(options);
     if (options.watch) {
         await startWatcher(options);
@@ -51,17 +83,22 @@ async function precompile(options) {
     }
     console.log("[shader-compiler-bundler] Done.");
     if (failed > 0) {
-        process.exit(1);
+        throw new Error(`${failed} shader(s) failed to precompile.`);
     }
 }
-async function runFull(options) {
-    const inputDir = path.resolve(options.input);
-    const outputDir = path.resolve(options.output);
+/**
+ * Precompiles the current shader source tree once.
+ * @param options - Source, output, cleanup, and artifact-generation options.
+ * @returns An object containing the number of shader sources that failed to compile.
+ * @throws Error when the input tree or an explicitly selected source is invalid.
+ */ async function runFull(options) {
+    const inputDir = path__default["default"].resolve(options.input);
+    const outputDir = path__default["default"].resolve(options.output);
     const platformTarget = options.platformTarget ?? 0;
-    if (!fs.existsSync(inputDir)) {
+    if (!fs__default["default"].existsSync(inputDir)) {
         throw new Error(`Input directory does not exist: ${inputDir}`);
     }
-    fs.mkdirSync(outputDir, {
+    fs__default["default"].mkdirSync(outputDir, {
         recursive: true
     });
     // Emit source indexes before compile so collectIncludeMap can resolve the freshly-built sources.
@@ -69,22 +106,13 @@ async function runFull(options) {
         emitSources(inputDir);
     }
     const shaderCompiler = await loadShaderCompiler();
-    shaderCompiler._setIncludeMap(await collectIncludeMap(inputDir));
+    shaderCompiler.setIncludeMap(await collectIncludeMap(inputDir));
     let failed = 0;
     if (options.only) {
-        const target = path.resolve(options.only);
+        const target = path__default["default"].resolve(options.only);
         if (!compileSingle(shaderCompiler, target, inputDir, outputDir, platformTarget)) failed++;
     } else {
-        const shaderFiles = findFiles(inputDir, ".shader");
-        console.log(`[shader-compiler-bundler] Precompiling ${shaderFiles.length} shader(s)...`);
-        for (const file of shaderFiles){
-            if (!compileSingle(shaderCompiler, file, inputDir, outputDir, platformTarget)) failed++;
-        }
-        if (options.clean) {
-            const removed = cleanOrphanedBundles(shaderFiles, inputDir, outputDir);
-            if (removed > 0) console.log(`[shader-compiler-bundler] Cleaned ${removed} orphaned .shaderc file(s).`);
-        }
-        if (failed > 0) console.warn(`[shader-compiler-bundler] ${failed} shader(s) failed to precompile.`);
+        failed = compileAll(shaderCompiler, inputDir, outputDir, platformTarget, options.clean);
     }
     if (options.emitIndex) {
         emitIndex(outputDir);
@@ -93,26 +121,40 @@ async function runFull(options) {
         failed
     };
 }
-async function startWatcher(options) {
-    const inputDir = path.resolve(options.input);
-    const outputDir = path.resolve(options.output);
+/**
+ * Watches one shader source tree and serializes incremental rebuilds.
+ * @param options - Source, output, cleanup, and artifact-generation options.
+ * @returns Once the filesystem watcher has been installed.
+ * @throws Error when the initial include registry cannot be loaded.
+ */ async function startWatcher(options) {
+    const inputDir = path__default["default"].resolve(options.input);
+    const outputDir = path__default["default"].resolve(options.output);
     const platformTarget = options.platformTarget ?? 0;
+    if (!fs__default["default"].existsSync(inputDir)) {
+        throw new Error(`Input directory does not exist: ${inputDir}`);
+    }
+    fs__default["default"].mkdirSync(outputDir, {
+        recursive: true
+    });
     const shaderCompiler = await loadShaderCompiler();
-    shaderCompiler._setIncludeMap(await collectIncludeMap(inputDir));
+    shaderCompiler.setIncludeMap(await collectIncludeMap(inputDir));
     // .glsl change → full recompile (can't cheaply track include graphs).
     // .shader change → single-file recompile.
     const handleInputChange = async (filename)=>{
         if (!filename) return;
         const norm = normalizePath(filename);
-        const fullPath = path.join(inputDir, filename);
+        const fullPath = path__default["default"].join(inputDir, filename);
         if (norm.endsWith(".glsl")) {
             console.log(`[shader-compiler-bundler] Include changed (${norm}), full recompile...`);
-            shaderCompiler._setIncludeMap(await collectIncludeMap(inputDir));
-            runFull(options).catch((e)=>console.error(e));
+            if (options.emitSources) emitSources(inputDir);
+            shaderCompiler.setIncludeMap(await collectIncludeMap(inputDir));
+            const failed = compileAll(shaderCompiler, inputDir, outputDir, platformTarget, options.clean);
+            if (options.emitIndex) emitIndex(outputDir);
+            if (failed > 0) console.error(`[shader-compiler-bundler] ${failed} shader(s) failed to precompile.`);
             return;
         }
         if (!norm.endsWith(".shader")) return;
-        if (!fs.existsSync(fullPath)) {
+        if (!fs__default["default"].existsSync(fullPath)) {
             removeBundleFor(fullPath, inputDir, outputDir);
         } else {
             compileSingle(shaderCompiler, fullPath, inputDir, outputDir, platformTarget);
@@ -121,69 +163,93 @@ async function startWatcher(options) {
         if (options.emitIndex) emitIndex(outputDir);
     };
     console.log(`[shader-compiler-bundler] Watching ${inputDir} ...`);
-    fs.watch(inputDir, {
+    let changeQueue = Promise.resolve();
+    fs__default["default"].watch(inputDir, {
         recursive: true
     }, (_event, filename)=>{
-        handleInputChange(filename).catch((e)=>console.error(e));
+        changeQueue = changeQueue.then(()=>handleInputChange(filename)).catch((e)=>console.error(e));
     });
 }
+function compileAll(shaderCompiler, inputDir, outputDir, platformTarget, clean) {
+    const shaderFiles = findFiles(inputDir, ".shader");
+    console.log(`[shader-compiler-bundler] Precompiling ${shaderFiles.length} shader(s)...`);
+    let failed = 0;
+    for (const file of shaderFiles){
+        if (!compileSingle(shaderCompiler, file, inputDir, outputDir, platformTarget)) failed++;
+    }
+    if (clean) {
+        const removed = cleanOrphanedBundles(shaderFiles, inputDir, outputDir);
+        if (removed > 0) console.log(`[shader-compiler-bundler] Cleaned ${removed} orphaned .shaderc file(s).`);
+    }
+    if (failed > 0) console.warn(`[shader-compiler-bundler] ${failed} shader(s) failed to precompile.`);
+    return failed;
+}
 async function loadShaderCompiler() {
-    // @ts-ignore — `../dist/main.js` is the compiled runtime entry; no .ts source.
-    // Bundler ships at `<pkg>/bundler/` and the runtime at `<pkg>/dist/`, so this
-    // resolves to the sibling `dist/` from `bundler/cli.js` at runtime.
-    const mod = await import('../dist/main.js');
-    const instance = new mod.ShaderCompiler();
-    if (typeof instance._precompile !== "function") {
-        throw new Error("ShaderCompiler._precompile is not available; rebuild @galacean/engine-shader-compiler first.");
+    const mod = await (process.env.GALACEAN_SHADER_COMPILER_BOOTSTRAP === "true" ? importBootstrapPrecompiler() : importReleasePrecompiler());
+    const instance = new mod.ShaderPrecompiler();
+    if (typeof instance.precompile !== "function") {
+        throw new Error("ShaderPrecompiler is unavailable; rebuild @galacean/engine-shader-compiler first.");
     }
     return instance;
 }
+async function importBootstrapPrecompiler() {
+    // @ts-expect-error generated repo-local runtime has no declaration file
+    return Promise.resolve().then(function () { return /*#__PURE__*/_interopNamespace(require('../.bootstrap/main.js')); });
+}
+async function importReleasePrecompiler() {
+    // @ts-expect-error generated Node-only runtime has no declaration file
+    return Promise.resolve().then(function () { return /*#__PURE__*/_interopNamespace(require('../dist/precompile.main.js')); });
+}
 // Local .glsl come from inputDir; standard library comes from
 // `@galacean/engine-shader/sources` with a sibling-dir fallback for engine self-build cold-start.
 async function collectIncludeMap(inputDir) {
-    const map = {};
+    const map = Object.create(null);
     for (const file of findFiles(inputDir, ".glsl")){
-        const relPath = normalizePath(path.relative(inputDir, file));
-        map[relPath] = fs.readFileSync(file, "utf-8");
+        const relPath = normalizePath(path__default["default"].relative(inputDir, file));
+        addIncludeSource(map, relPath, fs__default["default"].readFileSync(file, "utf-8"));
     }
-    let usedRelease = false;
     // Resolve from inputDir's node_modules so consumers without transitive linkage to shader-compiler can still find it.
+    const requireFromInput = node_module.createRequire(path__default["default"].join(inputDir, "package.json"));
+    let sourcesPath;
     try {
-        const requireFromInput = createRequire(path.join(inputDir, "package.json"));
-        const sourcesPath = requireFromInput.resolve("@galacean/engine-shader/sources");
-        const { shaderLibrary } = await import(pathToFileURL(sourcesPath).href);
+        sourcesPath = requireFromInput.resolve("@galacean/engine-shader/sources");
+    } catch (error) {
+        if (error.code !== "MODULE_NOT_FOUND") throw error;
+    }
+    if (sourcesPath) {
+        const { shaderLibrary } = requireFromInput(sourcesPath);
         for (const { source, path: chunkPath } of shaderLibrary){
-            map[chunkPath] = source;
+            addIncludeSource(map, chunkPath, source);
         }
-        usedRelease = true;
-    } catch  {
-    // engine self-build cold-start: dist/sources.* not yet built; use sibling source.
-    }
-    if (!usedRelease) {
-        const siblingLibrary = path.join(path.dirname(inputDir), "ShaderLibrary");
-        if (fs.existsSync(siblingLibrary)) {
+    } else {
+        // Engine self-build cold-start has no generated sources entry yet.
+        const siblingLibrary = path__default["default"].join(path__default["default"].dirname(inputDir), "ShaderLibrary");
+        if (fs__default["default"].existsSync(siblingLibrary)) {
             for (const file of findFiles(siblingLibrary, ".glsl")){
-                const rel = normalizePath(path.relative(siblingLibrary, file));
-                map[`ShaderLibrary/${rel}`] = fs.readFileSync(file, "utf-8");
+                const rel = normalizePath(path__default["default"].relative(siblingLibrary, file));
+                addIncludeSource(map, `ShaderLibrary/${rel}`, fs__default["default"].readFileSync(file, "utf-8"));
             }
         }
     }
     return map;
 }
-// Mirrors `ShaderPass._shaderRootPath` in engine; inlined to keep bundler engine-free.
-const SHADER_ROOT_PATH = "shaders://root/";
+function addIncludeSource(map, key, source) {
+    if (Object.prototype.hasOwnProperty.call(map, key)) {
+        throw new Error(`Shader include "${key}" is registered more than once.`);
+    }
+    map[key] = source;
+}
 function compileSingle(shaderCompiler, shaderPath, inputDir, outputDir, platformTarget) {
-    const source = fs.readFileSync(shaderPath, "utf-8");
-    const relativePath = normalizePath(path.relative(inputDir, shaderPath));
+    const relativePath = shaderSourceRelativePath(shaderPath, inputDir);
+    const source = fs__default["default"].readFileSync(shaderPath, "utf-8");
     const bundleRelative = relativePath.replace(/\.shader$/, ".shaderc");
-    const bundlePath = path.join(outputDir, bundleRelative);
-    const basePathForIncludeKey = new URL(relativePath, SHADER_ROOT_PATH).href;
-    fs.mkdirSync(path.dirname(bundlePath), {
+    const bundlePath = path__default["default"].join(outputDir, bundleRelative);
+    fs__default["default"].mkdirSync(path__default["default"].dirname(bundlePath), {
         recursive: true
     });
     try {
-        const precompiled = shaderCompiler._precompile(source, platformTarget, basePathForIncludeKey);
-        fs.writeFileSync(bundlePath, JSON.stringify(precompiled));
+        const precompiled = shaderCompiler.precompile(source, platformTarget, relativePath);
+        fs__default["default"].writeFileSync(bundlePath, JSON.stringify(precompiled));
         console.log(`  ${relativePath} -> ${bundleRelative}`);
         return true;
     } catch (e) {
@@ -192,17 +258,24 @@ function compileSingle(shaderCompiler, shaderPath, inputDir, outputDir, platform
         return false;
     }
 }
+function shaderSourceRelativePath(shaderPath, inputDir) {
+    const relativePath = path__default["default"].relative(inputDir, shaderPath);
+    if (relativePath === ".." || relativePath.startsWith(`..${path__default["default"].sep}`) || path__default["default"].isAbsolute(relativePath) || path__default["default"].extname(relativePath) !== ".shader") {
+        throw new Error(`Shader source must be a .shader file inside the input directory: ${shaderPath}`);
+    }
+    return normalizePath(relativePath);
+}
 function cleanOrphanedBundles(shaderFiles, inputDir, outputDir) {
-    const aliveSet = new Set(shaderFiles.map((f)=>normalizePath(path.relative(inputDir, f)).replace(/\.shader$/, "")));
+    const aliveSet = new Set(shaderFiles.map((f)=>normalizePath(path__default["default"].relative(inputDir, f)).replace(/\.shader$/, "")));
     const bundleFiles = findFiles(outputDir, ".shaderc");
     let removed = 0;
     for (const bundleFile of bundleFiles){
-        const rel = normalizePath(path.relative(outputDir, bundleFile)).replace(/\.shaderc$/, "");
+        const rel = normalizePath(path__default["default"].relative(outputDir, bundleFile)).replace(/\.shaderc$/, "");
         if (!aliveSet.has(rel)) {
-            fs.unlinkSync(bundleFile);
+            fs__default["default"].unlinkSync(bundleFile);
             console.log(`  Removed orphaned: ${rel}.shaderc`);
             removed++;
-            pruneEmptyDirs(path.dirname(bundleFile), outputDir);
+            pruneEmptyDirs(path__default["default"].dirname(bundleFile), outputDir);
         }
     }
     return removed;
@@ -210,19 +283,23 @@ function cleanOrphanedBundles(shaderFiles, inputDir, outputDir) {
 function emitIndex(outputDir) {
     const bundleFiles = findFiles(outputDir, ".shaderc");
     const entries = bundleFiles.map((file)=>{
-        const rel = normalizePath(path.relative(outputDir, file));
+        const rel = normalizePath(path__default["default"].relative(outputDir, file));
         return {
             varName: shadercPathToVarName(rel),
             importPath: `./${rel}`
         };
     }).sort((a, b)=>a.varName.localeCompare(b.varName));
+    assertUniqueIdentifiers(entries.map(({ varName, importPath })=>({
+            identifier: varName,
+            path: importPath
+        })));
     const imports = entries.map((e)=>`import ${e.varName}Data from "${e.importPath}";`).join("\n");
     const exports = entries.map((e)=>`export const ${e.varName}: IPrecompiledShader = ${e.varName}Data;`).join("\n");
     const content = `// Auto-generated by shader-compiler-precompile --emit-index — do not edit.\nimport type { IPrecompiledShader } from "@galacean/engine-design";\n${imports}\n\n${exports}\n`;
-    const indexPath = path.join(outputDir, "index.ts");
-    const existing = fs.existsSync(indexPath) ? fs.readFileSync(indexPath, "utf-8") : "";
+    const indexPath = path__default["default"].join(outputDir, "index.ts");
+    const existing = fs__default["default"].existsSync(indexPath) ? fs__default["default"].readFileSync(indexPath, "utf-8") : "";
     if (content !== existing) {
-        fs.writeFileSync(indexPath, content);
+        fs__default["default"].writeFileSync(indexPath, content);
         console.log("  Updated index.ts");
     }
 }
@@ -231,17 +308,21 @@ function emitIndex(outputDir) {
 //   <sibling>/ShaderLibrary/index.ts — `.glsl` array (only if the directory exists)
 function emitSources(inputDir) {
     emitShaderSourceIndex(inputDir);
-    const libraryDir = path.join(path.dirname(inputDir), "ShaderLibrary");
-    if (fs.existsSync(libraryDir)) {
+    const libraryDir = path__default["default"].join(path__default["default"].dirname(inputDir), "ShaderLibrary");
+    if (fs__default["default"].existsSync(libraryDir)) {
         emitLibrarySourceIndex(libraryDir);
     }
 }
 function emitShaderSourceIndex(rootDir) {
-    const srcDir = path.dirname(rootDir);
+    const srcDir = path__default["default"].dirname(rootDir);
     const files = findFiles(rootDir, ".shader").sort();
-    const importPaths = files.map((f)=>normalizePath(path.relative(rootDir, f)));
-    const paths = files.map((f)=>normalizePath(path.relative(srcDir, f)));
+    const importPaths = files.map((f)=>normalizePath(path__default["default"].relative(rootDir, f)));
+    const paths = files.map((f)=>normalizePath(path__default["default"].relative(srcDir, f)));
     const ids = importPaths.map((p)=>pathToIdentifier(p, ".shader"));
+    assertUniqueIdentifiers(ids.map((identifier, index)=>({
+            identifier,
+            path: importPaths[index]
+        })));
     const lines = [];
     lines.push("// Auto-generated by shader-compiler-precompile --emit-sources — do not edit.");
     lines.push("");
@@ -257,16 +338,20 @@ function emitShaderSourceIndex(rootDir) {
     paths.forEach((p, i)=>lines.push(`  { source: ${ids[i]}, path: ${JSON.stringify(p)} },`));
     lines.push("];");
     lines.push("");
-    const out = path.join(rootDir, "index.ts");
-    fs.writeFileSync(out, lines.join("\n"), "utf-8");
-    console.log(`  Emitted shaders index ${path.relative(process.cwd(), out)} (${files.length})`);
+    const out = path__default["default"].join(rootDir, "index.ts");
+    fs__default["default"].writeFileSync(out, lines.join("\n"), "utf-8");
+    console.log(`  Emitted shaders index ${path__default["default"].relative(process.cwd(), out)} (${files.length})`);
 }
 function emitLibrarySourceIndex(rootDir) {
-    const srcDir = path.dirname(rootDir);
+    const srcDir = path__default["default"].dirname(rootDir);
     const files = findFiles(rootDir, ".glsl").sort();
-    const importPaths = files.map((f)=>normalizePath(path.relative(rootDir, f)));
-    const paths = files.map((f)=>normalizePath(path.relative(srcDir, f)));
+    const importPaths = files.map((f)=>normalizePath(path__default["default"].relative(rootDir, f)));
+    const paths = files.map((f)=>normalizePath(path__default["default"].relative(srcDir, f)));
     const ids = importPaths.map((p)=>pathToIdentifier(p, ".glsl"));
+    assertUniqueIdentifiers(ids.map((identifier, index)=>({
+            identifier,
+            path: importPaths[index]
+        })));
     const lines = [];
     lines.push("// Auto-generated by shader-compiler-precompile --emit-sources — do not edit.");
     lines.push("");
@@ -278,17 +363,27 @@ function emitLibrarySourceIndex(rootDir) {
     paths.forEach((p, i)=>lines.push(`  { source: ${ids[i]}, path: ${JSON.stringify(p)} },`));
     lines.push("];");
     lines.push("");
-    const out = path.join(rootDir, "index.ts");
-    fs.writeFileSync(out, lines.join("\n"), "utf-8");
-    console.log(`  Emitted library index ${path.relative(process.cwd(), out)} (${files.length})`);
+    const out = path__default["default"].join(rootDir, "index.ts");
+    fs__default["default"].writeFileSync(out, lines.join("\n"), "utf-8");
+    console.log(`  Emitted library index ${path__default["default"].relative(process.cwd(), out)} (${files.length})`);
+}
+function assertUniqueIdentifiers(entries) {
+    const pathsByIdentifier = new Map();
+    for (const { identifier, path: sourcePath } of entries){
+        const existingPath = pathsByIdentifier.get(identifier);
+        if (existingPath !== undefined) {
+            throw new Error(`Shader asset paths "${existingPath}" and "${sourcePath}" both emit identifier "${identifier}".`);
+        }
+        pathsByIdentifier.set(identifier, sourcePath);
+    }
 }
 function removeBundleFor(shaderPath, inputDir, outputDir) {
-    const rel = normalizePath(path.relative(inputDir, shaderPath)).replace(/\.shader$/, ".shaderc");
-    const bundlePath = path.join(outputDir, rel);
-    if (fs.existsSync(bundlePath)) {
-        fs.unlinkSync(bundlePath);
+    const rel = normalizePath(path__default["default"].relative(inputDir, shaderPath)).replace(/\.shader$/, ".shaderc");
+    const bundlePath = path__default["default"].join(outputDir, rel);
+    if (fs__default["default"].existsSync(bundlePath)) {
+        fs__default["default"].unlinkSync(bundlePath);
         console.log(`  Removed: ${rel}`);
-        pruneEmptyDirs(path.dirname(bundlePath), outputDir);
+        pruneEmptyDirs(path__default["default"].dirname(bundlePath), outputDir);
     }
 }
 
@@ -299,7 +394,7 @@ function removeBundleFor(shaderPath, inputDir, outputDir) {
  *   shader-compiler-precompile <input-dir> <output-dir>
  *     [--clean] [--watch] [--only <file>] [--emit-index] [--emit-sources]
  */ async function main() {
-    const { positionals, values } = parseArgs({
+    const { positionals, values } = node_util.parseArgs({
         allowPositionals: true,
         options: {
             clean: {