typespec_from_serializers 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86e41505961e13ef72df62124721ae6d1c929104726378b893c2c785dcec7da0
-  data.tar.gz: 985c5514cdc77c02ee25a4257c8c3fc7d3c8adb7d7ea7585d1d64c3f3af1f732
+  metadata.gz: 0fcb3ccc36429f3897ca0241c3546ae767871bcd3dc7acd51ed396ad9242baf4
+  data.tar.gz: c005d31f939a5d18cc85c7dc4444e73407c587575646debf673bf272abe8d507
 SHA512:
-  metadata.gz: d51adab2df0d34f587eb375950cafd6231fd5e94b8e1359086d8b7fd5745c6c200900217c7e95edab0a855a07029aaf5147fde3f89639c9843770298d03ab031
-  data.tar.gz: 06fd0b0629657ae60d101bca4ed879cb5134801ce91097e87acc8e14825f7f2a290211dd282801bcd8154b4d7f1514ab2f24e83cfd5fd4f22be18db711bb6399
+  metadata.gz: b35e53c47b2e075eb57e26436ac037d18fe4b2cb2154ed58877e55bc206fe67ee17a253cc78f61d0c8007f7487c8429b6d899332c8b1e7f5686afbd026b080c8
+  data.tar.gz: ec7c3fa57c006157fefa598c3c129091edd3ac5f35484f46602392a7fbd2b00dc9df2343e776f19cdbc2a98eec64c49d94b6af89e252423c8d401d5bae3a695c

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # TypeSpec From Serializers Changelog
 
+## [0.3.0] - 2025-12-20
+
+### Features
+- Extract RDoc comments from serializers and controllers to generate `@doc` decorators
+- New `extract_docs` config option (enabled by default) to control documentation extraction
+- Requires RDoc 7.0+ for Prism-based parser support
+
 ## [0.2.1] - 2025-12-19
 
 ### Fixed

data/lib/typespec_from_serializers/generator.rb

@@ -3,6 +3,7 @@
 require "digest"
 require "fileutils"
 require "pathname"
+require "typespec_from_serializers/rdoc"
 
 # Public: Automatically generates TypeSpec descriptions for Ruby serializers and Rails routes.
 module TypeSpecFromSerializers
@@ -93,6 +94,7 @@ module TypeSpecFromSerializers
                   optional: options[:optional] || options.key?(:if),
                   multi: options[:association] == :many,
                   column_name: options.fetch(:value_from),
+                  doc: TypeSpecFromSerializers.config.extract_docs ? RDoc.method_doc(self, options.fetch(:value_from)) : nil,
                 ).tap do |property|
                   property.infer_typespec_from(model_columns, model_enums, typespec_from, self, model_class)
                 end
@@ -107,6 +109,7 @@ module TypeSpecFromSerializers
           name: tsp_name,
           filename: tsp_filename,
           properties: tsp_properties,
+          doc: TypeSpecFromSerializers.config.extract_docs ? RDoc.class_doc(self) : nil,
         )
       end
     end
@@ -134,6 +137,7 @@ module TypeSpecFromSerializers
     :package_manager,
     :openapi_path,
     :max_line_length,
+    :extract_docs,
     :root,
     keyword_init: true,
   ) do
@@ -151,6 +155,7 @@ module TypeSpecFromSerializers
     :name,
     :filename,
     :properties,
+    :doc,
     keyword_init: true,
   ) do
     using SerializerRefinements
@@ -209,13 +214,20 @@ module TypeSpecFromSerializers
 
     def as_typespec
       indent = TypeSpecFromSerializers.config.namespace ? 2 : 1
+      doc_decorator = doc ? "@doc(\"#{escape_doc(doc)}\")\n#{"  " * (indent - 1)}" : ""
       <<~TSP.gsub(/\n$/, "")
-        model #{name} {
+        #{doc_decorator}model #{name} {
         #{"  " * indent}#{properties.index_by(&:name).values.map(&:as_typespec).join("\n#{"  " * indent}")}
         #{"  " * (indent - 1)}}
       TSP
     end
 
