miniray 0.2.2 → 0.3.1

package/README.md

@@ -60,7 +60,7 @@ console.log(result.code);
 
 ### `initialize(options)`
 
-Initialize the WASM module. Must be called before `minify()` or `reflect()`.
+Initialize the WASM module. Must be called before `minify()`, `reflect()`, or `validate()`.
 
 ```typescript
 interface InitializeOptions {
@@ -170,6 +170,76 @@ Memory layouts follow the WGSL specification:
 - Struct members are aligned to their natural alignment
 - Struct size is rounded up to struct alignment
 
+### `validate(source, options?)`
+
+Validate WGSL source for semantic errors, type mismatches, and uniformity violations.
+
+```typescript
+interface ValidateOptions {
+  strictMode?: boolean;                                    // Treat warnings as errors
+  diagnosticFilters?: Record<string, 'error' | 'warning' | 'info' | 'off'>;
+}
+
+interface ValidateResult {
+  valid: boolean;              // true if no errors
+  diagnostics: DiagnosticInfo[];
+  errorCount: number;
+  warningCount: number;
+}
+
+interface DiagnosticInfo {
+  severity: 'error' | 'warning' | 'info' | 'note';
+  code?: string;               // e.g., "E0200"
+  message: string;
+  line: number;                // 1-based
+  column: number;              // 1-based
+  endLine?: number;
+  endColumn?: number;
+  specRef?: string;            // WGSL spec reference
+}
+```
+
+**Example:**
+
+```javascript
+const result = validate(`
+  fn foo() -> f32 {
+    var x: i32 = 1;
+    return x;  // Error: returning i32 from f32 function
+  }
+`);
+
+console.log(result.valid);  // false
+console.log(result.errorCount);  // 1
+console.log(result.diagnostics[0]);
+// {
+//   severity: "error",
+//   code: "E0200",
+//   message: "cannot return 'i32' from function returning 'f32'",
+//   line: 4,
+//   column: 5
+// }
+```
+
+**With options:**
+
+```javascript
+const result = validate(source, {
+  strictMode: true,  // Treat warnings as errors
+  diagnosticFilters: {
+    derivative_uniformity: 'off',  // Disable uniformity warnings
+  },
+});
+```
+
+**Validation checks:**
+- Type mismatches (assignments, returns, function calls)
+- Undefined symbols (variables, functions, types)
+- Invalid operations (operators, indexing, member access)
+- Entry point requirements
+- Uniformity analysis (textureSample, derivatives)
+- WGSL spec compliance
+
 ### `isInitialized()`
 
 Returns `true` if the WASM module is initialized.

package/esm/browser.js

@@ -138,6 +138,43 @@ export function minify(source, options) {
   return globalThis.__miniray.minify(source, options || {});
 }
 
+/**
+ * Reflect WGSL source to extract binding and struct information.
+ * @param {string} source - WGSL source code
+ * @returns {Object} Reflection result with bindings, structs, entryPoints, and errors
+ */
+export function reflect(source) {
+  if (!_initialized) {
+    throw new Error('miniray not initialized. Call initialize() first.');
+  }
+
+  if (typeof source !== 'string') {
+    throw new Error('source must be a string');
+  }
+
+  return globalThis.__miniray.reflect(source);
+}
+
+/**
+ * Validate WGSL source code.
+ * @param {string} source - WGSL source code
+ * @param {Object} [options] - Validation options
+ * @param {boolean} [options.strictMode] - Treat warnings as errors
+ * @param {Object} [options.diagnosticFilters] - Map of rule name to severity
+ * @returns {Object} Validation result with valid, diagnostics, errorCount, warningCount
+ */
+export function validate(source, options) {
+  if (!_initialized) {
+    throw new Error('miniray not initialized. Call initialize() first.');
+  }
+
+  if (typeof source !== 'string') {
+    throw new Error('source must be a string');
+  }
+
+  return globalThis.__miniray.validate(source, options || {});
+}
+
 /**
  * Check if initialized.
  * @returns {boolean}
@@ -163,4 +200,4 @@ export const version = (() => {
 })();
 
 // Default export for convenience
-export default { initialize, minify, isInitialized, version };
+export default { initialize, minify, reflect, validate, isInitialized, version };

package/lib/browser.js

@@ -166,6 +166,26 @@
     return globalThis.__miniray.reflect(source);
   }
 
+  /**
+   * Validate WGSL source code.
+   * @param {string} source - WGSL source code
+   * @param {Object} [options] - Validation options
+   * @param {boolean} [options.strictMode] - Treat warnings as errors
+   * @param {Object} [options.diagnosticFilters] - Map of rule name to severity
+   * @returns {Object} Validation result with valid, diagnostics, errorCount, warningCount
+   */
+  function validate(source, options) {
+    if (!_initialized) {
+      throw new Error('miniray not initialized. Call initialize() first.');
+    }
+
+    if (typeof source !== 'string') {
+      throw new Error('source must be a string');
+    }
+
+    return globalThis.__miniray.validate(source, options || {});
+  }
+
   /**
    * Check if initialized.
    * @returns {boolean}
@@ -189,6 +209,7 @@
     initialize: initialize,
     minify: minify,
     reflect: reflect,
+    validate: validate,
     isInitialized: isInitialized,
     get version() { return getVersion(); }
   };

package/lib/main.d.ts

@@ -151,6 +151,60 @@ export interface EntryPointInfo {
   workgroupSize: [number, number, number] | null;
 }
 
+/**
+ * Options for WGSL validation.
+ */
+export interface ValidateOptions {
+  /**
+   * Treat warnings as errors.
+   * @default false
+   */
+  strictMode?: boolean;
+
+  /**
+   * Map of diagnostic rule names to their severity override.
+   * Rules: "derivative_uniformity", "subgroup_uniformity"
+   * Severities: "error", "warning", "info", "off"
+   */
+  diagnosticFilters?: Record<string, "error" | "warning" | "info" | "off">;
+}
+
+/**
+ * A single validation diagnostic message.
+ */
+export interface DiagnosticInfo {
+  /** Severity: "error", "warning", "info", or "note" */
+  severity: "error" | "warning" | "info" | "note";
+  /** Error code (e.g., "E0200" for type mismatch) */
+  code?: string;
+  /** Human-readable error message */
+  message: string;
+  /** Line number (1-based) */
+  line: number;
+  /** Column number (1-based) */
+  column: number;
+  /** End line number (1-based), if available */
+  endLine?: number;
+  /** End column number (1-based), if available */
+  endColumn?: number;
+  /** Reference to WGSL spec section */
+  specRef?: string;
+}
+
+/**
+ * Result of WGSL validation.
+ */
+export interface ValidateResult {
+  /** Whether the shader is valid (no errors) */
+  valid: boolean;
+  /** All validation diagnostics */
+  diagnostics: DiagnosticInfo[];
+  /** Number of error-level diagnostics */
+  errorCount: number;
+  /** Number of warning-level diagnostics */
+  warningCount: number;
+}
+
 /**
  * Options for initializing the WASM module.
  */
@@ -189,6 +243,15 @@ export function minify(source: string, options?: MinifyOptions): MinifyResult;
  */
 export function reflect(source: string): ReflectResult;
 
+/**
+ * Validate WGSL source code for errors and warnings.
+ * Performs full semantic validation compatible with the Dawn Tint compiler.
+ * @param source - WGSL source code to validate
+ * @param options - Validation options
+ * @returns Validation result with valid flag, diagnostics, and counts
+ */
+export function validate(source: string, options?: ValidateOptions): ValidateResult;
+
 /**
  * Check if the WASM module is initialized.
  */

package/lib/main.js

@@ -158,6 +158,26 @@ function reflect(source) {
   return global.__miniray.reflect(source);
 }
 
+/**
+ * Validate WGSL source code.
+ * @param {string} source - WGSL source code
+ * @param {Object} [options] - Validation options
+ * @param {boolean} [options.strictMode] - Treat warnings as errors
+ * @param {Object} [options.diagnosticFilters] - Map of rule name to severity ("error", "warning", "info", "off")
+ * @returns {Object} Validation result with valid, diagnostics, errorCount, warningCount
+ */
+function validate(source, options) {
+  if (!_initialized) {
+    throw new Error('miniray not initialized. Call initialize() first.');
+  }
+
+  if (typeof source !== 'string') {
+    throw new Error('source must be a string');
+  }
+
+  return global.__miniray.validate(source, options || {});
+}
+
 /**
  * Check if initialized.
  * @returns {boolean}
@@ -181,6 +201,7 @@ module.exports = {
   initialize,
   minify,
   reflect,
+  validate,
   isInitialized,
   get version() { return getVersion(); }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miniray",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "WGSL minifier for WebGPU shaders - WebAssembly build",
   "main": "lib/main.js",
   "module": "esm/browser.js",