wesl-tooling 0.6.2

package/README.md

@@ -0,0 +1 @@
+Utilities for nodejs wesl tools

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+import { VirtualLibraryFn, WeslBundle, WeslDevice } from "wesl";
+import { GPUElementFormat } from "thimbleberry";
+
+//#region src/ParseDependencies.d.ts
+/**
+* Find the wesl package dependencies in a set of WESL files
+* (for packaging WESL files into a library)
+*
+* Parse the WESL files and partially bind the identifiers,
+* returning any identifiers that are not succesfully bound.
+* Those identifiers are the package dependencies.
+*
+* The dependency might be a default export bundle or
+* a named export bundle. e.g. for 'foo::bar::baz', it could be
+*    . package foo, export '.' bundle, module bar
+*    . package foo, export './bar' bundle, element baz
+*    . package foo, export './bar/baz' bundle, module lib.wesl, element baz
+* To distinguish these, we node resolve the longest path we can.
+*/
+/**
+ * Find the wesl package dependencies in a set of WESL files
+ * (for packaging WESL files into a library)
+ *
+ * Parse the WESL files and partially bind the identifiers,
+ * returning any identifiers that are not succesfully bound.
+ * Those identifiers are the package dependencies.
+ *
+ * The dependency might be a default export bundle or
+ * a named export bundle. e.g. for 'foo::bar::baz', it could be
+ *    . package foo, export '.' bundle, module bar
+ *    . package foo, export './bar' bundle, element baz
+ *    . package foo, export './bar/baz' bundle, module lib.wesl, element baz
+ * To distinguish these, we node resolve the longest path we can.
+ */
+declare function parseDependencies(weslSrc: Record<string, string>, projectDir: string): string[];
+/** @return WeslBundle instances referenced by wesl sources
+ *
+ * Parse the WESL files to find references to external WESL modules,
+ * and then load those modules (weslBundle.js files) using node dynamic imports.
+ */
+declare function dependencyBundles(weslSrc: Record<string, string>, projectDir: string): Promise<WeslBundle[]>;
+
+//#endregion
+//#region src/SimpleComputeShader.d.ts
+/**
+ * Compiles a single WESL shader source string into a GPUShaderModule for testing
+ * with automatic package detection.
+ *
+ * Parses the shader source to find references to wesl packages, and
+ * then searches installed npm packages to find the appropriate npm package
+ * bundle to include in the link.
+ *
+ * @param projectDir - The project directory, used for resolving dependencies.
+ * @param device - The WeslDevice to use for shader compilation.
+ * @param src - The WESL shader source code.
+ * @returns A Promise that resolves to the compiled GPUShaderModule.
+ */
+declare function compileShader(projectDir: string, device: WeslDevice, src: string, virtualLibs?: Record<string, VirtualLibraryFn>): Promise<GPUShaderModule>;
+/**
+ * Transpiles and runs a simple compute shader on the GPU for testing.
+ *
+ * A storage buffer is available for the shader to write test results.
+ * `test::results[0]` is the first element of the buffer in wesl.
+ * After execution the storage buffer is copied back to the CPU and returned
+ * for test validation.
+ *
+ * Shader libraries mentioned in the shader source are attached automatically
+ * if they are in node_modules.
+ *
+ * @param module - The compiled GPUShaderModule containing the compute shader.
+ * The shader is invoked once.
+ * @param resultFormat - format for interpreting the result buffer data. (default u32)
+ * @returns storage result array (typically four numbers if the buffer format is u32 or f32)
+ */
+declare function testComputeShader(projectDir: string, gpu: GPU, src: string, resultFormat?: GPUElementFormat): Promise<number[]>;
+/**
+ * Transpiles and runs a simple compute shader on the GPU for testing.
+ *
+ * a 16 byte storage buffer is available for the shader at `@group(0) @binding(0)`.
+ * Compute shaders can write test results into the buffer.
+ * After execution the storage buffer is copied back to the CPU and returned
+ * for test validation.
+ *
+ * Shader libraries mentioned in the shader source are attached automatically
+ * if they are in node_modules.
+ *
+ * @param module - The compiled GPUShaderModule containing the compute shader.
+ * The shader is invoked once.
+ * @param resultFormat - format for interpreting the result buffer data. (default u32)
+ * @returns storage result array
+ */
+declare function runSimpleComputePipeline(device: GPUDevice, module: GPUShaderModule, resultFormat?: GPUElementFormat): Promise<number[]>;
+
+//#endregion
+export { compileShader, dependencyBundles, parseDependencies, runSimpleComputePipeline, testComputeShader };

