@unrdf/kgn 5.0.1

package/src/filters/index.js

@@ -0,0 +1,270 @@
+/**
+ * KGEN Template Filters - Complete Filter Library
+ *
+ * Migrated essential filters from unjucks with 80/20 principle:
+ * - Text processing (upper, lower, camelCase, etc.)
+ * - Array manipulation (join, sort, unique, etc.)
+ * - Data handling (json, default, type checking)
+ * - RDF/SPARQL support (mocked for deterministic testing)
+ *
+ * All filters provide deterministic, reproducible output
+ */
+
+import crypto from 'crypto';
+import { textFilters } from './text.js';
+import { arrayFilters } from './array.js';
+import { dataFilters } from './data.js';
+import { rdfFilters } from './rdf.js';
+
+/**
+ * Create custom filters with deterministic operations
+ */
+export function createCustomFilters(options = {}) {
+  const { deterministicMode = false, staticBuildTime = '2024-01-01T00:00:00.000Z' } = options;
+
+  // Merge all filter collections
+  const allFilters = {
+    ...textFilters,
+    ...arrayFilters,
+    ...dataFilters,
+    ...rdfFilters,
+
+    // Enhanced deterministic filters that override or augment the base filters
+
+    // Deterministic date/time formatting
+    formatDate: (date, format = 'YYYY-MM-DD') => {
+      if (deterministicMode) {
+        // Use static build time for deterministic rendering
+        return staticBuildTime.split('T')[0]; // Returns '2024-01-01'
+      }
+
+      const d = new Date(date);
+      if (isNaN(d.getTime())) return '';
+
+      switch (format) {
+        case 'YYYY-MM-DD':
+          return d.toISOString().split('T')[0];
+        case 'MM/DD/YYYY':
+          return `${(d.getMonth() + 1).toString().padStart(2, '0')}/${d.getDate().toString().padStart(2, '0')}/${d.getFullYear()}`;
+        case 'DD/MM/YYYY':
+          return `${d.getDate().toString().padStart(2, '0')}/${(d.getMonth() + 1).toString().padStart(2, '0')}/${d.getFullYear()}`;
+        default:
+          return d.toISOString().split('T')[0];
+      }
+    },
+
+    formatTime: (date, format = 'HH:mm:ss') => {
+      if (deterministicMode) {
+        return '00:00:00';
+      }
+
+      const d = new Date(date);
+      if (isNaN(d.getTime())) return '';
+
+      const hours = d.getHours().toString().padStart(2, '0');
+      const minutes = d.getMinutes().toString().padStart(2, '0');
+      const seconds = d.getSeconds().toString().padStart(2, '0');
+
+      switch (format) {
+        case 'HH:mm:ss':
+          return `${hours}:${minutes}:${seconds}`;
+        case 'HH:mm':
+          return `${hours}:${minutes}`;
+        default:
+          return `${hours}:${minutes}:${seconds}`;
+      }
+    },
+
+    // Deterministic timestamp
+    timestamp: () => {
+      if (deterministicMode) {
+        return staticBuildTime;
+      }
+      return new Date().toISOString();
+    },
+
+    // Content hashing for deterministic IDs
+    hash: (content, algorithm = 'sha256') => {
+      return crypto.createHash(algorithm).update(String(content)).digest('hex');
+    },
+
+    shortHash: (content, length = 8) => {
+      return crypto.createHash('sha256').update(String(content)).digest('hex').substring(0, length);
+    },
+
+    // File and path utilities
+    filename: (filePath) => {
+      if (!filePath) return '';
+      return filePath.split('/').pop().split('\\').pop();
+    },
+
+    basename: (filePath, ext) => {
+      const name = filePath.split('/').pop().split('\\').pop();
+      if (ext && name.endsWith(ext)) {
+        return name.slice(0, -ext.length);
+      }
+      const dotIndex = name.lastIndexOf('.');
+      return dotIndex > 0 ? name.slice(0, dotIndex) : name;
+    },
+
+    dirname: (filePath) => {
+      if (!filePath) return '';
+      const parts = filePath.split('/');
+      if (parts.length === 1) {
+        // Try Windows separators
+        const winParts = filePath.split('\\');
+        return winParts.length > 1 ? winParts.slice(0, -1).join('\\') : '';
+      }
+      return parts.slice(0, -1).join('/');
+    },
+
+    // Code generation helpers
+    comment: (text, style = '//') => {
+      if (!text) return '';
+      switch (style) {
+        case '//':
+          return text.split('\n').map(line => `// ${line}`).join('\n');
+        case '#':
+          return text.split('\n').map(line => `# ${line}`).join('\n');
+        case '/*':
+          return `/* ${text} */`;
+        case '<!--':
+          return `<!-- ${text} -->`;
+        default:
+          return text.split('\n').map(line => `${style} ${line}`).join('\n');
+      }
+    },
+
+    // Validation and safety filters
+    required: (value, message = 'Value is required') => {
+      if (value === null || value === undefined || value === '') {
+        throw new Error(message);
+      }
+      return value;
+    },
+
+    // Determinism blockers - these will throw in deterministic mode
+    now: () => {
+      if (deterministicMode) {
+        throw new Error('Filter "now" is not allowed in deterministic mode. Use "timestamp" instead.');
+      }
+      return new Date().toISOString();
+    },
+
+    random: () => {
+      if (deterministicMode) {
+        throw new Error('Filter "random" is not allowed in deterministic mode. Use "hash" for consistent randomness.');
+      }
+      return Math.random();
+    },
+
+    uuid: () => {
+      if (deterministicMode) {
+        throw new Error('Filter "uuid" is not allowed in deterministic mode. Use "hash" for consistent IDs.');
+      }
+      return crypto.randomUUID();
+    },
+
+    // CSV conversion filters
+    csv: (data, options = {}) => {
+      if (!Array.isArray(data)) return '';
+      if (data.length === 0) return '';
+
+      const { delimiter = ',', quote = '"', headers = true } = options;
+      const lines = [];
+
+      // Get headers from first object
+      if (headers && data.length > 0 && typeof data[0] === 'object') {
+        const headerRow = Object.keys(data[0]).map(h => `${quote}${h}${quote}`).join(delimiter);
+        lines.push(headerRow);
+      }
+
+      // Add data rows
+      for (const row of data) {
+        if (typeof row === 'object' && row !== null) {
+          const values = Object.values(row).map(v => {
+            const str = String(v || '');
+            return str.includes(delimiter) || str.includes(quote) || str.includes('\n')
+              ? `${quote}${str.replace(new RegExp(quote, 'g'), quote + quote)}${quote}`
+              : str;
+          });
+          lines.push(values.join(delimiter));
+        } else {
+          lines.push(String(row));
+        }
+      }
+
+      return lines.join('\n');
+    },
+
+    // Markdown table filter
+    markdown: (data, options = {}) => {
+      if (!Array.isArray(data)) return '';
+      if (data.length === 0) return '';
+
+      const { align = 'left' } = options;
+      const lines = [];
+
+      if (typeof data[0] === 'object' && data[0] !== null) {
+        const headers = Object.keys(data[0]);
+
+        // Header row
+        lines.push('| ' + headers.join(' | ') + ' |');
+
+        // Separator row
+        const separators = headers.map(() => {
+          switch (align) {
+            case 'center': return ':---:';
+            case 'right': return '---:';
+            default: return '---';
+          }
+        });
+        lines.push('| ' + separators.join(' | ') + ' |');
+
+        // Data rows
+        for (const row of data) {
+          const values = headers.map(h => String(row[h] || '').replace(/\|/g, '\\|'));
+          lines.push('| ' + values.join(' | ') + ' |');
+        }
+      }
+
+      return lines.join('\n');
+    }
+  };
+
+  return allFilters;
+}
+
+/**
+ * Register all filters with Nunjucks environment
+ * @param {Object} env - Nunjucks environment
+ * @param {Object} options - Filter options
+ */
+export function registerFilters(env, options = {}) {
+  const filters = createCustomFilters(options);
+
+  for (const [name, filter] of Object.entries(filters)) {
+    env.addFilter(name, filter);
+  }
+
+  return env;
+}
+
+/**
+ * Get all available filter names
+ * @param {Object} options - Filter options
+ * @returns {Array} Array of filter names
+ */
+export function getFilterNames(options = {}) {
+  return Object.keys(createCustomFilters(options));
+}
+
+/**
+ * Export individual filter collections
+ */
+export { textFilters, arrayFilters, dataFilters, rdfFilters };
+
+/**
+ * Export default function
+ */
+export default createCustomFilters;

