thecore_generators 3.2.0 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48198bd6f914066ca468eae2e95cb9dba85003d49532b1db28f8620db3c40b21
-  data.tar.gz: 7a3e542b82e0ff43691e3a988dad6e42f59fc51da0e460220e5481881eb55ba3
+  metadata.gz: b52de470428f2cecb91388721b140a88d6cdb0a1e0ea7b3ce07b0b855e17fbaa
+  data.tar.gz: 5a6147ac698f2820027e493bd8bdee96c13f39867dd50f6b472a495f5f01b829
 SHA512:
-  metadata.gz: 82748585f40f3f1e3975a3c1186d4bb98a3d8c4963ebcb495d9ba4c3c86701b2a48e981c28a6bfe220bd20b90fbcdacffa7e332b36edcbba2d4c3ab80e097e0d
-  data.tar.gz: ca82db7bdc678f66789b0ed9af24bf28f4f2253e2c025c3972118e602a86e662fc845863b098ba220d3163739c30b73f2588b30eb0aa8384300bc86a25adf013
+  metadata.gz: 52374b36988c76209702afb27c59e32ac95e05c53ca805914257264bb3eaae31ee06fa3329faae3a6da5c25742d31e136f470a22cf1897cdbd9a17caad010f97
+  data.tar.gz: 75083924ea8bdc22bf39d5dbea930da5ec5eb37d736107b43037e235d40a4430b0ae963a24133b9789631135de83b51cdfb1afd82515c4d2f0c69ddb43bb30a2

data/README.md

@@ -12,10 +12,16 @@ own `thecore:*`-namespaced generators or an application template. See
 in the thecore repo for the full design.
 
 **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)).
