thecore_generators 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e0af52a7399d45699c4b84d80cead588d71f37e255bfa324141d8a0033aa561
-  data.tar.gz: 241b9957c4a166c010d78c5f1175b98bc802eb28f4757131fc69d1c1d4e24e2d
+  metadata.gz: 48198bd6f914066ca468eae2e95cb9dba85003d49532b1db28f8620db3c40b21
+  data.tar.gz: 7a3e542b82e0ff43691e3a988dad6e42f59fc51da0e460220e5481881eb55ba3
 SHA512:
-  metadata.gz: 736b763f3dbf6508d97e14b934240b2420db7da18b5e0eda0fd1c6c987e76e26ff3c36ea6a0c3c9d03ed6bf89fef1be5ad631303d38978fc52df021d0c717002
-  data.tar.gz: 32bb39ef9cdc30d2023986db40e487a36869555ba3ac02582bb8ba9d89622d1030ed4ce2f9be8b043cf2e521dac1f08f3c1805c4ef389a092c362b157952164d
+  metadata.gz: 82748585f40f3f1e3975a3c1186d4bb98a3d8c4963ebcb495d9ba4c3c86701b2a48e981c28a6bfe220bd20b90fbcdacffa7e332b36edcbba2d4c3ab80e097e0d
+  data.tar.gz: ca82db7bdc678f66789b0ed9af24bf28f4f2253e2c025c3972118e602a86e662fc845863b098ba220d3163739c30b73f2588b30eb0aa8384300bc86a25adf013

data/README.md

@@ -26,13 +26,23 @@ transparently apply thecore's scaffolding conventions — no new command vocabul
   `app/models`/`db/migrate`/`test` instead of the host app's. Pass `--atom=NAME` to
   override detection explicitly (works independent of `cwd`, e.g. from CI or the host-app
   root).
