categoria 0.1.0.pre.beta0 → 0.1.0.pre.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 708dc304bd6e976ef1570ee99cb1208b4814c37fdcff7e0f69ac4d2ce7970e50
-  data.tar.gz: d2db1ff75ae27757941554ee650ea86e5db8fb6a34d715a439e74b2bbc67f4b3
+  metadata.gz: a0660b4ae95d4760102773e4c0f7ec88dc6261a740f4edacb521a853501bbb9d
+  data.tar.gz: 41bdb997ca840970d69dfa8847e23217b9d742eeb3f8720ae16cb6ac84203596
 SHA512:
-  metadata.gz: 84ff6674a0d1c147b13a449c2f816314d1e748263e67bfad5ada878055897398ee60a501d372649718d74e34d3973447553cd45747a098aa9433d6851e137a37
-  data.tar.gz: 3581214bb48972f200f24b59567b2e529fdcf6c3164aa49f3b001d38c6173af89aa182cb240995d2eb058312d28ebeaa61225b195bc7a6150117a7b34ef4246d
+  metadata.gz: b75fcff2064e3150c32885e9ec65c6035fc6a0b12d9223596627a1f74f80ee380839badd568a88412bd0d095be5494e7d3de873721f83ec8ad02beddeb04496c
+  data.tar.gz: aa8228b9561687786378d77fe84939b02a8e16d80482e686c5e6491eba43453764378803ce6ba5c78e30fec4ac55a95bfbd4807d2a2d0fd55c7cf00d6bdd6dfe

data/README.md

@@ -17,16 +17,37 @@ along domain lines. it's similar in spirit to [phoenix's context][phxc]. the
 point of departure is the following:
 
 **a category/domain doesn't concern itself with the web part of the application.**
+that is because the web concerns tend to be cross-cutting (across domains). in a
+controller action, it's possible to invoke several commands from different
+domains in service of the request. the returned response might also be a
+combination of data from different domains. in order to allow this freedom, all
+app components that directly handle web requests can remain in their
+conventional locations.
+
+what to call controllers? typically they have matched a given model. you have a
+`Document` model, here's the `DocumentsController`. now that the document model
+is subsumed under a domain of different name, the controller should be allowed
+to float freely. it could be an interface to a domain, or to several domains at
+the same time. an appropriate name should be chosen.
 
 ### directory structure of a domain
 
 domains live under `app/lib` of the rails application. internally, it is
 organized into three main categories, represented by directories and ruby module
-namespaces:
+namespaces. all domains are sub-namespaced under the application's main
+namespace. an initializer is added to override zeitwerk's default behavior of
+using `Object` as the root namespace for classes loaded from `app/lib`.
 
-- `internal`: to be described
-- `command`: to be described
-- `data`: to be described
+#### `internal`
+#### `command`
+#### `data`
+
+## Test
+
+the same structure is repeated under the `test` directory, under universal
+`Test` namespace. just so constant loading, in non-test local and remote (prod)
+environments don't load unnecessary code. the `Test` namespace should only be
+loaded in a test environment.
 
 [discourse]: https:/github.com/discourse/discourse
 [dc_models]: https://github.com/discourse/discourse/tree/main/app/models

data/lib/categoria/data.rb

@@ -0,0 +1,11 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Categoria
+  class Data
+    extend T::Helpers
+    extend T::Sig
+
+    abstract!
+  end
+end

data/lib/categoria/types.rb

@@ -0,0 +1,16 @@
+# typed: false
+# frozen_string_literal: true
+
+module Categoria
+  module Types
+    extend T::Sig
+
+    class Component < T::Enum
+      enums do
+        Command = new("command")
+        Model   = new("model")
+        Data    = new("data")
+      end
+    end
+  end
+end

data/lib/categoria/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Categoria
-  VERSION = "0.1.0-beta0"
+  VERSION = "0.1.0-beta1"
 end

data/lib/categoria.rb

@@ -1,9 +1,13 @@
 # typed: strict
 # frozen_string_literal: true
 
