rails-openapi-gen 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 862b4bda485ef4f20970eb00a11b6d9c7c52215b9013a4d5596fc2101914d48b
-  data.tar.gz: 9f34b642c0ce919ac0384e6ffdc9c0cfa6073f4ab33c827f599db0bcdbed597b
+  metadata.gz: 0d59044c5ff98fab8b4ca1e9de7dd53e71eea91ffa2d5a8d37f0acb9f335f059
+  data.tar.gz: cc88029ac40811d0181ca65892ea8c09dd43134dd08a2d668bcd0285e2003f3d
 SHA512:
-  metadata.gz: 1b1a0e43790fd0094a4831b0abb69c3646f849bcebc378329b0d156f248f9a393f1066f5d7ebb2a39b77247d666ab07df82e892537fe707a23072176e6b913f0
-  data.tar.gz: e9510642fbb5a8a37da2864778ea926bd1c0317b33700aa9299ce9ebfbe495a6443e8a61e0e265277a21c8efdc61669fd64f4a2231d8234739844c0b249c6022
+  metadata.gz: 2578b9fd575a89a3432ea01f64e86e8f4e6922343f606c8f246a092f5a7a6dfe8da98b47717159238982f0140377ebdfdf0dc90bac879ba2b14727782e5ca297
+  data.tar.gz: 0cc4b985a493cf04edb7d1cb689e24d244ac33572d457f7b0c8fea49d8562a2c778ee13c5972fe14ddecd09ba026ee943edcc2c5924c6585717ce4952b69eff7

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.0.3] - 2025-01-13
+
+### Added
+- Ruby 3.1 compatibility with intelligent fallback parsing system
+- Robust error handling for Parser gem version mismatches
+- Support for root array structures in Jbuilder templates
+- Component reference system for partials
+- Enhanced debug output with RAILS_OPENAPI_DEBUG environment variable
+
+### Fixed
+- Parser gem compatibility issues between Ruby 3.1.3 and 3.1.7
+- RuboCop compliance with all Lint rules enabled
+- Test failures related to boolean symbols and unused variables
+- Proper handling of nested partials and array structures
+- Component naming conflicts in test environments
+
+### Changed
+- Parser gem dependency updated to ~> 3.1.0 for better compatibility
+- Improved AST parsing with multiple fallback strategies
+- Enhanced error messages and debugging capabilities
+- Removed project-specific naming patterns from tests
+
+## [0.0.2] - Previous version
+
+### Initial features
+- Basic OpenAPI generation from Rails routes
+- Jbuilder template parsing with @openapi comments
+- Controller action detection
+- YAML output generation
+
+## [0.0.1] - Initial release
+
+### Features
+- Initial implementation of rails-openapi-gen
+- Basic route parsing
+- Simple Jbuilder template support

data/CLAUDE.md

@@ -6,12 +6,18 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Rails OpenAPI Gen is a Ruby gem that automatically generates OpenAPI 3.0 specifications from Rails applications. It uses AST parsing to analyze routes, controllers, and Jbuilder templates, relying on `# @openapi` comments as the source of truth for type information.
 
+**Requirements:**
+- Ruby 3.0 or higher
+- Rails 6.0 or higher
+- Parser gem 3.0+ for AST processing
+
 ## Development Commands
 
 **Testing:**
 ```bash
-rspec                    # Run all tests
-rspec spec/specific_spec.rb   # Run specific test file
+bundle exec rspec        # Run all tests (required for parser gem dependencies)
+bundle exec rspec spec/specific_spec.rb   # Run specific test file
+rspec                    # Alternative (may have parser gem loading issues)
 ```
 
 **Linting:**
@@ -29,7 +35,7 @@ bin/rails openapi:check     # Check for missing comments and uncommitted changes
 
 **Gem Development:**
 ```bash
-bundle install          # Install dependencies
+bundle install          # Install dependencies (requires Ruby 3.0+)
 rake -T                 # List available rake tasks
 ```
 
@@ -66,19 +72,25 @@ rake -T                 # List available rake tasks
 The gem uses `# @openapi` comments in Jbuilder templates:
 
 ```ruby
-# @openapi id:integer required:true description:"User ID"
+# @openapi id:integer description:"User ID"
 json.id @user.id
 
 # @openapi status:string enum:[active,inactive] description:"User status"  
 json.status @user.status
+
+# @openapi email:string required:false description:"Optional email"
+json.email @user.email
 ```
 
 **Supported attributes:**
 - `type`: Data type (string, integer, boolean, number, array, object)
