ecs_on_rails 0.2.1

data/lib/ecs_rails/relationships.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+# #constantize is load-bearing for reload safety: relationship metadata stores
+# the backing and target class *names* (strings) and resolves them on read, so a
+# reloaded constant is picked up — the same discipline as the registry
+# (RFC-0002). Required explicitly rather than relying on ActiveRecord.
+require "active_support/core_ext/string/inflections"
+
+module EcsRails
+  # The class-level DSL for cross-entity links: `relates_to`.
+  #
+  # Implements RFC-0012, decided by ADR-0013. Extended into EcsRails::Entity,
+  # alongside the `component` DSL it is built on. Surfaced by the demo, where
+  # `Authorship`, `MemberUser` and `MemberGroup` were each *nothing but* a
+  # `belongs_to` in a component, plus a `component` declaration and a migration.
+  #
+  #   class Post < ApplicationEntity
+  #     relates_to :author, User
+  #   end
+  #
+  #   class Membership < ApplicationEntity
+  #     relates_to :user, User
+  #     relates_to :team, Team
+  #     component Role
+  #   end
+  #
+  #   post.author = user   # writer   (delegated from the backing belongs_to)
+  #   post.author          # => the User (delegated)
+  #   post.author_relationship  # => the backing component row (the reader)
+  #
+  # `relates_to` writes no relationship component file. It defines the backing
+  # component dynamically and then declares it with `component`, so the whole
+  # RFC-0004/0005/0006/0009/0010/0011 stack applies for free: registry, lazy
+  # reader, delegation, `with_component`, presence, `includes_components`.
+  #
+  # ## How the backing component is built (ADR-0013)
+  #
+  # `relates_to :author, User` on `Post` dynamically defines
+  # `Post::AuthorRelationship`, a concrete EcsRails::Component subclass, with:
+  #   - `table_name = "post_authors"` — `#{entity.singular}_#{relation.plural}`,
+  #     owner-scoped so it is collision-free by construction (ADR-0013),
+  #   - `belongs_to :author, class_name: "User", foreign_key: :author_id,
+  #     optional: true` — the target link, optional so an unset relationship is
+  #     valid (ADR-0003).
+  #
+  # Then it runs `component Post::AuthorRelationship`. Delegation surfaces the
+  # `belongs_to` as `post.author` / `post.author=`; the backing component's own
+  # reader is `post.author_relationship`. There is no reader collision, because
+  # the component is named for the *relationship* and the association for the
+  # *target* — the rule the ADR-0006 amendment arrived at the hard way.
+  #
+  # ## The reader name (RFC-0012 Open, resolved)
+  #
+  # The reader is `author_relationship`, not `post_author_relationship`. That is
+  # a real trap: the DSL derives the reader (and has_one name, and preload key)
+  # from `component_class.model_name.singular`, and for the *nested* constant
+  # `Post::AuthorRelationship` that is "post_author_relationship" — the namespace
+  # leaks in and the entity name is doubled up. ADR-0013 specifies
+  # `author_relationship`. So the backing class pins its own `model_name` to the
+  # demodulized element ("AuthorRelationship" => "author_relationship"), which is
+  # the single source every DSL derivation reads. Nothing else in the gem uses
+  # the backing component's model_name, so this is safe and total: reader,
+  # has_one, and `includes_components` key all agree on `author_relationship`.
+  #
+  # ## Querying and preloading by name (RFC-0013 / ADR-0014)
+  #
+  # `with_related` / `without_related` / `includes_related` are the
+  # relationship-name equivalents of `with_component` / `without_component` /
+  # `includes_components`. They are thin sugar: each resolves the relationship
+  # name to its backing class and FK via metadata `relates_to` records, then
+  # delegates to the component verb — so `Post.with_related(:author, ada)`
+  # compiles to exactly `Post.with_component(Post::AuthorRelationship, author_id:
+  # ada.id)` and inherits its entity-model scoping and EXISTS correctness
+  # (ADR-0011). The backing `*Relationship` class never appears in app code.
+  module Relationships
+    # One recorded relationship, held by NAME so it survives a Rails reload the
+    # same way the registry's Declaration does (RFC-0002): #backing_class and
+    # #target_class resolve via constantize on read, so a metadata entry taken
+    # before a reload still resolves to the post-reload constants.
+    RelationshipMeta = Struct.new(:name, :backing_class_name, :foreign_key, :target_class_name) do
+      def backing_class
+        backing_class_name.constantize
+      end
+
+      def target_class
+        target_class_name.constantize
+      end
+    end
+
+    # Sentinel for with_related's optional target: distinguishes "no target
+    # given" (filter to any backing row) from an explicit value. RFC-0013 only
+    # needs the no-arg form, but a sentinel — rather than a nil default — keeps
+    # "unset" from ever being confused with a legitimate id or entity.
+    ANY_TARGET = Object.new
+    private_constant :ANY_TARGET
+
+    # Declares a cross-entity link named `name` at `target_class`.
+    #
+    # `target_class` must be a concrete EcsRails::Entity; otherwise
+    # InvalidRelationship (a subclass of InvalidComponent — see errors.rb). `name`
+    # must not collide with an existing reader or delegated method on the entity;
+    # otherwise DelegationConflict, naming `name` (RFC-0012). Subclasses inherit
+    # the declaration exactly as they inherit `component` (the backing const lives
+    # on the declaring entity and resolves through ordinary constant lookup).
+    #
+    # Returns the Registry::Declaration for the backing component.
+    def relates_to(name, target_class)
+      name = name.to_sym
+
+      # Target first: this must fire before any name/table derivation, so that
+      # `Class.new(ApplicationEntity).relates_to(:x, String)` raises on the bad
+      # target rather than on the anonymous entity's blank model_name.
+      validate_relationship_target!(name, target_class)
+
+      # Then the name, with a relationship-shaped message. Left to `component`,
+      # a re-declared relationship trips the registry's DuplicateComponent, whose
+      # message names the CamelCase backing class ("Post::AuthorRelationship")
+      # rather than the relationship the developer wrote (`:author`) — and it
+      # would also warn on the doubled const_set. Catching it here keeps the
+      # message about the thing the developer typed.
+      detect_relationship_collision!(name)
+
+      backing = build_relationship_component(name, target_class)
+      declaration = component(backing)
+
+      # RFC-0013 / ADR-0014: record the relationship metadata the `*_related`
+      # query verbs resolve against. Recorded here, at declaration, so there is
+      # one source of truth for the backing class + FK rather than a second
+      # place that re-derives the naming convention (ADR-0014). On reload the
+      # entity class body reruns on a fresh class, repopulating this from empty.
+      record_relationship_meta(name, backing, target_class)
+
+      declaration
+    end
+
+    # The recorded metadata for relationship `name` on this entity (RFC-0013),
+    # or nil if there is none. Walks the entity ancestry, so a subclass sees its
+    # parents' relationships — the same way #component_declarations does.
+    def relationship_meta(name)
+      relationship_declarations[name.to_sym]
+    end
+
+    # The declared relationship names for this entity, ancestry included. Used
+    # in the InvalidRelationship message and handy for introspection.
+    def relationship_names
+      relationship_declarations.keys
+    end
+
+    # Entities whose `name` relationship points at `target` (RFC-0013 / ADR-0014).
+    #
+    # `target` may be an entity (its id is used) or a bare id. With no `target`,
+    # filters to entities that merely HAVE the relationship set (a backing row
+    # exists). Sugar for `with_component(backing, foreign_key => id)` — or
+    # `with_component(backing)` with no target — so it inherits that verb's
+    # entity-model scoping and correlated EXISTS (ADR-0011): no cross-entity leak.
+    #
+    # Returns a chainable ActiveRecord::Relation. Available on the class and on a
+    # relation, like the component verbs, because it builds on them (they run on
+    # `all`, the current default-scoped relation).
+    def with_related(name, target = ANY_TARGET)
+      meta = ecs_resolve_relationship!(name)
+
+      return with_component(meta.backing_class) if ANY_TARGET.equal?(target)
+
+      id = target.respond_to?(:id) ? target.id : target
+      with_component(meta.backing_class, meta.foreign_key => id)
+    end
+
+    # Entities with NO backing row for `name` (RFC-0013). Sugar for
+    # `without_component(backing)`; inherits its NULL-safe NOT EXISTS (ADR-0011).
+    def without_related(name)
+      without_component(ecs_resolve_relationship!(name).backing_class)
+    end
+
+    # Preloads each named relationship's backing component AND its target entity
+    # — one hop — so `entity.author` costs no extra query (RFC-0013 / ADR-0014).
+    #
+    # For `:author` that is `preload(author_relationship: :author)`: the backing
+    # reader is `<name>_relationship` (the backing's model_name.singular, pinned
+    # by ADR-0013) and the target association on the backing is the `<name>`
+    # belongs_to. Does NOT preload the target's own components (ADR-0014 non-goal).
+    #
+    # Chainable; returns a relation. Built from `all`, like Preloading, so it
+    # keeps any prior scope and the entity-model default scope.
+    def includes_related(*names)
+      preloads = names.map do |name|
+        meta = ecs_resolve_relationship!(name)
+        { :"#{meta.name}_relationship" => meta.name }
+      end
+
+      all.preload(*preloads)
+    end
+
+    private
+
+    # Records one relationship's metadata on THIS class, by name and by class
+    # NAMES (strings), never Class objects (reload safety — see RelationshipMeta).
+    def record_relationship_meta(name, backing, target_class)
+      ecs_own_relationships[name] = RelationshipMeta.new(
+        name,               # :author
+        backing.name,       # "Post::AuthorRelationship"
+        :"#{name}_id",      # :author_id
+        target_class.name   # "User"
+      )
+    end
+
+    # This class's OWN relationships (not inherited). A per-class hash, so a fresh
+    # class object after a reload starts empty and `relates_to` repopulates it.
+    # Instance variables are not inherited, which is exactly what lets
+    # #relationship_declarations do the ancestry walk explicitly.
+    def ecs_own_relationships
+      @ecs_relationships ||= {}
+    end
+
+    # Every relationship declared on this entity, ancestors' before its own —
+    # merged across #entity_ancestry the same way #component_declarations walks
+    # it, so a subclass inherits its parents' relationships. Base-first merge
+    # means a nearer class would win a name clash, mirroring method lookup.
+    def relationship_declarations
+      entity_ancestry.each_with_object({}) do |klass, merged|
+        own = klass.instance_variable_get(:@ecs_relationships)
+        merged.merge!(own) if own
+      end
+    end
+
+    # Resolves `name` to its metadata or raises the fail-loud InvalidRelationship
+    # (RFC-0013) — naming the relationship and this entity's declared ones, the
+    # same component-shaped stance as the rest of the DSL.
+    def ecs_resolve_relationship!(name)
+      meta = relationship_meta(name)
+      return meta if meta
+
+      declared = relationship_names
+      known = declared.empty? ? "none" : declared.map { |n| ":#{n}" }.join(", ")
+      raise InvalidRelationship,
+            "#{self.name} has no relationship named :#{name}. " \
+            "#{self.name} relates to: #{known}."
+    end
+
+    # Dynamically defines the backing component class and returns it. Named
+    # before anything reads its name: the registry keys by name and rejects
+    # anonymous classes (RFC-0002), and `model_name` is derived from the const —
+    # so const_set, which both installs the nested constant and gives the class
+    # its name, must come first.
+    def build_relationship_component(name, target_class)
+      const_name = :"#{name.to_s.camelize}Relationship"       # :AuthorRelationship
+      table = "#{model_name.singular}_#{name.to_s.pluralize}" # "post_authors"
+      foreign_key = :"#{name}_id"                             # :author_id
+
+      backing = Class.new(EcsRails::Component)
+      const_set(const_name, backing)
+
+      # table_name is set explicitly (ADR-0013): the class name and the table
+      # name are decoupled, so `Post::AuthorRelationship` reads `post_authors`.
+      backing.table_name = table
+
+      # Pin model_name to the demodulized element, so the DSL-derived reader is
+      # `author_relationship` and not `post_author_relationship` — see the module
+      # comment. Closed over `const_name`; ActiveModel::Name.new(self, nil,
+      # "AuthorRelationship") gives singular "author_relationship".
+      element = const_name.to_s
+      backing.define_singleton_method(:model_name) do
+        @ecs_relationship_model_name ||= ActiveModel::Name.new(self, nil, element)
+      end
+
+      # The one sanctioned place a component names an entity class (ADR-0006):
+      # optional, so a post with no author — or a nullified one — is valid.
+      backing.belongs_to name,
+                         class_name: target_class.name,
+                         foreign_key: foreign_key,
+                         optional: true
+
+      backing
+    end
+
+    # RFC-0012: the target must be a concrete entity. A component, an abstract
+    # entity, or a plain class is rejected with a relationship-shaped message.
+    def validate_relationship_target!(name, target_class)
+      unless target_class.is_a?(Class) && target_class < EcsRails::Entity
+        raise InvalidRelationship,
+              "relates_to :#{name} expected a concrete EcsRails::Entity as its " \
+              "target, got #{target_class.inspect}. A relationship points at an " \
+              "entity, not a component or a plain class."
+      end
+
+      return unless target_class.abstract_class?
+
+      raise InvalidRelationship,
+            "relates_to :#{name} target #{target_class.name} is abstract and owns " \
+            "no rows; relate to a concrete entity subclass."
+    end
+
+    # RFC-0012: `name` must not already be a reader or a delegated method on this
+    # entity — two `relates_to :author`, or `:author` clashing with a component
+    # that already exposes `author`. Checked here, before the backing const is
+    # created, so the message names `:author` (the relationship) rather than the
+    # backing class, and no doubled const_set warning is printed.
+    #
+    # Reuses the DSL's own reader/delegation resolution (#reader_name_for,
+    # #delegated_method_names), so "what names does this entity already answer"
+    # is computed the one way the gem computes it everywhere else.
+    def detect_relationship_collision!(name)
+      taken = component_declarations.flat_map do |declaration|
+        component = declaration.component_class
+        [reader_name_for(component)] + delegated_method_names(component, declaration.options)
+      end
+
+      return unless taken.include?(name)
+
+      raise DelegationConflict,
+            "relates_to :#{name} on #{self.name} collides with an existing " \
+            "##{name} method — a component reader or another relationship already " \
+            "owns that name. Choose a different relationship name."
+    end
+  end
+end

