@unrdf/kgn 5.0.1 → 26.4.3

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@unrdf/kgn",
-  "version": "5.0.1",
+  "version": "26.4.3",
   "description": "Deterministic Nunjucks template system with custom filters and frontmatter support",
   "type": "module",
-  "main": "src/index.js",
+  "main": "dist/index.mjs",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./src/index.js"
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
     },
     "./engine": {
       "import": "./src/engine/index.js"
@@ -23,26 +25,27 @@
     "./templates/*": "./src/templates/*"
   },
   "dependencies": {
+    "@unrdf/core": "26.4.3",
     "fs-extra": "^11.3.1",
     "gray-matter": "^4.0.3",
     "nunjucks": "^3.2.4",
     "yaml": "^2.8.1",
-    "@unrdf/core": "5.0.1",
-    "@unrdf/test-utils": "5.0.1"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@amiceli/vitest-cucumber": "^4.1.1",
+    "@amiceli/vitest-cucumber": "^6.2.0",
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",
     "comment-parser": "^1.4.1",
     "eslint": "^8.56.0",
     "nodemon": "^3.0.1",
-    "vitest": "^2.1.9"
+    "vitest": "^4.0.16"
   },
   "engines": {
     "node": ">=18.0.0",
-    "pnpm": ">=8.0.0"
+    "pnpm": ">=7.0.0"
   },
+  "sideEffects": false,
   "keywords": [
     "unrdf",
     "kgn",
@@ -57,13 +60,13 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/seanchatmangpt/unrdf.git",
+    "url": "https://github.com/unrdf/unrdf.git",
     "directory": "packages/kgn"
   },
   "bugs": {
-    "url": "https://github.com/seanchatmangpt/unrdf/issues"
+    "url": "https://github.com/unrdf/unrdf/issues"
   },