+require "zeitwerk"
 require "sorbet-runtime"
 
-require_relative "categoria/version"
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/generators")
+loader.setup
 
 module Categoria
+  extend T::Sig
 end

data/lib/generators/categoria/command_generator.rb

@@ -1,8 +1,40 @@
 # typed: strict
 # frozen_string_literal: true
 
+require_relative "helpers"
+
 module Categoria
   module Generators
-    class CommandGenerator < ::Rails::Generators::NamedBase; end
+    class CommandGenerator < ::Rails::Generators::NamedBase
+      extend T::Sig
+
+      include Helpers
+
+      Component = Types::Component
+
+      def generate_command_class
+        in_root do
+          component_path = domain_component_path(domain, Component::Command)
+          class_path     = component_path.join("#{component}.rb")
+
+          create_file class_path, <<~COMMAND
+            # frozen_string_literal: true
+
+            module #{root_module}
+              module #{domain_module}
+                module Command
+                  class #{class_name}
+                    def self.invoke(arg0); end
+                  end
+                end
+              end
+            end
+          COMMAND
+        end
+      end
+
+      sig { returns(String) }
+      def class_name = component.classify
+    end
   end
 end

data/lib/generators/categoria/data_generator.rb

@@ -0,0 +1,18 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Categoria
+  module Generators
+    class DataGenerator < ::Rails::Generators::NamedBase
+      extend T::Sig
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc <<~DOC.squish
+        generates a data class for the domain. data classes are used
+        like value classes: hashes are more fit for the purpose except
+        that in the wild hashes are difficult to tame.
+      DOC
+    end
+  end
+end

data/lib/generators/categoria/domain_generator.rb

@@ -8,27 +8,51 @@ module Categoria
 
       source_root File.expand_path("templates", __dir__)
 
+      sig { returns(String) }
       def module_name = file_name.capitalize
 
       sig { void }
       def setup_new_domain
-        domain_directory_path = "#{Rails.root}/app/lib/#{file_name}"
-        %w[
-          internal/commands
-          internal/models
-          command
-          data
-        ].each do |component_path|
-          full_component_path = "#{domain_directory_path}/#{component_path}"
-
-          empty_directory full_component_path
-          create_file "#{full_component_path}/.keep"
+        domain_dir = Pathname.new("app/lib/#{file_name}")
+
+        in_root do
+          # turns out that in order to cleanly undo the changes
+          # introduced by the generator, we should make a few of
+          # the actions more explicit, and independent, like the
+          # creation of the domain directory itself.
+          empty_directory domain_dir
+
+          %w[
+            internal/commands
+            internal/models
+            command
+            data
+          ].each do |component_path|
+            create_empty_directory_with_keep_file \
+              at: domain_dir.join(component_path)
+          end
+
+          template \
+            "domain_description.yml.erb",
+            domain_dir.join("description.yml")
+          create_file domain_dir.join("README.md"), <<~README
+            # About #{module_name}
+
+            Describe the domain. You may provide usage guide for your public interfaces (commands).
+            Feel free to describe explicitly what may be implicit (e.g. triggered jobs, emitted
+            events, sent emails, etc).
+          README
         end
 
-        create_file "#{domain_directory_path}/description.yml"
         template \
           "domain_module.rb.erb",
-          "#{domain_directory_path}.rb"
+          "#{domain_dir}.rb"
+      end
+
+      sig { params(at: Pathname).void }
+      private def create_empty_directory_with_keep_file(at:)
+        empty_directory at
+        create_file at.join(".keep")
       end
     end
   end

data/lib/generators/categoria/helpers.rb