-- `required`: Whether field is required (true/false)
+- `required`: Whether field is required (false to make optional; defaults to required)
 - `enum`: Allowed values for the field
 - `description`: Human-readable description
 
+**Required Field Behavior:**
+Properties are **required by default** unless explicitly marked with `required:false`. This ensures comprehensive API documentation where all fields are documented as required unless specifically marked as optional.
+
 ### Conditional Rendering Support
 
 For properties that are conditionally rendered (e.g., inside `if` statements), use the `# @openapi conditional:true` comment:

data/README.md

@@ -2,6 +2,31 @@
 
 Rails comment-driven OpenAPI specification generator.
 
+## Requirements
+
+- **Ruby 3.0 or higher**
+- **Rails 6.0 or higher**
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails-openapi-gen'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install rails-openapi-gen
+```
+
 ## Overview
 
 rails-openapi-gen analyzes your Rails application's routes.rb, controllers, and jbuilder templates to automatically generate OpenAPI documentation. It uses AST parsing to extract JSON structure and relies on `# @openapi` comments for accurate type information.

data/lib/rails-openapi-gen/ast_nodes/array_node.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module RailsOpenapiGen::AstNodes
+  # Represents an array node in Jbuilder template (json.array! or json.property @collection)
+  class ArrayNode < BaseNode
+    attr_reader :property_name, :comment_data, :is_conditional, :is_root_array
+
+    def initialize(property_name: nil, comment_data: nil, is_conditional: false, is_root_array: false, parent: nil, metadata: {})
+      super(parent: parent, metadata: metadata)
+      @property_name = property_name || (is_root_array ? 'items' : nil)
+      @comment_data = comment_data || CommentData.new(type: 'array')
+      @is_conditional = is_conditional
+      @is_root_array = is_root_array
+    end
+
+    # Add an item property to this array
+    # @param item_node [BaseNode] Item node to add
+    # @return [BaseNode] The added item node
+    def add_item(item_node)
+      add_child(item_node)
+    end
+
+    # Get all item properties in this array
+    # @return [Array<BaseNode>] Array item nodes
+    def items
+      @children
+    end
+
+    # Check if this array is required in OpenAPI schema
+    # @return [Boolean] True if array is required
+    def required?
+      @comment_data.required? && !@is_conditional
+    end
+
+    # Check if this array is optional in OpenAPI schema
+    # @return [Boolean] True if array is optional
+    def optional?
+      !required?
+    end
+
+    # Get the OpenAPI type for array items
+    # @return [String] OpenAPI type for items
+    def item_type
+      return 'object' if items.any?
+
+      # Check comment data for item type specification
+      if @comment_data.items
+        case @comment_data.items
+        when Hash
+          @comment_data.items[:type] || 'object'
+        when String
+          @comment_data.items
+        else
+          'object'
+        end
+      else
+        'object'
+      end
+    end
+
+    # Get the description for this array
+    # @return [String, nil] Array description
+    def description
+      @comment_data.description
+    end
+
+    # Check if this is a root array (json.array! at template root)
+    # @return [Boolean] True if this is a root array
+    def root_array?
+      @is_root_array
+    end
+
+    # Convert to hash representation
+    # @return [Hash] Hash representation
+    def to_h
+      items_hash = items.map { |item| item.respond_to?(:to_h) ? item.to_h : item }
+      super.merge(
+        property_name: @property_name,
+        comment_data: @comment_data&.to_h,
+        is_conditional: @is_conditional,
+        is_root_array: @is_root_array,
+        required: required?,
+        openapi_type: 'array',
+        item_type: item_type,
+        description: description,
+        items: items_hash,
+        # Backward compatibility - also provide array_item_properties for Generator
+        array_item_properties: items_hash,
+        # Backward compatibility - also provide is_array_root for Generator
+        is_array_root: @is_root_array
+      ).compact
+    end
+
+    # Accept visitor for visitor pattern
+    # @param visitor [Object] Visitor object
+    # @return [Object] Result from visitor
+    def accept(visitor)
+      visitor.visit_array(self)
+    end
+  end
+end

