@polymorphism-tech/morph-spec 3.1.0 → 3.2.0

package/src/lib/validators/content-validator.js

@@ -0,0 +1,351 @@
+import { readFileSync, existsSync } from 'fs';
+
+/**
+ * Content Validator - Validates structure and content of output files
+ *
+ * Ensures spec.md, tasks.json, and other outputs have required sections
+ * and proper structure before allowing phase transitions.
+ */
+
+/**
+ * Validate spec.md structure
+ * @param {string} specPath - Path to spec.md file
+ * @returns {Object} Validation result
+ */
+export function validateSpecContent(specPath) {
+  if (!existsSync(specPath)) {
+    return {
+      valid: false,
+      missing: ['File does not exist'],
+      errors: ['Spec file not found at: ' + specPath]
+    };
+  }
+
+  const content = readFileSync(specPath, 'utf8');
+
+  // Required sections for a complete spec
+  const requiredSections = [
+    '## Overview',
+    '## Requirements',
+    '## Technical Design',
+    '## Data Model',
+    '## API Contracts'
+  ];
+
+  const missing = requiredSections.filter(section => !content.includes(section));
+
+  // Additional quality checks
+  const errors = [];
+  const warnings = [];
+
+  // Check minimum content length
+  if (content.length < 500) {
+    warnings.push('Spec seems very short (< 500 characters). Consider adding more detail.');
+  }
+
+  // Check for placeholder text that should be replaced
+  const placeholders = ['TODO', 'TBD', 'PLACEHOLDER', '{{'];
+  placeholders.forEach(placeholder => {
+    if (content.includes(placeholder)) {
+      warnings.push(`Spec contains "${placeholder}" - ensure all placeholders are replaced`);
+    }
+  });
+
+  // Check for anti-patterns mentioned in the plan
+  if (content.toLowerCase().includes('manual azure portal')) {
+    errors.push(
+      'Spec mentions manual Azure portal creation. ' +
+      'All infrastructure must be defined in Bicep (Infrastructure as Code).'
+    );
+  }
+
+  if (content.toLowerCase().includes('create resource manually')) {
+    errors.push(
+      'Spec mentions manual resource creation. ' +
+      'Use IaC (Bicep) for all infrastructure resources.'
+    );
+  }
+
+  return {
+    valid: missing.length === 0 && errors.length === 0,
+    missing,
+    errors,
+    warnings,
+    sections: {
+      required: requiredSections.length,
+      found: requiredSections.length - missing.length
+    }
+  };
+}
+
+/**
+ * Validate tasks.json structure
+ * @param {string} tasksPath - Path to tasks.json file
+ * @returns {Object} Validation result
+ */
+export function validateTasksContent(tasksPath) {
+  if (!existsSync(tasksPath)) {
+    return {
+      valid: false,
+      errors: ['Tasks file not found at: ' + tasksPath]
+    };
+  }
+
+  let tasks;
+  try {
+    const content = readFileSync(tasksPath, 'utf8');
+    tasks = JSON.parse(content);
+  } catch (error) {
+    return {
+      valid: false,
+      errors: ['Invalid JSON in tasks file: ' + error.message]
+    };
+  }
+
+  const errors = [];
+  const warnings = [];
+
+  // Check required top-level fields
+  if (!tasks.feature) {
+    errors.push('Missing "feature" field in tasks.json');
+  }
+
+  if (!tasks.tasks || !Array.isArray(tasks.tasks)) {
+    errors.push('Missing or invalid "tasks" array in tasks.json');
+    return { valid: false, errors, warnings };
+  }
+
+  if (tasks.tasks.length === 0) {
+    errors.push('Tasks array is empty - no tasks defined');
+    return { valid: false, errors, warnings };
+  }
+
+  // Validate individual tasks
+  tasks.tasks.forEach((task, index) => {
+    const taskId = task.id || `Task ${index}`;
+
+    // Check required fields
+    if (!task.id) {
+      errors.push(`${taskId}: Missing "id" field`);
+    } else if (!/^(T\d{3}|CHECKPOINT_\d{3})$/.test(task.id)) {
+      warnings.push(`${taskId}: ID should follow format T### or CHECKPOINT_###`);
+    }
+
+    if (!task.title) {
+      errors.push(`${taskId}: Missing "title" field`);
+    }
+
+    if (!task.description) {
+      errors.push(`${taskId}: Missing "description" field`);
+    }
+
+    if (!task.dependencies) {
+      errors.push(`${taskId}: Missing "dependencies" field (use empty array if no deps)`);
+    }
+
+    // For regular tasks (not checkpoints)
+    if (task.id && task.id.startsWith('T')) {
+      if (!task.category) {
+        warnings.push(`${taskId}: Missing "category" field`);
+      }
+
+      if (!task.estimatedMinutes) {
+        warnings.push(`${taskId}: Missing "estimatedMinutes" field`);
+      }
+
+      if (!task.files || task.files.length === 0) {
+        warnings.push(`${taskId}: No files specified - consider adding affected files`);
+      }
+    }
+
+    // For checkpoints
+    if (task.id && task.id.startsWith('CHECKPOINT')) {
+      if (!task.afterTasks || task.afterTasks.length === 0) {
+        warnings.push(`${taskId}: Checkpoint should specify "afterTasks"`);
+      }
+
+      if (!task.validations || task.validations.length === 0) {
+        warnings.push(`${taskId}: Checkpoint should specify "validations"`);
+      }
+    }
+  });
+
+  // Check for orphaned tasks (missing dependencies)
+  const taskIds = new Set(tasks.tasks.map(t => t.id));
+  tasks.tasks.forEach(task => {
+    if (task.dependencies && Array.isArray(task.dependencies)) {
+      task.dependencies.forEach(depId => {
+        if (depId && !taskIds.has(depId)) {
+          errors.push(`${task.id}: References non-existent dependency "${depId}"`);
+        }
+      });
+    }
+  });
+
+  // Check for circular dependencies (simple check)
+  const hasCycle = (taskId, visited = new Set()) => {
+    if (visited.has(taskId)) return true;
+    visited.add(taskId);
+
+    const task = tasks.tasks.find(t => t.id === taskId);
+    if (!task || !task.dependencies) return false;
+
+    return task.dependencies.some(depId => hasCycle(depId, new Set(visited)));
+  };
+
+  tasks.tasks.forEach(task => {
+    if (task.id && hasCycle(task.id)) {
+      errors.push(`Circular dependency detected involving task ${task.id}`);
+    }
+  });
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    stats: {
+      totalTasks: tasks.tasks.length,
+      regularTasks: tasks.tasks.filter(t => t.id?.startsWith('T')).length,
+      checkpoints: tasks.tasks.filter(t => t.id?.startsWith('CHECKPOINT')).length
+    }
+  };
+}
+
+/**
+ * Validate contracts file structure (C# contracts)
+ * @param {string} contractsPath - Path to contracts file
+ * @returns {Object} Validation result
+ */
+export function validateContractsContent(contractsPath) {
+  if (!existsSync(contractsPath)) {
+    return {
+      valid: false,
+      errors: ['Contracts file not found at: ' + contractsPath]
+    };
+  }
+
+  const content = readFileSync(contractsPath, 'utf8');
+  const errors = [];
+  const warnings = [];
+
+  // Check for basic C# structure
+  if (!content.includes('namespace')) {
+    errors.push('Contracts file missing namespace declaration');
+  }
+
+  // Check for at least one interface or record
+  const hasInterface = /interface\s+\w+/.test(content);
+  const hasRecord = /record\s+\w+/.test(content);
+  const hasClass = /class\s+\w+/.test(content);
+
+  if (!hasInterface && !hasRecord && !hasClass) {
+    errors.push('Contracts file should define at least one interface, record, or class');
+  }
+
+  // Check for common anti-patterns
+  if (content.includes('// TODO') || content.includes('// PLACEHOLDER')) {
+    warnings.push('Contracts contain TODO/PLACEHOLDER comments - ensure they are completed');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    found: {
+      hasNamespace: content.includes('namespace'),
+      hasInterfaces: hasInterface,
+      hasRecords: hasRecord,
+      hasClasses: hasClass
+    }
+  };
+}
+
+/**
+ * Validate proposal.md structure
+ * @param {string} proposalPath - Path to proposal.md file
+ * @returns {Object} Validation result
+ */
+export function validateProposalContent(proposalPath) {
+  if (!existsSync(proposalPath)) {
+    return {
+      valid: false,
+      errors: ['Proposal file not found at: ' + proposalPath]
+    };
+  }
+
+  const content = readFileSync(proposalPath, 'utf8');
+  const errors = [];
+  const warnings = [];
+
+  // Required sections
+  const requiredSections = [
+    '## Problem Statement',
+    '## Proposed Solution'
+  ];
+
+  const missing = requiredSections.filter(section => !content.includes(section));
+  missing.forEach(section => errors.push(`Missing required section: ${section}`));
+
+  // Check for minimum content
+  if (content.length < 300) {
+    warnings.push('Proposal seems very brief (< 300 characters)');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    sections: {
+      required: requiredSections.length,
+      found: requiredSections.length - missing.length
+    }
+  };
+}
+
+/**
+ * Validate all outputs for a feature comprehensively
+ * @param {Object} featureState - Feature state object
+ * @param {string} targetPhase - Target phase for validation
+ * @returns {Object} Comprehensive validation result
+ */
+export function validateFeatureOutputs(featureState, targetPhase) {
+  const results = {
+    valid: true,
+    validations: []
+  };
+
+  // Validate based on target phase
+  if (targetPhase === 'clarify' || targetPhase === 'tasks' || targetPhase === 'implement') {
+    // Spec is required
+    if (featureState.outputs?.spec?.created) {
+      const specResult = validateSpecContent(featureState.outputs.spec.path);
+      results.validations.push({ type: 'spec', ...specResult });
+      if (!specResult.valid) results.valid = false;
+    } else {
+      results.valid = false;
+      results.validations.push({
+        type: 'spec',
+        valid: false,
+        errors: ['Spec file not created']
+      });
+    }
+  }
+
+  if (targetPhase === 'implement') {
+    // Tasks are required
+    if (featureState.outputs?.tasks?.created) {
+      const tasksResult = validateTasksContent(featureState.outputs.tasks.path);
+      results.validations.push({ type: 'tasks', ...tasksResult });
+      if (!tasksResult.valid) results.valid = false;
+    } else {
+      results.valid = false;
+      results.validations.push({
+        type: 'tasks',
+        valid: false,
+        errors: ['Tasks file not created']
+      });
+    }
+  }
+
+  return results;
+}

