spec_forge 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b2d5790d4797a63b8fbad4dd296b9c9beb657b30a98bda5fab8ca7c635abd5a
-  data.tar.gz: b22a8f664dd676846e703f5312383c9c9b1b9cabab52b2cc3c8a8d28830490c0
+  metadata.gz: 7f8c38cb9ff50cb02ee74171a4d571ac411807b1dcce43edab0f28a757269b2f
+  data.tar.gz: 1595911a7a84d7712ddcc5bf0e2a08c0c30afce995ac02bb1372c1ae29ca7db0
 SHA512:
-  metadata.gz: 858e7dfd4546bc34e7dd8f899d99b5cf03d26cfbe9042f238de44566e2981a82bcd06803a0319f6d937d7c509dc3c02e8a962415c8e6fbb8e3c515c693c5e176
-  data.tar.gz: 3b246fda2d4bbbc5ce12fa0f683e27e1cb0e2950fe3b7c03b978f6d88662d1b65b0037b00931fe598415ee3d3c8477f7f76fd3f523547e061f86ac000e617d52
+  metadata.gz: 731ff8f0cc847010f38caab823c7d30c0d3d7083d4ea53de6ac46c19929c2c31ce698db787303c706ae6ee517dea396ef5ceb220732dd172050967404dd102af
+  data.tar.gz: 1a24dd8f84528427e30d105c4e358ca226b699e79a68a9ac2eb5385a974abb2acb27f8c8a3751e8c69a70001ef8d2ef3938ab06f9c81f1f041325b1b038923e1

data/CHANGELOG.md

@@ -15,7 +15,115 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Removed
 -->
 
-## [Unreleased]
+## [0.7.0] - 12025-06-22
+
+### Added
+
+#### 🚀 Documentation-First Architecture
+**The Big Picture**: SpecForge now generates OpenAPI documentation from your tests automatically!
+
+- **Primary Documentation Workflow**: New `docs` command (now the default!) generates OpenAPI specs from test execution
+  - Smart caching system with `--fresh` flag for forced regeneration
+  - Multiple output formats: YAML (default) or JSON via `--format`
+  - Custom output paths with `--output` option
+  - Built-in OpenAPI 3.0.4 validation with detailed, helpful error messages
+  - Optional validation skip with `--skip-validation` for faster iterations
+
+- **Live Documentation Server**: `spec_forge serve` command for immediate feedback
+  - Local web server with Swagger UI (default) or Redoc (`--ui redoc`)
+  - Configurable port with `--port` (defaults to 8080)
+  - Auto-generated HTML templates for both UI options
+  - Perfect for development and API review workflows
+
+- **Flexible Configuration System**:
+  - Directory-based config: `config/components/`, `config/paths/`, etc.
+  - Template-based initialization with sensible defaults
+  - Enhanced YAML merging with `$ref` support
+  - Full OpenAPI customization through configuration files
+
+#### 🧪 Enhanced Testing Capabilities
+
+- **HTTP Header Testing**: Comprehensive header validation
+  ```yaml
+  headers:
+    Content-Type: "application/json"
+    X-Request-ID: /^[0-9a-f-]{36}$/
+    Cache-Control:
+      matcher.and:
+      - matcher.include: "max-age="
+      - matcher.include: "private"
+  ```
+
+- **Flexible Store System**: Store anything, access everything
+  - OpenStruct-based entries for maximum flexibility
+  - Custom data via callbacks (config, metadata, computed values)
+  - Same familiar `store.id.attribute` syntax
+  - Perfect for complex test scenarios and feature flags
+
+- **Documentation Control**: Fine-grained control over what gets documented
+  - New `documentation: true/false` attribute for specs and expectations
+  - Exclude test-only scenarios from API docs while keeping functionality
+
+#### ⚙️ Architecture Improvements
+
+- **YAML-Driven Normalizers**: Configuration over code
+  - Structure definitions in `lib/spec_forge/normalizers/*.yml`
+  - Powerful `reference:` system for reusable components
+  - Wildcard support (`*`) for catch-all schemas
+  - Centralized validation logic in dedicated module
+
+- **Enhanced CLI Experience**:
+  - Improved `init` command with `--skip-openapi` and `--skip-factories` flags
+  - Better help text and examples throughout
+  - Clearer error messages with actionable context
+
+- **Developer Utilities**:
+  - `Array#to_merged_h` for cleaner hash merging
+  - Unified `.normalize!(input, using:)` API across normalizers
+  - Separated test preparation (`Runner.prepare`) from execution
+
+### Changed
+
+#### 🎯 User Experience Overhaul
+
+- **New Default Behavior**: `spec_forge` without arguments now shows help instead of running tests
+  - **Breaking Change**: Use `spec_forge docs` for documentation or `spec_forge run` for test-only execution
+  - Safer default that guides users to the right command for their needs
+
+- **Streamlined Commands**:
+  - Better command organization and help text
+  - Consistent flag naming across commands
+  - Enhanced error handling with helpful suggestions
+
+#### 🏗️ Internal Refactoring
+
+- **Normalizer Architecture**: YAML-based instead of class-heavy approach
+  - Consolidated shared definitions in `_shared.yml`
+  - Easier maintenance and extension
+  - Better error context with attribute path tracking
+
+- **Test Execution Pipeline**:
+  - Clean separation between test preparation and execution
+  - Enhanced RSpec adapter pattern
+  - Better reusability for documentation generation
+
+- **HTTP & Store Improvements**:
+  - Automatic header value string conversion
+  - Simplified store entry structure with OpenStruct flexibility
+  - Enhanced request/response handling
+
+### Removed
+
+- **Legacy Architecture**: Individual normalizer class files (replaced with YAML config)
+
+---
+
+**Migration Notes**:
+- Update any scripts using bare `spec_forge` - now shows help instead of running tests
+- Use `spec_forge docs` for documentation generation or `spec_forge run` for testing
+- Store access patterns remain the same, but internal structure is more flexible
+
+## [0.6.0] - 12025-03-25
 
 ### Added
 
