familia 2.0.0.pre22 → 2.0.0.pre23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf37d5963fa9ae33323b70ad4eea48cfa45e91aa59ea46ecce2ac85644a9d0e2
-  data.tar.gz: 8880f7e2914b12db9a0cdcf2f741968c7c43731ef15833a921be72df19de70cd
+  metadata.gz: cc6c562adc770554d50a5d8d97be46b8a924d04ed6a28e7447a765990e69d89b
+  data.tar.gz: 97812dfbbcd8b7cb2e3c9447558e7b1b6eb30181d9eed8c3ae86e0371f83cf7e
 SHA512:
-  metadata.gz: 31b585405895213ee9857a66306ee2e7b60ce2f26568915571bc8c992e1169ff8589856c40253e2b8ef8081fd3805b0f32f0a769d85108a11528786621ac4440
-  data.tar.gz: 715766983ba9c44603bc8a94c240dc716130cc70cc182fd84dec1cc5b17333de32e52b1677610d62b6aba047aadada2cdf65b61867df1d3bffab08f94d8c4067
+  metadata.gz: 6d41492ba9f38dafacfe65a37a792c6f50ad90e406718131b0e226a6003b27008a1057851eb1d73ed1ff8baf8cf95312e684b290e23b3bbc2c9b5d453f0ba2ea
+  data.tar.gz: 2bf7cb92e0e06b623429dd0ff3b1da46686236329f5f3540e9f344195d1a51b50a209fc3b7d6538827c91e51194dd1014f9e5efd536a264c08283c505ea5044f

data/.github/workflows/claude-code-review.yml

@@ -7,11 +7,11 @@ on:
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    # Run on opened/synchronize, but only on 'labeled' if label is 'claude-review'
+    if: |
+      github.event.action == 'opened' ||
+      github.event.action == 'synchronize' ||
+      (github.event.action == 'labeled' && github.event.label.name == 'claude-review')
 
     runs-on: ubuntu-latest
     permissions:
@@ -50,3 +50,6 @@ jobs:
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
           allowed_tools: "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"
+
+          # Allow bot-initiated workflows (e.g., qodo, dependabot)
+          allowed_bots: "*"

data/CHANGELOG.rst

@@ -7,6 +7,39 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.0.0.pre23:
+
+2.0.0.pre23 — 2025-12-22
+========================
+
+Added
+-----
+
+- Add ``:through`` option to ``participates_in`` for join model support.
+  Enables storing additional attributes (role, permissions, metadata) on
+  participation relationships via an intermediate model. The through model
+  uses deterministic keys and supports idempotent operations - adding an
+  existing participant updates rather than duplicates.
+
+Security
+--------
+
+- Add validation for through model attributes to prevent arbitrary method
+  invocation. Only fields defined on the through model schema can be set
+  via the ``through_attrs`` parameter.
+
+Documentation
+-------------
+
+- Add YARD documentation for the ``:through`` parameter on both
+  ``participates_in`` and ``class_participates_in`` methods.
+
+AI Assistance
+-------------
+
+- Implementation design and code review assistance provided by Claude.
+  Security hardening for attribute validation added based on Qodo review.
+
 .. _changelog-2.0.0.pre22:
 
 2.0.0.pre22 — 2025-12-03

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre22)
+    familia (2.0.0.pre23)
       benchmark (~> 0.4)
       concurrent-ruby (~> 1.3)
       connection_pool (~> 2.5)
@@ -17,10 +17,10 @@ GEM
   specs:
     ast (2.4.3)
     base64 (0.3.0)
-    benchmark (0.4.1)
-    bigdecimal (3.2.3)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.3)
+    benchmark (0.5.0)
+    bigdecimal (3.3.1)
+    concurrent-ruby (1.3.6)
+    connection_pool (2.5.5)
     csv (3.3.5)
     date (3.5.0)
     debug (1.11.0)
@@ -69,7 +69,7 @@ GEM
     lint_roller (1.1.0)
     logger (1.7.0)
     minitest (5.26.0)
-    oj (3.16.11)
+    oj (3.16.13)
       bigdecimal (>= 3.0)
       ostruct (>= 0.2)
     ostruct (0.6.3)
@@ -99,7 +99,7 @@ GEM
     redcarpet (3.6.1)
     redis (5.4.1)
       redis-client (>= 0.22.0)