+[ADR 0002](https://github.com/gabrieletassoni/thecore/blob/release/3/docs/adr/0002-thecore-generators-gem-and-generator-hook-mechanism.md)),
+plus default-concern removal ([ADR 0001](https://github.com/gabrieletassoni/thecore/blob/release/3/docs/adr/0001-application-record-defaults-over-generated-concerns.md))
+and migration-driven inverse-association wiring
+([ADR 0003](https://github.com/gabrieletassoni/thecore/blob/release/3/docs/adr/0003-migration-driven-inverse-association-wiring.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.
+transparently apply thecore's scaffolding conventions — no new command vocabulary. **Phase 2
+(check_practices + Root/Member Action generators) is complete** as of this release: `rails
+generate thecore:root_action`, `rails generate thecore:member_action`, and `rails
+thecore:check_practices` (Scaffold Files + Models + Actions, `--fix` included) all ship.
 
 ### What `rails generate model`/`rails generate migration` do now
 
@@ -104,6 +110,148 @@ 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.
 
+### Inverse association wiring for `references` columns
+
+Rails' own generators only ever wire the owning (`belongs_to`) side of a `references`/
+`add_reference` column — the inverse `has_many`/`has_one` side has always been a manual
+follow-up. `rails generate model`/`migration` now write that missing inverse side
+automatically into the *target* model's own canonical concern
+(`config/initializers/concern_<target_model>.rb`, wired up via
+`config/initializers/after_initialize.rb`):
+
+```bash
+rails generate migration AddPostRefToComments post:references
+# → prompts: "Inverse association on Post for this reference (has_many/has_one/skip)?"
+# → writes `has_many :comments` into config/initializers/concern_post.rb
+```
+
+With a real terminal attached you're prompted for cardinality (`has_many` default, `has_one`,
+or `skip`); pass `--non-interactive` (always used by `addModel`/`addMigration` in the VS Code
+extension, and recommended for any other scripted/CI invocation) to skip the prompt and default
+straight to `has_many`. Re-running the generator against the same target model never duplicates
+an already-written association line, and a later, different reference onto the same target
+appends into the same existing concern file. When the target model lives in a different ATOM
+than the one being generated into, the concern is still written into the *invoking* app/ATOM
+(never the target's own) and the generator logs — but never edits — the gemspec/Gemfile
+dependency line a human needs to add so that include actually resolves. Full mechanics in
+`CLAUDE.md`.
+
+### `rails generate thecore:root_action NAME`
+
+A Ruby port of `thecore_code_extension`'s `addRootAction.js` — produces the same end result
+from a terminal, with the same ATOM-aware placement `rails generate model`/`migration` use:
+
+```bash
+rails generate thecore:root_action my_action
+```
+
+This creates:
+
+- The RailsAdmin action config file — `lib/root_actions/my_action.rb` in ATOM context,
+  `config/root_actions/my_action.rb` in host-app context (main-app actions never live under
+  `lib/`, for Zeitwerk autoload safety).
+- Its view/JS/SCSS companions: `app/views/rails_admin/main/my_action.html.erb`,
+  `app/assets/javascripts/rails_admin/actions/my_action.js`,
+  `app/assets/stylesheets/rails_admin/actions/my_action.scss`.
+- A `require` line inserted into `config/initializers/after_initialize.rb` (created from a
+  skeleton if absent) — `require 'root_actions/my_action'` in ATOM context, a full
+  `Rails.root.join(...)` require in host-app context (`config/` isn't on the load path).
+- A precompile line inserted into `config/initializers/assets.rb` (created from a skeleton if
+  absent).
+- An `admin.actions.my_action` locale entry (`menu`/`title`/`breadcrumb`, all set to the
+  title-cased action name) written into **every** `*.yml` file already present under
+  `config/locales` — `en.yml`/`it.yml` are created first only when the directory has none yet.
+
+`NAME` must be snake_case (lowercase letters, digits, underscores). `--atom=NAME` overrides
+placement the same way it does for `rails generate model`/`migration`. Re-running the
+generator against the same action name never duplicates the require line, the precompile
+line, or a locale entry.
+
+The reusable pieces behind this (`Thecore::Generators::CompanionFiles`,
+`Thecore::Generators::ActionCompanion`) are shared with `thecore:member_action` (below), and
+`check_practices --fix` (further below) delegates straight to both generators' own template
+rendering rather than reimplementing it.
+
+### `rails generate thecore:member_action NAME`
+
+The Member Action counterpart to `thecore:root_action` above — a Ruby port of
+`thecore_code_extension`'s `addMemberAction.js`, sharing everything about placement, the
+after_initialize.rb/assets.rb/locale mechanics, and even the generator implementation itself
+(`Thecore::Generators::ActionCompanion`) with Root Action:
+
+```bash
+rails generate thecore:member_action my_action
+```
+
+Same file layout as Root Action (`lib/member_actions/`/`config/member_actions/`,
+`app/views/rails_admin/main/my_action.html.erb`, `.../actions/my_action.js`/`.scss`,
+after_initialize.rb require line, assets.rb precompile line, every-locale-file entry,
+`--atom=NAME`, idempotent re-run). What differs is each action's own template content — not
+unified between the two, matching `addRootAction.js`/`addMemberAction.js`'s own separate
+templates exactly:
+
+- **`action.rb`** (server-side, the real behavioral difference) — a RailsAdmin `:member`
+  action (`http_methods [:get, :patch]`) whose controller branches on `request.xhr? &&
+  request.get?` (returns JSON) vs. `request.patch?` (a form submission, redirects back to the
+  record), instead of Root's single `:root` action with a fetch/JSON + `ActionCable.server.broadcast`
+  example.
+- **`action.js`/`action.html.erb`** — both still set up the same `ActivityLogChannel`
+  ActionCable subscription Root's do; only the test button's click handler differs (a plain
+  XHR `GET` here vs. `fetch` there), and the view adds a `form_with(..., method: :patch)` for
+  the PATCH half of the example.
+
+### `rails thecore:check_practices`
+
+A Ruby port of `thecore_code_extension`'s `checkPractices.js` — audits **Scaffold Files**
+(thecore_generators#13), **Models** (thecore_generators#13), and **Actions**
+(thecore_generators#14, `--fix` included).
+
+```bash
+rails thecore:check_practices                       # host app + every ATOM under vendor/submodules/
+rails thecore:check_practices -- --atom=my_atom      # scope to a single ATOM
+rails thecore:check_practices -- --json              # structured output for CI/the VS Code extension
+rails thecore:check_practices -- --fix               # apply every fixable violation, no confirmation
+```
+
+The `--` before any flag is the standard Rake convention for passing arguments through to a
+task instead of having Rake's own option parser reject them — see
+[Rake's own docs](https://ruby.github.io/rake/doc/rakefile_rdoc.html#label-Task+Arguments).
+Flags combine freely, e.g. `rails thecore:check_practices -- --atom=my_atom --fix --json`.
+
+- **Scaffold Files** — `config/initializers/after_initialize.rb` and `assets.rb` must exist
+  and carry their structural marker (`Rails.application.configure do` /
+  `Rails.application.config.assets.precompile`). Checked in **both** ATOM and host-app
+  context (`checkPractices.js` only ever checked ATOM context). Not fixable.
+- **Models** — rescoped per [ADR 0001](https://github.com/gabrieletassoni/thecore/blob/release/3/docs/adr/0001-application-record-defaults-over-generated-concerns.md):
+  a model with **no** `Api::`/`RailsAdmin::` concern is the correct, no-customization default
+  and is never flagged. Only two states are violations: a model `include`-ing a concern module
+  whose file doesn't exist (`orphan_api_include`/`orphan_rails_admin_include`), or a concern
+  file present but missing one of its required markers (`extend ActiveSupport::Concern` plus
+  `cattr_accessor :json_attrs` for `Api::`, `rails_admin do` for `RailsAdmin::`). Not fixable —
+  regenerating over an existing, hand-edited concern could clobber real customization.
+- **Actions** — scans `root_actions`, `member_actions`, and `collection_actions` (in `lib/` for
+  an ATOM, `config/` for the host app), with the same rules for all three:
+  `collection_actions` is scanned even though no generator creates files there yet, since a
+  hand-written one could already exist and go unreported otherwise. Reports missing/broken
+  action-file markers (`RailsAdmin::Config::Actions.add_action`, `http_methods` — never
+  fixable), a missing companion view/JS/SCSS or one present but missing its own marker (a
+  *missing* companion is fixable for `root_action`/`member_action`, by delegating straight to
+  that generator's own template rendering — never for `collection_action`, which has no
+  generator to delegate to; an *existing* companion missing a marker is never fixable, same
+  reasoning as Models), a missing `after_initialize.rb` require line (fixable, all three
+  kinds), and a missing locale entry checked against **every** `*.yml` already present in the
+  locales directory, not just `en`/`it` (fixable, all three kinds).
+
+Default output is human-readable text grouped by file; `--json` emits
+`{ "violations": [{ "file", "line", "message", "severity", "fixable", "code" }] }` — `code` is
+a stable identifier (e.g. `missing_after_initialize`, `orphan_api_include`,
+`missing_companion_view`) a future consumer can filter on without depending on `message` text.
+`--fix` applies every fixable violation in one pass with no confirmation of its own — whoever
+passes it has already decided — then re-scans and reports/exits based on whatever violations
+remain (so a violation this run can't fix, e.g. a `collection_action` companion, still shows up
+after `--fix`). The task exits non-zero whenever any violation remains, zero otherwise, so it's
+usable as a CI gate either with or without `--fix`.
+
 ## Installation
 
 Add to your host app's or ATOM's `Gemfile`:
@@ -142,6 +290,16 @@ To run a single test file:
 bundle exec ruby -Itest test/generators/thecore/model_generator_test.rb
 ```
 
+## Who depends on this
+
+The host backend app's own `Gemfile` (`:development` group) and the
+[Thecore VS Code extension](https://github.com/gabrieletassoni/thecore_code_extension)'s
+`addModel`/`addMigration` commands both depend on this gem being present to get Thecore-aware
+`rails generate` behavior — the extension actually checks for it and offers to add it
+automatically if it's missing, since without it `rails generate model`/`migration` still "work"
+but silently skip every convention described above. See `CLAUDE.md`'s "Who consumes this gem"
+section for detail.
+
 ## Releasing
 
 Version lives in `lib/thecore_generators/version.rb`. Pushing a commit that bumps it

data/lib/generators/thecore/action_companion.rb

@@ -0,0 +1,116 @@
+module Thecore
+  module Generators
+    # Shared helper logic for Thecore's own per-action generators
+    # (RootActionGenerator - thecore_generators#11, MemberActionGenerator -
+    # thecore_generators#12): everything about them that is NOT the action
+    # file's own RailsAdmin action type/template content, and not a Thor
+    # *task* method itself.
+    #
+    # Thor::Group (which Rails::Generators::Base/NamedBase extends)
+    # discovers its task list via a `method_added` hook that only fires for
+    # methods defined directly, via `def`, in the generator class's own
+    # body - never for methods a class merely picks up through `include`.
+    # So each of `validate_action_name!`/`create_action_file`/
+    # `create_view_js_scss_companions`/`add_after_initialize_require`/
+    # `add_assets_precompile_line`/`add_locale_entries` must still be a
+    # thin method defined directly on RootActionGenerator/
+    # MemberActionGenerator themselves (identical one-liners in both); only
+    # the private logic those methods delegate to lives here.
+    #
+    # Extracted once both generators existed and turned out identical apart
+    # from that thin task-method layer and their directory name
+    # ("root_actions"/"member_actions") - not a speculative abstraction
+    # built ahead of a second user.
+    #
+    # The including class must declare `action_kind "root_action"` (or
+    # `"member_action"`) at the class body level, which derives both the
+    # directory name (pluralized: "root_actions"/"member_actions") and the
+    # wording used in the name-validation error message.
+    module ActionCompanion
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Shared require-line text for an action's `after_initialize.rb`
+      # registration - `lib/<kind>s/<name>` in ATOM context (on the load
+      # path via the gemspec), a full `Rails.root.join('config', ...)` path
+      # in host-app context (`config/` isn't on the load path). A plain
+      # module method (not routed through `ClassMethods`/`extend`, unlike
+      # `action_kind` below) so it's callable directly as
+      # `Thecore::Generators::ActionCompanion.require_line_for(...)` without
+      # an including generator instance - used both by `require_line` below
+      # (via a real generator's own `atom_dir`/`file_name`) and directly by
+      # `Thecore::CheckPractices`' Actions check, so the audit's own
+      # expectation can never drift out of sync with what a real Root/Member
+      # Action generator actually writes.
+      def self.require_line_for(kind:, in_atom:, name:)
+        dir_name = "#{kind}s"
+        if in_atom
+          "require '#{dir_name}/#{name}'"
+        else
+          "require Rails.root.join('config', '#{dir_name}', '#{name}').to_s"
+        end
+      end
+
+      # A class-level accessor, not an instance `define_method`, and
+      # deliberately so: any *instance* method this DSL defined directly on
+      # the including generator class - even a private one, since Thor's
+      # `method_added` hook fires and registers it as a task at the moment
+      # `define_method` returns, before a later `private` call could demote
+      # it - would itself become a spurious Thor task (this was tried and
+      # caught via `RootActionGenerator.all_tasks.keys` including
+      # "action_kind" as an actual, if harmless, generator step). Storing
+      # the value in a class-level ivar instead, read back via
+      # `self.class.action_kind` from the private instance methods below,
+      # adds no method to the generator class's own instance side at all.
+      module ClassMethods
+        def action_kind(value = nil)
+          @action_kind = value unless value.nil?
+          @action_kind
+        end
+      end
+
+      private
+
+      def validate_action_name_for_kind!
+        return if name.match?(/\A[a-z_][a-z0-9_]*\z/)
+
+        raise Thor::Error,
+          "'#{name}' is not a valid #{self.class.action_kind.tr("_", " ")} name - use " \
+          "snake_case, starting with a lowercase letter or underscore (a leading digit would " \
+          "make the generated `topic: :#{name}` symbol invalid Ruby)."
+      end
+
+      def action_dir_name
+        "#{self.class.action_kind}s"
+      end
+
+      # lib/<action_dir_name> in ATOM context (on the load path via the
+      # gemspec), config/<action_dir_name> in host-app context (not on the
+      # load path, hence the full-path require in `require_line` below) -
+      # see docs/adr/0001-main-app-actions-live-in-config.md in
+      # thecore_code_extension.
+      def action_file_path
+        base_dir = atom_dir ? "lib" : "config"
+        File.join(base_dir, action_dir_name, "#{file_name}.rb")
+      end
+
+      def require_line
+        ActionCompanion.require_line_for(kind: self.class.action_kind, in_atom: !atom_dir.nil?, name: file_name)
+      end
+
+      def assets_precompile_line
+        "Rails.application.config.assets.precompile += %w( rails_admin/actions/#{file_name}.js " \
+          "rails_admin/actions/#{file_name}.css )"
+      end
+
+      def action_name_camel_case
+        file_name.downcase.gsub(/[-_]([a-z0-9])/) { Regexp.last_match(1).upcase }
+      end
+
+      def title_case_name
+        file_name.split("_").map(&:capitalize).join(" ")
+      end
+    end
+  end
+end

data/lib/generators/thecore/association_wiring.rb

@@ -0,0 +1,217 @@
+require "generators/thecore/workspace_context"
+
+module Thecore
+  module Generators
+    # Implements ADR 0003 in the thecore repo
+    # (docs/adr/0003-migration-driven-inverse-association-wiring.md):
+    # Rails' own migration generator only ever wires the owning (`belongs_to`)
+    # side of a `references`/`add_reference` column — the inverse
+    # (`has_many`/`has_one`) has always been manual. This module detects
+    # `references` attributes on the migration being generated and writes the
+    # missing inverse side into the *target* model's canonical per-model
+    # concern, following the cross-ATOM extension pattern GUIDE.md §4.5
+    # already documents (`config/initializers/concern_<model>.rb` plus a
+    # `TargetModel.send(:include, ...)` registered in
+    # `config/initializers/after_initialize.rb`).
+    #
+    # Included by both Thecore::Generators::MigrationGenerator (standalone
+    # `rails generate migration ... x:references`) and
+    # Thecore::Generators::ModelGenerator (`rails generate model Foo
+    # x:references` delegates its own migration creation to
+    # ActiveRecord::Generators::ModelGenerator#create_migration_file, a
+    # *different* method than MigrationGenerator's own, so both host classes
+    # need their own hook). Both wire it the same way: override
+    # `create_migration_file`, call `super`, then
+    # `wire_inverse_associations_from_references` — matching the
+    # override-and-call-super style Thecore::Generators::ModelGenerator
+    # already uses for `create_model_file`/`add_default_concerns`.
+    #
+    # Requires the includer to already provide (directly or via
+    # Thecore::Generators::AtomAware, included by both host classes):
+    #   - `attributes` — Rails::Generators::GeneratedAttribute array (from
+    #     ActiveRecord's own migration/model generator `argument`)
+    #   - `table_name` — Rails::Generators::NamedBase; memoized into
+    #     @table_name, which for MigrationGenerator is populated by
+    #     ActiveRecord's own `set_local_assigns!` (run during `super`) from
+    #     the migration's file name (`add_x_to_y`/`create_y`), and for
+    #     ModelGenerator resolves directly from the model's own class name -
+    #     either way it names the table/model *gaining* the reference.
+    #   - `destination_root`/`host_app_root` — Thecore::Generators::AtomAware
+    module AssociationWiring
+      HEADER_COMMENT = <<~RUBY.freeze
+        # This file is maintained by thecore_generators (migration generator's
+        # inverse-association wiring - see
+        # docs/adr/0003-migration-driven-inverse-association-wiring.md in the
+        # thecore repo). Associations below are appended automatically whenever
+        # a `references` column targeting this model is added elsewhere.
+        # Do not hand-edit the generated section: a future generator run may
+        # append to it again, and hand edits are not accounted for.
+      RUBY
+
+      AFTER_INITIALIZE_TEMPLATE = <<~RUBY.freeze
+        Rails.application.configure do
+            config.after_initialize do
+            end
+        end
+      RUBY
+
+      def self.included(base)
+        base.class_option :non_interactive, type: :boolean, default: false,
+          desc: "Skip the inverse-association cardinality prompt and default to has_many " \
+                "(no real TTY is available to CI or scripted invocations, e.g. the VS Code " \
+                "extension)"
+      end
+
+      private
+
+      # Entry point, called after `super` from the includer's own
+      # `create_migration_file` override.
+      def wire_inverse_associations_from_references
+        return if options[:migration] == false # ModelGenerator's --no-migration
+        return if attributes.nil?
+
+        owning_table_name = table_name
+        return if owning_table_name.blank?
+
+        reference_attributes = attributes.select(&:reference?)
+        return if reference_attributes.empty?
+
+        reference_attributes.each { |attribute| wire_inverse_association(owning_table_name, attribute) }
+      end
+
+      def wire_inverse_association(owning_table_name, attribute)
+        target_class_name = attribute.singular_name.camelize
+        cardinality = prompt_cardinality_for(target_class_name)
+        return if cardinality == :skip
+
+        association_line = association_line_for(cardinality, owning_table_name)
+        write_target_concern(target_class_name, association_line)
+        register_after_initialize(target_class_name)
+        log_cross_boundary_dependency(target_class_name)
+      end
+
+      def association_line_for(cardinality, owning_table_name)
+        if cardinality == :has_one
+          "has_one :#{owning_table_name.singularize}"
+        else
+          "has_many :#{owning_table_name}"
+        end
+      end
+
+      def prompt_cardinality_for(target_class_name)
+        return :has_many unless interactive_association_prompt?
+
+        answer = ask(
+          "Inverse association on #{target_class_name} for this reference " \
+          "(has_many/has_one/skip)?",
+          default: "has_many",
+          limited_to: %w[has_many has_one skip]
+        )
+        answer.to_s.strip.to_sym
+      end
+
+      # No real TTY is present for CI/scripted/extension invocations (or the
+      # includer was explicitly told not to prompt via --non-interactive) -
+      # default straight to has_many, per ADR 0003.
+      def interactive_association_prompt?
+        !options[:non_interactive] && $stdin.tty? && $stdout.tty?
+      end
+
+      def concern_path_for(target_class_name)
+        "config/initializers/concern_#{target_class_name.underscore}.rb"
+      end
+
+      def concern_module_name_for(target_class_name)
+        "Concern#{target_class_name}"
+      end
+
+      def write_target_concern(target_class_name, association_line)
+        concern_path = concern_path_for(target_class_name)
+
+        if File.exist?(File.join(destination_root, concern_path))
+          insert_association_into_existing_concern(concern_path, association_line)
+        else
+          create_concern_file(concern_path, concern_module_name_for(target_class_name), association_line)
+        end
+      end
+
+      def create_concern_file(concern_path, concern_module_name, association_line)
+        content = <<~RUBY
+          #{HEADER_COMMENT}
+          module #{concern_module_name}
+            extend ActiveSupport::Concern
+
+            included do
+              #{association_line}
+            end
+          end
+        RUBY
+
+        create_file(concern_path, content)
+      end
+
+      def insert_association_into_existing_concern(concern_path, association_line)
+        full_path = File.join(destination_root, concern_path)
+        content = File.read(full_path)
+
+        if content.match?(/^\s*#{Regexp.escape(association_line)}\s*$/)
+          say_status :skip, "#{concern_path} already has `#{association_line}`", :blue
+          return
+        end
+
+        insert_into_file(concern_path, "    #{association_line}\n", after: /included do\n/)
+      end
+
+      def register_after_initialize(target_class_name)
+        path = "config/initializers/after_initialize.rb"
+        full_path = File.join(destination_root, path)
+
+        create_file(path, AFTER_INITIALIZE_TEMPLATE) unless File.exist?(full_path)
+
+        registration_line = "#{target_class_name}.send(:include, #{concern_module_name_for(target_class_name)})"
+        content = File.read(full_path)
+        return if content.include?(registration_line)
+
+        insert_into_file(path, "        #{registration_line}\n", after: /config\.after_initialize do\n/)
+      end
+
+      # Cross-boundary case (ADR 0003): the concern always lives in the
+      # invoking app/ATOM (destination_root), never the target model's own -
+      # so when the target model actually lives elsewhere, the generated
+      # `TargetModel.send(:include, ...)` line depends on that model's
+      # constant being loaded, which requires a real gem/path dependency a
+      # human has to add. We only log it — never edit a gemspec/Gemfile.
+      def log_cross_boundary_dependency(target_class_name)
+        target_root = Thecore::Generators::WorkspaceContext.model_root_for(
+          class_name: target_class_name, app_root: host_app_root
+        )
+        return if target_root.nil? || target_root == destination_root
+
+        own_is_atom = destination_root != host_app_root
+        target_is_atom = target_root != host_app_root
+        own_label = own_is_atom ? File.basename(destination_root) : "the host app"
+        target_label = target_is_atom ? File.basename(target_root) : "the host app"
+
+        message = "Cross-boundary reference: #{target_class_name} lives in #{target_label}, but the " \
+          "generated concern was written into #{own_label} (ADR 0003: the concern always lives in the " \
+          "invoking app/ATOM). #{dependency_hint(own_is_atom, target_is_atom, target_root)}"
+
+        say_status :dependency, message, :yellow
+      end
+
+      def dependency_hint(own_is_atom, target_is_atom, target_root)
+        target_gem_name = File.basename(target_root)
+
+        if own_is_atom && target_is_atom
+          "Add a gem dependency in this ATOM's gemspec, e.g.: spec.add_dependency \"#{target_gem_name}\""
+        elsif !own_is_atom && target_is_atom
+          "Add a Gemfile dependency in the host app, e.g.: gem \"#{target_gem_name}\", " \
+            "path: \"vendor/submodules/#{target_gem_name}\""
+        else
+          "The target model lives in the host app; confirm this ATOM is meant to reference host-app " \
+            "code directly (no gemspec/Gemfile dependency line applies here)."
+        end
+      end
+    end
+  end
+end

data/lib/generators/thecore/atom_aware.rb

@@ -30,21 +30,32 @@ module Thecore
 
       def initialize(*args)
         super
+        @host_app_root = destination_root
         self.destination_root = atom_dir if atom_dir
       end
 
+      # The true host-app root, captured before `destination_root` is
+      # (possibly) overridden above — for a real `rails generate` invocation
+      # this is `Rails::Command.root`, in tests whatever
+      # `Rails::Generators::TestCase` configured as `destination_root`.
+      # Unlike `destination_root` (which becomes the ATOM dir once
+      # overridden), this always stays the app root, giving
+      # Thecore::Generators::WorkspaceContext.model_root_for a stable anchor
+      # to search from regardless of where *this* invocation itself landed.
+      attr_reader :host_app_root
+
       # 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`.
+      # pre-override `destination_root` (== `host_app_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,
+          app_root: host_app_root,
           atom_name: options[:atom]
         )
       end