data/lib/ecs_rails/validations.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module EcsRails
+  # Validation error merging: `entity.valid?` reflects its components' validity,
+  # and `entity.errors` reads naturally in a Rails form.
+  #
+  # Implements RFC-0007. Closes the gap RFC-0006 left explicit (see its "Status"
+  # section): the save/save! contract was already atomic, but it held *by
+  # accident* — the after_save cascade's `component.save!` raised, and `save`
+  # rescued it. `valid?` itself did not yet know a dirty component was bad.
+  #
+  #   user = User.create!
+  #   user.email.address = "not-an-email"
+  #   user.valid?                       # => false        (now, not just on save)
+  #   user.errors[:"email.address"]     # => ["is invalid"]
+  #   user.errors.full_messages         # => ["Email address is invalid"]
+  #   user.save                         # => false, and inserts nothing
+  #
+  # With this in place, `entity.save` returns false because `valid?` is false
+  # *before* the cascade ever runs — the cascade's bang becomes belt-and-braces,
+  # exactly as ActiveRecord's autosave is. See RFC-0006's `#save_dirty_components`.
+  module Validations
+    # Mixed into EcsRails::Entity.
+    module Entity
+      extend ActiveSupport::Concern
+
+      included do
+        # A single `validate` callback that walks the memo and merges. No `on:`,
+        # so it runs in both the create and update contexts: an entity has no
+        # mutable fields of its own (architecture.md §1), so the money path is
+        # always a persisted-entity save whose only real work is a component's,
+        # and validation must fire there too.
+        validate :ecs_merge_component_errors
+      end
+
+      # Class-level hooks. `human_attribute_name` is a class method, and
+      # `ActiveModel::Error.full_message` reaches it via `base.class`, so the
+      # override that decouples the human label from the error key has to live
+      # here rather than on the instance.
+      module ClassMethods
+        # Turns a component-namespaced error key into a readable label, so that
+        # the *key* and the *full message* can diverge (RFC-0007):
+        #
+        #   errors[:"email.address"]   # machine-readable, namespaced by reader
+        #   full_messages             # => "Email address is invalid"  (human)
+        #
+        # ActiveModel couples these: `full_message` is
+        # "%{human_attribute_name(attribute)} %{message}", and the stock
+        # `human_attribute_name("email.address")` rpartitions on the dot and
+        # returns just "Address" — giving "Address is invalid", which drops the
+        # component entirely. Humanising the *whole* dotted key instead
+        # ("email.address" -> "email_address" -> "Email address") keeps the
+        # component as a word and reads as one sentence, only the first word
+        # capitalised — which is exactly the RFC's expected message and, notably,
+        # *not* "Email Address" (deferring to the component's own
+        # `human_attribute_name` would capitalise both).
+        #
+        # Guarded to component reader keys only, so this never hijacks an
+        # unrelated dotted attribute a host app might introduce.
+        def human_attribute_name(attribute, options = {})
+          key = attribute.to_s
+          reader, dot, rest = key.partition(".")
+
+          return super if dot.empty? || rest.empty?
+          return super unless ecs_component_reader?(reader)
+
+          key.tr(".", "_").humanize
+        end
+
+        # Is `reader` the name of a component reader on this entity?
+        #
+        # Deliberately `method_defined?` and not the registry (`components`).
+        # The registry is a mutable process-wide singleton that the Railtie
+        # clears and repopulates on reload, and that sibling specs clear outright
+        # — so `components` can transiently be empty for a fully-composed entity.
+        # The generated reader is the durable artifact: the DSL defines it into an
+        # included module at declaration time, and it survives a registry clear
+        # (the same reason delegation keeps working across one). Since
+        # `human_attribute_name` is a hot method every form field hits, this is
+        # also the cheaper check.
+        #
+        # It can only ever matter for a dotted key, and the only dotted keys the
+        # gem produces are component-namespaced error keys whose head is, by
+        # construction, a real reader — so the looseness (any instance method
+        # named `reader` would pass) is harmless.
+        def ecs_component_reader?(reader)
+          method_defined?(reader)
+        end
+      end
+
+      private
+
+      # Merges the errors of every component that deserves validating onto the
+      # entity, namespaced by the component's reader (`email.address`).
+      #
+      # **Which components?** Exactly the ones in RFC-0006's memo — the ones the
+      # caller has actually read on *this* instance — and of those, only the ones
+      # that are dirty or already persisted (ADR-0003: a virtual, untouched
+      # component is not validated at all). This is deliberately *not* a walk of
+      # every declared component:
+      #
+      #   - Reading an unread component to validate it would materialise it (a
+      #     SELECT, or a fresh virtual instance) — a side effect `valid?` must not
+      #     have, and it would validate a component the caller never touched.
+      #   - A *persisted* component the caller has not loaded on this instance is
+      #     therefore not validated here. "if this row exists it must be
+      #     well-formed" (ADR-0003) is a save-time guarantee the row's own
+      #     validations keep; `valid?` speaks only to what is in front of it.
+      #
+      # So `valid?` has no side effects: it inserts nothing, dirties nothing, and
+      # materialises no component that was never read. Pinned hard in
+      # validation_spec.rb.
+      #
+      # ActiveModel clears the entity's errors at the top of every `valid?`
+      # (`run_validations!` does `errors.clear`), and `component.valid?` clears
+      # the component's own — so merging twice cannot double-count or leak state
+      # across calls. Idempotent by construction.
+      def ecs_merge_component_errors
+        return unless @ecs_components
+
+        @ecs_components.each do |reader, component|
+          # Destroyed through the reader inside this same lifecycle — there is no
+          # row to be well-formed, and the reader hands out a fresh virtual next.
+          next if component.destroyed?
+          next unless component.ecs_dirty? || component.persisted?
+
+          # `valid?` (not `errors.any?`) so the component actually runs its
+          # validations, in the same create/update context a save would use.
+          next if component.valid?
+
+          merge_component_errors(reader, component)
+        end
+      end
+
+      # Copies one component's errors onto the entity. Each error is re-added
+      # individually so the attribute can be re-namespaced (`address` ->
+      # `email.address`) while the message is carried across verbatim; the human
+      # label is then composed by the `human_attribute_name` override above.
+      #
+      # A component base error (`errors.add(:base, ...)`) has no attribute to
+      # namespace, so it lands under the bare reader key.
+      def merge_component_errors(reader, component)
+        component.errors.each do |error|
+          key = error.attribute == :base ? reader : :"#{reader}.#{error.attribute}"
+          errors.add(key, error.message)
+        end
+      end
+    end
+  end
+end

