strict_associations 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 14e631cb0e94a7fd616afc1c62fd686625008b0f30916a6f45a3614038e4a460
+  data.tar.gz: a229561f5c4b1a54abf6433e54cfa1e13ec0480cd2274906fef3f5c52aa85049
+SHA512:
+  metadata.gz: 57336b91485f245790e47e8e6afe1974024f308b747c628b7eb370640e30873e2f190c196974f182dede3591fbcec43e2ba3fec03cb1536b9a1ad600cf6cc32e
+  data.tar.gz: 24dadd9079a717411b2a76a7df76c2bf056140ab13d662e6879e4de7b3b070100ffeef25669e1ba65526f51cfe5e28b741654efd01db2561bbe7a12944b9936c

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [0.1.0] - 2026-03-12
+
+### Added
+
+- Initial release
+- Validates `has_many` and `has_one` associations declare `:dependent`
+- Validates `belongs_to` associations have a matching inverse
+- Validates polymorphic `belongs_to` declares `valid_types:`
+- Detects `has_and_belongs_to_many` usage (configurable)
+- Per-association opt-out via `strict: false`
+- Per-model opt-out via `skip_strict_association`
+- Railtie for automatic setup in Rails applications

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 SOFware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/strict_associations/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module StrictAssociations
+  class Configuration
+    def initialize
+      @habtm_allowed = false
+    end
+
+    def allow_habtm(value = true)
+      @habtm_allowed = value
+    end
+
+    def habtm_allowed?
+      @habtm_allowed
+    end
+  end
+end

data/lib/strict_associations/railtie.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module StrictAssociations
+  class Railtie < Rails::Railtie
+    initializer "strict_associations.extend_active_record" do
+      ActiveSupport.on_load(:active_record) do
+        # Register :strict and :valid_types as recognized association options
+        %i[BelongsTo HasMany HasOne].each do |builder_name|
+          ActiveRecord::Associations::Builder
+            .const_get(builder_name)
+            .singleton_class.prepend(
+              Module.new do
+                define_method(:valid_options) do |options|
+                  extra = [:strict]
+                  extra << :valid_types if builder_name == :BelongsTo
+
+                  super(options) + extra
+                end
+              end
+            )
+        end
+
+        # Provide .skip_strict_association on all models
+        #
+        # Inside on_load(:active_record), self is ActiveRecord::Base, so we define
+        # directly.
+        def self.skip_strict_association(*names)
+          @_strict_associations_skipped ||= Set.new
+          names.each do |n|
+            @_strict_associations_skipped.add(n.to_sym)
+          end
+        end
+
+        def self.strict_associations_skipped
+          @_strict_associations_skipped || Set.new
+        end
+
+        def self.strict_association_skipped?(name)
+          klass = self
+          while klass && klass != ActiveRecord::Base
+            return true if klass.strict_associations_skipped.include?(name.to_sym)
+
+            klass = klass.superclass
+          end
+          false
+        end
+      end
+    end
+  end
+end

