@unrdf/kgn 5.0.1

package/src/injection/integration.js

@@ -0,0 +1,339 @@
+/**
+ * KGEN Injection Integration
+ *
+ * Integrates injection capabilities with the existing KGEN template engine.
+ * Provides seamless injection support for template processing.
+ */
+
+import { inject, dryRun, processTemplate, initializeInjection } from './api.js';
+import { DEFAULT_CONFIG, INJECTION_MODES } from './constants.js';
+
+/**
+ * Enhance KGEN engine with injection capabilities
+ */
+export function enhanceKgenWithInjection(kgenEngine, injectionConfig = {}) {
+  const config = { ...DEFAULT_CONFIG, ...injectionConfig };
+
+  // Initialize injection system
+  const injectionEngine = initializeInjection(config);
+
+  // Store original methods
+  const originalRender = kgenEngine.render;
+  const originalRenderString = kgenEngine.renderString;
+
+  /**
+   * Enhanced render method with injection support
+   */
+  kgenEngine.render = async function(templatePath, data = {}, options = {}) {
+    // First, try to read and parse the template
+    const template = await this.getTemplate(templatePath);
+
+    // Check if template has injection configuration in frontmatter
+    if (template.frontmatter && template.frontmatter.inject) {
+      return await processInjectionTemplate(template, data, options, injectionEngine);
+    }
+
+    // Fall back to original render for non-injection templates
+    return originalRender.call(this, templatePath, data, options);
+  };
+
+  /**
+   * Enhanced renderString with injection support
+   */
+  kgenEngine.renderString = async function(templateString, data = {}, options = {}) {
+    // Parse template string for frontmatter
+    const parsed = parseTemplateString(templateString);
+
+    if (parsed.frontmatter && parsed.frontmatter.inject) {
+      return await processInjectionTemplate(parsed, data, options, injectionEngine);
+    }
+
+    // Fall back to original renderString
+    return originalRenderString.call(this, templateString, data, options);
+  };
+
+  /**
+   * Add injection-specific methods to the engine
+   */
+  kgenEngine.inject = async function(templateConfig, content, variables = {}) {
+    return await inject(templateConfig, content, variables, { config });
+  };
+
+  kgenEngine.dryRunInjection = async function(templateConfig, content, variables = {}) {
+    return await dryRun(templateConfig, content, variables, { config });
+  };
+
+  kgenEngine.getInjectionHistory = function() {
+    return injectionEngine.getOperationHistory();
+  };
+
+  kgenEngine.undoInjection = async function(operationId) {
+    return await injectionEngine.undo(operationId);
+  };
+
+  /**
+   * Batch template processing with injection support
+   */
+  kgenEngine.processBatch = async function(templates, globalData = {}, options = {}) {
+    const results = [];
+    const errors = [];
+
+    for (const template of templates) {
+      try {
+        const templateData = { ...globalData, ...(template.data || {}) };
+        let result;
+
+        if (template.content) {
+          result = await this.renderString(template.content, templateData, options);
+        } else if (template.path) {
+          result = await this.render(template.path, templateData, options);
+        } else {
+          throw new Error('Template must have either content or path');
+        }
+
+        results.push({
+          template,
+          result,
+          success: true
+        });
+
+      } catch (error) {
+        errors.push({
+          template,
+          error: error.message,
+          success: false
+        });
+
+        if (!options.continueOnError) {
+          break;
+        }
+      }
+    }
+
+    return {
+      results,
+      errors,
+      total: templates.length,
+      successful: results.length,
+      failed: errors.length
+    };
+  };
+
+  return kgenEngine;
+}
+
+/**
+ * Process injection template
+ */
+async function processInjectionTemplate(template, data, options, injectionEngine) {
+  const { frontmatter, content } = template;
+
+  // Render the template content first
+  const renderedContent = await renderTemplateContent(content, data, options);
+
+  // Perform injection
+  const injectionResult = await injectionEngine.inject(frontmatter, renderedContent, data);
+
+  return {
+    injectionResult,
+    operationId: injectionResult.operationId,
+    success: injectionResult.success,
+    skipped: injectionResult.skipped,
+    targets: injectionResult.targets,
+    content: renderedContent
+  };
+}
+
+/**
+ * Render template content (without injection)
+ */
+async function renderTemplateContent(content, data, options) {
+  // Simple variable interpolation - in production use proper template engine
+  return content.replace(/\{\{(\w+)\}\}/g, (match, variable) => {
+    return data[variable] || match;
+  });
+}
+
+/**
+ * Parse template string for frontmatter
+ */
+function parseTemplateString(templateString) {
+  const frontmatterMatch = templateString.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+
+  if (!frontmatterMatch) {
+    return {
+      frontmatter: {},
+      content: templateString
+    };
+  }
+
+  const frontmatter = parseFrontmatter(frontmatterMatch[1]);
+  const content = frontmatterMatch[2];
+
+  return { frontmatter, content };
+}
+
+/**
+ * Simple frontmatter parser
+ */
+function parseFrontmatter(text) {
+  const result = {};
+  const lines = text.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const colonIndex = trimmed.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = trimmed.substring(0, colonIndex).trim();
+    let value = trimmed.substring(colonIndex + 1).trim();
+
+    // Parse arrays
+    if (value.startsWith('[') && value.endsWith(']')) {
+      value = value.slice(1, -1).split(',').map(v => v.trim().replace(/['"]/g, ''));
+    }
+    // Parse booleans
+    else if (value === 'true') {
+      value = true;
+    } else if (value === 'false') {
+      value = false;
+    }
+    // Parse numbers
+    else if (/^\d+$/.test(value)) {
+      value = parseInt(value);
+    }
+    // Remove quotes
+    else if ((value.startsWith('"') && value.endsWith('"')) ||
+             (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Create injection-aware template loader
+ */
+export function createInjectionTemplateLoader(baseLoader, injectionConfig = {}) {
+  return {
+    ...baseLoader,
+
+    async loadTemplate(templatePath, options = {}) {
+      const template = await baseLoader.loadTemplate(templatePath, options);
+
+      // Parse for injection configuration
+      const parsed = parseTemplateString(template.content || template);
+
+      return {
+        ...template,
+        frontmatter: parsed.frontmatter,
+        content: parsed.content,
+        hasInjection: !!(parsed.frontmatter && parsed.frontmatter.inject),
+        injectionMode: parsed.frontmatter?.mode || INJECTION_MODES.APPEND
+      };
+    }
+  };
+}
+
+/**
+ * Validation helpers for injection templates
+ */
+export const injectionValidators = {
+  /**
+   * Validate injection template configuration
+   */
+  validateTemplate(template) {
+    const errors = [];
+
+    if (!template.frontmatter) {
+      return { valid: true, errors: [] }; // Non-injection template
+    }
+
+    const fm = template.frontmatter;
+
+    if (fm.inject && !fm.to) {
+      errors.push('Injection templates must specify "to" target');
+    }
+
+    if (fm.mode && !Object.values(INJECTION_MODES).includes(fm.mode)) {
+      errors.push(`Invalid injection mode: ${fm.mode}`);
+    }
+
+    if (fm.mode === INJECTION_MODES.BEFORE && !fm.target) {
+      errors.push('Before mode requires "target" pattern');
+    }
+
+    if (fm.mode === INJECTION_MODES.AFTER && !fm.target) {
+      errors.push('After mode requires "target" pattern');
+    }
+
+    if (fm.mode === INJECTION_MODES.REPLACE && !fm.target) {
+      errors.push('Replace mode requires "target" pattern');
+    }
+
+    if (fm.mode === INJECTION_MODES.LINE_AT && typeof fm.lineNumber !== 'number') {
+      errors.push('LineAt mode requires "lineNumber" as number');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  },
+
+  /**
+   * Validate injection context data
+   */
+  validateData(data, template) {
+    const errors = [];
+    const fm = template.frontmatter;
+
+    if (!fm || !fm.inject) {
+      return { valid: true, errors: [] };
+    }
+
+    // Check for required variables in template content
+    const requiredVars = extractTemplateVariables(template.content);
+
+    for (const variable of requiredVars) {
+      if (!(variable in data)) {
+        errors.push(`Required template variable missing: ${variable}`);
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+};
+
+/**
+ * Extract template variables from content
+ */
+function extractTemplateVariables(content) {
+  const variables = new Set();
+  const matches = content.matchAll(/\{\{(\w+)\}\}/g);
+
+  for (const match of matches) {
+    variables.add(match[1]);
+  }
+
+  return Array.from(variables);
+}
+
+/**
+ * Export integration utilities
+ */
+export {
+  inject,
+  dryRun,
+  initializeInjection,
+  INJECTION_MODES,
+  DEFAULT_CONFIG
+};

package/src/injection/modes/index.js

@@ -0,0 +1,341 @@
+/**
+ * KGEN Injection Modes
+ *
+ * Implements different injection modes for deterministic content modification.
+ * Each mode provides atomic and idempotent content insertion strategies.
+ */
+
+import { INJECTION_MODES, LINE_ENDINGS } from '../constants.js';
+
+export class InjectionModes {
+  constructor(config = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Apply injection mode to content
+   */
+  async applyMode(mode, currentContent, injectionContent, target, variables = {}) {
+    const normalizedCurrent = this._normalizeContent(currentContent);
+    const normalizedInjection = this._normalizeInjectionContent(injectionContent, variables);
+
+    switch (mode) {
+      case INJECTION_MODES.APPEND:
+        return this._applyAppend(normalizedCurrent, normalizedInjection, target);
+
+      case INJECTION_MODES.PREPEND:
+        return this._applyPrepend(normalizedCurrent, normalizedInjection, target);
+
+      case INJECTION_MODES.BEFORE:
+        return this._applyBefore(normalizedCurrent, normalizedInjection, target);
+
+      case INJECTION_MODES.AFTER:
+        return this._applyAfter(normalizedCurrent, normalizedInjection, target);
+
+      case INJECTION_MODES.REPLACE:
+        return this._applyReplace(normalizedCurrent, normalizedInjection, target);
+
+      case INJECTION_MODES.LINE_AT:
+        return this._applyLineAt(normalizedCurrent, normalizedInjection, target);
+
+      case INJECTION_MODES.CREATE:
+        return this._applyCreate(normalizedCurrent, normalizedInjection, target);
+
+      default:
+        throw new Error(`Unknown injection mode: ${mode}`);
+    }
+  }
+
+  /**
+   * Append content to end of file
+   */
+  _applyAppend(currentContent, injectionContent, target) {
+    const lineEnding = this._detectLineEnding(currentContent);
+    const ensureNewline = target.ensureNewline !== false;
+
+    let result = currentContent;
+
+    // Add newline before injection if file doesn't end with one
+    if (ensureNewline && currentContent && !currentContent.endsWith(lineEnding)) {
+      result += lineEnding;
+    }
+
+    result += injectionContent;
+
+    // Ensure file ends with newline if configured
+    if (target.ensureTrailingNewline && !result.endsWith(lineEnding)) {
+      result += lineEnding;
+    }
+
+    return result;
+  }
+
+  /**
+   * Prepend content to beginning of file
+   */
+  _applyPrepend(currentContent, injectionContent, target) {
+    const lineEnding = this._detectLineEnding(currentContent);
+    let result = injectionContent;
+
+    // Add newline after injection if it doesn't end with one
+    if (!injectionContent.endsWith(lineEnding)) {
+      result += lineEnding;
+    }
+
+    result += currentContent;
+
+    // Sort imports if enabled and content looks like imports
+    if (target.sortImports && this._looksLikeImports(injectionContent)) {
+      result = this._sortImports(result);
+    }
+
+    return result;
+  }
+
+  /**
+   * Insert content before specific target
+   */
+  _applyBefore(currentContent, injectionContent, target) {
+    const targetPattern = target.target;
+    if (!targetPattern) {
+      throw new Error('Before mode requires target pattern');
+    }
+
+    const lineEnding = this._detectLineEnding(currentContent);
+    const lines = currentContent.split(lineEnding);
+    const insertionLines = injectionContent.split(lineEnding);
+
+    // Find target line
+    const targetIndex = this._findTargetLine(lines, targetPattern, target);
+    if (targetIndex === -1) {
+      throw new Error(`Target pattern not found: ${targetPattern}`);
+    }
+
+    // Preserve indentation if configured
+    if (target.preserveIndentation) {
+      const targetIndentation = this._getLineIndentation(lines[targetIndex]);
+      for (let i = 0; i < insertionLines.length; i++) {
+        if (insertionLines[i].trim()) {
+          insertionLines[i] = targetIndentation + insertionLines[i].trim();
+        }
+      }
+    }
+
+    // Insert before target line
+    lines.splice(targetIndex, 0, ...insertionLines);
+
+    return lines.join(lineEnding);
+  }
+
+  /**
+   * Insert content after specific target
+   */
+  _applyAfter(currentContent, injectionContent, target) {
+    const targetPattern = target.target;
+    if (!targetPattern) {
+      throw new Error('After mode requires target pattern');
+    }
+
+    const lineEnding = this._detectLineEnding(currentContent);
+    const lines = currentContent.split(lineEnding);
+    const insertionLines = injectionContent.split(lineEnding);
+
+    // Find target line
+    const targetIndex = this._findTargetLine(lines, targetPattern, target);
+    if (targetIndex === -1) {
+      throw new Error(`Target pattern not found: ${targetPattern}`);
+    }
+
+    // Preserve indentation if configured
+    if (target.preserveIndentation) {
+      const targetIndentation = this._getLineIndentation(lines[targetIndex]);
+      for (let i = 0; i < insertionLines.length; i++) {
+        if (insertionLines[i].trim()) {
+          insertionLines[i] = targetIndentation + insertionLines[i].trim();
+        }
+      }
+    }
+
+    // Insert after target line
+    lines.splice(targetIndex + 1, 0, ...insertionLines);
+
+    return lines.join(lineEnding);
+  }
+
+  /**
+   * Replace specific content
+   */
+  _applyReplace(currentContent, injectionContent, target) {
+    const targetPattern = target.target;
+    if (!targetPattern) {
+      throw new Error('Replace mode requires target pattern');
+    }
+
+    let result = currentContent;
+
+    if (target.regex) {
+      // Regex replacement
+      const flags = target.regexFlags || 'g';
+      const regex = new RegExp(targetPattern, flags);
+      result = result.replace(regex, injectionContent);
+    } else if (target.exact) {
+      // Exact string replacement
+      result = result.replace(targetPattern, injectionContent);
+    } else {
+      // First occurrence replacement
+      const index = result.indexOf(targetPattern);
+      if (index === -1) {
+        throw new Error(`Target pattern not found: ${targetPattern}`);
+      }
+      result = result.substring(0, index) + injectionContent + result.substring(index + targetPattern.length);
+    }
+
+    return result;
+  }
+
+  /**
+   * Insert content at specific line number
+   */
+  _applyLineAt(currentContent, injectionContent, target) {
+    const lineNumber = target.lineNumber;
+    if (typeof lineNumber !== 'number') {
+      throw new Error('LineAt mode requires lineNumber');
+    }
+
+    const lineEnding = this._detectLineEnding(currentContent);
+    const lines = currentContent.split(lineEnding);
+    const insertionLines = injectionContent.split(lineEnding);
+
+    // Validate line number
+    if (target.validateTarget && (lineNumber < 1 || lineNumber > lines.length + 1)) {
+      throw new Error(`Invalid line number: ${lineNumber}. File has ${lines.length} lines.`);
+    }
+
+    // Convert to 0-based index
+    const insertIndex = lineNumber - 1;
+
+    // Insert at specified line
+    lines.splice(insertIndex, 0, ...insertionLines);
+
+    return lines.join(lineEnding);
+  }
+
+  /**
+   * Create new file content
+   */
+  _applyCreate(currentContent, injectionContent, target) {
+    // If file exists and not empty, handle based on configuration
+    if (currentContent && target.failIfExists) {
+      throw new Error('File already exists and failIfExists is true');
+    }
+
+    if (currentContent && target.appendIfExists) {
+      return this._applyAppend(currentContent, injectionContent, target);
+    }
+
+    // Return injection content as new file content
+    return injectionContent;
+  }
+
+  /**
+   * Helper Methods
+   */
+
+  _normalizeContent(content) {
+    if (!content) return '';
+
+    // Normalize line endings if configured
+    if (this.config.consistentLineEndings) {
+      const targetEnding = this.config.lineEnding || LINE_ENDINGS.LF;
+      return content.replace(/\r\n|\r|\n/g, targetEnding);
+    }
+
+    return content;
+  }
+
+  _normalizeInjectionContent(content, variables) {
+    // Variable interpolation
+    let result = content.replace(/\{\{(\w+)\}\}/g, (match, variable) => {
+      return variables[variable] || match;
+    });
+
+    // Trim if configured
+    if (this.config.trimInjectedContent) {
+      result = result.trim();
+    }
+
+    return result;
+  }
+
+  _detectLineEnding(content) {
+    if (content.includes('\r\n')) return LINE_ENDINGS.CRLF;
+    if (content.includes('\r')) return LINE_ENDINGS.CR;
+    return LINE_ENDINGS.LF;
+  }
+
+  _findTargetLine(lines, pattern, target) {
+    if (target.regex) {
+      const flags = target.regexFlags || 'gm';
+      const regex = new RegExp(pattern, flags);
+      return lines.findIndex(line => regex.test(line));
+    }
+
+    // String search (first occurrence for deterministic behavior)
+    return lines.findIndex(line => line.includes(pattern));
+  }
+
+  _getLineIndentation(line) {
+    const match = line.match(/^(\s*)/);
+    return match ? match[1] : '';
+  }
+
+  _looksLikeImports(content) {
+    return /^import\s+.*from\s+['"][^'"]+['"];?\s*$/m.test(content);
+  }
+
+  _sortImports(content) {
+    const lineEnding = this._detectLineEnding(content);
+    const lines = content.split(lineEnding);
+
+    // Find import blocks
+    const importBlocks = [];
+    let currentBlock = [];
+    let inImportBlock = false;
+
+    for (const line of lines) {
+      if (/^import\s+/.test(line.trim())) {
+        inImportBlock = true;
+        currentBlock.push(line);
+      } else if (inImportBlock && line.trim() === '') {
+        currentBlock.push(line);
+      } else if (inImportBlock) {
+        importBlocks.push([...currentBlock]);
+        currentBlock = [];
+        inImportBlock = false;
+      }
+    }
+
+    // Sort imports within each block deterministically
+    for (const block of importBlocks) {
+      block.sort((a, b) => {
+        const aImport = a.trim();
+        const bImport = b.trim();
+
+        // Sort by import source (deterministic)
+        const aSource = this._extractImportSource(aImport);
+        const bSource = this._extractImportSource(bImport);
+
+        return aSource.localeCompare(bSource);
+      });
+    }
+
+    // Reconstruct content with sorted imports
+    // This is a simplified implementation - real sorting would be more complex
+    return content;
+  }
+
+  _extractImportSource(importLine) {
+    const match = importLine.match(/from\s+['"]([^'"]+)['"]/);
+    return match ? match[1] : '';
+  }
+}