data/lib/ecs_rails/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EcsRails
+  VERSION = "0.2.1"
+end

data/lib/ecs_rails.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_support"
+
+require "ecs_rails/version"
+require "ecs_rails/config"
+require "ecs_rails/errors"
+require "ecs_rails/registry"
+require "ecs_rails/lazy"
+require "ecs_rails/presence"
+require "ecs_rails/validations"
+require "ecs_rails/dsl"
+require "ecs_rails/relationships"
+require "ecs_rails/querying"
+require "ecs_rails/preloading"
+require "ecs_rails/entity"
+require "ecs_rails/component"
+
+# ECS Rails — an Entity-Component-System reimagining of ActiveRecord.
+#
+# See docs/architecture.md for the invariants this library guarantees.
+module EcsRails
+  class << self
+    # The process-wide component registry. See RFC-0002.
+    def registry
+      @registry ||= Registry.new
+    end
+
+    # The process-wide generator configuration (ADR-0010). Layout only — the
+    # runtime does not consult it; the generators and the initializer they emit
+    # do.
+    def config
+      @config ||= Config.new
+    end
+
+    # Yields the config for block-style setup, as a host app's
+    # config/initializers/ecs_rails.rb does:
+    #
+    #   EcsRails.configure { |config| config.entities_path = "app/models" }
+    def configure
+      yield config
+    end
+  end
+end
+
+require "ecs_rails/railtie" if defined?(Rails::Railtie)

