@unrdf/kgn 5.0.1

package/src/linter/determinism-linter.js

@@ -0,0 +1,473 @@
+/**
+ * KGEN Determinism Linter - ZERO TOLERANCE ENFORCEMENT
+ *
+ * Mission: Detect and eliminate ALL sources of nondeterminism in KGEN templates
+ *
+ * Features:
+ * - Real-time violation detection
+ * - Template depth analysis
+ * - Output size validation
+ * - Deterministic pattern enforcement
+ * - Cross-platform consistency checking
+ *
+ * Generated by: Determinism Sentinel Agent
+ * Authority: ZERO TOLERANCE for nondeterminism
+ */
+
+import { readFileSync, statSync, readdirSync } from 'fs';
+import { resolve, relative, extname } from 'path';
+import { createHash } from 'crypto';
+import { glob } from 'glob';
+import consola from 'consola';
+
+export class DeterminismLinter {
+  constructor(config = {}) {
+    this.config = {
+      // CRITICAL LIMITS (ZERO TOLERANCE)
+      maxTemplateDepth: 10,
+      maxOutputSize: 10 * 1024 * 1024, // 10MB
+      maxIterations: 10000,
+      maxFileSize: 1 * 1024 * 1024, // 1MB per template
+
+      // ENFORCEMENT SETTINGS
+      strictMode: true,
+      zeroTolerance: true,
+      failFast: true,
+
+      // VIOLATION TRACKING
+      trackViolations: true,
+      generateReport: true,
+
+      ...config
+    };
+
+    this.logger = consola.withTag('determinism-linter');
+    this.violations = [];
+    this.statistics = {
+      filesScanned: 0,
+      violationsFound: 0,
+      criticalViolations: 0,
+      templateDepthExceeded: 0,
+      outputSizeExceeded: 0
+    };
+
+    // CRITICAL VIOLATION PATTERNS (ZERO TOLERANCE)
+    this.criticalPatterns = [
+      // Temporal nondeterminism
+      {
+        pattern: /new\s+Date\s*\(/g,
+        severity: 'CRITICAL',
+        message: 'new Date() constructor detected - FORBIDDEN',
+        replacement: 'context.metadata.buildTime'
+      },
+      {
+        pattern: /Date\.now\s*\(/g,
+        severity: 'CRITICAL',
+        message: 'Date.now() detected - FORBIDDEN',
+        replacement: 'context.metadata.buildTime'
+      },
+      {
+        pattern: /Math\.random\s*\(/g,
+        severity: 'CRITICAL',
+        message: 'Math.random() detected - FORBIDDEN',
+        replacement: 'generateDeterministicId(inputData)'
+      },
+
+      // Environment dependencies
+      {
+        pattern: /process\.env\./g,
+        severity: 'CRITICAL',
+        message: 'process.env access in template - FORBIDDEN',
+        replacement: 'config.environment'
+      },
+      {
+        pattern: /os\.hostname\s*\(/g,
+        severity: 'CRITICAL',
+        message: 'os.hostname() detected - FORBIDDEN',
+        replacement: 'config.targetHost'
+      },
+      {
+        pattern: /process\.platform/g,
+        severity: 'CRITICAL',
+        message: 'process.platform access - FORBIDDEN',
+        replacement: 'config.targetPlatform'
+      },
+
+      // Nondeterministic iteration
+      {
+        pattern: /for\s*\(\s*\w+\s+in\s+/g,
+        severity: 'CRITICAL',
+        message: 'for...in loop detected - key order undefined',
+        replacement: 'for (key of Object.keys(obj).sort())'
+      },
+      {
+        pattern: /Object\.keys\([^)]+\)\.forEach/g,
+        severity: 'HIGH',
+        message: 'Object.keys().forEach() without sorting',
+        replacement: 'Object.keys(obj).sort().forEach'
+      },
+
+      // Random/UUID generation
+      {
+        pattern: /crypto\.randomBytes/g,
+        severity: 'CRITICAL',
+        message: 'crypto.randomBytes() detected - FORBIDDEN',
+        replacement: 'generateDeterministicBytes(seed, length)'
+      },
+      {
+        pattern: /uuid\(\)|uuidv4\(\)/g,
+        severity: 'CRITICAL',
+        message: 'UUID generation detected - FORBIDDEN',
+        replacement: 'generateDeterministicId(content)'
+      }
+    ];
+
+    // HIGH PRIORITY PATTERNS
+    this.highPriorityPatterns = [
+      {
+        pattern: /fs\.readdir\([^)]+\)(?!\.sort\(\))/g,
+        severity: 'HIGH',
+        message: 'fs.readdir() without sorting - order undefined',
+        replacement: 'fs.readdir(path).then(files => files.sort())'
+      },
+      {
+        pattern: /glob\([^)]+\)(?!\.sort\(\))/g,
+        severity: 'HIGH',
+        message: 'glob() without sorting - order undefined',
+        replacement: 'glob(pattern).then(files => files.sort())'
+      },
+      {
+        pattern: /require\([^)]*\$\{[^}]+\}[^)]*\)/g,
+        severity: 'HIGH',
+        message: 'Dynamic require() with template literals',
+        replacement: 'Static import paths only'
+      }
+    ];
+  }
+
+  /**
+   * Lint a single file for determinism violations
+   */
+  async lintFile(filePath) {
+    this.logger.info(`Linting ${filePath} for determinism violations`);
+
+    try {
+      const content = readFileSync(filePath, 'utf8');
+      const fileViolations = [];
+
+      // Check file size limits
+      const stats = statSync(filePath);
+      if (stats.size > this.config.maxFileSize) {
+        fileViolations.push({
+          file: filePath,
+          line: 1,
+          column: 1,
+          severity: 'HIGH',
+          message: `File size ${stats.size} exceeds limit ${this.config.maxFileSize}`,
+          type: 'file-size-exceeded'
+        });
+      }
+
+      // Scan for critical patterns
+      await this.scanPatterns(filePath, content, this.criticalPatterns, fileViolations);
+      await this.scanPatterns(filePath, content, this.highPriorityPatterns, fileViolations);
+
+      // Template-specific checks
+      if (this.isTemplateFile(filePath)) {
+        await this.validateTemplateStructure(filePath, content, fileViolations);
+      }
+
+      // JavaScript-specific checks
+      if (this.isJavaScriptFile(filePath)) {
+        await this.validateJavaScriptCode(filePath, content, fileViolations);
+      }
+
+      this.violations.push(...fileViolations);
+      this.statistics.filesScanned++;
+      this.statistics.violationsFound += fileViolations.length;
+      this.statistics.criticalViolations += fileViolations.filter(v => v.severity === 'CRITICAL').length;
+
+      return fileViolations;
+
+    } catch (error) {
+      this.logger.error(`Failed to lint ${filePath}:`, error);
+      return [{
+        file: filePath,
+        line: 1,
+        column: 1,
+        severity: 'ERROR',
+        message: `Linting failed: ${error.message}`,
+        type: 'linting-error'
+      }];
+    }
+  }
+
+  /**
+   * Scan content for violation patterns
+   */
+  async scanPatterns(filePath, content, patterns, violations) {
+    const lines = content.split('\n');
+
+    for (const patternConfig of patterns) {
+      const matches = [...content.matchAll(patternConfig.pattern)];
+
+      for (const match of matches) {
+        const position = this.getLineAndColumn(content, match.index);
+
+        violations.push({
+          file: filePath,
+          line: position.line,
+          column: position.column,
+          severity: patternConfig.severity,
+          message: patternConfig.message,
+          pattern: patternConfig.pattern.source,
+          replacement: patternConfig.replacement,
+          type: 'pattern-violation',
+          matchedText: match[0]
+        });
+      }
+    }
+  }
+
+  /**
+   * Validate template structure for determinism
+   */
+  async validateTemplateStructure(filePath, content, violations) {
+    // Check template depth
+    const depth = this.calculateTemplateDepth(content);
+    if (depth > this.config.maxTemplateDepth) {
+      violations.push({
+        file: filePath,
+        line: 1,
+        column: 1,
+        severity: 'HIGH',
+        message: `Template depth ${depth} exceeds maximum ${this.config.maxTemplateDepth}`,
+        type: 'template-depth-exceeded'
+      });
+      this.statistics.templateDepthExceeded++;
+    }
+
+    // Check for dynamic includes
+    const dynamicIncludes = content.match(/{%\s*include\s+[^'"][^%]*%}/g);
+    if (dynamicIncludes) {
+      dynamicIncludes.forEach((include, index) => {
+        const position = this.getLineAndColumn(content, content.indexOf(include));
+        violations.push({
+          file: filePath,
+          line: position.line,
+          column: position.column,
+          severity: 'HIGH',
+          message: 'Dynamic template include detected - path must be static',
+          type: 'dynamic-include',
+          matchedText: include
+        });
+      });
+    }
+
+    // Check for nondeterministic filters
+    const nondeterministicFilters = [
+      'timestamp', 'random', 'uuid', 'now', 'hostname', 'platform'
+    ];
+
+    for (const filter of nondeterministicFilters) {
+      const filterPattern = new RegExp(`\\|\\s*${filter}\\s*(?:\\([^)]*\\))?`, 'g');
+      const matches = [...content.matchAll(filterPattern)];
+
+      for (const match of matches) {
+        const position = this.getLineAndColumn(content, match.index);
+        violations.push({
+          file: filePath,
+          line: position.line,
+          column: position.column,
+          severity: 'CRITICAL',
+          message: `Nondeterministic filter '${filter}' detected`,
+          type: 'nondeterministic-filter',
+          matchedText: match[0]
+        });
+      }
+    }
+  }
+
+  /**
+   * Validate JavaScript code for determinism
+   */
+  async validateJavaScriptCode(filePath, content, violations) {
+    // Check for unsorted object processing
+    const objectIterationPatterns = [
+      /Object\.keys\([^)]+\)(?!\.sort\(\))/g,
+      /Object\.values\([^)]+\)(?!\[Object\.keys\([^)]+\)\.sort\(\)\])/g,
+      /Object\.entries\([^)]+\)(?!\.sort\(\))/g
+    ];
+
+    for (const pattern of objectIterationPatterns) {
+      const matches = [...content.matchAll(pattern)];
+      for (const match of matches) {
+        const position = this.getLineAndColumn(content, match.index);
+        violations.push({
+          file: filePath,
+          line: position.line,
+          column: position.column,
+          severity: 'HIGH',
+          message: 'Object iteration without deterministic ordering',
+          type: 'unsorted-iteration',
+          matchedText: match[0]
+        });
+      }
+    }
+
+    // Check for array sort without stable comparator
+    const unstableSortPattern = /\.sort\(\)(?!\s*\/\/\s*stable|\.sort\([^)]+\))/g;
+    const sortMatches = [...content.matchAll(unstableSortPattern)];
+
+    for (const match of sortMatches) {
+      const position = this.getLineAndColumn(content, match.index);
+      violations.push({
+        file: filePath,
+        line: position.line,
+        column: position.column,
+        severity: 'MEDIUM',
+        message: 'Array.sort() without explicit comparator - may be unstable',
+        type: 'unstable-sort',
+        matchedText: match[0]
+      });
+    }
+  }
+
+  /**
+   * Lint entire directory recursively
+   */
+  async lintDirectory(directoryPath, extensions = ['.js', '.ts', '.njk', '.ejs']) {
+    this.logger.info(`Scanning directory ${directoryPath} for determinism violations`);
+
+    const pattern = `${directoryPath}/**/*{${extensions.join(',')}}`;
+    const files = await glob(pattern, { ignore: ['**/node_modules/**', '**/dist/**'] });
+
+    const allViolations = [];
+
+    for (const file of files) {
+      const fileViolations = await this.lintFile(file);
+      allViolations.push(...fileViolations);
+    }
+
+    return allViolations;
+  }
+
+  /**
+   * Generate comprehensive violation report
+   */
+  generateReport() {
+    const criticalViolations = this.violations.filter(v => v.severity === 'CRITICAL');
+    const highViolations = this.violations.filter(v => v.severity === 'HIGH');
+
+    const report = {
+      summary: {
+        totalFiles: this.statistics.filesScanned,
+        totalViolations: this.statistics.violationsFound,
+        criticalViolations: criticalViolations.length,
+        highViolations: highViolations.length,
+        status: criticalViolations.length > 0 ? 'FAILED' : 'PASSED'
+      },
+      violations: {
+        critical: criticalViolations,
+        high: highViolations,
+        medium: this.violations.filter(v => v.severity === 'MEDIUM')
+      },
+      statistics: this.statistics,
+      enforcement: {
+        zeroToleranceMode: this.config.zeroTolerance,
+        strictMode: this.config.strictMode,
+        maxTemplateDepth: this.config.maxTemplateDepth,
+        maxOutputSize: this.config.maxOutputSize
+      }
+    };
+
+    if (this.config.generateReport) {
+      this.logger.info('Determinism Linting Report:', report);
+    }
+
+    return report;
+  }
+
+  /**
+   * Utility methods
+   */
+  calculateTemplateDepth(content) {
+    const includePattern = /{%\s*include\s+/g;
+    const extendPattern = /{%\s*extends\s+/g;
+    const blockPattern = /{%\s*block\s+/g;
+
+    const includes = (content.match(includePattern) || []).length;
+    const extends_ = (content.match(extendPattern) || []).length;
+    const blocks = (content.match(blockPattern) || []).length;
+
+    return Math.max(includes, extends_, blocks);
+  }
+
+  getLineAndColumn(content, index) {
+    const lines = content.substring(0, index).split('\n');
+    return {
+      line: lines.length,
+      column: lines[lines.length - 1].length + 1
+    };
+  }
+
+  isTemplateFile(filePath) {
+    const templateExtensions = ['.njk', '.ejs', '.hbs', '.mustache', '.liquid'];
+    return templateExtensions.some(ext => filePath.endsWith(ext));
+  }
+
+  isJavaScriptFile(filePath) {
+    return filePath.endsWith('.js') || filePath.endsWith('.ts');
+  }
+
+  /**
+   * ZERO TOLERANCE enforcement
+   */
+  enforceZeroTolerance() {
+    const criticalViolations = this.violations.filter(v => v.severity === 'CRITICAL');
+
+    if (criticalViolations.length > 0 && this.config.zeroTolerance) {
+      this.logger.error(`ZERO TOLERANCE VIOLATION: ${criticalViolations.length} critical determinism violations detected`);
+
+      criticalViolations.forEach(violation => {
+        this.logger.error(`${violation.file}:${violation.line}:${violation.column} - ${violation.message}`);
+      });
+
+      if (this.config.failFast) {
+        throw new Error(`DETERMINISM ENFORCEMENT FAILED: ${criticalViolations.length} critical violations detected`);
+      }
+    }
+
+    return criticalViolations.length === 0;
+  }
+}
+
+/**
+ * CLI interface for determinism linting
+ */
+export async function runDeterminismLinter(targetPath, options = {}) {
+  const linter = new DeterminismLinter(options);
+
+  try {
+    const violations = await linter.lintDirectory(targetPath);
+    const report = linter.generateReport();
+
+    // ZERO TOLERANCE enforcement
+    const passed = linter.enforceZeroTolerance();
+
+    return {
+      passed,
+      report,
+      violations,
+      exitCode: passed ? 0 : 1
+    };
+
+  } catch (error) {
+    consola.error('Determinism linting failed:', error);
+    return {
+      passed: false,
+      error: error.message,
+      exitCode: 2
+    };
+  }
+}