foundries 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf089585b858ec4b4fb09964e7b8e17d1c2bcc3dcc1236a5a1414afb49810c11
-  data.tar.gz: 9919d0537dd62b84c9e3b49ccfce1de19778998203aca7e5bff36292e790fb8c
+  metadata.gz: c8245b09fe2227ef4a25d5751c30f4a94a1d2d80519ef5fb97b8ba2b9dc527ef
+  data.tar.gz: 24162154115e9f413117fb88d71aa0cbc19374cbbf9b6fa059f23e36535511e5
 SHA512:
-  metadata.gz: 8a1a3e44f94106f6a4b8ac0702c9ffff6d55e54d57cd4c7e19d8c34eb8ee74cebadadf35267a49269c5e638d2fae9421de3e47af9577377b9d42f9fc21cdd38d
-  data.tar.gz: f3045a5705fd20d79d0ac77c29b4f104f6c6d09b690e39bb94d93c3f78df8458f883da25ec5efe68aced414d11cb1b879db6b03c205befa308dbf9f4aba1bf75
+  metadata.gz: f0b22d20d6edc795ef1c7a2f3403b1a7e5cbbbc0d3ca4bd19fc82c25992bcea6d460175df202d8cd0465dd328a8bc189672171423ed283aa7879390450261318
+  data.tar.gz: 1ece80e18cdc964013db346ec665e2919f146bda411ddaf4254abb4c714c712a4a692cb30241a051da98029c164fbbc77b1e4fc44c2dac0cadda396c0fbccadf

data/CHANGELOG.md

@@ -5,22 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [0.1.1] - 2026-03-06
+## [0.1.3] - 2026-03-13
 
 ### Added
 
-- Blueprint base class with collection tracking, parent scoping, and factory_bot integration (0002336)
-- Snapshot caching system with Postgres and SQLite adapters for test suite acceleration (0002336)
-- Source file content hashing in snapshot fingerprint for automatic cache invalidation (cfb348d)
+- ancestor DSL and ancestors_for for path-based hierarchy building (7027e06)
 
-### Changed
+## [0.1.2] - 2026-03-12
 
-- Snapshot caching is opt-in via ARMATURE_CACHE=1 environment variable (0002336)
-- Similarity detection only warns on identical structure, not containment (a5bdf25)
+### Added
 
-### Fixed
+- aliases DSL on Base for shorthand method names (377632f)
+- lookup_order DSL on Blueprint for ancestor traversal (377632f)
+- find_or_create pattern on Blueprint (377632f)
+- Tests for inherited registries, parent-scoped find, collection_find_by kwargs, find_or_create, ascending_find, and parent_present? (2d92945)
 
-- Parentless blueprints no longer raise NameError when find calls same_parent? (cfb348d)
-- Snapshot-cached presets no longer produce false similarity warnings (a5bdf25)
+### Changed
 
-## [0.1.0] - 2026-02-25
+- Collections initialize before blueprints (377632f)
+- Fix find parent scoping and collection_find_by kwargs handling (3ebfc3e)

data/lib/foundries/base.rb

@@ -59,6 +59,18 @@ module Foundries
         blueprint_registry.keys.filter_map { |klass| klass.collection_name&.to_s }
       end
 
+      # Declare shorthand aliases for blueprint methods.
+      #
+      #   aliases member: :enrollment, hva_mod: :skilled_mod
+      #
+      # Resolves aliases during method_missing before blueprint
+      # delegation.
+      def aliases(mapping = nil)
+        return @aliases || {} unless mapping
+
+        @aliases = (@aliases || {}).merge(mapping)
+      end
+
       # Methods delegated from this foundry to its blueprint instances.
       def delegations
         blueprint_registry.select { |_, methods| methods.any? }
@@ -121,16 +133,17 @@ module Foundries
 
       def inherited(subclass)
         super
-        # Ensure subclasses get their own registries
-        subclass.instance_variable_set(:@blueprint_registry, {})
-        subclass.instance_variable_set(:@extra_collections, [])
+        # Copy parent registries so subclasses inherit blueprints
+        subclass.instance_variable_set(:@blueprint_registry, blueprint_registry.dup)
+        subclass.instance_variable_set(:@extra_collections, extra_collections.dup)
+        subclass.instance_variable_set(:@aliases, aliases.dup)
       end
     end
 
     def initialize(&block)
       @_similarity_recorder = self.class._active_similarity_recorder
-      instantiate_blueprints
       initialize_collections
+      instantiate_blueprints
       @current = OpenStruct.new(resource: self)
       setup
       instance_exec(&block) if block
@@ -187,6 +200,31 @@ module Foundries
     end
     alias_method :update_current, :load_state
 
+    # Build a hierarchy from a path string or array.
+    # Finds the blueprint that handles `type` and calls
+    # `ancestors` on it to recursively create the chain.
+    #
+    #   ancestors_for :task, "org/block/template/phase/mod/event" do
+    #     task "my_task"
+    #   end
+    #
+    def ancestors_for(type, path = nil, path_arr: nil, &block)
+      path_arr ||= path.split("/")
+      blueprint_for(type).ancestors(path_arr, &block)
+    end
+
+    # Find the blueprint instance that handles a given method.
+    def blueprint_for(method_name)
+      resolved = self.class.aliases[method_name] || method_name
+      self.class.delegations.each do |klass, methods|
+        if methods.include?(resolved)
+          ivar = :"@#{ivar_name_for(klass)}"
+          return instance_variable_get(ivar)
+        end
+      end
+      raise "No blueprint handles :#{method_name}"
+    end
+
     private
 
     # Override in subclasses for post-initialize hooks (e.g. pending phase rules).
