@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

package/src/core/templates/template-validator.js

@@ -0,0 +1,296 @@
+/**
+ * Template Validator - Validates Handlebars templates
+ * Checks for:
+ * - Required placeholders are present
+ * - No deprecated pre-computed variables ({FEATURE_NAME_PASCAL})
+ * - Valid Handlebars syntax
+ * - Proper helper usage
+ */
+
+import { readFileSync } from 'fs';
+import { getTemplateById, getAllTemplates } from './template-registry.js';
+
+/**
+ * Deprecated placeholder patterns (v1.0 pre-computed variables)
+ */
+const DEPRECATED_PATTERNS = [
+  { pattern: /\{\{FEATURE_NAME_PASCAL\}\}/g, replacement: '{{pascalCase FEATURE_NAME}}' },
+  { pattern: /\{\{FEATURE_NAME_CAMEL\}\}/g, replacement: '{{camelCase FEATURE_NAME}}' },
+  { pattern: /\{\{FEATURE_NAME_SNAKE\}\}/g, replacement: '{{snakeCase FEATURE_NAME}}' },
+  { pattern: /\{\{FEATURE_NAME_UPPER_SNAKE\}\}/g, replacement: '{{upperSnakeCase FEATURE_NAME}}' },
+  { pattern: /\{\{FEATURE_NAME_TITLE\}\}/g, replacement: '{{titleCase FEATURE_NAME}}' },
+  { pattern: /\{\{FEATURE_NAME_KEBAB\}\}/g, replacement: '{{kebabCase FEATURE_NAME}}' },
+];
+
+/**
+ * Old template syntax (non-Handlebars)
+ */
+const OLD_SYNTAX_PATTERNS = [
+  { pattern: /\{Feature\}/g, description: 'Old {Feature} syntax (use {{pascalCase FEATURE_NAME}})' },
+  { pattern: /\{feature\}/g, description: 'Old {feature} syntax (use {{kebabCase FEATURE_NAME}})' },
+];
+
+/**
+ * Validation result
+ */
+class ValidationResult {
+  constructor(templateId, templatePath) {
+    this.templateId = templateId;
+    this.templatePath = templatePath;
+    this.valid = true;
+    this.errors = [];
+    this.warnings = [];
+    this.info = [];
+  }
+
+  addError(message) {
+    this.errors.push(message);
+    this.valid = false;
+  }
+
+  addWarning(message) {
+    this.warnings.push(message);
+  }
+
+  addInfo(message) {
+    this.info.push(message);
+  }
+
+  get hasIssues() {
+    return this.errors.length > 0 || this.warnings.length > 0;
+  }
+}
+
+/**
+ * Validates a single template
+ * @param {string} templateId - Template ID
+ * @param {string} projectPath - Project root path
+ * @returns {ValidationResult}
+ */
+export function validateTemplate(templateId, projectPath = process.cwd()) {
+  const template = getTemplateById(templateId, projectPath);
+
+  if (!template) {
+    const result = new ValidationResult(templateId, null);
+    result.addError(`Template not found: ${templateId}`);
+    return result;
+  }
+
+  const result = new ValidationResult(templateId, template.path);
+
+  // Read template content
+  let content;
+  try {
+    const fullPath = `${projectPath}/framework/templates/${template.path}`;
+    content = readFileSync(fullPath, 'utf-8');
+  } catch (error) {
+    result.addError(`Failed to read template: ${error.message}`);
+    return result;
+  }
+
+  // Check for deprecated pre-computed variables
+  for (const { pattern, replacement } of DEPRECATED_PATTERNS) {
+    const matches = content.match(pattern);
+    if (matches) {
+      result.addError(
+        `Deprecated placeholder found: ${matches[0]} (use ${replacement} instead)`
+      );
+    }
+  }
+
+  // Check for old non-Handlebars syntax
+  for (const { pattern, description } of OLD_SYNTAX_PATTERNS) {
+    const matches = content.match(pattern);
+    if (matches) {
+      const count = matches.length;
+      result.addWarning(
+        `${count} occurrence(s) of old syntax: ${description}`
+      );
+    }
+  }
+
+  // Check for required placeholders if specified
+  if (template.placeholders && template.placeholders.length > 0) {
+    const missingPlaceholders = [];
+
+    for (const placeholder of template.placeholders) {
+      // Check for exact placeholder or helper usage
+      const exactMatch = new RegExp(`\\{\\{${placeholder}\\}\\}`, 'g');
+      const helperMatch = new RegExp(`\\{\\{\\w+\\s+${placeholder}\\}\\}`, 'g');
+
+      if (!exactMatch.test(content) && !helperMatch.test(content)) {
+        missingPlaceholders.push(placeholder);
+      }
+    }
+
+    if (missingPlaceholders.length > 0) {
+      result.addWarning(
+        `Template declares placeholders but they're not used: ${missingPlaceholders.join(', ')}`
+      );
+    }
+  }
+
+  // Check for balanced Handlebars blocks
+  const openBlocks = (content.match(/\{\{#\w+/g) || []).length;
+  const closeBlocks = (content.match(/\{\{\/\w+/g) || []).length;
+
+  if (openBlocks !== closeBlocks) {
+    result.addError(
+      `Unbalanced Handlebars blocks: ${openBlocks} opening, ${closeBlocks} closing`
+    );
+  }
+
+  // Info: Count Handlebars placeholders
+  const placeholderMatches = content.match(/\{\{[^}]+\}\}/g) || [];
+  const uniquePlaceholders = [...new Set(placeholderMatches)];
+  result.addInfo(`Found ${uniquePlaceholders.length} unique Handlebars expressions`);
+
+  // Info: Check if template uses helpers
+  const helperMatches = content.match(/\{\{(pascalCase|camelCase|snakeCase|titleCase|kebabCase|upperSnakeCase|pluralize|singularize|formatDate|uppercase|lowercase|capitalize|trim|replace|concat|substr|startsWith|endsWith|contains|length|add|subtract|multiply|divide|mod|round|join|first|last|slice|now|year|default|json)/g) || [];
+  if (helperMatches.length > 0) {
+    const uniqueHelpers = [...new Set(helperMatches.map(m => m.replace('{{', '')))];
+    result.addInfo(`Uses helpers: ${uniqueHelpers.join(', ')}`);
+  }
+
+  return result;
+}
+
+/**
+ * Validates all templates
+ * @param {string} projectPath - Project root path
+ * @param {Object} options - Validation options
+ * @returns {Array<ValidationResult>}
+ */
+export function validateAllTemplates(projectPath = process.cwd(), options = {}) {
+  const {
+    skipDeprecated = true,
+    category = null,
+    technology = null,
+  } = options;
+
+  const templates = getAllTemplates(projectPath);
+  const results = [];
+
+  for (const template of templates) {
+    // Skip deprecated if requested
+    if (skipDeprecated && template.deprecated) {
+      continue;
+    }
+
+    // Filter by category if specified
+    if (category && template.category !== category) {
+      continue;
+    }
+
+    // Filter by technology if specified
+    if (technology && template.technology !== technology) {
+      continue;
+    }
+
+    const result = validateTemplate(template.id, projectPath);
+    results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * Generates a validation summary
+ * @param {Array<ValidationResult>} results - Validation results
+ * @returns {Object}
+ */
+export function summarizeValidation(results) {
+  const summary = {
+    total: results.length,
+    valid: 0,
+    hasErrors: 0,
+    hasWarnings: 0,
+    errors: [],
+    warnings: [],
+  };
+
+  for (const result of results) {
+    if (result.valid && result.warnings.length === 0) {
+      summary.valid++;
+    }
+
+    if (result.errors.length > 0) {
+      summary.hasErrors++;
+      summary.errors.push({
+        templateId: result.templateId,
+        errors: result.errors,
+      });
+    }
+
+    if (result.warnings.length > 0) {
+      summary.hasWarnings++;
+      summary.warnings.push({
+        templateId: result.templateId,
+        warnings: result.warnings,
+      });
+    }
+  }
+
+  return summary;
+}
+
+/**
+ * Formats validation results for display
+ * @param {Array<ValidationResult>} results - Validation results
+ * @param {Object} options - Display options
+ * @returns {string}
+ */
+export function formatValidationResults(results, options = {}) {
+  const { showInfo = false, showValid = false } = options;
+
+  let output = '';
+  let validCount = 0;
+  let errorCount = 0;
+  let warningCount = 0;
+
+  for (const result of results) {
+    if (result.valid && result.warnings.length === 0) {
+      validCount++;
+      if (showValid) {
+        output += `✅ ${result.templateId}\n`;
+      }
+      continue;
+    }
+
+    if (result.errors.length > 0) {
+      errorCount++;
+      output += `\n❌ ${result.templateId}\n`;
+      output += `   Path: ${result.templatePath}\n`;
+      for (const error of result.errors) {
+        output += `   ERROR: ${error}\n`;
+      }
+    }
+
+    if (result.warnings.length > 0) {
+      warningCount++;
+      if (result.errors.length === 0) {
+        output += `\n⚠️  ${result.templateId}\n`;
+        output += `   Path: ${result.templatePath}\n`;
+      }
+      for (const warning of result.warnings) {
+        output += `   WARNING: ${warning}\n`;
+      }
+    }
+
+    if (showInfo && result.info.length > 0) {
+      for (const info of result.info) {
+        output += `   INFO: ${info}\n`;
+      }
+    }
+  }
+
+  // Summary
+  output += `\n${'='.repeat(60)}\n`;
+  output += `SUMMARY:\n`;
+  output += `  Total templates: ${results.length}\n`;
+  output += `  ✅ Valid: ${validCount}\n`;
+  output += `  ❌ Errors: ${errorCount}\n`;
+  output += `  ⚠️  Warnings: ${warningCount}\n`;
+
+  return output;
+}

package/src/core/workflows/index.js

@@ -0,0 +1,7 @@
+/**
+ * Core Workflow System
+ *
+ * Workflow detection and classification (fast-track, standard, full-morph, etc.)
+ */
+
+export { WorkflowDetector, detectWorkflow } from './workflow-detector.js';

package/src/core/workflows/workflow-detector.js

@@ -0,0 +1,354 @@
+/**
+ * @fileoverview Workflow Detection Engine
+ *
+ * Analyzes user requests to automatically select the appropriate workflow based on:
+ * - Keyword matching
+ * - Complexity estimation
+ * - Workflow criteria
+ *
+ * @module workflow-detector
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Get framework root directory
+ * @param {string} projectPath - Project path
+ * @returns {string} Framework root path
+ */
+function getFrameworkRoot(projectPath) {
+  // Try npm-installed package first
+  const npmPath = join(projectPath, 'node_modules/@polymorphism-tech/morph-spec');
+  if (existsSync(npmPath)) {
+    return npmPath;
+  }
+
+  // Fallback to local development path (from src/lib/ → root)
+  return join(__dirname, '..', '..');
+}
+
+/**
+ * Load all workflow configurations
+ * @param {string} projectPath - Project path
+ * @returns {Array<Object>} Array of workflow configs
+ */
+function loadWorkflowConfigs(projectPath) {
+  const frameworkRoot = getFrameworkRoot(projectPath);
+  const configsDir = join(frameworkRoot, 'framework/workflows/configs');
+
+  if (!existsSync(configsDir)) {
+    return [];
+  }
+
+  const configFiles = readdirSync(configsDir).filter(f => f.endsWith('.json'));
+  const configs = [];
+
+  for (const file of configFiles) {
+    try {
+      const configPath = join(configsDir, file);
+      const content = readFileSync(configPath, 'utf8');
+      configs.push(JSON.parse(content));
+    } catch (err) {
+      // Skip invalid configs
+      continue;
+    }
+  }
+
+  return configs;
+}
+
+/**
+ * Match keywords in user request
+ * @param {string} userRequest - User request text
+ * @param {Array<string>} keywords - Workflow keywords
+ * @returns {{matched: Array<string>, score: number}}
+ */
+function matchKeywords(userRequest, keywords) {
+  const requestLower = userRequest.toLowerCase();
+  const matched = [];
+
+  for (const keyword of keywords) {
+    const keywordLower = keyword.toLowerCase();
+
+    // Check for partial matches (e.g., "paginação" matches "pagination")
+    if (requestLower.includes(keywordLower)) {
+      matched.push(keyword);
+    }
+  }
+
+  // Score: percentage of keywords matched
+  const score = matched.length > 0 ? matched.length / keywords.length : 0;
+
+  return { matched, score };
+}
+
+/**
+ * Estimate complexity from user request
+ * @param {string} userRequest - User request text
+ * @returns {{files: number, lines: number, components: number, hasInfra: boolean}}
+ */
+function estimateComplexity(userRequest) {
+  const requestLower = userRequest.toLowerCase();
+
+  // Scope indicators
+  const scopeIndicators = {
+    trivial: ['button', 'cor', 'color', 'css', 'fix', 'typo', 'edge case', 'one'],
+    small: ['add', 'create', 'single', 'simple', 'quick'],
+    medium: ['feature', 'pagination', 'filter', 'export', 'refactor', 'optimize'],
+    large: ['system', 'complete', 'all', 'multiple', 'integration', 'architecture'],
+    huge: ['platform', 'infrastructure', 'subsystem', 'migrate', 'rebuild']
+  };
+
+  // Infrastructure indicators
+  const infraKeywords = ['bicep', 'azure', 'deploy', 'docker', 'kubernetes', 'infrastructure', 'terraform'];
+  const hasInfra = infraKeywords.some(kw => requestLower.includes(kw));
+
+  // Component indicators
+  const componentKeywords = ['component', 'page', 'screen', 'form', 'table', 'chart', 'modal'];
+  const componentMatches = componentKeywords.filter(kw => requestLower.includes(kw)).length;
+
+  // Entity indicators
+  const entityKeywords = ['user', 'order', 'product', 'customer', 'invoice', 'report'];
+  const entityMatches = entityKeywords.filter(kw => requestLower.includes(kw)).length;
+
+  // Determine scope
+  let scope = 'medium';
+  for (const [level, indicators] of Object.entries(scopeIndicators)) {
+    if (indicators.some(indicator => requestLower.includes(indicator))) {
+      scope = level;
+      break;
+    }
+  }
+
+  // Estimate based on scope
+  const estimates = {
+    trivial: { files: 1, lines: 30, components: 0 },
+    small: { files: 2, lines: 100, components: 1 },
+    medium: { files: 5, lines: 200, components: 1 },
+    large: { files: 12, lines: 800, components: 3 },
+    huge: { files: 25, lines: 2000, components: 5 }
+  };
+
+  const base = estimates[scope] || estimates.medium;
+
+  // Adjust based on entities and components mentioned
+  const files = base.files + entityMatches + componentMatches;
+  const lines = base.lines + (entityMatches * 50) + (componentMatches * 100);
+  const components = base.components + componentMatches;
+
+  return {
+    files,
+    lines,
+    components,
+    hasInfra
+  };
+}
+
+/**
+ * Check if complexity matches workflow criteria
+ * @param {Object} complexity - Estimated complexity
+ * @param {Object} criteria - Workflow criteria
+ * @returns {{matches: boolean, score: number}}
+ */
+function matchComplexity(complexity, criteria) {
+  let matches = 0;
+  let total = 0;
+
+  // File count
+  if (criteria.maxFiles !== undefined) {
+    total++;
+    if (complexity.files <= criteria.maxFiles) matches++;
+  }
+  if (criteria.minFiles !== undefined) {
+    total++;
+    if (complexity.files >= criteria.minFiles) matches++;
+  }
+
+  // Line count
+  if (criteria.maxLines !== undefined) {
+    total++;
+    if (complexity.lines <= criteria.maxLines) matches++;
+  }
+  if (criteria.minLines !== undefined) {
+    total++;
+    if (complexity.lines >= criteria.minLines) matches++;
+  }
+
+  // Component count
+  if (criteria.maxComponents !== undefined) {
+    total++;
+    if (complexity.components <= criteria.maxComponents) matches++;
+  }
+  if (criteria.minComponents !== undefined) {
+    total++;
+    if (complexity.components >= criteria.minComponents) matches++;
+  }
+
+  // Infrastructure
+  if (criteria.noInfrastructure !== undefined) {
+    total++;
+    if (criteria.noInfrastructure === !complexity.hasInfra) matches++;
+  }
+  if (criteria.infrastructure !== undefined) {
+    total++;
+    if (criteria.infrastructure === complexity.hasInfra) matches++;
+  }
+
+  const score = total > 0 ? matches / total : 0.5;
+  const meetsAll = total > 0 && matches === total;
+
+  return { matches: meetsAll, score };
+}
+
+/**
+ * Detect workflow for a feature request
+ * @param {Object} options - Detection options
+ * @param {string} options.userRequest - User's feature request
+ * @param {string} [options.projectPath='.'] - Project path
+ * @param {string} [options.featureName] - Feature name (optional)
+ * @returns {Object} Detection result
+ */
+export async function detectWorkflow(options) {
+  const { userRequest, projectPath = '.', featureName } = options;
+
+  if (!userRequest || userRequest.trim().length === 0) {
+    throw new Error('userRequest is required');
+  }
+
+  // Load all workflow configs
+  const workflows = loadWorkflowConfigs(projectPath);
+
+  if (workflows.length === 0) {
+    // Fallback if no configs found
+    return {
+      workflowId: 'full-morph',
+      confidence: 0.5,
+      matchedKeywords: [],
+      estimatedComplexity: { files: 0, lines: 0, components: 0, hasInfra: false },
+      reasoning: 'No workflow configs found - using full-morph as fallback',
+      alternativeWorkflows: []
+    };
+  }
+
+  // Estimate complexity
+  const complexity = estimateComplexity(userRequest);
+
+  // Score each workflow
+  const scores = [];
+
+  for (const workflow of workflows) {
+    const keywordMatch = matchKeywords(userRequest, workflow.keywords || []);
+    const complexityMatch = matchComplexity(complexity, workflow.criteria || {});
+
+    // Weighted scoring
+    const keywordWeight = 0.4;
+    const complexityWeight = 0.3;
+    const priorityWeight = 0.2;
+    const contextWeight = 0.1;
+
+    // Priority score (lower number = higher priority = higher score)
+    const priorityScore = workflow.priority ? (4 - workflow.priority) / 3 : 0.5;
+
+    // Context score (checks for special conditions)
+    let contextScore = 0.5;
+    if (workflow.criteria?.hasPrototype && (userRequest.toLowerCase().includes('prototype') || userRequest.toLowerCase().includes('mockup'))) {
+      contextScore = 1.0;
+    }
+    if (workflow.criteria?.hasExistingPages && userRequest.toLowerCase().includes('existing')) {
+      contextScore = 1.0;
+    }
+
+    // Calculate total score
+    let totalScore =
+      (keywordMatch.score * keywordWeight) +
+      (complexityMatch.score * complexityWeight) +
+      (priorityScore * priorityWeight) +
+      (contextScore * contextWeight);
+
+    // Penalty for workflows with no keyword matches (unless it's full-morph fallback)
+    if (keywordMatch.matched.length === 0 && workflow.id !== 'full-morph') {
+      totalScore *= 0.5; // 50% penalty for no keyword match
+    }
+
+    // Boost for strong keyword matches (3+ keywords matched)
+    if (keywordMatch.matched.length >= 3) {
+      totalScore *= 1.2; // 20% boost
+    }
+
+    scores.push({
+      workflowId: workflow.id,
+      workflowName: workflow.name,
+      score: totalScore,
+      keywordMatch: keywordMatch.matched,
+      complexityMatch: complexityMatch.matches,
+      reasoning: []
+    });
+  }
+
+  // Sort by score (highest first)
+  scores.sort((a, b) => b.score - a.score);
+
+  // Get top result
+  const topResult = scores[0];
+  const confidence = topResult.score;
+
+  // Build reasoning
+  const reasoning = [];
+  if (topResult.keywordMatch.length > 0) {
+    reasoning.push(`Matched keyword${topResult.keywordMatch.length > 1 ? 's' : ''}: ${topResult.keywordMatch.join(', ')}`);
+  }
+  reasoning.push(`Estimated ${complexity.files} files, ~${complexity.lines} lines`);
+  if (complexity.hasInfra) {
+    reasoning.push('Infrastructure keywords detected');
+  }
+  if (topResult.complexityMatch) {
+    reasoning.push('Meets all complexity criteria');
+  }
+
+  // Get alternatives (next 2 workflows with score > 0.2)
+  const alternatives = scores.slice(1, 3)
+    .filter(w => w.score > 0.2)
+    .map(w => ({
+      workflowId: w.workflowId,
+      confidence: w.score,
+      reason: `${w.workflowName} (${Math.round(w.score * 100)}% match)`
+    }));
+
+  return {
+    workflowId: topResult.workflowId,
+    confidence,
+    matchedKeywords: topResult.keywordMatch,
+    estimatedComplexity: complexity,
+    reasoning: reasoning.join(' + '),
+    alternativeWorkflows: alternatives
+  };
+}
+
+/**
+ * Get workflow configuration by ID
+ * @param {string} workflowId - Workflow ID
+ * @param {string} [projectPath='.'] - Project path
+ * @returns {Object|null} Workflow config or null
+ */
+export function getWorkflowConfig(workflowId, projectPath = '.') {
+  const workflows = loadWorkflowConfigs(projectPath);
+  return workflows.find(w => w.id === workflowId) || null;
+}
+
+/**
+ * List all available workflows
+ * @param {string} [projectPath='.'] - Project path
+ * @returns {Array<{id: string, name: string, description: string}>}
+ */
+export function listWorkflows(projectPath = '.') {
+  const workflows = loadWorkflowConfigs(projectPath);
+  return workflows.map(w => ({
+    id: w.id,
+    name: w.name,
+    description: w.description
+  }));
+}