@unrdf/kgn 5.0.1

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

@@ -0,0 +1,306 @@
+/**
+ * @fileoverview RDF Graph Builder
+ * Converts parsed JSDoc data to RDF triples
+ */
+
+import crypto from 'crypto';
+
+/**
+ * RDF Vocabulary Prefixes
+ */
+export const PREFIXES = {
+  rdf: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#',
+  rdfs: 'http://www.w3.org/2000/01/rdf-schema#',
+  xsd: 'http://www.w3.org/2001/XMLSchema#',
+  code: 'http://unrdf.org/vocab/code#',
+  fs: 'http://unrdf.org/vocab/fs#',
+  doc: 'http://unrdf.org/vocab/doc#',
+  ex: 'http://example.org/',
+};
+
+/**
+ * Generate a deterministic URI for a resource
+ * @param {string} path - Resource path
+ * @returns {string} URI
+ */
+function generateURI(path) {
+  // Use package path as namespace
+  const namespace = 'http://unrdf.org/packages/';
+  // Create deterministic ID from path
+  const id = path.replace(/[^a-zA-Z0-9]/g, '-').replace(/-+/g, '-');
+  return namespace + id;
+}
+
+/**
+ * Generate a blank node ID
+ * @param {string} name - Name for blank node
+ * @returns {string} Blank node ID
+ */
+function blankNode(name) {
+  const hash = crypto.createHash('md5').update(name).digest('hex').substring(0, 8);
+  return `_:${name}_${hash}`;
+}
+
+/**
+ * Escape string for Turtle literal
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string
+ */
+function escapeLiteral(str) {
+  if (!str) return '""';
+  return `"${str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t')}"`;
+}
+
+/**
+ * Build RDF graph from parsed file data
+ * @param {Object} parsedFile - Output from parser.parseFile()
+ * @returns {string} Turtle RDF representation
+ */
+export function buildRDFGraph(parsedFile) {
+  const triples = [];
+
+  // File resource
+  const fileURI = generateURI(parsedFile.relativePath);
+
+  triples.push(`# File: ${parsedFile.relativePath}`);
+  triples.push(`${fileURI}`);
+  triples.push(`  a fs:File , code:Module ;`);
+  triples.push(`  fs:path ${escapeLiteral(parsedFile.relativePath)} ;`);
+  triples.push(`  fs:absolutePath ${escapeLiteral(parsedFile.file)} ;`);
+  triples.push(`  code:commentCount ${parsedFile.comments} .`);
+  triples.push('');
+
+  // Exports
+  parsedFile.exports.forEach((exp, idx) => {
+    const exportURI = `${fileURI}#${exp.name}`;
+
+    triples.push(`# Export: ${exp.name}`);
+    triples.push(`${exportURI}`);
+
+    if (exp.type === 'function') {
+      triples.push(`  a code:Function ;`);
+      triples.push(`  code:name ${escapeLiteral(exp.name)} ;`);
+
+      if (exp.description) {
+        triples.push(`  doc:description ${escapeLiteral(exp.description)} ;`);
+      }
+
+      if (exp.async) {
+        triples.push(`  code:async true ;`);
+      }
+
+      // Parameters
+      exp.params?.forEach((param, paramIdx) => {
+        const paramNode = blankNode(`${exp.name}_param_${param.name}`);
+        triples.push(`  code:param ${paramNode} ;`);
+
+        const paramTriples = [];
+        paramTriples.push(`${paramNode}`);
+        paramTriples.push(`  a code:Parameter ;`);
+        paramTriples.push(`  code:name ${escapeLiteral(param.name)} ;`);
+        paramTriples.push(`  code:type ${escapeLiteral(param.type)} ;`);
+
+        if (param.optional) {
+          paramTriples.push(`  code:optional true ;`);
+        }
+
+        if (param.description) {
+          paramTriples.push(`  doc:description ${escapeLiteral(param.description)} ;`);
+        }
+
+        if (param.default !== undefined) {
+          paramTriples.push(`  code:default ${escapeLiteral(String(param.default))} ;`);
+        }
+
+        paramTriples.push(`  code:position ${paramIdx} .`);
+        triples.push(...paramTriples);
+        triples.push('');
+      });
+
+      // Returns
+      if (exp.returns) {
+        triples.push(`  code:returns ${escapeLiteral(exp.returns.type)} ;`);
+        if (exp.returns.description) {
+          triples.push(`  code:returnsDescription ${escapeLiteral(exp.returns.description)} ;`);
+        }
+      }
+
+      // Examples
+      exp.examples?.forEach((example, exIdx) => {
+        triples.push(`  doc:example ${escapeLiteral(example)} ;`);
+      });
+
+      // Remove trailing semicolon from last triple
+      const lastLine = triples[triples.length - 1];
+      triples[triples.length - 1] = lastLine.replace(/\s;$/, ' .');
+
+    } else if (exp.type === 'class') {
+      triples.push(`  a code:Class ;`);
+      triples.push(`  code:name ${escapeLiteral(exp.name)} ;`);
+
+      if (exp.description) {
+        triples.push(`  doc:description ${escapeLiteral(exp.description)} ;`);
+      }
+
+      if (exp.extends) {
+        triples.push(`  code:extends ${escapeLiteral(exp.extends)} ;`);
+      }
+
+      // Methods
+      exp.methods?.forEach(method => {
+        const methodNode = blankNode(`${exp.name}_${method.name}`);
+        triples.push(`  code:method ${methodNode} ;`);
+
+        const methodTriples = [];
+        methodTriples.push(`${methodNode}`);
+        methodTriples.push(`  a code:Method ;`);
+        methodTriples.push(`  code:name ${escapeLiteral(method.name)} ;`);
+        methodTriples.push(`  code:kind ${escapeLiteral(method.kind)} ;`);
+
+        if (method.static) {
+          methodTriples.push(`  code:static true ;`);
+        }
+
+        if (method.async) {
+          methodTriples.push(`  code:async true ;`);
+        }
+
+        methodTriples.push(`  code:paramCount ${method.params?.length || 0} .`);
+        triples.push(...methodTriples);
+        triples.push('');
+      });
+
+      // Remove trailing semicolon
+      const lastLine = triples[triples.length - 1];
+      if (lastLine.includes(';')) {
+        triples[triples.length - 1] = lastLine.replace(/\s;$/, ' .');
+      }
+
+    } else if (exp.type === 'variable') {
+      triples.push(`  a code:Variable ;`);
+      triples.push(`  code:name ${escapeLiteral(exp.name)} ;`);
+      triples.push(`  code:valueType ${escapeLiteral(exp.valueType)} .`);
+    }
+
+    triples.push('');
+  });
+
+  // Imports (for cross-referencing)
+  parsedFile.imports?.forEach((imp, idx) => {
+    const importNode = blankNode(`import_${idx}`);
+
+    triples.push(`# Import from: ${imp.source}`);
+    triples.push(`${fileURI}`);
+    triples.push(`  code:imports ${importNode} .`);
+    triples.push('');
+
+    triples.push(`${importNode}`);
+    triples.push(`  a code:Import ;`);
+    triples.push(`  code:source ${escapeLiteral(imp.source)} ;`);
+
+    imp.specifiers.forEach((spec, specIdx) => {
+      const specNode = blankNode(`import_${idx}_spec_${specIdx}`);
+      triples.push(`  code:specifier ${specNode} ;`);
+
+      triples.push(`${specNode}`);
+      triples.push(`  a code:ImportSpecifier ;`);
+      triples.push(`  code:imported ${escapeLiteral(spec.imported)} ;`);
+      triples.push(`  code:local ${escapeLiteral(spec.local)} ;`);
+      triples.push(`  code:specifierType ${escapeLiteral(spec.type)} .`);
+      triples.push('');
+    });
+
+    triples.push('');
+  });
+
+  // Build complete Turtle document
+  const prefixDeclarations = Object.entries(PREFIXES)
+    .map(([prefix, uri]) => `@prefix ${prefix}: <${uri}> .`)
+    .join('\n');
+
+  return `${prefixDeclarations}\n\n${triples.join('\n')}`;
+}
+
+/**
+ * Build RDF graph for multiple files
+ * @param {Array} parsedFiles - Array of parsed file data
+ * @returns {string} Combined Turtle RDF
+ */
+export function buildRDFGraphs(parsedFiles) {
+  const graphs = parsedFiles
+    .filter(file => !file.error)
+    .map(file => buildRDFGraph(file));
+
+  const prefixDeclarations = Object.entries(PREFIXES)
+    .map(([prefix, uri]) => `@prefix ${prefix}: <${uri}> .`)
+    .join('\n');
+
+  // Remove duplicate prefix declarations from individual graphs
+  const graphsWithoutPrefixes = graphs.map(graph =>
+    graph.replace(/@prefix[^\n]+\n/g, '').trim()
+  );
+
+  return `${prefixDeclarations}\n\n${graphsWithoutPrefixes.join('\n\n')}`;
+}
+
+/**
+ * Build JSON-LD representation
+ * @param {Object} parsedFile - Parsed file data
+ * @returns {Object} JSON-LD document
+ */
+export function buildJSONLD(parsedFile) {
+  const fileURI = generateURI(parsedFile.relativePath);
+
+  const document = {
+    '@context': PREFIXES,
+    '@id': fileURI,
+    '@type': ['fs:File', 'code:Module'],
+    'fs:path': parsedFile.relativePath,
+    'fs:absolutePath': parsedFile.file,
+    'code:commentCount': parsedFile.comments,
+    'code:exports': [],
+  };
+
+  parsedFile.exports.forEach(exp => {
+    const exportObj = {
+      '@id': `${fileURI}#${exp.name}`,
+      '@type': `code:${exp.type.charAt(0).toUpperCase() + exp.type.slice(1)}`,
+      'code:name': exp.name,
+    };
+
+    if (exp.description) {
+      exportObj['doc:description'] = exp.description;
+    }
+
+    if (exp.type === 'function') {
+      if (exp.params) {
+        exportObj['code:param'] = exp.params.map(param => ({
+          '@type': 'code:Parameter',
+          'code:name': param.name,
+          'code:type': param.type,
+          'code:optional': param.optional,
+          'doc:description': param.description,
+        }));
+      }
+
+      if (exp.returns) {
+        exportObj['code:returns'] = exp.returns.type;
+      }
+
+      if (exp.examples?.length) {
+        exportObj['doc:example'] = exp.examples;
+      }
+    }
+
+    document['code:exports'].push(exportObj);
+  });
+
+  return document;
+}
+
+export default { buildRDFGraph, buildRDFGraphs, buildJSONLD, PREFIXES };