data/lib/strict_associations/validator.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+module StrictAssociations
+  class Validator
+    def initialize(configuration, models: nil)
+      @config = configuration
+      @explicit_models = models
+    end
+
+    def call
+      violations = []
+
+      models_to_check.each do |model|
+        check_habtm(model, violations)
+        check_belongs_to_inverses(model, violations)
+        check_polymorphic_inverses(model, violations)
+        check_dependent_options(model, violations)
+      end
+
+      violations
+    end
+
+    private
+
+    attr_reader :config, :explicit_models
+
+    def models_to_check
+      candidates = explicit_models || all_models
+      candidates.reject do |model|
+        model.abstract_class? || !safe_table_exists?(model) || view?(model)
+      end
+    end
+
+    def all_models
+      ActiveRecord::Base.descendants.reject(&:abstract_class?)
+    end
+
+    def safe_table_exists?(model)
+      model.table_exists?
+    rescue ActiveRecord::NoDatabaseError
+      false
+    end
+
+    def view?(model)
+      model.connection.view_exists?(model.table_name)
+    rescue ActiveRecord::NoDatabaseError
+      false
+    end
+
+    def check_habtm(model, violations)
+      return if config.habtm_allowed?
+
+      habtm = :has_and_belongs_to_many
+      model.reflect_on_all_associations(habtm).each do |ref|
+        next if skipped?(model, ref)
+
+        violations << Violation.new(
+          model:,
+          association_name: ref.name,
+          rule: :habtm_banned,
+          message: <<~MSG.squish
+            has_and_belongs_to_many is not allowed.
+            Use a join model with has_many :through instead.
+          MSG
+        )
+      end
+    end
+
+    def check_belongs_to_inverses(model, violations)
+      refs = model.reflect_on_all_associations(:belongs_to)
+      refs.each do |ref|
+        next if skipped?(model, ref)
+        next if ref.options[:polymorphic]
+
+        target = resolve_target(ref)
+        next unless target
+
+        unless inverse_exists?(model, ref, target)
+          fk = ref.foreign_key
+          inverse_name = model.table_name.to_sym
+          violations << Violation.new(
+            model:,
+            association_name: ref.name,
+            rule: :missing_inverse,
+            message: <<~MSG.squish
+              #{target} has no has_many/has_one pointing back to \
+              #{model.table_name} with foreign key #{fk}. \
+              Define the inverse. \
+              Or mark this association with strict: false. \
+              Or call skip_strict_association :#{inverse_name} \
+              on #{target}
+            MSG
+          )
+        end
+      end
+    end
+
+    def check_polymorphic_inverses(model, violations)
+      refs = model.reflect_on_all_associations(:belongs_to)
+      refs.each do |ref|
+        next if skipped?(model, ref)
+        next unless ref.options[:polymorphic]
+
+        resolved = resolve_valid_types(model, ref)
+
+        unless resolved
+          violations << Violation.new(
+            model:,
+            association_name: ref.name,
+            rule: :unregistered_polymorphic,
+            message: <<~MSG.squish
+              #{model}##{ref.name} is polymorphic but has no \
+              valid_types declared. Add valid_types: to the \
+              association. Or mark with strict: false.
+            MSG
+          )
+          next
+        end
+
+        type_violations, types =
+          resolved.partition { |r| r.is_a?(Violation) }
+        violations.concat(type_violations)
+        check_registered_polymorphic_types(
+          model, ref, types, violations
+        )
+      end
+    end
+
+    def resolve_valid_types(model, ref)
+      inline = ref.options[:valid_types]
+      return unless inline
+
+      resolved = []
+      Array(inline).each do |t|
+        resolved << t.to_s.constantize
+      rescue NameError => e
+        resolved << Violation.new(
+          model:,
+          association_name: ref.name,
+          rule: :invalid_valid_type,
+          message: <<~MSG.squish
+            #{model}##{ref.name} declares valid_types \
+            containing "#{t}" but #{e.message}. \
+            Check for typos in valid_types.
+          MSG
+        )
+      end
+
+      resolved
+    end
+
+    def check_registered_polymorphic_types(
+      model, ref, types, violations
+    )
+      fk = ref.foreign_key.to_s
+      source_table = model.table_name
+
+      types.each do |type_class|
+        next if polymorphic_inverse_exists?(
+          type_class, source_table, fk
+        )
+
+        violations << Violation.new(
+          model:,
+          association_name: ref.name,
+          rule: :missing_polymorphic_inverse,
+          message: <<~MSG.squish
+            #{type_class} is registered for \
+            #{model}##{ref.name} but has no has_many/has_one \
+            pointing back to #{source_table} with foreign \
+            key #{fk}.
+          MSG
+        )
+      end
+    end
+
+    def check_dependent_options(model, violations)
+      %i[has_many has_one].each do |macro|
+        model.reflect_on_all_associations(macro).each do |ref|
+          next if skipped?(model, ref)
+          next if ref.is_a?(
+            ActiveRecord::Reflection::ThroughReflection
+          )
+          next if target_is_view?(ref)
+
+          unless ref.options.key?(:dependent)
+            violations << Violation.new(
+              model:,
+              association_name: ref.name,
+              rule: :missing_dependent,
+              message: <<~MSG.squish
+                #{model}##{ref.name} is missing a :dependent \
+                option. Add dependent: :destroy, :delete_all, \
+                :nullify, or :restrict_with_exception. \
+                Or mark with strict: false. \
+                Or call skip_strict_association :#{ref.name} \
+                on #{model}.
+              MSG
+            )
+          end
+        end
+      end
+    end
+
+    def resolve_target(reflection)
+      reflection.klass
+    rescue NameError
+      nil
+    end
+
+    def inverse_exists?(source_model, belongs_to_ref, target)
+      fk = belongs_to_ref.foreign_key.to_s
+      source_table = source_model.table_name
+
+      target.reflect_on_all_associations.any? do |ref|
+        next unless %i[has_many has_one].include?(ref.macro)
+        next if ref.is_a?(
+          ActiveRecord::Reflection::ThroughReflection
+        )
+
+        begin
+          ref.klass.table_name == source_table &&
+            ref.foreign_key.to_s == fk
+        rescue NameError
+          false
+        end
+      end
+    end
+
+    def polymorphic_inverse_exists?(type, table, fk)
+      type.reflect_on_all_associations.any? do |ref|
+        next unless %i[has_many has_one].include?(ref.macro)
+        next if ref.is_a?(
+          ActiveRecord::Reflection::ThroughReflection
+        )
+
+        begin
+          ref.klass.table_name == table &&
+            ref.foreign_key.to_s == fk
+        rescue NameError
+          false
+        end
+      end
+    end
+
+    def target_is_view?(reflection)
+      target = resolve_target(reflection)
+      target && view?(target)
+    end
+
+    def skipped?(model, ref)
+      ref.options[:strict] == false ||
+        model.strict_association_skipped?(ref.name)
+    end
+  end
+end