package/src/llm/analyzer.js

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview LLMAnalyzer - Analyzes project context using Claude Code's LLM
+ * @module morph-spec/llm/analyzer
+ */
+
+import { spawn } from 'child_process';
+import { detectClaudeCode, isInteractive } from './environment-detector.js';
+import { buildPrompt } from './prompt-builder.js';
+import Ajv from 'ajv';
+import projectConfigSchema from './project-config-schema.json' with { type: 'json' };
+
+/**
+ * @typedef {import('../types/index.js').SanitizedContext} SanitizedContext
+ * @typedef {import('../types/index.js').ProjectConfig} ProjectConfig
+ */
+
+/**
+ * LLM Analysis Error
+ */
+export class LLMAnalysisError extends Error {
+  constructor(message, statusCode = 500, attempts = 0, originalError = null) {
+    super(message);
+    this.name = 'LLMAnalysisError';
+    this.statusCode = statusCode;
+    this.attempts = attempts;
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Validation Error
+ */
+export class ValidationError extends Error {
+  constructor(message, field, value, schema = null) {
+    super(message);
+    this.name = 'ValidationError';
+    this.field = field;
+    this.value = value;
+    this.schema = schema;
+  }
+}
+
+/**
+ * LLMAnalyzer - Analyzes project context using Claude Code's embedded LLM
+ * @class
+ */
+export class LLMAnalyzer {
+  constructor() {
+    this.ajv = new Ajv({ allErrors: true });
+    this.validateSchema = this.ajv.compile(projectConfigSchema);
+  }
+
+  /**
+   * Analyze project context using Claude Code's LLM
+   * @param {SanitizedContext} context - Sanitized project context
+   * @param {Object} [options] - Analysis options
+   * @param {number} [options.timeout] - Timeout in ms (default: 60000 for user, no timeout for LLM)
+   * @returns {Promise<ProjectConfig>}
+   * @throws {LLMAnalysisError} If analysis fails
+   */
+  async analyze(context, options = {}) {
+    // Check if Claude Code is available
+    if (!detectClaudeCode()) {
+      throw new LLMAnalysisError(
+        'Claude Code environment not detected. This feature requires Claude Code CLI.',
+        503,
+        0
+      );
+    }
+
+    // Build the prompt
+    const prompt = buildPrompt(context);
+
+    // Determine timeout: 60s for interactive (user present), no timeout for LLM-only
+    const timeout = options.timeout || (isInteractive() ? 60000 : 0);
+
+    // Invoke Claude Code LLM
+    const response = await this.invokeLLM(prompt, { timeout });
+
+    // Parse and validate JSON response
+    const projectConfig = this.parseJsonResponse(response);
+
+    return projectConfig;
+  }
+
+  /**
+   * Build structured prompt for LLM
+   * @param {SanitizedContext} context - Sanitized context
+   * @returns {string} Prompt text
+   */
+  buildPrompt(context) {
+    return buildPrompt(context);
+  }
+
+  /**
+   * Invoke Claude Code's LLM via spawning a subprocess
+   *
+   * IMPLEMENTATION NOTE: This is a placeholder implementation.
+   * The actual Claude Code invocation mechanism depends on how Claude Code exposes its LLM.
+   *
+   * Possible approaches:
+   * 1. Spawn `claude` CLI with a special flag for JSON mode
+   * 2. Use an internal API/IPC mechanism
+   * 3. Write prompt to a temp file and invoke Claude Code agent
+   *
+   * For now, we'll simulate the response for testing purposes.
+   *
+   * @param {string} prompt - Prompt text
+   * @param {Object} options - Invocation options
+   * @param {number} options.timeout - Timeout in ms (0 = no timeout)
+   * @returns {Promise<string>} JSON response from LLM
+   * @throws {LLMAnalysisError}
+   */
+  async invokeLLM(prompt, options = {}) {
+    return new Promise((resolve, reject) => {
+      // TODO: Replace with actual Claude Code invocation
+      // For now, this is a placeholder that would need to be implemented
+      // based on how Claude Code exposes its LLM for programmatic access
+
+      // Example approach (pseudo-code):
+      // const claudeProcess = spawn('claude', ['--mode=json', '--prompt', prompt]);
+
+      // Placeholder: Simulate a timeout if needed
+      const { timeout } = options;
+
+      let output = '';
+      let errorOutput = '';
+
+      // Simulated response for testing (to be replaced with actual Claude Code invocation)
+      // In real implementation, this would spawn Claude Code process:
+      /*
+      const claudeProcess = spawn('claude-code', [
+        '--json',
+        '--prompt-from-stdin'
+      ]);
+
+      claudeProcess.stdin.write(prompt);
+      claudeProcess.stdin.end();
+
+      claudeProcess.stdout.on('data', (data) => {
+        output += data.toString();
+      });
+
+      claudeProcess.stderr.on('data', (data) => {
+        errorOutput += data.toString();
+      });
+
+      claudeProcess.on('close', (code) => {
+        if (code !== 0) {
+          reject(new LLMAnalysisError(
+            `Claude Code exited with code ${code}: ${errorOutput}`,
+            500,
+            1
+          ));
+          return;
+        }
+
+        resolve(output);
+      });
+
+      if (timeout > 0) {
+        setTimeout(() => {
+          claudeProcess.kill();
+          reject(new LLMAnalysisError('LLM analysis timeout', 504, 1));
+        }, timeout);
+      }
+      */
+
+      // For now, reject with a "not implemented" error
+      // This will be replaced when we know the exact Claude Code invocation mechanism
+      reject(new LLMAnalysisError(
+        'LLM invocation not yet implemented. Awaiting Claude Code API documentation.',
+        501,
+        0
+      ));
+    });
+  }
+
+  /**
+   * Parse and validate LLM JSON response
+   * @param {string} response - Raw LLM response
+   * @returns {ProjectConfig}
+   * @throws {ValidationError} If response doesn't match schema
+   */
+  parseJsonResponse(response) {
+    // Try to parse JSON
+    let parsed;
+    try {
+      parsed = JSON.parse(response);
+    } catch (error) {
+      throw new ValidationError(
+        'LLM response is not valid JSON',
+        'response',
+        response,
+        null
+      );
+    }
+
+    // Validate against schema
+    const valid = this.validateSchema(parsed);
+    if (!valid) {
+      const errors = this.validateSchema.errors || [];
+      const errorMessages = errors.map(err => `${err.instancePath} ${err.message}`).join(', ');
+
+      throw new ValidationError(
+        `Schema validation failed: ${errorMessages}`,
+        'schema',
+        parsed,
+        projectConfigSchema
+      );
+    }
+
+    return parsed;
+  }
+}

package/src/llm/environment-detector.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Environment Detector - Detects if running in Claude Code
+ * @module morph-spec/llm/environment-detector
+ */
+
+/**
+ * Detect if running inside Claude Code environment
+ * @returns {boolean} True if Claude Code is available
+ */
+export function detectClaudeCode() {
+  // Check for environment variables that Claude Code sets
+  const claudeEnvVars = [
+    'CLAUDE_CODE_SESSION',
+    'CLAUDE_API_KEY',
+    'ANTHROPIC_API_KEY'
+  ];
+
+  // Check if any Claude-specific env var is set
+  const hasClaudeEnv = claudeEnvVars.some(varName => process.env[varName]);
+
+  // Check if we can detect Claude Code CLI
+  // (This is a heuristic - Claude Code sets these when running)
+  const hasClaudeCLI = process.env.TERM_PROGRAM === 'claude' ||
+                       process.env.CLAUDE_CODE_VERSION;
+
+  return hasClaudeEnv || hasClaudeCLI;
+}
+
+/**
+ * Get Claude Code version if available
+ * @returns {string|null} Version string or null
+ */
+export function getClaudeCodeVersion() {
+  return process.env.CLAUDE_CODE_VERSION || null;
+}
+
+/**
+ * Check if running in interactive mode (user is present)
+ * @returns {boolean} True if interactive
+ */
+export function isInteractive() {
+  return process.stdout.isTTY && process.stdin.isTTY;
+}