-- **Default concerns, unchanged.** `Api::ModelName`/`RailsAdmin::ModelName` concern files
-  are generated and `include`d into the model, exactly as `thecore_code_extension`'s
-  `addModel.js` templates do today.
-- **No `Endpoints::ModelName` by default** (per
+- **No concern files by default.** `Api::ModelName`/`RailsAdmin::ModelName` concern files
+  are **not** generated (per
   [ADR 0001](https://github.com/gabrieletassoni/thecore/blob/release/3/docs/adr/0001-application-record-defaults-over-generated-concerns.md)) —
-  add one by hand, following the `after_initialize` + `class_eval` pattern, only when a
-  real custom action is needed.
+  the no-customization case relies entirely on the default `json_attrs`/`navigation_label`/
+  `navigation_icon` behavior that `model_driven_api` and `thecore_ui_rails_admin` `include`
+  into every `ApplicationRecord` subclass automatically
+  (`ThecoreBackendCommons::DefaultModuleRegistry`). Pass `--with-api-concern` and/or
+  `--with-admin-concern` to scaffold a starter concern file — identical in shape to what
+  this generator produced before this default changed — for the case where customization
+  is already known to be needed at generation time:
+  ```bash
+  rails generate model Foo name:string --with-api-concern --with-admin-concern
+  ```
+  See "Adding a concern by hand" below for the (more common) case of realizing
+  customization is needed *after* the model already exists.
+- **No `Endpoints::ModelName` by default** (per ADR 0001) — add one by hand, following the
+  `after_initialize` + `class_eval` pattern, only when a real custom action is needed.
 - **Test file generation is never suppressed** — a real Minitest file is generated, same
   as Rails' own `active_record:model` default.
 - **`rails generate active_record:model`/`active_record:migration` still work directly**
@@ -40,9 +50,60 @@ transparently apply thecore's scaffolding conventions — no new command vocabul
 
 Both `Thecore::Generators::ModelGenerator` and `MigrationGenerator` wrap (not reimplement)
 `ActiveRecord::Generators::ModelGenerator`/`MigrationGenerator` — all attribute parsing and
-template content is inherited as-is; only file placement and the two default concerns are
+template content is inherited as-is; only file placement and the two opt-in concerns are
 added on top.
 
+### Adding a concern by hand
+
+The common case is not knowing at `rails generate model` time that a model will need
+custom API serialization or RailsAdmin configuration — that need usually surfaces later.
+Since neither concern is generated by default, add the missing one directly instead of
+regenerating the model:
+
+**`Api::ModelName`** (custom `json_attrs`) — create `app/models/concerns/api/model_name.rb`:
+```ruby
+module Api::ModelName
+  extend ActiveSupport::Concern
+
+  included do
+    cattr_accessor :json_attrs
+    self.json_attrs = ::ModelDrivenApi.smart_merge(json_attrs || {}), { only: [:id, :name] }
+  end
+end
+```
+then `include Api::ModelName` in the model. Because the default module (`model_driven_api`'s
+`ModelDrivenApiDefaultJsonAttrs`) is already `include`d by the time the model class body
+runs, `::ModelDrivenApi.smart_merge(json_attrs || {}, ...)` composes on top of it rather
+than starting from nothing — the same pattern the opt-in `--with-api-concern` template
+below uses.
+
+**`RailsAdmin::ModelName`** (custom admin config) — create
+`app/models/concerns/rails_admin/model_name.rb`:
+```ruby
+module RailsAdmin::ModelName
+  extend ActiveSupport::Concern
+
+  included do
+    rails_admin do
+      navigation_label I18n.t('admin.registries.label')
+      navigation_icon 'fa fa-file' # see https://fontawesome.com/v5/search
+      configure :some_field do
+        hide
+      end
+    end
+  end
+end
+```
+then `include RailsAdmin::ModelName` in the model. RailsAdmin evaluates same-origin
+`rails_admin do ... end` blocks in registration order and later calls win on settings they
+touch (`navigation_label`/`navigation_icon` are last-write-wins setters) — so this explicit
+block, `include`d after the default from the class body, overrides the default's
+`navigation_label`/`navigation_icon` while the default itself keeps applying to every other
+model that has no concern of its own.
+
+Either concern can be added independently — a model doesn't need both just because it
+needs one.
+
 ## Installation
 
 Add to your host app's or ATOM's `Gemfile`:
@@ -55,12 +116,24 @@ gem "thecore_generators", "~> 3.0"
 
 Tests use a `Rails::Generators::TestCase`-based harness against the `test/dummy` Rails
 app included in this repo (needed to exercise generators the way a real host app would).
+`test/dummy` also boots real `model_driven_api`/`thecore_ui_rails_admin` (and their own
+transitive `thecore_backend_commons`/`thecore_auth_commons` dependencies) as temporary
+git-based dependencies — see the Gemfile's comment — purely so
+`test/generators/thecore/model_generator_default_concern_behavior_test.rb` can prove the
+no-concern default actually works at runtime, not just that no file was written.
 
 ```bash
 bundle install
 bundle exec rake test
 ```
 
+If your shell has `DATABASE_URL` set to a PostgreSQL URL (e.g. inside the Thecore
+devcontainer), unset it first — it overrides `test/dummy`'s own SQLite3 test config:
+
+```bash
+env -u DATABASE_URL bundle exec rake test
+```
+
 `bundle exec rake` alone runs the same suite (`test` is the default Rake task).
 
 To run a single test file:

data/lib/generators/thecore/model/model_generator.rb

@@ -14,11 +14,19 @@ module Thecore
     # generation are inherited as-is. On top of that:
     #   - Thecore::Generators::AtomAware redirects placement into an ATOM's
     #     app/models + db/migrate when one is detected (see its own docs).
-    #   - `Api::ModelName`/`RailsAdmin::ModelName` concern files are
-    #     generated and `include`d into the model, replicating
-    #     thecore_code_extension's addModel.js templates exactly (unchanged
-    #     by this ticket — see thecore_generators#3 / ADR 0001 in the thecore
-    #     repo).
+    #   - `Api::ModelName`/`RailsAdmin::ModelName` concern files are NOT
+    #     generated by default (thecore_generators#4 / ADR 0001 in the
+    #     thecore repo): the no-customization case now relies entirely on
+    #     the default `json_attrs`/`navigation_label`/`navigation_icon`
+    #     modules that `model_driven_api` and `thecore_ui_rails_admin`
+    #     `include` into every `ApplicationRecord` subclass automatically
+    #     (`ThecoreBackendCommons::DefaultModuleRegistry`). Pass
+    #     `--with-api-concern`/`--with-admin-concern` to scaffold a starter
+    #     concern file — identical in shape to what this generator produced
+    #     before this ticket — for the case where customization is already
+    #     known to be needed at generation time. To add one later instead
+    #     (the common case), see the "Adding a concern by hand" section of
+    #     this gem's README.
     #   - `Endpoints::ModelName` is deliberately NOT generated (ADR 0001: it's
     #     never `include`d by default; add it by hand, following the
     #     after_initialize + class_eval pattern, only when a real custom
@@ -29,6 +37,15 @@ module Thecore
     class ModelGenerator < ActiveRecord::Generators::ModelGenerator
       include Thecore::Generators::AtomAware
 
+      class_option :with_api_concern, type: :boolean, default: false,
+        desc: "Scaffold a starter app/models/concerns/api/<model>.rb, included into the model " \
+          "(pre-thecore_generators#4 default behavior). Opt in only when customization is " \
+          "already known to be needed at generation time."
+      class_option :with_admin_concern, type: :boolean, default: false,
+        desc: "Scaffold a starter app/models/concerns/rails_admin/<model>.rb, included into the " \
+          "model (pre-thecore_generators#4 default behavior). Opt in only when customization is " \
+          "already known to be needed at generation time."
+
       # `source_root` (singular) must be set explicitly: Rails::Generators::Base's
       # auto-computed `default_source_root` derives its path from *this*
       # class's own base_name/generator_name ("thecore"/"model"), which
@@ -42,30 +59,39 @@ module Thecore
 
       def create_model_file
         super
-        add_default_concerns
+        add_opted_in_concerns
       end
 
       private
 
       # Faithful Ruby port of addModel.js's api_concern.rb/rails_admin_concern.rb
       # templates and its `include Api::X` / `include RailsAdmin::X` model-file
-      # rewrite — down to the exact generated content — per this ticket's
-      # explicit "unchanged, still generated exactly as today" scope (that
-      # removal is thecore_generators#6, gated on other work landing first).
-      def add_default_concerns
-        template "api_concern.rb", File.join("app/models/concerns/api", class_path, "#{file_name}.rb")
-        template "rails_admin_concern.rb", File.join("app/models/concerns/rails_admin", class_path, "#{file_name}.rb")
+      # rewrite — down to the exact generated content — kept available behind
+      # `--with-api-concern`/`--with-admin-concern` for the explicit
+      # customization-at-generation-time case (thecore_generators#4).
+      def add_opted_in_concerns
+        include_lines = +""
+
+        if options[:with_api_concern]
+          template "api_concern.rb", File.join("app/models/concerns/api", class_path, "#{file_name}.rb")
+          include_lines << "  include Api::#{class_name}\n"
+        end
+
+        if options[:with_admin_concern]
+          template "rails_admin_concern.rb", File.join("app/models/concerns/rails_admin", class_path, "#{file_name}.rb")
+          include_lines << "  include RailsAdmin::#{class_name}\n"
+        end
 
-        include_default_concerns_in_model
+        include_opted_in_concerns_in_model(include_lines) unless include_lines.empty?
       end
 
-      def include_default_concerns_in_model
+      def include_opted_in_concerns_in_model(include_lines)
         model_file = File.join("app/models", class_path, "#{file_name}.rb")
         simple_class_name = class_name.split("::").last
 
         insert_into_file(
           model_file,
-          "  include Api::#{class_name}\n  include RailsAdmin::#{class_name}\n",
+          include_lines,
           after: /class #{Regexp.escape(simple_class_name)} < .*\n/
         )
       end

data/lib/thecore_generators/version.rb

@@ -1,3 +1,3 @@
 module ThecoreGenerators
-  VERSION = "3.1.0"
+  VERSION = "3.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thecore_generators
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Gabriele Tassoni