-    redis-client (0.25.1)
+    redis-client (0.26.2)
       connection_pool
     reek (6.5.0)
       dry-schema (~> 1.13)
@@ -154,7 +154,7 @@ GEM
       base64
     ruby-progressbar (1.13.0)
     stackprof (0.2.27)
-    stringio (3.1.7)
+    stringio (3.1.9)
     timecop (0.9.10)
     tryouts (3.7.1)
       concurrent-ruby (~> 1.0, < 2)

data/docs/1106-participates_in-bidirectional-solution.md

@@ -1,15 +1,23 @@
-The Naming Problem
+# Bidirectional Relationships in Familia
 
-bidirectional: true is misleading because:
+> **Document Status**: Updated 2025-12 to reflect current implementation including
+> `:through` option and `config_name`-based method naming.
+
+## The Original Naming Problem (Now Resolved)
+
+The parameter was renamed from `bidirectional:` to `generate_participant_methods:`.
+
+`bidirectional: true` was misleading because:
 
 1. It's not truly bidirectional - It only helps you manage membership in specific instances, not query all memberships
-2. Better name would be: generate_participant_methods: true
+2. Better name: `generate_participant_methods: true` (**now implemented**)
 3. True bidirectionality would mean both sides can easily query their relationships
 
-What True Bidirectionality Should Look Like
+## What True Bidirectionality Should Look Like
 
-Option 1: Auto-generate reverse collections
+### Option 1: Auto-generate reverse collections
 
+```ruby
 class Customer < Familia::Horreum
   participates_in Team, :members, bidirectional: true, reverse: :teams
 end
@@ -18,9 +26,11 @@ end
 customer.teams           # All teams this customer is in
 customer.teams.count     # How many teams
 customer.teams.include?(team_id)  # Check membership
+```
 
-Option 2: Make bidirectional actually bidirectional
+### Option 2: Make bidirectional actually bidirectional
 
+```ruby
 class Customer < Familia::Horreum
   participates_in Team, :members, bidirectional: true
 end
@@ -28,10 +38,13 @@ end
 # Should auto-generate (using pluralized class name):
 customer.teams           # Since we're participating in Team class
 customer.organizations   # If also participating in Organization class
+```
 
-Current Implementation Gap
+## The Implementation Gap (Historical Context)
 
-Looking at the actual usage pattern:
+Looking at the original usage pattern:
+
+```ruby
 # Easy to go from Team → Customers
 team.members.to_a        # Simple!
 customers = Customer.multiget(*team.members.to_a)
@@ -41,89 +54,219 @@ customer.participations.members
   .select { |k| k.start_with?("team:") }
   .map { |k| k.split(':')[1] }
   # ... etc - complicated!
+```
+
+### What Was Really Happening
 
-What's Really Happening
+The bidirectional flag only controlled whether these instance-to-instance methods were generated:
+- `customer.add_to_team_members(specific_team)`
+- `customer.in_team_members?(specific_team)`
 
-The bidirectional flag only controls whether these instance-to-instance methods are generated:
-- customer.add_to_team_members(specific_team)
-- customer.in_team_members?(specific_team)
+It did NOT create instance-to-collection methods:
+- `customer.teams` ❌
+- `customer.all_team_memberships` ❌
 
-It does NOT create instance-to-collection methods:
-- customer.teams ❌
-- customer.all_team_memberships ❌
+---
 
+## Current Implementation (Familia 2.x)
 
-The functionality we are hoping to achieve:
-Bidirectional Relationships Feature Spec
+The solution now auto-generates reverse collection methods on participant classes.
 
-Problem
+### Implemented API (Using `_instance` Suffix + `config_name` Naming)
 
-Currently, Familia relationships are asymmetric. While you can easily query team.members to get all members, there's no convenient way to get
-all teams a user belongs to without manually parsing the participations reverse index.
+**Important**: Method names are based on the target class's `config_name` (snake_case of
+the full class name), not just the class basename. This ensures uniqueness when
+multiple classes have the same basename (e.g., `Admin::Team` vs `Public::Team`).
 