package/src/doc-generator/scanner.mjs

@@ -0,0 +1,189 @@
+/**
+ * @fileoverview Workspace scanner for batch documentation generation
+ * Scans packages and finds all documentable source files
+ */
+
+import { readdir, stat } from 'fs/promises';
+import { join, relative } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+
+/**
+ * Scan workspace for source files
+ * @param {string} rootDir - Workspace root directory
+ * @param {Object} options - Scanner options
+ * @returns {Promise<Array>} Array of file paths grouped by package
+ */
+export async function scanWorkspace(rootDir, options = {}) {
+  const {
+    packagesDir = 'packages',
+    include = ['**/*.mjs', '**/*.js'],
+    exclude = ['**/node_modules/**', '**/dist/**', '**/test/**', '**/*.test.*', '**/*.spec.*'],
+  } = options;
+
+  const packagesPath = join(rootDir, packagesDir);
+  const packages = [];
+
+  try {
+    const packageDirs = await readdir(packagesPath);
+
+    for (const pkgName of packageDirs) {
+      const pkgPath = join(packagesPath, pkgName);
+      const pkgStat = await stat(pkgPath);
+
+      if (!pkgStat.isDirectory()) continue;
+
+      // Check if package has a src directory
+      const srcPath = join(pkgPath, 'src');
+      let hasSrc = false;
+      try {
+        const srcStat = await stat(srcPath);
+        hasSrc = srcStat.isDirectory();
+      } catch {
+        // No src directory
+      }
+
+      if (!hasSrc) continue;
+
+      // Scan for source files
+      const sourceFiles = await scanDirectory(srcPath, {
+        include,
+        exclude,
+        rootDir,
+      });
+
+      if (sourceFiles.length > 0) {
+        packages.push({
+          name: pkgName,
+          path: pkgPath,
+          relativePath: relative(rootDir, pkgPath),
+          srcPath,
+          sourceFiles,
+        });
+      }
+    }
+
+    return packages;
+  } catch (error) {
+    console.error(`Failed to scan workspace: ${error.message}`);
+    return [];
+  }
+}
+
+/**
+ * Recursively scan directory for source files
+ * @param {string} dir - Directory to scan
+ * @param {Object} options - Scan options
+ * @returns {Promise<Array>} Array of file paths
+ */
+async function scanDirectory(dir, options) {
+  const { include, exclude, rootDir } = options;
+  const files = [];
+
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      const relativePath = relative(rootDir, fullPath);
+
+      // Check exclusions
+      if (shouldExclude(relativePath, exclude)) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        // Recursively scan subdirectories
+        const subFiles = await scanDirectory(fullPath, options);
+        files.push(...subFiles);
+      } else if (entry.isFile()) {
+        // Check if file matches include patterns
+        if (shouldInclude(entry.name, include)) {
+          files.push(fullPath);
+        }
+      }
+    }
+  } catch (error) {
+    console.error(`Failed to scan directory ${dir}: ${error.message}`);
+  }
+
+  return files;
+}
+
+/**
+ * Check if path should be excluded
+ * @param {string} path - Path to check
+ * @param {Array<string>} patterns - Exclusion patterns
+ * @returns {boolean} True if should exclude
+ */
+function shouldExclude(path, patterns) {
+  return patterns.some(pattern => {
+    const regex = patternToRegex(pattern);
+    return regex.test(path);
+  });
+}
+
+/**
+ * Check if filename should be included
+ * @param {string} filename - Filename to check
+ * @param {Array<string>} patterns - Inclusion patterns
+ * @returns {boolean} True if should include
+ */
+function shouldInclude(filename, patterns) {
+  return patterns.some(pattern => {
+    const regex = patternToRegex(pattern);
+    return regex.test(filename);
+  });
+}
+
+/**
+ * Convert glob pattern to regex
+ * @param {string} pattern - Glob pattern
+ * @returns {RegExp} Regular expression
+ */
+function patternToRegex(pattern) {
+  // Simple glob to regex conversion
+  const regexPattern = pattern
+    .replace(/\*\*/g, '.*')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\./g, '\\.');
+
+  return new RegExp(`^${regexPattern}$`);
+}
+
+/**
+ * Group files by package and module
+ * @param {Array} packages - Scanned packages
+ * @returns {Object} Grouped file structure
+ */
+export function groupFilesByModule(packages) {
+  const grouped = {};
+
+  packages.forEach(pkg => {
+    const modules = new Map();
+
+    pkg.sourceFiles.forEach(filePath => {
+      const relativePath = relative(pkg.srcPath, filePath);
+      const parts = relativePath.split('/');
+
+      // Group by top-level directory in src/
+      const moduleName = parts.length > 1 ? parts[0] : 'root';
+
+      if (!modules.has(moduleName)) {
+        modules.set(moduleName, []);
+      }
+
+      modules.get(moduleName).push(filePath);
+    });
+
+    grouped[pkg.name] = {
+      ...pkg,
+      modules: Object.fromEntries(modules),
+    };
+  });
+
+  return grouped;
+}
+
+export default { scanWorkspace, groupFilesByModule };

package/src/engine/index.js

@@ -0,0 +1,42 @@
+/**
+ * DETERMINISTIC Template Engine - Complete Exports
+ *
+ * 4-Stage Pipeline: plan → render → post → attest
+ * 100% Deterministic guarantees with cryptographic attestation
+ */
+
+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);
+
+  return {
+    pipeline,
+    renderer: pipeline.renderer,
+
+    async render(template, data, opts = {}) {
+      return await pipeline.execute(template, data, opts);
+    },
+
+    async verifyDeterminism(template, data, iterations = 3) {
+      return await pipeline.verifyDeterminism(template, data, iterations);
+    },
+
+    async renderBatch(batch, opts = {}) {
+      return await pipeline.executeBatch(batch, opts);
+    },
+
+    getStats() { return pipeline.getStats(); },
+    resetStats() { pipeline.resetStats(); }
+  };
+}
+
+export default {
+  TemplateEngine,
+  DeterministicRenderer,
+  DeterministicPipeline,
+  createDeterministicEngine
+};