@unrdf/kgn 5.0.1

package/src/injection/idempotency-manager.js

@@ -0,0 +1,295 @@
+/**
+ * KGEN Idempotency Manager
+ *
+ * Manages idempotent injection operations using skipIf conditions
+ * to prevent duplicate content and ensure deterministic behavior.
+ */
+
+import { promises as fs } from 'fs';
+import { createHash } from 'crypto';
+
+import { SKIP_IF_LOGIC, CHECKSUM_ALGORITHMS } from './constants.js';
+
+export class IdempotencyManager {
+  constructor(config = {}) {
+    this.config = config;
+    this.contentCache = new Map();
+    this.hashCache = new Map();
+  }
+
+  /**
+   * Check if injection should be skipped based on skipIf conditions
+   */
+  async shouldSkipInjection(target, content, variables) {
+    const skipConditions = target.skipIf;
+
+    if (!skipConditions) {
+      return { skip: false, reason: null };
+    }
+
+    // Handle different skipIf condition types
+    if (typeof skipConditions === 'string') {
+      return await this._evaluateSingleCondition(skipConditions, target, content, variables);
+    }
+
+    if (Array.isArray(skipConditions)) {
+      return await this._evaluateMultipleConditions(skipConditions, target, content, variables);
+    }
+
+    if (typeof skipConditions === 'object') {
+      return await this._evaluateObjectCondition(skipConditions, target, content, variables);
+    }
+
+    return { skip: false, reason: 'Invalid skipIf condition' };
+  }
+
+  /**
+   * Generate content hash for duplicate detection
+   */
+  async generateContentHash(content, target) {
+    const cacheKey = `${target.resolvedPath}:${content}`;
+
+    if (this.hashCache.has(cacheKey)) {
+      return this.hashCache.get(cacheKey);
+    }
+
+    const hash = createHash(CHECKSUM_ALGORITHMS.SHA256);
+    hash.update(content);
+    hash.update(target.resolvedPath);
+    hash.update(target.mode);
+
+    const result = hash.digest('hex');
+    this.hashCache.set(cacheKey, result);
+
+    return result;
+  }
+
+  /**
+   * Check if content already exists in target file
+   */
+  async contentExists(target, content, options = {}) {
+    try {
+      const fileContent = await this._getFileContent(target.resolvedPath);
+      const { exact = false, ignoreWhitespace = false, regex = false } = options;
+
+      if (regex) {
+        const pattern = new RegExp(content, options.regexFlags || 'gm');
+        return pattern.test(fileContent);
+      }
+
+      let searchContent = content;
+      let searchFileContent = fileContent;
+
+      if (ignoreWhitespace) {
+        searchContent = content.replace(/\s+/g, ' ').trim();
+        searchFileContent = fileContent.replace(/\s+/g, ' ').trim();
+      }
+
+      if (exact) {
+        return searchFileContent === searchContent;
+      }
+
+      return searchFileContent.includes(searchContent);
+
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return false; // File doesn't exist, content can't exist
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Private Methods
+   */
+
+  async _evaluateSingleCondition(condition, target, content, variables) {
+    // Built-in conditions
+    if (condition === 'file_exists') {
+      const exists = await this._fileExists(target.resolvedPath);
+      return {
+        skip: exists,
+        reason: exists ? 'Target file already exists' : null
+      };
+    }
+
+    if (condition.startsWith('file_size >')) {
+      const sizeLimit = parseInt(condition.split('>')[1].trim());
+      const actualSize = await this._getFileSize(target.resolvedPath);
+      const skip = actualSize > sizeLimit;
+      return {
+        skip,
+        reason: skip ? `File size exceeds limit (${actualSize} > ${sizeLimit} bytes)` : null
+      };
+    }
+
+    if (condition.startsWith('line_count >')) {
+      const lineLimit = parseInt(condition.split('>')[1].trim());
+      const actualLines = await this._getLineCount(target.resolvedPath);
+      const skip = actualLines > lineLimit;
+      return {
+        skip,
+        reason: skip ? `File has too many lines (${actualLines} > ${lineLimit})` : null
+      };
+    }
+
+    // Pattern matching conditions
+    if (condition.startsWith('/') && condition.endsWith('/')) {
+      // Regex pattern
+      const pattern = condition.slice(1, -1);
+      const exists = await this.contentExists(target, pattern, { regex: true });
+      return {
+        skip: exists,
+        reason: exists ? `Pattern already exists: ${condition}` : null
+      };
+    }
+
+    // Variable interpolation
+    const interpolatedCondition = this._interpolateVariables(condition, variables);
+
+    // Check if interpolated content exists in file
+    const exists = await this.contentExists(target, interpolatedCondition);
+    return {
+      skip: exists,
+      reason: exists ? `Content already exists: ${interpolatedCondition}` : null
+    };
+  }
+
+  async _evaluateMultipleConditions(conditions, target, content, variables) {
+    const logic = target.skipIfLogic || SKIP_IF_LOGIC.OR;
+    const results = [];
+
+    for (const condition of conditions) {
+      const result = await this._evaluateSingleCondition(condition, target, content, variables);
+      results.push(result);
+    }
+
+    if (logic === SKIP_IF_LOGIC.AND) {
+      const allTrue = results.every(r => r.skip);
+      return {
+        skip: allTrue,
+        reason: allTrue ? `All conditions matched (AND logic): ${results.map(r => r.reason).join(', ')}` : null
+      };
+    } else {
+      // OR logic (default)
+      const anyTrue = results.some(r => r.skip);
+      const matchingReasons = results.filter(r => r.skip).map(r => r.reason);
+      return {
+        skip: anyTrue,
+        reason: anyTrue ? `Condition matched (OR logic): ${matchingReasons[0]}` : null
+      };
+    }
+  }
+
+  async _evaluateObjectCondition(conditionObj, target, content, variables) {
+    // Complex object-based conditions
+    const { pattern, exists, custom, hash } = conditionObj;
+
+    if (pattern) {
+      return await this._evaluateSingleCondition(pattern, target, content, variables);
+    }
+
+    if (exists !== undefined) {
+      const fileExists = await this._fileExists(target.resolvedPath);
+      return {
+        skip: fileExists === exists,
+        reason: fileExists === exists ? `File existence matches condition: ${exists}` : null
+      };
+    }
+
+    if (hash) {
+      const contentHash = await this.generateContentHash(content, target);
+      const existingHash = await this._getExistingContentHash(target);
+      const skip = contentHash === existingHash;
+      return {
+        skip,
+        reason: skip ? 'Content hash already exists' : null
+      };
+    }
+
+    if (custom && typeof custom === 'function') {
+      const result = await custom(target, content, variables);
+      return {
+        skip: result.skip,
+        reason: result.reason || 'Custom condition matched'
+      };
+    }
+
+    return { skip: false, reason: 'Invalid object condition' };
+  }
+
+  _interpolateVariables(template, variables) {
+    return template.replace(/\{\{(\w+)\}\}/g, (match, variable) => {
+      return variables[variable] || match;
+    });
+  }
+
+  async _getFileContent(filePath) {
+    const cacheKey = filePath;
+
+    if (this.contentCache.has(cacheKey)) {
+      return this.contentCache.get(cacheKey);
+    }
+
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+      this.contentCache.set(cacheKey, content);
+      return content;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        this.contentCache.set(cacheKey, '');
+        return '';
+      }
+      throw error;
+    }
+  }
+
+  async _fileExists(filePath) {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  async _getFileSize(filePath) {
+    try {
+      const stats = await fs.stat(filePath);
+      return stats.size;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return 0;
+      }
+      throw error;
+    }
+  }
+
+  async _getLineCount(filePath) {
+    try {
+      const content = await this._getFileContent(filePath);
+      return content.split('\n').length;
+    } catch (error) {
+      return 0;
+    }
+  }
+
+  async _getExistingContentHash(target) {
+    try {
+      const content = await this._getFileContent(target.resolvedPath);
+      const hash = createHash(CHECKSUM_ALGORITHMS.SHA256);
+      hash.update(content);
+      return hash.digest('hex');
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Clear caches (useful for testing or long-running processes)
+   */
+  clearCache() {
+    this.contentCache.clear();
+    this.hashCache.clear();
+  }
+}

package/src/injection/index.js

@@ -0,0 +1,28 @@
+/**
+ * KGEN Injection Operations System
+ *
+ * Provides atomic, idempotent, and deterministic code injection capabilities
+ * for modifying existing files without complete overwriting.
+ *
+ * Key Features:
+ * - Atomic operations with rollback capability
+ * - Idempotent with skipIf conditions
+ * - Deterministic behavior across runs
+ * - Marker-based precise targeting
+ * - Multiple injection modes (append, prepend, before, after, replace)
+ * - Comprehensive validation and error handling
+ */
+
+export { InjectionEngine } from './injection-engine.js';
+export { InjectionModes } from './modes/index.js';
+export { TargetResolver } from './target-resolver.js';
+export { AtomicWriter } from './atomic-writer.js';
+export { IdempotencyManager } from './idempotency-manager.js';
+export { ValidationEngine } from './validation-engine.js';
+export { RollbackManager } from './rollback-manager.js';
+
+// Main injection API
+export { inject } from './api.js';
+
+// Types and constants
+export { INJECTION_MODES, VALIDATION_RULES, ERROR_CODES } from './constants.js';

package/src/injection/injection-engine.js

@@ -0,0 +1,378 @@
+/**
+ * KGEN Injection Engine
+ *
+ * Main orchestrator for all injection operations. Provides atomic,
+ * idempotent, and deterministic file modification capabilities.
+ */
+
+import { promises as fs } from 'fs';
+import { join, dirname, resolve, relative } from 'path';
+import { createHash } from 'crypto';
+
+import { TargetResolver } from './target-resolver.js';
+import { AtomicWriter } from './atomic-writer.js';
+import { IdempotencyManager } from './idempotency-manager.js';
+import { ValidationEngine } from './validation-engine.js';
+import { RollbackManager } from './rollback-manager.js';
+import { InjectionModes } from './modes/index.js';
+
+import {
+  INJECTION_MODES,
+  ERROR_CODES,
+  DEFAULT_CONFIG,
+  OPERATION_METADATA
+} from './constants.js';
+
+export class InjectionEngine {
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+
+    // Initialize components
+    this.targetResolver = new TargetResolver(this.config);
+    this.atomicWriter = new AtomicWriter(this.config);
+    this.idempotencyManager = new IdempotencyManager(this.config);
+    this.validationEngine = new ValidationEngine(this.config);
+    this.rollbackManager = new RollbackManager(this.config);
+    this.injectionModes = new InjectionModes(this.config);
+
+    // Operation state
+    this.activeOperations = new Map();
+    this.operationHistory = [];
+  }
+
+  /**
+   * Main injection method - atomic, idempotent, deterministic
+   */
+  async inject(templateConfig, content, variables = {}) {
+    const operationId = this._generateOperationId(templateConfig, content);
+
+    try {
+      // Start atomic operation
+      await this._beginOperation(operationId, templateConfig);
+
+      // Resolve targets deterministically
+      const targets = await this.targetResolver.resolveTargets(templateConfig, variables);
+
+      // Validate all targets before any modifications
+      await this._validateAllTargets(targets);
+
+      // Check idempotency for all targets
+      const filteredTargets = await this._filterIdempotentTargets(targets, content, variables);
+
+      if (filteredTargets.length === 0) {
+        return {
+          success: true,
+          skipped: true,
+          message: 'All injections skipped - idempotent conditions met',
+          targets: targets.length
+        };
+      }
+
+      // Execute atomic multi-target injection
+      const results = await this._executeAtomicInjection(filteredTargets, content, variables, operationId);
+
+      // Commit operation
+      await this._commitOperation(operationId, results);
+
+      return {
+        success: true,
+        operationId,
+        results,
+        targets: filteredTargets.length,
+        skipped: targets.length - filteredTargets.length
+      };
+
+    } catch (error) {
+      // Atomic rollback on any failure
+      await this._rollbackOperation(operationId, error);
+      throw this._wrapError(error, operationId);
+    }
+  }
+
+  /**
+   * Dry run - shows what would be done without making changes
+   */
+  async dryRun(templateConfig, content, variables = {}) {
+    const targets = await this.targetResolver.resolveTargets(templateConfig, variables);
+    const validationResults = await this._validateAllTargets(targets, false); // Non-failing validation
+    const idempotencyResults = await this._checkIdempotency(targets, content, variables);
+
+    return {
+      targets: targets.map((target, index) => ({
+        path: target.resolvedPath,
+        mode: target.mode,
+        valid: validationResults[index].valid,
+        wouldSkip: idempotencyResults[index].skip,
+        reason: idempotencyResults[index].reason,
+        validation: validationResults[index]
+      }))
+    };
+  }
+
+  /**
+   * Undo previous injection
+   */
+  async undo(operationId) {
+    return await this.rollbackManager.undoOperation(operationId);
+  }
+
+  /**
+   * Get operation history
+   */
+  getOperationHistory() {
+    return [...this.operationHistory];
+  }
+
+  /**
+   * Private Methods
+   */
+
+  _generateOperationId(templateConfig, content) {
+    const hash = createHash('sha256');
+    hash.update(JSON.stringify(templateConfig, null, 0));
+    hash.update(content);
+    hash.update(Date.now().toString());
+    return `injection-${hash.digest('hex').substring(0, 16)}`;
+  }
+
+  async _beginOperation(operationId, templateConfig) {
+    this.activeOperations.set(operationId, {
+      id: operationId,
+      config: templateConfig,
+      startTime: Date.now(),
+      phase: 'initializing',
+      targets: [],
+      backups: []
+    });
+  }
+
+  async _validateAllTargets(targets, throwOnError = true) {
+    const results = [];
+
+    for (const target of targets) {
+      try {
+        const result = await this.validationEngine.validateTarget(target);
+        results.push(result);
+
+        if (throwOnError && !result.valid) {
+          throw new Error(`Target validation failed: ${result.errors.join(', ')}`);
+        }
+      } catch (error) {
+        if (throwOnError) throw error;
+        results.push({ valid: false, errors: [error.message] });
+      }
+    }
+
+    return results;
+  }
+
+  async _filterIdempotentTargets(targets, content, variables) {
+    const filtered = [];
+
+    for (const target of targets) {
+      const shouldSkip = await this.idempotencyManager.shouldSkipInjection(
+        target, content, variables
+      );
+
+      if (!shouldSkip.skip) {
+        filtered.push(target);
+      } else {
+        console.log(`Skipping ${target.resolvedPath}: ${shouldSkip.reason}`);
+      }
+    }
+
+    return filtered;
+  }
+
+  async _checkIdempotency(targets, content, variables) {
+    const results = [];
+
+    for (const target of targets) {
+      const result = await this.idempotencyManager.shouldSkipInjection(
+        target, content, variables
+      );
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  async _executeAtomicInjection(targets, content, variables, operationId) {
+    const operation = this.activeOperations.get(operationId);
+    operation.phase = 'executing';
+    operation.targets = targets;
+
+    // If single target, use simple atomic write
+    if (targets.length === 1) {
+      return [await this._injectSingleTarget(targets[0], content, variables, operationId)];
+    }
+
+    // Multiple targets require transaction
+    return await this._executeTransaction(targets, content, variables, operationId);
+  }
+
+  async _injectSingleTarget(target, content, variables, operationId) {
+    // Read current file content
+    const currentContent = await this._readTargetFile(target);
+
+    // Apply injection mode
+    const modifiedContent = await this.injectionModes.applyMode(
+      target.mode,
+      currentContent,
+      content,
+      target,
+      variables
+    );
+
+    // Validate resulting content
+    await this.validationEngine.validateContent(modifiedContent, target);
+
+    // Write atomically
+    const result = await this.atomicWriter.writeAtomic(
+      target.resolvedPath,
+      modifiedContent,
+      {
+        backup: this.config.backupEnabled,
+        operationId,
+        preserveMetadata: this.config.preservePermissions
+      }
+    );
+
+    return {
+      target: target.resolvedPath,
+      mode: target.mode,
+      success: true,
+      backup: result.backupPath,
+      checksum: result.checksum
+    };
+  }
+
+  async _executeTransaction(targets, content, variables, operationId) {
+    const transaction = await this.atomicWriter.beginTransaction(operationId);
+
+    try {
+      const results = [];
+
+      // Prepare all operations
+      for (const target of targets) {
+        const currentContent = await this._readTargetFile(target);
+        const modifiedContent = await this.injectionModes.applyMode(
+          target.mode,
+          currentContent,
+          content,
+          target,
+          variables
+        );
+
+        await this.validationEngine.validateContent(modifiedContent, target);
+
+        const result = await transaction.prepareWrite(
+          target.resolvedPath,
+          modifiedContent
+        );
+
+        results.push({
+          target: target.resolvedPath,
+          mode: target.mode,
+          prepared: true,
+          checksum: result.checksum
+        });
+      }
+
+      // Commit all changes atomically
+      await transaction.commit();
+
+      return results.map(r => ({ ...r, success: true, prepared: false }));
+
+    } catch (error) {
+      await transaction.rollback();
+      throw error;
+    }
+  }
+
+  async _readTargetFile(target) {
+    if (target.mode === INJECTION_MODES.CREATE && target.createIfMissing) {
+      try {
+        return await fs.readFile(target.resolvedPath, 'utf8');
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          // Create directory structure if needed
+          if (target.createDirectories) {
+            await fs.mkdir(dirname(target.resolvedPath), { recursive: true });
+          }
+          return '';
+        }
+        throw error;
+      }
+    }
+
+    return await fs.readFile(target.resolvedPath, 'utf8');
+  }
+
+  async _commitOperation(operationId, results) {
+    const operation = this.activeOperations.get(operationId);
+    operation.phase = 'committed';
+    operation.endTime = Date.now();
+    operation.results = results;
+
+    // Record in history
+    this.operationHistory.push({
+      ...operation,
+      metadata: {
+        ...OPERATION_METADATA,
+        timestamp: new Date().toISOString(),
+        duration: operation.endTime - operation.startTime
+      }
+    });
+
+    // Clean up active operation
+    this.activeOperations.delete(operationId);
+  }
+
+  async _rollbackOperation(operationId, error) {
+    const operation = this.activeOperations.get(operationId);
+
+    if (operation) {
+      operation.phase = 'rolling-back';
+
+      try {
+        await this.rollbackManager.rollbackOperation(operationId, operation);
+        operation.phase = 'rolled-back';
+      } catch (rollbackError) {
+        operation.phase = 'rollback-failed';
+        operation.rollbackError = rollbackError.message;
+        console.error('Rollback failed:', rollbackError);
+      }
+
+      operation.error = error.message;
+      operation.endTime = Date.now();
+
+      // Record failed operation in history
+      this.operationHistory.push({ ...operation });
+      this.activeOperations.delete(operationId);
+    }
+  }
+
+  _wrapError(error, operationId) {
+    return new InjectionError(
+      error.message,
+      error.code || ERROR_CODES.ATOMIC_FAILURE,
+      operationId,
+      error
+    );
+  }
+}
+
+/**
+ * Custom error class for injection operations
+ */
+export class InjectionError extends Error {
+  constructor(message, code, operationId, originalError = null) {
+    super(message);
+    this.name = 'InjectionError';
+    this.code = code;
+    this.operationId = operationId;
+    this.originalError = originalError;
+    this.timestamp = new Date().toISOString();
+  }
+}