@unrdf/knowledge-engine 5.0.1 → 26.4.2

package/src/engines/rdf-engine.mjs

@@ -1,299 +0,0 @@
-/**
- * @fileoverview Production-grade RDF engine for JavaScript.
- * @version 2.0.0
- * @license MIT
- */
-
-import { Parser, Writer, UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
-import { createStore } from '@unrdf/oxigraph'; // TODO: Replace with Oxigraph Store
-import { createStore as createOxigraphStore } from '@unrdf/oxigraph';
-import rdf from 'rdf-ext';
-import SHACLValidator from 'rdf-validate-shacl';
-import rdfCanonize from 'rdf-canonize';
-import eyereasoner from 'eyereasoner';
-import _jsonld from 'jsonld';
-
-const { namedNode, literal, quad, blankNode, defaultGraph } = DataFactory;
-
-/**
- * A comprehensive, production-grade engine for RDF processing in JavaScript.
- * It unifies parsing, serialization, querying, validation, and reasoning.
- */
-export class RdfEngine {
-  /**
-   * @param {object} [options] - Configuration options for the engine.
-   * @param {string} [options.baseIRI] - The base IRI to use for parsing relative URIs.
-   */
-  constructor(options = {}) {
-    this.baseIRI = options.baseIRI || 'http://example.org/';
-    this.store = createStore();
-  }
-
-  // =================================================================
-  // == Core Setup & Store Access
-  // =================================================================
-
-  /**
-   * Returns the underlying N3.js Store instance.
-   * @returns {import('n3').Store}
-   */
-  getStore() {
-    return this.store;
-  }
-
-  /**
-   * Clears the internal store, removing all quads.
-   */
-  clearStore() {
-    this.store.removeQuads(this.store.getQuads());
-  }
-
-  // =================================================================
-  // == Term Creation
-  // =================================================================
-
-  /**
-   *
-   */
-  namedNode(value) {
-    return namedNode(value);
-  }
-  /**
-   *
-   */
-  literal(value, langOrDt) {
-    return literal(value, langOrDt);
-  }
-  /**
-   *
-   */
-  blankNode(value) {
-    return blankNode(value);
-  }
-  /**
-   *
-   */
-  quad(s, p, o, g = defaultGraph()) {
-    return quad(s, p, o, g);
-  }
-
-  // =================================================================
-  // == Parsing & Serialization
-  // =================================================================
-
-  /**
-   * Parses a Turtle string and adds the quads to the internal store.
-   * @param {string} ttl - The Turtle string to parse.
-   * @returns {import('n3').Store} The engine's store instance.
-   */
-  parseTurtle(ttl) {
-    const quads = new Parser({ baseIRI: this.baseIRI }).parse(ttl);
-    this.store.addQuads(quads);
-    return this.store;
-  }
-
-  /**
-   * Serializes a store to a Turtle string.
-   * @param {import('n3').Store} [store=this.store] - The store to serialize.
-   * @param {object} [options] - N3.js Writer options.
-   * @returns {string}
-   */
-  serializeTurtle(store = this.store, options = {}) {
-    const writer = new Writer({ ...options, format: 'Turtle' });
-    return writer.quadsToString(store.getQuads());
-  }
-
-  /**
-   * Serializes a store to a canonical N-Quads string.
-   * @param {import('n3').Store} [store=this.store] - The store to serialize.
-   * @returns {string}
-   */
-  serializeNQuads(store = this.store) {
-    const writer = new Writer({ format: 'N-Quads' });
-    return writer.quadsToString(store.getQuads());
-  }
-
-  // =================================================================
-  // == SPARQL Querying
-  // =================================================================
-
-  /**
-   * Executes a read-only SPARQL query (SELECT, ASK, CONSTRUCT) against the store.
-   * @param {string} sparql - The SPARQL query string.
-   * @returns {Promise<Array<object>|boolean|import('n3').Store>} The query result.
-   */
-  async query(sparql) {
-    // Remove PREFIX declarations to find the actual query type
-    const queryWithoutPrefixes = sparql.replace(/^PREFIX\s+[^\s]+\s+<[^>]+>\s*/gm, '').trim();
-    const queryType = queryWithoutPrefixes.toUpperCase().split(/\s+/)[0];
-
-    // Convert n3.Store to Oxigraph store and execute query synchronously
-    const oxigraphStore = createOxigraphStore(Array.from(this.store.getQuads()));
-    const result = oxigraphStore.query(sparql);
-
-    switch (queryType) {
-      case 'SELECT': {
-        // Oxigraph returns array of binding objects for SELECT
-        const rows = Array.isArray(result)
-          ? result.map(item => {
-              const entry = {};
-              if (item && typeof item === 'object') {
-                for (const [key, val] of Object.entries(item)) {
-                  entry[key] = val && val.value ? val.value : val;
-                }
-              }
-              return entry;
-            })
-          : [];
-        const variables = rows.length > 0 ? Object.keys(rows[0]) : [];
-        return { type: 'select', rows, variables };
-      }
-      case 'ASK': {
-        // Oxigraph returns boolean for ASK
-        const boolean = typeof result === 'boolean' ? result : false;
-        return { type: 'ask', boolean };
-      }
-      case 'CONSTRUCT': {
-        // Oxigraph returns array of quads for CONSTRUCT
-        const quads = Array.isArray(result) ? result : [];
-        return {
-          type: 'construct',
-          store: createStore(quads),
-        };
-      }
-      case 'DESCRIBE': {
-        // Oxigraph returns array of quads for DESCRIBE
-        const quads = Array.isArray(result) ? result : [];
-        return {
-          type: 'describe',
-          store: createStore(quads),
-        };
-      }
-      case 'INSERT':
-      case 'UPDATE':
-      case 'DELETE':
-        throw new Error(
-          `Query type "${queryType}" is not supported. Use the update() helper for writes.`
-        );
-      default:
-        throw new Error(`Query type "${queryType}" is not supported by query().`);
-    }
-  }
-
-  /**
-   * Executes a SPARQL UPDATE operation (INSERT, DELETE, etc.) against the store.
-   * @param {string} sparql - The SPARQL UPDATE query string.
-   * @returns {Promise<object>} The update result.
-   */
-  async update(sparql) {
-    // Remove PREFIX declarations to find the actual query type
-    const queryWithoutPrefixes = sparql.replace(/PREFIX\s+[^\s]+\s+<[^>]+>\s*/g, '').trim();
-
-    // If still starts with PREFIX, try a different approach
-    if (queryWithoutPrefixes.startsWith('PREFIX')) {
-      const lines = queryWithoutPrefixes.split('\n');
-      const nonPrefixLines = lines.filter(line => !line.trim().startsWith('PREFIX'));
-      const result = nonPrefixLines.join('\n').trim();
-      return this.update(result);
-    }
-    const queryType = queryWithoutPrefixes.toUpperCase().split(/\s+/)[0];
-
-    // For now, we'll implement a simple INSERT DATA operation
-    if (queryType === 'INSERT' && queryWithoutPrefixes.includes('INSERT DATA')) {
-      // Parse the INSERT DATA operation - need to handle PREFIX declarations
-      const insertMatch = sparql.match(/INSERT\s+DATA\s*\{([^}]+)\}/is);
-      if (insertMatch) {
-        const turtleData = insertMatch[1].trim();
-
-        // Extract PREFIX declarations from the original query
-        const prefixMatches = sparql.match(/PREFIX\s+[^\s]+\s+<[^>]+>/gi) || [];
-        const prefixes = prefixMatches.join('\n');
-
-        // Combine prefixes with the data for parsing
-        const dataToParse = prefixes + (prefixes ? '\n' : '') + turtleData;
-
-        // Parse the Turtle data with PREFIX declarations and add to store
-        const parser = new Parser();
-        const quads = parser.parse(dataToParse);
-        for (const quad of quads) {
-          this.store.add(quad);
-        }
-        return { type: 'update', ok: true, inserted: quads.length };
-      }
-    }
-
-    // For other UPDATE operations, throw an error for now
-    throw new Error(`UPDATE operation "${queryType}" not yet implemented`);
-  }
-
-  // =================================================================
-  // == SHACL Validation
-  // =================================================================
-
-  /**
-   * Validates a data store against a set of SHACL shapes.
-   * @param {import('n3').Store} dataStore - The store containing data to validate.
-   * @param {import('n3').Store|string} shapes - The store or Turtle string containing SHACL shapes.
-   * @returns {{conforms: boolean, results: Array<object>}} A validation report.
-   */
-  validateShacl(dataStore, shapes) {
-    const shapesStore =
-      typeof shapes === 'string' ? createStore(new Parser().parse(shapes)) : shapes;
-
-    const validator = new SHACLValidator(rdf.dataset([...shapesStore]));
-    const report = validator.validate(rdf.dataset([...dataStore]));
-
-    return {
-      conforms: report.conforms,
-      results: (report.results || []).map(r => ({
-        message: r.message?.[0]?.value || null,
-        path: r.path?.value || null,
-        focusNode: r.focusNode?.value || null,
-      })),
-    };
-  }
-
-  // =================================================================
-  // == Reasoning
-  // =================================================================
-
-  /**
-   * Infers new knowledge by applying N3 Rules to a data store.
-   * @param {import('n3').Store} dataStore - The store containing data.
-   * @param {import('n3').Store|string} rules - The store or Turtle string containing N3 Rules.
-   * @returns {Promise<import('n3').Store>} A new store containing both original and inferred quads.
-   */
-  async reason(dataStore, rules) {
-    const rulesN3 = typeof rules === 'string' ? rules : this.serializeTurtle(rules);
-    const dataN3 = this.serializeTurtle(dataStore);
-    const { executeBasicEyeQuery } = await import('eyereasoner');
-    const inferredN3 = await executeBasicEyeQuery(eyereasoner.SWIPL, dataN3, rulesN3);
-    return createStore(new Parser().parse(inferredN3));
-  }
-
-  // =================================================================
-  // == Canonicalization & Isomorphism
-  // =================================================================
-
-  /**
-   * Produces a canonical representation of a store's quads using URDNA2015.
-   * @param {import('n3').Store} store - The store to canonicalize.
-   * @returns {string} The canonical N-Quads string.
-   */
-  canonicalize(store) {
-    return rdfCanonize.canonizeSync(store.getQuads(), {
-      algorithm: 'URDNA2015',
-    });
-  }
-
-  /**
-   * Checks if two stores are logically equivalent (isomorphic).
-   * @param {import('n3').Store} storeA
-   * @param {import('n3').Store} storeB
-   * @returns {boolean}
-   */
-  isIsomorphic(storeA, storeB) {
-    if (storeA.size !== storeB.size) return false;
-    return this.canonicalize(storeA) === this.canonicalize(storeB);
-  }
-}