package/dist/index.js

@@ -0,0 +1,199 @@
+import { resolve } from "import-meta-resolve";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { WeslParseError, filterMap, findUnboundIdents, link, parseIntoRegistry, parsedRegistry, requestWeslDevice } from "wesl";
+import { copyBuffer } from "thimbleberry";
+
+//#region src/ParseDependencies.ts
+/**
+* Find the wesl package dependencies in a set of WESL files
+* (for packaging WESL files into a library)
+*
+* Parse the WESL files and partially bind the identifiers,
+* returning any identifiers that are not succesfully bound.
+* Those identifiers are the package dependencies.
+*
+* The dependency might be a default export bundle or
+* a named export bundle. e.g. for 'foo::bar::baz', it could be
+*    . package foo, export '.' bundle, module bar
+*    . package foo, export './bar' bundle, element baz
+*    . package foo, export './bar/baz' bundle, module lib.wesl, element baz
+* To distinguish these, we node resolve the longest path we can.
+*/
+function parseDependencies(weslSrc, projectDir) {
+	const registry = parsedRegistry();
+	try {
+		parseIntoRegistry(weslSrc, registry);
+	} catch (e) {
+		if (e.cause instanceof WeslParseError) console.error(e.message, "\n");
+		else throw e;
+	}
+	const unbound = findUnboundIdents(registry);
+	if (!unbound) return [];
+	const pkgRefs = unbound.filter((modulePath) => modulePath.length > 1);
+	if (pkgRefs.length === 0) return [];
+	const fullProjectDir = path.resolve(path.join(projectDir, "foo"));
+	const projectURL = pathToFileURL(fullProjectDir).href;
+	const deps = filterMap(pkgRefs, (mPath) => unboundToDependency(mPath, projectURL));
+	const uniqueDeps = [...new Set(deps)];
+	return uniqueDeps;
+}
+/**
+* Find the longest resolvable npm subpath from a module path.
+*
+* @param mPath module path, e.g. ['foo', 'bar', 'baz', 'elem']
+* @param importerURL URL of the importer, e.g. 'file:///path/to/project/foo/bar/baz.wesl' (doesn't need to be a real file)
+* @returns longest resolvable subpath of mPath, e.g. 'foo/bar/baz' or 'foo/bar'
+*/
+function unboundToDependency(mPath, importerURL) {
+	return exportSubpaths(mPath).find((subPath) => tryResolve(subPath, importerURL));
+}
+/** Try to resolve a path using node's resolve algorithm.
+* @return the resolved path */
+function tryResolve(path$1, importerURL) {
+	try {
+		return resolve(path$1, importerURL);
+	} catch (e) {
+		return void 0;
+	}
+}
+/**
+* Yield possible export entry subpaths from module path
+* longest subpath first.
+*/
+function* exportSubpaths(mPath) {
+	const longest = mPath.length - 1;
+	for (let i = longest; i >= 0; i--) {
+		const subPath = mPath.slice(0, i).join("/");
+		yield subPath;
+	}
+}
+/** @return WeslBundle instances referenced by wesl sources
+*
+* Parse the WESL files to find references to external WESL modules,
+* and then load those modules (weslBundle.js files) using node dynamic imports.
+*/
+async function dependencyBundles(weslSrc, projectDir) {
+	const deps = parseDependencies(weslSrc, projectDir);
+	const bundles = deps.map(async (dep) => {
+		const url = resolve(dep, projectDir);
+		const module = await import(url);
+		return module.default;
+	});
+	return await Promise.all(bundles);
+}
+
+//#endregion
+//#region src/SimpleComputeShader.ts
+const resultBufferSize = 16;
+/**
+* Compiles a single WESL shader source string into a GPUShaderModule for testing
+* with automatic package detection.
+*
+* Parses the shader source to find references to wesl packages, and
+* then searches installed npm packages to find the appropriate npm package
+* bundle to include in the link.
+*
+* @param projectDir - The project directory, used for resolving dependencies.
+* @param device - The WeslDevice to use for shader compilation.
+* @param src - The WESL shader source code.
+* @returns A Promise that resolves to the compiled GPUShaderModule.
+*/
+async function compileShader(projectDir, device, src, virtualLibs) {
+	const weslSrc = { main: src };
+	const libs = await dependencyBundles(weslSrc, projectDir);
+	const linked = await link({
+		weslSrc,
+		libs,
+		virtualLibs
+	});
+	return device.createShaderModule({ code: linked.dest });
+}
+/**
+* Transpiles and runs a simple compute shader on the GPU for testing.
+*
+* A storage buffer is available for the shader to write test results.
+* `test::results[0]` is the first element of the buffer in wesl.
+* After execution the storage buffer is copied back to the CPU and returned
+* for test validation.
+*
+* Shader libraries mentioned in the shader source are attached automatically
+* if they are in node_modules.
+*
+* @param module - The compiled GPUShaderModule containing the compute shader.
+* The shader is invoked once.
+* @param resultFormat - format for interpreting the result buffer data. (default u32)
+* @returns storage result array (typically four numbers if the buffer format is u32 or f32)
+*/
+async function testComputeShader(projectDir, gpu, src, resultFormat = "f32") {
+	const adapter = await gpu.requestAdapter();
+	const device = await requestWeslDevice(adapter);
+	try {
+		const arraySize = resultBufferSize / elementByteSize(resultFormat);
+		const arrayType = `array<${resultFormat}, ${arraySize}>`;
+		const virtualLibs = { test: () => `@group(0) @binding(0) var <storage, read_write> results: ${arrayType};` };
+		const module = await compileShader(projectDir, device, src, virtualLibs);
+		const result = await runSimpleComputePipeline(device, module, resultFormat);
+		return result;
+	} finally {
+		device.destroy();
+	}
+}
+/** size in bytes of a wgsl numeric type, e.g. 'f32' => 4 */
+function elementByteSize(fmt) {
+	const found = fmt.match(/\d+/);
+	const bits = Number.parseInt(found?.[0]);
+	return bits / 8;
+}
+/**
+* Transpiles and runs a simple compute shader on the GPU for testing.
+*
+* a 16 byte storage buffer is available for the shader at `@group(0) @binding(0)`.
+* Compute shaders can write test results into the buffer.
+* After execution the storage buffer is copied back to the CPU and returned
+* for test validation.
+*
+* Shader libraries mentioned in the shader source are attached automatically
+* if they are in node_modules.
+*
+* @param module - The compiled GPUShaderModule containing the compute shader.
+* The shader is invoked once.
+* @param resultFormat - format for interpreting the result buffer data. (default u32)
+* @returns storage result array
+*/
+async function runSimpleComputePipeline(device, module, resultFormat) {
+	const bgLayout = device.createBindGroupLayout({ entries: [{
+		binding: 0,
+		visibility: GPUShaderStage.COMPUTE,
+		buffer: { type: "storage" }
+	}] });
+	const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [bgLayout] });
+	const pipeline = device.createComputePipeline({
+		layout: pipelineLayout,
+		compute: { module }
+	});
+	const storageBuffer = device.createBuffer({
+		label: "storage",
+		size: resultBufferSize,
+		usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+	});
+	const bindGroup = device.createBindGroup({
+		layout: bgLayout,
+		entries: [{
+			binding: 0,
+			resource: { buffer: storageBuffer }
+		}]
+	});
+	const commands = device.createCommandEncoder();
+	const pass = commands.beginComputePass();
+	pass.setPipeline(pipeline);
+	pass.setBindGroup(0, bindGroup);
+	pass.dispatchWorkgroups(1);
+	pass.end();
+	device.queue.submit([commands.finish()]);
+	const data = await copyBuffer(device, storageBuffer, resultFormat);
+	return data;
+}
+
+//#endregion
+export { compileShader, dependencyBundles, parseDependencies, runSimpleComputePipeline, testComputeShader };

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "wesl-tooling",
+  "version": "0.6.2",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "import-meta-resolve": "^4.1.0",
+    "thimbleberry": "^0.2.9"
+  },
+  "devDependencies": {
+    "dependent_package": "x",
+    "tsdown": "^0.11.3",
+    "wesl": "0.6.2"
+  },
+  "scripts": {
+    "echo": "echo",
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "format": "prettier . --write",
+    "lint": "eslint src",
+    "typecheck": "tsc",
+    "test": "FORCE_COLOR=1 vitest",
+    "test:once": "vitest run"
+  }
+}