rubocop-dev_doc 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05e1aabe21621ec2ef5867764976fcfb58d7e0bb42b6224f56065ac17bb5cd8b
-  data.tar.gz: 2adbd5114fa685aaf7240c04df9fadb955d2cba1a0ccfd83d1e8fb44751f9743
+  metadata.gz: 11175a594b0adb68ca20c3e2ff0ef414d1136d55152cd010a8d95ee26601a759
+  data.tar.gz: 460f211f62e554bead8cd267a4c3e918159eccff748d2d03f0f06b56454d025e
 SHA512:
-  metadata.gz: ffe0a1d90cdf8d0a4dcee8ba865631f9d9c8e3a1e2b3de6af25aa6eb9441a966d715d099e3824e40ec5ec2640c001d9043f375e81fc590732309554b81b80e18
-  data.tar.gz: 1d164d6cc051b8f216384ef334d0b5015a08d52a71cdb9b93e0cf065b6440e9a7285c3d4904d83be92936631b638428ff1dd816f39ace4a76b6053ee98b184b4
+  metadata.gz: 5b5a9ae0aed54ff1979d4deb8313ef53e0e8b3d831e9d3bbdabaf9c4d9c3897acd7486054cbd012222453c9e6dbcd0054821ea83ddac71c1231bc51d7be6072e
+  data.tar.gz: e6acacc3e7f65769104c90d5043a08c6385983ab6c9f38db8088ff30193044ac1cd6e14b365c1cbf521de52d445b84e9c4312f75e2dcb6ab93370077a8134bed

data/config/default.yml

@@ -403,6 +403,18 @@ DevDoc/Rails/ApplicationRecordTransaction:
   Exclude:
     - "app/models/**/*.rb"
 
+DevDoc/Rails/ApplicationModelBase:
+  Description: "Inherit the app's ApplicationModel root instead of including ActiveModel::Model directly (three-way rule, backend/03_model.md item 9)."
+  # Disabled by default: requires the project to have an ApplicationModel root
+  # over glib-web's Glib::Model. Enable per project, scoped to app/models; the
+  # root itself and any engine-side base need excluding where they legitimately
+  # carry the include.
+  Enabled: false
+  Include:
+    - "app/models/**/*.rb"
+  Exclude:
+    - "app/models/application_model.rb"
+
 DevDoc/Style/AvoidOptionsHash:
   Description: "Use keyword arguments instead of `**options` — typos raise `ArgumentError`; options hashes swallow them silently."
   Enabled: true

data/lib/dev_doc/test/lints/domain_class_base.rb

