@unrdf/kgn 5.0.1

package/src/linter/test-doubles.js

@@ -0,0 +1,475 @@
+/**
+ * KGEN Deterministic Test Doubles - London BDD Style
+ *
+ * Mission: Provide deterministic alternatives for nondeterministic APIs
+ * Style: London School TDD - Test Doubles, Mocks, Stubs, Fakes
+ *
+ * These test doubles ensure that all tests produce consistent, deterministic results
+ * by replacing nondeterministic dependencies with predictable alternatives.
+ *
+ * Generated by: Determinism Sentinel Agent
+ * Authority: ZERO TOLERANCE for nondeterminism
+ */
+
+import { createHash } from 'crypto';
+import { EventEmitter } from 'events';
+
+/**
+ * TEMPORAL TEST DOUBLES
+ * Replace all time-based nondeterministic functions
+ */
+
+export class DeterministicDate extends Date {
+  static FIXED_TIMESTAMP = '2025-01-01T00:00:00.000Z';
+  static FIXED_TIME_MS = new Date(DeterministicDate.FIXED_TIMESTAMP).getTime();
+
+  constructor(...args) {
+    if (args.length === 0) {
+      // No arguments = current time -> use fixed time
+      super(DeterministicDate.FIXED_TIMESTAMP);
+    } else if (args.length === 1 && typeof args[0] === 'undefined') {
+      // undefined argument -> use fixed time
+      super(DeterministicDate.FIXED_TIMESTAMP);
+    } else {
+      // Specific time provided -> use it (deterministic)
+      super(...args);
+    }
+  }
+
+  static now() {
+    return DeterministicDate.FIXED_TIME_MS;
+  }
+
+  static deterministic() {
+    return DeterministicDate.FIXED_TIME_MS;
+  }
+}
+
+export class MockMath {
+  static seed = 0.12345; // Fixed seed for deterministic "random"
+
+  static random() {
+    // Linear congruential generator - deterministic pseudorandom
+    MockMath.seed = (MockMath.seed * 9301 + 49297) % 233280;
+    return MockMath.seed / 233280;
+  }
+
+  static resetSeed() {
+    MockMath.seed = 0.12345;
+  }
+
+  static setSeed(newSeed) {
+    MockMath.seed = newSeed;
+  }
+
+  // Proxy all other Math methods
+  static floor = Math.floor;
+  static ceil = Math.ceil;
+  static round = Math.round;
+  static abs = Math.abs;
+  static max = Math.max;
+  static min = Math.min;
+}
+
+/**
+ * DETERMINISTIC ID GENERATOR
+ * Replace UUID and random ID generation with content-based deterministic IDs
+ */
+
+export class DeterministicIdGenerator {
+  constructor(config = {}) {
+    this.config = {
+      defaultSalt: 'kgen-deterministic',
+      hashAlgorithm: 'sha256',
+      idLength: 8,
+      ...config
+    };
+    this.counter = 0;
+  }
+
+  generateId(content, salt = null) {
+    const actualSalt = salt || this.config.defaultSalt;
+    const hash = createHash(this.config.hashAlgorithm);
+
+    // Ensure deterministic serialization of content
+    const serializedContent = typeof content === 'object'
+      ? JSON.stringify(content, Object.keys(content).sort())
+      : String(content);
+
+    hash.update(serializedContent);
+    hash.update(actualSalt);
+    hash.update(String(this.counter++)); // Add counter for uniqueness
+
+    return hash.digest('hex').substring(0, this.config.idLength);
+  }
+
+  generateUUID(content, salt = null) {
+    const hash = this.generateId(content, salt);
+    // Format as UUID v4 structure (but deterministic)
+    return `${hash.substring(0, 8)}-${hash.substring(8, 12)}-4${hash.substring(12, 15)}-8${hash.substring(15, 18)}-${hash.substring(18, 30)}000000`.substring(0, 36);
+  }
+
+  reset() {
+    this.counter = 0;
+  }
+}
+
+/**
+ * ENVIRONMENT TEST DOUBLES
+ * Replace process.env and system information with deterministic alternatives
+ */
+
+export class MockProcessEnv {
+  static FIXED_ENV = {
+    NODE_ENV: 'test',
+    BASE_URL: 'https://test.example.com',
+    API_KEY: 'test-api-key-deterministic',
+    DATABASE_URL: 'sqlite://test.db',
+    REDIS_URL: 'redis://localhost:6379/0',
+    PORT: '3000',
+    HOST: '0.0.0.0'
+  };
+
+  static get(key) {
+    return MockProcessEnv.FIXED_ENV[key];
+  }
+
+  static set(key, value) {
+    MockProcessEnv.FIXED_ENV[key] = value;
+  }
+
+  static reset() {
+    MockProcessEnv.FIXED_ENV = { ...MockProcessEnv.FIXED_ENV };
+  }
+
+  static toObject() {
+    return { ...MockProcessEnv.FIXED_ENV };
+  }
+}
+
+export class MockOS {
+  static FIXED_INFO = {
+    hostname: 'test-hostname',
+    platform: 'linux',
+    arch: 'x64',
+    version: '1.0.0-test',
+    tmpdir: '/tmp/test',
+    userInfo: {
+      username: 'test-user',
+      uid: 1000,
+      gid: 1000,
+      shell: '/bin/bash',
+      homedir: '/home/test-user'
+    }
+  };
+
+  static hostname() {
+    return MockOS.FIXED_INFO.hostname;
+  }
+
+  static platform() {
+    return MockOS.FIXED_INFO.platform;
+  }
+
+  static arch() {
+    return MockOS.FIXED_INFO.arch;
+  }
+
+  static version() {
+    return MockOS.FIXED_INFO.version;
+  }
+
+  static tmpdir() {
+    return MockOS.FIXED_INFO.tmpdir;
+  }
+
+  static userInfo() {
+    return { ...MockOS.FIXED_INFO.userInfo };
+  }
+}
+
+/**
+ * I/O TEST DOUBLES
+ * Replace filesystem operations with deterministic alternatives
+ */
+
+export class MockFS {
+  static sortFiles = true;
+  static fixedFiles = new Map();
+
+  static async readdir(path, options = {}) {
+    // Simulate async operation
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    const files = MockFS.fixedFiles.get(path) || [
+      'file-a.js',
+      'file-b.js',
+      'file-c.js'
+    ];
+
+    return MockFS.sortFiles ? files.sort() : files;
+  }
+
+  static async readFile(path, encoding = 'utf8') {
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    const content = MockFS.fixedFiles.get(`content:${path}`) ||
+      `// Mock file content for ${path}\nexport default 'deterministic content';`;
+
+    return content;
+  }
+
+  static setFixedFiles(path, files) {
+    MockFS.fixedFiles.set(path, files);
+  }
+
+  static setFixedContent(path, content) {
+    MockFS.fixedFiles.set(`content:${path}`, content);
+  }
+
+  static reset() {
+    MockFS.fixedFiles.clear();
+    MockFS.sortFiles = true;
+  }
+}
+
+export class MockGlob {
+  static patterns = new Map();
+
+  static async glob(pattern, options = {}) {
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    const matches = MockGlob.patterns.get(pattern) || [
+      `match1-${pattern}`,
+      `match2-${pattern}`,
+      `match3-${pattern}`
+    ];
+
+    return matches.sort(); // Always sorted for determinism
+  }
+
+  static setFixedMatches(pattern, matches) {
+    MockGlob.patterns.set(pattern, matches);
+  }
+
+  static reset() {
+    MockGlob.patterns.clear();
+  }
+}
+
+/**
+ * NETWORK TEST DOUBLES
+ * Replace network operations with deterministic responses
+ */
+
+export class MockFetch {
+  static responses = new Map();
+  static defaultResponse = {
+    ok: true,
+    status: 200,
+    statusText: 'OK',
+    json: async () => ({ message: 'deterministic response' }),
+    text: async () => 'deterministic text response'
+  };
+
+  static async fetch(url, options = {}) {
+    await new Promise(resolve => setTimeout(resolve, 10)); // Simulate network delay
+
+    const key = `${options.method || 'GET'} ${url}`;
+    const response = MockFetch.responses.get(key) || MockFetch.defaultResponse;
+
+    return {
+      ...response,
+      url,
+      options: { ...options }
+    };
+  }
+
+  static setResponse(method, url, response) {
+    const key = `${method} ${url}`;
+    MockFetch.responses.set(key, response);
+  }
+
+  static reset() {
+    MockFetch.responses.clear();
+  }
+}
+
+/**
+ * COMPREHENSIVE TEST ENVIRONMENT SETUP
+ * Replace all nondeterministic globals with deterministic alternatives
+ */
+
+export class DeterministicTestEnvironment {
+  constructor() {
+    this.originalGlobals = {};
+    this.idGenerator = new DeterministicIdGenerator();
+    this.isActive = false;
+  }
+
+  activate() {
+    if (this.isActive) return;
+
+    // Store originals
+    this.originalGlobals = {
+      Date: global.Date,
+      Math: global.Math,
+      process: global.process,
+      require: global.require
+    };
+
+    // Replace with deterministic versions
+    global.Date = DeterministicDate;
+    global.Math = new Proxy(Math, {
+      get: (target, prop) => {
+        if (prop === 'random') return MockMath.random;
+        return target[prop];
+      }
+    });
+
+    // Mock process.env access
+    if (global.process) {
+      const originalEnv = global.process.env;
+      global.process.env = new Proxy(originalEnv, {
+        get: (target, prop) => {
+          return MockProcessEnv.get(prop) || target[prop];
+        }
+      });
+    }
+
+    this.isActive = true;
+  }
+
+  deactivate() {
+    if (!this.isActive) return;
+
+    // Restore originals
+    Object.assign(global, this.originalGlobals);
+    this.isActive = false;
+  }
+
+  reset() {
+    MockMath.resetSeed();
+    MockProcessEnv.reset();
+    MockFS.reset();
+    MockGlob.reset();
+    MockFetch.reset();
+    this.idGenerator.reset();
+  }
+
+  generateDeterministicData(schema) {
+    const data = {};
+
+    for (const [key, type] of Object.entries(schema)) {
+      switch (type) {
+        case 'id':
+          data[key] = this.idGenerator.generateId(key);
+          break;
+        case 'uuid':
+          data[key] = this.idGenerator.generateUUID(key);
+          break;
+        case 'timestamp':
+          data[key] = DeterministicDate.FIXED_TIMESTAMP;
+          break;
+        case 'number':
+          data[key] = MockMath.random() * 1000;
+          break;
+        case 'string':
+          data[key] = `deterministic-${key}-${this.idGenerator.generateId(key)}`;
+          break;
+        default:
+          data[key] = `${type}-${key}`;
+      }
+    }
+
+    return data;
+  }
+}
+
+/**
+ * BDD-STYLE TEST HELPERS
+ * Behavior-driven development helpers for deterministic testing
+ */
+
+export class BDDTestHelpers {
+  static createDeterministicFixture(name, schema) {
+    const env = new DeterministicTestEnvironment();
+    env.activate();
+
+    const fixture = env.generateDeterministicData(schema);
+
+    env.deactivate();
+
+    return fixture;
+  }
+
+  static async verifyDeterministicBehavior(testFunction, iterations = 3) {
+    const results = [];
+    const env = new DeterministicTestEnvironment();
+
+    for (let i = 0; i < iterations; i++) {
+      env.activate();
+      env.reset(); // Reset to same initial state
+
+      const result = await testFunction();
+      results.push(JSON.stringify(result, Object.keys(result).sort()));
+
+      env.deactivate();
+    }
+
+    // All results should be identical
+    const firstResult = results[0];
+    const allIdentical = results.every(result => result === firstResult);
+
+    if (!allIdentical) {
+      throw new Error(`Nondeterministic behavior detected. Results: ${results.join(' | ')}`);
+    }
+
+    return JSON.parse(firstResult);
+  }
+
+  static createMockContext(overrides = {}) {
+    return {
+      metadata: {
+        buildTime: DeterministicDate.FIXED_TIMESTAMP,
+        targetPlatform: 'test-platform',
+        ...overrides.metadata
+      },
+      config: {
+        environment: 'test',
+        targetHost: 'test-host',
+        baseUrl: 'https://test.example.com',
+        ...overrides.config
+      },
+      ...overrides
+    };
+  }
+}
+
+/**
+ * EXPORT ALL TEST DOUBLES
+ */
+
+export const DeterministicTestDoubles = {
+  // Temporal
+  Date: DeterministicDate,
+  Math: MockMath,
+
+  // Environment
+  ProcessEnv: MockProcessEnv,
+  OS: MockOS,
+
+  // I/O
+  FS: MockFS,
+  Glob: MockGlob,
+
+  // Network
+  Fetch: MockFetch,
+
+  // Utilities
+  IdGenerator: DeterministicIdGenerator,
+  TestEnvironment: DeterministicTestEnvironment,
+  BDDHelpers: BDDTestHelpers
+};
+
+export default DeterministicTestDoubles;