@@ -0,0 +1,63 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "active_support/inflector"
+
+module Categoria
+  module Generators
+    module Helpers
+      extend T::Sig
+
+      Component = Types::Component
+
+      sig { returns(String) }
+      def root_module = Rails.application.class.module_parent.name
+
+      sig { returns(String) }
+      def domain_module = domain.capitalize
+
+      sig { returns(String) }
+      def domain_prefix = domain.singularize
+
+      def class_name = ActiveSupport::Inflector.classify(component)
+
+      sig { returns(String) }
+      def domain
+        @domain ||= T.let(
+          T.must(domain_and_component[0]),
+          T.nilable(String)
+        )
+      end
+
+      def component
+        @component ||= T.let(
+          T.must(domain_and_component[1]),
+          T.nilable(String)
+        )
+      end
+
+      sig { returns([String, String]) }
+      def domain_and_component
+        @domain_and_component ||= T.let(
+          T.must(name.split(/:/)[..1]),
+          [String, String]
+        )
+      end
+
+      sig { params(domain: String, component: Types::Component).returns(Pathname) }
+      def domain_component_path(domain, component)
+        domain_path = domain_path_in_root(domain)
+
+        case component
+        when Component::Command then Pathname.new %(#{domain_path}/command)
+        when Component::Model   then Pathname.new %(#{domain_path}/internal/models)
+        when Component::Data    then Pathname.new %(#{domain_path}/data)
+        else T.absurd(component)
+        end
+      end
+
+      sig { params(domain: String).returns(String) }
+      def domain_path_in_root(domain) = %(app/lib/#{domain})
+    end
+  end
+end

data/lib/generators/categoria/initializer_generator.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Categoria
+  module Generators
+    class InitializerGenerator < ::Rails::Generators::Base
+      extend T::Sig
+
+      sig { void }
+      def create_categoria_initializer_file
+        in_root do
+          create_file "config/initializers/categoria.rb", <<~INITIALIZER
+            # frozen_string_literal: true
+
+            Rails.autoloaders.main.push_dir(
+              "\#{Rails.root}/app/lib",
+              namespace: Rails.application.class.module_parent
+            )
+          INITIALIZER
+        end
+      end
+    end
+  end
+end

data/lib/generators/categoria/model_generator.rb

@@ -1,8 +1,78 @@
 # typed: strict
 # frozen_string_literal: true
 
+require "rails/generators"
+require "rails/generators/active_record"
+require "rails/generators/active_record/migration"
+require "rails/generators/model_helpers"
+require "rails/generators/migration"
+require "active_record"
+require_relative "helpers"
+
 module Categoria
   module Generators
-    class ModelGenerator < ::Rails::Generators::NamedBase; end
+    # `ModelGenerator` is almost an exact copy of the ActiveRecord
+    # model generator. significant departures are as follows:
+    #   - migrations cannot be skipped since a model should be an orm class,
+    #     otherwise a data class is what you need. a data class typically
+    #     serializes one or more model records into a form that is publicized.
+    #     they are allowed to perform all sorts of key & value transformations
+    #     for purposes of data interchange format and/or
+    #     security-by-obscurity.
+    #   - models are not in `app/models` but instead internal to domain.
+    class ModelGenerator < ::Rails::Generators::NamedBase
+      extend T::Sig
+      include ::Rails::Generators::ModelHelpers
+      include ::Rails::Generators::Migration
+      include ::ActiveRecord::Generators::Migration
+      include Helpers
+
+      Component = Types::Component
+
+      desc <<~DOC.squish
+      DOC
+
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument \
+        :attributes,
+        type: :array,
+        default: [],
+        banner: %(field[:type][:index] field[:type][:index])
+
+      sig { void }
+      def create_migration_file
+        migrate_dir = Pathname.new(db_migrate_path)
+
+        migration_template(
+          "model_migration.rb.erb",
+          migrate_dir.join("create_#{domain_prefixed_relation_name}_table.rb"),
+          migration_version:
+        )
+      end
+
+      sig { returns(String) }
+      def migration_version = "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+
+      sig { void }
+      def generate_internal_model
+        component_path = domain_component_path(domain, Component::Model)
+        class_path = component_path.join("#{component}.rb")
+
+        in_root { template "model.rb.erb", class_path }
+      end
+
+      sig { returns(String) }
+      def domain_prefixed_relation_name = %(#{domain_prefix}_#{component.pluralize})
+
+      sig { returns(T::Array[String]) }
+      def attributes_with_index = attributes.select { !_1.reference? && _1.has_index? }
+
+      sig { params(dirname: String).returns(String) }
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+    end
   end
 end

data/lib/generators/categoria/templates/data.rb.erb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module <%= Rails.application.class.module_parent %>
+  module <%= domain_module %>
+    module Data
+      class <%= data_class_name %> < ::Categoria::Data
+      end
+    end
+  end
+end
+

data/lib/generators/categoria/templates/domain_description.yml.erb

@@ -0,0 +1,12 @@
+# Domains are typically owned by one team (and one team can own)
+# many domains. The contents of this yaml file help other teams
+# quickly learn about the domain, and figure out how to contact
+# the owners.
+---
+
+manifest:
+  owner:
+    github_username: "@owner-github-username"
+    slack_channel: "#owner-slack-channel"
+    email: "owner@example.org"
+    team: "org-team-name"

data/lib/generators/categoria/templates/model.rb.erb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module <%= Rails.application.class.module_parent %>
+  module <%= domain_module %>
+    module Internal
+      module Models
+        class <%= class_name %> < ApplicationRecord
+          self.table_name = "<%= domain_prefixed_relation_name %>"
+        end
+      end
+    end
+  end
+end

data/lib/generators/categoria/templates/model_migration.rb.erb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= domain_prefixed_relation_name %><%= primary_key_type %> do |t|
+<% attributes.each do |attribute| -%>
+<% if attribute.password_digest? -%>
+      t.string :password_digest<%= attribute.inject_options %>
+<% elsif attribute.token? -%>
+      t.string :<%= attribute.name %><%= attribute.inject_options %>
+<% elsif attribute.reference? -%>
+      t.<%= attribute.type %> :<%= attribute.name %><%= attribute.inject_options %><%= foreign_key_type %>
+<% elsif !attribute.virtual? -%>
+      t.<%= attribute.type %> :<%= attribute.name %><%= attribute.inject_options %>
+<% end -%>
+<% end -%>
+<% if options[:timestamps] %>
+      t.timestamps
+<% end -%>
+    end
+<% attributes.select(&:token?).each do |attribute| -%>
+    add_index :<%= table_name %>, :<%= attribute.index_name %><%= attribute.inject_index_options %>, unique: true
+<% end -%>
+<% attributes_with_index.each do |attribute| -%>
+    add_index :<%= table_name %>, :<%= attribute.index_name %><%= attribute.inject_index_options %>
+<% end -%>
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: categoria
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.beta0
+  version: 0.1.0.pre.beta1
 platform: ruby
 authors:
 - Yaw Boakye
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-03 00:00:00.000000000 Z
+date: 2024-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
@@ -203,17 +203,26 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
-- LICENSE.txt
+- LICENSE
 - README.md
 - Rakefile
 - categoria.gemspec
 - lib/categoria.rb
+- lib/categoria/data.rb
+- lib/categoria/types.rb
 - lib/categoria/version.rb
 - lib/generators/categoria/command_generator.rb
+- lib/generators/categoria/data_generator.rb
 - lib/generators/categoria/domain_generator.rb
+- lib/generators/categoria/helpers.rb
+- lib/generators/categoria/initializer_generator.rb
 - lib/generators/categoria/model_generator.rb
+- lib/generators/categoria/templates/data.rb.erb
+- lib/generators/categoria/templates/domain_description.yml.erb
 - lib/generators/categoria/templates/domain_module.rb.erb
-- sig/categoria.rbs
+- lib/generators/categoria/templates/model.rb.erb
+- lib/generators/categoria/templates/model_migration.rb.erb
+- lib/tasks/check.rake
 - sorbet/config
 - sorbet/rbi/annotations/.gitattributes
 - sorbet/rbi/annotations/actionmailer.rbi

data/sig/categoria.rbs

@@ -1,4 +0,0 @@
-module Categoria
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end