@specverse/engines 4.1.0

package/libs/instance-factories/views/templates/shared/pattern-validator.ts

@@ -0,0 +1,279 @@
+/**
+ * Composite View Pattern Validator
+ *
+ * Validates composite view patterns for correctness and completeness.
+ * Ensures patterns are well-formed and can be used by framework adapters.
+ *
+ * NO FRAMEWORK DEPENDENCIES - Pure TypeScript validation logic.
+ */
+
+import type {
+  CompositeViewPattern,
+  PatternValidationResult
+} from './composite-pattern-types.js';
+import { ATOMIC_COMPONENTS_REGISTRY } from './atomic-components-registry.js';
+
+/**
+ * Validate a composite view pattern
+ */
+export function validatePattern(pattern: CompositeViewPattern): PatternValidationResult {
+  const errors: Array<{ field: string; message: string; severity: 'error' | 'warning' }> = [];
+  const warnings: Array<{ field: string; message: string }> = [];
+
+  // Validate identity fields
+  if (!pattern.id || pattern.id.trim() === '') {
+    errors.push({
+      field: 'id',
+      message: 'Pattern ID is required',
+      severity: 'error'
+    });
+  }
+
+  if (!pattern.name || pattern.name.trim() === '') {
+    errors.push({
+      field: 'name',
+      message: 'Pattern name is required',
+      severity: 'error'
+    });
+  }
+
+  if (!pattern.version || !isValidVersion(pattern.version)) {
+    errors.push({
+      field: 'version',
+      message: 'Pattern version must be in semver format (e.g., 1.0.0)',
+      severity: 'error'
+    });
+  }
+
+  if (!pattern.description || pattern.description.trim() === '') {
+    warnings.push({
+      field: 'description',
+      message: 'Pattern description is recommended for clarity'
+    });
+  }
+
+  // Validate category
+  const validCategories = ['data-entry', 'data-display', 'dashboard', 'navigation', 'workflow'];
+  if (!validCategories.includes(pattern.category)) {
+    errors.push({
+      field: 'category',
+      message: `Category must be one of: ${validCategories.join(', ')}`,
+      severity: 'error'
+    });
+  }
+
+  // Validate required atomic components
+  if (!pattern.requiredAtomicComponents || pattern.requiredAtomicComponents.length === 0) {
+    errors.push({
+      field: 'requiredAtomicComponents',
+      message: 'At least one required atomic component must be specified',
+      severity: 'error'
+    });
+  } else {
+    // Check if required components exist in atomic registry
+    for (const component of pattern.requiredAtomicComponents) {
+      if (!ATOMIC_COMPONENTS_REGISTRY[component]) {
+        errors.push({
+          field: 'requiredAtomicComponents',
+          message: `Required component '${component}' not found in ATOMIC_COMPONENTS_REGISTRY`,
+          severity: 'error'
+        });
+      }
+    }
+  }
+
+  // Validate optional atomic components
+  if (pattern.optionalAtomicComponents) {
+    for (const component of pattern.optionalAtomicComponents) {
+      if (!ATOMIC_COMPONENTS_REGISTRY[component]) {
+        warnings.push({
+          field: 'optionalAtomicComponents',
+          message: `Optional component '${component}' not found in ATOMIC_COMPONENTS_REGISTRY`
+        });
+      }
+    }
+  }
+
+  // Validate layout strategy
+  if (!pattern.layoutStrategy) {
+    errors.push({
+      field: 'layoutStrategy',
+      message: 'Layout strategy is required',
+      severity: 'error'
+    });
+  } else {
+    const validLayoutTypes = ['single-column', 'two-column', 'grid', 'flex', 'masonry', 'custom'];
+    if (!validLayoutTypes.includes(pattern.layoutStrategy.type)) {
+      errors.push({
+        field: 'layoutStrategy.type',
+        message: `Layout type must be one of: ${validLayoutTypes.join(', ')}`,
+        severity: 'error'
+      });
+    }
+  }
+
+  // Validate data bindings
+  if (!pattern.dataBindings) {
+    errors.push({
+      field: 'dataBindings',
+      message: 'Data bindings are required',
+      severity: 'error'
+    });
+  } else {
+    const validSources = ['model', 'controller', 'service', 'store', 'computed'];
+    if (!validSources.includes(pattern.dataBindings.source)) {
+      errors.push({
+        field: 'dataBindings.source',
+        message: `Data source must be one of: ${validSources.join(', ')}`,
+        severity: 'error'
+      });
+    }
+
+    if (!pattern.dataBindings.operations || pattern.dataBindings.operations.length === 0) {
+      errors.push({
+        field: 'dataBindings.operations',
+        message: 'At least one data operation must be specified',
+        severity: 'error'
+      });
+    } else {
+      // Validate each operation
+      for (const op of pattern.dataBindings.operations) {
+        const validOps = ['create', 'update', 'retrieve', 'retrieve_many', 'validate', 'evolve', 'delete'];
+        if (!validOps.includes(op.operation)) {
+          errors.push({
+            field: 'dataBindings.operations',
+            message: `Operation '${op.operation}' must be one of: ${validOps.join(', ')}`,
+            severity: 'error'
+          });
+        }
+      }
+    }
+  }
+
+  // Validate supported operations
+  if (!pattern.supportedOperations || pattern.supportedOperations.length === 0) {
+    errors.push({
+      field: 'supportedOperations',
+      message: 'At least one supported operation must be specified',
+      severity: 'error'
+    });
+  }
+
+  // Validate event handlers (if present)
+  if (pattern.eventHandlers) {
+    for (const handler of pattern.eventHandlers) {
+      if (!handler.event) {
+        errors.push({
+          field: 'eventHandlers',
+          message: 'Event handler must specify an event name',
+          severity: 'error'
+        });
+      }
+
+      // Must have either operation or handler
+      if (!handler.operation && !handler.handler) {
+        errors.push({
+          field: 'eventHandlers',
+          message: `Event handler for '${handler.event}' must specify either operation or handler`,
+          severity: 'error'
+        });
+      }
+    }
+  }
+
+  // Validate relationships (if present)
+  if (pattern.dataBindings?.relationships) {
+    for (const rel of pattern.dataBindings.relationships) {
+      const validRelTypes = ['belongsTo', 'hasMany', 'hasOne', 'manyToMany'];
+      if (!validRelTypes.includes(rel.type)) {
+        errors.push({
+          field: 'dataBindings.relationships',
+          message: `Relationship type '${rel.type}' must be one of: ${validRelTypes.join(', ')}`,
+          severity: 'error'
+        });
+      }
+
+      if (!rel.display?.labelField) {
+        warnings.push({
+          field: 'dataBindings.relationships',
+          message: `Relationship '${rel.name}' should specify a labelField for display`
+        });
+      }
+    }
+  }
+
+  // Validate extends (if present)
+  if (pattern.extends) {
+    // Check if parent pattern exists would require access to full registry
+    // This is a soft warning
+    warnings.push({
+      field: 'extends',
+      message: `Pattern extends '${pattern.extends}' - ensure parent pattern exists`
+    });
+  }
+
+  // Validate customization (if present)
+  if (pattern.customization) {
+    if (pattern.customization.requiredOverrides && pattern.customization.requiredOverrides.length > 0) {
+      // Check that required overrides reference valid fields
+      const validFields = ['layoutStrategy', 'sections', 'operations', 'relationships'];
+      for (const override of pattern.customization.requiredOverrides) {
+        if (!validFields.includes(override)) {
+          warnings.push({
+            field: 'customization.requiredOverrides',
+            message: `Override field '${override}' may not be a valid customization point`
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+
+/**
+ * Validate version string (basic semver check)
+ */
+function isValidVersion(version: string): boolean {
+  const semverRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$/;
+  return semverRegex.test(version);
+}
+
+/**
+ * Validate all patterns in a registry
+ */
+export function validatePatternRegistry(
+  registry: Record<string, CompositeViewPattern>
+): Record<string, PatternValidationResult> {
+  const results: Record<string, PatternValidationResult> = {};
+
+  for (const [id, pattern] of Object.entries(registry)) {
+    results[id] = validatePattern(pattern);
+  }
+
+  return results;
+}
+
+/**
+ * Get summary of validation results
+ */
+export function getValidationSummary(results: Record<string, PatternValidationResult>): {
+  total: number;
+  valid: number;
+  invalid: number;
+  warnings: number;
+} {
+  const total = Object.keys(results).length;
+  const valid = Object.values(results).filter(r => r.valid).length;
+  const invalid = total - valid;
+  const warnings = Object.values(results).reduce(
+    (sum, r) => sum + r.warnings.length,
+    0
+  );
+
+  return { total, valid, invalid, warnings };
+}

package/libs/instance-factories/views/templates/shared/property-mapper.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Property Mapper - Multi-Framework Support
+ *
+ * Maps SpecVerse component properties to framework-specific property values.
+ * Supports React (shadcn, MUI, antd), Vue (Vuetify, Element Plus), Svelte (Carbon),
+ * Angular (Material), and runtime interpretation.
+ *
+ * Architecture:
+ * - PropertyTarget: All supported frameworks/libraries + semantic layer
+ * - COMMON_PROPERTY_MAPPINGS: Universal properties (variant, size, color, position, orientation)
+ * - COMPONENT_SPECIFIC_MAPPINGS: Per-component overrides
+ * - mapProperty(): Main mapping function with fallback chain
+ */
+/**
+ * All supported property mapping targets
+ */
+export type PropertyTarget = 'shadcn' | 'mui' | 'antd' | 'vuetify' | 'elementPlus' | 'primeVue' | 'carbon' | 'svelteui' | 'angularMaterial' | 'primeNg' | 'runtime' | 'semantic';
+/**
+ * Framework categories for quick target identification
+ */
+export type FrameworkCategory = 'react' | 'vue' | 'svelte' | 'angular' | 'runtime';
+export declare const FRAMEWORK_TARGETS: Record<FrameworkCategory, PropertyTarget[]>;
+/**
+ * Property value mapping for a specific SpecVerse value
+ */
+export interface PropertyValueMapping {
+    shadcn?: string | boolean | number;
+    mui?: string | boolean | number;
+    antd?: string | boolean | number;
+    vuetify?: string | boolean | number;
+    elementPlus?: string | boolean | number;
+    primeVue?: string | boolean | number;
+    carbon?: string | boolean | number;
+    svelteui?: string | boolean | number;
+    angularMaterial?: string | boolean | number;
+    primeNg?: string | boolean | number;
+    runtime?: string | boolean | number;
+    semantic: string;
+}
+/**
+ * Complete mapping for a property
+ */
+export interface PropertyMapping {
+    [specverseValue: string]: PropertyValueMapping;
+}
+/**
+ * Component-specific property overrides
+ */
+export interface ComponentPropertyMapping {
+    [componentType: string]: {
+        [propertyName: string]: PropertyMapping;
+    };
+}
+/**
+ * Variant mappings - Primary, secondary, destructive actions
+ * Consistency: 60-85% across frameworks (HIGH)
+ */
+export declare const VARIANT_MAPPING: PropertyMapping;
+/**
+ * Size mappings - Component dimensions
+ * Consistency: 85-90% across frameworks (VERY HIGH)
+ */
+export declare const SIZE_MAPPING: PropertyMapping;
+/**
+ * Color mappings - Semantic color values
+ * Consistency: 70-80% across frameworks (HIGH)
+ */
+export declare const COLOR_MAPPING: PropertyMapping;
+/**
+ * Position mappings - Spatial positioning
+ * Consistency: 95-100% across frameworks (UNIVERSAL)
+ */
+export declare const POSITION_MAPPING: PropertyMapping;
+/**
+ * Orientation mappings - Layout direction
+ * Consistency: 90-95% across frameworks (VERY HIGH)
+ */
+export declare const ORIENTATION_MAPPING: PropertyMapping;
+/**
+ * All common property mappings
+ */
+export declare const COMMON_PROPERTY_MAPPINGS: Record<string, PropertyMapping>;
+/**
+ * Component-specific overrides for properties that differ from common mappings
+ *
+ * Example: Table pagination size works differently than button size
+ */
+export declare const COMPONENT_SPECIFIC_MAPPINGS: ComponentPropertyMapping;
+/**
+ * Maps a single property value from SpecVerse to a target framework/library
+ *
+ * Fallback chain:
+ * 1. Component-specific mapping
+ * 2. Common property mapping
+ * 3. Original value (passthrough)
+ *
+ * @param componentType - Component type (e.g., 'button', 'table')
+ * @param propertyName - Property name (e.g., 'variant', 'size')
+ * @param specverseValue - SpecVerse property value (e.g., 'primary', 'large')
+ * @param target - Target framework/library
+ * @returns Mapped property value for target
+ */
+export declare function mapProperty(componentType: string, propertyName: string, specverseValue: any, target: PropertyTarget): any;
+/**
+ * Gets the semantic meaning of a property value (universal across frameworks)
+ *
+ * @param propertyName - Property name
+ * @param specverseValue - SpecVerse property value
+ * @returns Semantic meaning string
+ */
+export declare function getSemanticMeaning(propertyName: string, specverseValue: string): string;
+/**
+ * Maps all properties of a component to a target framework/library
+ *
+ * @param componentType - Component type
+ * @param properties - Object containing all component properties
+ * @param target - Target framework/library
+ * @returns Object with all properties mapped to target
+ */
+export declare function mapProperties(componentType: string, properties: Record<string, any>, target: PropertyTarget): Record<string, any>;
+/**
+ * Gets all framework targets for a given framework category
+ *
+ * @param category - Framework category
+ * @returns Array of property targets for that framework
+ */
+export declare function getFrameworkTargets(category: FrameworkCategory): PropertyTarget[];
+/**
+ * Checks if a property value has a mapping for a specific target
+ *
+ * @param componentType - Component type
+ * @param propertyName - Property name
+ * @param specverseValue - SpecVerse property value
+ * @param target - Target framework/library
+ * @returns True if mapping exists, false otherwise
+ */
+export declare function hasMapping(componentType: string, propertyName: string, specverseValue: string, target: PropertyTarget): boolean;
+/**
+ * Gets all available mappings for a property across all frameworks
+ *
+ * Useful for debugging and documentation generation
+ *
+ * @param componentType - Component type
+ * @param propertyName - Property name
+ * @param specverseValue - SpecVerse property value
+ * @returns Object with all target mappings
+ */
+export declare function getAllMappings(componentType: string, propertyName: string, specverseValue: string): Partial<PropertyValueMapping> | null;
+//# sourceMappingURL=property-mapper.d.ts.map

package/libs/instance-factories/views/templates/shared/property-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-mapper.d.ts","sourceRoot":"","sources":["property-mapper.ts"],"names":[],"mappings":"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"}