+  private
+
+    def escape_doc(str)
+      str.gsub('\\', '\\\\').gsub('"', '\\"').gsub("\n", "\\n")
+    end
+
   protected
 
     def pathname
@@ -242,6 +254,7 @@ module TypeSpecFromSerializers
     :optional,
     :multi,
     :column_name,
+    :doc,
     keyword_init: true,
   ) do
     using SerializerRefinements
@@ -314,11 +327,16 @@ module TypeSpecFromSerializers
       end
 
       escaped_name = escape_field_name(name)
-      "#{escaped_name}#{"?" if optional}: #{type_str}#{"[]" if multi};"
+      field_line = "#{escaped_name}#{"?" if optional}: #{type_str}#{"[]" if multi};"
+      doc ? "@doc(\"#{escape_doc(doc)}\")\n  #{field_line}" : field_line
     end
 
   private
 
+    def escape_doc(str)
+      str.gsub('\\', '\\\\').gsub('"', '\\"').gsub("\n", "\\n")
+    end
+
     def escape_field_name(field_name)
       # Escape field names that conflict with TypeSpec keywords using backticks
       all_keywords = TYPESPEC_LANGUAGE_KEYWORDS +
@@ -361,22 +379,27 @@ module TypeSpecFromSerializers
   end
 
   # Internal: Represents a TypeSpec operation within a resource
-  Operation = Struct.new(:method, :action, :path, :path_params, :body_params, :response_type, keyword_init: true) do
+  Operation = Struct.new(:method, :action, :path, :path_params, :body_params, :response_type, :doc, keyword_init: true) do
     def as_typespec(resource_path: nil)
       tsp_method = method.downcase
       operation_name = TypeSpecFromSerializers.config.action_to_operation_mapping[action] || action
       route_line = build_route_decorator(resource_path)
+      doc_line = doc ? "@doc(\"#{escape_doc(doc)}\")\n  " : ""
 
       # Check if we need multiline formatting
       single_line = build_single_line(tsp_method, operation_name)
 
       too_long_for_single_line?(single_line) ?
-        multiline_format(route_line, tsp_method, operation_name) :
-        "#{route_line}#{single_line}"
+        "#{doc_line}#{multiline_format(route_line, tsp_method, operation_name)}" :
+        "#{doc_line}#{route_line}#{single_line}"
     end
 
     private
 
+    def escape_doc(str)
+      str.gsub('\\', '\\\\').gsub('"', '\\"').gsub("\n", "\\n")
+    end
+
     def build_route_decorator(resource_path)
       decorator = operation_route_decorator(resource_path)
       decorator ? "#{decorator}\n  " : ""
@@ -698,6 +721,7 @@ module TypeSpecFromSerializers
     def build_operation(controller, route)
       path_param_names = route[:path].scan(/:([a-zA-Z_][a-zA-Z0-9_]*)/).flatten
       param_types = extract_all_param_types(controller, route)
+      controller_class = "#{controller.camelize}#{config.controller_suffix}".safe_constantize
 
       Operation.new(
         method: route[:method],
@@ -706,6 +730,7 @@ module TypeSpecFromSerializers
         path_params: build_path_params(path_param_names, param_types),
         body_params: build_body_params(route[:method], path_param_names, param_types),
         response_type: infer_operation_response_type(route),
+        doc: config.extract_docs && controller_class ? RDoc.method_doc(controller_class, route[:action]) : nil,
       )
     end
 
@@ -1267,6 +1292,9 @@ module TypeSpecFromSerializers
         # Maximum line length before switching to multiline format for operations
         max_line_length: 100,
 
+        # Extract documentation from RDoc comments
+        extract_docs: true,
+
         # Project root directory
         root: root,
       )

