@specverse/engine-realize 3.5.3

package/assets/examples/10-api/usage-example.ts

@@ -0,0 +1,363 @@
+/**
+ * SpecVerse TypeScript/JavaScript API Usage Examples
+ * 
+ * This file demonstrates how to use SpecVerse functionality programmatically
+ * instead of through the CLI.
+ */
+
+import {
+  // Parser and AST
+  SpecVerseParser,
+  ParseResult,
+  SpecVerseAST,
+  
+  // Inference Engine
+  LogicalInferenceEngine,
+  InferenceEngineConfig,
+  
+  // Generators
+  AIViewGenerator,
+  UMLGenerator,
+  DocumentationGenerator,
+  UnifiedDiagramGenerator,
+  
+  // Types
+  ModelSpec,
+  ControllerSpec,
+  ServiceSpec,
+  EventSpec,
+  ViewSpec
+} from '@specverse/lang';
+
+import { readFileSync, writeFileSync } from 'fs';
+import * as yaml from 'js-yaml';
+
+// ============================================
+// 1. PARSING SPECVERSE FILES
+// ============================================
+
+async function parseSpecification(filePath: string): Promise<SpecVerseAST | undefined> {
+  // Load the schema (in real usage, this would be from node_modules/@specverse/lang/schema/)
+  const schema = JSON.parse(readFileSync('node_modules/@specverse/lang/schema/SPECVERSE-SCHEMA.json', 'utf8'));
+  
+  // Create parser instance
+  const parser = new SpecVerseParser(schema);
+  
+  // Read and parse the file
+  const content = readFileSync(filePath, 'utf8');
+  const result: ParseResult = parser.parseContent(content, filePath);
+  
+  // Check for errors
+  if (result.errors.length > 0) {
+    console.error('Parse errors:', result.errors);
+    return undefined;
+  }
+  
+  // Handle warnings if any
+  if (result.warnings && result.warnings.length > 0) {
+    console.warn('Parse warnings:', result.warnings);
+  }
+  
+  console.log('✅ Successfully parsed:', filePath);
+  return result.ast;
+}
+
+// ============================================
+// 2. USING THE INFERENCE ENGINE
+// ============================================
+
+async function runInference(ast: SpecVerseAST): Promise<any> {
+  // Configure inference options
+  const config: Partial<InferenceEngineConfig> = {
+    logical: {
+      generateControllers: true,
+      generateServices: true,
+      generateEvents: true,
+      generateViews: true,
+      generateTypes: true,
+    },
+    rules: {
+      logicalRulesPath: 'node_modules/@specverse/lang/dist/inference-engine/rules/logical',
+      deploymentRulesPath: 'node_modules/@specverse/lang/dist/inference-engine/rules/deployment'
+    }
+  };
+  
+  // Create inference engine instance
+  const inferenceEngine = new LogicalInferenceEngine(config);
+  
+  // Extract models from AST
+  const models = ast.components.flatMap(c => c.models);
+  
+  // Load rules first
+  console.log('📋 Loading inference rules...');
+  const rulesValidation = await inferenceEngine.loadRules();
+  
+  if (!rulesValidation.valid) {
+    console.error('❌ Failed to load inference rules:', rulesValidation.errors.map(e => e.message));
+    return undefined;
+  }
+  
+  // Run inference on models
+  const componentName = 'GeneratedComponent';
+  const inferenceResult = await inferenceEngine.inferLogicalSpecification(models, componentName);
+  
+  console.log('📊 Inference Results:');
+  console.log('   Validation:', inferenceResult.validation.valid ? '✅' : '❌');
+  console.log('   Models processed:', inferenceResult.statistics.modelsProcessed);
+  console.log('   Controllers generated:', inferenceResult.statistics.controllersGenerated);
+  console.log('   Services generated:', inferenceResult.statistics.servicesGenerated);
+  console.log('   Events generated:', inferenceResult.statistics.eventsGenerated);
+  console.log('   Views generated:', inferenceResult.statistics.viewsGenerated);
+  
+  if (!inferenceResult.validation.valid) {
+    console.error('   Errors:', inferenceResult.validation.errors.map(e => e.message));
+  }
+  
+  return inferenceResult;
+}
+
+// ============================================
+// 3. GENERATING AI-OPTIMIZED SPECIFICATIONS
+// ============================================
+
+async function generateAIView(ast: SpecVerseAST): Promise<void> {
+  const generator = new AIViewGenerator();
+  
+  // Generate AI-optimized specification
+  const aiSpec = generator.generate(ast);
+  
+  // Convert to YAML for readability
+  const yamlOutput = yaml.dump(aiSpec, {
+    indent: 2,
+    lineWidth: 120,
+    noRefs: true
+  });
+  
+  writeFileSync('output/ai-optimized.yaml', yamlOutput);
+  console.log('✅ AI-optimized specification generated');
+}
+
+// ============================================
+// 4. GENERATING UML DIAGRAMS
+// ============================================
+
+async function generateUMLDiagrams(ast: SpecVerseAST): Promise<void> {
+  try {
+    const generator = new UMLGenerator();
+    
+    // Generate different types of diagrams with proper options
+    const diagramTypes = [
+      { type: 'er' as const, includeAttributes: true, includeRelationships: true },
+      { type: 'sequence' as const, includeEvents: true },
+      { type: 'architecture' as const, includeControllers: true, includeServices: true, includeEvents: true },
+      { type: 'lifecycle' as const }
+    ];
+    
+    // Generate and save diagrams
+    for (const options of diagramTypes) {
+      const content = generator.generate(ast, options);
+      if (content) {
+        writeFileSync(`output/diagram-${options.type}.mmd`, content);
+        console.log(`✅ Generated ${options.type} diagram`);
+      }
+    }
+  } catch (error) {
+    console.warn('⚠️ UML diagram generation failed:', error instanceof Error ? error.message : String(error));
+  }
+}
+
+// ============================================
+// 5. GENERATING DOCUMENTATION
+// ============================================
+
+async function generateDocumentation(ast: SpecVerseAST): Promise<void> {
+  try {
+    const generator = new DocumentationGenerator();
+    
+    // Generate markdown documentation
+    const markdown = generator.generate(ast, { 
+      format: 'markdown',
+      includeTableOfContents: true,
+      includeExamples: true,
+      includeDiagrams: false
+    });
+    writeFileSync('output/documentation.md', markdown);
+    
+    // Generate HTML documentation  
+    const html = generator.generate(ast, { 
+      format: 'html',
+      includeTableOfContents: true,
+      includeExamples: true
+    });
+    writeFileSync('output/documentation.html', html);
+    
+    // Generate OpenAPI specification
+    const openapi = generator.generate(ast, { 
+      format: 'openapi',
+      baseUrl: 'https://api.example.com'
+    });
+    writeFileSync('output/openapi.json', openapi);
+    
+    console.log('✅ Documentation generated (Markdown, HTML, OpenAPI)');
+  } catch (error) {
+    console.warn('⚠️ Documentation generation failed:', error instanceof Error ? error.message : String(error));
+  }
+}
+
+// ============================================
+// 6. WORKING WITH MERMAID DIAGRAMS (V3.1)
+// ============================================
+
+async function generateMermaidDiagrams(filePath: string): Promise<void> {
+  const generator = new UnifiedDiagramGenerator();
+  
+  // Generate all diagram types
+  const outputDir = 'output/diagrams';
+  await generator.generateFromFile(filePath, outputDir);
+  
+  console.log('✅ Mermaid diagrams generated in:', outputDir);
+}
+
+// ============================================
+// 7. CUSTOM PROCESSING EXAMPLE
+// ============================================
+
+async function customProcessing(ast: SpecVerseAST): Promise<void> {
+  // Extract all models
+  const allModels: ModelSpec[] = ast.components.flatMap(c => c.models);
+  
+  // Extract all controllers
+  const allControllers: ControllerSpec[] = ast.components.flatMap(c => c.controllers);
+  
+  // Extract all events
+  const allEvents: EventSpec[] = ast.components.flatMap(c => c.events);
+  
+  // Custom analysis
+  console.log('\n📊 Custom Analysis:');
+  console.log('Total models:', allModels.length);
+  console.log('Models with lifecycles:', allModels.filter(m => m.lifecycle).length);
+  console.log('Total endpoints:', allControllers.flatMap(c => c.actions).length);
+  console.log('Total events:', allEvents.length);
+  
+  // Generate custom output
+  const customOutput = {
+    summary: {
+      modelCount: allModels.length,
+      controllerCount: allControllers.length,
+      eventCount: allEvents.length,
+    },
+    models: allModels.map(m => ({
+      name: m.name,
+      attributeCount: Object.keys(m.attributes || {}).length,
+      hasLifecycle: !!m.lifecycle,
+      relationshipCount: m.relationships?.length || 0
+    })),
+    controllers: allControllers.map(c => ({
+      name: c.name,
+      actionCount: c.actions.length,
+      model: c.model
+    }))
+  };
+  
+  writeFileSync('output/custom-analysis.json', JSON.stringify(customOutput, null, 2));
+  console.log('✅ Custom analysis saved');
+}
+
+// ============================================
+// 8. VALIDATION ONLY
+// ============================================
+
+function validateSpecification(filePath: string): boolean {
+  const schema = JSON.parse(readFileSync('node_modules/@specverse/lang/schema/SPECVERSE-SCHEMA.json', 'utf8'));
+  const parser = new SpecVerseParser(schema);
+  
+  const content = readFileSync(filePath, 'utf8');
+  const result = parser.parseContent(content, filePath);
+  
+  if (result.errors.length === 0) {
+    console.log('✅ Specification is valid');
+    return true;
+  } else {
+    console.error('❌ Validation errors:');
+    result.errors.forEach(error => console.error('  -', error));
+    return false;
+  }
+}
+
+// ============================================
+// 9. PROCESSING SPECLY TO YAML
+// ============================================
+
+function processSpeclyToYaml(speclyPath: string, outputPath: string): void {
+  const schema = JSON.parse(readFileSync('node_modules/@specverse/lang/schema/SPECVERSE-SCHEMA.json', 'utf8'));
+  const parser = new SpecVerseParser(schema);
+  
+  const content = readFileSync(speclyPath, 'utf8');
+  const result = parser.processToYaml(content);
+  
+  if (result.errors.length > 0) {
+    console.error('❌ Processing errors:', result.errors);
+    return;
+  }
+  
+  writeFileSync(outputPath, result.yaml);
+  console.log('✅ Processed to YAML:', outputPath);
+}
+
+// ============================================
+// MAIN EXAMPLE USAGE
+// ============================================
+
+async function main() {
+  try {
+    const specFile = 'examples/01-fundamentals/01-01-basic-model.specly';
+    
+    // 1. Parse the specification
+    const ast = await parseSpecification(specFile);
+    if (!ast) {
+      console.error('Failed to parse specification');
+      return;
+    }
+    
+    // 2. Run inference to generate complete architecture
+    const inferenceResult = await runInference(ast);
+    
+    // 3. Generate various outputs
+    await generateAIView(ast);
+    await generateUMLDiagrams(ast);
+    await generateDocumentation(ast);
+    await generateMermaidDiagrams(specFile);
+    
+    // 4. Custom processing
+    await customProcessing(ast);
+    
+    // 5. Process .specly to .yaml
+    processSpeclyToYaml(specFile, 'output/processed.yaml');
+    
+    console.log('\n✨ All operations completed successfully!');
+    
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+// Run if this file is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+// ============================================
+// EXPORTS FOR USE IN OTHER MODULES
+// ============================================
+
+export {
+  parseSpecification,
+  runInference,
+  generateAIView,
+  generateUMLDiagrams,
+  generateDocumentation,
+  generateMermaidDiagrams,
+  customProcessing,
+  validateSpecification,
+  processSpeclyToYaml
+};

package/assets/examples/10-api/workflow-test.js

@@ -0,0 +1,113 @@
+/**
+ * SpecVerse API Workflow Test
+ * 
+ * Focused end-to-end workflow test for the SpecVerse API
+ * This is a minimal, streamlined test extracted from test-specverse-api
+ */
+
+import { SpecVerseParser, LogicalInferenceEngine } from '../../dist/index.js';
+import { readFileSync, writeFileSync } from 'fs';
+
+// Simple test specification
+const testSpec = `components:
+  UserManagement:
+    version: "1.0.0"
+    description: "User management system"
+
+    models:
+      User:
+        description: "User model for API testing"
+        attributes:
+          id: UUID required
+          name: String required
+          email: Email unique required
+          created_at: DateTime auto=now
+
+        lifecycles:
+          status:
+            flow: inactive -> active -> suspended
+
+deployments: {}`;
+
+async function testFullWorkflow() {
+  console.log('🧪 Testing full API workflow...');
+  
+  try {
+    // 1. Parse the spec
+    console.log('1️⃣ Parsing specification...');
+    
+    const schema = JSON.parse(readFileSync('schema/SPECVERSE-SCHEMA.json', 'utf8'));
+    const parser = new SpecVerseParser(schema);
+    const result = parser.parseContent(testSpec, 'test.specly');
+    
+    if (result.errors.length > 0) {
+      throw new Error('Parse failed: ' + result.errors.map(e => e.message).join(', '));
+    }
+    
+    const ast = result.ast;
+    console.log('✅ Parsed successfully');
+    
+    // 2. Run inference
+    console.log('2️⃣ Running inference...');
+    const config = {
+      logical: {
+        generateControllers: true,
+        generateServices: true,
+        generateEvents: true,
+        generateViews: true,
+        generateTypes: true
+      },
+      rules: {
+        logicalRulesPath: 'dist/inference-engine/rules/logical',
+        deploymentRulesPath: 'dist/inference-engine/rules/deployment'
+      }
+    };
+    
+    const engine = new LogicalInferenceEngine(config);
+    const models = ast.components.flatMap(c => c.models);
+    
+    // Load rules
+    const rulesResult = await engine.loadRules();
+    if (!rulesResult.valid) {
+      throw new Error('Failed to load rules: ' + rulesResult.errors.map(e => e.message).join(', '));
+    }
+    
+    // Run inference
+    const inferenceResult = await engine.inferLogicalSpecification(models, 'TestComponent');
+    
+    console.log('✅ Inference completed!');
+    console.log('   Generated Controllers:', inferenceResult.statistics.controllersGenerated || 0);
+    console.log('   Generated Services:', inferenceResult.statistics.servicesGenerated || 0);
+    console.log('   Generated Events:', inferenceResult.statistics.eventsGenerated || 0);
+    console.log('   Generated Views:', inferenceResult.statistics.viewsGenerated || 0);
+    
+    if (inferenceResult.validation.valid) {
+      console.log('✅ Generated specification is valid!');
+      console.log('🎉 FULL API WORKFLOW SUCCESS!');
+      return true;
+    } else {
+      console.log('⚠️ Generated specification has warnings:', inferenceResult.validation.errors.length);
+      inferenceResult.validation.errors.forEach(error => {
+        console.log('   -', error.message);
+      });
+      return false;
+    }
+    
+  } catch (error) {
+    console.error('❌ Workflow failed:', error.message);
+    return false;
+  }
+}
+
+// Export for use in tests
+export { testFullWorkflow };
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  testFullWorkflow()
+    .then(success => process.exit(success ? 0 : 1))
+    .catch(error => {
+      console.error('Unexpected error:', error);
+      process.exit(1);
+    });
+}

package/assets/examples/manifests/01-simple-default-mappings.yaml

@@ -0,0 +1,36 @@
+# SpecVerse v3.3 Manifest - Simple Default Mappings Example
+#
+# This manifest demonstrates the simplest v3.3 approach:
+# Using defaultMappings to specify instance factories by category.
+#
+# Resolution: All instances of a category use the same factory.
+
+specVersion: "3.3.0"
+name: "simple-api-manifest"
+description: "Basic REST API with Fastify and PostgreSQL using default mappings"
+version: "1.0.0"
+
+# Link to deployment specification
+deployment:
+  deploymentSource: "./blog-api.specly"
+  deploymentName: "production"
+
+# Default instance factories by category (lowest priority)
+# Fine-grained factories allow flexible composition
+defaultMappings:
+  controller: "FastifyAPI"      # Pure Fastify routes (no ORM coupling)
+  service: "PrismaORM"          # Prisma ORM for data access
+  storage: "PostgreSQL15"        # PostgreSQL database instance
+
+# Capability-based mappings for cross-cutting concerns
+capabilityMappings:
+  - capability: "validation.runtime"
+    instanceFactory: "ZodValidation"
+
+# Global configuration applied to all instance factories
+configuration:
+  environment: "production"
+  region: "us-east-1"
+  logging:
+    level: "info"
+    format: "json"

package/assets/examples/manifests/02-capability-mappings.yaml

@@ -0,0 +1,55 @@
+# SpecVerse v3.3 Manifest - Capability Mappings Example
+#
+# This manifest demonstrates capability-based mapping with pattern matching.
+# Different capabilities can be mapped to different instance factories.
+#
+# Resolution: Matches capability patterns with wildcard support.
+
+specVersion: "3.3.0"
+name: "capability-based-manifest"
+description: "API with specialized factories for different capability patterns"
+version: "1.0.0"
+
+deployment:
+  deploymentSource: "./blog-api.specly"
+  deploymentName: "production"
+
+# Default factories (used when no capability match found)
+defaultMappings:
+  controller: "FastifyPrismaAPI"
+  storage: "PostgreSQL15"
+
+# Capability-based mappings (medium priority)
+# Overrides defaults when capability pattern matches
+capabilityMappings:
+  # REST API endpoints use Fastify
+  - capability: "api.rest"
+    instanceFactory: "FastifyPrismaAPI"
+    version: "^1.0.0"
+
+  # WebSocket capabilities use specialized factory
+  - capability: "api.websocket"
+    instanceFactory: "FastifyWebSocketAPI"
+    version: "^1.0.0"
+
+  # Reporting endpoints get specialized configuration
+  - capability: "api.rest.reports"
+    instanceFactory: "ReportingAPI"
+    configuration:
+      caching: true
+      timeout: 60000
+
+  # Database storage uses PostgreSQL
+  - capability: "storage.database"
+    instanceFactory: "PostgreSQL15"
+
+  # Cache capabilities use Redis
+  - capability: "storage.cache"
+    instanceFactory: "Redis7"
+
+  # Validation uses Zod
+  - capability: "validation.runtime"
+    instanceFactory: "ZodValidation"
+
+configuration:
+  environment: "production"

package/assets/examples/manifests/03-hybrid-mappings.yaml

@@ -0,0 +1,109 @@
+# SpecVerse v3.3 Manifest - Hybrid Mappings Example
+#
+# This manifest demonstrates the full power of v3.3 hybrid mapping:
+# All three mapping strategies working together with clear priorities.
+#
+# Resolution Priority:
+# 1. instanceMappings (highest) - explicit instance name
+# 2. capabilityMappings (medium) - capability pattern match
+# 3. defaultMappings (lowest) - category-based fallback
+
+specVersion: "3.3.0"
+name: "hybrid-mapping-manifest"
+description: "Complex API using all three mapping strategies for maximum flexibility"
+version: "1.0.0"
+
+deployment:
+  deploymentSource: "./blog-api.specly"
+  deploymentName: "production"
+
+# PRIORITY 3: Default factories by category (lowest priority)
+# Used when no capability or instance mapping matches
+# Fine-grained factories enable flexible composition
+defaultMappings:
+  controller: "FastifyAPI"       # Pure Fastify (no ORM coupling)
+  service: "PrismaORM"           # Prisma data access layer
+  view: "TypeScriptSDK"
+  storage: "PostgreSQL15"
+  infrastructure: "DockerK8s"
+
+# PRIORITY 2: Capability-based mappings (medium priority)
+# Overrides defaultMappings when capability pattern matches
+capabilityMappings:
+  # Validation capabilities
+  - capability: "validation.runtime"
+    instanceFactory: "ZodValidation"
+
+  # Most REST APIs use Fastify
+  - capability: "api.rest"
+    instanceFactory: "FastifyAPI"
+
+  # But reporting APIs get specialized treatment
+  - capability: "api.rest.reports"
+    instanceFactory: "ReportingAPI"
+    configuration:
+      caching: true
+      batchSize: 1000
+      timeout: 120000
+
+  # Analytics capabilities use special processing
+  - capability: "api.rest.analytics"
+    instanceFactory: "AnalyticsAPI"
+    configuration:
+      aggregation: true
+      realtime: true
+
+  # WebSocket for real-time features
+  - capability: "api.websocket"
+    instanceFactory: "FastifyWebSocketAPI"
+
+  # Standard database operations
+  - capability: "storage.database"
+    instanceFactory: "PostgreSQL15"
+
+  # Cache operations
+  - capability: "storage.cache"
+    instanceFactory: "Redis7"
+
+# PRIORITY 1: Instance-specific mappings (highest priority)
+# Explicit instance names override everything else
+instanceMappings:
+  # Analytics database uses MongoDB instead of PostgreSQL
+  - instanceName: "analyticsDb"
+    instanceFactory: "MongoDB6"
+    configuration:
+      sharding: true
+      replication: 3
+
+  # High-performance cache for user sessions
+  - instanceName: "sessionCache"
+    instanceFactory: "Redis7"
+    configuration:
+      maxMemory: "4gb"
+      evictionPolicy: "allkeys-lru"
+
+  # Specialized API for admin operations
+  - instanceName: "adminApi"
+    instanceFactory: "NestJSAPI"
+    configuration:
+      rbac: true
+      auditLog: true
+
+  # Main user-facing API with specific config
+  - instanceName: "userApi"
+    instanceFactory: "FastifyPrismaAPI"
+    configuration:
+      rateLimit:
+        max: 1000
+        timeWindow: "1 minute"
+
+# Global configuration
+configuration:
+  environment: "production"
+  region: "us-east-1"
+  monitoring:
+    enabled: true
+    provider: "datadog"
+  logging:
+    level: "info"
+    format: "json"