shale-builder 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c029074a32dcf979db1589f717921bec3739c32cd81d6e3885ade102119d1612
-  data.tar.gz: 7dfd4acf1e1e2442b39a8c62510f2ee332b1ada7e55a346ea7709901cdf3520d
+  metadata.gz: 15122ca23e6581da8b35ea0567084d915cb5fca400179505ad618470a6b5b014
+  data.tar.gz: 65c523711576535345141f10d2f656a892a29d111bde9f661310b0a01158b5c4
 SHA512:
-  metadata.gz: 6d805f195b379215bc3e10b748919ba10ba3e51abb80c3973679a3546aff1f577983abd383cf1551e48da5fa1511b0110b4e4d5ac28a071f17f3f4ea3216a8c6
-  data.tar.gz: ad11f0fb55e725fa3145941d56ac4727b3080b0dfcccceb6acc83d81afea8766b2fa7131725a83d50f9cda62090c1cd17d0cdb54d5db517723a2dbb8a350253a
+  metadata.gz: b2fb0f51350d3b412a92fc1c20fd3dc470313a403dbeb2a13196ad7bf7b4423cc7a6cb4862c434106964e1a3d9597c68b2648f715cbfbf77344a2b0450e7c08c
+  data.tar.gz: c87b6e5e6a75c80fc3b08a2c2473e7d775c452b85fcc890ac940848223c65ff847824816382922cd88c80f22c4d4f9b67cca0cacc0455b6d35de9926d1f53998

data/.rubocop.yml

@@ -5,3 +5,9 @@ AllCops:
   TargetRubyVersion: 3.0
   Exclude:
     - lib/tapioca/**/*.rb
+
+Style/DocumentationMethod:
+  Enabled: false
+
+Style/TrailingCommaInArguments:
+  Enabled: false

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [0.1.6] - 2024-05-13
+
+- Add support for doc strings in the tapioca compiler
+
 ## [0.1.5] - 2024-05-13
 
 - Fix a bug in the tapioca compiler

data/Gemfile

@@ -11,3 +11,4 @@ gem 'rake', '~> 13.0' # automation tasks
 gem 'rubocop-espago', '~> 1.0' # ruby linter
 gem 'shoulda-context', '~> 2.0' # more pleasant test syntax
 gem 'solargraph', '~> 0.48'  # language server
+gem 'tapioca', '> 0.13' # RBI generator for sorbet

data/Gemfile.lock

@@ -1,8 +1,10 @@
 PATH
   remote: .
   specs:
-    shale-builder (0.1.5)
+    shale-builder (0.1.6)
+      booleans (>= 0.1)
       shale (< 2.0)
+      sorbet-runtime (> 0.5)
 
 GEM
   remote: https://rubygems.org/
@@ -10,9 +12,11 @@ GEM
     ast (2.4.2)
     backport (1.2.0)
     benchmark (0.2.1)
+    booleans (0.1.1)
     byebug (11.1.3)
     diff-lcs (1.5.0)
     e2mmap (0.1.0)
+    erubi (1.12.0)
     jaro_winkler (1.5.4)
     json (2.6.3)
     kramdown (2.4.0)
@@ -20,6 +24,7 @@ GEM
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     minitest (5.17.0)
+    netrc (0.11.0)
     nokogiri (1.14.2-arm64-darwin)
       racc (~> 1.4)
     nokogiri (1.14.2-x86_64-linux)
@@ -27,9 +32,13 @@ GEM
     parallel (1.22.1)
     parser (3.2.1.0)
       ast (~> 2.4.1)
+    prism (0.29.0)
     racc (1.6.2)
     rainbow (3.1.1)
     rake (13.0.6)
+    rbi (0.1.13)
+      prism (>= 0.18.0, < 1.0.0)
+      sorbet-runtime (>= 0.5.9204)
     regexp_parser (2.7.0)
     reverse_markdown (2.1.1)
       nokogiri
@@ -66,12 +75,37 @@ GEM
       thor (~> 1.0)
       tilt (~> 2.0)
       yard (~> 0.9, >= 0.9.24)
+    sorbet (0.5.11372)
+      sorbet-static (= 0.5.11372)
+    sorbet-runtime (0.5.11372)
+    sorbet-static (0.5.11372-universal-darwin)
+    sorbet-static (0.5.11372-x86_64-linux)
+    sorbet-static-and-runtime (0.5.11372)
+      sorbet (= 0.5.11372)
+      sorbet-runtime (= 0.5.11372)
+    spoom (1.3.2)
+      erubi (>= 1.10.0)
+      prism (>= 0.19.0)
+      sorbet-static-and-runtime (>= 0.5.10187)
+      thor (>= 0.19.2)
+    tapioca (0.14.1)
+      bundler (>= 2.2.25)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      rbi (>= 0.1.4, < 0.2)
+      sorbet-static-and-runtime (>= 0.5.11087)
+      spoom (>= 1.2.0)
+      thor (>= 1.2.0)
+      yard-sorbet
     thor (1.2.1)
     tilt (2.1.0)
     unicode-display_width (2.4.2)
     webrick (1.7.0)
     yard (0.9.28)
       webrick (~> 1.7.0)
