thecore_generators 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f829a0f19f22655ce14f10be2c9c748dd67acc8a9432aced696cd9ca3ba7f8a
-  data.tar.gz: '08b6468f673411496eab954f7d2511c4345242aa5aa1a020d7a3860ad42580bc'
+  metadata.gz: 6e0af52a7399d45699c4b84d80cead588d71f37e255bfa324141d8a0033aa561
+  data.tar.gz: 241b9957c4a166c010d78c5f1175b98bc802eb28f4757131fc69d1c1d4e24e2d
 SHA512:
-  metadata.gz: 92ad6a86068b45d71a7a077cee5c083fb893724767314bb49d914a567cd09b4708091c97fa7d5772470e4f37bd068447f63b9b600081807fa73ed842455f9353
-  data.tar.gz: 1e5430b20ea00057c7dea7b48736c31f2cbc64dc236550fc5957d90874dd3d42b1435968fb996bfcb2022ad9d3b7fe4b4cf79bcf6f4bd5b1fad358a9c0388cfa
+  metadata.gz: 736b763f3dbf6508d97e14b934240b2420db7da18b5e0eda0fd1c6c987e76e26ff3c36ea6a0c3c9d03ed6bf89fef1be5ad631303d38978fc52df021d0c717002
+  data.tar.gz: 32bb39ef9cdc30d2023986db40e487a36869555ba3ac02582bb8ba9d89622d1030ed4ce2f9be8b043cf2e521dac1f08f3c1805c4ef389a092c362b157952164d

data/README.md

