rails-autodoc 0.1.0

data/lib/rails_autodoc/registry.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  class OperationAnnotation
+    attr_accessor :controller,
+                  :action,
+                  :summary,
+                  :description,
+                  :tags,
+                  :deprecated,
+                  :body_params,
+                  :query_params,
+                  :responses,
+                  :security,
+                  :request_body_schema,
+                  :exclude
+
+    def initialize(controller:, action:)
+      @controller = controller
+      @action = action
+      @summary = nil
+      @description = nil
+      @tags = []
+      @deprecated = false
+      @body_params = []
+      @query_params = []
+      @responses = {}
+      @security = nil
+      @request_body_schema = nil
+      @exclude = false
+    end
+
+    def operation_id
+      "#{controller.name.underscore.tr('/', '_')}_#{action}"
+    end
+  end
+
+  class Registry
+    def initialize
+      @annotations = {}
+    end
+
+    def register(controller, action, &block)
+      key = annotation_key(controller, action)
+      annotation = (@annotations[key] ||= OperationAnnotation.new(
+        controller: controller,
+        action: action
+      ))
+      DSL::ControllerExtensions::AnnotationBuilder.new(annotation).instance_eval(&block)
+      annotation
+    end
+
+    def find(controller, action)
+      @annotations[annotation_key(controller, action)]
+    end
+
+    def all
+      @annotations.values
+    end
+
+    def clear!
+      @annotations.clear
+    end
+
+    private
+
+    def annotation_key(controller, action)
+      "#{controller.name}##{action}"
+    end
+  end
+end

data/lib/rails_autodoc/response_inferencer.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "parser/current"
+
+module RailsAutodoc
+  class ResponseInferencer
+    include AstTraversal
+
+    ResponseHint = Struct.new(:status, :schema_ref, :schema, :description, keyword_init: true)
+
+    DEFAULT_STATUS = {
+      "GET" => "200",
+      "POST" => "201",
+      "PUT" => "200",
+      "PATCH" => "200",
+      "DELETE" => "204"
+    }.freeze
+
+    def initialize(source_path:, class_name:, serializer_registry: Serializers::Registry.new)
+      @source_path = source_path
+      @class_name = class_name
+      @serializer_registry = serializer_registry
+      @buffer, = Parser::CurrentRuby.parse_file(source_path)
+    end
+
+    def responses_for_action(action_name, verb: "GET")
+      action_node = find_action_node(action_name)
+      hints = action_node ? extract_render_hints(action_node) : []
+
+      hints << default_response(verb) if hints.empty?
+
+      hints
+    end
+
+    private
+
+    def class_node
+      @class_node ||= find_class_node(@buffer, class_name: @class_name)
+    end
+
+    def find_action_node(action_name)
+      each_method_definition(class_node) do |child|
+        next unless child.type == :def
+
+        return child if child.children[0].to_s == action_name.to_s
+      end
+      nil
+    end
+
+    def extract_render_hints(action_node)
+      hints = []
+      walk_nodes(action_node) do |node|
+        next unless node.type == :send
+
+        if node.children[1] == :render
+          hint = build_hint_from_render(node)
+          hints << hint if hint
+        elsif node.children[1] == :head
+          status = normalize_status(node.children[2])
+          hints << ResponseHint.new(status: status, schema: nil, description: "No content")
+        end
+      end
+      hints
+    end
+
+    def build_hint_from_render(node)
+      status = "200"
+      schema_ref = nil
+      schema = { type: "object" }
+
+      node.children[2..].each do |arg|
+        next unless arg
+
+        next unless arg.type == :hash
+
+        each_hash_pair(arg) do |key, value|
+          case literal_value(key)
+          when :json
+            schema_ref, schema = infer_json_schema(value)
+          when :status
+            status = normalize_status(value)
+          end
+        end
+      end
+
+      ResponseHint.new(status: status, schema_ref: schema_ref, schema: schema, description: "Successful response")
+    end
+
+    def infer_json_schema(value_node)
+      case value_node.type
+      when :send
+        receiver = value_node.children[0]
+        method_name = value_node.children[1]
+        if receiver&.type == :const && method_name == :new
+          serializer_class = const_path(receiver)
+          schema = @serializer_registry.schema_for(serializer_class)
+          return [serializer_class, schema]
+        end
+        if receiver&.type == :ivar
+          model_name = infer_model_from_ivar(receiver)
+          return [model_name, { "$ref" => "#/components/schemas/#{model_name}" }] if model_name
+        end
+      when :const
+        model_name = const_path(value_node)
+        return [model_name, { "$ref" => "#/components/schemas/#{model_name}" }]
+      when :hash
+        return [nil, { type: "object" }]
+      end
+
+      [nil, { type: "object" }]
+    end
+
+    def infer_model_from_ivar(node)
+      node.children[0].to_s.sub(/^@/, "").classify
+    rescue StandardError
+      nil
+    end
+
+    def each_hash_pair(hash_node, &block)
+      hash_node.children.each do |pair_node|
+        next unless pair_node.type == :pair
+
+        yield pair_node.children[0], pair_node.children[1]
+      end
+    end
+
+    def default_response(verb)
+      status = DEFAULT_STATUS.fetch(verb, "200")
+      if status == "204"
+        ResponseHint.new(status: status, schema: nil, description: "No content")
+      else
+        ResponseHint.new(status: status, schema: { type: "object" }, description: "Successful response")
+      end
+    end
+
+    def normalize_status(node)
+      value = literal_value(node)
+      case value
+      when Integer then value.to_s
+      when Symbol
+        Rack::Utils.status_code(value).to_s
+      else
+        value.to_s
+      end
+    rescue StandardError
+      "200"
+    end
+
+    def literal_value(node)
+      case node&.type
+      when :sym then node.children[0]
+      when :int then node.children[0]
+      when :str then node.children[0]
+      else node.to_s
+      end
+    end
+  end
+end