+    yard-sorbet (0.8.1)
+      sorbet-runtime (>= 0.5)
+      yard (>= 0.9)
 
 PLATFORMS
   arm64-darwin-20
@@ -86,6 +120,7 @@ DEPENDENCIES
   shale-builder!
   shoulda-context (~> 2.0)
   solargraph (~> 0.48)
+  tapioca (> 0.13)
 
 BUNDLED WITH
    2.4.7

data/README.md

@@ -2,6 +2,9 @@
 
 This addon to the [shale](https://github.com/kgiszczak/shale) Ruby gem adds a simple yet powerful builder DSL.
 
+It also adds support for sorbet and tapioca in shale.
+This gem includes a custom tapioca DSL compiler designed for shale.
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -48,7 +51,11 @@ class Amount < Shale::Mapper
     include Shale::Builder
 
     attribute :value, Shale::Type::Float
-    attribute :currency, Shale::Type::String
+    attribute :currency, Shale::Type::String, doc: <<~DOC
+        This is some custom documentation that can be used by sorbet.
+        It will be used by the tapioca DSL compiler
+        to generate the RBI documentation for this attribute.
+    DOC
 end
 ```
 
@@ -67,6 +74,36 @@ amount = Amount.build do |a|
 end
 ```
 
+If you use sorbet and run `bundle exec tapioca dsl` you'll get the following RBI file.
+
+```rb
+# typed: true
+
+class Amount
+  include ShaleAttributeMethods
+
+  module ShaleAttributeMethods
+    sig { returns(T.nilable(Float)) }
+    def value; end
+
+    sig { params(value: T.nilable(Float)).returns(T.nilable(Float)) }
+    def value=(value); end
+
+    # This is some custom documentation that can be used by sorbet.
+    # It will be used by the tapioca DSL compiler
+    # to generate the RBI documentation for this attribute.
+    sig { returns(T.nilable(String)) }
+    def currency; end
+
+    # This is some custom documentation that can be used by sorbet.
+    # It will be used by the tapioca DSL compiler
+    # to generate the RBI documentation for this attribute.
+    sig { params(value: T.nilable(String)).returns(T.nilable(String)) }
+    def currency=(value); end
+  end
+end
+```
+
 ### Building nested objects
 
 It's kind of pointless when you've got a flat structure.

data/lib/shale/attribute.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+# typed: true
+
+require 'shale'
+
+module Shale
+  class Attribute # rubocop:disable Style/Documentation
+    extend T::Sig
+
+    # Contains the documentation comment for the shale attribute
+    # in a Ruby String.
+    sig { returns(T.nilable(String)) }
+    attr_accessor :doc
+  end
+end

data/lib/shale/builder/version.rb

@@ -2,7 +2,6 @@
 
 module Shale
   module Builder
-    # @return [String]
-    VERSION = '0.1.5'
+    VERSION = '0.1.6'
   end
 end

data/lib/shale/builder.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
+# typed: true
 
 require 'shale'
+require 'sorbet-runtime'
 
 require_relative 'builder/version'
+require_relative 'attribute'
 
 module Shale
   # It's meant to be included in subclasses of `Shale::Mapper`
@@ -37,11 +40,13 @@ module Shale
   #       end
   #
   module Builder
+    extend T::Helpers
+
     class << self
+      extend T::Sig
+
       # Gets called after including this module in a module or class.
-      #
-      # @param mod [Module, Class]
-      # @return [void]
+      sig { params(mod: Module).void }
       def included(mod)
         mod.extend ClassMethods
         Builder.prepare_mod(mod)
@@ -49,9 +54,7 @@ module Shale
 
       # Prepares the received module or class
       # for dynamic method definition.
-      #
-      # @param mod [Module, Class]
-      # @return [void]
+      sig { params(mod: Module).void }
       def prepare_mod(mod)
         builder_methods_module = ::Module.new
         mod.instance_variable_set :@builder_methods_module, builder_methods_module
@@ -61,8 +64,12 @@ module Shale
 
     # Class methods provided by `Shale::Builder`
     module ClassMethods
-      # @param subclass [Class]
-      # @return [void]
+      extend T::Sig
+      extend T::Generic
+      abstract!
+      has_attached_class!
+
+      sig { params(subclass: Class).void }
       def inherited(subclass)
         super
         Builder.prepare_mod(subclass)
@@ -70,27 +77,37 @@ module Shale
 
       # Contains overridden getter methods for attributes
       # with complex types (so that they accept a block for building)
-      #
-      # @return [Module]
+      sig { returns(Module) }
       attr_reader :builder_methods_module
 
-      # @return [Class, nil]
-      attr_accessor :request_class
-
-      # @yieldparam [self]
-      # @return [self]
-      def build
+      sig { params(_block: T.proc.params(arg0: T.attached_class).void).returns(T.attached_class) }
+      def build(&_block)
         body = new
         yield(body)
 
         body
       end
 
-      # @param name [String, Symbol]
-      # @param type [Class]
-      # @return [void]
-      def attribute(name, type, *args, collection: false, **kwargs, &block)
-        super
+      sig { abstract.returns(T.attached_class) }
+      def new; end
+
+      sig { abstract.returns(T::Hash[Symbol, Shale::Attribute]) }
+      def attributes; end
+
+      sig do
+        params(
+          name: T.any(String, Symbol),
+          type: Class,
+          collection: T::Boolean,
+          default: T.nilable(Proc),
+          doc: T.nilable(String),
+          kwargs: Object,
+          block: T.nilable(T.proc.void),
+        ).void
+      end
+      def attribute(name, type, collection: false, default: nil, doc: nil, **kwargs, &block)
+        super(name, type, collection: collection, default: default, **kwargs, &block)
+        attributes[name.to_sym]&.doc = doc # add doc to the attribute
         return unless type < ::Shale::Mapper
 
         if collection
@@ -121,5 +138,7 @@ module Shale
 
     end
 
+    mixes_in_class_methods(ClassMethods)
+
   end
 end

data/lib/tapioca/dsl/compilers/shale.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require 'shale'
+require 'booleans'
 begin
   require 'shale/builder'
 rescue LoadError
@@ -10,9 +11,12 @@ end
 module Tapioca
   module Compilers
     class Shale < Tapioca::Dsl::Compiler
+      extend T::Sig
       ConstantType = type_member { { fixed: T.class_of(::Shale::Mapper) } }
 
       class << self
+        extend T::Sig
+
         sig { override.returns(T::Enumerable[Module]) }
         def gather_constants
           # Collect all the classes that inherit from Shale::Mapper
@@ -20,19 +24,27 @@ module Tapioca
         end
       end
 
+      SHALE_ATTRIBUTE_MODULE = 'ShaleAttributeMethods'
+
       sig { override.void }
       def decorate
         # Create a RBI definition for each class that inherits from Shale::Mapper
         root.create_path(constant) do |klass|
           has_shale_builder = includes_shale_builder(constant)
-
+          mod = klass.create_module(SHALE_ATTRIBUTE_MODULE)
+          klass.create_include(SHALE_ATTRIBUTE_MODULE)
           # For each attribute defined in the class
           constant.attributes.each_value do |attribute|
+            attribute = T.let(attribute, ::Shale::Attribute)
             non_nilable_type, nilable_type = shale_type_to_sorbet_type(attribute)
             type = nilable_type
             if attribute.collection?
               type = "T.nilable(T::Array[#{non_nilable_type}])"
             end
+            comments = T.let([], T::Array[RBI::Comment])
+            if shale_builder_defined? && attribute.doc
+              comments << RBI::Comment.new(T.must(attribute.doc))
+            end
 
             if has_shale_builder && attribute.type < ::Shale::Mapper
               sigs = T.let([], T::Array[RBI::Sig])
@@ -46,20 +58,22 @@ module Tapioca
                 parameters: { block: "T.proc.params(arg0: #{non_nilable_type}).void" },
                 return_type: non_nilable_type
               )
