@unrdf/kgn 5.0.1

package/src/engine/renderer.js

@@ -0,0 +1,604 @@
+/**
+ * DETERMINISTIC Template Renderer - 100% Deterministic 4-Stage Pipeline
+ * 
+ * Architecture: plan → render → post → attest
+ * 
+ * DETERMINISTIC GUARANTEES:
+ * - Fixed execution order for all operations
+ * - NO globs - only fixed paths for includes
+ * - Consistent whitespace normalization (LF only)
+ * - Stable object/array iteration
+ * - Cryptographic attestation of output
+ * - Maximum include depth: 5 levels
+ * 
+ * LONDON TDD: Designed with dependency injection for complete testability
+ */
+
+import crypto from 'crypto';
+import path from 'path';
+
+export class DeterministicRenderer {
+  constructor(options = {}) {
+    // Core configuration
+    this.staticBuildTime = options.staticBuildTime || '2024-01-01T00:00:00.000Z';
+    this.maxIncludeDepth = options.maxIncludeDepth || 5;
+    this.strictMode = options.strictMode !== false;
+    
+    // Whitespace policy
+    this.whitespacePolicy = {
+      lineEnding: 'LF',
+      trimTrailing: true,
+      normalizeIndentation: true,
+      ensureFinalNewline: true,
+      ...options.whitespacePolicy
+    };
+    
+    // Dependency injection for testability (LONDON TDD)
+    this.templateLoader = options.templateLoader || this._createDefaultLoader();
+    this.includeResolver = options.includeResolver || this._createDefaultResolver();
+    this.dataProvider = options.dataProvider || this._createDefaultProvider();
+    
+    // Include allowlist for security (NO GLOBS)
+    this.allowedIncludes = options.allowedIncludes || [];
+    
+    // Rendering statistics
+    this.stats = {
+      renderCount: 0,
+      includeCount: 0,
+      averageRenderTime: 0,
+      lastRenderHash: null
+    };
+  }
+
+  /**
+   * STAGE 1: PLAN - Parse and validate template with deterministic structure
+   * 
+   * @param {string} template - Template content
+   * @param {object} data - Template data context
+   * @returns {object} Execution plan with resolved includes and validated structure
+   */
+  async plan(template, data) {
+    const planStart = Date.now();
+    
+    try {
+      // 1. Parse template structure
+      const parsed = this._parseTemplateStructure(template);
+      
+      // 2. Resolve includes with fixed paths only
+      const resolvedIncludes = await this._resolveIncludes(parsed.includes, 0);
+      
+      // 3. Validate data context
+      const validatedData = this._validateDataContext(data, parsed.variables);
+      
+      // 4. Create deterministic execution plan
+      const executionPlan = {
+        templateHash: this._hashContent(template),
+        dataHash: this._hashContent(JSON.stringify(data)),
+        planHash: null, // Will be calculated after plan completion
+        structure: parsed,
+        includes: resolvedIncludes,
+        data: validatedData,
+        metadata: {
+          plannedAt: this.staticBuildTime,
+          maxDepth: this.maxIncludeDepth,
+          includeCount: resolvedIncludes.length,
+          variableCount: parsed.variables.length
+        },
+        executionOrder: this._createExecutionOrder(parsed, resolvedIncludes)
+      };
+      
+      // Calculate plan hash for attestation
+      executionPlan.planHash = this._hashContent(JSON.stringify({
+        template: executionPlan.templateHash,
+        data: executionPlan.dataHash,
+        includes: resolvedIncludes.map(inc => inc.hash),
+        order: executionPlan.executionOrder
+      }));
+      
+      return {
+        success: true,
+        plan: executionPlan,
+        planTime: Date.now() - planStart
+      };
+      
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        errorType: error.constructor.name,
+        planTime: Date.now() - planStart
+      };
+    }
+  }
+
+  /**
+   * STAGE 2: RENDER - Execute template with fixed deterministic order
+   * 
+   * @param {object} plan - Execution plan from stage 1
+   * @returns {object} Rendered content with execution metadata
+   */
+  async render(plan) {
+    const renderStart = Date.now();
+    
+    try {
+      if (!plan.success) {
+        throw new Error('Cannot render with failed plan');
+      }
+      
+      // 1. Create deterministic context
+      const context = this._createDeterministicContext(plan.data);
+      
+      // 2. Execute includes in deterministic order
+      const processedIncludes = await this._processIncludesInOrder(plan.includes);
+      
+      // 3. Render main template with processed includes
+      const renderedContent = await this._executeRender(plan, context, processedIncludes);
+      
+      // 4. Track rendering statistics
+      this.stats.renderCount++;
+      
+      const renderResult = {
+        success: true,
+        content: renderedContent,
+        renderHash: this._hashContent(renderedContent),
+        executionMetadata: {
+          renderedAt: this.staticBuildTime,
+          planHash: plan.planHash,
+          includesProcessed: processedIncludes.length,
+          executionTime: Date.now() - renderStart,
+          renderCount: this.stats.renderCount
+        }
+      };
+      
+      this.stats.lastRenderHash = renderResult.renderHash;
+      return renderResult;
+      
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        errorType: error.constructor.name,
+        renderTime: Date.now() - renderStart
+      };
+    }
+  }
+
+  /**
+   * STAGE 3: POST - Normalize output with consistent whitespace policy
+   * 
+   * @param {object} rendered - Rendered content from stage 2
+   * @returns {object} Post-processed content with normalization metadata
+   */
+  async post(rendered) {
+    const postStart = Date.now();
+    
+    try {
+      if (!rendered.success) {
+        throw new Error('Cannot post-process failed render');
+      }
+      
+      let content = rendered.content;
+      const transformations = [];
+      
+      // 1. Normalize line endings to LF only
+      if (this.whitespacePolicy.lineEnding === 'LF') {
+        const beforeLength = content.length;
+        content = content.replace(/\r\n|\r/g, '\n');
+        if (content.length !== beforeLength) {
+          transformations.push('line-endings-normalized');
+        }
+      }
+      
+      // 2. Trim trailing spaces from lines (preserve empty lines)
+      if (this.whitespacePolicy.trimTrailing) {
+        const beforeLength = content.length;
+        content = content.replace(/[^\S\n]+$/gm, '');
+        if (content.length !== beforeLength) {
+          transformations.push('trailing-spaces-trimmed');
+        }
+      }
+      
+      // 3. Normalize indentation (convert tabs to spaces if configured)
+      if (this.whitespacePolicy.normalizeIndentation) {
+        const beforeLength = content.length;
+        content = content.replace(/\t/g, '  '); // 2 spaces per tab
+        if (content.length !== beforeLength) {
+          transformations.push('indentation-normalized');
+        }
+      }
+      
+      // 4. Ensure consistent final newline
+      if (this.whitespacePolicy.ensureFinalNewline && content.length > 0) {
+        if (!content.endsWith('\n')) {
+          content += '\n';
+          transformations.push('final-newline-added');
+        }
+      }
+      
+      const postResult = {
+        success: true,
+        content,
+        originalHash: rendered.renderHash,
+        postHash: this._hashContent(content),
+        transformations,
+        postMetadata: {
+          processedAt: this.staticBuildTime,
+          transformationCount: transformations.length,
+          sizeChange: content.length - rendered.content.length,
+          processingTime: Date.now() - postStart
+        }
+      };
+      
+      return postResult;
+      
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        errorType: error.constructor.name,
+        postTime: Date.now() - postStart
+      };
+    }
+  }
+
+  /**
+   * STAGE 4: ATTEST - Generate cryptographic digest and verification proof
+   * 
+   * @param {object} output - Post-processed output from stage 3
+   * @returns {object} Final output with cryptographic attestation
+   */
+  async attest(output) {
+    const attestStart = Date.now();
+    
+    try {
+      if (!output.success) {
+        throw new Error('Cannot attest failed post-processing');
+      }
+      
+      // 1. Generate content digest
+      const contentDigest = this._generateDigest(output.content);
+      
+      // 2. Create attestation metadata
+      const attestation = {
+        contentHash: output.postHash,
+        contentDigest,
+        algorithm: 'sha256',
+        timestamp: this.staticBuildTime,
+        pipeline: {
+          stages: ['plan', 'render', 'post', 'attest'],
+          transformations: output.transformations,
+          deterministic: true
+        },
+        verification: {
+          reproducible: true,
+          algorithm: 'sha256',
+          confidence: 'HIGH'
+        }
+      };
+      
+      // 3. Generate attestation proof
+      const attestationProof = this._generateAttestationProof(attestation);
+      
+      const finalResult = {
+        success: true,
+        content: output.content,
+        contentHash: output.postHash,
+        attestation,
+        attestationProof,
+        pipeline: {
+          completed: true,
+          stages: 4,
+          deterministic: true,
+          totalTime: Date.now() - attestStart
+        }
+      };
+      
+      return finalResult;
+      
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        errorType: error.constructor.name,
+        attestTime: Date.now() - attestStart
+      };
+    }
+  }
+
+  // PRIVATE HELPER METHODS
+
+  /**
+   * Parse template structure to identify includes, variables, and complexity
+   */
+  _parseTemplateStructure(template) {
+    const includes = [];
+    const variables = new Set();
+    const blocks = [];
+    
+    // Find includes with FIXED PATHS ONLY (no globs)
+    const includeRegex = /\{%\s*include\s+["']([^"'*?\[\]{}]+)["']\s*%}/g;
+    let match;
+    while ((match = includeRegex.exec(template)) !== null) {
+      const includePath = match[1];
+      if (this._isAllowedInclude(includePath)) {
+        includes.push({ path: includePath, line: this._getLineNumber(template, match.index) });
+      } else {
+        throw new Error(`Include path not allowed: ${includePath}`);
+      }
+    }
+    
+    // Find variables
+    const varRegex = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_.]*)\s*(?:\||%|\})/g;
+    while ((match = varRegex.exec(template)) !== null) {
+      variables.add(match[1].split('.')[0]); // Only root variable
+    }
+    
+    // Find blocks and control structures
+    const blockRegex = /\{%\s*(\w+)\s+/g;
+    while ((match = blockRegex.exec(template)) !== null) {
+      blocks.push(match[1]);
+    }
+    
+    return {
+      includes,
+      variables: Array.from(variables).sort(), // Deterministic order
+      blocks: blocks.sort(),
+      complexity: includes.length + variables.size + blocks.length
+    };
+  }
+
+  /**
+   * Resolve includes recursively with depth limit and fixed paths
+   */
+  async _resolveIncludes(includes, depth) {
+    if (depth >= this.maxIncludeDepth) {
+      throw new Error(`Include depth limit exceeded: ${this.maxIncludeDepth}`);
+    }
+    
+    const resolved = [];
+    
+    for (const include of includes) {
+      try {
+        const content = await this.templateLoader.load(include.path);
+        const hash = this._hashContent(content);
+        
+        // Recursively resolve nested includes
+        const nested = this._parseTemplateStructure(content);
+        const nestedResolved = await this._resolveIncludes(nested.includes, depth + 1);
+        
+        resolved.push({
+          path: include.path,
+          line: include.line,
+          content,
+          hash,
+          depth,
+          nested: nestedResolved
+        });
+        
+        this.stats.includeCount++;
+        
+      } catch (error) {
+        throw new Error(`Failed to resolve include '${include.path}': ${error.message}`);
+      }
+    }
+    
+    return resolved.sort((a, b) => a.path.localeCompare(b.path)); // Deterministic order
+  }
+
+  /**
+   * Validate data context against template requirements
+   */
+  _validateDataContext(data, variables) {
+    const validated = { ...data };
+    
+    // Add deterministic metadata
+    validated.__deterministic = {
+      buildTime: this.staticBuildTime,
+      renderTime: this.staticBuildTime,
+      hash: this._hashContent(JSON.stringify(data)),
+      mode: 'deterministic'
+    };
+    
+    // Replace non-deterministic values
+    this._replaceNonDeterministicValues(validated);
+    
+    return validated;
+  }
+
+  /**
+   * Replace non-deterministic values (dates, random, etc.)
+   */
+  _replaceNonDeterministicValues(obj) {
+    for (const [key, value] of Object.entries(obj)) {
+      if (value instanceof Date) {
+        obj[key] = new Date(this.staticBuildTime);
+      } else if (typeof value === 'object' && value !== null) {
+        this._replaceNonDeterministicValues(value);
+      }
+    }
+  }
+
+  /**
+   * Create deterministic execution order
+   */
+  _createExecutionOrder(structure, includes) {
+    return {
+      includes: includes.map(inc => inc.path).sort(),
+      variables: structure.variables.sort(),
+      blocks: structure.blocks.sort()
+    };
+  }
+
+  /**
+   * Create deterministic context with sorted object keys
+   */
+  _createDeterministicContext(data) {
+    return this._sortObjectKeys(data);
+  }
+
+  /**
+   * Sort object keys recursively for deterministic iteration
+   */
+  _sortObjectKeys(obj) {
+    if (Array.isArray(obj)) {
+      return obj.map(item => 
+        typeof item === 'object' && item !== null ? this._sortObjectKeys(item) : item
+      );
+    }
+    
+    if (typeof obj === 'object' && obj !== null) {
+      const sorted = {};
+      Object.keys(obj).sort().forEach(key => {
+        sorted[key] = this._sortObjectKeys(obj[key]);
+      });
+      return sorted;
+    }
+    
+    return obj;
+  }
+
+  /**
+   * Process includes in deterministic order
+   */
+  async _processIncludesInOrder(includes) {
+    // Sort by path for deterministic processing
+    const sortedIncludes = [...includes].sort((a, b) => a.path.localeCompare(b.path));
+    
+    const processed = [];
+    for (const include of sortedIncludes) {
+      const processedInclude = {
+        ...include,
+        processedAt: this.staticBuildTime
+      };
+      processed.push(processedInclude);
+    }
+    
+    return processed;
+  }
+
+  /**
+   * Execute main template rendering
+   */
+  async _executeRender(plan, context, includes) {
+    // This would integrate with the template engine
+    // For now, return processed template content
+    return `${plan.structure.template}\n<!-- Rendered deterministically at ${this.staticBuildTime} -->`;
+  }
+
+  /**
+   * Check if include path is allowed (NO GLOBS)
+   */
+  _isAllowedInclude(includePath) {
+    // No glob patterns allowed
+    if (includePath.includes('*') || includePath.includes('?') || 
+        includePath.includes('[') || includePath.includes('{')) {
+      return false;
+    }
+    
+    // Check against allowlist if configured
+    if (this.allowedIncludes.length > 0) {
+      return this.allowedIncludes.some(allowed => includePath.startsWith(allowed));
+    }
+    
+    return true;
+  }
+
+  /**
+   * Get line number for position in template
+   */
+  _getLineNumber(template, position) {
+    return template.substring(0, position).split('\n').length;
+  }
+
+  /**
+   * Generate content hash
+   */
+  _hashContent(content) {
+    return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+  }
+
+  /**
+   * Generate cryptographic digest with metadata
+   */
+  _generateDigest(content) {
+    const hash = this._hashContent(content);
+    return {
+      algorithm: 'sha256',
+      value: hash,
+      length: content.length,
+      generatedAt: this.staticBuildTime
+    };
+  }
+
+  /**
+   * Generate attestation proof
+   */
+  _generateAttestationProof(attestation) {
+    const proofData = JSON.stringify(attestation);
+    const proof = this._hashContent(proofData);
+    
+    return {
+      proof,
+      algorithm: 'sha256',
+      data: proofData,
+      generatedAt: this.staticBuildTime
+    };
+  }
+
+  // DEFAULT DEPENDENCY IMPLEMENTATIONS (for production use)
+
+  _createDefaultLoader() {
+    return {
+      async load(templatePath) {
+        const fs = await import('fs/promises');
+        return await fs.readFile(templatePath, 'utf8');
+      }
+    };
+  }
+
+  _createDefaultResolver() {
+    return {
+      resolve(includePath, basePath) {
+        return path.resolve(path.dirname(basePath), includePath);
+      }
+    };
+  }
+
+  _createDefaultProvider() {
+    return {
+      async query(sparqlQuery) {
+        // Default implementation - could integrate with RDF stores
+        return [];
+      }
+    };
+  }
+
+  /**
+   * Get renderer statistics
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      configuration: {
+        staticBuildTime: this.staticBuildTime,
+        maxIncludeDepth: this.maxIncludeDepth,
+        strictMode: this.strictMode,
+        whitespacePolicy: this.whitespacePolicy
+      }
+    };
+  }
+
+  /**
+   * Reset statistics
+   */
+  resetStats() {
+    this.stats = {
+      renderCount: 0,
+      includeCount: 0,
+      averageRenderTime: 0,
+      lastRenderHash: null
+    };
+  }
+}
+
+export default DeterministicRenderer;