data/lib/rails_autodoc/route_inspector.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  class RouteOperation
+    attr_reader :verb,
+                :path,
+                :controller_class,
+                :action,
+                :route_name,
+                :path_params,
+                :tags,
+                :constraints
+
+    def initialize(verb:, path:, controller_class:, action:, route_name:, path_params:, tags:, constraints: {})
+      @verb = verb
+      @path = path
+      @controller_class = controller_class
+      @action = action.to_s
+      @route_name = route_name
+      @path_params = path_params
+      @tags = tags
+      @constraints = constraints
+    end
+
+    def operation_id
+      "#{controller_class.name.underscore.tr('/', '_')}_#{action}"
+    end
+
+    def openapi_path
+      path.gsub(/:([a-zA-Z_][a-zA-Z0-9_]*)/, '{\1}')
+    end
+  end
+
+  class RouteInspector
+    HTTP_VERBS = %w[GET HEAD POST PUT PATCH DELETE OPTIONS].freeze
+
+    def initialize(config: RailsAutodoc.config)
+      @config = config
+    end
+
+    def operations
+      ensure_controllers_loaded!
+      collect_operations.sort_by { |op| [op.path, op.verb, op.action] }
+    end
+
+    private
+
+    def ensure_controllers_loaded!
+      return unless defined?(Rails) && Rails.application
+
+      Rails.application.eager_load! if Rails.application.config.eager_load == false
+    rescue StandardError
+      nil
+    end
+
+    def collect_operations
+      routes.flat_map { |route| operation_from_route(route) }.compact
+    end
+
+    def routes
+      Rails.application.routes.routes
+    end
+
+    def operation_from_route(route)
+      return nil unless route.respond_to?(:requirements)
+
+      requirements = route.requirements
+      controller_name = requirements[:controller]
+      action = requirements[:action]
+      return nil if controller_name.blank? || action.blank?
+
+      controller_class = resolve_controller(controller_name)
+      return nil unless controller_class
+      return nil unless controller_class.action_methods.include?(action.to_s)
+
+      path = normalize_path(route.path.spec.to_s)
+      return nil if @config.excluded_path?(path)
+
+      verbs = extract_verbs(route)
+      path_params = extract_path_params(path)
+      tags = extract_tags(controller_class)
+
+      verbs.map do |verb|
+        RouteOperation.new(
+          verb: verb,
+          path: path,
+          controller_class: controller_class,
+          action: action,
+          route_name: route.name,
+          path_params: path_params,
+          tags: tags,
+          constraints: route.constraints
+        )
+      end
+    rescue StandardError
+      nil
+    end
+
+    def resolve_controller(controller_name)
+      controller_path = "#{controller_name.camelize}Controller"
+      controller_path.constantize
+    rescue NameError
+      nil
+    end
+
+    def normalize_path(raw_path)
+      path = raw_path
+      path = path.sub(/\(\.:format\)\z/, "")
+      path = path.sub("(.:format)", "")
+      path = "/" if path.blank?
+      path
+    end
+
+    def extract_verbs(route)
+      verb = route.verb
+      if verb.is_a?(Regexp)
+        HTTP_VERBS.grep(verb)
+      elsif verb.is_a?(String)
+        verb.split("|").map(&:upcase).reject { |v| v == "HEAD" }
+      else
+        ["GET"]
+      end
+    end
+
+    def extract_path_params(path)
+      path.scan(/:([a-zA-Z_][a-zA-Z0-9_]*)/).flatten.uniq
+    end
+
+    def extract_tags(controller_class)
+      parts = controller_class.name.split("::")
+      controller_part = parts.last.sub(/Controller\z/, "")
+      tags = [controller_part]
+
+      namespace_parts = parts[0..-2]
+      tags.concat(namespace_parts) unless namespace_parts.empty?
+      tags.uniq
+    end
+  end
+end