package/src/file-resolver.mjs

@@ -1,387 +0,0 @@
-/**
- * @file File URI resolver with content-addressed verification.
- * @module file-resolver
- *
- * @description
- * Production-ready file resolver that loads SPARQL/SHACL files from URIs
- * with SHA-256 hash verification for content integrity and provenance.
- */
-
-import { readFile } from 'fs/promises';
-import { createHash } from 'crypto';
-import { _fileURLToPath } from 'url';
-import { _dirname, _join, _resolve } from 'path';
-import { createPathValidator } from './security/path-validator.mjs';
-
-/**
- * Resolve a file URI to an absolute path.
- * @param {string} uri - The file URI (e.g., "file://hooks/compliance/largeTx.ask.rq")
- * @param {string} [basePath] - Base path for relative resolution
- * @returns {string} Absolute file path
- *
- * @throws {Error} If URI is invalid or file doesn't exist
- */
-export function resolveFileUri(uri, basePath = process.cwd()) {
-  if (!uri || typeof uri !== 'string') {
-    throw new TypeError('resolveFileUri: uri must be a non-empty string');
-  }
-
-  if (!uri.startsWith('file://')) {
-    throw new Error(`resolveFileUri: URI must start with 'file://', got: ${uri}`);
-  }
-
-  // Validate path for security vulnerabilities
-  const pathValidator = createPathValidator({ basePath });
-  const validation = pathValidator.validateFileUri(uri);
-
-  if (!validation.valid) {
-    throw new Error(`Security validation failed: ${validation.violations.join(', ')}`);
-  }
-
-  // Use sanitized path from validator
-  return validation.sanitizedPath;
-}
-
-/**
- * Calculate SHA-256 hash of file content.
- * @param {string} filePath - Path to the file
- * @returns {Promise<string>} Hexadecimal SHA-256 hash
- *
- * @throws {Error} If file cannot be read
- */
-export async function calculateFileHash(filePath) {
-  try {
-    const content = await readFile(filePath, 'utf-8');
-    const hash = createHash('sha256');
-    hash.update(content, 'utf-8');
-    return hash.digest('hex');
-  } catch (error) {
-    throw new Error(`Failed to calculate hash for ${filePath}: ${error.message}`);
-  }
-}
-
-/**
- * Load file content with hash verification.
- * @param {string} uri - The file URI
- * @param {string} expectedHash - Expected SHA-256 hash
- * @param {string} [basePath] - Base path for resolution
- * @returns {Promise<{content: string, hash: string, path: string}>} File content and metadata
- *
- * @throws {Error} If file cannot be loaded or hash doesn't match
- */
-export async function loadFileWithHash(uri, expectedHash, basePath = process.cwd()) {
-  if (!expectedHash || typeof expectedHash !== 'string') {
-    throw new TypeError('loadFileWithHash: expectedHash must be a non-empty string');
-  }
-
-  const filePath = resolveFileUri(uri, basePath);
-
-  try {
-    // Load file content
-    const content = await readFile(filePath, 'utf-8');
-
-    // Calculate actual hash
-    const actualHash = await calculateFileHash(filePath);
-
-    // Verify hash matches
-    if (actualHash !== expectedHash) {
-      throw new Error(
-        `Hash verification failed for ${uri}\n` +
-          `Expected: ${expectedHash}\n` +
-          `Actual:   ${actualHash}\n` +
-          `File:     ${filePath}`
-      );
-    }
-
-    return {
-      content,
-      hash: actualHash,
-      path: filePath,
-      uri,
-    };
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      throw new Error(`File not found: ${uri} (resolved to: ${filePath})`);
-    }
-    throw error;
-  }
-}
-
-/**
- * Load and parse a SPARQL query file.
- * @param {string} uri - The file URI
- * @param {string} expectedHash - Expected SHA-256 hash
- * @param {string} [basePath] - Base path for resolution
- * @returns {Promise<{sparql: string, hash: string, path: string}>} Parsed SPARQL query
- *
- * @throws {Error} If file cannot be loaded or is not valid SPARQL
- */
-export async function loadSparqlFile(uri, expectedHash, basePath = process.cwd()) {
-  const fileData = await loadFileWithHash(uri, expectedHash, basePath);
-
-  // Basic SPARQL syntax validation
-  const sparql = fileData.content.trim();
-  if (!sparql) {
-    throw new Error(`Empty SPARQL file: ${uri}`);
-  }
-
-  // Check for common SPARQL keywords
-  const sparqlKeywords = ['SELECT', 'ASK', 'CONSTRUCT', 'DESCRIBE', 'INSERT', 'DELETE', 'PREFIX'];
-  const hasKeyword = sparqlKeywords.some(keyword => sparql.toUpperCase().includes(keyword));
-
-  if (!hasKeyword) {
-    throw new Error(`Invalid SPARQL syntax in ${uri}: No recognized SPARQL keywords found`);
-  }
-
-  return {
-    sparql,
-    hash: fileData.hash,
-    path: fileData.path,
-    uri: fileData.uri,
-  };
-}
-
-/**
- * Load and parse a SHACL shapes file.
- * @param {string} uri - The file URI
- * @param {string} expectedHash - Expected SHA-256 hash
- * @param {string} [basePath] - Base path for resolution
- * @returns {Promise<{turtle: string, hash: string, path: string}>} Parsed SHACL shapes
- *
- * @throws {Error} If file cannot be loaded or is not valid Turtle
- */
-export async function loadShaclFile(uri, expectedHash, basePath = process.cwd()) {
-  const fileData = await loadFileWithHash(uri, expectedHash, basePath);
-
-  // Basic Turtle syntax validation
-  const turtle = fileData.content.trim();
-  if (!turtle) {
-    throw new Error(`Empty SHACL file: ${uri}`);
-  }
-
-  // Check for SHACL namespace
-  if (!turtle.includes('http://www.w3.org/ns/shacl#')) {
-    throw new Error(`Invalid SHACL file ${uri}: Missing SHACL namespace`);
-  }
-
-  // Check for common SHACL terms
-  const shaclTerms = ['sh:NodeShape', 'sh:PropertyShape', 'sh:targetClass', 'sh:path'];
-  const hasShaclTerm = shaclTerms.some(term => turtle.includes(term));
-
-  if (!hasShaclTerm) {
-    throw new Error(`Invalid SHACL file ${uri}: No recognized SHACL terms found`);
-  }
-
-  return {
-    turtle,
-    hash: fileData.hash,
-    path: fileData.path,
-    uri: fileData.uri,
-  };
-}
-
-/**
- * Create a file resolver with caching.
- * @param {Object} [options] - Resolver options
- * @param {string} [options.basePath] - Base path for file resolution
- * @param {boolean} [options.enableCache] - Enable file content caching
- * @param {number} [options.cacheMaxAge] - Cache max age in milliseconds
- * @returns {Object} File resolver instance
- */
-export function createFileResolver(options = {}) {
-  const {
-    basePath = process.cwd(),
-    enableCache = true,
-    cacheMaxAge = 300000, // 5 minutes
-  } = options;
-
-  const cache = new Map();
-
-  return {
-    /**
-     * Load a file with hash verification.
-     * @param {string} uri - The file URI
-     * @param {string} expectedHash - Expected SHA-256 hash
-     * @returns {Promise<Object>} File content and metadata
-     */
-    async loadFile(uri, expectedHash) {
-      const cacheKey = `${uri}:${expectedHash}`;
-
-      if (enableCache && cache.has(cacheKey)) {
-        const cached = cache.get(cacheKey);
-        if (Date.now() - cached.timestamp < cacheMaxAge) {
-          return cached.data;
-        }
-        cache.delete(cacheKey);
-      }
-
-      const data = await loadFileWithHash(uri, expectedHash, basePath);
-
-      if (enableCache) {
-        cache.set(cacheKey, {
-          data,
-          timestamp: Date.now(),
-        });
-      }
-
-      return data;
-    },
-
-    /**
-     * Load a SPARQL file.
-     * @param {string} uri - The file URI
-     * @param {string} expectedHash - Expected SHA-256 hash
-     * @returns {Promise<Object>} Parsed SPARQL query
-     */
-    async loadSparql(uri, expectedHash) {
-      const cacheKey = `sparql:${uri}:${expectedHash}`;
-
-      if (enableCache && cache.has(cacheKey)) {
-        const cached = cache.get(cacheKey);
-        if (Date.now() - cached.timestamp < cacheMaxAge) {
-          return cached.data;
-        }
-        cache.delete(cacheKey);
-      }
-
-      const data = await loadSparqlFile(uri, expectedHash, basePath);
-
-      if (enableCache) {
-        cache.set(cacheKey, {
-          data,
-          timestamp: Date.now(),
-        });
-      }
-
-      return data;
-    },
-
-    /**
-     * Load a SHACL file.
-     * @param {string} uri - The file URI
-     * @param {string} expectedHash - Expected SHA-256 hash
-     * @returns {Promise<Object>} Parsed SHACL shapes
-     */
-    async loadShacl(uri, expectedHash) {
-      const cacheKey = `shacl:${uri}:${expectedHash}`;
-
-      if (enableCache && cache.has(cacheKey)) {
-        const cached = cache.get(cacheKey);
-        if (Date.now() - cached.timestamp < cacheMaxAge) {
-          return cached.data;
-        }
-        cache.delete(cacheKey);
-      }
-
-      const data = await loadShaclFile(uri, expectedHash, basePath);
-
-      if (enableCache) {
-        cache.set(cacheKey, {
-          data,
-          timestamp: Date.now(),
-        });
-      }
-
-      return data;
-    },
-
-    /**
-     * Clear the cache.
-     */
-    clearCache() {
-      cache.clear();
-    },
-
-    /**
-     * Pre-load a file at startup (compute hash once, avoid I/O in hot path)
-     * @param {string} uri - The file URI
-     * @returns {Promise<Object>} File content, computed hash, and metadata
-     *
-     * This method loads a file and computes its SHA-256 hash once at startup,
-     * then caches the result. Useful for "warming" the cache before transaction execution.
-     */
-    async preload(uri) {
-      try {
-        const filePath = resolveFileUri(uri, basePath);
-        const content = await readFile(filePath, 'utf-8');
-        const hash = await calculateFileHash(filePath);
-
-        const data = {
-          content,
-          hash,
-          path: filePath,
-          uri,
-        };
-
-        // Cache with preloaded marker (very long TTL)
-        const cacheKey = `preloaded:${uri}`;
-        if (enableCache) {
-          cache.set(cacheKey, {
-            data,
-            timestamp: Date.now(),
-          });
-        }
-
-        return data;
-      } catch (error) {
-        throw new Error(`Failed to preload ${uri}: ${error.message}`);
-      }
-    },
-
-    /**
-     * Collect all file URIs referenced in hook conditions
-     * @param {Array<Object>} hooks - Array of hook definitions
-     * @returns {Set<string>} Set of unique file URIs
-     *
-     * This method analyzes hook conditions to find all file references
-     * that should be preloaded at startup to eliminate File I/O from hot path.
-     */
-    collectFileUris(hooks) {
-      const uris = new Set();
-
-      if (!Array.isArray(hooks)) {
-        return uris;
-      }
-
-      for (const hook of hooks) {
-        if (hook.condition && hook.condition.file) {
-          uris.add(hook.condition.file);
-        }
-        if (hook.conditions && Array.isArray(hook.conditions)) {
-          for (const cond of hook.conditions) {
-            if (cond.file) {
-              uris.add(cond.file);
-            }
-          }
-        }
-      }
-
-      return uris;
-    },
-
-    /**
-     * Get cache statistics.
-     * @returns {Object} Cache statistics
-     */
-    getCacheStats() {
-      const now = Date.now();
-      let validEntries = 0;
-      let expiredEntries = 0;
-
-      for (const [_key, value] of cache.entries()) {
-        if (now - value.timestamp < cacheMaxAge) {
-          validEntries++;
-        } else {
-          expiredEntries++;
-        }
-      }
-
-      return {
-        totalEntries: cache.size,
-        validEntries,
-        expiredEntries,
-        cacheMaxAge,
-      };
-    },
-  };
-}