-Solution
+```ruby
+class Domain < Familia::Horreum
+  # Customer.config_name => "customer"
+  participates_in Customer, :domains
+  # Auto-generates on Domain:
+  #   domain.customer_instances
+  #   domain.customer_ids
+  #   domain.customer?
+  #   domain.customer_count
 
-Auto-generate reverse collection methods on participant classes to provide symmetric access to relationships.
+  # With custom naming via `as:`
+  participates_in Customer, :partner_domains, as: :partners
+  # Auto-generates:
+  #   domain.partners_instances
+  #   domain.partners_ids
+  #   domain.partners?
+  #   domain.partners_count
+end
 
-## Implemented API (Using _instance Suffix Pattern)
+class ProjectTeam < Familia::Horreum
+  # Note: config_name is "project_team", not "team"
+end
 
 class User < Familia::Horreum
-  participates_in Team, :members          # Auto-generates: user.team_instances
-  participates_in Team, :admins           # Also adds to: user.team_instances (union)
-  participates_in Organization, :employees # Auto-generates: user.organization_instances
-  participates_in Organization, :contractors, as: :contracting_orgs  # Custom name
+  participates_in ProjectTeam, :members
+  # Auto-generates: user.project_team_instances (NOT user.team_instances)
+end
+```
+
+### Forward Direction (Target Class Methods)
+
+```ruby
+customer.domains                         # → SortedSet of domain IDs
+customer.add_domains_instance(domain)    # → Adds + tracks participation
+customer.remove_domains_instance(domain) # → Removes + untracks
+```
+
+### Reverse Direction (Participant Class Methods)
+
+```ruby
+domain.customer_instances    # → Array of Customer instances
+domain.customer_ids          # → Array of customer IDs (no object loading)
+domain.customer?             # → Boolean: participates in any customers?
+domain.customer_count        # → Integer count without loading objects
+```
+
+### Implementation Status
+
+| Method Pattern | Forward (Target) | Reverse (Participant) |
+|----------------|------------------|----------------------|
+| `*_instances` | `add_*_instance`, `remove_*_instance` | `{config_name}_instances` |
+| `*_ids` | N/A (use collection directly) | `{config_name}_ids` |
+| `*?` | N/A | `{config_name}?` |
+| `*_count` | N/A (use `collection.size`) | `{config_name}_count` |
+
+---
+
+## Through Models (New in 2.x)
+
+The `:through` option enables rich join model patterns for storing additional
+membership data (roles, timestamps, status).
+
+```ruby
+class OrganizationMembership < Familia::Horreum
+  feature :object_identifier  # Required for through models
+  prefix :org_membership
+
+  field :organization_id
+  field :customer_id
+  field :role             # 'owner', 'admin', 'member'
+  field :status           # 'active', 'pending', 'declined'
+  field :invited_at
+  field :joined_at
+end
+
+class Customer < Familia::Horreum
+  participates_in Organization, :members,
+    score: :joined,
+    through: :OrganizationMembership
 end
+```
+
+### Through Model Behavior
+
+```ruby
+# Adding creates/updates the through model
+membership = org.add_members_instance(customer, through_attrs: { role: 'admin' })
+membership.role  # => 'admin'
+
+# Chaining pattern also works
+membership = org.add_members_instance(customer)
+membership.role = 'admin'
+membership.save
 
-# Forward (existing)
-team.members                       # → SortedSet of user IDs
-team.add_members_instance(user)    # → Adds to collection + tracks participation
-team.remove_members_instance(user) # → Removes from collection + untracks
+# Removing destroys the through model
+org.remove_members_instance(customer)  # OrganizationMembership is deleted
+```
 
-# Reverse (NEW)
-user.team_instances                # → Array of Team instances user belongs to
-user.team_ids                      # → Array of team IDs (efficient, no loading)
-user.team?                         # → Boolean: belongs to any teams?
-user.team_count                    # → Count without loading objects
+### Through Model Requirements
 
-# Custom naming (user chooses base name via as: parameter)
-user.contracting_orgs_instances    # → Array of Organization instances
-user.contracting_orgs_ids          # → Array of IDs
-user.contracting_orgs?             # → Boolean
-user.contracting_orgs_count        # → Count
+- Must have `feature :object_identifier` enabled
+- Through model is auto-created on add, auto-destroyed on remove
+- Attributes can be passed inline via `through_attrs:` or set after
+
+---
 
 ## Naming Rationale: Why `_instance` Suffix?
 
-The implementation uses an `_instance` suffix pattern instead of pluralization/singularization to avoid fragility:
+The implementation uses an `_instance` suffix pattern instead of pluralization/singularization:
 
 **Target Methods (Forward Direction):**
