@unrdf/project-engine 5.0.1

package/src/project-config.mjs

@@ -0,0 +1,142 @@
+/**
+ * @file Project engine configuration - central config for all capabilities
+ * @module project-engine/project-config
+ */
+
+import { z } from 'zod';
+
+/**
+ * Full project engine configuration schema
+ */
+export const ProjectEngineConfigSchema = z
+  .object({
+    // Filesystem scanning
+    fs: z
+      .object({
+        ignorePatterns: z.array(z.string()).optional(),
+        baseIri: z.string().default('http://example.org/unrdf/fs#'),
+        scanHiddenFiles: z.boolean().default(false),
+      })
+      .optional(),
+
+    // Project modeling
+    project: z
+      .object({
+        conventions: z
+          .object({
+            sourcePaths: z.array(z.string()).default(['src']),
+            featurePaths: z.array(z.string()).default(['features', 'modules']),
+            testPaths: z.array(z.string()).default(['__tests__', 'test', 'tests']),
+          })
+          .optional(),
+        baseIri: z.string().default('http://example.org/unrdf/project#'),
+      })
+      .optional(),
+
+    // Golden structure
+    golden: z
+      .object({
+        profile: z
+          .enum([
+            'react-feature-v1',
+            'next-app-router-v1',
+            'next-pages-v1',
+            'nest-api-v1',
+            'express-api-v1',
+          ])
+          .optional(),
+        loadFromPath: z.string().optional(),
+      })
+      .optional(),
+
+    // Diff/comparison
+    diff: z
+      .object({
+        structureLens: z.literal('project-structure').default('project-structure'),
+        transactionLens: z.string().optional(),
+      })
+      .optional(),
+
+    // Materialization
+    materialize: z
+      .object({
+        templateConfig: z.record(z.string(), z.any()).optional(),
+        outputRoot: z.string().default('.'),
+        dryRun: z.boolean().default(false),
+      })
+      .optional(),
+
+    // Observability
+    observability: z
+      .object({
+        enableTracing: z.boolean().default(true),
+        enableMetrics: z.boolean().default(true),
+      })
+      .optional(),
+  })
+  .strict();
+
+/**
+ * Get project engine configuration from environment + defaults
+ *
+ * @param {Object} [overrides] - Config overrides
+ * @returns {Object} Validated configuration
+ */
+export function getProjectEngineConfig(overrides = {}) {
+  const defaults = {
+    fs: {
+      ignorePatterns: ['node_modules', '.git', 'dist', 'build', '.next', '.turbo', 'coverage'],
+      baseIri: 'http://example.org/unrdf/fs#',
+    },
+    project: {
+      conventions: {
+        sourcePaths: ['src'],
+        featurePaths: ['features', 'modules'],
+        testPaths: ['__tests__', 'test', 'tests', 'spec'],
+      },
+      baseIri: 'http://example.org/unrdf/project#',
+    },
+    golden: {
+      profile: 'react-feature-v1',
+    },
+    diff: {
+      structureLens: 'project-structure',
+    },
+    materialize: {
+      outputRoot: '.',
+      dryRun: false,
+    },
+    observability: {
+      enableTracing: true,
+      enableMetrics: true,
+    },
+  };
+
+  // Merge overrides
+  const merged = deepMerge(defaults, overrides);
+
+  // Validate
+  return ProjectEngineConfigSchema.parse(merged);
+}
+
+/**
+ * Deep merge objects for configuration
+ *
+ * @private
+ */
+function deepMerge(target, source) {
+  const result = { ...target };
+
+  for (const key in source) {
+    if (Array.isArray(source[key]) && Array.isArray(result[key])) {
+      // Merge arrays by combining them
+      result[key] = [...result[key], ...source[key]];
+    } else if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+      result[key] = deepMerge(result[key] || {}, source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+
+  return result;
+}

package/src/project-diff.mjs

@@ -0,0 +1,28 @@
+/**
+ * @file Project structure diff - convenience wrapper over diff.mjs
+ * @module project-engine/project-diff
+ */
+
+import { diffOntologyFromStores } from '../diff.mjs';
+import { ProjectStructureLens } from './lens/project-structure.mjs';
+import { z } from 'zod';
+
+const ProjectDiffOptionsSchema = z.object({
+  actualStore: z.object({}).passthrough(),
+  goldenStore: z.object({}).passthrough(),
+});
+
+/**
+ * Compute project structure diff using low-level diff.mjs
+ *
+ * @param {Object} options
+ * @param {Store} options.actualStore - Current project graph
+ * @param {Store} options.goldenStore - Expected golden structure
+ * @returns {OntologyDiff}
+ */
+export function diffProjectStructure(options) {
+  const validated = ProjectDiffOptionsSchema.parse(options);
+  const { actualStore, goldenStore } = validated;
+
+  return diffOntologyFromStores(goldenStore, actualStore, ProjectStructureLens);
+}

package/src/project-engine/build-utils.mjs

@@ -0,0 +1,237 @@
+/**
+ * @file Build Utilities - Package building and verification
+ * @module @unrdf/project-engine/build-utils
+ */
+
+import { readFile, readdir, access, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+
+/**
+ * Package verification schema
+ */
+const VerificationResultSchema = z.object({
+  valid: z.boolean(),
+  errors: z.array(z.string()),
+  warnings: z.array(z.string()),
+  checkedFiles: z.array(z.string()),
+});
+
+/**
+ * Build single package
+ * @param {string} packagePath - Path to package directory
+ * @returns {Promise<Object>} Build result
+ *
+ * @throws {TypeError} If packagePath is not a string
+ * @throws {Error} If build fails
+ *
+ * @example
+ * const result = await buildPackage('./packages/core');
+ * console.log('Build status:', result.success);
+ */
+export async function buildPackage(packagePath) {
+  if (typeof packagePath !== 'string') {
+    throw new TypeError('buildPackage: packagePath must be a string');
+  }
+
+  try {
+    const { execFile } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    const execFileAsync = promisify(execFile);
+
+    // Check if package has build script
+    const packageJsonPath = join(packagePath, 'package.json');
+    const packageJsonContent = await readFile(packageJsonPath, 'utf-8');
+    const packageJson = JSON.parse(packageJsonContent);
+
+    if (!packageJson.scripts || !packageJson.scripts.build) {
+      return {
+        success: true,
+        message: 'No build script defined',
+        output: '',
+      };
+    }
+
+    // Run build script
+    const { stdout, stderr } = await execFileAsync('pnpm', ['run', 'build'], {
+      cwd: packagePath,
+    });
+
+    return {
+      success: true,
+      message: 'Build completed successfully',
+      output: stdout,
+      errors: stderr,
+    };
+  } catch (error) {
+    throw new Error(`buildPackage failed: ${error.message}`);
+  }
+}
+
+/**
+ * Verify package integrity
+ * @param {string} packagePath - Path to package directory
+ * @returns {Promise<Object>} Verification result with errors/warnings
+ *
+ * @throws {TypeError} If packagePath is not a string
+ * @throws {Error} If verification fails
+ *
+ * @example
+ * const result = await verifyPackage('./packages/core');
+ * console.log('Valid:', result.valid);
+ * console.log('Errors:', result.errors);
+ */
+export async function verifyPackage(packagePath) {
+  if (typeof packagePath !== 'string') {
+    throw new TypeError('verifyPackage: packagePath must be a string');
+  }
+
+  const errors = [];
+  const warnings = [];
+  const checkedFiles = [];
+
+  try {
+    // Check package.json exists
+    const packageJsonPath = join(packagePath, 'package.json');
+    try {
+      await access(packageJsonPath);
+      checkedFiles.push('package.json');
+
+      const content = await readFile(packageJsonPath, 'utf-8');
+      const packageJson = JSON.parse(content);
+
+      // Validate required fields
+      if (!packageJson.name) {
+        errors.push('package.json missing "name" field');
+      }
+      if (!packageJson.version) {
+        errors.push('package.json missing "version" field');
+      }
+      if (!packageJson.type || packageJson.type !== 'module') {
+        errors.push('package.json must have "type": "module"');
+      }
+
+      // Check exports field
+      if (!packageJson.exports) {
+        warnings.push('package.json missing "exports" field');
+      }
+
+      // Verify main entry point exists
+      if (packageJson.main) {
+        const mainPath = join(packagePath, packageJson.main);
+        try {
+          await access(mainPath);
+          checkedFiles.push(packageJson.main);
+        } catch {
+          errors.push(`Main entry point not found: ${packageJson.main}`);
+        }
+      }
+
+      // Check for README
+      const readmePath = join(packagePath, 'README.md');
+      try {
+        await access(readmePath);
+        checkedFiles.push('README.md');
+      } catch {
+        warnings.push('README.md not found');
+      }
+
+      // Check for LICENSE
+      const licensePath = join(packagePath, 'LICENSE');
+      try {
+        await access(licensePath);
+        checkedFiles.push('LICENSE');
+      } catch {
+        warnings.push('LICENSE file not found');
+      }
+
+      // Check src directory exists
+      const srcPath = join(packagePath, 'src');
+      try {
+        const srcStat = await stat(srcPath);
+        if (!srcStat.isDirectory()) {
+          errors.push('src must be a directory');
+        }
+        checkedFiles.push('src/');
+      } catch {
+        errors.push('src directory not found');
+      }
+
+      // Check test directory
+      const testPath = join(packagePath, 'test');
+      try {
+        const testStat = await stat(testPath);
+        if (!testStat.isDirectory()) {
+          warnings.push('test should be a directory');
+        }
+        checkedFiles.push('test/');
+      } catch {
+        warnings.push('test directory not found');
+      }
+    } catch {
+      errors.push('package.json not found or invalid JSON');
+    }
+
+    const result = {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+      checkedFiles,
+    };
+
+    return VerificationResultSchema.parse(result);
+  } catch (error) {
+    throw new Error(`verifyPackage failed: ${error.message}`);
+  }
+}
+
+/**
+ * List all packages in monorepo
+ * @param {string} [monorepoPath='.'] - Path to monorepo root
+ * @returns {Promise<Array<Object>>} List of packages with metadata
+ *
+ * @throws {TypeError} If monorepoPath is not a string
+ * @throws {Error} If monorepo cannot be scanned
+ *
+ * @example
+ * const packages = await listPackages();
+ * packages.forEach(pkg => console.log(pkg.name, pkg.path));
+ */
+export async function listPackages(monorepoPath = '.') {
+  if (typeof monorepoPath !== 'string') {
+    throw new TypeError('listPackages: monorepoPath must be a string');
+  }
+
+  try {
+    const packagesPath = join(monorepoPath, 'packages');
+    const entries = await readdir(packagesPath, { withFileTypes: true });
+
+    const packages = [];
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const packagePath = join(packagesPath, entry.name);
+        const packageJsonPath = join(packagePath, 'package.json');
+
+        try {
+          const content = await readFile(packageJsonPath, 'utf-8');
+          const packageJson = JSON.parse(content);
+
+          packages.push({
+            name: packageJson.name,
+            version: packageJson.version,
+            description: packageJson.description || '',
+            path: packagePath,
+            private: packageJson.private || false,
+          });
+        } catch {
+          // Skip invalid packages
+        }
+      }
+    }
+
+    return packages;
+  } catch (error) {
+    throw new Error(`listPackages failed: ${error.message}`);
+  }
+}

package/src/project-engine/code-analyzer.mjs

@@ -0,0 +1,248 @@
+/**
+ * @file Code Analyzer - Package quality metrics and analysis
+ * @module @unrdf/project-engine/code-analyzer
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+
+/**
+ * Package analysis schema
+ */
+const PackageAnalysisSchema = z.object({
+  name: z.string(),
+  linesOfCode: z.number(),
+  fileCount: z.number(),
+  exportCount: z.number(),
+  testCoverage: z.number().min(0).max(100),
+  dependencies: z.array(z.string()),
+  devDependencies: z.array(z.string()),
+  publicApis: z.array(z.string()),
+  complexity: z.enum(['low', 'medium', 'high']),
+});
+
+/**
+ * Analyze package quality metrics
+ * @param {string} packagePath - Path to package directory
+ * @returns {Promise<Object>} Package analysis results
+ *
+ * @throws {TypeError} If packagePath is not a string
+ * @throws {Error} If package cannot be analyzed
+ *
+ * @example
+ * const analysis = await analyzePackage('./packages/core');
+ * console.log('Lines of code:', analysis.linesOfCode);
+ * console.log('Test coverage:', analysis.testCoverage);
+ */
+export async function analyzePackage(packagePath) {
+  if (typeof packagePath !== 'string') {
+    throw new TypeError('analyzePackage: packagePath must be a string');
+  }
+
+  try {
+    // Read package.json
+    const packageJsonPath = join(packagePath, 'package.json');
+    const packageJsonContent = await readFile(packageJsonPath, 'utf-8');
+    const packageJson = JSON.parse(packageJsonContent);
+
+    // Count lines of code
+    const srcPath = join(packagePath, 'src');
+    const sourceFiles = await findFiles(srcPath, '.mjs');
+    let linesOfCode = 0;
+
+    for (const file of sourceFiles) {
+      const content = await readFile(file, 'utf-8');
+      linesOfCode += content.split('\n').length;
+    }
+
+    // Find all exports
+    const publicApis = [];
+    for (const file of sourceFiles) {
+      const exports = await findExports(file);
+      publicApis.push(...exports);
+    }
+
+    // Estimate test coverage
+    const testPath = join(packagePath, 'test');
+    const testFiles = await findFiles(testPath, '.test.mjs');
+    const testCoverage = await estimateTestCoverage(sourceFiles, testFiles);
+
+    // Determine complexity
+    const complexity = determineComplexity(linesOfCode, publicApis.length, sourceFiles.length);
+
+    const analysis = {
+      name: packageJson.name,
+      linesOfCode,
+      fileCount: sourceFiles.length,
+      exportCount: publicApis.length,
+      testCoverage,
+      dependencies: Object.keys(packageJson.dependencies || {}),
+      devDependencies: Object.keys(packageJson.devDependencies || {}),
+      publicApis,
+      complexity,
+    };
+
+    return PackageAnalysisSchema.parse(analysis);
+  } catch (error) {
+    throw new Error(`analyzePackage failed: ${error.message}`);
+  }
+}
+
+/**
+ * Find all exports from a module
+ * @param {string} filePath - Path to module file
+ * @returns {Promise<Array<string>>} List of exported identifiers
+ *
+ * @throws {TypeError} If filePath is not a string
+ * @throws {Error} If file cannot be read
+ *
+ * @example
+ * const exports = await findExports('./src/index.mjs');
+ * console.log('Exports:', exports);
+ */
+export async function findExports(filePath) {
+  if (typeof filePath !== 'string') {
+    throw new TypeError('findExports: filePath must be a string');
+  }
+
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    const exports = [];
+
+    // Named exports: export function/const/let/class name
+    const namedMatches = content.matchAll(
+      /export\s+(async\s+)?(function|const|let|class)\s+(\w+)/g
+    );
+    for (const match of namedMatches) {
+      exports.push(match[3]);
+    }
+
+    // Export { name1, name2 }
+    const braceMatches = content.matchAll(/export\s+\{([^}]+)\}/g);
+    for (const match of braceMatches) {
+      const names = match[1].split(',').map(n => n.trim().split(/\s+as\s+/)[0]);
+      exports.push(...names);
+    }
+
+    return exports;
+  } catch (error) {
+    throw new Error(`findExports failed: ${error.message}`);
+  }
+}
+
+/**
+ * Estimate test coverage percentage
+ * @param {Array<string>} sourceFiles - Source file paths
+ * @param {Array<string>} testFiles - Test file paths
+ * @returns {Promise<number>} Estimated coverage percentage
+ *
+ * @throws {TypeError} If arguments are not arrays
+ *
+ * @example
+ * const coverage = await countCoverage(['src/a.mjs'], ['test/a.test.mjs']);
+ * console.log('Coverage:', coverage + '%');
+ */
+export async function countCoverage(sourceFiles, testFiles) {
+  if (!Array.isArray(sourceFiles)) {
+    throw new TypeError('countCoverage: sourceFiles must be an array');
+  }
+  if (!Array.isArray(testFiles)) {
+    throw new TypeError('countCoverage: testFiles must be an array');
+  }
+
+  return estimateTestCoverage(sourceFiles, testFiles);
+}
+
+/**
+ * Find files with specific extension
+ * @param {string} dirPath - Directory path
+ * @param {string} extension - File extension
+ * @returns {Promise<Array<string>>} List of file paths
+ */
+async function findFiles(dirPath, extension) {
+  const files = [];
+
+  try {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dirPath, entry.name);
+
+      if (entry.isDirectory()) {
+        const subFiles = await findFiles(fullPath, extension);
+        files.push(...subFiles);
+      } else if (entry.isFile() && entry.name.endsWith(extension)) {
+        files.push(fullPath);
+      }
+    }
+  } catch (error) {
+    // Directory doesn't exist
+  }
+
+  return files;
+}
+
+/**
+ * Estimate test coverage heuristically
+ * @param {Array<string>} sourceFiles - Source file paths
+ * @param {Array<string>} testFiles - Test file paths
+ * @returns {Promise<number>} Coverage percentage
+ */
+async function estimateTestCoverage(sourceFiles, testFiles) {
+  if (sourceFiles.length === 0) {
+    return 0;
+  }
+
+  if (testFiles.length === 0) {
+    return 0;
+  }
+
+  // Heuristic: ratio of test files to source files
+  const ratio = testFiles.length / sourceFiles.length;
+
+  // Count test assertions as proxy for coverage
+  let totalAssertions = 0;
+  for (const testFile of testFiles) {
+    const content = await readFile(testFile, 'utf-8');
+    const assertionCount = (content.match(/expect\(/g) || []).length;
+    totalAssertions += assertionCount;
+  }
+
+  // Count source functions
+  let totalFunctions = 0;
+  for (const srcFile of sourceFiles) {
+    const content = await readFile(srcFile, 'utf-8');
+    const functionCount = (content.match(/export\s+(async\s+)?function/g) || []).length;
+    totalFunctions += functionCount;
+  }
+
+  if (totalFunctions === 0) {
+    return ratio * 50; // Base estimate
+  }
+
+  // Coverage estimate: assertions per function
+  const assertionsPerFunction = totalAssertions / totalFunctions;
+  const coverageEstimate = Math.min(assertionsPerFunction * 30, 100);
+
+  return Math.round(coverageEstimate);
+}
+
+/**
+ * Determine package complexity
+ * @param {number} linesOfCode - Total lines of code
+ * @param {number} exportCount - Number of exports
+ * @param {number} fileCount - Number of files
+ * @returns {string} Complexity level
+ */
+function determineComplexity(linesOfCode, exportCount, fileCount) {
+  const score = linesOfCode / 100 + exportCount * 2 + fileCount * 5;
+
+  if (score < 50) {
+    return 'low';
+  } else if (score < 200) {
+    return 'medium';
+  } else {
+    return 'high';
+  }
+}