package/src/parser/frontmatter.js

@@ -0,0 +1,228 @@
+/**
+ * Frontmatter Parser - YAML frontmatter extraction and parsing
+ * Migrated from ~/unjucks with enhanced error handling
+ */
+
+import matter from 'gray-matter';
+import { parse as parseYAML, stringify as stringifyYAML } from 'yaml';
+
+export class FrontmatterParser {
+  constructor(options = {}) {
+    this.strict = options.strict !== false;
+    this.allowEmpty = options.allowEmpty !== false;
+  }
+
+  /**
+   * Parse frontmatter from template content
+   */
+  parse(content) {
+    try {
+      const result = matter(content, {
+        engines: {
+          yaml: {
+            parse: parseYAML,
+            stringify: stringifyYAML
+          }
+        }
+      });
+
+      return {
+        frontmatter: result.data || {},
+        content: result.content || '',
+        isEmpty: result.isEmpty,
+        excerpt: result.excerpt
+      };
+
+    } catch (error) {
+      if (this.strict) {
+        throw new Error(`Frontmatter parsing failed: ${error.message}`);
+      }
+
+      // Return content as-is if parsing fails in non-strict mode
+      return {
+        frontmatter: {},
+        content: content,
+        isEmpty: true,
+        parseError: error.message
+      };
+    }
+  }
+
+  /**
+   * Extract only frontmatter without parsing content
+   */
+  extractFrontmatter(content) {
+    try {
+      const result = matter(content);
+      return {
+        success: true,
+        frontmatter: result.data || {},
+        isEmpty: result.isEmpty
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        frontmatter: {}
+      };
+    }
+  }
+
+  /**
+   * Validate frontmatter structure
+   */
+  validate(frontmatter, schema = {}) {
+    const errors = [];
+    const warnings = [];
+
+    // Check required fields
+    if (schema.required) {
+      schema.required.forEach(field => {
+        if (!(field in frontmatter)) {
+          errors.push(`Missing required field: ${field}`);
+        }
+      });
+    }
+
+    // Check field types
+    if (schema.types) {
+      Object.entries(schema.types).forEach(([field, expectedType]) => {
+        if (field in frontmatter) {
+          const actualType = typeof frontmatter[field];
+          if (actualType !== expectedType) {
+            errors.push(`Field '${field}' should be ${expectedType}, got ${actualType}`);
+          }
+        }
+      });
+    }
+
+    // Check allowed values
+    if (schema.enum) {
+      Object.entries(schema.enum).forEach(([field, allowedValues]) => {
+        if (field in frontmatter) {
+          if (!allowedValues.includes(frontmatter[field])) {
+            errors.push(`Field '${field}' must be one of: ${allowedValues.join(', ')}`);
+          }
+        }
+      });
+    }
+
+    // Template-specific validations
+    this.validateTemplateFields(frontmatter, errors, warnings);
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+
+  /**
+   * Validate template-specific frontmatter fields
+   */
+  validateTemplateFields(frontmatter, errors, warnings) {
+    // Check for common template metadata
+    const recommendedFields = ['name', 'description', 'version'];
+    recommendedFields.forEach(field => {
+      if (!(field in frontmatter)) {
+        warnings.push(`Recommended field missing: ${field}`);
+      }
+    });
+
+    // Validate variables definition
+    if (frontmatter.variables) {
+      if (typeof frontmatter.variables !== 'object') {
+        errors.push('variables field should be an object');
+      } else {
+        Object.entries(frontmatter.variables).forEach(([varName, varDesc]) => {
+          if (typeof varDesc !== 'string' && typeof varDesc !== 'object') {
+            warnings.push(`Variable '${varName}' should have a description`);
+          }
+        });
+      }
+    }
+
+    // Validate template type
+    if (frontmatter.type) {
+      const validTypes = ['component', 'page', 'service', 'model', 'config', 'documentation'];
+      if (!validTypes.includes(frontmatter.type)) {
+        warnings.push(`Unknown template type: ${frontmatter.type}`);
+      }
+    }
+
+    // Validate output configuration
+    if (frontmatter.output) {
+      if (typeof frontmatter.output === 'string') {
+        // Simple path - OK
+      } else if (typeof frontmatter.output === 'object') {
+        // Complex output config - validate structure
+        if (frontmatter.output.path && typeof frontmatter.output.path !== 'string') {
+          errors.push('output.path must be a string');
+        }
+        if (frontmatter.output.mode && !['write', 'append', 'inject'].includes(frontmatter.output.mode)) {
+          errors.push('output.mode must be one of: write, append, inject');
+        }
+      } else {
+        errors.push('output must be a string path or object configuration');
+      }
+    }
+  }
+
+  /**
+   * Merge frontmatter with defaults
+   */
+  mergeWithDefaults(frontmatter, defaults = {}) {
+    return {
+      // Template metadata defaults
+      name: frontmatter.name || defaults.name || 'Untitled Template',
+      description: frontmatter.description || defaults.description || '',
+      version: frontmatter.version || defaults.version || '1.0.0',
+      author: frontmatter.author || defaults.author || '',
+      
+      // Template configuration
+      type: frontmatter.type || defaults.type || 'component',
+      category: frontmatter.category || defaults.category || 'general',
+      tags: frontmatter.tags || defaults.tags || [],
+      
+      // Output configuration
+      output: frontmatter.output || defaults.output,
+      
+      // Variable definitions
+      variables: {
+        ...defaults.variables,
+        ...frontmatter.variables
+      },
+      
+      // Custom fields
+      ...Object.fromEntries(
+        Object.entries(frontmatter).filter(([key]) => 
+          !['name', 'description', 'version', 'author', 'type', 'category', 'tags', 'output', 'variables'].includes(key)
+        )
+      )
+    };
+  }
+
+  /**
+   * Convert frontmatter back to YAML string
+   */
+  stringify(frontmatter, content = '') {
+    try {
+      const yamlString = stringifyYAML(frontmatter);
+      return `---\n${yamlString}---\n${content}`;
+    } catch (error) {
+      throw new Error(`Failed to stringify frontmatter: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get parser statistics
+   */
+  getStats() {
+    return {
+      strict: this.strict,
+      allowEmpty: this.allowEmpty
+    };
+  }
+}
+
+export default FrontmatterParser;