@unrdf/project-engine 5.0.1

package/src/autonomic-mapek.mjs

@@ -0,0 +1,511 @@
+/**
+ * @file Autonomic MAPEK Loop - Self-healing knowledge system
+ * @module project-engine/autonomic-mapek
+ *
+ * @description
+ * Full autonomic system using MAPEK (Monitor-Analyze-Plan-Execute-Knowledge):
+ * - Monitor: Track drift, type mismatches, hotspots continuously
+ * - Analyze: Gap finder, type auditor, complexity analysis
+ * - Plan: Generate fix plans for detected issues
+ * - Execute: Apply fixes via knowledge hooks
+ * - Knowledge: Learn patterns and update policies
+ *
+ * Integrated with UNRDF Knowledge Hooks for autonomous self-healing.
+ */
+
+import { z } from 'zod';
+import { findMissingRoles } from './gap-finder.mjs';
+import { auditTypeConsistency } from './type-auditor.mjs';
+import { analyzeHotspots } from './hotspot-analyzer.mjs';
+import { computeDrift } from './drift-snapshot.mjs';
+
+const _MapekStateSchema = z.object({
+  phase: z.enum(['monitor', 'analyze', 'plan', 'execute', 'knowledge']),
+  timestamp: z.string().datetime(),
+  findings: z.object({}).passthrough(),
+  actions: z.array(z.object({}).passthrough()).default([]),
+  metrics: z.object({
+    gapScore: z.number().default(0),
+    typeScore: z.number().default(0),
+    hotspotScore: z.number().default(0),
+    driftSeverity: z.string().default('none'),
+  }),
+});
+
+/**
+ * Autonomic MAPEK Loop - Single iteration
+ *
+ * @param {Object} options
+ * @param {Store} options.projectStore - RDF project structure
+ * @param {Store} options.domainStore - RDF domain model
+ * @param {Store} options.baselineSnapshot - From createStructureSnapshot
+ * @param {string} options.projectRoot - File system root
+ * @param {Object} options.stackProfile - Stack detection result
+ * @param {Object} options.knowledge - Learned patterns from previous runs
+ * @returns {Object} { phase, findings, actions, nextPhase, shouldRepeat }
+ */
+export async function runMapekIteration(options) {
+  const validated = 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', {
+        message: 'domainStore must be an RDF store with getQuads method',
+      }),
+      baselineSnapshot: z.object({}).passthrough().optional(),
+      projectRoot: z.string(),
+      stackProfile: z.object({}).passthrough().optional(),
+      knowledge: z.object({}).passthrough().optional(),
+    })
+    .parse(options);
+
+  const state = {
+    phase: 'monitor',
+    timestamp: new Date().toISOString(),
+    findings: {},
+    actions: [],
+    metrics: {
+      gapScore: 0,
+      typeScore: 0,
+      hotspotScore: 0,
+      driftSeverity: 'none',
+    },
+  };
+
+  // ===== PHASE 1: MONITOR =====
+  // Continuously observe system state
+  state.findings.gaps = findMissingRoles({
+    domainStore: validated.domainStore,
+    projectStore: validated.projectStore,
+    stackProfile: validated.stackProfile,
+  });
+
+  state.findings.typeIssues = await auditTypeConsistency({
+    domainStore: validated.domainStore,
+    fsStore: validated.projectStore,
+    stackProfile: validated.stackProfile,
+    projectRoot: validated.projectRoot,
+  });
+
+  state.findings.hotspots = analyzeHotspots({
+    projectStore: validated.projectStore,
+    domainStore: validated.domainStore,
+    stackProfile: validated.stackProfile,
+  });
+
+  if (validated.baselineSnapshot) {
+    state.findings.drift = computeDrift(validated.projectStore, validated.baselineSnapshot);
+  }
+
+  // ===== PHASE 2: ANALYZE =====
+  // Interpret findings and calculate health metrics
+  state.phase = 'analyze';
+
+  // Gap severity (0-100, higher = more missing)
+  const gapCount = state.findings.gaps?.gaps?.length || 0;
+  const criticalGaps = state.findings.gaps?.gaps?.filter(g => g.score > 80).length || 0;
+  state.metrics.gapScore = Math.min(100, gapCount * 10 + criticalGaps * 20);
+
+  // Type safety score (0-100, higher = more problems)
+  const typeCount = state.findings.typeIssues?.mismatches?.length || 0;
+  const highSeverityTypes =
+    state.findings.typeIssues?.mismatches?.filter(m => m.severity === 'high').length || 0;
+  state.metrics.typeScore = Math.min(100, typeCount * 15 + highSeverityTypes * 25);
+
+  // Hotspot score (average risk of identified hotspots)
+  const hotspotCount = state.findings.hotspots?.hotspots?.length || 0;
+  const highRiskCount =
+    state.findings.hotspots?.hotspots?.filter(h => h.risk === 'HIGH').length || 0;
+  state.metrics.hotspotScore = Math.min(100, hotspotCount * 5 + highRiskCount * 30);
+
+  // Drift severity (from computeDrift)
+  state.metrics.driftSeverity = state.findings.drift?.driftSeverity || 'none';
+
+  // Overall health
+  const overallHealth =
+    (state.metrics.gapScore * 0.3 +
+      state.metrics.typeScore * 0.3 +
+      state.metrics.hotspotScore * 0.2 +
+      (state.metrics.driftSeverity === 'major'
+        ? 50
+        : state.metrics.driftSeverity === 'minor'
+          ? 25
+          : 0) *
+        0.2) /
+    100;
+
+  // ===== PHASE 3: PLAN =====
+  // Decide what to do about findings
+  state.phase = 'plan';
+
+  const decisions = [];
+
+  // Decision 1: Fix type mismatches (highest priority)
+  if (state.metrics.typeScore > 60) {
+    decisions.push({
+      issue: 'type-mismatch',
+      severity: 'critical',
+      action: 'sync-zod-ts-types',
+      description: `${typeCount} type mismatches detected. Sync Zod schemas with TypeScript types.`,
+      autoFixable: true,
+    });
+  }
+
+  // Decision 2: Fill gaps (medium priority)
+  if (state.metrics.gapScore > 50) {
+    const topGaps = state.findings.gaps?.gaps?.slice(0, 3) || [];
+    decisions.push({
+      issue: 'missing-roles',
+      severity: criticalGaps > 0 ? 'high' : 'medium',
+      action: 'generate-missing-files',
+      targets: topGaps.map(g => ({
+        entity: g.entity,
+        roles: g.missingRoles,
+        score: g.score,
+      })),
+      autoFixable: true,
+      description: `Generate ${topGaps.length} missing files for ${topGaps.map(g => g.entity).join(', ')}`,
+    });
+  }
+
+  // Decision 3: Refactor hotspots (low priority, requires human review)
+  if (state.metrics.hotspotScore > 70) {
+    const topRisks = state.findings.hotspots?.topRisks?.slice(0, 2) || [];
+    decisions.push({
+      issue: 'high-complexity',
+      severity: 'medium',
+      action: 'refactor-hotspots',
+      targets: topRisks,
+      autoFixable: false, // Requires human decision
+      description: `Features ${topRisks.map(r => r.feature).join(', ')} have high complexity.`,
+      recommendation: 'Add tests or refactor into smaller modules.',
+    });
+  }
+
+  // Decision 4: Fix drift (if baseline exists)
+  if (state.metrics.driftSeverity === 'major') {
+    decisions.push({
+      issue: 'major-drift',
+      severity: 'high',
+      action: 'resync-model',
+      autoFixable: true,
+      description: 'Project structure has drifted significantly from baseline.',
+      recommendation: 'Run: unrdf init --skip-snapshot to resync',
+    });
+  }
+
+  state.findings.decisions = decisions;
+
+  // ===== PHASE 4: EXECUTE =====
+  // Apply fixes autonomously (for auto-fixable issues)
+  state.phase = 'execute';
+
+  for (const decision of decisions) {
+    if (decision.autoFixable) {
+      if (decision.action === 'generate-missing-files') {
+        // Plan and queue file generation
+        const targets = decision.targets || [];
+        for (const target of targets) {
+          state.actions.push({
+            type: 'generate-files',
+            entity: target.entity,
+            roles: target.roles,
+            status: 'planned',
+            timestamp: new Date().toISOString(),
+          });
+        }
+      } else if (decision.action === 'sync-zod-ts-types') {
+        state.actions.push({
+          type: 'sync-types',
+          mismatches: state.findings.typeIssues?.mismatches?.length || 0,
+          status: 'planned',
+          timestamp: new Date().toISOString(),
+        });
+      } else if (decision.action === 'resync-model') {
+        state.actions.push({
+          type: 'reinitialize',
+          reason: 'drift-recovery',
+          status: 'planned',
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }
+  }
+
+  // ===== PHASE 5: KNOWLEDGE =====
+  // Learn from outcomes and update policies
+  state.phase = 'knowledge';
+
+  // Extract learning
+  const learnings = {
+    timestamp: new Date().toISOString(),
+    gapPatterns: (state.findings.gaps?.gaps || [])
+      .filter(g => g.score > 80)
+      .map(g => ({
+        entity: g.entity,
+        missingRoles: g.missingRoles,
+        frequency: 1,
+      })),
+    typePatterns: (state.findings.typeIssues?.mismatches || [])
+      .filter(m => m.severity === 'high')
+      .map(m => ({
+        entity: m.entity,
+        issueType: 'type-mismatch',
+        frequency: m.issues?.length || 1,
+      })),
+    hotspotThresholds: {
+      fileCountHighRisk: 40,
+      testCoverageHighRisk: 70,
+      dependenciesHighRisk: 12,
+    },
+  };
+
+  state.findings.learnings = learnings;
+
+  // Determine if another iteration is needed
+  const shouldRepeat = overallHealth < 0.7 && state.actions.length > 0;
+
+  return {
+    state,
+    overallHealth: Math.round(overallHealth * 100),
+    phase: state.phase,
+    findings: state.findings,
+    metrics: state.metrics,
+    decisions: decisions.filter(d => d.autoFixable),
+    actions: state.actions,
+    learnings,
+    shouldRepeat,
+  };
+}
+
+/**
+ * Create Knowledge Hooks for autonomous execution
+ *
+ * @param {Object} mapekFindings - From runMapekIteration
+ * @param {Store} projectStore - Project RDF store
+ * @returns {Hook[]} Array of hooks for KnowledgeHookManager
+ */
+export function createAutonomicHooks(mapekFindings, _projectStore) {
+  const hooks = [];
+
+  // Hook 1: Auto-generate missing files on gap detection
+  if (mapekFindings.findings.gaps?.gaps?.some(g => g.score > 80)) {
+    hooks.push({
+      meta: {
+        name: 'autonomic:auto-generate-missing-files',
+        description: 'Autonomously generate missing files for high-score gaps',
+        source: 'mapek:execute',
+      },
+      channel: { graphs: ['urn:graph:project'], view: 'after' },
+      when: {
+        kind: 'sparql-ask',
+        query: `
+          ASK {
+            ?entity rdf:type dom:Entity .
+            FILTER NOT EXISTS { ?file project:belongsToFeature ?entity . }
+          }
+        `,
+      },
+      run: async ({ payload, _context }) => {
+        // This hook triggers when a new entity is detected without corresponding files
+        // The actual file generation is handled by applyMapekActions in the CLI
+        const entity = payload?.subject?.value || payload?.subject || 'unknown';
+        console.log(`[Autonomic Hook] Detected missing files for entity: ${entity}`);
+        return {
+          result: {
+            action: 'generate',
+            entity,
+            triggered: true,
+            note: 'File generation will be handled by MAPEK execute phase',
+          },
+        };
+      },
+    });
+  }
+
+  // Hook 2: Auto-sync types when mismatch detected
+  if (mapekFindings.findings.typeIssues?.mismatches?.some(m => m.severity === 'high')) {
+    hooks.push({
+      meta: {
+        name: 'autonomic:auto-sync-types',
+        description: 'Autonomously sync Zod schemas with TypeScript types',
+        source: 'mapek:execute',
+      },
+      channel: { graphs: ['urn:graph:project'], view: 'after' },
+      when: {
+        kind: 'custom',
+      },
+      run: async ({ _payload, _context }) => {
+        // This hook triggers when type mismatches are detected
+        // The actual type syncing requires manual review due to complexity
+        console.log('[Autonomic Hook] Type mismatch detected - requires manual review');
+        return {
+          result: {
+            action: 'sync',
+            type: 'zod-ts',
+            triggered: true,
+            note: 'Type syncing requires manual review. Run: unrdf autonomic --full',
+          },
+        };
+      },
+    });
+  }
+
+  // Hook 3: Alert on hotspots (for human review)
+  if (mapekFindings.findings.hotspots?.hotspots?.some(h => h.risk === 'HIGH')) {
+    hooks.push({
+      meta: {
+        name: 'autonomic:hotspot-alert',
+        description: 'Alert on high-risk features that need attention',
+        source: 'mapek:execute',
+      },
+      channel: { graphs: ['urn:graph:project'], view: 'after' },
+      when: {
+        kind: 'custom',
+      },
+      run: async ({ _payload, _context }) => {
+        // This hook alerts on high-risk features that need human attention
+        const topRisk = mapekFindings.findings.hotspots?.topRisks?.[0];
+        if (topRisk) {
+          console.log(`[Autonomic Hook] High-risk feature detected: ${topRisk.feature}`);
+          console.log(`   Reason: ${topRisk.reason || 'High complexity'}`);
+          return {
+            result: {
+              action: 'alert',
+              feature: topRisk.feature,
+              reason: topRisk.reason,
+              level: 'warning',
+              triggered: true,
+            },
+          };
+        }
+        return {
+          result: {
+            action: 'alert',
+            level: 'info',
+            triggered: false,
+          },
+        };
+      },
+    });
+  }
+
+  return hooks;
+}
+
+/**
+ * Continuous autonomic loop (polling-based)
+ *
+ * @param {Object} options
+ * @param {Function} options.getState - Function to get current project state
+ * @param {Function} options.applyActions - Function to apply decisions
+ * @param {number} [options.intervalMs] - Polling interval (default 5000)
+ * @param {number} [options.maxIterations] - Stop after N iterations (default: run forever)
+ * @returns {Promise<Object>} Final state after convergence
+ */
+export async function runContinuousMapekLoop(options) {
+  const {
+    getState,
+    applyActions,
+    intervalMs = 5000,
+    maxIterations = 10,
+  } = z
+    .object({
+      getState: z.function(),
+      applyActions: z.function(),
+      intervalMs: z.number().default(5000),
+      maxIterations: z.number().default(10),
+    })
+    .parse(options);
+
+  let iteration = 0;
+  let lastState = null;
+  let converged = false;
+
+  while (iteration < maxIterations && !converged) {
+    iteration++;
+
+    // Get current state
+    const state = await getState();
+
+    // Run MAPEK iteration
+    const result = await runMapekIteration(state);
+
+    // Apply auto-fixable actions
+    if (result.actions.length > 0) {
+      await applyActions(result.actions, state);
+    }
+
+    lastState = result;
+
+    // Check convergence
+    if (result.overallHealth > 80) {
+      converged = true;
+    } else if (!result.shouldRepeat) {
+      converged = true;
+    }
+
+    // Wait before next iteration
+    if (!converged && iteration < maxIterations) {
+      await new Promise(resolve => setTimeout(resolve, intervalMs));
+    }
+  }
+
+  return {
+    converged,
+    iterations: iteration,
+    finalHealth: lastState?.overallHealth || 0,
+    finalState: lastState,
+  };
+}
+
+/**
+ * MAPEK Status reporter
+ *
+ * @param {Object} mapekState - From runMapekIteration
+ * @returns {string} Human-readable status report
+ */
+export function reportMapekStatus(mapekState) {
+  const lines = [
+    '\n╔════════════════════════════════════════╗',
+    '║         AUTONOMIC SYSTEM STATUS        ║',
+    '╚════════════════════════════════════════╝\n',
+    `🔄 Overall Health: ${mapekState.overallHealth}%`,
+    '',
+    '📊 Metrics:',
+    `   Gap Score: ${mapekState.metrics.gapScore}/100`,
+    `   Type Score: ${mapekState.metrics.typeScore}/100`,
+    `   Hotspot Score: ${mapekState.metrics.hotspotScore}/100`,
+    `   Drift: ${mapekState.metrics.driftSeverity}`,
+    '',
+    '🔍 Findings:',
+    `   Gaps: ${mapekState.findings.gaps?.gaps?.length || 0} missing roles`,
+    `   Type Issues: ${mapekState.findings.typeIssues?.mismatches?.length || 0} mismatches`,
+    `   Hotspots: ${mapekState.findings.hotspots?.hotspots?.length || 0} high-risk features`,
+  ];
+
+  if (mapekState.findings.decisions?.length > 0) {
+    lines.push('');
+    lines.push('📋 Decisions:');
+    mapekState.findings.decisions.forEach(d => {
+      const icon = d.autoFixable ? '⚙️ ' : '🤔';
+      lines.push(`   ${icon} ${d.description}`);
+    });
+  }
+
+  if (mapekState.actions?.length > 0) {
+    lines.push('');
+    lines.push('⚡ Planned Actions:');
+    mapekState.actions.forEach(a => {
+      lines.push(`   → ${a.type}: ${a.status}`);
+    });
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+export { findMissingRoles, scoreMissingRole } from './gap-finder.mjs';
+export { auditTypeConsistency, compareTypes } from './type-auditor.mjs';
+export { analyzeHotspots, scoreFeature } from './hotspot-analyzer.mjs';

package/src/capabilities-manifest.mjs

@@ -0,0 +1,125 @@
+/**
+ * @file Project Engine Capabilities Manifest
+ * @module project-engine/capabilities-manifest
+ * @description Defines all available capabilities with feature flags for the project initialization pipeline
+ */
+
+/**
+ * @typedef {Object} CapabilityFeatureFlag
+ * @property {string} name - Feature flag name (e.g., 'code_complexity_js')
+ * @property {string} status - Feature status: 'stable', 'beta', 'experimental', 'deprecated'
+ * @property {string} [description] - Human-readable description
+ * @property {string} [since] - Version when introduced
+ * @property {boolean} [enabled] - Whether feature is enabled by default
+ */
+
+/**
+ * @typedef {Object} CapabilityMetadata
+ * @property {string} id - Unique capability ID
+ * @property {string} name - Human-readable name
+ * @property {string} description - Detailed description
+ * @property {string} phase - Pipeline phase name (e.g., 'Phase 6.5')
+ * @property {string} module - Module path relative to project-engine
+ * @property {string} exportName - Function export name
+ * @property {string} version - Capability version
+ * @property {string[]} tags - Searchable tags
+ * @property {CapabilityFeatureFlag} featureFlag - Associated feature flag
+ * @property {Object} [config] - Default configuration
+ */
+
+/**
+ * JavaScript Code Complexity Analysis Capability
+ * @type {CapabilityMetadata}
+ */
+export const CODE_COMPLEXITY_JS = {
+  id: 'code_complexity_js',
+  name: 'JavaScript Code Complexity Analysis',
+  description:
+    'Analyzes JavaScript/TypeScript source code for complexity metrics including cyclomatic complexity, Halstead volume, and maintainability index',
+  phase: 'Phase 6.5',
+  module: './code-complexity-js.mjs',
+  exportName: 'analyzeJsComplexity',
+  version: '1.0.0',
+  tags: ['analysis', 'metrics', 'complexity', 'javascript', 'typescript', 'rdf'],
+  featureFlag: {
+    name: 'code_complexity_js',
+    status: 'stable',
+    description: 'Enable JavaScript/TypeScript code complexity analysis in project initialization',
+    since: '4.0.0',
+    enabled: true,
+  },
+  config: {
+    mode: 'observe', // 'off', 'observe', 'enforce'
+    excludePatterns: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/build/**',
+      '**/coverage/**',
+      '**/.next/**',
+      '**/test/**',
+      '**/__tests__/**',
+      '**/spec/**',
+      '**/*.test.mjs',
+      '**/*.test.js',
+      '**/*.spec.mjs',
+      '**/*.spec.js',
+    ],
+  },
+};
+
+/**
+ * All available capabilities in the project engine
+ * @type {CapabilityMetadata[]}
+ */
+export const CAPABILITIES = [CODE_COMPLEXITY_JS];
+
+/**
+ * Feature flag registry - controls which capabilities are enabled
+ * @type {Map<string, boolean>}
+ */
+export const FEATURE_FLAGS = new Map([
+  // Phase 6.5: Code Complexity Analysis
+  [CODE_COMPLEXITY_JS.featureFlag.name, CODE_COMPLEXITY_JS.featureFlag.enabled],
+]);
+
+/**
+ * Check if a capability is enabled via feature flag
+ *
+ * @param {string} capabilityId - Capability ID (e.g., 'code_complexity_js')
+ * @param {Object} [overrides] - Override feature flags for this check
+ * @returns {boolean} - True if capability is enabled
+ */
+export function isCapabilityEnabled(capabilityId, overrides = {}) {
+  const flags = new Map([...FEATURE_FLAGS, ...Object.entries(overrides || {})]);
+  return flags.get(capabilityId) ?? false;
+}
+
+/**
+ * Get capability metadata by ID
+ *
+ * @param {string} capabilityId - Capability ID
+ * @returns {CapabilityMetadata|null} - Capability metadata or null if not found
+ */
+export function getCapabilityMetadata(capabilityId) {
+  return CAPABILITIES.find(cap => cap.id === capabilityId) || null;
+}
+
+/**
+ * Get all enabled capabilities
+ *
+ * @param {Object} [overrides] - Override feature flags
+ * @returns {CapabilityMetadata[]} - Array of enabled capabilities
+ */
+export function getEnabledCapabilities(overrides = {}) {
+  return CAPABILITIES.filter(cap => isCapabilityEnabled(cap.id, overrides));
+}
+
+/**
+ * Enable/disable capability at runtime
+ *
+ * @param {string} capabilityId - Capability ID
+ * @param {boolean} enabled - Enable or disable
+ */
+export function setCapabilityEnabled(capabilityId, enabled) {
+  FEATURE_FLAGS.set(capabilityId, enabled);
+}