data/lib/rails-openapi-gen/ast_nodes/base_node.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module RailsOpenapiGen
+  module AstNodes
+    # Base class for all AST nodes in the Jbuilder parser
+    # Provides common interface and basic functionality for tree structure
+    class BaseNode
+      attr_accessor :parent
+      attr_reader :children, :metadata
+
+      def initialize(parent: nil, metadata: {})
+        @parent = parent
+        @children = []
+        @metadata = metadata
+      end
+
+      # Add a child node to this node
+      # @param child [BaseNode] Child node to add
+      # @return [BaseNode] The added child node
+      def add_child(child)
+        child.parent = self if child.respond_to?(:parent=)
+        @children << child
+        child
+      end
+
+      # Remove a child node from this node
+      # @param child [BaseNode] Child node to remove
+      # @return [BaseNode, nil] The removed child node or nil
+      def remove_child(child)
+        @children.delete(child)
+      end
+
+      # Get all descendants (children and their children recursively)
+      # @return [Array<BaseNode>] All descendant nodes
+      def descendants
+        result = []
+        @children.each do |child|
+          result << child
+          result.concat(child.descendants) if child.respond_to?(:descendants)
+        end
+        result
+      end
+
+      # Check if this node is a leaf (has no children)
+      # @return [Boolean] True if this node has no children
+      def leaf?
+        @children.empty?
+      end
+
+      # Check if this node is the root (has no parent)
+      # @return [Boolean] True if this node has no parent
+      def root?
+        @parent.nil?
+      end
+
+      # Get the root node of the tree
+      # @return [BaseNode] The root node
+      def root
+        return self if root?
+
+        @parent.root
+      end
+
+      # Convert node to hash representation
+      # @return [Hash] Hash representation of the node
+      def to_h
+        {
+          node_type: self.class.name.split('::').last.downcase.gsub('node', ''),
+          metadata: @metadata,
+          children: @children.map { |child| child.respond_to?(:to_h) ? child.to_h : child }
+        }
+      end
+
+      # Accept a visitor for visitor pattern implementation
+      # @param visitor [Object] Visitor object
+      # @return [Object] Result from visitor
+      def accept(visitor)
+        visitor.visit(self)
+      end
+
+      # Pretty print the AST tree structure for debugging
+      # @param indent [Integer] Current indentation level
+      # @return [void]
+      def pretty_print(indent = 0)
+        pad = '  ' * indent
+        node_name = self.class.name.split('::').last
+        summary = summary_attributes
+
+        puts "#{pad}#{tree_symbol(indent)} #{node_name}#{summary.empty? ? '' : " (#{summary})"}"
+
+        @children.each_with_index do |child, _index|
+          child.pretty_print(indent + 1) if child.respond_to?(:pretty_print)
+        end
+      end
+
+      # Print just this node without children
+      # @return [String] Single line representation
+      def debug_line
+        node_name = self.class.name.split('::').last
+        summary = summary_attributes
+        "#{node_name}#{summary.empty? ? '' : " (#{summary})"}"
+      end
+
+      # Generate summary attributes for debugging display
+      # @return [String] Summary of key attributes
+      def summary_attributes
+        attrs = []
+
+        # Common attributes that most nodes might have
+        attrs << "name=#{property_name}" if respond_to?(:property_name) && property_name
+
+        if respond_to?(:comment_data) && comment_data
+          attrs << "type=#{comment_data.type}" if comment_data.type
+          attrs << "required=#{comment_data.required?}" if comment_data.respond_to?(:required?)
+          attrs << "desc=#{comment_data.description[0..30]}..." if comment_data.description && comment_data.description.length > 30
+          attrs << "desc=#{comment_data.description}" if comment_data.description && comment_data.description.length <= 30
+        end
+
+        attrs << "children=#{@children.size}" if @children.size > 0
+        attrs << "conditional" if respond_to?(:is_conditional) && is_conditional
+
+        attrs.join(', ')
+      end
+
+      private
+
+      # Generate tree symbol for pretty printing
+      # @param indent [Integer] Current indentation level
+      # @return [String] Tree symbol (├── or └──)
+      def tree_symbol(indent)
+        return '└─' if indent == 0
+
+        '├─'
+      end
+
+      # No longer need protected attr_writer since we have attr_accessor above
+    end
+  end
+end

data/lib/rails-openapi-gen/ast_nodes/comment_data.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module RailsOpenapiGen::AstNodes
+  # Represents comment data parsed from @openapi annotations
+  # Encapsulates all OpenAPI-related metadata extracted from comments
+  class CommentData
+    attr_reader :type, :description, :required, :enum, :field_name, :items, :conditional, :format, :example
+
+    def initialize(
+      type: nil,
+      description: nil,
+      required: true,
+      enum: nil,
+      field_name: nil,
+      items: nil,
+      conditional: false,
+      format: nil,
+      example: nil
+    )
+      @type = type
+      @description = description
+      @required = required
+      @enum = enum
+      @field_name = field_name
+      @items = items
+      @conditional = conditional
+      @format = format
+      @example = example
+    end
+
+    # Check if the property is required
+    # @return [Boolean] True if property is required
+    def required?
+      @required != false && @required != 'false'
+    end
+
+    # Check if the property is optional
+    # @return [Boolean] True if property is optional
+    def optional?
+      !required?
+    end
+
+    # Check if the property is conditional
+    # @return [Boolean] True if property is conditional
+    def conditional?
+      @conditional == true || @conditional == 'true'
+    end
+
+    # Check if the property has enum values
+    # @return [Boolean] True if property has enum values
+    def has_enum?
+      @enum && !@enum.empty?
+    end
+
+    # Check if the property has a specific format
+    # @return [Boolean] True if property has format specification
+    def has_format?
+      # Auto-detect format from invalid types that were converted
+      return true if auto_format_from_invalid_type
+
+      @format && !@format.empty?
+    end
+
+    # Check if the property has an example
+    # @return [Boolean] True if property has example
+    def has_example?
+      @example
+    end
+
+    # Get OpenAPI type, defaulting to string if not specified
+    # @return [String] OpenAPI type
+    def openapi_type
+      # Handle common invalid types and auto-correct them
+      case @type
+      when 'date-time', 'datetime', 'date', 'time'
+        # These are not valid OpenAPI types, should be string with format
+        'string'
+      else
+        @type || 'string'
+      end
+    end
+
+    # Get format for the property, including auto-detected formats
+    # @return [String, nil] Format specification
+    def format_value
+      # Auto-detect format from invalid types that were converted
+      auto_format = auto_format_from_invalid_type
+      return auto_format if auto_format
+
+      @format
+    end
+
+    # Get items specification for arrays
+    # @return [Hash, nil] Items specification
+    def array_items
+      return nil unless @type == 'array'
+
+      @items || { 'type' => 'object' }
+    end
+
+    # Convert to hash representation suitable for OpenAPI schema
+    # @return [Hash] Hash representation
+    def to_openapi_schema
+      schema = { 'type' => openapi_type }
+      schema['description'] = @description if @description
+      schema['enum'] = @enum if has_enum?
+      schema['format'] = format_value if has_format?
+      schema['example'] = @example if has_example?
+      schema['items'] = array_items if @type == 'array' && array_items
+      schema
+    end
+
+    # Convert to hash representation for internal use
+    # @return [Hash] Hash representation
+    def to_h
+      {
+        type: @type,
+        description: @description,
+        required: @required,
+        enum: @enum,
+        field_name: @field_name,
+        items: @items,
+        conditional: @conditional,
+        format: @format,
+        example: @example
+      }.compact
+    end
+
+    # Merge with another CommentData, giving precedence to non-nil values
+    # @param other [CommentData] Other comment data to merge
+    # @return [CommentData] New merged comment data
+    def merge(other)
+      return self unless other.is_a?(CommentData)
+
+      CommentData.new(
+        type: other.type || @type,
+        description: other.description || @description,
+        required: other.required.nil? ? @required : other.required,
+        enum: other.enum || @enum,
+        field_name: other.field_name || @field_name,
+        items: other.items || @items,
+        conditional: other.conditional.nil? ? @conditional : other.conditional,
+        format: other.format || @format,
+        example: other.example || @example
+      )
+    end
+
+    # Create a copy with updated attributes
+    # @param attributes [Hash] Attributes to update
+    # @return [CommentData] New comment data with updated attributes
+    def with(**attributes)
+      CommentData.new(
+        type: attributes.fetch(:type, @type),
+        description: attributes.fetch(:description, @description),
+        required: attributes.fetch(:required, @required),
+        enum: attributes.fetch(:enum, @enum),
+        field_name: attributes.fetch(:field_name, @field_name),
+        items: attributes.fetch(:items, @items),
+        conditional: attributes.fetch(:conditional, @conditional),
+        format: attributes.fetch(:format, @format),
+        example: attributes.fetch(:example, @example)
+      )
+    end
+
+    private
+
+    # Auto-detect format from invalid types that were converted to string
+    # @return [String, nil] Format specification
+    def auto_format_from_invalid_type
+      case @type
+      when 'date-time', 'datetime'
+        'date-time'
+      when 'date'
+        'date'
+      when 'time'
+        'time'
+      end
+    end
+  end
+end