data/lib/strict_associations/version.rb

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

data/lib/strict_associations/violation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module StrictAssociations
+  class Violation
+    attr_reader :model, :association_name, :rule, :message
+
+    def initialize(model:, association_name:, rule:, message:)
+      @model = model
+      @association_name = association_name
+      @rule = rule
+      @message = message
+    end
+  end
+end

data/lib/strict_associations.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "strict_associations/version"
+require_relative "strict_associations/configuration"
+require_relative "strict_associations/validator"
+require_relative "strict_associations/violation"
+require_relative "strict_associations/railtie" if defined?(Rails::Railtie)
+
+module StrictAssociations
+  class ViolationError < StandardError; end
+
+  class << self
+    def configure(&block)
+      @configure_block = block
+      block.call(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def validate!(models: nil)
+      eager_load_if_needed
+      config = Configuration.new
+      @configure_block&.call(config)
+      @configuration = config
+
+      validator = Validator.new(config, models:)
+      violations = validator.call
+
+      return if violations.empty?
+
+      raise ViolationError, format_violations(violations)
+    end
+
+    def reset!
+      @configuration = nil
+      @configure_block = nil
+    end
+
+    private
+
+    def eager_load_if_needed
+      return unless defined?(Rails)
+      return if Rails.application.config.eager_load
+
+      Rails.application.eager_load!
+    end
+
+    def format_violations(violations)
+      lines = violations.map do |v|
+        "  #{v.model}.#{v.association_name}" \
+          " [#{v.rule}]: #{v.message}"
+      end
+
+      <<~MSG
+        StrictAssociations found #{violations.size} violation(s):
+
+        #{lines.join("\n")}
+      MSG
+    end
+  end
+end

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: strict_associations
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jeff Lange
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: reissue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+description: |
+  Enforces that both sides of an association (e.g. belongs_to, has_many) are
+  explicitly defined. Enforces that has_many (or has_one) associations define a
+  :dependent option, or explicitly opt-out via `strict: false`
+email:
+- jeff.lange@sofwarellc.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- lib/strict_associations.rb
+- lib/strict_associations/configuration.rb
+- lib/strict_associations/railtie.rb
+- lib/strict_associations/validator.rb
+- lib/strict_associations/version.rb
+- lib/strict_associations/violation.rb
+homepage: https://github.com/SOFware/strict_associations
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/SOFware/strict_associations
+  changelog_uri: https://github.com/SOFware/strict_associations/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Enforces explicit definition of both sides of ActiveRecord associations (e.g.
+  belongs_to, has_many)
+test_files: []