data/lib/typespec_from_serializers/rdoc.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "rdoc"
+
+module TypeSpecFromSerializers
+  # Public: RDoc integration for documentation extraction.
+  #
+  # This module uses RDoc's Prism-based parser to extract documentation
+  # comments from Ruby source files. It provides documentation for:
+  # 1. Classes (serializers, controllers)
+  # 2. Methods (controller actions, serializer attributes)
+  #
+  # The module caches parsed files to avoid re-parsing the same file
+  # multiple times during a single generation run.
+  #
+  # Requires RDoc 7.0+ for Prism parser support. Gracefully degrades
+  # to returning nil for all documentation when unavailable.
+  module RDoc
+    class << self
+      # Public: Check if RDoc Prism parser is available.
+      #
+      # Returns true if RDoc 7.0+ with Prism parser is available.
+      def available?
+        return @available if defined?(@available)
+
+        @available = begin
+          require "rdoc/parser/prism_ruby"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      # Public: Get documentation for a class.
+      #
+      # klass - The Class to get documentation for
+      #
+      # Returns String or nil
+      def class_doc(klass)
+        find_rdoc_class(klass)&.then { extract_comment_text(_1.comment) }
+      end
+
+      # Public: Get documentation for a method.
+      #
+      # klass       - The Class containing the method
+      # method_name - Symbol or String name of the method
+      #
+      # Returns String or nil
+      def method_doc(klass, method_name)
+        find_rdoc_class(klass)
+          &.method_list
+          &.find { _1.name == method_name.to_s }
+          &.then { extract_comment_text(_1.comment) }
+      end
+
+      # Public: Clear the parse cache.
+      #
+      # This should be called between generation runs if files may have changed.
+      def clear_cache!
+        @cache = {}
+      end
+
+      private
+
+      # Internal: Find the RDoc class object for a Ruby class.
+      #
+      # klass - The Class to find documentation for
+      #
+      # Returns RDoc::NormalClass, RDoc::NormalModule, or nil
+      def find_rdoc_class(klass)
+        return unless available?
+
+        file_path = Object.const_source_location(klass.name)&.first
+        top_level = file_path && parse_file(file_path)
+        return unless top_level
+
+        class_name = klass.name.split("::").last
+        top_level.classes.find { _1.name == class_name } ||
+          top_level.modules.find { _1.name == class_name }
+      rescue
+        nil
+      end
+
+      # Internal: Parse a Ruby file and return the RDoc top-level object.
+      #
+      # file_path - String path to the Ruby file
+      #
+      # Returns RDoc::TopLevel or nil if parsing fails
+      def parse_file(file_path)
+        @cache ||= {}
+        @cache[file_path] ||= begin
+          return unless File.exist?(file_path)
+
+          options = ::RDoc::Options.new
+          store = ::RDoc::Store.new(options)
+          top_level = store.add_file(file_path)
+          stats = ::RDoc::Stats.new(store, 0, 0)
+
+          parser = ::RDoc::Parser::PrismRuby.new(top_level, File.read(file_path), options, stats)
+          parser.scan
+          top_level
+        rescue => e
+          warn "TypeSpec: Failed to parse #{file_path} for docs: #{e.message}" if ENV["DEBUG"]
+          nil
+        end
+      end
+
+      # Internal: Extract text from an RDoc::Comment or String.
+      #
+      # comment - RDoc::Comment object or String
+      #
+      # Returns String or nil
+      def extract_comment_text(comment)
+        case comment
+        when String then comment.strip.presence
+        when nil then nil
+        else
+          comment.normalize
+          comment.text&.strip.presence
+        end
+      end
+    end
+  end
+end

data/lib/typespec_from_serializers/version.rb

@@ -2,5 +2,5 @@
 
 module TypeSpecFromSerializers
   # Public: This library adheres to semantic versioning.
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typespec_from_serializers
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Danila Poyarkov
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-19 00:00:00.000000000 Z
+date: 2025-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -87,6 +87,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -305,6 +319,7 @@ files:
 - lib/typespec_from_serializers/openapi_compiler.rb
 - lib/typespec_from_serializers/railtie.rb
 - lib/typespec_from_serializers/rbi.rb
+- lib/typespec_from_serializers/rdoc.rb
 - lib/typespec_from_serializers/runner.rb
 - lib/typespec_from_serializers/sorbet.rb
 - lib/typespec_from_serializers/version.rb