-- `team.add_members_instance(user)` instead of `team.add_member(user)`
-- `team.remove_members_instance(user)` instead of `team.remove_member(user)`
+- `customer.add_domains_instance(domain)` instead of `customer.add_domain(domain)`
+- `customer.remove_domains_instance(domain)` instead of `customer.remove_domain(domain)`
 
 **Reverse Collection Methods:**
-- `user.team_instances` instead of `user.teams`
+- `domain.customer_instances` instead of `domain.customers`
 - `user.organization_instances` instead of `user.organizations`
 
 **Benefits:**
-1. **No irregular plurals** - Avoids issues with words like "person/people", "child/children", "foot/feet"
+1. **No irregular plurals** - Avoids issues with "person/people", "child/children", "foot/feet"
 2. **Clear intent** - The suffix makes it obvious you're working with instances, not counts or IDs
 3. **Consistent pattern** - Same suffix for both forward and reverse operations
-4. **No external dependencies** - Removes need for inflection libraries like `dry-inflector`
+4. **No external dependencies** - No need for inflection libraries like `dry-inflector`
 5. **Predictable** - Easy to remember and document
 
 **Trade-off:**
 - Slightly more verbose, but eliminates an entire class of edge case bugs
 
-Key Requirements
+---
+
+## The `method_prefix:` Option
+
+The default implementation uses `config_name` which can be verbose for namespaced
+classes (e.g., `admin_project_team_instances`). The `method_prefix:` option provides
+explicit control over reverse method naming:
+
+```ruby
+participates_in Admin::ProjectTeam, :members, method_prefix: :team
+# Generates: user.team_instances instead of user.admin_project_team_instances
+```
+
+### Parameter Priority
+
+When multiple naming options are provided, the most specific wins:
+
+| Parameter | Scope | Priority |
+|-----------|-------|----------|
+| `as:` | Single collection only | 1 (highest) |
+| `method_prefix:` | All collections for target class | 2 |
+| (default) | Uses `config_name` | 3 (lowest) |
+
+### Examples
+
+```ruby
+# Default: uses config_name
+participates_in Admin::ProjectTeam, :members
+# → user.admin_project_team_instances, user.admin_project_team_ids, etc.
+
+# With method_prefix: shorter, cleaner names
+participates_in Admin::ProjectTeam, :members, method_prefix: :team
+# → user.team_instances, user.team_ids, user.team?, user.team_count
+
+# With as: overrides for specific collection only
+participates_in Admin::ProjectTeam, :members, as: :my_teams
+# → user.my_teams_instances, user.my_teams_ids, etc.
+
+# Both as: and method_prefix: - as: wins (more specific)
+participates_in Admin::ProjectTeam, :members, method_prefix: :team, as: :my_teams
+# → user.my_teams_instances (as: takes precedence)
+```
+
+This gives developers explicit control over method naming while maintaining
+the predictability of the default system.
+
+---
+
+## Key Requirements (All Implemented)
 
-1. Automatic generation - No manual method definitions needed
-2. Multiple collections - Union of all collections to same target class
-3. Performance - Efficient ID-only access without loading objects (no caching for data freshness)
-4. Custom naming - Override auto-generated names when needed via `as:` parameter
-5. Thread-safe - No caching means no stale data or cache invalidation complexity
+1. **Automatic generation** - No manual method definitions needed ✓
+2. **Multiple collections** - Union of all collections to same target class ✓
+3. **Performance** - Efficient ID-only access without loading objects ✓
+4. **Custom naming** - Override auto-generated names via `as:` or `method_prefix:` parameters ✓
+5. **Thread-safe** - No caching means no stale data or cache invalidation complexity ✓
+6. **Through models** - Rich join data via `:through` option ✓
 
-Benefits
+## Benefits
 
-- Symmetry - Both directions equally convenient
-- Discoverability - Natural Ruby method names
-- Efficiency - Choose between full objects, IDs, or counts
-- Backwards compatible - All existing code continues to work
+- **Symmetry** - Both directions equally convenient
+- **Discoverability** - Natural Ruby method names
+- **Efficiency** - Choose between full objects, IDs, or counts
+- **Backwards compatible** - All existing code continues to work
+- **Extensible** - Through models enable rich membership data