data/lib/rails_autodoc/schema_mapper.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  class SchemaMapper
+    TYPE_MAP = {
+      string: { type: "string" },
+      text: { type: "string" },
+      citext: { type: "string" },
+      uuid: { type: "string", format: "uuid" },
+      integer: { type: "integer" },
+      bigint: { type: "integer", format: "int64" },
+      float: { type: "number", format: "float" },
+      decimal: { type: "number", format: "double" },
+      boolean: { type: "boolean" },
+      datetime: { type: "string", format: "date-time" },
+      date: { type: "string", format: "date" },
+      time: { type: "string", format: "time" },
+      json: { type: "object" },
+      jsonb: { type: "object" }
+    }.freeze
+
+    def initialize(schema_path: default_schema_path)
+      @schema_path = schema_path
+      @tables = {}
+      @models = {}
+      load_schema if @schema_path&.exist?
+    end
+
+    def apply_types!(schema, model_name: nil)
+      return schema unless schema.is_a?(Hash)
+
+      schema[:properties]&.each do |field, field_schema|
+        typed = column_schema(model_name, field) if model_name
+        schema[:properties][field] = merge_schemas(field_schema, typed) if typed
+        apply_types!(schema[:properties][field], model_name: model_name)
+      end
+
+      schema
+    end
+
+    def model_schema(model_name)
+      return nil unless defined?(ActiveRecord::Base)
+
+      model = model_name.constantize
+      table = model.table_name
+      columns = @tables[table]
+      return nil unless columns
+
+      properties = {}
+      required = []
+      columns.each do |column_name, column_meta|
+        next if %w[id created_at updated_at].include?(column_name)
+
+        properties[column_name] = column_meta.dup
+        required << column_name unless column_meta[:nullable]
+      end
+
+      {
+        type: "object",
+        properties: properties,
+        required: required
+      }
+    rescue StandardError
+      nil
+    end
+
+    def infer_model_from_controller(controller_class)
+      name = controller_class.name.split("::").last.sub(/Controller\z/, "").singularize
+      name.constantize.name
+    rescue StandardError
+      nil
+    end
+
+    def all_model_schemas
+      return {} unless defined?(ActiveRecord::Base)
+
+      schemas = {}
+      @tables.each_key do |table|
+        model_name = table.classify
+        schema = model_schema(model_name)
+        schemas[model_name] = schema if schema
+      rescue StandardError
+        next
+      end
+      schemas
+    end
+
+    private
+
+    def default_schema_path
+      return nil unless defined?(Rails) && Rails.respond_to?(:root)
+
+      Rails.root.join("db/schema.rb")
+    end
+
+    def load_schema
+      content = @schema_path.read.gsub("\r\n", "\n")
+      parse_create_tables(content)
+    end
+
+    def parse_create_tables(content)
+      content.scan(/create_table\s+"([^"]+)"[^\n]*\n(.*?)end/m).each do |table, body|
+        @tables[table] = parse_columns(body)
+      end
+    end
+
+    def parse_columns(body)
+      columns = {}
+      body.scan(/t\.(\w+)\s+"([^"]+)"(?:,\s*(.*?))?(?:\r)?$/).each do |type, name, options|
+        columns[name] = build_column_schema(type, options)
+      end
+      columns
+    end
+
+    def build_column_schema(type, options)
+      schema = (TYPE_MAP[type.to_sym] || { type: "string" }).dup
+      schema[:nullable] = options.to_s.include?("null: false") == false
+      schema
+    end
+
+    def column_schema(model_name, field)
+      return nil unless model_name
+
+      model = model_name.constantize
+      table = model.table_name
+      column = @tables.dig(table, field.to_s)
+      return nil unless column
+
+      column.dup.tap { |s| s.delete(:nullable) }
+    rescue StandardError
+      nil
+    end
+
+    def merge_schemas(base, overlay)
+      return overlay unless base.is_a?(Hash)
+
+      base.merge(overlay) do |_key, old_val, new_val|
+        old_val.is_a?(Hash) && new_val.is_a?(Hash) ? old_val.merge(new_val) : new_val
+      end
+    end
+  end
+end

