@polymorphism-tech/morph-spec 3.1.0 → 3.2.0

package/src/generator/config-generator.js

@@ -0,0 +1,206 @@
+/**
+ * @fileoverview ConfigGenerator - Renders templates and generates config files
+ * @module morph-spec/generator/config-generator
+ */
+
+import { readFile, access, copyFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import Handlebars from 'handlebars';
+import { fileURLToPath } from 'url';
+import Ajv from 'ajv';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * @typedef {import('../types/index.js').ProjectConfig} ProjectConfig
+ * @typedef {import('../types/index.js').GeneratedConfigs} GeneratedConfigs
+ */
+
+/**
+ * Validation Error
+ */
+export class ValidationError extends Error {
+  constructor(message, field, value) {
+    super(message);
+    this.name = 'ValidationError';
+    this.field = field;
+    this.value = value;
+  }
+}
+
+/**
+ * ConfigGenerator - Generates configuration files from ProjectConfig
+ * @class
+ */
+export class ConfigGenerator {
+  constructor() {
+    this.projectMdTemplate = null;
+    this.configJsonTemplate = null;
+    this.ajv = new Ajv({ allErrors: true });
+  }
+
+  /**
+   * Load templates from filesystem
+   * @private
+   */
+  async loadTemplates() {
+    if (this.projectMdTemplate && this.configJsonTemplate) {
+      return; // Already loaded
+    }
+
+    const templatesDir = join(__dirname, 'templates');
+
+    const [projectMdSource, configJsonSource] = await Promise.all([
+      readFile(join(templatesDir, 'project.md.template'), 'utf-8'),
+      readFile(join(templatesDir, 'config.json.template'), 'utf-8')
+    ]);
+
+    this.projectMdTemplate = Handlebars.compile(projectMdSource);
+    this.configJsonTemplate = Handlebars.compile(configJsonSource);
+  }
+
+  /**
+   * Generate configuration files from project config
+   * @param {ProjectConfig} projectConfig - Detected project config
+   * @returns {Promise<GeneratedConfigs>}
+   */
+  async generate(projectConfig) {
+    // Load templates if not already loaded
+    await this.loadTemplates();
+
+    // Add generation timestamp
+    const context = {
+      ...projectConfig,
+      generatedAt: new Date().toISOString()
+    };
+
+    // Render templates
+    const projectMd = this.renderProjectMd(context);
+    const configJson = this.renderConfigJson(context);
+
+    // Parse config.json to object
+    const configObject = JSON.parse(configJson);
+
+    // Validate config.json (optional, but good practice)
+    // Note: agent-schema.json validation would happen here if we had the schema
+    // For now, we just ensure it's valid JSON
+
+    return {
+      projectMd,
+      configJson,
+      configObject
+    };
+  }
+
+  /**
+   * Render project.md template
+   * @param {ProjectConfig} config - Project config
+   * @returns {string} Rendered markdown
+   */
+  renderProjectMd(config) {
+    if (!this.projectMdTemplate) {
+      throw new Error('Templates not loaded. Call loadTemplates() first.');
+    }
+
+    return this.projectMdTemplate(config);
+  }
+
+  /**
+   * Render config.json template
+   * @param {ProjectConfig} config - Project config
+   * @returns {string} Rendered JSON string
+   */
+  renderConfigJson(config) {
+    if (!this.configJsonTemplate) {
+      throw new Error('Templates not loaded. Call loadTemplates() first.');
+    }
+
+    const rendered = this.configJsonTemplate(config);
+
+    // Validate that rendered output is valid JSON
+    try {
+      JSON.parse(rendered);
+      return rendered;
+    } catch (error) {
+      throw new ValidationError(
+        `Rendered config.json is not valid JSON: ${error.message}`,
+        'configJson',
+        rendered
+      );
+    }
+  }
+
+  /**
+   * Validate config.json against agent schema
+   * @param {string} configJson - JSON string
+   * @returns {boolean} True if valid
+   * @throws {ValidationError} If validation fails
+   */
+  validateConfigJson(configJson) {
+    // Parse JSON
+    let parsed;
+    try {
+      parsed = JSON.parse(configJson);
+    } catch (error) {
+      throw new ValidationError(
+        `Invalid JSON: ${error.message}`,
+        'configJson',
+        configJson
+      );
+    }
+
+    // Basic validation - ensure required fields exist
+    const requiredFields = ['name', 'type', 'description', 'stack', 'architecture'];
+    for (const field of requiredFields) {
+      if (!parsed[field]) {
+        throw new ValidationError(
+          `Missing required field: ${field}`,
+          field,
+          parsed
+        );
+      }
+    }
+
+    // Validate stack.backend is required
+    if (!parsed.stack || !parsed.stack.backend) {
+      throw new ValidationError(
+        'stack.backend is required',
+        'stack.backend',
+        parsed
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Backup existing configuration files
+   * @param {string} cwd - Current working directory
+   * @returns {Promise<void>}
+   */
+  async backupExisting(cwd) {
+    const projectMdPath = join(cwd, '.morph', 'project.md');
+    const configJsonPath = join(cwd, '.morph', 'config', 'config.json');
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+
+    // Backup project.md if exists
+    try {
+      await access(projectMdPath);
+      const backupPath = join(cwd, '.morph', `project.md.${timestamp}.backup`);
+      await copyFile(projectMdPath, backupPath);
+    } catch (error) {
+      // File doesn't exist, no need to backup
+    }
+
+    // Backup config.json if exists
+    try {
+      await access(configJsonPath);
+      const backupPath = join(cwd, '.morph', 'config', `config.json.${timestamp}.backup`);
+      await copyFile(configJsonPath, backupPath);
+    } catch (error) {
+      // File doesn't exist, no need to backup
+    }
+  }
+}

package/src/generator/templates/config.json.template

@@ -0,0 +1,40 @@
+{
+  "$schema": "../schema/agent-schema.json",
+  "name": "{{name}}",
+  "type": "{{type}}",
+  "description": "{{description}}",
+  "stack": {
+    {{#if stack.frontend}}
+    "frontend": {
+      "tech": "{{stack.frontend.tech}}",
+      "version": "{{stack.frontend.version}}"{{#if stack.frontend.details}},
+      "details": "{{stack.frontend.details}}"{{/if}}
+    },
+    {{/if}}
+    "backend": {
+      "tech": "{{stack.backend.tech}}",
+      "version": "{{stack.backend.version}}"{{#if stack.backend.details}},
+      "details": "{{stack.backend.details}}"{{/if}}
+    }{{#if stack.database}},
+    "database": {
+      "tech": "{{stack.database.tech}}",
+      "version": "{{stack.database.version}}"{{#if stack.database.details}},
+      "details": "{{stack.database.details}}"{{/if}}
+    }{{/if}}{{#if stack.hosting}},
+    "hosting": "{{stack.hosting}}"{{/if}}
+  },
+  "architecture": "{{architecture}}",
+  "conventions": "{{conventions}}",
+  "infrastructure": {
+    "azure": {{hasAzure}},
+    "docker": {{hasDocker}},
+    "devops": {{hasDevOps}}
+  }{{#if repository}},
+  "repository": "{{repository}}"{{/if}},
+  "meta": {
+    "generatedBy": "morph-spec-cli",
+    "generatedAt": "{{generatedAt}}",
+    "llmConfidence": {{confidence}},
+    "autoDetected": true
+  }
+}

package/src/generator/templates/project.md.template

@@ -0,0 +1,67 @@
+# {{name}}
+
+> {{description}}
+
+## Stack
+
+| Component | Technology |
+|-----------|------------|
+{{#if stack.frontend}}
+| **Frontend** | {{stack.frontend.tech}} {{stack.frontend.version}}{{#if stack.frontend.details}} - {{stack.frontend.details}}{{/if}} |
+{{/if}}
+| **Backend** | {{stack.backend.tech}} {{stack.backend.version}}{{#if stack.backend.details}} - {{stack.backend.details}}{{/if}} |
+{{#if stack.database}}
+| **Database** | {{stack.database.tech}} {{stack.database.version}}{{#if stack.database.details}} - {{stack.database.details}}{{/if}} |
+{{/if}}
+{{#if stack.hosting}}
+| **Hosting** | {{stack.hosting}} |
+{{/if}}
+
+## Architecture
+
+**Pattern:** {{architecture}}
+
+{{projectStructure}}
+
+## Code Conventions
+
+{{conventions}}
+
+## Infrastructure
+
+{{#if hasAzure}}
+- ✅ **Azure** - Uses Azure infrastructure (Bicep files detected)
+{{else}}
+- ❌ **Azure** - No Azure resources detected
+{{/if}}
+
+{{#if hasDocker}}
+- ✅ **Docker** - Containerized (Dockerfile/docker-compose.yml detected)
+{{else}}
+- ❌ **Docker** - Not containerized
+{{/if}}
+
+{{#if hasDevOps}}
+- ✅ **CI/CD** - Pipelines detected
+{{else}}
+- ❌ **CI/CD** - No pipelines detected
+{{/if}}
+
+{{#if repository}}
+## Repository
+
+{{repository}}
+{{/if}}
+
+{{#if warnings.length}}
+## ⚠️ Warnings
+
+{{#each warnings}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+---
+
+*Auto-generated by MORPH-SPEC CLI on {{generatedAt}}*
+*LLM Confidence: {{confidence}}%*

package/src/lib/checkpoint-hooks.js

@@ -0,0 +1,258 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * Checkpoint Hooks - Automated validation orchestration
+ *
+ * Runs validators, tests, and linters at checkpoint milestones (every N tasks).
+ * Blocks progress if critical validations fail.
+ */
+
+/**
+ * Load LLM interaction configuration
+ * @returns {Object} Configuration object
+ */
+function loadLLMInteractionConfig() {
+  const configPath = join(process.cwd(), '.morph/config/llm-interaction.json');
+
+  if (!existsSync(configPath)) {
+    // Return defaults if config doesn't exist
+    return {
+      checkpoints: {
+        frequency: 3,
+        autoValidate: true,
+        validators: {
+          enabled: ['architecture', 'packages', 'design-system', 'security'],
+          optional: []
+        },
+        hooks: {
+          runTests: false,
+          runLinters: true,
+          buildCheck: false
+        },
+        onFailure: {
+          blockProgress: true,
+          maxRetries: 3,
+          escalateAfter: 3
+        }
+      }
+    };
+  }
+
+  return JSON.parse(readFileSync(configPath, 'utf8'));
+}
+
+/**
+ * Run a single validator
+ * @param {string} validatorName - Validator to run (architecture, packages, etc.)
+ * @param {string} featureName - Feature being validated
+ * @returns {Promise<Object>} Validation result
+ */
+async function runValidator(validatorName, featureName) {
+  try {
+    // Use existing validate command
+    const result = execSync(
+      `node bin/validate.js ${validatorName} --feature=${featureName} --json`,
+      { encoding: 'utf8', stdio: 'pipe' }
+    );
+
+    const parsed = JSON.parse(result);
+    return {
+      validator: validatorName,
+      passed: parsed.errors === 0,
+      errors: parsed.errors || 0,
+      warnings: parsed.warnings || 0,
+      details: parsed.issues || []
+    };
+  } catch (error) {
+    return {
+      validator: validatorName,
+      passed: false,
+      errors: 1,
+      warnings: 0,
+      details: [{ message: error.message, severity: 'error' }]
+    };
+  }
+}
+
+/**
+ * Run tests if configured
+ * @param {string} featureName - Feature being tested
+ * @returns {Promise<Object>} Test result
+ */
+async function runTests(featureName) {
+  try {
+    execSync('npm test --passWithNoTests', { encoding: 'utf8', stdio: 'pipe' });
+    return {
+      validator: 'tests',
+      passed: true,
+      errors: 0,
+      warnings: 0,
+      details: []
+    };
+  } catch (error) {
+    return {
+      validator: 'tests',
+      passed: false,
+      errors: 1,
+      warnings: 0,
+      details: [{ message: 'Test suite failed', severity: 'error' }]
+    };
+  }
+}
+
+/**
+ * Run linters if configured
+ * @param {string} featureName - Feature being linted
+ * @returns {Promise<Object>} Linter result
+ */
+async function runLinters(featureName) {
+  try {
+    // Check if eslint exists
+    if (existsSync(join(process.cwd(), 'node_modules/.bin/eslint'))) {
+      execSync('npm run lint --if-present', { encoding: 'utf8', stdio: 'pipe' });
+    }
+
+    return {
+      validator: 'linters',
+      passed: true,
+      errors: 0,
+      warnings: 0,
+      details: []
+    };
+  } catch (error) {
+    return {
+      validator: 'linters',
+      passed: false,
+      errors: 0,
+      warnings: 1,
+      details: [{ message: 'Linting warnings detected', severity: 'warning' }]
+    };
+  }
+}
+
+/**
+ * Run checkpoint hooks - orchestrates all validation
+ * @param {string} featureName - Feature name
+ * @param {number} checkpointNum - Checkpoint number (1, 2, 3, etc.)
+ * @returns {Promise<Object>} Checkpoint result
+ */
+export async function runCheckpointHooks(featureName, checkpointNum) {
+  const config = loadLLMInteractionConfig();
+  const checkpointConfig = config.checkpoints;
+
+  if (!checkpointConfig.autoValidate) {
+    return {
+      passed: true,
+      skipped: true,
+      message: 'Auto-validation disabled in config'
+    };
+  }
+
+  console.log(`\n🔍 Running CHECKPOINT ${checkpointNum} for feature: ${featureName}`);
+  console.log('━'.repeat(60));
+
+  const results = [];
+
+  // 1. Run enabled validators
+  console.log('\n📋 Running validators...');
+  for (const validatorName of checkpointConfig.validators.enabled) {
+    process.stdout.write(`  • ${validatorName}... `);
+    const result = await runValidator(validatorName, featureName);
+    results.push(result);
+
+    if (result.passed) {
+      console.log('✅ PASSED');
+    } else {
+      console.log(`❌ FAILED (${result.errors} errors, ${result.warnings} warnings)`);
+    }
+  }
+
+  // 2. Run tests (if configured)
+  if (checkpointConfig.hooks.runTests) {
+    console.log('\n🧪 Running tests...');
+    process.stdout.write('  • test suite... ');
+    const testResult = await runTests(featureName);
+    results.push(testResult);
+
+    if (testResult.passed) {
+      console.log('✅ PASSED');
+    } else {
+      console.log('❌ FAILED');
+    }
+  }
+
+  // 3. Run linters (if configured)
+  if (checkpointConfig.hooks.runLinters) {
+    console.log('\n🎨 Running linters...');
+    process.stdout.write('  • code style... ');
+    const lintResult = await runLinters(featureName);
+    results.push(lintResult);
+
+    if (lintResult.passed) {
+      console.log('✅ PASSED');
+    } else {
+      console.log('⚠️  WARNINGS');
+    }
+  }
+
+  // Calculate overall pass/fail
+  const errorCount = results.reduce((sum, r) => sum + r.errors, 0);
+  const warningCount = results.reduce((sum, r) => sum + r.warnings, 0);
+  const passed = errorCount === 0;
+
+  console.log('\n' + '━'.repeat(60));
+  console.log(`\n📊 Checkpoint ${checkpointNum} Summary:`);
+  console.log(`   Errors: ${errorCount}`);
+  console.log(`   Warnings: ${warningCount}`);
+  console.log(`   Status: ${passed ? '✅ PASSED' : '❌ FAILED'}`);
+
+  if (!passed) {
+    console.log('\n⚠️  Checkpoint failed! Fix violations before proceeding.');
+
+    // Show details of failures
+    results.filter(r => r.errors > 0).forEach(r => {
+      console.log(`\n❌ ${r.validator} errors:`);
+      r.details.forEach(d => {
+        if (d.severity === 'error') {
+          console.log(`   - ${d.message}`);
+        }
+      });
+    });
+  }
+
+  console.log('\n' + '━'.repeat(60) + '\n');
+
+  return {
+    passed,
+    checkpointNum,
+    timestamp: new Date().toISOString(),
+    results,
+    summary: {
+      errors: errorCount,
+      warnings: warningCount,
+      validatorsRun: results.length
+    }
+  };
+}
+
+/**
+ * Check if checkpoint should run based on task count
+ * @param {number} tasksCompleted - Number of tasks completed
+ * @param {number} frequency - Checkpoint frequency (default: 3)
+ * @returns {boolean} True if checkpoint should run
+ */
+export function shouldRunCheckpoint(tasksCompleted, frequency = 3) {
+  return tasksCompleted > 0 && tasksCompleted % frequency === 0;
+}
+
+/**
+ * Get checkpoint number from task count
+ * @param {number} tasksCompleted - Number of tasks completed
+ * @param {number} frequency - Checkpoint frequency (default: 3)
+ * @returns {number} Checkpoint number
+ */
+export function getCheckpointNumber(tasksCompleted, frequency = 3) {
+  return Math.floor(tasksCompleted / frequency);
+}