-              klass.create_method_with_sigs(
+              mod.create_method_with_sigs(
                 attribute.name,
                 sigs: sigs,
+                comments: comments,
                 parameters: [RBI::BlockParam.new('block')],
               )
             else
-              klass.create_method(attribute.name, return_type: type)
+              mod.create_method(attribute.name, return_type: type, comments: comments)
             end
 
             # setter
-            klass.create_method(
+            mod.create_method(
               "#{attribute.name}=",
               parameters: [create_param('value', type: type)],
               return_type: type,
+              comments: comments,
             )
           end
         end
@@ -75,6 +89,9 @@ module Tapioca
         klass < ::Shale::Builder
       end
 
+      sig { returns(T::Boolean) }
+      def shale_builder_defined? = Boolean(defined?(::Shale::Builder))
+
       SHALE_TYPES_MAP = T.let(
         {
           ::Shale::Type::Value    => Object,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shale-builder
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Mateusz Drewniak
@@ -10,6 +10,20 @@ bindir: exe
 cert_chain: []
 date: 2024-05-13 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: booleans
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: shale
   requirement: !ruby/object:Gem::Requirement
@@ -24,6 +38,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 description: An addon to the shale Ruby gem which adds a simple yet powerful builder
   DSL.
 email:
@@ -40,6 +68,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- lib/shale/attribute.rb
 - lib/shale/builder.rb
 - lib/shale/builder/version.rb
 - lib/tapioca/dsl/compilers/shale.rb