-  "homepage": "https://github.com/seanchatmangpt/unrdf#readme",
+  "homepage": "https://github.com/unrdf/unrdf#readme",
   "files": [
     "src/",
     "README.md"
@@ -72,7 +75,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "echo '@unrdf/kgn - ES modules verified'",
+    "build": "unbuild && tsc --emitDeclarationOnly || true",
+    "build:types": "tsc --emitDeclarationOnly",
     "build:watch": "nodemon --watch src --exec 'npm run build'",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -80,8 +84,8 @@
     "test:cucumber:watch": "vitest --config vitest.cucumber.config.js --watch",
     "test:all": "npm run test && npm run test:cucumber",
     "test:coverage": "vitest run --coverage",
-    "lint": "eslint src/ --ext .js,.mjs",
-    "lint:fix": "eslint src/ --ext .js,.mjs --fix",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
     "dev": "nodemon --watch src --exec 'echo @unrdf/kgn dev mode - watching for changes'",
     "typecheck": "echo '@unrdf/kgn - JavaScript validation not configured'",
     "clean": "rm -rf coverage .nyc_output dist build",

package/src/base/filter-templates.js

@@ -5,9 +5,15 @@
  * All filter templates are designed to be composable and reusable
  */
 
-import crypto from 'crypto';
+import _crypto from 'crypto';
 
+/**
+ *
+ */
 export class KGenFilterTemplates {
+  /**
+   *
+   */
   constructor(options = {}) {
     this.options = {
       deterministicMode: options.deterministicMode !== false,

package/src/base/index.js

@@ -1,31 +1,36 @@
 /**
  * KGEN Base Templates - Foundation template system
- * 
+ *
  * Exports all base template classes and utilities for building
  * deterministic, reusable template components
  */
 
-// Base template foundation
-export { KGenTemplateBase } from './template-base.js';
+// Import classes for local use
+import { KGenTemplateBase } from './template-base.js';
+import { KGenMacroTemplates } from './macro-templates.js';
+import { KGenFilterTemplates } from './filter-templates.js';
+import { KGenSHACLTemplates } from './shacl-templates.js';
+import { KGenInjectionTargets } from './injection-targets.js';
 
-// Macro system for reusable components
+// Re-export for external use
+export { KGenTemplateBase } from './template-base.js';
 export { KGenMacroTemplates } from './macro-templates.js';
-
-// Filter system for deterministic data processing
 export { KGenFilterTemplates } from './filter-templates.js';
-
-// SHACL validation templates for RDF knowledge graphs
 export { KGenSHACLTemplates } from './shacl-templates.js';
-
-// Injection targets for code modification
 export { KGenInjectionTargets } from './injection-targets.js';
 
 // Convenience factory function
+/**
+ *
+ */
 export function createBaseTemplate(options = {}) {
   return new KGenTemplateBase(options);
 }
 
 // Template system factory
+/**
+ *
+ */
 export function createTemplateSystem(options = {}) {
   const base = new KGenTemplateBase(options);
   const macros = new KGenMacroTemplates(options);

package/src/base/injection-targets.js

@@ -5,7 +5,13 @@
  * Supports marker-based, semantic-based, and position-based injection strategies
  */
 
+/**
+ *
+ */
 export class KGenInjectionTargets {
+  /**
+   *
+   */
   constructor(options = {}) {
     this.options = {
       deterministicMode: options.deterministicMode !== false,

package/src/base/macro-templates.js

@@ -5,7 +5,13 @@
  * All macros are deterministic and compatible with KGEN template engine
  */
 
+/**
+ *
+ */
 export class KGenMacroTemplates {
+  /**
+   *
+   */
   constructor(options = {}) {
     this.options = {
       deterministicMode: options.deterministicMode !== false,

package/src/base/shacl-templates.js

@@ -5,7 +5,13 @@
  * for validating RDF knowledge graphs used in KGEN template generation
  */
 
+/**
+ *
+ */
 export class KGenSHACLTemplates {
+  /**
+   *
+   */
   constructor(options = {}) {
     this.options = {
       deterministicMode: options.deterministicMode !== false,

package/src/base/template-base.js

@@ -9,7 +9,13 @@ import crypto from 'crypto';
 import { KGenTemplateEngine } from '../core/kgen-engine.js';
 import { TemplateInheritanceEngine } from '../inheritance/index.js';
 
+/**
+ *
+ */
 export class KGenTemplateBase {
+  /**
+   *
+   */
   constructor(options = {}) {
     this.options = {
       strictMode: options.strictMode !== false,
@@ -231,7 +237,7 @@ export default {{ moduleName }};
   /**
    * Generate template from registered template
    */
-  async generateFromTemplate(templateName, context = {}, options = {}) {
+  async generateFromTemplate(templateName, context = {}, _options = {}) {
     if (!this.templates.has(templateName)) {
       throw new Error(`Template '${templateName}' not found`);
     }

package/src/core/attestor.js

@@ -1,6 +1,8 @@
 /**
- * KGEN Attestor - Generate cryptographic attestations for deterministic output
+ * @file KGEN Attestor - Generate cryptographic attestations for deterministic output
+ * @module @unrdf/kgn/core/attestor
  *
+ * @description
  * Provides:
  * - Content integrity verification
  * - Deterministic output attestation
@@ -10,7 +12,21 @@
 
 import crypto from 'crypto';
 
+/**
+ * KGEN Attestor class - Cryptographic attestation system
+ */
 export class KGenAttestor {
+  /**
+   * Create a new KGenAttestor instance
+   * @param {Object} [options={}] - Attestor configuration options
+   * @param {boolean} [options.enableAttestation=true] - Enable attestation generation
+   * @param {string} [options.algorithm='sha256'] - Hash algorithm to use
+   * @param {string} [options.attestorId='kgen-templates'] - Attestor identifier
+   * @param {string} [options.version='2.0.0'] - Attestor version
+   * @param {string} [options.staticBuildTime] - Static timestamp for deterministic mode
+   * @param {boolean} [options.deterministicMode=true] - Enable deterministic mode
+   * @param {boolean} [options.includeMetadata=true] - Include additional metadata
+   */
   constructor(options = {}) {
     this.options = {
       enableAttestation: options.enableAttestation !== false,
@@ -26,6 +42,9 @@ export class KGenAttestor {
 
   /**
    * Generate attestation for rendered content
+   * @param {string} content - Content to attest
+   * @param {Object} [context={}] - Context data for attestation
+   * @returns {Promise<Object>} Attestation result
    */
   async attest(content, context = {}) {
     if (!this.options.enableAttestation) {
@@ -61,6 +80,9 @@ export class KGenAttestor {
 
   /**
    * Create complete attestation record
+   * @param {string} content - Content to attest
+   * @param {Object} [context={}] - Context data
+   * @returns {Promise<Object>} Complete attestation record
    */
   async createAttestation(content, context = {}) {
     const contentHash = this.createContentHash(content);
@@ -104,6 +126,9 @@ export class KGenAttestor {
 
   /**
    * Verify attestation integrity
+   * @param {string} content - Content to verify
+   * @param {Object} attestation - Attestation to verify against
+   * @returns {Promise<Object>} Verification result
    */
   async verify(content, attestation) {
     try {
@@ -159,6 +184,10 @@ export class KGenAttestor {
 
   /**
    * Create reproducibility proof
+   * @param {string} content - Content to test reproducibility
+   * @param {Object} context - Context data
+   * @param {number} [iterations=3] - Number of iterations to test
+   * @returns {Promise<Object>} Reproducibility proof
    */
   async createReproducibilityProof(content, context, iterations = 3) {
     const proofs = [];
@@ -194,6 +223,8 @@ export class KGenAttestor {
 
   /**
    * Create audit trail for template execution
+   * @param {Array<Object>} [steps=[]] - Execution steps to audit
+   * @returns {Object} Audit trail record
    */
   createAuditTrail(steps = []) {
     return {
@@ -214,6 +245,9 @@ export class KGenAttestor {
 
   /**
    * Compare two attestations
+   * @param {Object} attestation1 - First attestation
+   * @param {Object} attestation2 - Second attestation
+   * @returns {Object} Comparison result
    */
   compareAttestations(attestation1, attestation2) {
     const differences = [];
@@ -264,6 +298,8 @@ export class KGenAttestor {
 
   /**
    * Create content hash using specified algorithm
+   * @param {string} content - Content to hash
+   * @returns {string} Content hash as hex string
    */
   createContentHash(content) {
     return crypto.createHash(this.options.algorithm)
@@ -273,6 +309,8 @@ export class KGenAttestor {
 
   /**
    * Create signature for attestation data
+   * @param {Object} data - Data to sign
+   * @returns {string} Signature as hex string
    */
   createSignature(data) {
     // Simple signature using hash of data + attestor ID
@@ -284,6 +322,9 @@ export class KGenAttestor {
 
   /**
    * Get additional metadata if enabled
+   * @param {string} content - Content being attested
+   * @param {Object} context - Context data
+   * @returns {Object} Additional metadata
    */
   getAdditionalMetadata(content, context) {
     return {
@@ -306,6 +347,7 @@ export class KGenAttestor {
 
   /**
    * Get deterministic or real timestamp
+   * @returns {string} ISO 8601 timestamp
    */
   getTimestamp() {
     return this.options.deterministicMode ?
@@ -315,6 +357,9 @@ export class KGenAttestor {
 
   /**
    * Export attestation in standard format
+   * @param {Object} attestation - Attestation to export
+   * @param {string} [format='json'] - Export format (json, compact, yaml, base64)
+   * @returns {string} Exported attestation
    */
   exportAttestation(attestation, format = 'json') {
     switch (format.toLowerCase()) {
@@ -340,6 +385,9 @@ export class KGenAttestor {
 
   /**
    * Import attestation from standard format
+   * @param {string} data - Attestation data to import
+   * @param {string} [format='json'] - Import format (json, compact, base64)
+   * @returns {Object} Imported attestation object
    */
   importAttestation(data, format = 'json') {
     try {
@@ -362,6 +410,7 @@ export class KGenAttestor {
 
   /**
    * Get attestor statistics
+   * @returns {Object} Attestor configuration and capabilities
    */
   getStats() {
     return {

package/src/core/filters.js

@@ -1,6 +1,8 @@
 /**
- * KGEN Filter System - Deterministic template filters
+ * @file KGEN Filter System - Deterministic template filters
+ * @module @unrdf/kgn/core/filters
  *
+ * @description
  * Implements all v1 Lock specification filters:
  * - Text: upper, lower, trim, replace, split, join, slice
  * - Data: default, unique, sort, groupby, map, sum, count
@@ -12,7 +14,16 @@
 
 import crypto from 'crypto';
 
+/**
+ * KGEN Filters class - Template filter system
+ */
 export class KGenFilters {
+  /**
+   * Create a new KGenFilters instance
+   * @param {Object} [options={}] - Filter configuration options
+   * @param {boolean} [options.deterministicMode=true] - Enable deterministic mode
+   * @param {boolean} [options.strictMode=true] - Enable strict error handling
+   */
   constructor(options = {}) {
     this.options = {
       deterministicMode: options.deterministicMode !== false,
@@ -26,6 +37,12 @@ export class KGenFilters {
 
   /**
    * Register a filter function
+   * @param {string} name - Filter name
+   * @param {Function} filterFunction - Filter implementation
+   * @param {Object} [options={}] - Filter options
+   * @param {boolean} [options.deterministic=true] - Whether filter is deterministic
+   * @param {string} [options.description=''] - Filter description
+   * @param {string} [options.category='custom'] - Filter category
    */
   register(name, filterFunction, options = {}) {
     if (typeof filterFunction !== 'function') {
@@ -42,6 +59,10 @@ export class KGenFilters {
 
   /**
    * Apply filter to value
+   * @param {string} filterName - Name of filter to apply
+   * @param {*} value - Value to filter
+   * @param {...*} args - Additional filter arguments
+   * @returns {*} Filtered value
    */
   apply(filterName, value, ...args) {
     const filter = this.filters.get(filterName);
@@ -70,6 +91,8 @@ export class KGenFilters {
 
   /**
    * Check if filter exists
+   * @param {string} filterName - Filter name to check
+   * @returns {boolean} True if filter exists
    */
   has(filterName) {
     return this.filters.has(filterName);
@@ -77,6 +100,7 @@ export class KGenFilters {
 
   /**
    * Get filter count
+   * @returns {number} Number of registered filters
    */
   getFilterCount() {
     return this.filters.size;
@@ -84,6 +108,7 @@ export class KGenFilters {
 
   /**
    * Register all core filters
+   * Registers text, data, format, RDF, validation, CAS, and utility filters
    */
   registerCoreFilters() {
     this.registerTextFilters();
@@ -97,6 +122,7 @@ export class KGenFilters {
 
   /**
    * Text processing filters
+   * Registers upper, lower, trim, replace, split, join, slice filters
    */
   registerTextFilters() {
     this.register('upper', (str) => String(str || '').toUpperCase(), {
@@ -146,10 +172,27 @@ export class KGenFilters {
       category: 'text',
       description: 'Extract substring by position'
     });
+
+    this.register('truncate', (str, length = 10, suffix = '...') => {
+      const s = String(str || '');
+      if (s.length <= length) return s;
+      return s.slice(0, length) + suffix;
+    }, {
+      category: 'text',
+      description: 'Truncate string to specified length'
+    });
+
+    this.register('reverse', (str) => {
+      return String(str || '').split('').reverse().join('');
+    }, {
+      category: 'text',
+      description: 'Reverse string'
+    });
   }
 
   /**
    * Data processing filters
+   * Registers default, unique, sort, groupby, map, sum, count filters
    */
   registerDataFilters() {
     this.register('default', (value, defaultValue = '') => {
@@ -356,6 +399,7 @@ export class KGenFilters {
 
   /**
    * Validation filters
+   * Registers shaclReport, validate filters
    */
   registerValidationFilters() {
     this.register('shaclReport', (data, shaclShapes = {}) => {
@@ -425,6 +469,7 @@ export class KGenFilters {
 
   /**
    * Utility filters
+   * Registers typeof, length, keys, values, entries, formatDate filters
    */
   registerUtilityFilters() {
     // Non-deterministic filters that throw in deterministic mode
@@ -460,6 +505,93 @@ export class KGenFilters {
       deterministic: false,
       description: 'Generate UUID (non-deterministic)'
     });
+
+    // Date arithmetic filters
+    this.register('dateAdd', (dateStr, amount, unit = 'day') => {
+      const date = new Date(dateStr);
+      switch (unit) {
+        case 'day':
+          date.setDate(date.getDate() + amount);
+          break;
+        case 'month':
+          date.setMonth(date.getMonth() + amount);
+          break;
+        case 'year':
+          date.setFullYear(date.getFullYear() + amount);
+          break;
+        default:
+          throw new Error(`Unknown unit: ${unit}`);
+      }
+      return date.toISOString();
+    }, {
+      category: 'utility',
+      description: 'Add time to date'
+    });
+
+    this.register('dateSub', (dateStr, amount, unit = 'day') => {
+      const date = new Date(dateStr);
+      switch (unit) {
+        case 'day':
+          date.setDate(date.getDate() - amount);
+          break;
+        case 'month':
+          date.setMonth(date.getMonth() - amount);
+          break;
+        case 'year':
+          date.setFullYear(date.getFullYear() - amount);
+          break;
+        default:
+          throw new Error(`Unknown unit: ${unit}`);
+      }
+      return date.toISOString();
+    }, {
+      category: 'utility',
+      description: 'Subtract time from date'
+    });
+
+    // Path utility filters
+    this.register('resolve', (base, relative) => {
+      // Simple path resolution (normalize and join)
+      const baseParts = base.split('/').filter(p => p);
+      const relativeParts = relative.split('/').filter(p => p);
+
+      for (const part of relativeParts) {
+        if (part === '..') {
+          baseParts.pop();
+        } else if (part !== '.') {
+          baseParts.push(part);
+        }
+      }
+
+      return '/' + baseParts.join('/');
+    }, {
+      category: 'utility',
+      description: 'Resolve path'
+    });
+
+    this.register('relative', (from, to) => {
+      // Simple relative path calculation
+      const fromParts = from.split('/').filter(p => p);
+      const toParts = to.split('/').filter(p => p);
+
+      // Find common base
+      let i = 0;
+      while (i < fromParts.length && i < toParts.length && fromParts[i] === toParts[i]) {
+        i++;
+      }
+
+      // Go up from 'from' directory
+      const upCount = fromParts.length - i;
+      const upParts = Array(upCount).fill('..');
+
+      // Then append remaining 'to' parts
+      const remainingParts = toParts.slice(i);
+
+      return [...upParts, ...remainingParts].join('/');
+    }, {
+      category: 'utility',
+      description: 'Calculate relative path'
+    });
   }
 
   /**
@@ -489,6 +621,7 @@ export class KGenFilters {
 
   /**
    * Get filter statistics
+   * @returns {Object} Filter system statistics
    */
   getStats() {
     const categories = {};

package/src/core/index.js

@@ -5,6 +5,10 @@
  * Features: Deterministic rendering, custom filters, attestation support
  */
 
+// Import class first so it can be used in factory function
+import { KGenTemplateEngine } from './kgen-engine.js';
+
+// Export all classes
 export { KGenTemplateEngine } from './kgen-engine.js';
 export { KGenParser } from './parser.js';
 export { KGenFilters } from './filters.js';
@@ -13,9 +17,12 @@ export { KGenPostProcessor } from './post-processor.js';
 export { KGenAttestor } from './attestor.js';
 
 // Convenience factory function
+/**
+ *
+ */
 export function createKGenEngine(options = {}) {
   return new KGenTemplateEngine(options);
 }
 
 // Default export
-export { KGenTemplateEngine as default };
+export default KGenTemplateEngine;