@@ -11,10 +11,37 @@ own `thecore:*`-namespaced generators or an application template. See
 [`docs/adr/0002-thecore-generators-gem-and-generator-hook-mechanism.md`](https://github.com/gabrieletassoni/thecore/blob/release/3/docs/adr/0002-thecore-generators-gem-and-generator-hook-mechanism.md)
 in the thecore repo for the full design.
 
-**Status:** bootstrap only. This release makes the gem buildable, testable, and
-publishable — it ships no generator behaviour yet. `ThecoreGenerators::Railtie`
-(`lib/thecore_generators/railtie.rb`) is a deliberate no-op; the `config.app_generators.orm`
-hook lands in a follow-up ticket.
+**Status:** Model + Migration generator hook (Phase 1 of
+[ADR 0002](https://github.com/gabrieletassoni/thecore/blob/release/3/docs/adr/0002-thecore-generators-gem-and-generator-hook-mechanism.md)).
+`ThecoreGenerators::Railtie` registers `config.app_generators.orm :thecore, migration:
+true, timestamps: true`, so plain `rails generate model`/`rails generate migration`
+transparently apply thecore's scaffolding conventions — no new command vocabulary.
+
+### What `rails generate model`/`rails generate migration` do now
+
+- **Context-aware placement.** `Thecore::Generators::WorkspaceContext` detects whether
+  the invoking process's `Dir.pwd` is inside a host app or an ATOM (`vendor/submodules/<atom>/`,
+  by gemspec presence — a Ruby port of `thecore_code_extension`'s `workspaceContext.js`).
+  When an ATOM is detected, the model/migration/test files land inside that ATOM's own
+  `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
+  [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.
+- **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**
+  as an escape hatch, entirely unaffected by the hook above.
+
+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
+added on top.
 
 ## Installation
 
@@ -39,7 +66,7 @@ bundle exec rake test
 To run a single test file:
 
 ```bash
-bundle exec ruby -Itest test/generators/placeholder_generator_test.rb
+bundle exec ruby -Itest test/generators/thecore/model_generator_test.rb
 ```
 
 ## Releasing

data/lib/generators/thecore/atom_aware.rb

@@ -0,0 +1,59 @@
+require "generators/thecore/workspace_context"
+
+module Thecore
+  module Generators
+    # Shared by Thecore::Generators::ModelGenerator and MigrationGenerator:
+    # redirects file placement into an ATOM directory when
+    # Thecore::Generators::WorkspaceContext detects one (from `Dir.pwd` or an
+    # explicit `--atom=NAME`), and otherwise leaves the wrapped ActiveRecord
+    # generator's own placement (relative to `destination_root`, already the
+    # host app root for a real `rails generate` invocation) untouched.
+    #
+    # Two distinct placement mechanisms need covering, since ActiveRecord's
+    # generators don't derive both from `destination_root`:
+    #   - Model/module/test files are `template`d at paths relative to
+    #     `destination_root` — overriding `destination_root` itself (in
+    #     `initialize`) redirects all of these, including the file the
+    #     inherited `hook_for :test_framework` generates, since Thor's
+    #     `_shared_configuration` passes the (already-overridden)
+    #     `destination_root` on to hooked generators automatically.
+    #   - The migration file's directory instead comes from
+    #     `ActiveRecord::Generators::Migration#db_migrate_path`, computed from
+    #     `Rails.application.config.paths["db/migrate"]` — i.e. always the
+    #     real app root, regardless of `destination_root`. This must be
+    #     overridden separately.
+    module AtomAware
+      def self.included(base)
+        base.class_option :atom, type: :string, default: nil,
+          desc: "Explicit ATOM name (under vendor/submodules/) to target, overriding cwd-based detection"
+      end
+
+      def initialize(*args)
+        super
+        self.destination_root = atom_dir if atom_dir
+      end
+
+      # The absolute ATOM directory this generator's files should land in, or
+      # nil for plain host-app context. Resolved once, before
+      # `destination_root` is (possibly) overridden above, since the
+      # pre-override `destination_root` is the correct app-root anchor for
+      # resolving an explicit `--atom=NAME`.
+      def atom_dir
+        return @atom_dir if @atom_dir_resolved
+
+        @atom_dir_resolved = true
+        @atom_dir = Thecore::Generators::WorkspaceContext.atom_dir_for(
+          cwd: Dir.pwd,
+          app_root: destination_root,
+          atom_name: options[:atom]
+        )
+      end
+
+      private
+
+      def db_migrate_path
+        atom_dir ? File.join(atom_dir, "db", "migrate") : super
+      end
+    end
+  end
+end

data/lib/generators/thecore/migration/migration_generator.rb

@@ -0,0 +1,25 @@
+require "rails/generators/active_record/migration/migration_generator"
+require "generators/thecore/atom_aware"
+
+module Thecore
+  module Generators
+    # Resolved automatically by plain `rails generate migration` once
+    # ThecoreGenerators::Railtie registers `config.app_generators.orm
+    # :thecore, ...` (namespace "thecore:migration" — see
+    # Thecore::Generators::ModelGenerator for the namespace-resolution
+    # mechanism, identical here).
+    #
+    # A pure wrap: 100% of ActiveRecord::Generators::MigrationGenerator's
+    # migration-content logic (add/remove/create-table detection, attribute
+    # parsing, templates) is inherited untouched. The only addition is
+    # Thecore::Generators::AtomAware, redirecting the migration file into an
+    # ATOM's db/migrate when one is detected from `Dir.pwd`/`--atom=NAME`, so
+    # `rails generate migration AddBarToFoo bar:string` gets the same
+    # context-aware placement standalone, not just via `rails generate model`.
+    class MigrationGenerator < ActiveRecord::Generators::MigrationGenerator
+      include Thecore::Generators::AtomAware
+
+      source_root ActiveRecord::Generators::MigrationGenerator.source_root
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+require "rails/generators/active_record/model/model_generator"
+require "generators/thecore/atom_aware"
+
+module Thecore
+  module Generators
+    # Resolved automatically by plain `rails generate model` once
+    # ThecoreGenerators::Railtie registers `config.app_generators.orm
+    # :thecore, ...` (namespace "thecore:model", derived from this class's
+    # own module nesting the same way ActiveRecord::Generators::ModelGenerator
+    # resolves to "active_record:model" — see Rails::Generators::Base#namespace).
+    #
+    # Wraps (does not reimplement) ActiveRecord's own model generator: all
+    # attribute parsing, the model/module templates, and migration-content
+    # 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).
+    #   - `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
+    #     action is needed).
+    #   - Test file generation is never suppressed (no `--skip-test-framework`
+    #     equivalent) — `hook_for :test_framework` runs exactly as it does for
+    #     `active_record:model`.
+    class ModelGenerator < ActiveRecord::Generators::ModelGenerator
+      include Thecore::Generators::AtomAware
+
+      # `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
+      # doesn't exist on disk — so it silently resolves to nil unless
+      # pointed at ActiveRecord's own directory here. Our own
+      # api_concern.rb.tt/rails_admin_concern.rb.tt templates live alongside
+      # this file and are added to `source_paths` (plural) separately, since
+      # `source_root` only holds one path.
+      source_paths.unshift(File.expand_path("templates", __dir__))
+      source_root ActiveRecord::Generators::ModelGenerator.source_root
+
+      def create_model_file
+        super
+        add_default_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")
+
+        include_default_concerns_in_model
+      end
+
+      def include_default_concerns_in_model
+        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",
+          after: /class #{Regexp.escape(simple_class_name)} < .*\n/
+        )
+      end
+    end
+  end
+end

data/lib/generators/thecore/model/templates/api_concern.rb.tt

@@ -0,0 +1,19 @@
+module Api::<%= class_name %>
+  extend ActiveSupport::Concern
+
+  included do
+    # Use self.json_attrs to drive json rendering for
+    # API model responses (index, show and update ones).
+    # For reference:
+    # https://api.rubyonrails.org/classes/ActiveModel/Serializers/JSON.html
+    # The object passed accepts only these keys:
+    # - only: list [] of model fields to be shown in JSON serialization
+    # - except: exclude these fields from the JSON serialization, is a list []
+    # - methods: include the result of some method defined in the model
+    # - include: include associated models, it's an object {} which also accepts the keys described here
+    cattr_accessor :json_attrs
+    self.json_attrs = ::ModelDrivenApi.smart_merge (json_attrs || {}), {}
+
+    # Custom action callable by the API must be defined in /app/models/concerns/endpoints/
+  end
+end

data/lib/generators/thecore/model/templates/rails_admin_concern.rb.tt

@@ -0,0 +1,10 @@
+module RailsAdmin::<%= class_name %>
+  extend ActiveSupport::Concern
+
+  included do
+    rails_admin do
+      navigation_label I18n.t('admin.registries.label')
+      navigation_icon 'fa fa-file' # TODO: customize icon, see https://fontawesome.com/v5/search
+    end
+  end
+end

data/lib/generators/thecore/workspace_context.rb

@@ -0,0 +1,107 @@
+require "thor/error"
+
+module Thecore
+  module Generators
+    # Ruby port of thecore_code_extension's libs/workspaceContext.js
+    # (specifically its `atomRootOf`/`hasGemspec` gemspec-presence-under-
+    # vendor/submodules detection). The extension resolved context from a
+    # right-clicked VS Code folder; here we resolve it from the invoking
+    # process's `Dir.pwd`, since a terminal has no clicked folder — see
+    # docs/adr/0002-thecore-generators-gem-and-generator-hook-mechanism.md in
+    # the thecore repo.
+    #
+    # There is no AppContext/ATOMContext class pair here (unlike the JS
+    # original): a generator only ever needs one thing from this module — the
+    # absolute ATOM directory to redirect file placement to, or `nil` when
+    # `cwd` (and no `--atom` override) resolves to plain host-app context, in
+    # which case the generator leaves Rails' own default placement (relative
+    # to `destination_root`, already the app root for a real `rails generate`
+    # invocation) untouched.
+    module WorkspaceContext
+      module_function
+
+      # Returns the absolute ATOM directory for placement, or nil for
+      # host-app context.
+      #
+      # `atom_name`, when present (a generator's `--atom=NAME` option), is an
+      # explicit override that skips `cwd`-based detection entirely and is
+      # resolved as `<app_root>/vendor/submodules/<atom_name>` instead — this
+      # is what lets `--atom=NAME` work "from anywhere", independent of `cwd`.
+      # `app_root` is the generator's own (pre-override) `destination_root`:
+      # for a real `rails generate` invocation that is already
+      # `Rails::Command.root` (see rails/commands/generate/generate_command.rb),
+      # and in tests it's whatever `Rails::Generators::TestCase` configured as
+      # `destination_root` — either way it's the correct anchor without this
+      # module needing its own notion of "the app root".
+      def atom_dir_for(cwd:, app_root:, atom_name: nil)
+        atom_name = atom_name.to_s.strip
+        return resolve_named_atom(app_root, atom_name) unless atom_name.empty?
+
+        resolve_cwd_atom(cwd)
+      end
+
+      # Walks up from `dir` until the immediate parent directory is
+      # `vendor/submodules` — that child is the ATOM root. Mirrors
+      # workspaceContext.js's `atomRootOf`. Returns nil if `dir` is not
+      # inside a `vendor/submodules/<atom>/` tree at all.
+      def atom_root_of(dir)
+        current = File.expand_path(dir.to_s)
+
+        loop do
+          parent = File.dirname(current)
+          return nil if parent == current # reached the filesystem root
+
+          if File.basename(parent) == "submodules" && File.basename(File.dirname(parent)) == "vendor"
+            return current
+          end
+
+          current = parent
+        end
+      end
+
+      # Ported from workspaceContext.js's `hasGemspec`: an ATOM directory is
+      # valid when it contains `<dirname>.gemspec` or, since gem names can't
+      # contain dashes, the dash-to-underscore variant of it.
+      def gemspec_path_for(atom_dir)
+        atom_name = File.basename(atom_dir)
+
+        [atom_name, atom_name.tr("-", "_")].each do |candidate|
+          path = File.join(atom_dir, "#{candidate}.gemspec")
+          return path if File.exist?(path)
+        end
+
+        nil
+      end
+
+      def valid_atom_dir?(atom_dir)
+        File.directory?(atom_dir) && !gemspec_path_for(atom_dir).nil?
+      end
+
+      class << self
+        private
+
+        def resolve_named_atom(app_root, atom_name)
+          candidate = File.join(app_root.to_s, "vendor", "submodules", atom_name)
+          return candidate if valid_atom_dir?(candidate)
+
+          raise Thor::Error,
+            "No ATOM named '#{atom_name}' found at #{candidate} " \
+            "(expected a #{atom_name}.gemspec or #{atom_name.tr('-', '_')}.gemspec inside it)."
+        end
+
+        def resolve_cwd_atom(cwd)
+          candidate = atom_root_of(cwd)
+          return nil unless candidate
+
+          unless valid_atom_dir?(candidate)
+            raise Thor::Error,
+              "#{candidate} is under vendor/submodules/ but has no gemspec - " \
+              "not a valid Thecore ATOM."
+          end
+
+          candidate
+        end
+      end
+    end
+  end
+end

data/lib/thecore_generators/railtie.rb

@@ -1,13 +1,25 @@
+require "rails/railtie"
+
 module ThecoreGenerators
-  # Boot-time hook point for this gem. Intentionally empty for now: no
-  # generator behaviour ships in this release. A future ticket will add
+  # Hooks `rails generate model`/`rails generate migration` the same way
+  # ActiveRecord's own Railtie does (`config.app_generators.orm :active_record,
+  # migration: true, timestamps: true` in active_record/railtie.rb) and Mongoid
+  # does for its own ORM. Registering this at the class body level — not inside
+  # an `initializer` block — matters: `config.app_generators` is a process-wide
+  # singleton (`Rails::Railtie::Configuration#app_generators`) copied into
+  # `Rails::Generators.options` early during boot, so this must run at require
+  # time, exactly mirroring ActiveRecord's own placement, to reliably win by
+  # require order (see docs/adr/0002-thecore-generators-gem-and-generator-hook-mechanism.md
+  # in the thecore repo).
   #
-  #   config.app_generators.orm :thecore, migration: true, timestamps: true
-  #
-  # here, following the same mechanism ActiveRecord's own Railtie and
-  # Mongoid both use to hook `rails generate model`/`migration` (see
-  # docs/adr/0002-thecore-generators-gem-and-generator-hook-mechanism.md in
-  # the thecore repo).
+  # This makes plain `rails generate model`/`rails generate migration` resolve
+  # to Thecore::Generators::ModelGenerator/MigrationGenerator (namespaces
+  # "thecore:model"/"thecore:migration") instead of ActiveRecord's own
+  # generators, with zero new command vocabulary for developers.
+  # `rails generate active_record:model`/`active_record:migration` remain
+  # available directly as an escape hatch — Rails only hides the override from
+  # `--help`, it never blocks direct namespace invocation.
   class Railtie < ::Rails::Railtie
+    config.app_generators.orm :thecore, migration: true, timestamps: true
   end
 end

data/lib/thecore_generators/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thecore_generators
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Gabriele Tassoni
@@ -36,6 +36,12 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- lib/generators/thecore/atom_aware.rb
+- lib/generators/thecore/migration/migration_generator.rb
+- lib/generators/thecore/model/model_generator.rb
+- lib/generators/thecore/model/templates/api_concern.rb.tt
+- lib/generators/thecore/model/templates/rails_admin_concern.rb.tt
+- lib/generators/thecore/workspace_context.rb
 - lib/thecore_generators.rb
 - lib/thecore_generators/railtie.rb
 - lib/thecore_generators/version.rb