@clypra/runtime 1.0.0

package/src/validation/resource-validator.ts

@@ -0,0 +1,173 @@
+/**
+ * @clypra/runtime — Resource Validator
+ *
+ * Validates resource bindings and availability.
+ */
+
+import type { ResourceValidationResult, ValidationIssue } from "./types";
+import type { FrameGraph, RenderPass } from "../planner/types";
+
+/**
+ * Resource Validator
+ *
+ * Validates that all required resources are properly bound.
+ */
+export class ResourceValidator {
+  /**
+   * Validate a frame graph's resources
+   */
+  validate(frameGraph: FrameGraph): ResourceValidationResult {
+    const issues: ValidationIssue[] = [];
+    const boundResources = new Set<string>();
+    const missingResources: string[] = [];
+
+    // Collect all allocated resources
+    for (const resource of frameGraph.resourceRequests) {
+      boundResources.add(resource.id);
+    }
+
+    // Check each pass
+    for (const pass of frameGraph.passes) {
+      this.validatePass(pass, boundResources, issues, missingResources);
+    }
+
+    return {
+      valid: issues.filter((i) => i.type === "error").length === 0,
+      issues,
+      boundResources: Array.from(boundResources),
+      missingResources: Array.from(new Set(missingResources)),
+    };
+  }
+
+  /**
+   * Validate a single render pass
+   */
+  private validatePass(pass: RenderPass, boundResources: Set<string>, issues: ValidationIssue[], missingResources: string[]): void {
+    // Check input resources
+    for (const input of pass.inputs) {
+      if (!boundResources.has(input)) {
+        issues.push({
+          type: "error",
+          category: "resource",
+          message: `Pass "${pass.id}" references missing input resource: ${input}`,
+          details: { passId: pass.id, resourceId: input },
+        });
+        missingResources.push(input);
+      }
+    }
+
+    // Check output resource
+    if (!boundResources.has(pass.output)) {
+      issues.push({
+        type: "error",
+        category: "resource",
+        message: `Pass "${pass.id}" references missing output resource: ${pass.output}`,
+        details: { passId: pass.id, resourceId: pass.output },
+      });
+      missingResources.push(pass.output);
+    }
+
+    // Validate uniforms
+    this.validateUniforms(pass, issues);
+
+    // Check for common issues
+    this.checkPassConfiguration(pass, issues);
+  }
+
+  /**
+   * Validate uniforms
+   */
+  private validateUniforms(pass: RenderPass, issues: ValidationIssue[]): void {
+    const uniforms = pass.uniforms;
+
+    // Check for undefined uniforms
+    for (const [key, value] of Object.entries(uniforms)) {
+      if (value === undefined || value === null) {
+        issues.push({
+          type: "warning",
+          category: "resource",
+          message: `Pass "${pass.id}" has undefined uniform: ${key}`,
+          details: { passId: pass.id, uniformName: key },
+        });
+      }
+
+      // Check for NaN values
+      if (typeof value === "number" && isNaN(value)) {
+        issues.push({
+          type: "error",
+          category: "resource",
+          message: `Pass "${pass.id}" has NaN uniform value: ${key}`,
+          details: { passId: pass.id, uniformName: key },
+        });
+      }
+    }
+  }
+
+  /**
+   * Check pass configuration
+   */
+  private checkPassConfiguration(pass: RenderPass, issues: ValidationIssue[]): void {
+    // Warn about passes with no inputs
+    if (pass.inputs.length === 0 && pass.shaderId !== "copy" && pass.shaderId !== "blit") {
+      issues.push({
+        type: "warning",
+        category: "resource",
+        message: `Pass "${pass.id}" has no input resources`,
+        details: { passId: pass.id },
+      });
+    }
+
+    // Warn about empty shader ID
+    if (!pass.shaderId || pass.shaderId.trim() === "") {
+      issues.push({
+        type: "error",
+        category: "resource",
+        message: `Pass "${pass.id}" has empty shader ID`,
+        details: { passId: pass.id },
+      });
+    }
+  }
+
+  /**
+   * Validate resource descriptors
+   */
+  validateDescriptors(descriptors: Array<{ id: string; width: number; height: number }>): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    const ids = new Set<string>();
+
+    for (const descriptor of descriptors) {
+      // Check for duplicate IDs
+      if (ids.has(descriptor.id)) {
+        issues.push({
+          type: "error",
+          category: "resource",
+          message: `Duplicate resource ID: ${descriptor.id}`,
+          details: { resourceId: descriptor.id },
+        });
+      }
+      ids.add(descriptor.id);
+
+      // Check dimensions
+      if (descriptor.width <= 0 || descriptor.height <= 0) {
+        issues.push({
+          type: "error",
+          category: "resource",
+          message: `Invalid resource dimensions for "${descriptor.id}": ${descriptor.width}x${descriptor.height}`,
+          details: { resourceId: descriptor.id, width: descriptor.width, height: descriptor.height },
+        });
+      }
+
+      // Warn about very large textures
+      if (descriptor.width > 4096 || descriptor.height > 4096) {
+        issues.push({
+          type: "warning",
+          category: "performance",
+          message: `Large texture size for "${descriptor.id}": ${descriptor.width}x${descriptor.height}`,
+          details: { resourceId: descriptor.id, width: descriptor.width, height: descriptor.height },
+        });
+      }
+    }
+
+    return issues;
+  }
+}

package/src/validation/shader-validator.ts