@@ -231,7 +339,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial commit
 
-[unreleased]: https://github.com/itsthedevman/spec_forge/compare/v0.5.0...HEAD
+[unreleased]: https://github.com/itsthedevman/spec_forge/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/itsthedevman/spec_forge/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/itsthedevman/spec_forge/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/itsthedevman/spec_forge/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/itsthedevman/spec_forge/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/itsthedevman/spec_forge/compare/v0.3.0...v0.3.2

data/README.md

@@ -6,7 +6,7 @@
 
 > Note: The code in this repository represents the latest development version with new features and improvements that are being prepared for future releases. For the current stable version, check out [v0.6.0](https://github.com/itsthedevman/spec_forge/releases/tag/v0.6.0) on GitHub releases.
 
-Write API tests in YAML that read like documentation:
+Write API tests in YAML that read like documentation and generate OpenAPI specifications:
 
 ```yaml
 show_user:
@@ -25,22 +25,39 @@ show_user:
           matcher.and:
           - kind_of.string
           - /@/
+      headers:
+        Content-Type: "application/json"
+        X-Request-ID: /^[0-9a-f-]{36}$/
 ```
 
-That's a complete test. No Ruby code, no configuration files, no HTTP client setup - just a clear description of what you're testing. Under the hood, you get all the power of RSpec's matchers, Faker's data generation, and FactoryBot's test objects.
+That's a complete test that validates your API and creates OpenAPI documentation. No Ruby code, no configuration files, no HTTP client setup - just clear, executable specifications.
 
 ## Why SpecForge?
 
-1. **Living Documentation**: Your tests should serve as clear, readable documentation of your API's behavior.
-2. **Reduce Boilerplate**: Write tests without repetitive setup code and HTTP configuration.
-3. **Quick Setup**: Start testing APIs in minutes instead of spending hours on test infrastructure.
-4. **Gradual Adoption**: Use alongside your existing test suite, introducing it incrementally where it makes sense.
-5. **Developer & QA Collaboration**: Create a testing format that everyone can understand and maintain, regardless of Ruby expertise.
+**For Testing:**
+
+- **Reduce Boilerplate**: Write tests without repetitive setup code and HTTP configuration
+- **Quick Setup**: Start testing APIs in minutes instead of spending hours on test infrastructure
+- **Clear Syntax**: Tests that everyone can read and understand, regardless of Ruby expertise
+
+**For Documentation:**
+
+- **OpenAPI Generation**: Generate OpenAPI specifications from your test structure, with full customization through configuration files
+- **Living Documentation**: Your tests ensure the documentation always matches your actual API behavior
+- **Professional Output**: View your API docs in Swagger UI or Redoc with minimal setup
+
+**For Teams:**
+
+- **Developer & QA Collaboration**: Create specifications that both developers and QA can maintain
+- **Gradual Adoption**: Use alongside your existing test suite, introducing it incrementally where it makes sense
 
 ## Key Features
 
+- **Automatic Documentation Generation**: Transform tests into OpenAPI specifications with customizable configuration
+- **Live Documentation Server**: Local development server for viewing generated documentation
 - **YAML-Based Tests**: Write clear, declarative tests that read like documentation
 - **RSpec Integration**: Leverage all the power of RSpec matchers and expectations
+- **Header Testing**: Comprehensive HTTP header validation with compound matchers
 - **FactoryBot Integration**: Generate test data with FactoryBot integration
 - **Faker Integration**: Create realistic test data with Faker
 - **Variable System**: Define and reference variables for dynamic test data
@@ -49,6 +66,23 @@ That's a complete test. No Ruby code, no configuration files, no HTTP client set
 - **Global Variables**: Define shared configuration at the file level
 - **Callback System**: Hook into the test lifecycle using Ruby for setup, teardown, and much more!
 
+## Quick Start
+
+Get started with SpecForge in 3 commands:
+
+```bash
+# 1. Initialize SpecForge
+spec_forge init
+
+# 2. Create your first test
+spec_forge new spec users
+
+# 3. View your documentation
+spec_forge serve
+```
+
+Then visit `http://localhost:8080` to see your API documentation!
+
 ## When Not to Use SpecForge
 
 Consider alternatives when you need:
@@ -92,12 +126,103 @@ Create your first test:
 spec_forge new spec users
 ```
 
-Run your tests:
+Generate documentation (default command):
+
+```bash
+spec_forge
+```
+
+Or start the live documentation server:
+
+```bash
+spec_forge serve
+```
+
+Run tests only (no documentation):
 
 ```bash
 spec_forge run
 ```
 
+## Documentation Workflow
+
+SpecForge provides multiple ways to work with your API documentation:
+
+```bash
+# Generate OpenAPI specifications
+spec_forge docs                    # Smart caching
+spec_forge docs --fresh            # Force regeneration
+spec_forge docs --format json      # Output as JSON instead of YAML
+
+# View documentation in browser
+spec_forge serve                   # Generate if needed + serve
+spec_forge serve --fresh           # Force regeneration + serve
+spec_forge serve --ui redoc        # Use Redoc instead
+spec_forge serve --port 3001       # Custom port
+
+# Traditional testing
+spec_forge run                     # Pure testing mode
+spec_forge run users:show_user     # Run specific tests
+```
+
+## Example: Complete User API
+
+```yaml
+# spec_forge/specs/users.yml
+global:
+  variables:
+    admin_role: "admin"
+
+list_users:
+  path: /users
+  expectations:
+  - expect:
+      status: 200
+      headers:
+        Content-Type: "application/json"
+      json:
+        users:
+          matcher.have_size:
+            be.greater_than: 0
+
+create_user:
+  path: /users
+  method: POST
+  variables:
+    username: faker.internet.username
+    email: faker.internet.email
+  body:
+    name: variables.username
+    email: variables.email
+    role: global.variables.admin_role
+  store_as: new_user
+  expectations:
+  - expect:
+      status: 201
+      headers:
+        Location: /\/users\/\d+/
+      json:
+        id: kind_of.integer
+        name: variables.username
+        email: variables.email
+        role: global.variables.admin_role
+
+show_user:
+  path: /users/{id}
+  query:
+    id: store.new_user.body.id
+  expectations:
+  - expect:
+      status: 200
+      json:
+        id: store.new_user.body.id
+        name: store.new_user.body.name
+        email: store.new_user.body.email
+        role: global.variables.admin_role
+```
+
+This automatically generates a complete OpenAPI specification with all endpoints, request/response schemas, and examples!
+
 ## Documentation
 
 For comprehensive documentation, visit the [SpecForge Wiki](https://github.com/itsthedevman/spec_forge/wiki) which includes:

data/flake.lock

@@ -20,11 +20,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1742422364,
-        "narHash": "sha256-mNqIplmEohk5jRkqYqG19GA8MbQ/D4gQSK0Mu4LvfRQ=",
+        "lastModified": 1750365781,
+        "narHash": "sha256-XE/lFNhz5lsriMm/yjXkvSZz5DfvKJLUjsS6pP8EC50=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "a84ebe20c6bc2ecbcfb000a50776219f48d134cc",
+        "rev": "08f22084e6085d19bcfb4be30d1ca76ecb96fe54",
         "type": "github"
       },
       "original": {

data/flake.nix

@@ -1,5 +1,5 @@
 {
-  description = "Ruby 3.4.2 development environment";
+  description = "Ruby 3.2 development environment";
 
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
@@ -20,8 +20,8 @@
       {
         devShells.default = pkgs.mkShell {
           buildInputs = with pkgs; [
-            (ruby_3_4.override {
-              jemallocSupport = true;
+            (ruby_3_2.override {
+              jemallocSupport = false;
               docSupport = false;
             })
 

data/lib/spec_forge/attribute/factory.rb

@@ -80,7 +80,7 @@ module SpecForge
         super
 
         # Check the arguments before preparing them
-        arguments[:keyword] = Normalizer.normalize_factory_reference!(arguments[:keyword])
+        arguments[:keyword] = Normalizer.normalize!(arguments[:keyword], using: :factory_reference)
 
         prepare_arguments!
       end

data/lib/spec_forge/callbacks.rb

@@ -36,6 +36,15 @@ module SpecForge
         instance[name.to_s] = block
       end
 
+      #
+      # Deregisters a callback
+      #
+      # @param name [String, Symbol] The name of the callback
+      #
+      def deregister(name)
+        instance.delete(name.to_s)
+      end
+
       #
       # Checks if a callback is registered for the given event
       #

data/lib/spec_forge/cli/docs/generate.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class CLI
+    class Docs < Command
+      #
+      # Shared functionality for generating OpenAPI documentation
+      #
+      # This module contains the core logic for running tests, extracting endpoint
+      # data, and generating OpenAPI specifications. It's used by both the Docs
+      # and Serve commands to avoid duplication.
+      #
+      module Generate
+        #
+        # Generates OpenAPI documentation and writes it to disk
+        #
+        # Runs the documentation generation pipeline: executes tests, extracts
+        # endpoint data, generates OpenAPI spec, validates it, and writes the
+        # output file in the specified format.
+        #
+        # @return [Pathname] The path to the generated documentation file
+        #
+        def generate_documentation
+          generator = Documentation::Generators::OpenAPI["3.0"]
+          output = generator.generate(use_cache: !options.fresh)
+
+          generator.validate!(output) unless options.skip_validation
+
+          # Determine output format and path
+          file_format = determine_file_format
+          file_path = determine_output_path(file_format)
+
+          content =
+            if file_format == "json"
+              JSON.pretty_generate(output)
+            else
+              output.to_yaml(stringify_names: true)
+            end
+
+          ::File.write(file_path, content)
+
+          file_path
+        end
+
+        private
+
+        def determine_file_format
+          file_format = options.format&.downcase || "yml"
+          validate_format!(file_format)
+
+          file_format
+        end
+
+        def validate_format!(format)
+          return if VALID_FORMATS.include?(format)
+
+          raise ArgumentError,
+            "Invalid format #{format.in_quotes}. Valid formats: #{VALID_FORMATS.join_map(", ", &:in_quotes)}"
+        end
+
+        def determine_output_path(format)
+          if options.output
+            Pathname.new(options.output)
+          else
+            extension = (format == "json") ? "json" : "yml"
+            SpecForge.openapi_path.join("generated", "openapi.#{extension}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/cli/docs.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "docs/generate"
+
+module SpecForge
+  class CLI
+    #
+    # Command for generating OpenAPI documentation from SpecForge tests
+    #
+    # Runs tests and extracts endpoint data to create OpenAPI specifications.
+    # Uses intelligent caching to avoid unnecessary test re-execution when
+    # specs haven't changed.
+    #
+    # @example Generate documentation
+    #   spec_forge docs
+    #
+    # @example Generate with fresh test run
+    #   spec_forge docs --fresh
+    #
+    class Docs < Command
+      include Docs::Generate
+
+      #
+      # Valid file formats for documentation output
+      #
+      # Supported formats include YAML variants (yml, yaml) and JSON.
+      # Used for validation when users specify the --format option.
+      #
+      # @api private
+      #
+      VALID_FORMATS = %w[yml yaml json].freeze
+
+      command_name "docs"
+      syntax "docs"
+      summary "Generate OpenAPI documentation from test results"
+
+      description <<~DESC
+        Generate OpenAPI documentation from test results.
+
+        Uses caching to avoid re-running tests unless specs
+        have changed. Output format can be YAML or JSON.
+      DESC
+
+      example "docs",
+        "Generates OpenAPI specifications from your tests using smart caching"
+
+      example "docs --fresh",
+        "Forces test re-execution and regenerates OpenAPI specs ignoring cache"
+
+      example "docs --format json",
+        "Generates OpenAPI specifications in JSON format instead of YAML"
+
+      example "docs --output ./build/api.yml",
+        "Generates OpenAPI specs to a custom file path"
+
+      example "docs --skip-validation",
+        "Generates documentation without validating the OpenAPI specification"
+
+      option "--fresh", "Re-run all tests ignoring cache"
+      option "--format=FORMAT", "Output format: yml/yaml or json (default: yml)"
+      option "--output=PATH", "Full file path for generated documentation"
+      option "--skip-validation", "Skip OpenAPI specification validation during generation"
+
+      #
+      # Generates OpenAPI documentation from tests
+      #
+      # Runs all SpecForge tests and creates OpenAPI specifications from the
+      # successful test results. This is the main entry point for the docs workflow.
+      #
+      # @return [void]
+      #
+      def call
+        # spec_forge/openapi/generated
+        generated_path = SpecForge.openapi_path.join("generated")
+        actions.empty_directory(generated_path, verbose: false)
+        actions.empty_directory(generated_path.join(".cache"), verbose: false)
+
+        file_path = generate_documentation
+
+        puts <<~STRING
+
+          ========================================
+          🎉 Success!
+          ========================================
+
+          Your OpenAPI specification is valid and ready to use.
+          Output written to: #{file_path.relative_path_from(SpecForge.forge_path)}
+        STRING
+      end
+    end
+  end
+end

data/lib/spec_forge/cli/init.rb

@@ -11,21 +11,53 @@ module SpecForge
     class Init < Command
       command_name "init"
       syntax "init"
-      summary "Initializes directory structure and configuration files"
+      summary "Set up your SpecForge project (creates folders and config files)"
+
+      description <<~DESC
+        Creates the SpecForge project structure.
+
+        Sets up:
+          • spec_forge/specs/ for test files
+          • spec_forge/factories/ for test data (optional)
+          • spec_forge/openapi/ for documentation config (optional)
+          • forge_helper.rb for configuration
+      DESC
+
+      option "--skip-openapi", "Skip generating the \"openapi\" directory"
+      option "--skip-factories", "Skip generating the \"factories\" directory"
 
       #
       # Creates the "spec_forge", "spec_forge/factories", and "spec_forge/specs" directories
       # Also creates the "spec_forge.rb" initialization file
       #
       def call
+        initialize_forge
+        initialize_openapi unless options.skip_openapi
+      end
+
+      private
+
+      def initialize_forge
         base_path = SpecForge.forge_path
-        actions.empty_directory "#{base_path}/factories"
-        actions.empty_directory "#{base_path}/specs"
+        actions.empty_directory(base_path.join("specs"))
+        actions.empty_directory(base_path.join("factories")) unless options.skip_factories
+        actions.template("forge_helper.rb.tt", base_path.join("forge_helper.rb"))
+      end
+
+      def initialize_openapi
+        # spec_forge/openapi
+        openapi_path = SpecForge.openapi_path
+        actions.empty_directory(openapi_path)
+
+        # spec_forge/openapi/config
+        config_path = openapi_path.join("config")
+
+        actions.empty_directory(config_path)
+        actions.empty_directory(config_path.join("paths")) # openapi/config/paths
+        actions.empty_directory(config_path.join("components")) # openapi/config/components
 
-        actions.template(
-          "forge_helper.tt",
-          SpecForge.root.join(base_path, "forge_helper.rb")
-        )
+        # openapi/config/openapi.yml
+        actions.template("openapi.yml.tt", config_path.join("openapi.yml"))
       end
     end
   end

data/lib/spec_forge/cli/new.rb

@@ -13,7 +13,17 @@ module SpecForge
     #
     class New < Command
       command_name "new"
-      summary "Create a new spec or factory"
+      summary "Create new test specs or data factories"
+
+      description <<~DESC
+        Generate new files from templates.
+
+        Types:
+          • spec - Creates YAML test files with common patterns
+          • factory - Creates FactoryBot factories for test data
+
+        Files are created in the appropriate spec_forge/ subdirectory.
+      DESC
 
       syntax "new <type> <name>"
 
@@ -51,7 +61,7 @@ module SpecForge
 
       def create_new_spec(name)
         actions.template(
-          "new_spec.tt",
+          "new_spec.yml.tt",
           SpecForge.forge_path.join("specs", "#{name}.yml"),
           context: Proxy.new(name).call
         )
@@ -59,7 +69,7 @@ module SpecForge
 
       def create_new_factory(name)
         actions.template(
-          "new_factory.tt",
+          "new_factory.yml.tt",
           SpecForge.forge_path.join("factories", "#{name}.yml"),
           context: Proxy.new(name).call
         )

data/lib/spec_forge/cli/run.rb

@@ -21,8 +21,18 @@ module SpecForge
       command_name "run"
       syntax "run [target]"
 
-      summary "Runs specs loaded from spec_forge/specs/"
-      description "Runs specs loaded from spec_forge/specs/. The optional target argument allows running specific files, specs, or expectations."
+      summary "Execute your API tests with smart filtering options"
+
+      description <<~DESC
+        Execute API tests with filtering options.
+
+        Target formats:
+          • file_name - Run all specs in a file
+          • file:spec - Run specific spec
+          • file:spec:"expectation" - Run individual expectation
+
+        Uses RSpec for execution with detailed error reporting.
+      DESC
 
       example "spec_forge run",
         "Run all specs in spec_forge/specs/"
@@ -39,8 +49,6 @@ module SpecForge
       example "spec_forge run users:create_user:\"POST /users - Create Admin\"",
         "Run the specific expectation named \"Create Admin\""
 
-      # option "-n", "--no-docs", "Do not generate OpenAPI documentation on completion"
-
       #
       # Loads and runs all specs, or a subset of specs based on the provided arguments
       #