@specverse/engines 5.0.2 → 5.1.0

package/assets/examples/10-api/README.md

@@ -1,216 +0,0 @@
-# 09-API: SpecVerse API Integration Examples
-
-These are complete examples for programmatic usage of the SpecVerse Language API in TypeScript and JavaScript applications.
-
-## Overview
-
-This directory contains comprehensive API integration examples demonstrating how to use SpecVerse programmatically in your applications. These examples cover the complete workflow from parsing specifications to generating code and documentation.
-
-## Files Overview
-
-- specverse-lang/examples/10-api/usage-example.js 
-- specverse-lang/examples/10-api/usage-example.ts
-
-**Comprehensive API usage examples** showing the complete SpecVerse workflow:
-
-- **Parsing**: Load and validate .specly files
-- **AI Inference**: Run logical inference to enhance specifications
-- **Code Generation**: Generate diagrams, documentation, and YAML output
-- **Error Handling**: Proper error management patterns
-- **Full Workflow**: End-to-end specification processing
-
-**Best for**: Learning the API, understanding all capabilities, integration planning
-
-<!-- ### **"[workflow-test.js]"**a -->
-- specverse-lang/examples/10-api/workflow-test.js
-
-**Focused end-to-end workflow test** for production validation:
-
-- **Quick Testing**: Minimal test for API functionality validation
-- **CI/CD Integration**: Suitable for automated testing pipelines  
-- **Error Reporting**: Clear success/failure indicators with actionable feedback
-- **Self-Contained**: Includes embedded test specification
-
-**Best for**: CI/CD pipelines, automated testing, quick API health checks
-
-<!-- ### **[package-integration-test.js](./package-integration-test.js)** -->
-- specverse-lang/examples/10-api/package-integration-test.js
-**npm package installation and integration test**:
-
-- **Package Testing**: Validates complete npm installation workflow
-- **Real-world Simulation**: Tests actual published package usage
-- **API Verification**: Confirms all API features work after installation
-- **Integration Validation**: End-to-end package integration testing
-
-**Best for**: Release validation, package testing, integration verification
-
-## Getting Started
-
-### Quick Start
-
-```bash
-# Run comprehensive API examples
-node examples/10-api/usage-example.js
-
-# Run focused workflow test  
-node examples/10-api/workflow-test.js
-
-# Run package integration test
-node examples/10-api/package-integration-test.js
-```
-
-### Integration in Your Project
-
-1. **Install SpecVerse Language**:
-   ```bash
-   npm install @specverse/lang
-   ```
-
-2. **Copy and adapt examples**:
-   - Start with `usage-example.js` or `usage-example.ts`
-   - Modify for your specific use case
-   - Use `workflow-test.js` for testing integration
-
-3. **Key API Components**:
-   ```javascript
-   import { SpecVerseParser, LogicalInferenceEngine, UMLDiagramGenerator } from '@specverse/engines/parser';
-   ```
-
-## API Features Demonstrated
-
-### 🔧 Core Parsing
-- Load and validate SpecVerse specifications
-- Schema validation with comprehensive error reporting
-- Convention processing and normalization
-
-### 🤖 AI Inference Engine
-- Logical inference for architecture generation
-- Controller, service, and event generation
-- Relationship inference and optimization
-
-### 📊 Code Generation
-- UML diagram generation (ER, Architecture, Sequence, Lifecycle)
-- YAML output generation
-- Documentation generation
-
-### ⚡ Error Handling
-- Comprehensive error reporting
-- Validation feedback
-- Processing diagnostics
-
-## Integration Patterns
-
-### Web Applications
-```javascript
-// React/Vue/Angular integration
-import { SpecVerseParser } from '@specverse/engines/parser';
-
-const parser = new SpecVerseParser(schema);
-const result = parser.parseContent(specContent, 'component.specly');
-```
-
-### Build Tools
-```javascript
-// webpack/vite plugin integration
-const { processSpecification } = require('@specverse/lang');
-
-// In build pipeline
-const output = await processSpecification(inputPath, outputPath);
-```
-
-### API Services
-```javascript
-// Express/Fastify API endpoint
-app.post('/api/specverse/validate', async (req, res) => {
-  const result = await validateSpecification(req.body.spec);
-  res.json(result);
-});
-```
-
-### CLI Tools
-```javascript
-// Custom CLI tool integration
-#!/usr/bin/env node
-const { SpecVerseParser } = require('@specverse/lang');
-// Custom CLI implementation
-```
-
-## Testing Integration
-
-All API examples are integrated into the SpecVerse test suite:
-
-```bash
-# Run API tests as part of main test suite
-npm test
-
-# Run API tests individually
-npm run test:api              # workflow-test.js
-npm run test:api:package      # package-integration-test.js
-```
-
-## TypeScript Support
-
-SpecVerse provides complete TypeScript definitions:
-
-```typescript
-import { 
-  SpecVerseParser,
-  LogicalInferenceEngine,
-  ParseResult,
-  InferenceConfig 
-} from '@specverse/engines/parser';
-
-const parser: SpecVerseParser = new SpecVerseParser(schema);
-const result: ParseResult = parser.parseContent(content, filename);
-```
-
-## Error Handling Patterns
-
-### Validation Errors
-```javascript
-try {
-  const result = parser.parseContent(content, filename);
-  if (!result.success) {
-    console.error('Validation failed:', result.errors);
-  }
-} catch (error) {
-  console.error('Parse error:', error.message);
-}
-```
-
-### Inference Errors
-```javascript
-try {
-  const inference = await engine.inferLogicalSpecification(models, componentName);
-} catch (error) {
-  if (error.code === 'INFERENCE_FAILED') {
-    // Handle inference-specific errors
-  }
-}
-```
-
-## Performance Considerations
-
-- **Parsing**: Sub-5ms for typical specifications
-- **Inference**: Highly optimized rule processing
-- **Memory**: Efficient rule loading and caching
-- **Concurrent**: Safe for concurrent processing
-
-## Next Steps
-
-After exploring these API examples:
-
-1. **Integrate**: Add SpecVerse to your project
-2. **Customize**: Adapt examples to your use case  
-3. **Test**: Use workflow-test.js pattern for validation
-4. **Deploy**: Use package-integration-test.js for release validation
-
-## Related Documentation
-
-- [Main Examples](../) - Learning examples and language features
-- [CLI Reference](/reference/cli) - Command-line interface
-- [API Documentation](https://specverse.dev/api/) - Complete API reference
-
----
-
-**💡 Pro Tip**: Start with `usage-example.js` to understand the complete API, then use `workflow-test.js` patterns for production integration!

package/assets/examples/10-api/ai-spec.yaml

@@ -1,194 +0,0 @@
-metadata:
-  component: SpecVerseFundamentals
-  version: 1.0.0
-  description: 'Example 01-01: Basic model definition with attributes'
-  tags: []
-imports:
-  - from: '@specverse/primitives'
-    select:
-      - Money
-exports: []
-models:
-  - name: Product
-    attributes:
-      - name: id
-        type: UUID
-        constraints:
-          required: true
-          unique: false
-          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
-          format: uuid
-        dbMapping:
-          columnName: id
-          columnType: UUID
-          index: false
-          nullable: false
-        validation:
-          rules:
-            - required
-        metadata:
-          encrypted: false
-          audit: false
-      - name: name
-        type: String
-        constraints:
-          required: true
-          unique: false
-        dbMapping:
-          columnName: name
-          columnType: VARCHAR(255)
-          index: false
-          nullable: false
-        validation:
-          rules:
-            - required
-        metadata:
-          encrypted: false
-          audit: false
-      - name: summary
-        type: String
-        constraints:
-          required: false
-          unique: false
-        dbMapping:
-          columnName: summary
-          columnType: VARCHAR(255)
-          index: false
-          nullable: true
-        validation:
-          rules: []
-        metadata:
-          encrypted: false
-          audit: false
-      - name: price
-        type: Money
-        constraints:
-          required: true
-          unique: false
-        dbMapping:
-          columnName: price
-          columnType: VARCHAR(255)
-          index: false
-          nullable: false
-        validation:
-          rules:
-            - required
-        metadata:
-          encrypted: false
-          audit: false
-      - name: inStock
-        type: Boolean
-        constraints:
-          required: false
-          unique: false
-        dbMapping:
-          columnName: in_stock
-          columnType: BOOLEAN
-          index: false
-          nullable: true
-          defaultValue: 'true'
-        validation:
-          rules: []
-        metadata:
-          encrypted: false
-          audit: false
-      - name: category
-        type: String
-        constraints:
-          required: true
-          unique: false
-        dbMapping:
-          columnName: category
-          columnType: VARCHAR(255)
-          index: false
-          nullable: false
-        validation:
-          rules:
-            - required
-        metadata:
-          encrypted: false
-          audit: false
-      - name: contactEmail
-        type: Email
-        constraints:
-          required: false
-          unique: false
-          pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
-          format: email
-        dbMapping:
-          columnName: contact_email
-          columnType: VARCHAR(255)
-          index: false
-          nullable: true
-        validation:
-          rules:
-            - email
-        metadata:
-          encrypted: false
-          audit: false
-    relationships: []
-    behaviors:
-      - name: attachProfile
-        signature: 'attachProfile(profileName: String): Promise<Boolean>'
-        implementation:
-          preconditions:
-            - Profile exists and is compatible with this model
-          postconditions:
-            - Profile is attached
-            - Profile attributes are available
-          sideEffects: []
-          steps: []
-          transactional: true
-        metadata:
-          async: true
-          cacheable: false
-          idempotent: false
-      - name: detachProfile
-        signature: 'detachProfile(profileName: String): Promise<Boolean>'
-        implementation:
-          preconditions:
-            - Profile is currently attached
-          postconditions:
-            - Profile is detached
-            - Profile attributes are no longer available
-          sideEffects: []
-          steps: []
-          transactional: true
-        metadata:
-          async: true
-          cacheable: false
-          idempotent: false
-      - name: hasProfile
-        signature: 'hasProfile(profileName: String): Promise<Boolean>'
-        implementation:
-          preconditions: []
-          postconditions: []
-          sideEffects: []
-          steps: []
-          transactional: false
-        metadata:
-          async: true
-          cacheable: false
-          idempotent: false
-    lifecycle:
-      states: []
-      transitions: {}
-      currentStateField: state
-    dbMapping:
-      tableName: products
-      indexes: []
-controllers: []
-services: []
-views: []
-events: []
-infrastructure:
-  database:
-    type: postgresql
-    migrations: true
-    seedData: false
-  messaging:
-    type: rabbitmq
-    queues: []
-  caching:
-    type: redis
-    ttl: 3600

package/assets/examples/10-api/converted.yaml

@@ -1,96 +0,0 @@
-components:
-  SpecVerseFundamentals:
-    version: 1.0.0
-    description: "Example 01-01: Basic model definition with attributes"
-    import:
-      - from: "@specverse/primitives"
-        select:
-          - Money
-    export:
-      models:
-        - Product
-    models:
-      Product:
-        description: Simple product with basic attributes
-        attributes:
-          id:
-            name: id
-            type: UUID
-            required: true
-            unique: false
-          name:
-            name: name
-            type: String
-            required: true
-            unique: false
-          summary:
-            name: summary
-            type: String
-            required: false
-            unique: false
-          price:
-            name: price
-            type: Money
-            required: true
-            unique: false
-          inStock:
-            name: inStock
-            type: Boolean
-            required: false
-            unique: false
-            default: "true"
-          category:
-            name: category
-            type: String
-            required: true
-            unique: false
-            values:
-              - electronics
-              - books
-              - clothing
-              - home
-          contactEmail:
-            name: contactEmail
-            type: Email
-            required: false
-            unique: false
-        behaviors:
-          attachProfile:
-            description: Attach a profile to this model instance
-            parameters:
-              profileName:
-                name: profileName
-                type: String
-                required: true
-                unique: false
-            returns: Boolean
-            requires:
-              - Profile exists and is compatible with this model
-            ensures:
-              - Profile is attached
-              - Profile attributes are available
-          detachProfile:
-            description: Detach a profile from this model instance
-            parameters:
-              profileName:
-                name: profileName
-                type: String
-                required: true
-                unique: false
-            returns: Boolean
-            requires:
-              - Profile is currently attached
-            ensures:
-              - Profile is detached
-              - Profile attributes are no longer available
-          hasProfile:
-            description: Check if a profile is attached to this model instance
-            parameters:
-              profileName:
-                name: profileName
-                type: String
-                required: true
-                unique: false
-            returns: Boolean
-deployments: {}
-manifests: {}

package/assets/examples/10-api/diagram-architecture.mmd

@@ -1,10 +0,0 @@
-graph TB
-  subgraph "Client Layer"
-  end
-  subgraph "Controller Layer"
-  end
-  subgraph "Service Layer"
-  end
-  subgraph "Model Layer"
-    Product[(Product)]
-  end

package/assets/examples/10-api/diagram-er.mmd

@@ -1,10 +0,0 @@
-erDiagram
-  Product {
-    uuid id "NOT NULL"
-    string name "NOT NULL"
-    string summary
-    string price "NOT NULL"
-    boolean inStock
-    string category "NOT NULL"
-    string contactEmail
-  }

package/assets/examples/10-api/documentation.html

@@ -1,104 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>SpecVerseFundamentals Documentation</title>
-    <style>
-        body {
-            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
-            line-height: 1.6;
-            color: #333;
-            max-width: 900px;
-            margin: 0 auto;
-            padding: 20px;
-        }
-        h1, h2, h3, h4, h5 { 
-            color: #2c3e50;
-            margin-top: 1.5em;
-        }
-        h1 { border-bottom: 2px solid #3498db; padding-bottom: 0.3em; }
-        h2 { border-bottom: 1px solid #ecf0f1; padding-bottom: 0.2em; }
-        table {
-            border-collapse: collapse;
-            width: 100%;
-            margin: 1em 0;
-        }
-        th, td {
-            border: 1px solid #ddd;
-            padding: 8px;
-            text-align: left;
-        }
-        th {
-            background-color: #f8f9fa;
-            font-weight: bold;
-        }
-        code {
-            background-color: #f4f4f4;
-            padding: 2px 4px;
-            border-radius: 3px;
-            font-family: 'Consolas', 'Monaco', 'Courier New', monospace;
-        }
-        pre {
-            background-color: #f4f4f4;
-            padding: 1em;
-            border-radius: 5px;
-            overflow-x: auto;
-        }
-        .toc {
-            background-color: #f8f9fa;
-            padding: 1em;
-            border-radius: 5px;
-            margin: 1em 0;
-        }
-        .toc ul {
-            list-style-type: none;
-            padding-left: 1em;
-        }
-        .toc a {
-            text-decoration: none;
-            color: #3498db;
-        }
-        .toc a:hover {
-            text-decoration: underline;
-        }
-        hr {
-            border: none;
-            border-top: 1px solid #ecf0f1;
-            margin: 2em 0;
-        }
-    </style>
-</head>
-<body>
-    <h1>SpecVerseFundamentals</h1><p>Example 01-01: Basic model definition with attributes</p><p><strong>Version:</strong> 1.0.0  
-<strong>Generated:</strong> 2026-03-23T18:22:33.405Z</p><h2>Table of Contents</h2><ul><li><a href="#overview">Overview</a></li>
-<li><a href="#models">Models</a></li>
-  - <a href="#product">Product</a></p><h2>Overview</h2><h3>Component Statistics</h3><p><tr><td>Component Type</td><td>Count</td></tr>
-
-<tr><td>Models</td><td>1</td></tr>
-<tr><td>Controllers</td><td>0</td></tr>
-<tr><td>Services</td><td>0</td></tr>
-<tr><td>Views</td><td>0</td></tr>
-<tr><td>Events</td><td>0</td></tr></p><h3>Imports</h3><p>
-<h3>Exports</h3><p><strong>SpecVerseFundamentals:</strong>
-<li><strong>models:</strong> Product</li></ul><h2>Models</h2><h3>Product</h3><p>Simple product with basic attributes</p><h4>Attributes</h4><p><tr><td>Name</td><td>Type</td><td>Required</td><td>Unique</td><td>Description</td></tr>
-
-<tr><td>id</td><td>UUID</td><td>✓</td></tr>
-<tr><td>name</td><td>String</td><td>✓</td></tr>
-<tr><td>summary</td><td>String</td></tr>
-<tr><td>price</td><td>Money</td><td>✓</td></tr>
-<tr><td>inStock</td><td>Boolean</td><td>Default: true</td></tr>
-<tr><td>category</td><td>String</td><td>✓</td></tr>
-<tr><td>contactEmail</td><td>Email</td></tr></p><h4>Behaviors</h4><h5>attachProfile</h5><p>Attach a profile to this model instance</p><p><strong>Parameters:</strong>
-<li><code>profileName</code>: String (required)</li></ul><p><strong>Returns:</strong> Boolean</p><p><strong>Preconditions:</strong>
-<li>Profile exists and is compatible with this model</li></ul><p><strong>Postconditions:</strong>
-<li>Profile is attached</li>
-<li>Profile attributes are available</li></ul><h5>detachProfile</h5><p>Detach a profile from this model instance</p><p><strong>Parameters:</strong>
-<li><code>profileName</code>: String (required)</li></ul><p><strong>Returns:</strong> Boolean</p><p><strong>Preconditions:</strong>
-<li>Profile is currently attached</li></ul><p><strong>Postconditions:</strong>
-<li>Profile is detached</li>
-<li>Profile attributes are no longer available</li></ul><h5>hasProfile</h5><p>Check if a profile is attached to this model instance</p><p><strong>Parameters:</strong>
-<li><code>profileName</code>: String (required)</li></ul><p><strong>Returns:</strong> Boolean</p><p>---
-</p>
-</body>
-</html>