data/lib/generators/ecs_rails/component/component_generator.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# See the note in install_generator.rb: rails/generators/active_record/migration
+# references ActiveRecord::Migration without loading it.
+require "active_record"
+require "rails/generators/named_base"
+require "rails/generators/active_record/migration"
+
+# Rails::Generators::GeneratedAttribute.parse calls String#remove, an
+# ActiveSupport core extension that neither rails/generators nor active_record
+# loads. A booted Rails app has active_support/all, so `rails g` works either
+# way — but without this the attribute parsing below depends on some other file
+# happening to have loaded the core ext first, which is not a dependency this
+# generator should have.
+require "active_support/core_ext/string/filters"
+
+# ADR-0010: the generator reads EcsRails.config to place its model and spec.
+# Require the library explicitly so the generator stands on its own requires
+# (see RFC-0008's isolation note and generator_isolation_spec.rb).
+require "ecs_rails"
+
+module EcsRails
+  module Generators
+    # `rails g ecs_rails:component NAME [field:type ...]`
+    #
+    # Implements RFC-0008. The whole point of this generator is that the
+    # entity_id + UNIQUE index + ON DELETE CASCADE invariant (ADR-0005) becomes
+    # impossible to forget, and that every attribute gets an explicit default
+    # (RFC-0006).
+    #
+    # Attribute parsing is Rails' own: declaring an `attributes` argument makes
+    # Rails::Generators::NamedBase run parse_attributes!, which turns
+    # "address:string" into a Rails::Generators::GeneratedAttribute.
+    class ComponentGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :attributes, type: :array, default: [], banner: "field:type field:type"
+
+      desc "Creates a component: its migration, its model, and its spec."
+
+      def create_migration_file
+        migration_template(
+          "migration.rb.tt",
+          File.join(db_migrate_path, "create_#{table_name}.rb")
+        )
+      end
+
+      # ADR-0010: the model lands under the configured components_path
+      # (entities_path/components), not app/models. class_path is preserved so a
+      # namespaced component (rails g ecs_rails:component Billing/Plan) still
+      # nests correctly.
+      def create_model_file
+        template "model.rb.tt",
+                 File.join(EcsRails.config.components_path, class_path, "#{file_name}.rb")
+      end
+
+      # ADR-0010: the spec mirrors the layout under spec/entities/components. Its
+      # template declares `type: :model` explicitly, because rspec-rails only
+      # infers that from spec/models/ — which this path no longer matches.
+      def create_spec_file
+        template "component_spec.rb.tt",
+                 File.join("spec/entities/components", class_path, "#{file_name}_spec.rb")
+      end
+
+      private
+
+      # The explicit-default policy (RFC-0008 / RFC-0006).
+      #
+      # A virtual component — one with no database row — reports its column
+      # defaults. So a column with no default silently reports nil, and that
+      # choice should be visible in the migration rather than implied. Every
+      # attribute therefore gets a `default:` written out.
+      #
+      #   boolean => default: false, null: false
+      #     A three-valued boolean has no sensible virtual reading: `user.email
+      #     .verified` should be false, not nil. Matches spec/support/schema.rb's
+      #     `verified` column. null: false because the default removes any
+      #     reason for the column to be nullable.
+      #
+      #   everything else => default: nil
+      #     There is no defensible universal default for a string or an integer,
+      #     and inventing one (0, "") would be worse than nil. nil is written
+      #     explicitly so the reader sees it was a decision.
+      #
+      # Override by hand in the generated migration when the domain has a real
+      # default — that edit is the point.
+      def column_options_for(attribute)
+        case attribute.type.to_s
+        when "boolean" then ", default: false, null: false"
+        else ", default: nil"
+        end
+      end
+
+      def migration_version
+        "#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}"
+      end
+    end
+  end
+end