package/src/filters/rdf.js

@@ -0,0 +1,264 @@
+/**
+ * KGEN RDF/SPARQL Filters - P0 Essential Semantic Web Processing
+ *
+ * Mock implementations for testing and London BDD approach
+ * These stubs provide deterministic behavior for template generation
+ */
+
+/**
+ * Mock RDF prefixes for expansion
+ */
+const DEFAULT_PREFIXES = {
+  'rdf': 'http://www.w3.org/1999/02/22-rdf-syntax-ns#',
+  'rdfs': 'http://www.w3.org/2000/01/rdf-schema#',
+  'owl': 'http://www.w3.org/2002/07/owl#',
+  'xsd': 'http://www.w3.org/2001/XMLSchema#',
+  'dc': 'http://purl.org/dc/elements/1.1/',
+  'foaf': 'http://xmlns.com/foaf/0.1/',
+  'skos': 'http://www.w3.org/2004/02/skos/core#',
+  'ex': 'http://example.org/',
+  'schema': 'https://schema.org/'
+};
+
+/**
+ * Mock SPARQL dataset for deterministic results
+ */
+const MOCK_SPARQL_RESULTS = {
+  'SELECT ?s ?p ?o WHERE { ?s ?p ?o }': [
+    { s: 'ex:Subject1', p: 'rdf:type', o: 'ex:Class1' },
+    { s: 'ex:Subject2', p: 'rdfs:label', o: '"Example Label"' }
+  ],
+  'SELECT * WHERE { ?s rdf:type ?type }': [
+    { s: 'ex:Instance1', type: 'ex:Person' },
+    { s: 'ex:Instance2', type: 'ex:Organization' }
+  ]
+};
+
+/**
+ * Expand CURIE (Compact URI) to full URI
+ * @param {string} curie - CURIE in format 'prefix:localName'
+ * @param {Object} prefixes - Custom prefix mappings
+ * @returns {string} Expanded URI
+ */
+export const expand = (curie, prefixes = {}) => {
+  if (!curie || typeof curie !== 'string') return '';
+
+  const allPrefixes = { ...DEFAULT_PREFIXES, ...prefixes };
+  const [prefix, localName] = curie.split(':', 2);
+
+  if (localName === undefined) return curie; // No prefix found
+  if (!allPrefixes[prefix]) return curie; // Unknown prefix
+
+  return allPrefixes[prefix] + localName;
+};
+
+/**
+ * Contract full URI to CURIE if possible
+ * @param {string} uri - Full URI
+ * @param {Object} prefixes - Custom prefix mappings
+ * @returns {string} CURIE or original URI
+ */
+export const contract = (uri, prefixes = {}) => {
+  if (!uri || typeof uri !== 'string') return '';
+
+  const allPrefixes = { ...DEFAULT_PREFIXES, ...prefixes };
+
+  for (const [prefix, namespace] of Object.entries(allPrefixes)) {
+    if (uri.startsWith(namespace)) {
+      const localName = uri.substring(namespace.length);
+      return `${prefix}:${localName}`;
+    }
+  }
+
+  return uri;
+};
+
+/**
+ * Execute mock SPARQL query (deterministic results)
+ * @param {string} query - SPARQL query string
+ * @param {any} dataset - Mock dataset (ignored in stub)
+ * @returns {Array} Mock query results
+ */
+export const sparql = async (query, dataset = null) => {
+  if (!query || typeof query !== 'string') return [];
+
+  // Return mock results for known queries
+  const normalizedQuery = query.trim().replace(/\s+/g, ' ');
+
+  if (MOCK_SPARQL_RESULTS[normalizedQuery]) {
+    return MOCK_SPARQL_RESULTS[normalizedQuery];
+  }
+
+  // Generate deterministic mock results based on query hash
+  const queryHash = query.split('').reduce((hash, char) => {
+    hash = ((hash << 5) - hash) + char.charCodeAt(0);
+    return hash & hash;
+  }, 0);
+
+  const numResults = Math.abs(queryHash) % 5 + 1; // 1-5 results
+  const results = [];
+
+  for (let i = 0; i < numResults; i++) {
+    results.push({
+      s: `ex:MockSubject${i + 1}`,
+      p: `ex:mockProperty${i + 1}`,
+      o: `"Mock Object ${i + 1}"`
+    });
+  }
+
+  return results;
+};
+
+/**
+ * Create RDF literal with optional language tag or datatype
+ * @param {any} value - Literal value
+ * @param {string} langOrType - Language tag (e.g., 'en') or datatype CURIE
+ * @returns {string} RDF literal string
+ */
+export const rdfLiteral = (value, langOrType = null) => {
+  if (value === null || value === undefined) return '""';
+
+  const literal = `"${String(value).replace(/"/g, '\\"')}"`;
+
+  if (!langOrType) return literal;
+
+  // Check if it's a language tag (2-3 letter code)
+  if (/^[a-z]{2,3}(-[A-Z]{2})?$/.test(langOrType)) {
+    return `${literal}@${langOrType}`;
+  }
+
+  // Treat as datatype
+  return `${literal}^^${langOrType}`;
+};
+
+/**
+ * Create RDF resource (URI reference)
+ * @param {string} uri - URI string
+ * @returns {string} URI wrapped in angle brackets
+ */
+export const rdfResource = (uri) => {
+  if (!uri || typeof uri !== 'string') return '<>';
+
+  // If already a CURIE or angle-bracketed URI, return as-is
+  if (uri.includes(':') && !uri.startsWith('http')) return uri;
+  if (uri.startsWith('<') && uri.endsWith('>')) return uri;
+
+  return `<${uri}>`;
+};
+
+/**
+ * Escape string for Turtle/N3 syntax
+ * @param {string} str - String to escape
+ * @returns {string} Turtle-escaped string
+ */
+export const turtleEscape = (str) => {
+  if (!str || typeof str !== 'string') return '';
+
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+};
+
+/**
+ * Create SPARQL variable
+ * @param {string} name - Variable name
+ * @returns {string} SPARQL variable with ? prefix
+ */
+export const sparqlVar = (name) => {
+  if (!name || typeof name !== 'string') return '?var';
+
+  // Remove any existing ? or $ prefix
+  const cleanName = name.replace(/^[?$]/, '');
+
+  // Ensure valid SPARQL variable name (alphanumeric + underscore)
+  const validName = cleanName.replace(/[^a-zA-Z0-9_]/g, '_');
+
+  return `?${validName}`;
+};
+
+/**
+ * Create RDF list (collection)
+ * @param {Array} items - Array items
+ * @returns {string} RDF list syntax
+ */
+export const rdfList = (items) => {
+  if (!Array.isArray(items) || items.length === 0) {
+    return 'rdf:nil';
+  }
+
+  return `( ${items.join(' ')} )`;
+};
+
+/**
+ * Create blank node identifier
+ * @param {string} id - Optional identifier
+ * @returns {string} Blank node with _: prefix
+ */
+export const blankNode = (id = null) => {
+  if (id && typeof id === 'string') {
+    const cleanId = id.replace(/[^a-zA-Z0-9_]/g, '_');
+    return `_:${cleanId}`;
+  }
+
+  // Generate deterministic blank node ID
+  const timestamp = new Date('2024-01-01T00:00:00.000Z').getTime();
+  return `_:blank${timestamp % 10000}`;
+};
+
+/**
+ * Add RDF datatype to literal
+ * @param {any} value - Value to type
+ * @param {string} datatype - XSD datatype (without prefix)
+ * @returns {string} Typed literal
+ */
+export const rdfDatatype = (value, datatype = 'string') => {
+  if (value === null || value === undefined) return '""';
+
+  const literal = `"${String(value)}"`;
+  return `${literal}^^xsd:${datatype}`;
+};
+
+/**
+ * Mock SHACL validation (always passes in stub)
+ * @param {any} data - Data to validate
+ * @param {any} shape - SHACL shape
+ * @returns {Object} Mock validation result
+ */
+export const shaclValidate = (data, shape) => {
+  return {
+    conforms: true,
+    results: [],
+    message: 'Mock SHACL validation passed'
+  };
+};
+
+/**
+ * Mock reasoning/inference (no-op in stub)
+ * @param {any} graph - RDF graph
+ * @param {string} reasoner - Reasoner type
+ * @returns {any} Original graph (no inference applied)
+ */
+export const infer = (graph, reasoner = 'rdfs') => {
+  return graph; // No-op for stub
+};
+
+// Collection of all RDF filters for easy import
+export const rdfFilters = {
+  expand,
+  contract,
+  sparql,
+  rdfLiteral,
+  rdfResource,
+  turtleEscape,
+  sparqlVar,
+  rdfList,
+  blankNode,
+  rdfDatatype,
+  shaclValidate,
+  infer
+};
+
+export default rdfFilters;