ecs_on_rails 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bef233f6d1933696953db3058563f4e4178c67aeb6d56f6d2f241f64f23b81f3
-  data.tar.gz: a7806e71e299991ae122dd30ce78a009bf181ed55c11d8b43444be2a2f6ef1d8
+  metadata.gz: f5ee13ec49dd2b98779e03c1fe5f29e4e9dd26c2fc7efdcc4be69dbb548fc65d
+  data.tar.gz: 49a77b4f33c89abd4ffbc1a21f6e4554ebc8540f74f6f562ca94ff73e6ec3b5b
 SHA512:
-  metadata.gz: 7fd3624f55f3264bbaf3c84cb355a63cc5e0e5e66eabd43d04ad01c1d87bff202dd8d4e851d6006c66c383c742702da548115161ab33dd2ddc7d1f37b0e86295
-  data.tar.gz: 926baa1d0cfca36f1453d0cc4abb02d463a04d49b499b2a6eb72f54534a4486ccfe27e1452a6b0a2206f2589062cd4f53aa1b05ab07fed7b4479e19515b92ecd
+  metadata.gz: a48ce6bd28e4db48233251a28e5d7991c14a830a04c51e83f321762a544ab74fef9fb321722bac48600a0acd028f67de23343c91104d154bb4f8aa0cf0447451
+  data.tar.gz: a8eaa377b244e0a694251aef678ebe6114a67062052824da9d35694095d3a3e340654871f2fb0a025b85643bf809e59bef1bf31156fd1fa2cd2a168b25646198

data/.yardopts

