@specverse/engine-realize 3.5.3

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

@@ -0,0 +1,194 @@
+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

@@ -0,0 +1,96 @@
+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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,104 @@
+<!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>

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

@@ -0,0 +1,95 @@
+# SpecVerseFundamentals
+
+Example 01-01: Basic model definition with attributes
+
+**Version:** 1.0.0  
+**Generated:** 2026-03-23T18:22:33.403Z
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Models](#models)
+  - [Product](#product)
+
+## Overview
+
+### Component Statistics
+
+| Component Type | Count |
+|----------------|-------|
+| Models | 1 |
+| Controllers | 0 |
+| Services | 0 |
+| Views | 0 |
+| Events | 0 |
+
+### Imports
+
+
+### Exports
+
+**SpecVerseFundamentals:**
+- **models:** Product
+
+## Models
+
+### Product
+
+Simple product with basic attributes
+
+#### Attributes
+
+| Name | Type | Required | Unique | Description |
+|------|------|----------|--------|-------------|
+| id | UUID | ✓ |  |  |
+| name | String | ✓ |  |  |
+| summary | String |  |  |  |
+| price | Money | ✓ |  |  |
+| inStock | Boolean |  |  | Default: true |
+| category | String | ✓ |  |  |
+| contactEmail | Email |  |  |  |
+
+#### Behaviors
+
+##### attachProfile
+
+Attach a profile to this model instance
+
+**Parameters:**
+- `profileName`: String (required)
+
+**Returns:** Boolean
+
+**Preconditions:**
+- Profile exists and is compatible with this model
+
+**Postconditions:**
+- Profile is attached
+- Profile attributes are available
+
+##### detachProfile
+
+Detach a profile from this model instance
+
+**Parameters:**
+- `profileName`: String (required)
+
+**Returns:** Boolean
+
+**Preconditions:**
+- Profile is currently attached
+
+**Postconditions:**
+- Profile is detached
+- Profile attributes are no longer available
+
+##### hasProfile
+
+Check if a profile is attached to this model instance
+
+**Parameters:**
+- `profileName`: String (required)
+
+**Returns:** Boolean
+
+---

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

@@ -0,0 +1,7 @@
+name: GeneratedComponent
+version: 3.1.0
+controllers: {}
+services: {}
+events: {}
+views: {}
+models: {}

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

@@ -0,0 +1,89 @@
+# API Integration Examples Metadata
+category: "api"
+title: "SpecVerse API Integration"
+description: "Comprehensive examples for programmatic integration of SpecVerse in TypeScript and JavaScript applications"
+targetAudience: "developers"
+estimatedTime: "2-3 hours"
+
+learningObjectives:
+  - "Master the SpecVerse programmatic API for parsing and validation"
+  - "Integrate AI inference engine into applications"
+  - "Generate UML diagrams and documentation programmatically"
+  - "Handle errors and edge cases in API integration"
+  - "Test and validate API integrations"
+
+examples:
+  - id: "09-01-usage-example"
+    title: "Comprehensive API Usage"
+    description: "Complete workflow examples showing all SpecVerse API capabilities"
+    concepts: ["api", "parsing", "inference", "generation", "integration"]
+    prerequisites: ["basic-javascript", "nodejs"]
+    difficulty: "intermediate"
+    estimatedTime: "45 minutes"
+    formats: ["js", "ts"]
+    learningObjectives:
+      - "Parse and validate SpecVerse specifications programmatically"
+      - "Use AI inference engine to enhance specifications"
+      - "Generate UML diagrams and documentation"
+      - "Handle parsing and validation errors"
+    specverseFeatures: ["Parser API", "Inference Engine", "Generators", "Error Handling"]
+    realWorldUseCase: "Build tools, web applications, automated processing pipelines"
+
+  - id: "09-02-workflow-test"
+    title: "End-to-End API Testing"
+    description: "Focused workflow test for CI/CD and production validation"
+    concepts: ["testing", "ci-cd", "validation", "automation"]
+    prerequisites: ["api-basics"]
+    difficulty: "intermediate" 
+    estimatedTime: "30 minutes"
+    formats: ["js"]
+    learningObjectives:
+      - "Create automated API tests for CI/CD pipelines"
+      - "Validate API functionality with embedded specifications"
+      - "Handle success/failure scenarios appropriately"
+    specverseFeatures: ["API Testing", "Validation", "CI/CD Integration"]
+    realWorldUseCase: "Automated testing, build pipelines, API health checks"
+
+  - id: "09-03-package-integration"
+    title: "Package Integration Testing"
+    description: "Validate complete npm package installation and API functionality"
+    concepts: ["npm", "package-testing", "integration", "real-world-usage"]
+    prerequisites: ["api-basics", "npm-knowledge"]
+    difficulty: "advanced"
+    estimatedTime: "45 minutes"
+    formats: ["js"]
+    learningObjectives:
+      - "Test complete package installation workflow"
+      - "Validate API functionality in real npm environment"
+      - "Ensure package integrity and completeness"
+    specverseFeatures: ["Package Distribution", "API Validation", "Integration Testing"]
+    realWorldUseCase: "Release validation, package testing, integration verification"
+
+usagePatterns:
+  webApplications:
+    description: "Integration into React, Vue, Angular applications"
+    examples: ["React component generation", "Vue template processing", "Angular service integration"]
+  
+  buildTools:
+    description: "webpack, vite, rollup plugin integration"
+    examples: ["Build-time specification processing", "Asset generation", "Plugin development"]
+  
+  apiServices:
+    description: "Express, Fastify, Koa API endpoint integration"
+    examples: ["Specification validation endpoints", "API generation services", "Documentation APIs"]
+  
+  cliTools:
+    description: "Custom CLI tool development"
+    examples: ["Custom specification processors", "Domain-specific tools", "Workflow automation"]
+
+performanceConsiderations:
+  parsing: "Sub-5ms for typical specifications"
+  inference: "Optimized rule processing engine"
+  memory: "Efficient caching and resource management"
+  concurrency: "Thread-safe for concurrent processing"
+
+nextSteps:
+  - "Integrate SpecVerse into your project using these patterns"
+  - "Customize examples for your specific use case"
+  - "Use workflow-test.js patterns for production validation" 
+  - "Explore advanced inference engine configuration options"

package/assets/examples/10-api/openapi.json

@@ -0,0 +1,61 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "SpecVerseFundamentals",
+    "description": "Example 01-01: Basic model definition with attributes",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://api.example.com"
+    }
+  ],
+  "paths": {},
+  "components": {
+    "schemas": {
+      "Product": {
+        "type": "object",
+        "description": "Simple product with basic attributes",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": ""
+          },
+          "name": {
+            "type": "string",
+            "description": ""
+          },
+          "summary": {
+            "type": "string",
+            "description": ""
+          },
+          "price": {
+            "type": "string",
+            "description": ""
+          },
+          "inStock": {
+            "type": "boolean",
+            "description": "Default: true",
+            "default": "true"
+          },
+          "category": {
+            "type": "string",
+            "description": ""
+          },
+          "contactEmail": {
+            "type": "string",
+            "description": ""
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "price",
+          "category"
+        ]
+      }
+    },
+    "responses": {},
+    "parameters": {}
+  }
+}