@unrdf/kgn 5.0.1 → 26.4.2

package/src/core/kgen-engine.js

@@ -1,6 +1,8 @@
 /**
- * KGEN Native Template Engine - Deterministic template processing without nunjucks
+ * @file KGEN Native Template Engine - Deterministic template processing without nunjucks
+ * @module @unrdf/kgn/core/kgen-engine
  *
+ * @description
  * Pipeline: plan → render → post → attest
  * Supports: Variables {{ var }}, conditionals {% if %}, loops {% for %}, filters {{ var | filter }}
  * Deterministic: All operations produce stable, reproducible output
@@ -13,7 +15,20 @@ import { KGenRenderer } from './renderer.js';
 import { KGenPostProcessor } from './post-processor.js';
 import { KGenAttestor } from './attestor.js';
 
+/**
+ * KGEN Template Engine - Main entry point for template processing
+ */
 export class KGenTemplateEngine {
+  /**
+   * Create a new KGenTemplateEngine instance
+   * @param {Object} [options={}] - Engine configuration options
+   * @param {boolean} [options.strictMode=true] - Enable strict mode validation
+   * @param {boolean} [options.deterministicMode=true] - Enable deterministic mode
+   * @param {string} [options.staticBuildTime='2024-01-01T00:00:00.000Z'] - Static timestamp for deterministic builds
+   * @param {number} [options.maxDepth=10] - Maximum template nesting depth
+   * @param {boolean} [options.enableIncludes=true] - Enable include statements
+   * @param {boolean} [options.enableAttestation=true] - Enable cryptographic attestation
+   */
   constructor(options = {}) {
     this.options = {
       strictMode: options.strictMode !== false,
@@ -38,6 +53,9 @@ export class KGenTemplateEngine {
 
   /**
    * PHASE 1: PLAN - Parse and analyze template
+   * @param {string} template - Template content to plan
+   * @param {Object} [context={}] - Context data for validation
+   * @returns {Promise<Object>} Plan result with parsed template, frontmatter, variables, expressions, includes, complexity, hash
    */
   async plan(template, context = {}) {
     try {
@@ -74,6 +92,9 @@ export class KGenTemplateEngine {
 
   /**
    * PHASE 2: RENDER - Execute template with context
+   * @param {Object} plan - Plan result from plan() phase
+   * @param {Object} [context={}] - Context data for rendering
+   * @returns {Promise<Object>} Render result with success, content, context, metadata
    */
   async render(plan, context = {}) {
     if (!plan.success) {
@@ -122,6 +143,8 @@ export class KGenTemplateEngine {
 
   /**
    * PHASE 3: POST - Post-process rendered content
+   * @param {Object} renderResult - Render result from render() phase
+   * @returns {Promise<Object>} Post-processed result with normalized content
    */
   async post(renderResult) {
     if (!renderResult.success) {
@@ -157,6 +180,8 @@ export class KGenTemplateEngine {
 
   /**
    * PHASE 4: ATTEST - Generate attestation of deterministic output
+   * @param {Object} postResult - Post-processed result from post() phase
+   * @returns {Promise<Object>} Attested result with cryptographic attestation
    */
   async attest(postResult) {
     if (!postResult.success || !this.options.enableAttestation) {
@@ -193,6 +218,9 @@ export class KGenTemplateEngine {
 
   /**
    * Complete pipeline: plan → render → post → attest
+   * @param {string} template - Template content to execute
+   * @param {Object} [context={}] - Context data for rendering
+   * @returns {Promise<Object>} Final result with all pipeline phases complete
    */
   async execute(template, context = {}) {
     const plan = await this.plan(template, context);
@@ -205,6 +233,9 @@ export class KGenTemplateEngine {
 
   /**
    * Simple render method for basic use cases
+   * @param {string} template - Template content to render
+   * @param {Object} [context={}] - Context data for rendering
+   * @returns {Promise<string>} Rendered content as string
    */
   async renderTemplate(template, context = {}) {
     // Use a simplified pipeline without post-processing for simple rendering
@@ -220,6 +251,7 @@ export class KGenTemplateEngine {
 
   /**
    * Register core filters
+   * Registers text, data, and format filters for template use
    */
   registerCoreFilters() {
     // Text filters
@@ -292,6 +324,11 @@ export class KGenTemplateEngine {
 
   /**
    * Calculate template complexity score
+   * @param {Object} parseResult - Parse result from parser
+   * @param {Array} [parseResult.variables=[]] - Variables in template
+   * @param {Array} [parseResult.expressions=[]] - Expressions in template
+   * @param {Array} [parseResult.includes=[]] - Includes in template
+   * @returns {number} Complexity score
    */
   calculateComplexity(parseResult) {
     const { variables = [], expressions = [], includes = [] } = parseResult;
@@ -300,6 +337,10 @@ export class KGenTemplateEngine {
 
   /**
    * Validate context has required variables
+   * @param {Array<string>} variables - Required variable names
+   * @param {Object} context - Context object to validate
+   * @param {Object} frontmatter - Frontmatter data
+   * @throws {Error} When required variables are missing
    */
   validateContext(variables, context, frontmatter) {
     const missing = [];
@@ -325,6 +366,8 @@ export class KGenTemplateEngine {
 
   /**
    * Generate deterministic content hash
+   * @param {string} content - Content to hash
+   * @returns {string} SHA-256 hash as hex string
    */
   hashContent(content) {
     return crypto.createHash('sha256').update(String(content || ''), 'utf8').digest('hex');
@@ -332,6 +375,7 @@ export class KGenTemplateEngine {
 
   /**
    * Get engine statistics
+   * @returns {Object} Engine configuration and statistics
    */
   getStats() {
     return {
@@ -343,6 +387,10 @@ export class KGenTemplateEngine {
 
   /**
    * Verify deterministic behavior across multiple runs
+   * @param {string} template - Template to verify
+   * @param {Object} context - Context for rendering
+   * @param {number} [iterations=3] - Number of iterations to test
+   * @returns {Promise<Object>} Verification result with isDeterministic, iterations, successfulRuns, uniqueOutputs, results
    */
   async verifyDeterminism(template, context, iterations = 3) {
     const results = [];

package/src/core/parser.js

@@ -1,6 +1,8 @@
 /**
- * KGEN Template Parser - Parse template syntax without nunjucks
+ * @file KGEN Template Parser - Parse template syntax without nunjucks
+ * @module @unrdf/kgn/core/parser
  *
+ * @description
  * Supports:
  * - Variables: {{ variable }}
  * - Filters: {{ variable | filter }}
@@ -12,7 +14,17 @@
 
 // Use existing frontmatter parser if available, fallback to basic parsing
 
+/**
+ * KGEN Template Parser class
+ */
 export class KGenParser {
+  /**
+   * Create a new KGenParser instance
+   * @param {Object} [options={}] - Parser configuration options
+   * @param {number} [options.maxDepth=10] - Maximum nesting depth for templates
+   * @param {boolean} [options.enableIncludes=true] - Enable include statement processing
+   * @param {boolean} [options.strictMode=true] - Enable strict syntax validation
+   */
   constructor(options = {}) {
     this.options = {
       maxDepth: options.maxDepth || 10,
@@ -32,6 +44,16 @@ export class KGenParser {
 
   /**
    * Parse template content into structured format
+   * @param {string} template - Template content to parse
+   * @returns {Promise<Object>} Parse result with template structure
+   * @returns {string} return.template - Parsed template content
+   * @returns {Object} return.frontmatter - Extracted frontmatter data
+   * @returns {Array<string>} return.variables - Extracted variable names
+   * @returns {Array<Object>} return.expressions - Extracted expressions
+   * @returns {Array<Object>} return.includes - Include statements
+   * @returns {Array<Object>} return.comments - Template comments
+   * @returns {Object} return.structure - Structural analysis
+   * @throws {Error} When parse error occurs
    */
   async parse(template) {
     try {
@@ -62,6 +84,10 @@ export class KGenParser {
 
   /**
    * Parse frontmatter from template
+   * @param {string} template - Template content with optional frontmatter
+   * @returns {Object} Frontmatter parse result
+   * @returns {Object} return.frontmatter - Parsed frontmatter data
+   * @returns {string} return.content - Template content without frontmatter
    */
   parseFrontmatter(template) {
     const match = template.match(this.patterns.frontmatter);
@@ -96,6 +122,8 @@ export class KGenParser {
 
   /**
    * Basic YAML parser for frontmatter (simplified)
+   * @param {string} yamlContent - YAML content to parse
+   * @returns {Object} Parsed YAML data as JavaScript object
    */
   parseBasicYAML(yamlContent) {
     const result = {};
@@ -134,6 +162,8 @@ export class KGenParser {
 
   /**
    * Extract variables from template content
+   * @param {string} content - Template content to analyze
+   * @returns {Array<string>} Array of required variable names
    */
   extractVariables(content) {
     const variables = new Set();
@@ -175,6 +205,8 @@ export class KGenParser {
 
   /**
    * Extract expressions (conditionals, loops, etc.)
+   * @param {string} content - Template content to analyze
+   * @returns {Array<Object>} Array of expression objects with type, expression, position, raw
    */
   extractExpressions(content) {
     const expressions = [];
@@ -200,6 +232,8 @@ export class KGenParser {
 
   /**
    * Extract include statements
+   * @param {string} content - Template content to analyze
+   * @returns {Array<Object>} Array of include objects with path, position, raw
    */
   extractIncludes(content) {
     const includes = [];
@@ -223,6 +257,8 @@ export class KGenParser {
 
   /**
    * Extract comments
+   * @param {string} content - Template content to analyze
+   * @returns {Array<Object>} Array of comment objects with text, position, raw
    */
   extractComments(content) {
     const comments = [];
@@ -244,6 +280,8 @@ export class KGenParser {
 
   /**
    * Analyze template structure
+   * @param {string} content - Template content to analyze
+   * @returns {Object} Structure analysis with conditionals, loops, includes, blocks, macros, depth counts
    */
   analyzeStructure(content) {
     const expressions = this.extractExpressions(content);
@@ -309,6 +347,8 @@ export class KGenParser {
 
   /**
    * Get expression type from expression string
+   * @param {string} expr - Expression string to classify
+   * @returns {string} Expression type (if, else, elif, endif, for, endfor, include, block, endblock, macro, endmacro, set, unknown)
    */
   getExpressionType(expr) {
     const trimmed = expr.trim().toLowerCase();
@@ -331,6 +371,8 @@ export class KGenParser {
 
   /**
    * Check if variable is a built-in
+   * @param {string} name - Variable name to check
+   * @returns {boolean} True if variable is a built-in
    */
   isBuiltinVariable(name) {
     const builtins = new Set([
@@ -342,6 +384,10 @@ export class KGenParser {
 
   /**
    * Validate template syntax
+   * @param {Object} parseResult - Parse result to validate
+   * @param {Array<Object>} parseResult.expressions - Expressions to validate
+   * @param {Object} parseResult.structure - Structure to validate
+   * @throws {Error} When syntax validation fails
    */
   validateSyntax(parseResult) {
     const { expressions } = parseResult;
@@ -402,6 +448,10 @@ export class KGenParser {
 
   /**
    * Check if template is deterministic
+   * @param {Object} parseResult - Parse result to check
+   * @param {Array<string>} parseResult.variables - Variables to check
+   * @param {Array<Object>} parseResult.expressions - Expressions to check
+   * @returns {Object} Result with deterministic boolean and reasons array
    */
   isDeterministic(parseResult) {
     const { variables, expressions } = parseResult;
@@ -435,6 +485,7 @@ export class KGenParser {
 
   /**
    * Get parser statistics
+   * @returns {Object} Parser configuration and supported patterns
    */
   getStats() {
     return {

package/src/core/post-processor.js

@@ -9,7 +9,13 @@
  * - Deterministic formatting
  */
 
+/**
+ *
+ */
 export class KGenPostProcessor {
+  /**
+   *
+   */
   constructor(options = {}) {
     this.options = {
       normalizeWhitespace: options.normalizeWhitespace !== false,
@@ -183,7 +189,7 @@ export class KGenPostProcessor {
     let hasSpaces = false;
     let hasTabs = false;
 
-    lines.forEach((line, index) => {
+    lines.forEach((line, _index) => {
       const indentMatch = line.match(/^(\s*)/);
       if (indentMatch && indentMatch[1]) {
         if (indentMatch[1].includes(' ')) hasSpaces = true;

package/src/core/renderer.js

@@ -1,6 +1,8 @@
 /**
- * KGEN Template Renderer - Execute template logic without nunjucks
+ * @file KGEN Template Renderer - Execute template logic without nunjucks
+ * @module @unrdf/kgn/core/renderer
  *
+ * @description
  * Handles:
  * - Variable interpolation: {{ variable }}
  * - Filter application: {{ variable | filter }}
@@ -9,7 +11,18 @@
  * - Include processing: {% include %}
  */
 
+/**
+ * KGEN Template Renderer class
+ */
 export class KGenRenderer {
+  /**
+   * Create a new KGenRenderer instance
+   * @param {Object} [options={}] - Renderer configuration options
+   * @param {number} [options.maxDepth=10] - Maximum rendering depth
+   * @param {boolean} [options.enableIncludes=true] - Enable include processing
+   * @param {boolean} [options.strictMode=true] - Enable strict error handling
+   * @param {boolean} [options.deterministicMode=true] - Enable deterministic mode
+   */
   constructor(options = {}) {
     this.options = {
       maxDepth: options.maxDepth || 10,
@@ -31,6 +44,11 @@ export class KGenRenderer {
 
   /**
    * Render template with context
+   * @param {string} template - Template content to render
+   * @param {Object} context - Context data for template variables
+   * @param {Object} [options={}] - Rendering options
+   * @param {Object} options.filters - Filter instance (required)
+   * @returns {Promise<Object>} Render result with content and metadata
    */
   async render(template, context, options = {}) {
     this.renderDepth = 0;
@@ -59,6 +77,11 @@ export class KGenRenderer {
 
   /**
    * Process template content recursively
+   * @param {string} template - Template content
+   * @param {Object} context - Context data
+   * @param {Object} filters - Filter instance
+   * @param {number} [depth=0] - Current recursion depth
+   * @returns {Promise<string>} Processed template content
    */
   async processTemplate(template, context, filters, depth = 0) {
     if (depth > this.options.maxDepth) {
@@ -83,6 +106,8 @@ export class KGenRenderer {
 
   /**
    * Remove template comments
+   * @param {string} template - Template content
+   * @returns {string} Template without comments
    */
   removeComments(template) {
     return template.replace(this.patterns.comment, '');
@@ -90,6 +115,11 @@ export class KGenRenderer {
 
   /**
    * Process template expressions (if, for, etc.)
+   * @param {string} template - Template content
+   * @param {Object} context - Context data
+   * @param {Object} filters - Filter instance
+   * @param {number} depth - Current recursion depth
+   * @returns {Promise<string>} Processed template
    */
   async processExpressions(template, context, filters, depth) {
     let processed = template;
@@ -110,6 +140,11 @@ export class KGenRenderer {
 
   /**
    * Process conditional expressions
+   * @param {string} template - Template content
+   * @param {Object} context - Context data
+   * @param {Object} filters - Filter instance
+   * @param {number} depth - Current recursion depth
+   * @returns {Promise<string>} Processed template with conditionals resolved
    */
   async processConditionals(template, context, filters, depth) {
     const ifPattern = /\{\%\s*if\s+([^%]+)\s*\%\}([\s\S]*?)(\{\%\s*else\s*\%\}([\s\S]*?))?\{\%\s*endif\s*\%\}/g;
@@ -155,6 +190,11 @@ export class KGenRenderer {
 
   /**
    * Process loop expressions
+   * @param {string} template - Template content
+   * @param {Object} context - Context data
+   * @param {Object} filters - Filter instance
+   * @param {number} depth - Current recursion depth
+   * @returns {Promise<string>} Processed template with loops expanded
    */
   async processLoops(template, context, filters, depth) {
     const forPattern = /\{\%\s*for\s+(\w+)\s+in\s+([^%]+)\s*\%\}([\s\S]*?)\{\%\s*endfor\s*\%\}/g;
@@ -235,6 +275,11 @@ export class KGenRenderer {
 
   /**
    * Process include expressions
+   * @param {string} template - Template content
+   * @param {Object} context - Context data
+   * @param {Object} filters - Filter instance
+   * @param {number} depth - Current recursion depth
+   * @returns {Promise<string>} Processed template with includes resolved
    */
   async processIncludes(template, context, filters, depth) {
     const includePattern = /\{\%\s*include\s+['"]([^'"]+)['"]\s*\%\}/g;
@@ -260,6 +305,10 @@ export class KGenRenderer {
 
   /**
    * Process variable interpolations and filters
+   * @param {string} template - Template content
+   * @param {Object} context - Context data
+   * @param {Object} filters - Filter instance
+   * @returns {string} Template with variables interpolated
    */
   processVariables(template, context, filters) {
     return template.replace(this.patterns.variable, (match, expression) => {
@@ -315,6 +364,9 @@ export class KGenRenderer {
 
   /**
    * Evaluate condition expression
+   * @param {string} condition - Condition expression to evaluate
+   * @param {Object} context - Context data
+   * @returns {boolean} Evaluation result
    */
   evaluateCondition(condition, context) {
     // Simple condition evaluation
@@ -341,6 +393,9 @@ export class KGenRenderer {
 
   /**
    * Evaluate expression to get value from context
+   * @param {string} expr - Expression to evaluate
+   * @param {Object} context - Context data
+   * @returns {*} Evaluated value
    */
   evaluateExpression(expr, context) {
     if (!expr) return '';
@@ -377,6 +432,8 @@ export class KGenRenderer {
 
   /**
    * Parse filter arguments from a comma-separated string, respecting quotes
+   * @param {string} argsStr - Arguments string
+   * @returns {Array<string>} Parsed arguments
    */
   parseFilterArguments(argsStr) {
     const args = [];
@@ -412,6 +469,9 @@ export class KGenRenderer {
 
   /**
    * Parse argument value (string, number, or variable reference)
+   * @param {string} arg - Argument to parse
+   * @param {Object} context - Context data
+   * @returns {*} Parsed value
    */
   parseArgument(arg, context) {
     // Handle quoted strings
@@ -435,6 +495,9 @@ export class KGenRenderer {
 
   /**
    * Parse value with context substitution
+   * @param {string} value - Value to parse
+   * @param {Object} context - Context data
+   * @returns {*} Parsed value
    */
   parseValue(value, context) {
     return this.parseArgument(value, context);
@@ -442,6 +505,8 @@ export class KGenRenderer {
 
   /**
    * Check if value is truthy in template context
+   * @param {*} value - Value to check
+   * @returns {boolean} True if value is truthy
    */
   isTruthy(value) {
     if (value === null || value === undefined) return false;
@@ -456,6 +521,7 @@ export class KGenRenderer {
 
   /**
    * Get renderer statistics
+   * @returns {Object} Renderer configuration and statistics
    */
   getStats() {
     return {

package/src/doc-generator/mdx-generator.mjs

@@ -6,7 +6,7 @@
 import nunjucks from 'nunjucks';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { readFileSync } from 'fs';
+import { readFileSync as _readFileSync } from 'fs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);

package/src/doc-generator/nav-generator.mjs

@@ -11,7 +11,7 @@
  */
 export function generateNavigation(groupedFiles, options = {}) {
   const {
-    rootTitle = 'API Reference',
+    rootTitle: _rootTitle = 'API Reference',
     includeIndex = true,
   } = options;
 

package/src/doc-generator/rdf-builder.mjs

@@ -76,7 +76,7 @@ export function buildRDFGraph(parsedFile) {
   triples.push('');
 
   // Exports
-  parsedFile.exports.forEach((exp, idx) => {
+  parsedFile.exports.forEach((exp, _idx) => {
     const exportURI = `${fileURI}#${exp.name}`;
 
     triples.push(`# Export: ${exp.name}`);
@@ -131,7 +131,7 @@ export function buildRDFGraph(parsedFile) {
       }
 
       // Examples
-      exp.examples?.forEach((example, exIdx) => {
+      exp.examples?.forEach((example, _exIdx) => {
         triples.push(`  doc:example ${escapeLiteral(example)} ;`);
       });
 

package/src/engine/index.js

@@ -5,11 +5,20 @@
  * 100% Deterministic guarantees with cryptographic attestation
  */
 
+// Import classes for local use
+import { TemplateEngine } from './template-engine.js';
+import { DeterministicRenderer } from './renderer.js';
+import { DeterministicPipeline } from './pipeline.js';
+
+// Re-export for external use
 export { TemplateEngine } from './template-engine.js';
 export { DeterministicRenderer } from './renderer.js';
 export { DeterministicPipeline } from './pipeline.js';
 
 // Factory for deterministic engine with complete pipeline
+/**
+ *
+ */
 export function createDeterministicEngine(options = {}) {
   const pipeline = new DeterministicPipeline(options);
 

package/src/engine/pipeline.js

@@ -17,7 +17,13 @@
 
 import { DeterministicRenderer } from './renderer.js';
 
+/**
+ *
+ */
 export class DeterministicPipeline {
+  /**
+   *
+   */
   constructor(options = {}) {
     this.renderer = new DeterministicRenderer(options);
     this.enableValidation = options.enableValidation !== false;
@@ -348,7 +354,7 @@ export class DeterministicPipeline {
   /**
    * Verify pipeline result integrity
    */
-  async _verifyPipelineResult(attestResult, template, data) {
+  async _verifyPipelineResult(attestResult, _template, _data) {
     const expectedHash = this.renderer._hashContent(attestResult.content);
     const actualHash = attestResult.contentHash;
     

package/src/engine/renderer.js

@@ -17,7 +17,13 @@
 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';
@@ -388,7 +394,7 @@ export class DeterministicRenderer {
   /**
    * Validate data context against template requirements
    */
-  _validateDataContext(data, variables) {
+  _validateDataContext(data, _variables) {
     const validated = { ...data };
     
     // Add deterministic metadata
@@ -479,7 +485,7 @@ export class DeterministicRenderer {
   /**
    * Execute main template rendering
    */
-  async _executeRender(plan, context, includes) {
+  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} -->`;
@@ -547,6 +553,9 @@ export class DeterministicRenderer {
 
   // DEFAULT DEPENDENCY IMPLEMENTATIONS (for production use)
 
+  /**
+   *
+   */
   _createDefaultLoader() {
     return {
       async load(templatePath) {
@@ -556,6 +565,9 @@ export class DeterministicRenderer {
     };
   }
 
+  /**
+   *
+   */
   _createDefaultResolver() {
     return {
       resolve(includePath, basePath) {
@@ -564,9 +576,12 @@ export class DeterministicRenderer {
     };
   }
 
+  /**
+   *
+   */
   _createDefaultProvider() {
     return {
-      async query(sparqlQuery) {
+      async query(_sparqlQuery) {
         // Default implementation - could integrate with RDF stores
         return [];
       }

package/src/engine/template-engine.js

@@ -23,9 +23,9 @@
 import nunjucks from 'nunjucks';
 import crypto from 'crypto';
 import path from 'path';
-import { Worker, isMainThread } from 'worker_threads';
-import { Transform } from 'stream';
-import { performance } from 'perf_hooks';
+import { Worker as _Worker, isMainThread as _isMainThread } from 'worker_threads';
+import { Transform as _Transform } from 'stream';
+import { performance as _performance } from 'perf_hooks';
 import { createCustomFilters } from '../filters/index.js';
 import { FrontmatterParser } from '../parser/frontmatter.js';
 import { VariableExtractor } from '../parser/variables.js';
@@ -150,7 +150,13 @@ class TemplateContextPool {
   }
 }
 
+/**
+ *
+ */
 export class TemplateEngine {
+  /**
+   *
+   */
   constructor(options = {}) {
     this.templatesDir = options.templatesDir || './templates';
     this.enableCache = options.enableCache !== false;
@@ -503,6 +509,9 @@ export class TemplateEngine {
  * Wrapper that provides both basic and inheritance-enabled rendering
  */
 export class EnhancedTemplateEngine extends TemplateEngine {
+  /**
+   *
+   */
   constructor(options = {}) {
     super({
       ...options,