data/lib/generators/ecs_rails/component/templates/component_spec.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+<% module_namespacing do -%>
+# type: :model is declared explicitly because this spec lives under
+# spec/entities/components, not spec/models — and rspec-rails only infers
+# :model metadata from spec/models/. See ADR-0010.
+RSpec.describe <%= class_name %>, type: :model do
+  it "is virtual until dirtied" do
+    # A component with no row reports its defaults and does not persist.
+    # See RFC-0006.
+    skip "write a test for <%= class_name %>"
+  end
+end
+<% end -%>

data/lib/generators/ecs_rails/component/templates/migration.rb.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Creates the <%= table_name %> component table.
+#
+# Every component table follows the same invariants (docs/architecture.md §2):
+# a UUID primary key, a non-null entity_id with a UNIQUE index (ADR-0005) and an
+# ON DELETE CASCADE foreign key, and an explicit default for every attribute
+# (RFC-0006).
+class Create<%= table_name.camelize %> < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+    create_table :<%= table_name %>, id: :uuid, default: -> { "gen_random_uuid()" } do |t|
+      t.uuid :entity_id, null: false
+<% attributes.each do |attribute| -%>
+      t.<%= attribute.type %> :<%= attribute.name %><%= column_options_for(attribute) %>
+<% end -%>
+      t.timestamps
+    end
+
+    # ADR-0005: a component appears at most once per entity.
+    add_index :<%= table_name %>, :entity_id, unique: true
+
+    # Destroying an entity destroys its components, at the database level.
+    add_foreign_key :<%= table_name %>, :entities, column: :entity_id, on_delete: :cascade
+  end
+end

data/lib/generators/ecs_rails/component/templates/model.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+<% module_namespacing do -%>
+# A component: data and behaviour, owned by exactly one entity.
+#
+# Methods defined here execute with `self` bound to the component, never the
+# entity (ADR-0001), and are delegated onto any entity that declares
+# `component <%= class_name %>`.
+#
+# This class must never reference an entity subclass.
+class <%= class_name %> < ApplicationComponent
+end
+<% end -%>