@@ -213,6 +251,13 @@ module Foundries
           end
         end
       end
+
+      # Set up alias methods that delegate to existing blueprint methods
+      self.class.aliases.each do |alias_name, target_name|
+        define_singleton_method(alias_name) do |*args, **kwargs, &block|
+          send(target_name, *args, **kwargs, &block)
+        end
+      end
     end
 
     def initialize_collections

data/lib/foundries/blueprint.rb

@@ -103,6 +103,36 @@ module Foundries
         end
       end
 
+      # Declare ancestor traversal order for ascending_find.
+      #
+      #   lookup_order %i[evented_mod phase cohort]
+      #
+      # When no parent is present, ascending_find walks these
+      # ancestor types on `current`, checking collection_name
+      # on each.
+      def lookup_order(ancestors = nil)
+        return @lookup_order || [] unless ancestors
+
+        @lookup_order = ancestors
+      end
+
+      # Declare the ancestor type for path-based hierarchy
+      # creation via `ancestors_for`.
+      #
+      #   ancestor :event
+      #
+      # Generates an `ancestors(path, &block)` method that
+      # pops the last path segment and either:
+      # - calls `foundry.send(type, name, &block)` if the
+      #   path is empty (terminal)
+      # - calls `foundry.ancestors_for(type, ...)` to
+      #   continue recursion otherwise
+      def ancestor(type = nil)
+        return @ancestor_type unless type
+
+        @ancestor_type = type
+      end
+
       # Declare which attributes are allowed through to factory_bot.
       def permitted_attrs(attr_list)
         define_method(:permitted_attrs) do |attrs|
@@ -195,6 +225,67 @@ module Foundries
       end
     end
 
+    # Walk a path array to build ancestor hierarchy, then
+    # yield the block in the innermost context. Requires
+    # the `ancestor` class DSL to be declared.
+    #
+    #   ancestors(["org", "block", "template"], &block)
+    #
+    def ancestors(path, &block)
+      type = self.class.ancestor
+      raise "No ancestor declared for #{self.class}" unless type
+
+      name = path.pop
+      if path.empty?
+        foundry.send(type, name, &block)
+      else
+        foundry.ancestors_for(type, path_arr: path) do
+          foundry.send(type, name, &block)
+        end
+      end
+    end
+
+    # Find or create: when no parent is present, walks ancestors
+    # via lookup_order; otherwise finds from parent or creates.
+    def find_or_create(name, attrs = {})
+      return ascending_find(name) unless parent_present?
+
+      find_from_parent(name) || create_object(name, attrs)
+    end
+
+    # Walk ancestor types declared in lookup_order, checking
+    # collection_name on each ancestor found in current state.
+    # Falls back to collection find.
+    def ascending_find(name)
+      object = nil
+      self.class.lookup_order.each do |ancestor_type|
+        ancestor = current.send(ancestor_type)
+        next unless ancestor
+
+        col = self.class.collection_name
+        object = ancestor.send(col).find_by(name:)
+        break if object
+      end
+
+      object || find(name)
+    end
+
+    # Whether a parent is available in the current context.
+    def parent_present?
+      parent_method = self.class.parent
+      return true if parent_method.in?(%i[self none])
+
+      parent
+    end
+
+    # Find from the parent's association, falling back to
+    # collection find.
+    def find_from_parent(name, col_name: "name")
+      col = self.class.collection_name
+      parent.send(col).find_by(col_name => name) ||
+        find(name, col_name:)
+    end
+
     # Find a record in the collection by name, falling back to the database.
     def find(name, col_name: "name")
       raise "#find called with nil :name, for col_name: #{col_name}." unless name
@@ -202,9 +293,13 @@ module Foundries
       found_record = collection.detect do |object|
         object.send(col_name).casecmp?(name) && same_parent?(object)
       end
+      return found_record if found_record
 
-      found_record ||
-        record_class.find_by(col_name => name)&.tap { |rec| collection << rec }
+      scope = record_class.where(col_name => name)
+      if parent_key && parent_id
+        scope = scope.where(parent_key => parent_id)
+      end
+      scope.first&.tap { |rec| collection << rec }
     end
 
     # Find a record in the collection by arbitrary criteria, falling back to the database.
@@ -254,7 +349,8 @@ module Foundries
     def method_missing(name, *args, **kwargs, &block)
       if (match = missing_find_by_request?(name))
         klass_name = match.named_captures["klass"]
-        return collection_find_by(klass_name, args)
+        attrs = kwargs.any? ? kwargs : args.first
+        return collection_find_by(klass_name, attrs)
       end
 
       if foundry.respond_to?(name)
@@ -274,8 +370,7 @@ module Foundries
       method_name.match(/^find_(?<klass>.*)_by$/)
     end
 
-    def collection_find_by(klass_name, args)
-      attrs = args.first
+    def collection_find_by(klass_name, attrs)
       target_collection_name = "#{klass_name.pluralize}_collection"
       objects = foundry.send(target_collection_name)
       objects.detect do |object|

data/lib/foundries/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Foundries
-  VERSION = "0.1.1"
-  RELEASE_DATE = "2026-03-06"
+  VERSION = "0.1.3"
+  RELEASE_DATE = "2026-03-13"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foundries
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - John Dowd