@specverse/engines 5.0.2 → 5.1.0

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

@@ -1,323 +0,0 @@
-/**
- * SpecVerse JavaScript API Usage Examples
- * 
- * Simple examples showing how to use SpecVerse from JavaScript
- */
-
-import { SpecVerseParser } from '../../dist/index.js';
-import { readFileSync, writeFileSync } from 'fs';
-import * as yaml from 'js-yaml';
-
-// ============================================
-// BASIC USAGE EXAMPLE
-// ============================================
-
-// 1. Parse a SpecVerse file
-function parseSpec(filePath) {
-  // Load the schema (in real usage, this would be from node_modules/@specverse/lang/schema/)
-  const schema = JSON.parse(readFileSync('../../schema/SPECVERSE-SCHEMA.json', 'utf8'));
-  
-  // Create parser
-  const parser = new SpecVerseParser(schema);
-  
-  // Parse the file
-  const content = readFileSync(filePath, 'utf8');
-  const result = parser.parseContent(content, filePath);
-  
-  if (result.errors.length > 0) {
-    console.error('Errors:', result.errors);
-    return null;
-  }
-  
-  console.log('✅ Parsed successfully');
-  return result.ast;
-}
-
-// 2. Validate a specification
-function validateSpec(filePath) {
-  const schema = JSON.parse(readFileSync('../../schema/SPECVERSE-SCHEMA.json', 'utf8'));
-  const parser = new SpecVerseParser(schema);
-  
-  const content = readFileSync(filePath, 'utf8');
-  const result = parser.parseContent(content, filePath);
-  
-  return result.errors.length === 0;
-}
-
-// 3. Convert .specly to .yaml
-function speclyToYaml(inputPath, outputPath) {
-  const schema = JSON.parse(readFileSync('../../schema/SPECVERSE-SCHEMA.json', 'utf8'));
-  const parser = new SpecVerseParser(schema);
-  
-  const content = readFileSync(inputPath, 'utf8');
-  const result = parser.processToYaml(content);
-  
-  if (result.errors.length === 0) {
-    writeFileSync(outputPath, result.yaml);
-    console.log('✅ Converted to YAML');
-    return true;
-  }
-  
-  console.error('❌ Conversion failed:', result.errors);
-  return false;
-}
-
-// 4. Extract information from AST
-function analyzeSpec(ast) {
-  if (!ast) return null;
-  
-  // Count different elements
-  const stats = {
-    components: ast.components.length,
-    models: 0,
-    controllers: 0,
-    services: 0,
-    events: 0,
-    views: 0
-  };
-  
-  // Iterate through components
-  ast.components.forEach(component => {
-    stats.models += component.models?.length || 0;
-    stats.controllers += component.controllers?.length || 0;
-    stats.services += component.services?.length || 0;
-    stats.events += component.events?.length || 0;
-    stats.views += component.views?.length || 0;
-  });
-  
-  return stats;
-}
-
-// 5. Example: Generate a simple report
-function generateReport(filePath) {
-  const ast = parseSpec(filePath);
-  if (!ast) return;
-  
-  const stats = analyzeSpec(ast);
-  
-  const report = {
-    file: filePath,
-    timestamp: new Date().toISOString(),
-    statistics: stats,
-    components: ast.components.map(c => ({
-      name: c.name,
-      version: c.version,
-      modelCount: c.models?.length || 0,
-      exports: c.exports
-    }))
-  };
-  
-  console.log('\n📊 Specification Report:');
-  console.log(JSON.stringify(report, null, 2));
-  
-  return report;
-}
-
-// ============================================
-// USING THE INFERENCE ENGINE
-// ============================================
-
-import { LogicalInferenceEngine } from '../../dist/index.js';
-
-async function runInference(filePath) {
-  // Parse the file first
-  const ast = parseSpec(filePath);
-  if (!ast) return;
-  
-  // Configure 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'
-    }
-  };
-  
-  // Create and run inference engine
-  const engine = 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 engine.loadRules();
-  
-  if (!rulesValidation.valid) {
-    console.error('❌ Failed to load inference rules:', rulesValidation.errors.map(e => e.message));
-    return null;
-  }
-  
-  // Run inference
-  const componentName = 'GeneratedComponent';
-  const result = await engine.inferLogicalSpecification(models, componentName);
-  
-  console.log('✅ Inference complete:');
-  console.log('   Validation:', result.validation.valid ? '✅' : '❌');
-  console.log('   Controllers:', result.statistics.controllersGenerated);
-  console.log('   Services:', result.statistics.servicesGenerated);
-  console.log('   Events:', result.statistics.eventsGenerated);
-  console.log('   Views:', result.statistics.viewsGenerated);
-  
-  if (!result.validation.valid) {
-    console.error('   Errors:', result.validation.errors.map(e => e.message));
-  }
-  
-  // Save the inferred specification
-  const output = yaml.dump(result.specification, {
-    indent: 2,
-    lineWidth: 120
-  });
-  
-  writeFileSync('inferred-spec.yaml', output);
-  console.log('💾 Saved to inferred-spec.yaml');
-  
-  return result;
-}
-
-// ============================================
-// USING GENERATORS
-// ============================================
-
-import { 
-  AIViewGenerator, 
-  UMLGenerator, 
-  DocumentationGenerator 
-} from '../../dist/index.js';
-
-function generateAIView(ast) {
-  try {
-    const generator = new AIViewGenerator();
-    const aiSpec = generator.generate(ast);
-    
-    // Save as YAML
-    const output = yaml.dump(aiSpec, { indent: 2 });
-    writeFileSync('ai-spec.yaml', output);
-    
-    console.log('✅ AI specification generated');
-    return aiSpec;
-  } catch (error) {
-    console.warn('⚠️ AI view generation failed:', error.message);
-  }
-}
-
-function generateDiagrams(ast) {
-  try {
-    const generator = new UMLGenerator();
-    
-    // Generate ER diagram
-    const erDiagram = generator.generate(ast, { 
-      type: 'er', 
-      includeAttributes: true,
-      includeRelationships: true 
-    });
-    if (erDiagram) {
-      writeFileSync('diagram-er.mmd', erDiagram);
-      console.log('✅ ER diagram generated');
-    }
-    
-    // Generate architecture diagram  
-    const archDiagram = generator.generate(ast, { 
-      type: 'architecture', 
-      includeControllers: true,
-      includeServices: true,
-      includeEvents: true
-    });
-    if (archDiagram) {
-      writeFileSync('diagram-architecture.mmd', archDiagram);
-      console.log('✅ Architecture diagram generated');
-    }
-  } catch (error) {
-    console.warn('⚠️ Diagram generation failed:', error.message);
-  }
-}
-
-function generateDocs(ast) {
-  try {
-    const generator = new DocumentationGenerator();
-    
-    // Generate markdown
-    const markdown = generator.generate(ast, { 
-      format: 'markdown',
-      includeTableOfContents: true,
-      includeExamples: true,
-      includeDiagrams: false
-    });
-    writeFileSync('documentation.md', markdown);
-    
-    // Generate HTML
-    const html = generator.generate(ast, { 
-      format: 'html',
-      includeTableOfContents: true,
-      includeExamples: true
-    });
-    writeFileSync('documentation.html', html);
-    
-    // Generate OpenAPI
-    const openapi = generator.generate(ast, { 
-      format: 'openapi',
-      baseUrl: 'https://api.example.com'
-    });
-    writeFileSync('openapi.json', openapi);
-    
-    console.log('✅ Documentation generated (Markdown, HTML, OpenAPI)');
-    return markdown;
-  } catch (error) {
-    console.warn('⚠️ Documentation generation failed:', error.message);
-  }
-}
-
-// ============================================
-// MAIN EXAMPLE
-// ============================================
-
-async function main() {
-  const specFile = '../01-fundamentals/01-01-basic-model.specly';
-  
-  // Basic operations
-  console.log('1️⃣ Parsing...');
-  const ast = parseSpec(specFile);
-  
-  if (ast) {
-    console.log('2️⃣ Analyzing...');
-    const stats = analyzeSpec(ast);
-    console.log('   Stats:', stats);
-    
-    console.log('3️⃣ Running inference...');
-    await runInference(specFile);
-    
-    console.log('4️⃣ Generating outputs...');
-    generateAIView(ast);
-    generateDiagrams(ast);
-    generateDocs(ast);
-    
-    console.log('5️⃣ Converting to YAML...');
-    speclyToYaml(specFile, 'converted.yaml');
-  }
-  
-  console.log('\n✨ Done!');
-}
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch(console.error);
-}
-
-// Export functions for use in other modules
-export {
-  parseSpec,
-  validateSpec,
-  speclyToYaml,
-  analyzeSpec,
-  generateReport,
-  runInference,
-  generateAIView,
-  generateDiagrams,
-  generateDocs
-};

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

@@ -1,363 +0,0 @@
-/**
- * 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
-};