@@ -0,0 +1,138 @@
+require 'pathname'
+
+module DevDoc
+  module Test
+    module Lints
+      # Runtime check: every CLASS defined by a file under `app/models/`
+      # (excluding `concerns/`) must descend from one of the project's domain
+      # base classes. Runs with the app loaded, so real ancestry is checked —
+      # intermediate family bases and indirect inheritance resolve correctly,
+      # which is exactly what a per-file static cop cannot do.
+      #
+      # Wrapped by the Minitest module `DomainClassBase` below — see that
+      # module for the rationale.
+      class DomainClassBaseChecker
+        # The three-way rule (best_practices/backend/en/03_model.md item 9):
+        # persisted -> ApplicationRecord; table-less but form-backed ->
+        # ApplicationModel; plain domain logic -> PlainModel.
+        DEFAULT_BASE_CLASS_NAMES = %w[ApplicationRecord ApplicationModel PlainModel].freeze
+
+        def initialize(project_root, base_class_names: DEFAULT_BASE_CLASS_NAMES, allowed_paths: [])
+          @project_root = Pathname(project_root)
+          @base_class_names = base_class_names
+          @allowed_paths = allowed_paths
+        end
+
+        # Returns an Array<String> of offender descriptions, or `[]` when
+        # every model class descends from an allowed base. Modules are skipped:
+        # the three-way rule classifies CLASSES — namespaces, function-bag
+        # modules, and concerns carry no instance state to classify.
+        def offenders
+          bases = @base_class_names.map(&:constantize)
+
+          model_files.filter_map do |path|
+            constant = constant_for(path)
+            next if constant.nil? # module or namespace-only file
+            next if bases.any? { |base| constant <= base }
+
+            "  #{relative(path)}: #{constant.name} < #{constant.superclass.name} — #{hint_for(constant)}"
+          end
+        end
+
+        private
+
+        def model_files
+          Dir.glob(@project_root.join('app/models/**/*.rb')).reject do |path|
+            relative = relative(path)
+            relative.start_with?('app/models/concerns/') ||
+              @allowed_paths.any? { |allowed| relative.start_with?(allowed) }
+          end
+        end
+
+        # Zeitwerk guarantees the file defines the constant its path names, so
+        # deriving it from the path (rather than parsing the source) is exact,
+        # and nested helper classes (e.g. error classes inside a model) are
+        # never enumerated.
+        def constant_for(path)
+          name = relative(path).delete_prefix('app/models/').delete_suffix('.rb').camelize
+          constant = name.constantize
+          constant.is_a?(Class) ? constant : nil
+        end
+
+        def hint_for(constant)
+          if constant.include?(ActiveModel::Model)
+            'it includes ActiveModel::Model, so inherit ApplicationModel instead'
+          else
+            'inherit PlainModel (or ApplicationRecord/ApplicationModel if it persists or backs a form)'
+          end
+        end
+
+        def relative(path)
+          Pathname(path).relative_path_from(@project_root).to_s
+        end
+      end
+
+      # Domain-class base tripwire: every class under `app/models/` must be one
+      # of the project's three kinds — persisted (ApplicationRecord),
+      # form-backed (ApplicationModel), or plain domain logic (PlainModel).
+      #
+      # ## Rationale
+      # The three-way rule (backend/03_model.md item 9) makes the author
+      # classify each domain class at creation time; the base's docstring then
+      # states the contract that kind carries. Static analysis cannot enforce
+      # totality — RuboCop sees one file at a time, so it cannot resolve
+      # whether `class Foo < SomeFamilyBase` ultimately reaches an allowed
+      # base. This lint checks real ancestry with the app loaded, so
+      # intermediate bases resolve and the rule is enforced literally.
+      # `Rails/ApplicationRecord` and `DevDoc/Rails/ApplicationModelBase`
+      # remain useful beside it for editor-time feedback on the two common
+      # direct mistakes.
+      #
+      # NOTE: Limitations:
+      # - Only classes whose files live under `app/models/` are checked; a
+      #   domain class parked elsewhere is invisible (placement itself is the
+      #   orchestration taxonomy's reviewer-owned residual).
+      # - Modules are skipped by design (namespaces, function-bag modules,
+      #   concerns) — the rule classifies classes.
+      #
+      # ## Usage
+      # Include this module in a Minitest test class (Rails test env) in a
+      # project whose three bases exist. Override the constants on the test
+      # class to rename bases or exempt a sanctioned file:
+      #
+      #   class DomainClassBaseTest < ActiveSupport::TestCase
+      #     include DevDoc::Test::Lints::DomainClassBase
+      #     # DOMAIN_BASE_CLASS_NAMES = %w[ApplicationRecord ApplicationModel PlainModel].freeze
+      #     # ALLOWED_DOMAIN_CLASS_PATHS = %w[app/models/legacy/].freeze
+      #   end
+      module DomainClassBase
+        # Defaults. Per-project override: redefine the constants on the test
+        # class that includes this module.
+        DOMAIN_BASE_CLASS_NAMES = DomainClassBaseChecker::DEFAULT_BASE_CLASS_NAMES
+        ALLOWED_DOMAIN_CLASS_PATHS = [].freeze
+
+        def test_every_model_class_descends_from_a_domain_base
+          offenders = DomainClassBaseChecker.new(
+            Rails.root,
+            base_class_names: self.class::DOMAIN_BASE_CLASS_NAMES,
+            allowed_paths: self.class::ALLOWED_DOMAIN_CLASS_PATHS
+          ).offenders
+
+          assert offenders.empty?, domain_class_base_message(offenders)
+        end
+
+        private
+
+        def domain_class_base_message(offenders)
+          "Classes under app/models must descend from one of " \
+            "#{self.class::DOMAIN_BASE_CLASS_NAMES.join(' / ')} — the three-way rule " \
+            "(backend/03_model.md item 9): persisted -> ApplicationRecord, form-backed " \
+            "-> ApplicationModel, plain domain logic -> PlainModel. If a class is a " \
+            "sanctioned exception, add its path to ALLOWED_DOMAIN_CLASS_PATHS on the " \
+            "including test class with a comment.\n\n" \
+            "Offenders:\n#{offenders.join("\n")}"
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/rails/application_model_base.rb