@@ -0,0 +1,12 @@
+--markup markdown
+--markup-provider kramdown
+--readme README.md
+--title "ECS Rails - an Entity-Component-System reimagining of ActiveRecord"
+--charset utf-8
+--no-private
+--hide-void-return
+--embed-mixins
+lib/**/*.rb
+-
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -6,6 +6,338 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-09-27
+
+**The zero-migrations release.** After `rails g ecs_rails:install` and one
+`db:migrate`, entities, labelled slots, relationships, markers and systems are
+plain Ruby: the catalogue ships the components, one shared table holds every
+relationship, another every marker. Breaking, pre-1.0.
+
+### Upgrading from 0.2
+
+Back up the database and try this on a copy first. The gem README's
+"Upgrading an existing installation" has the full steps.
+
+1. Update the Gemfile to `gem "ecs_on_rails", "~> 0.3.0"` and run
+   `bundle update ecs_on_rails`.
+2. In development, run `bin/rails generate ecs_rails:upgrade` (add
+   `--sets core commerce` for `Money`), review the migrations, then
+   `bin/rails db:migrate`. It adds `slot` to every component table and moves
+   the unique index to `(entity_id, slot)`, creates `relationships`, `markers`
+   and the catalogue tables, and moves rows from per-relationship and marker
+   tables into the shared ones, keeping their IDs. Running it again generates
+   nothing.
+3. **Delegated names are prefixed with the reader**: `user.address` becomes
+   `user.email_address`. Add `prefix: false` to a declaration to keep bare names.
+4. **Markers are declared by name**: `component Moderator` becomes
+   `marker :moderator`, and `add(Moderator)` becomes `add(:moderator)`. Delete
+   the old marker class after migrating.
+5. **`rails g ecs_rails:relationship` is gone**: `relates_to` needs no
+   migration. Nested preloads name `target`:
+   `preload(author_relationship: { target: :name })`.
+6. Run `bin/rails zeitwerk:check` and your tests.
+
+### Added
+
+- **Demo journey, identity and accessibility** (ECS-35): the demo opens on a
+  four-step tour quoting each step's declaration; a session-backed "acting
+  as" bar replaces per-form user pickers; a scripted rendered and axe-core
+  review (`demo/script/qa`) brought 21 pages and 7 states to zero WCAG 2.1 AA
+  violations in light and dark schemes and fixed phone layouts. See
+  [the review](../docs/design/demo-qa.md). No gem change.
+
+- **Geocoder map in the demo** (ECS-44): `/geocoder` draws located
+  Geolocations on a server-rendered SVG world map (Natural Earth 1:110m, public
+  domain; no JavaScript or tiles), with non-overlapping labels, merged markers
+  for nearby points, a text list of places, and filter links by entity type that
+  narrow map and table with `Geolocation.where(entity: User.all)`. No gem change.
+
+- **Geocoder system in the demo** (ECS-8): `Demo::Geocoder` pairs every
+  `Address` with a `Geolocation` in the same slot across users (shipping and
+  billing) and companies without naming either, skips owners that declare no
+  pair (order/invoice snapshots), redoes only new or edited addresses, records
+  unknown or blank places without coordinates, and resolves overlapping runs on
+  the `(entity_id, slot)` unique index. Lookups are simulated. The demo's
+  `/geocoder` page shows each address's state, runs it and lists the one
+  migration. `Geolocation#locate` now takes `at:` (default `Time.current`) so a
+  system can stamp the address version the coordinates describe, and documents
+  `locate(nil, nil)` as a lookup that found nothing.
+
+- **Entity generator** (ECS-11): `rails generate ecs_rails:entity Person name
+  email mobile:phone work:phone home:address` writes a plain entity class from
+  existing components, including labelled slots and namespaces. Validates names,
+  concrete references and duplicates before writing; respects configured paths
+  and normal file collision handling. Emits no migration. Quickstart/package
+  checks now exercise generated classes and independent persisted slots.
+
+- **Executable onboarding** (ECS-34): the gem README starts with a contacts
+  tutorial covering composition, querying, a cross-entity system and rendering.
+  Package CI executes its actual snippets, upgrade commands and bespoke storage
+  example. The demo guide documents setup, resets, tests and a guided journey;
+  lifecycle guidance covers virtual reads, replacements, targets and deletion.
+
+- **Source walkthrough and readability review** (ECS-36): follow installation,
+  composition, checkout and entity-independent indexing through the gem and demo.
+  Simplified checkout orchestration and Period branching; corrected catalogue
+  examples, generated comments and lifecycle/query/token documentation to match
+  existing behavior. No API, schema or dependency changes.
+
+- **Reproducible performance evidence** (ECS-33): the companion demo includes
+  equivalent ECS/conventional Rails catalogue, detail, checkout, indexing and
+  slot-preload workloads, behavioral verification and a CI smoke run. Published
+  local measurements include latency distributions, allocations, SQL, storage
+  and query plans at 100/1,000/5,000 products. See
+  [the comparison](../docs/design/performance-comparison.md) for costs and
+  limitations; no gem API or production schema change.
+
+- **Component queries beyond equality, and ordering** (RFC-0018).
+  `with_component` takes a block run on the component's relation
+  (`{ where("amount_cents < ?", 5000) }`, `{ tagged("ruby") }`,
+  `{ matching(q) }`) and `where`-style positional conditions
+  (`with_component(Rating, "stars >= ?", 4)`), all inside the same correlated
+  `EXISTS`. New `order_by_component(Money, :amount_cents, :desc, prefix:
+  :price)` orders by a component column through a correlated scalar subquery —
+  no join, no duplicate rows — with the column defaulting to the component's
+  primary attribute and entities lacking the row sorting last.
+
+- **Inverse relationships** (RFC-0015): `has_many :comments, via: :post` and
+  `has_one :invoice, via: :order` on the parent expand to native `has_many
+  :through` over the shared `relationships` table — a real `CollectionProxy` of
+  the child class, `<<`, `create!`, scopes, the component query DSL chained on,
+  `includes(:comments)`. The child is inferred from the reader, or named
+  (`"Comment"`, or the class), and the pair is validated on first use and at
+  boot under `eager_load` — never at class-load time, which autoloading makes
+  unsafe. `has_one` requires the child's `unique: true`. `dependent: :destroy`
+  / `:delete_all` removes the link rows with the parent. `entity.referrers`
+  lists every relationship row pointing at an entity. Without `via:` both
+  macros are ActiveRecord's own.
+
+- **Primary attributes** (RFC-0014 amendment). A component declares
+  `primary :value`; a labelled slot of it then also delegates the bare slot
+  name, so `component Text, prefix: :title` gives `post.title` / `post.title=`
+  (→ `title_text.value`) beside `post.title_text` and `post.title_text_value`.
+  The catalogue declares them on `Text`, `Identifier`, `Counter`, `Timestamp`,
+  `CalendarDate`, `Rating`, `Position` and `Role`. Decided by the forum rebuild.
+
+- **The catalogue** (ADR-0018, RFC-0017): 25 standard components shipped as
+  concerns under `EcsRails::Catalogue` — `Name`, `Email`, `Password`, `Phone`,
+  `Address`, `Geolocation`, `Link`, `Text`, `Identifier`, `Counter`, `Rating`,
+  `Timestamp`, `CalendarDate`, `Period`, `Position`, `State`, `Tags`,
+  `SearchVector`, `Discard`, `Image`, `Role`, `Token`, `Marker`, `Relationship`
+  (`core`) and `Money` (`commerce`). Each carries its behaviour, validations and
+  a schema declaration; `rails g ecs_rails:install` writes a one-line class per
+  component and ONE migration creating every table in the chosen `--sets`, so
+  an application builds from the catalogue with no further migration.
+  `--rename money:Price` is the name-collision remedy. `rails g
+  ecs_rails:upgrade` diffs the declarations against the database and writes
+  what is missing.
+
+- **Markers on one shared table** (ADR-0018 §4, RFC-0016). `marker :moderator`
+  declares a marker as slot "moderator" of the app's `Marker` component
+  (`EcsRails::Catalogue::Marker`, one-line class written by install), with the
+  bare `user.moderator?` predicate, a Boolean `user.moderator = true` writer,
+  `add(:moderator)` / `has?` / `remove` by name, and `User.with_marker(:moderator)`
+  / `without_marker`. No table per marker; a zero-attribute component on its own
+  table still works. `EcsRails.config.marker_class_name` names the class.
+  `ecs_rails:upgrade` gains a third job that creates `markers` and moves every
+  empty per-marker table into it.
+
+- **One shared `relationships` table** (ADR-0017). Every `relates_to` is now a
+  row in a table created at install, under a slot named for the relationship;
+  declaring a relationship needs no migration. The public API is unchanged
+  (`relates_to`, `post.author`, `post.author=`, `with_related`,
+  `without_related`, `includes_related`), plus `post.author_id` /
+  `post.author_id=`.
+- `relates_to :order, Order, unique: true` — at most one owner of this type per
+  target, enforced by a partial unique index created once at install.
+- `EcsRails::Catalogue::Relationship`, the first catalogue concern (ADR-0018);
+  `rails g ecs_rails:install` writes the one-line `Relationship` class that
+  includes it. `EcsRails.config.relationship_class_name` names it (default
+  `"Relationship"`).
+- The target type is checked on assignment: `post.author = team` raises
+  `EcsRails::InvalidRelationship`.
+- `rails g ecs_rails:upgrade` gains a second job: create `relationships` and
+  move every pre-0.3 per-relationship table into it (recognised by shape and
+  name), then drop them. Irreversible; review the generated file.
+
+- **Labelled (plural) components — slots** (RFC-0014 / ADR-0015). A component
+  may be declared more than once on an entity under distinct labels, each a
+  singleton with its own reader: `component Address` and `component Address,
+  prefix: :business` give `user.address` and `user.business_address`, backed by
+  one `addresses` table and told apart by a new `slot` column. Everything
+  singular works per slot with no new API — the lazy reader (a virtual is
+  built with its slot preset), delegation (`business_address_line1`), presence
+  (`add(Address, prefix: :business)`, `user.business_address?`), validation
+  keys (`errors[:"business_address.postcode"]`), querying
+  (`with_component(Address, prefix: :business, region: "WA")`) and preloading
+  (`includes_components(Address)` batches every slot).
+- `component Foo, delegate: false` — reader and predicate only, no delegated
+  methods, for when even prefixed names get long.
+- **Per-slot options.** A component declares what it accepts with
+  `slot_option :states, default: []`; the declaration site passes them as extra
+  keywords (`component State, prefix: :order, states: %w[pending paid]`); the
+  instance reads them back (`order_state.states`, `slot_options`). Unknown
+  options raise at declaration time.
+- `Entity.declaration_for(Component, prefix:)`; `Registry::Declaration#slot`,
+  `#reader_name`, `#prefix`, `#slot_options`.
+- **`rails g ecs_rails:upgrade`** — one migration that adds the `slot` column
+  and the `(entity_id, slot)` unique index to every existing component table
+  that lacks them, found by inspecting the database. Safe on shipped data.
+  This is the only migration a 0.2.x app needs to run.
+
+- `component Foo, prefix: false` — bare delegation for one declaration, where
+  the prefix would be redundant (`post.state`, not `post.publish_state_state`).
+  `prefix: true` is the explicit default. A Symbol (RFC-0014's slot label)
+  raises `ArgumentError` until labelled slots are implemented.
+- **Flat mass assignment.** Because the prefixed writers exist,
+  `User.create!(name_first: "Ada", email_address: "a@b.com")` routes each key
+  to its component, dirties it and persists it through the save cascade;
+  `update!` too. Rails multiparameter form fields (`date_select` →
+  `group_founded_on(1i)`…) route the same way. Unknown keys still raise
+  `ActiveModel::UnknownAttributeError`.
+
+### Fixed
+
+- **Bounded demo indexing** (ECS-32): the component indexer batches 100 owners,
+  reads every eligible owner's text slots together, and batches owner discovery
+  and existing vector reads. Preserves slot ordering, declaration eligibility
+  and vector identity without loading the full Text table.
+
+- **Bounded demo lists** (ECS-31): market, bulletin, people, sellers, groups,
+  order history and growing detail lists use 24-row Kaminari pages. Stable
+  UUID tie-breakers prevent ambiguous ordering; navigation retains filters,
+  normalizes invalid pages and preserves total counts. Component and
+  relationship preloads apply only to the selected page.
+
+- The Rails-compatible JSON `< 3` constraint is now a runtime dependency,
+  protecting installed gem consumers as well as development bundles (ECS-30).
+  CI covers each Rails 7.1/7.2/8.0/8.1 series, Ruby 3.2 through 4.0 representative
+  combinations, the demo suite, documentation and real packaged install/upgrade
+  flows against isolated PostgreSQL databases.
+
+- Catalogue upgrades verify live column definitions, UUID primary keys,
+  unique/partial indexes and validated foreign keys with deletion behavior
+  before writing files (ECS-29). Missing compatible structures generate additive
+  migrations; incompatible definitions report actual/expected properties and
+  require explicit repair. Known catalogue tables with missing attributes are
+  no longer mistaken for legacy marker tables. No data conversion is inferred.
+
+- Demo checkout and basket edits now coordinate on the basket; stock updates
+  lock the actual Counter rows in product order (ECS-28). Submitted revisions
+  identify completed orders so successful retries return the original result,
+  stale forms are rejected, and declines can retry without partial changes.
+  Order/invoice allocation uses transaction advisory locks and numeric suffixes.
+  No new demo migration is required. Demo specs refuse non-test environments.
+
+- Demo price filters and ordering now treat an absent Money row as the displayed
+  zero price, matching persisted free products (ECS-27). The product-specific
+  queries use a slot-scoped left join and `COALESCE`, with stable price ties;
+  the gem's persisted component-presence semantics are unchanged.
+
+- Component assignment now replaces a singleton atomically and updates both
+  the lazy memo and association cache (ECS-26), including labelled slots.
+  Invalid replacements preserve the old row; new owners defer persistence,
+  default-only replacements remain virtual, and nil removes the row. Cross-owner
+  and persisted cross-slot moves are rejected. Component reload/reset helpers
+  clear both caches; generated build/create helpers now raise an intentional
+  error directing callers to reader-based attribute updates.
+
+- Explicitly assigned new relationship targets now save with their owner in
+  one transaction instead of being silently dropped (ECS-25). The lazy
+  cascade recognizes pending targets, and Rails autosave validates and saves
+  them and their touched components. Invalid targets fail through `save` /
+  `save!`; simply reading an unset relationship still creates no row.
+
+- Relationship target IDs now validate against the declared target class,
+  including flat mass assignment and direct Relationship saves (ECS-24).
+  Wrong-type and nonexistent IDs return validation errors through `save` /
+  `save!`; subclasses and nil targets remain valid, and validation reuses
+  loaded targets. Wrong-type object assignments still raise immediately.
+
+- `EcsRails::Catalogue::Password` no longer raises at class-load time when
+  bcrypt is absent — which, under `eager_load`, stopped an application that
+  installed `core` from booting. `has_secure_password` is set up when bcrypt is
+  available; otherwise `password=` and `authenticate` raise a LoadError saying
+  what to add. Surfaced by eager-loading the forum.
+- The catalogue's format validators (`Email#address`, `Phone#e164` and
+  `#extension`, `Link#url`, `Address#country`, `Image#url`) use `allow_blank`,
+  not `allow_nil`: a blank form field no longer reads "is invalid" on top of
+  the application's own presence rule. Surfaced by the forum rebuild (ECS-17).
+
+### Removed
+
+- `rails g ecs_rails:relationship` and the per-relationship backing tables
+  (`post_authors`, ...). The dynamic `Post::AuthorRelationship` classes are gone;
+  `Post.components` lists `Relationship` instead.
+
+### Changed
+
+- The install migration is now `ecs_rails_install` (`EcsRailsInstall`) and
+  creates both `entities` and `relationships`.
+- `RelationshipMeta` is `(name, target_class_name, unique)` with `slot` and
+  `reader_name` derived; `backing_class_name` and `foreign_key` are gone.
+- The nested-preload key for a relationship's target is `target`:
+  `preload(author_relationship: { target: :name })`.
+- **Every component table carries `slot string NOT NULL DEFAULT ''`, and the
+  unique index moves from `entity_id` to `(entity_id, slot)`.** The
+  `ecs_rails:component` and `ecs_rails:relationship` generators emit the new
+  shape; existing tables need `rails g ecs_rails:upgrade` (above). **Breaking
+  for existing databases** until upgraded: the gem's has_ones are slot-scoped
+  and will not find rows in a table with no slot column.
+- `Entity.components` lists each component type once however many slots it is
+  declared under; `component_declarations` lists each slot.
+- A new reader colliding with a name the entity already answers (a sibling's
+  reader or delegated method) now raises `DelegationConflict` at declaration.
+- `EcsRails::Registry#register` takes `slot:` and `slot_options:`; the same
+  component in a different slot is a distinct declaration, the same slot twice
+  is still `DuplicateComponent`.
+
+- **Delegation is component-prefixed by default** (ADR-0016). A component's
+  delegated methods are named `#{reader}_#{method}`: `component Email` now gives
+  `user.email_address`, `user.email_verified` and
+  `user.email_send_welcome_email`, all routed through `user.email`. The rule is
+  uniform — attributes and behaviour alike — so two components can never
+  collide on a shared attribute name, and a component reader can never be
+  shadowed by a delegated `belongs_to`. The reader (`user.email`) and the
+  presence predicate (`user.email?`) are unchanged.
+  **Breaking:** every bare delegated call (`user.address`) becomes
+  `user.email_address` unless the declaration opts out. `only:`/`except:`
+  still name the component's own methods (`except: [:title]`).
+- `EcsRails::DelegationConflict` is now raised on the *entity-level* names, so
+  `Name#title` and `Group#title` coexist as `name_title` / `group_title` with no
+  `except:`. A conflict, and the reader-collision raise, now need two bare
+  declarations; both messages name dropping `prefix: false` as a way out.
+- `relates_to` declares its backing component bare, so `post.author` /
+  `post.author=` keep their shape.
+
+## [0.2.2] — 2026-07-23
+
+### Added
+
+- **YARD API documentation across the whole public API** — `@param`, `@return`,
+  `@raise`, `@example` and `@see` tags on every public module, class, attribute
+  and method (100% documented, verified by `yard stats`). The existing prose
+  rationale is kept; the tags are additive, so
+  [rubydoc.info/gems/ecs_on_rails](https://rubydoc.info/gems/ecs_on_rails) now
+  renders a real API reference rather than bare comments.
+- A `.yardopts`, shipped in the gem so rubydoc.info honours it. Notably
+  `--embed-mixins`, without which the DSL that `EcsRails::Entity` gains by
+  `extend`ing {EcsRails::DSL}, `Querying`, `Preloading` and `Relationships`
+  would not appear on `Entity` at all — which is where users look for it.
+- `documentation_uri` in the gemspec, pointing at the rubydoc.info API
+  reference. The narrative documentation (architecture, ADRs, RFCs) is reached
+  via the homepage and `source_code_uri`.
+
+### Fixed
+
+- `changelog_uri` in the gemspec pointed at `<repo>/blob/main/CHANGELOG.md`,
+  which 404s: the gem lives in `gem/` of a monorepo and there is no changelog at
+  the repo root, so the Changelog link on the 0.2.1 RubyGems page was broken.
+  Gem metadata is immutable once published, so this needed a release to correct.
+- `source_code_uri` now points at the `gem/` subtree rather than the repo root.
+
+No code change — 0.2.2 is identical to 0.2.1 apart from gemspec metadata.
+
 ## [0.2.1] — 2026-07-23
 
 First RubyGems release.