data/lib/rails_autodoc/serializers/active_model_serializer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  module Serializers
+    class ActiveModelSerializer < Base
+      def detect?
+        defined?(::ActiveModel::Serializer)
+      end
+
+      def attributes_for(serializer_class)
+        if serializer_class.respond_to?(:_attributes)
+          serializer_class._attributes.keys.map(&:to_s)
+        else
+          []
+        end
+      end
+
+      def schema_for(serializer_class)
+        properties = attributes_for(serializer_class).to_h do |field|
+          [field, { type: "string" }]
+        end
+
+        { type: "object", properties: properties }
+      end
+    end
+  end
+end

data/lib/rails_autodoc/serializers/alba.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  module Serializers
+    class Alba < Base
+      def detect?
+        defined?(::Alba)
+      end
+
+      def attributes_for(serializer_class)
+        serializer_class.instance_methods(false).grep(/^[a-z]/) +
+          extract_alba_attributes(serializer_class)
+      rescue StandardError
+        []
+      end
+
+      def schema_for(serializer_class)
+        fields = extract_alba_attributes(serializer_class)
+        properties = fields.to_h do |field|
+          [field.to_s, { type: "string" }]
+        end
+
+        { type: "object", properties: properties }
+      end
+
+      private
+
+      def extract_alba_attributes(serializer_class)
+        if serializer_class.respond_to?(:attributes)
+          serializer_class.attributes.keys.map(&:to_s)
+        elsif serializer_class.respond_to?(:_attributes)
+          serializer_class._attributes.keys.map(&:to_s)
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/rails_autodoc/serializers/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  module Serializers
+    class Base
+      def detect?
+        false
+      end
+
+      def attributes_for(_serializer_class)
+        []
+      end
+
+      def schema_for(_serializer_class)
+        { type: "object" }
+      end
+    end
+  end
+end

data/lib/rails_autodoc/serializers/blueprinter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  module Serializers
+    class Blueprinter < Base
+      def detect?
+        defined?(::Blueprinter)
+      end
+
+      def attributes_for(serializer_class)
+        if serializer_class.respond_to?(:fields)
+          serializer_class.fields.keys.map(&:to_s)
+        else
+          []
+        end
+      end
+
+      def schema_for(serializer_class)
+        properties = attributes_for(serializer_class).to_h do |field|
+          [field, { type: "string" }]
+        end
+
+        { type: "object", properties: properties }
+      end
+    end
+  end
+end

data/lib/rails_autodoc/serializers/registry.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "alba"
+require_relative "blueprinter"
+require_relative "active_model_serializer"
+
+module RailsAutodoc
+  module Serializers
+    class Registry
+      ADAPTERS = [
+        Alba.new,
+        Blueprinter.new,
+        ActiveModelSerializer.new
+      ].freeze
+
+      def active_adapters
+        ADAPTERS.select(&:detect?)
+      end
+
+      def schema_for(serializer_class)
+        adapter = active_adapters.find do |candidate|
+          candidate.schema_for(serializer_class).fetch(:properties, {}).any?
+        end
+        adapter ? adapter.schema_for(serializer_class) : { type: "object" }
+      end
+    end
+  end
+end