pangea-core 0.2.0 → 0.3.0

data/vendor/bundle/ruby/3.3.0/gems/abstract-synthesizer-0.0.15/examples/README.md

@@ -0,0 +1,230 @@
+# Abstract Synthesizer Examples
+
+> **📋 Navigation**: [Main README](../README.md) | [Overview](../docs/overview.md) | [Usage Guide](../docs/usage.md) | **Examples**
+
+This directory contains comprehensive examples demonstrating the power and flexibility of Abstract Synthesizer across different domains. Each example is a complete, runnable demonstration showcasing real-world applications.
+
+## 📚 Quick Navigation
+
+- [🏗️ Infrastructure as Code](#️-infrastructure-as-code) - Kubernetes deployments
+- [🌐 API Configuration](#-api-configuration) - REST API route generation  
+- [⚙️ Build Systems](#️-build-systems) - CI/CD pipeline configuration
+- [📊 Configuration Management](#-configuration-management) - Application configuration with validation
+
+## 🏗️ Infrastructure as Code
+
+### [Kubernetes Deployment DSL](infrastructure/kubernetes_deployment.rb)
+
+Create declarative Kubernetes configurations with built-in validation:
+
+```ruby
+infrastructure = KubernetesInfrastructure.build do
+  deployment :web_app, :production do
+    image 'nginx:1.21'
+    replicas 3
+    container_port 80
+  end
+  
+  service :web_app, :production do
+    port 80
+    target_port 80
+    type 'LoadBalancer'
+  end
+end
+
+# Verify and generate YAML
+if infrastructure.verify_manifest[:valid]
+  puts infrastructure.to_kubernetes_yaml
+end
+```
+
+**Features demonstrated:**
+- Resource validation
+- Multi-environment support  
+- YAML generation
+- Manifest verification
+
+## 🌐 API Configuration
+
+### [REST API DSL](api/rest_api_dsl.rb)
+
+Define REST APIs declaratively with automatic route generation:
+
+```ruby
+api_config = RestAPIConfiguration.build do
+  namespace :api, :v1 do
+    middleware :authentication
+    middleware :rate_limiting, requests: 1000
+    
+    resource :users do
+      get :index, auth: true, cache: 300
+      post :create, validation: :UserSchema
+    end
+  end
+end
+
+# Generate Rails routes and OpenAPI spec
+puts api_config.to_rails_routes
+puts api_config.to_openapi.to_json
+```
+
+**Features demonstrated:**
+- Nested namespaces
+- Middleware configuration
+- Route generation for multiple frameworks
+- OpenAPI specification generation
+- Built-in validation
+
+## ⚙️ Build Systems
+
+### [CI/CD Pipeline DSL](build_system/ci_cd_pipeline.rb)
+
+Create complex build pipelines with dependency management:
+
+```ruby
+pipeline = CICDPipelineConfiguration.build do
+  pipeline :web_app, :ci do
+    stage :test do
+      task :unit_tests, command: 'rspec'
+      task :lint, command: 'rubocop'
+    end
+    
+    stage :deploy, depends_on: :test do
+      task :deploy_production,
+           command: 'kubectl apply -f k8s/',
+           condition: 'branch == main'
+    end
+  end
+end
+
+# Generate CI/CD configs for different platforms
+puts pipeline.to_github_actions.to_yaml
+puts pipeline.to_gitlab_ci.to_yaml
+puts pipeline.to_jenkinsfile
+```
+
+**Features demonstrated:**
+- Stage dependencies
+- Conditional execution
+- Multi-platform generation (GitHub Actions, GitLab CI, Jenkins)
+- Notification configuration
+- Artifact management
+
+## 📊 Configuration Management
+
+### [Application Configuration DSL](configuration_management/app_config_dsl.rb)
+
+Manage complex application configurations with validation and drift detection:
+
+```ruby
+config = ApplicationConfigurationManager.build(environment: :production) do
+  database :primary, :postgresql do
+    host ENV['PROD_DB_HOST']
+    ssl true
+    connection_pool 20
+  end
+  
+  security :authentication, :jwt do
+    secret ENV['JWT_SECRET']
+    expiry 3600
+  end
+  
+  feature :new_ui, :beta do
+    enabled true
+    rollout_percentage 25
+  end
+end
+
+# Comprehensive validation
+verification = config.verify_manifest
+puts "Valid: #{verification[:valid]}"
+puts "Errors: #{verification[:errors]}"
+puts "Warnings: #{verification[:warnings]}"
+
+# Generate deployment artifacts
+puts config.to_env_file        # Environment variables
+puts config.to_yaml           # YAML configuration
+puts config.generate_deployment_checklist  # Deployment checklist
+```
+
+**Features demonstrated:**
+- Environment-specific configurations
+- Multi-format output (ENV, YAML, JSON)
+- Comprehensive validation with warnings
+- Configuration drift detection
+- Deployment checklists
+- Security best practices validation
+
+## 🎯 Key Benefits Demonstrated
+
+### 1. **Declarative Over Imperative**
+All examples show how to declare *what* you want rather than *how* to achieve it.
+
+### 2. **Built-in Validation**
+Every DSL includes comprehensive validation that catches errors early.
+
+### 3. **Multi-Format Generation**
+Generate configuration files for different tools and platforms from a single source.
+
+### 4. **Verifiable Manifests**
+All configurations produce inspectable, immutable manifests for auditing.
+
+### 5. **Environment Awareness**
+Support for multiple environments with environment-specific validation.
+
+### 6. **Drift Detection**
+Compare desired state with actual state to detect configuration drift.
+
+## 🚀 Running the Examples
+
+Each example is a standalone Ruby script that can be executed directly:
+
+```bash
+# Run infrastructure example
+ruby examples/infrastructure/kubernetes_deployment.rb
+
+# Run API configuration example  
+ruby examples/api/rest_api_dsl.rb
+
+# Run build pipeline example
+ruby examples/build_system/ci_cd_pipeline.rb
+
+# Run configuration management example
+ruby examples/configuration_management/app_config_dsl.rb
+```
+
+## 🧩 Creating Your Own DSLs
+
+These examples serve as templates for creating your own domain-specific languages:
+
+1. **Define your domain vocabulary** (the `keys` array)
+2. **Create a wrapper class** with build methods
+3. **Add validation logic** specific to your domain
+4. **Implement output formats** for your target systems
+5. **Add verification methods** for configuration validation
+
+## 💡 Best Practices Demonstrated
+
+- **Single Responsibility**: Each DSL focuses on one domain
+- **Validation First**: Validate configurations before processing
+- **Immutable Outputs**: Generate immutable configuration artifacts
+- **Error Handling**: Provide clear, actionable error messages
+- **Documentation**: Self-documenting configuration through clear DSL syntax
+- **Testing**: Easy to test configurations without side effects
+
+These examples showcase how Abstract Synthesizer can standardize declarative programming patterns across Ruby applications while maintaining type safety, verifiability, and ease of use.
+
+---
+
+## 🔗 Related Documentation
+
+- **[Main README](../README.md)** - Project overview and getting started
+- **[Architecture Overview](../docs/overview.md)** - Technical implementation details
+- **[Usage Guide](../docs/usage.md)** - Comprehensive patterns and best practices
+
+## 💡 Next Steps
+
+1. **Run the examples** - Each file is executable: `ruby examples/infrastructure/kubernetes_deployment.rb`
+2. **Study the patterns** - Each example demonstrates different DSL design approaches
+3. **Build your own** - Use these as templates for your domain-specific DSLs
+4. **Contribute** - Share your own examples via pull requests!

data/vendor/bundle/ruby/3.3.0/gems/abstract-synthesizer-0.0.15/examples/api/rest_api_dsl.rb

@@ -0,0 +1,269 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'abstract-synthesizer'
+require 'json'
+
+# Example: REST API Configuration DSL
+# This demonstrates how abstract-synthesizer can create a declarative
+# language for API definition with automatic route generation and validation.
+
+class RestAPIConfiguration
+  def self.build(&block)
+    api_resources = %i[namespace resource middleware auth]
+    
+    synthesizer = SynthesizerFactory.create_synthesizer(
+      name: :rest_api_config,
+      keys: api_resources
+    )
+    
+    synthesizer.synthesize(&block)
+    
+    new(synthesizer.synthesis)
+  end
+  
+  def initialize(manifest)
+    @manifest = manifest
+  end
+  
+  def to_rails_routes
+    routes = []
+    routes << "Rails.application.routes.draw do"
+    
+    @manifest.each do |resource_type, resources|
+      case resource_type
+      when :namespace
+        routes.concat(generate_namespace_routes(resources))
+      when :resource
+        routes.concat(generate_resource_routes(resources))
+      end
+    end
+    
+    routes << "end"
+    routes.join("\n")
+  end
+  
+  def to_openapi
+    {
+      openapi: "3.0.0",
+      info: {
+        title: "Generated API",
+        version: "1.0.0"
+      },
+      paths: generate_openapi_paths
+    }
+  end
+  
+  def verify_manifest
+    errors = []
+    
+    @manifest.each do |resource_type, resources|
+      case resource_type
+      when :resource
+        resources.each do |resource_name, config|
+          config.each do |action, settings|
+            next unless %i[get post put delete patch].include?(action)
+            
+            if settings[:auth] && !has_auth_middleware?
+              errors << "#{resource_name}.#{action}: requires auth but no auth middleware defined"
+            end
+            
+            if settings[:validation] && !valid_schema?(settings[:validation])
+              errors << "#{resource_name}.#{action}: invalid validation schema"
+            end
+          end
+        end
+      end
+    end
+    
+    { valid: errors.empty?, errors: errors }
+  end
+  
+  private
+  
+  def generate_namespace_routes(namespaces)
+    routes = []
+    
+    namespaces.each do |namespace_name, versions|
+      versions.each do |version, config|
+        routes << "  namespace :#{namespace_name} do"
+        routes << "    namespace :#{version} do"
+        
+        if config[:middleware]
+          Array(config[:middleware]).each do |middleware|
+            routes << "      # Middleware: #{middleware}"
+          end
+        end
+        
+        if config[:resource]
+          config[:resource].each do |resource_name, resource_config|
+            routes << "      resources :#{resource_name} do"
+            
+            resource_config.each do |action, settings|
+              next unless %i[get post put delete patch].include?(action)
+              
+              auth_comment = settings[:auth] ? " # Requires authentication" : ""
+              cache_comment = settings[:cache] ? " # Cached for #{settings[:cache]}s" : ""
+              
+              routes << "        #{action} :#{action == :get ? 'index' : action}#{auth_comment}#{cache_comment}"
+            end
+            
+            routes << "      end"
+          end
+        end
+        
+        routes << "    end"
+        routes << "  end"
+      end
+    end
+    
+    routes
+  end
+  
+  def generate_resource_routes(resources)
+    routes = []
+    
+    resources.each do |resource_name, config|
+      routes << "  resources :#{resource_name} do"
+      
+      config.each do |action, settings|
+        next unless %i[get post put delete patch].include?(action)
+        
+        auth_comment = settings[:auth] ? " # Requires authentication" : ""
+        routes << "    #{action} :#{action}#{auth_comment}"
+      end
+      
+      routes << "  end"
+    end
+    
+    routes
+  end
+  
+  def generate_openapi_paths
+    paths = {}
+    
+    @manifest.each do |resource_type, resources|
+      case resource_type
+      when :namespace
+        resources.each do |namespace_name, versions|
+          versions.each do |version, config|
+            next unless config[:resource]
+            
+            config[:resource].each do |resource_name, resource_config|
+              path_base = "/#{namespace_name}/#{version}/#{resource_name}"
+              
+              resource_config.each do |action, settings|
+                next unless %i[get post put delete patch].include?(action)
+                
+                path = action == :get ? path_base : "#{path_base}/{id}"
+                paths[path] ||= {}
+                
+                paths[path][action.to_s] = {
+                  summary: "#{action.to_s.capitalize} #{resource_name}",
+                  security: settings[:auth] ? [{ bearerAuth: [] }] : nil,
+                  responses: generate_responses_for_action(action)
+                }.compact
+              end
+            end
+          end
+        end
+      end
+    end
+    
+    paths
+  end
+  
+  def generate_responses_for_action(action)
+    case action
+    when :get
+      {
+        "200" => { description: "Success" },
+        "404" => { description: "Not found" }
+      }
+    when :post
+      {
+        "201" => { description: "Created" },
+        "400" => { description: "Bad request" }
+      }
+    when :put, :patch
+      {
+        "200" => { description: "Updated" },
+        "404" => { description: "Not found" }
+      }
+    when :delete
+      {
+        "204" => { description: "Deleted" },
+        "404" => { description: "Not found" }
+      }
+    end
+  end
+  
+  def has_auth_middleware?
+    @manifest.dig(:middleware, :auth) || 
+    @manifest.values.any? { |v| v.is_a?(Hash) && v.values.any? { |vv| vv.is_a?(Hash) && vv[:middleware]&.include?(:authentication) } }
+  end
+  
+  def valid_schema?(schema)
+    schema.is_a?(Symbol) || schema.is_a?(String)
+  end
+end
+
+# Usage Example
+if __FILE__ == $0
+  api_config = RestAPIConfiguration.build do
+    namespace :api, :v1 do
+      middleware :authentication
+      middleware :rate_limiting, requests: 1000, window: 3600
+      middleware :cors
+      
+      resource :users do
+        get :index, auth: true, cache: 300
+        get :show, auth: true, cache: 600
+        post :create, validation: :UserCreateSchema
+        put :update, auth: true, validation: :UserUpdateSchema
+        delete :destroy, auth: true, admin_only: true
+      end
+      
+      resource :posts do
+        get :index, cache: 300, pagination: true
+        get :show, cache: 600
+        post :create, auth: true, validation: :PostCreateSchema
+        put :update, auth: true, validation: :PostUpdateSchema
+        delete :destroy, auth: true
+      end
+      
+      resource :comments do
+        get :index, cache: 120
+        post :create, auth: true, validation: :CommentSchema
+        delete :destroy, auth: true
+      end
+    end
+    
+    auth :jwt do
+      secret ENV['JWT_SECRET']
+      expiry 3600
+      refresh_token true
+    end
+    
+    middleware :global do
+      cors_enabled true
+      rate_limiting 10000
+      request_logging true
+    end
+  end
+  
+  # Verify the API configuration
+  verification = api_config.verify_manifest
+  if verification[:valid]
+    puts "✅ API configuration is valid"
+    
+    puts "\n--- Generated Rails Routes ---"
+    puts api_config.to_rails_routes
+    
+    puts "\n--- Generated OpenAPI Specification ---"
+    puts JSON.pretty_generate(api_config.to_openapi)
+  else
+    puts "❌ API configuration errors:"
+    verification[:errors].each { |error| puts "  - #{error}" }
+  end
+end