@@ -0,0 +1,56 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Inherit the app's `ApplicationModel` root instead of including
+        # `ActiveModel::Model` directly in a class under `app/models`.
+        #
+        # ## Rationale
+        # Table-less form-backed domain objects follow the three-way rule
+        # (backend/03_model.md item 9): persisted classes inherit
+        # `ApplicationRecord`, form-backed POROs inherit `ApplicationModel`
+        # (a thin app root over `Glib::Model`, which carries the shared
+        # mechanics such as `attr_id_list`), and plain domain logic inherits
+        # `PlainModel`. A direct `include ActiveModel::Model` bypasses the
+        # shared root: the class silently misses the shared mechanics, and the
+        # author never makes the which-kind-is-this decision the rule exists
+        # to force. This is the ActiveModel analog of `Rails/ApplicationRecord`.
+        #
+        # This cop gives editor-time feedback on the single most common direct
+        # mistake; totality (every model class descends from one of the three
+        # bases, through any intermediate family base) is enforced at test time
+        # by `DevDoc::Test::Lints::DomainClassBase`, since resolving indirect
+        # ancestry is beyond per-file static analysis.
+        #
+        # Disabled by default: enable it in projects whose `ApplicationModel`
+        # root exists (it requires glib-web's `Glib::Model`).
+        #
+        # @example
+        #   # bad
+        #   class BulkOperation
+        #     include ActiveModel::Model
+        #   end
+        #
+        #   # good
+        #   class BulkOperation < ApplicationModel
+        #   end
+        class ApplicationModelBase < Base
+          MSG = 'Inherit `ApplicationModel` instead of including `ActiveModel::Model` directly — ' \
+                'the shared root carries the form-object mechanics (backend/03_model.md item 9).'.freeze
+
+          RESTRICT_ON_SEND = %i[include].freeze
+
+          def_node_matcher :active_model_include?, <<~PATTERN
+            (send nil? :include (const (const {nil? cbase} :ActiveModel) :Model))
+          PATTERN
+
+          def on_send(node)
+            return unless active_model_include?(node)
+
+            add_offense(node)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.16.0".freeze
+    VERSION = "0.17.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-28 00:00:00.000000000 Z
+date: 2026-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -95,6 +95,7 @@ files:
 - lib/dev_doc/test/lints/cron_schedule.rb
 - lib/dev_doc/test/lints/cross_tenant_canary_check.rb
 - lib/dev_doc/test/lints/cross_tenant_canary_sweep.rb
+- lib/dev_doc/test/lints/domain_class_base.rb
 - lib/dev_doc/test/lints/duplicate_snapshot.rb
 - lib/dev_doc/test/lints/enqueue_disable_naming.rb
 - lib/dev_doc/test/lints/external_io_boundary.rb
@@ -133,6 +134,7 @@ files:
 - lib/rubocop/cop/dev_doc/migration/require_primary_key.rb
 - lib/rubocop/cop/dev_doc/migration/require_reference_foreign_key.rb
 - lib/rubocop/cop/dev_doc/migration/require_timestamps.rb
+- lib/rubocop/cop/dev_doc/rails/application_model_base.rb
 - lib/rubocop/cop/dev_doc/rails/application_record_transaction.rb
 - lib/rubocop/cop/dev_doc/rails/avoid_bypassing_validation.rb
 - lib/rubocop/cop/dev_doc/rails/avoid_lifecycle_method_override.rb