spec_forge 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b2d5790d4797a63b8fbad4dd296b9c9beb657b30a98bda5fab8ca7c635abd5a
-  data.tar.gz: b22a8f664dd676846e703f5312383c9c9b1b9cabab52b2cc3c8a8d28830490c0
+  metadata.gz: 9891353d8acd7d64ec4b2690e4e91d68c0d455913b8ca81c7f9e410859f51774
+  data.tar.gz: 7ff9aa712f7d21a75ae8a383175702ed8973b25e2935458bd75dd713f59b6fb3
 SHA512:
-  metadata.gz: 858e7dfd4546bc34e7dd8f899d99b5cf03d26cfbe9042f238de44566e2981a82bcd06803a0319f6d937d7c509dc3c02e8a962415c8e6fbb8e3c515c693c5e176
-  data.tar.gz: 3b246fda2d4bbbc5ce12fa0f683e27e1cb0e2950fe3b7c03b978f6d88662d1b65b0037b00931fe598415ee3d3c8477f7f76fd3f523547e061f86ac000e617d52
+  metadata.gz: 0637e96a8739579015af17ee0a6c8442b51c9fd189b2a220b7828ae68f0784760aad4d5312eabf450f18ee7e6db2789dad3fb55327cee0aa19f3a8e9b88be243
+  data.tar.gz: 3d10cc2cafb76d2d14b42e104fba62a5e8ec35d70cb92f6769e3fcde9611d9949d707fdc287caae52454e04d6542c507274e357bb38f41090792efa40e5d6436

data/CHANGELOG.md

@@ -15,7 +15,159 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Removed
 -->
 
-## [Unreleased]
+## [0.7.1] - 12025-10-08
+
+### Added
+
+- **Configuration alias**: `base_path` can now be used as an alias for `base_url` in spec definitions
+- **Improved debug configuration**: New `config.on_debug { }` block syntax for cleaner configuration
+
+  ```ruby
+  # New cleaner syntax (recommended)
+  config.on_debug { binding.pry }
+
+  # Old syntax still works with deprecation warning
+  config.on_debug = -> { binding.pry }
+  ```
+
+### Changed
+
+- **Fixed path handling in HTTP requests**: Paths with leading slashes (e.g., `/users`) now properly append to base URLs instead of replacing the entire path
+  - Previously, a base URL like `http://api.example.com/v1` with path `/users` would incorrectly resolve to `http://api.example.com/users`
+  - Now correctly resolves to `http://api.example.com/v1/users`
+  - This matches user expectations and common API patterns
+  - **Note**: If you need to replace the entire path, use absolute URLs like `https://api.example.com/users`
+- **CI/CD improvements**: Updated to GitHub Actions checkout v5 and streamlined Ruby version testing
+
+### Fixed
+
+- **Transform.join resolution**: Now properly generates fresh values instead of using cached results
+- **Test adapter optimization**: Removed JSON class validation check to allow matchers to be used
+
+### Deprecated
+
+- `config.on_debug = proc` syntax - use `config.on_debug { }` block syntax instead
+
+## [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
 
@@ -26,6 +178,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - `Context::Variables` for managing variables with overlay support
     - `Context::Store` for storing the results of the tests
 - Added support for defining and referencing global variables
+
   ```yaml
   global:
     variables:
@@ -37,13 +190,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     query:
       api_version: "global.variables.api_version"
   ```
+
 - Added compound matcher support via `matcher.and` for combining multiple matchers
   ```yaml
   email:
     matcher.and:
-    - kind_of.string
-    - /@/
-    - matcher.end_with: ".com"
+      - kind_of.string
+      - /@/
+      - matcher.end_with: ".com"
   ```
 - Added custom RSpec matcher `have_size` for checking an object's size via `matcher.have_size`
 - Added new `Loader` class for improved spec file processing
@@ -51,6 +205,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added normalizer for global context validation
 - Added line number tracking for specs and expectations
 - Added support for defining and referencing callbacks
+
   ```ruby
   # Configuration level
   SpecForge.configure do |config|
@@ -63,14 +218,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   # Module level (no aliases)
   SpecForge.register_callback("callback_name") { |context| }
   ```
+
   Once defined, callbacks can be referenced in spec files via the global context
+
   ```yaml
   global:
     callbacks:
-    - before: callback_name
-      after: cleanup_database_state
+      - before: callback_name
+        after: cleanup_database_state
   ```
+
 - Added support for storing and retrieving test data via the `store_as` directive and `store` attribute
+
   ```yaml
   create_user:
     path: "/users"
@@ -90,6 +249,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - expect:
         status: 200
   ```
+
 - Added `UndefinedMatcherError` for clearer error messaging when invalid matchers are used
 - Enhanced debugging capabilities with improved DebugProxy methods and store access
 - Added HTTP status descriptions for better error messages
@@ -140,7 +300,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   variables:
     users:
       factory.user:
-        size: 10  # Creates 10 user records
+        size: 10 # Creates 10 user records
   ```
   - All FactoryBot list methods now supported:
     - `create_list` (default)
@@ -199,6 +359,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Core Infrastructure
+
   - Configuration management
   - User input validation and normalization
   - Factory registration
@@ -208,11 +369,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Debugging tooling
 
 - CLI
+
   - Project initialization (`init`)
   - Spec/factory generation (`new`)
   - Test execution (`run`)
 
 - Attributes
+
   - Chainable attribute handling (through `Chainable`)
   - Expanded attribute handling (through `Parameterized`)
   - Factory (with chainable support) - `factories.`
@@ -231,7 +394,10 @@ 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.1...HEAD
+[0.7.1]: https://github.com/itsthedevman/spec_forge/compare/v0.7.0...v0.7.1
+[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

@@ -1,12 +1,12 @@
 # SpecForge
 
 [![Gem Version](https://badge.fury.io/rb/spec_forge.svg)](https://badge.fury.io/rb/spec_forge)
-![Ruby Version](https://img.shields.io/badge/ruby-3.3.7-ruby)
+![Ruby Version](https://img.shields.io/badge/ruby-3.2+-ruby)
 [![Tests](https://github.com/itsthedevman/spec_forge/actions/workflows/main.yml/badge.svg)](https://github.com/itsthedevman/spec_forge/actions/workflows/main.yml)
 
-> 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.
+> 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.7.1](https://github.com/itsthedevman/spec_forge/releases/tag/v0.7.1) 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/attribute/transform.rb

@@ -59,7 +59,7 @@ module SpecForge
         case function
         when "join"
           # Technically supports any attribute, but I ain't gonna test all them edge cases
-          arguments[:positional].resolved.join
+          arguments[:positional].resolve.join
         end
       end
     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