@@ -0,0 +1,154 @@
+/**
+ * @clypra/runtime — Shader Validator
+ *
+ * Validates GLSL shaders for compilation and correctness.
+ */
+
+import type { ShaderValidationResult, ValidationIssue } from "./types";
+
+/**
+ * Shader Validator
+ *
+ * Validates GLSL shaders without requiring a full WebGL context.
+ */
+export class ShaderValidator {
+  /**
+   * Validate a GLSL shader
+   */
+  validate(source: string, type: "vertex" | "fragment"): ShaderValidationResult {
+    const issues: ValidationIssue[] = [];
+    const uniformsFound: string[] = [];
+    const attributesFound: string[] = [];
+
+    // Parse uniforms
+    const uniformMatches = source.matchAll(/uniform\s+(\w+)\s+(\w+);/g);
+    for (const match of uniformMatches) {
+      uniformsFound.push(match[2]);
+    }
+
+    // Parse attributes (vertex shaders only)
+    if (type === "vertex") {
+      const attributeMatches = source.matchAll(/attribute\s+(\w+)\s+(\w+);/g);
+      for (const match of attributeMatches) {
+        attributesFound.push(match[2]);
+      }
+    }
+
+    // Check for common issues
+    this.checkSyntax(source, issues);
+    this.checkPrecision(source, issues);
+    this.checkMainFunction(source, issues);
+
+    return {
+      valid: issues.filter((i) => i.type === "error").length === 0,
+      compiled: true, // Will be set by actual compilation
+      issues,
+      uniformsFound,
+      attributesFound,
+    };
+  }
+
+  /**
+   * Validate shader compilation with WebGL context
+   */
+  validateWithContext(gl: WebGLRenderingContext | WebGL2RenderingContext, source: string, type: "vertex" | "fragment"): ShaderValidationResult {
+    const result = this.validate(source, type);
+
+    try {
+      const shaderType = type === "vertex" ? gl.VERTEX_SHADER : gl.FRAGMENT_SHADER;
+      const shader = gl.createShader(shaderType);
+
+      if (!shader) {
+        result.issues.push({
+          type: "error",
+          category: "shader",
+          message: "Failed to create shader",
+        });
+        result.compiled = false;
+        result.valid = false;
+        return result;
+      }
+
+      gl.shaderSource(shader, source);
+      gl.compileShader(shader);
+
+      const compiled = gl.getShaderParameter(shader, gl.COMPILE_STATUS);
+      result.compiled = compiled;
+
+      if (!compiled) {
+        const log = gl.getShaderInfoLog(shader);
+        result.issues.push({
+          type: "error",
+          category: "shader",
+          message: `Shader compilation failed: ${log}`,
+        });
+        result.valid = false;
+      }
+
+      gl.deleteShader(shader);
+    } catch (error) {
+      result.issues.push({
+        type: "error",
+        category: "shader",
+        message: `Shader validation error: ${error}`,
+      });
+      result.compiled = false;
+      result.valid = false;
+    }
+
+    return result;
+  }
+
+  /**
+   * Check syntax issues
+   */
+  private checkSyntax(source: string, issues: ValidationIssue[]): void {
+    // Check for missing semicolons
+    const lines = source.split("\n");
+    lines.forEach((line, index) => {
+      const trimmed = line.trim();
+
+      // Skip empty lines and preprocessor directives
+      if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("//")) {
+        return;
+      }
+
+      // Check for statements that should end with semicolon
+      if (!trimmed.endsWith(";") && !trimmed.endsWith("{") && !trimmed.endsWith("}") && trimmed.length > 0) {
+        issues.push({
+          type: "warning",
+          category: "shader",
+          message: "Possible missing semicolon",
+          location: { line: index + 1 },
+        });
+      }
+    });
+  }
+
+  /**
+   * Check precision declarations
+   */
+  private checkPrecision(source: string, issues: ValidationIssue[]): void {
+    // Fragment shaders should have precision declarations
+    if (!source.includes("precision")) {
+      issues.push({
+        type: "warning",
+        category: "shader",
+        message: "Missing precision qualifier (e.g., precision highp float;)",
+      });
+    }
+  }
+
+  /**
+   * Check for main function
+   */
+  private checkMainFunction(source: string, issues: ValidationIssue[]): void {
+    if (!source.includes("void main()")) {
+      issues.push({
+        type: "error",
+        category: "shader",
+        message: "Missing main function",
+      });
+    }
+  }
+}

package/src/validation/types.ts

@@ -0,0 +1,31 @@
+/**
+ * @clypra/runtime — Validation Types
+ */
+
+export interface ValidationIssue {
+  type: "error" | "warning";
+  category: "shader" | "resource" | "graph" | "performance";
+  message: string;
+  details?: any;
+  location?: {
+    file?: string;
+    line?: number;
+    column?: number;
+  };
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  issues: ValidationIssue[];
+}
+
+export interface ShaderValidationResult extends ValidationResult {
+  compiled: boolean;
+  uniformsFound: string[];
+  attributesFound: string[];
+}
+
+export interface ResourceValidationResult extends ValidationResult {
+  boundResources: string[];
+  missingResources: string[];
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM"],
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: {
+    index: "src/index.ts",
+    "graph/index": "src/graph/index.ts",
+    "planner/index": "src/planner/index.ts",
+    "pixi/index": "src/pixi/index.ts",
+    "resources/index": "src/resources/index.ts",
+    "validation/index": "src/validation/index.ts",
+  },
+  format: ["esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  splitting: false,
+  treeshake: true,
+});