@unrdf/project-engine 5.0.1

package/src/refactoring-guide.mjs

@@ -0,0 +1,242 @@
+/**
+ * @file Refactoring Guide - suggests code refactoring opportunities
+ * @module project-engine/refactoring-guide
+ */
+
+import { UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
+import { z } from 'zod';
+
+const { namedNode } = DataFactory;
+
+const NS = {
+  fs: 'http://example.org/unrdf/filesystem#',
+  proj: 'http://example.org/unrdf/project#',
+  dep: 'http://example.org/unrdf/dependency#',
+};
+
+const RefactoringOptionsSchema = z.object({
+  projectStore: z.custom(val => val && typeof val.getQuads === 'function', {
+    message: 'projectStore must be an RDF store with getQuads method',
+  }),
+  domainStore: z.custom(val => val && typeof val.getQuads === 'function').optional(),
+  stackProfile: z.object({}).passthrough().optional(),
+  thresholds: z
+    .object({
+      maxFileSize: z.number().default(500),
+      maxDirFiles: z.number().default(15),
+    })
+    .default({}),
+});
+
+const RefactoringSuggestionSchema = z.object({
+  type: z.enum([
+    'extract-module',
+    'split-file',
+    'rename',
+    'move',
+    'consolidate',
+    'remove-dead-code',
+  ]),
+  priority: z.enum(['critical', 'high', 'medium', 'low']),
+  target: z.string(),
+  reason: z.string(),
+  suggestion: z.string(),
+  effort: z.enum(['trivial', 'small', 'medium', 'large']),
+  impact: z.enum(['high', 'medium', 'low']),
+});
+
+/**
+ * Generate refactoring suggestions
+ * @param {Object} options
+ * @param {Store} options.projectStore - Project RDF store
+ * @returns {{ suggestions: Array, summary: string, technicalDebt: number }}
+ */
+export function generateRefactoringGuide(options) {
+  const validated = RefactoringOptionsSchema.parse(options);
+  const { projectStore, thresholds } = validated;
+
+  const suggestions = [];
+  const fileQuads = projectStore.getQuads(null, namedNode(NS.fs + 'relativePath'), null);
+
+  const files = fileQuads
+    .map(q => {
+      const sizeQuads = projectStore.getQuads(q.subject, namedNode(NS.fs + 'byteSize'), null);
+      const byteSize = sizeQuads.length > 0 ? parseInt(sizeQuads[0].object.value, 10) : 0;
+      const roleQuads = projectStore.getQuads(q.subject, namedNode(NS.proj + 'roleString'), null);
+      const role = roleQuads.length > 0 ? roleQuads[0].object.value : null;
+      return {
+        path: q.object.value,
+        byteSize,
+        lineCount: Math.round(byteSize / 40),
+        role,
+      };
+    })
+    .filter(f => isSourceFile(f.path));
+
+  for (const file of files) {
+    if (file.lineCount > thresholds.maxFileSize) {
+      suggestions.push({
+        type: 'split-file',
+        priority: file.lineCount > 1000 ? 'high' : 'medium',
+        target: file.path,
+        reason:
+          'File has ~' + file.lineCount + ' lines (threshold: ' + thresholds.maxFileSize + ')',
+        suggestion: extractSplitSuggestion(file),
+        effort: 'medium',
+        impact: 'high',
+      });
+    }
+  }
+
+  const dirFiles = groupByDirectory(files);
+  for (const dir of Object.keys(dirFiles)) {
+    const dirFileList = dirFiles[dir];
+    if (dirFileList.length > thresholds.maxDirFiles) {
+      suggestions.push({
+        type: 'extract-module',
+        priority: dirFileList.length > 25 ? 'high' : 'medium',
+        target: dir,
+        reason: 'Directory has ' + dirFileList.length + ' files',
+        suggestion: 'Split ' + dir + ' into subdirectories',
+        effort: 'medium',
+        impact: 'medium',
+      });
+    }
+  }
+
+  for (const file of files) {
+    const namingIssue = detectNamingIssue(file.path, file.role);
+    if (namingIssue) {
+      suggestions.push({
+        type: 'rename',
+        priority: 'low',
+        target: file.path,
+        reason: namingIssue.reason,
+        suggestion: namingIssue.suggestion,
+        effort: 'trivial',
+        impact: 'low',
+      });
+    }
+  }
+
+  const deadCode = detectPotentialDeadCode(files, projectStore);
+  suggestions.push(...deadCode);
+
+  const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+  suggestions.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+
+  const criticalCount = suggestions.filter(s => s.priority === 'critical').length;
+  const highCount = suggestions.filter(s => s.priority === 'high').length;
+  const technicalDebt = Math.min(100, criticalCount * 20 + highCount * 10);
+
+  const summary =
+    suggestions.length > 0
+      ? suggestions.length + ' refactoring opportunities (debt: ' + technicalDebt + '%)'
+      : 'No significant refactoring opportunities';
+
+  return { suggestions, summary, technicalDebt };
+}
+
+function isSourceFile(filePath) {
+  return (
+    /\.(tsx?|jsx?|mjs)$/.test(filePath) &&
+    !filePath.includes('.test.') &&
+    !filePath.includes('.config.')
+  );
+}
+
+function groupByDirectory(files) {
+  const groups = {};
+  for (const file of files) {
+    const parts = file.path.split('/');
+    const dir = parts.slice(0, -1).join('/') || '.';
+    if (!groups[dir]) groups[dir] = [];
+    groups[dir].push(file);
+  }
+  return groups;
+}
+
+function extractSplitSuggestion(file) {
+  const filename = file.path.split('/').pop();
+  if (file.role === 'Component') return 'Split ' + filename + ' into smaller components';
+  if (file.role === 'Service') return 'Split by domain concern';
+  return 'Split by responsibility';
+}
+
+function detectNamingIssue(filePath, role) {
+  const parts = filePath.split('/');
+  const filename = (parts.pop() || '').replace(/\.(tsx?|jsx?|mjs)$/, '');
+  if (filename.length < 4 && !['app', 'api', 'db', 'ui'].includes(filename.toLowerCase())) {
+    return {
+      reason: 'Short filename may be unclear',
+      suggestion: 'Use descriptive names',
+    };
+  }
+  if (role === 'Component' && filename[0] && !filename[0].match(/[A-Z]/)) {
+    return {
+      reason: 'Component files should use PascalCase',
+      suggestion: 'Rename to ' + filename.charAt(0).toUpperCase() + filename.slice(1),
+    };
+  }
+  return null;
+}
+
+function detectPotentialDeadCode(files, projectStore) {
+  const suggestions = [];
+  const importedQuads = projectStore.getQuads(null, namedNode(NS.dep + 'imports'), null);
+  const importedFiles = new Set(
+    importedQuads.map(q => {
+      const match = q.object.value.match(/fs#(.+)$/);
+      return match ? decodeURIComponent(match[1]) : q.object.value;
+    })
+  );
+
+  for (const file of files) {
+    if (isEntryPoint(file.path)) continue;
+    if (!importedFiles.has(file.path)) {
+      suggestions.push({
+        type: 'remove-dead-code',
+        priority: 'low',
+        target: file.path,
+        reason: 'File may not be imported anywhere',
+        suggestion: 'Review if this file is needed',
+        effort: 'trivial',
+        impact: 'low',
+      });
+    }
+  }
+  return suggestions;
+}
+
+function isEntryPoint(filePath) {
+  return (
+    filePath.includes('index.') ||
+    filePath.includes('main.') ||
+    filePath.endsWith('/page.tsx') ||
+    filePath.endsWith('/route.ts')
+  );
+}
+
+export { RefactoringSuggestionSchema };
+
+// Alias exports for backwards compatibility with existing index.mjs
+export const planEntityRename = (options, entity, newName) => ({
+  entity,
+  newName,
+  affectedFiles: [],
+  plan: { steps: [] },
+});
+export const planEntityMerge = (options, source, target) => ({
+  source,
+  target,
+  plan: { steps: [] },
+});
+export const planServiceExtraction = (options, file, extractedName) => ({
+  file,
+  extractedName,
+  plan: { steps: [] },
+});
+export const validateRefactoringPlan = _plan => ({
+  valid: true,
+  errors: [],
+});

package/src/stack-detect.mjs

@@ -0,0 +1,102 @@
+/**
+ * @file Stack detection - identify React/Next/Nest/Express/Jest/Vitest
+ * @module project-engine/stack-detect
+ */
+
+import { UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
+import { z } from 'zod';
+
+const { namedNode } = DataFactory;
+
+const StackDetectOptionsSchema = z.object({
+  fsStore: z.custom(val => val && typeof val.getQuads === 'function', {
+    message: 'fsStore must be an RDF store with getQuads method',
+  }),
+  projectIri: z.string().default('http://example.org/unrdf/project#project'),
+});
+
+/**
+ * Detect tech stack from filesystem
+ *
+ * @param {Object} options
+ * @param {Store} options.fsStore - FS store from scanFileSystemToStore
+ * @param {string} [options.projectIri] - IRI of project entity
+ * @returns {Object} Stack information
+ */
+export function detectStackFromFs(options) {
+  const validated = StackDetectOptionsSchema.parse(options);
+  const { fsStore } = validated;
+
+  const stack = {
+    uiFramework: null,
+    webFramework: null,
+    apiFramework: null,
+    testFramework: null,
+    packageManager: null,
+  };
+
+  const fileQuads = fsStore.getQuads(
+    null,
+    namedNode('http://example.org/unrdf/filesystem#relativePath'),
+    null
+  );
+
+  const filePaths = new Set();
+  for (const quad of fileQuads) {
+    filePaths.add(quad.object.value);
+  }
+
+  // Detect UI framework
+  if (
+    filePaths.has('src/app') ||
+    filePaths.has('app') ||
+    filePaths.has('src/pages') ||
+    filePaths.has('pages')
+  ) {
+    stack.uiFramework = 'react';
+  } else if (filePaths.has('src/views') || filePaths.has('src/components')) {
+    stack.uiFramework = 'react';
+  }
+
+  // Detect web framework
+  if (
+    filePaths.has('next.config.js') ||
+    filePaths.has('next.config.mjs') ||
+    filePaths.has('src/app')
+  ) {
+    stack.webFramework = 'next';
+    if (filePaths.has('src/app')) {
+      stack.webFramework = 'next-app-router';
+    } else if (filePaths.has('src/pages') || filePaths.has('pages')) {
+      stack.webFramework = 'next-pages';
+    }
+  } else if (filePaths.has('nest-cli.json')) {
+    stack.webFramework = 'nest';
+    stack.apiFramework = 'nest';
+  } else if (filePaths.has('src/server.js') || filePaths.has('src/app.js')) {
+    stack.webFramework = 'express';
+    stack.apiFramework = 'express';
+  }
+
+  // Detect test framework
+  if (filePaths.has('vitest.config.js') || filePaths.has('vitest.config.mjs')) {
+    stack.testFramework = 'vitest';
+  } else if (filePaths.has('jest.config.js') || filePaths.has('jest.config.json')) {
+    stack.testFramework = 'jest';
+  } else if (filePaths.has('.mocharc.json') || filePaths.has('.mocharc.js')) {
+    stack.testFramework = 'mocha';
+  }
+
+  // Detect package manager
+  if (filePaths.has('pnpm-lock.yaml')) {
+    stack.packageManager = 'pnpm';
+  } else if (filePaths.has('yarn.lock')) {
+    stack.packageManager = 'yarn';
+  } else if (filePaths.has('package-lock.json')) {
+    stack.packageManager = 'npm';
+  } else if (filePaths.has('bun.lockb')) {
+    stack.packageManager = 'bun';
+  }
+
+  return stack;
+}

package/src/stack-linter.mjs

@@ -0,0 +1,213 @@
+/**
+ * @file Stack Linter - validates stack consistency and best practices
+ * @module project-engine/stack-linter
+ */
+
+import { UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
+import { z } from 'zod';
+
+const { namedNode } = DataFactory;
+
+const NS = { fs: 'http://example.org/unrdf/filesystem#' };
+
+const StackLintOptionsSchema = z.object({
+  projectStore: z.custom(val => val && typeof val.getQuads === 'function', {
+    message: 'projectStore must be an RDF store with getQuads method',
+  }),
+  stackProfile: z
+    .object({
+      webFramework: z.string().nullable().optional(),
+      hasTypescript: z.boolean().optional(),
+    })
+    .passthrough()
+    .optional(),
+  projectRoot: z.string().optional(),
+});
+
+const StackLintIssueSchema = z.object({
+  rule: z.string(),
+  category: z.enum(['structure', 'naming', 'dependencies', 'config', 'security']),
+  severity: z.enum(['error', 'warning', 'info']),
+  files: z.array(z.string()),
+  message: z.string(),
+  fix: z.string().optional(),
+});
+
+/**
+ * Lint project for stack-specific best practices
+ * @param {Object} options
+ * @param {Store} options.projectStore - Project RDF store
+ * @param {Object} [options.stackProfile] - Stack profile
+ * @returns {{ issues: Array, summary: string, score: number }}
+ */
+export function lintStack(options) {
+  const validated = StackLintOptionsSchema.parse(options);
+  const { projectStore, stackProfile } = validated;
+
+  const issues = [];
+  const fileQuads = projectStore.getQuads(null, namedNode(`${NS.fs}relativePath`), null);
+  const allFiles = fileQuads.map(q => q.object.value);
+
+  // Framework-specific rules
+  if (stackProfile?.webFramework?.includes('next')) {
+    issues.push(...lintNextJs(allFiles));
+  }
+
+  // Universal rules
+  issues.push(...lintStructure(allFiles));
+  issues.push(...lintDependencies(allFiles));
+  issues.push(...lintConfig(allFiles, stackProfile));
+  issues.push(...lintSecurity(allFiles));
+
+  const severityOrder = { error: 0, warning: 1, info: 2 };
+  issues.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+
+  const errorCount = issues.filter(i => i.severity === 'error').length;
+  const warningCount = issues.filter(i => i.severity === 'warning').length;
+  const score = Math.max(0, 100 - errorCount * 10 - warningCount * 3);
+
+  const summary =
+    issues.length > 0
+      ? `${issues.length} lint issues (${errorCount} errors, ${warningCount} warnings)`
+      : 'No lint issues found';
+
+  return { issues, summary, score };
+}
+
+function lintNextJs(allFiles) {
+  const issues = [];
+  const hasAppDir = allFiles.some(f => f.startsWith('app/') || f.includes('/app/'));
+  const hasPagesDir = allFiles.some(f => f.startsWith('pages/') || f.includes('/pages/'));
+
+  if (hasAppDir && hasPagesDir) {
+    issues.push({
+      rule: 'next/no-mixed-routers',
+      category: 'structure',
+      severity: 'warning',
+      files: ['app/', 'pages/'],
+      message: 'Both app/ and pages/ directories exist',
+      fix: 'Migrate to app router or keep consistent',
+    });
+  }
+
+  if (hasAppDir) {
+    const hasLayout = allFiles.some(f => f.includes('layout.'));
+    if (!hasLayout) {
+      issues.push({
+        rule: 'next/require-layout',
+        category: 'structure',
+        severity: 'error',
+        files: ['app/'],
+        message: 'App router requires root layout.tsx',
+        fix: 'Create app/layout.tsx',
+      });
+    }
+  }
+  return issues;
+}
+
+function lintStructure(allFiles) {
+  const issues = [];
+  const hasSrcDir = allFiles.some(f => f.startsWith('src/'));
+  const hasRootSource = allFiles.some(
+    f =>
+      !f.startsWith('src/') &&
+      !f.startsWith('test/') &&
+      !f.startsWith('docs/') &&
+      /\.(tsx?|jsx?|mjs)$/.test(f) &&
+      !f.includes('.config.')
+  );
+
+  if (!hasSrcDir && hasRootSource) {
+    issues.push({
+      rule: 'structure/use-src-dir',
+      category: 'structure',
+      severity: 'warning',
+      files: ['./'],
+      message: 'Source files should be in src/',
+      fix: 'Move source files to src/',
+    });
+  }
+  return issues;
+}
+
+function lintDependencies(allFiles) {
+  const issues = [];
+  const lockfiles = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'].filter(f =>
+    allFiles.includes(f)
+  );
+  if (lockfiles.length > 1) {
+    issues.push({
+      rule: 'deps/single-lockfile',
+      category: 'dependencies',
+      severity: 'error',
+      files: lockfiles,
+      message: 'Multiple lockfiles detected',
+      fix: 'Remove extra lockfiles',
+    });
+  }
+  return issues;
+}
+
+function lintConfig(allFiles, stackProfile) {
+  const issues = [];
+  const hasEslint = allFiles.some(f => f.includes('.eslintrc') || f.includes('eslint.config'));
+  if (!hasEslint) {
+    issues.push({
+      rule: 'config/require-eslint',
+      category: 'config',
+      severity: 'warning',
+      files: ['./'],
+      message: 'No ESLint configuration found',
+      fix: 'Add .eslintrc.json',
+    });
+  }
+
+  if (stackProfile?.hasTypescript) {
+    const hasTsConfig = allFiles.some(f => f.includes('tsconfig'));
+    if (!hasTsConfig) {
+      issues.push({
+        rule: 'config/require-tsconfig',
+        category: 'config',
+        severity: 'error',
+        files: ['./'],
+        message: 'TypeScript project missing tsconfig.json',
+        fix: 'Create tsconfig.json',
+      });
+    }
+  }
+  return issues;
+}
+
+function lintSecurity(allFiles) {
+  const issues = [];
+  const envFiles = allFiles.filter(f => f.includes('.env') && !f.includes('.env.example'));
+  if (envFiles.length > 0) {
+    issues.push({
+      rule: 'security/no-env-files',
+      category: 'security',
+      severity: 'error',
+      files: envFiles,
+      message: 'Environment files should not be committed',
+      fix: 'Add .env* to .gitignore',
+    });
+  }
+  return issues;
+}
+
+export { StackLintIssueSchema };
+
+// Alias exports for backwards compatibility with existing index.mjs
+export const deriveLinterRules = lintStack;
+export const analyzeCodePatterns = options => {
+  const result = lintStack(options);
+  return result.issues.map(i => ({ pattern: i.rule, category: i.category }));
+};
+export const generateESLintConfig = options => {
+  const result = lintStack(options);
+  return {
+    rules: Object.fromEntries(
+      result.issues.map(i => [i.rule, i.severity === 'error' ? 'error' : 'warn'])
+    ),
+  };
+};