rubocop-katalyst 3.0.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a3da31c89d2b9f9926408c588371742a0ae1d8b912c56cb44273616135b528c
-  data.tar.gz: 308439a55bc2d7c2d40a43f1d5eaf879a53d599a707f1366cf802703cfe62d83
+  metadata.gz: ca026117c849f4df349fe5c67aed0695aedfc780a64af122996eb3d51fc3cc28
+  data.tar.gz: db9a73d62f9d1f0005540ae233de188ce4fa7486272a06387ac72335b8bc3037
 SHA512:
-  metadata.gz: 75bf1de953b0125adab24812789f19fe06dbb96c67f608a824d97fbbdc77185b08a855d18b2d3d36108cccfd53cd264220f34e49f67864f88442854b5cd09623
-  data.tar.gz: 9c8d94ef1dddc927453f8f3548d4410c92a4d1eb1cd48873ba4b29122031c14e88021d430f830d98a145352ef188b01decb8dd1cae7f6546aefde520cd84b73e
+  metadata.gz: 752ce4174f0ea3121ba76a2cfe72c49771e0069dc4f940eda114f789ed13a73cc1dbe88558efb4a193765c3b5038003a8af8a2c3979a4b126d515d5b171304c2
+  data.tar.gz: d9dd3b37ec0884d11b0d08a0ceb228315174b00ffdc6736246bd1da5e9f8271f7fa1d2af91809170d5ebfc2d0f664daba801d0d8b0ac5be4ed7d46b8150859c7

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [3.2.0] - 2026-08-17
+
+- Add Koi/DuplicatesAssociation identifying Katalyst::Content items that
+  have associations but don't use the library-provided `duplicates_association`
+  helper.
+
+## [3.1.0] - 2026-08-14
+
+- Add Koi department for custom cops specific to katalyst-koi projects,
+  configured in `config/rubocop-koi.yml` and applied to admin views via erb_lint
+- Add Koi/TableLinkHeading cop: tables in admin index/archived views and row
+  partials should link to the record once, from the column that identifies
+  it. A single record link must be marked `heading: true` (autocorrectable);
+  additional links should use `text`, or `heading: false` when intentional
+- Run tests and linting in CI via `bin/ci`
+- Remove prettier/yarn from this repository and stop shipping `package.json`
+  in the gem — nothing consumed it, and downstream `PrettierTask` installs
+  prettier in the host project itself
+
 ## [3.0.0] - 2026-05-21
 
 - Update Ruby minimum version and syntax to 4.0

data/README.md

@@ -1,9 +1,11 @@
 # Rubocop::Katalyst
 
-[Katalyst's](https://katalyst.com.au) style guide for Ruby and Rails, in gem form. Katalyst does not at present have any custom cops; this is simply a repository for our configuration of the standard cops with Rails, Rake, Performance and RSpec extensions.
+[Katalyst's](https://katalyst.com.au) style guide for Ruby and Rails, in gem form. This is a repository for our configuration of the standard cops with Rails, Rake, Performance and RSpec extensions, plus our own custom cops.
 
 Cops are broken down by department; a file corresponding to each department can be found in the `config` directory, as well as the `default.yml` file which contains any global configuration and loads the cops. The `.rubocop.yml` file contains the configuration for this particular project as a guide for use in non-Rails environments.
 
+Custom cops in the `Koi` department apply to projects built on [katalyst-koi](https://github.com/katalyst/koi). They target admin views, which plain RuboCop does not inspect — they take effect when RuboCop runs through [erb_lint](https://github.com/Shopify/erb_lint) (`rake erb_lint`), which lints the Ruby inside ERB templates. If your `.erb_lint.yml` restricts the RuboCop linter with an `only:` list, add the `Koi` cops to that list.
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/config/default.yml

@@ -15,6 +15,7 @@ inherit_mode:
 inherit_from:
   - "./rubocop-bundler.yml"
   - "./rubocop-gemspec.yml"
+  - "./rubocop-koi.yml"
   - "./rubocop-layout.yml"
   - "./rubocop-lint.yml"
   - "./rubocop-metrics.yml"

data/config/rubocop-koi.yml

@@ -0,0 +1,27 @@
+# Custom cops for projects built on Koi (katalyst-koi).
+Koi:
+  Enabled: true
+
+Koi/DuplicatesAssociation:
+  Description: "Owned detail associations on content items should declare duplicates_association."
+  Enabled: true
+  Safe: true
+  SafeAutoCorrect: false
+  VersionAdded: "3.2"
+  BaseClasses:
+    - Katalyst::Content::Item
+  Include:
+    - "**/app/models/**/*.rb"
+
+# Targets admin views, which are only linted when RuboCop runs through
+# erb_lint, so it takes effect via `rake erb_lint`.
+Koi/TableLinkHeading:
+  Description: "Tables should have a single record link, rendered as the row heading."
+  Enabled: true
+  Safe: true
+  SafeAutoCorrect: false
+  VersionAdded: "3.1"
+  Include:
+    - "**/app/views/admin/**/index.html.erb"
+    - "**/app/views/admin/**/archived.html.erb"
+    - "**/app/views/admin/**/*.html+row.erb"

data/lib/rubocop/cop/katalyst_cops.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "koi/duplicates_association"
+require_relative "koi/table_link_heading"

data/lib/rubocop/cop/koi/duplicates_association.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Koi
+      # Content items are duplicated for copy-on-write editing, and owned
+      # detail records must be duplicated with them. katalyst-content
+      # provides `duplicates_association` for this; without it the duplicate
+      # silently loses the detail record when the item is next edited.
+      #
+      # An association is considered an owned detail when it declares
+      # `dependent: :destroy` and is autosaved, either explicitly with
+      # `autosave: true` or implicitly via `accepts_nested_attributes_for`.
+      #
+      # The cop only applies where `duplicates_association` is available:
+      # classes that extend one of the configured `BaseClasses`
+      # (`Katalyst::Content::Item` by default), include
+      # `Katalyst::Content::DuplicatesAssociations`, or already call
+      # `duplicates_association`.
+      #
+      # @example
+      #   # bad
+      #   class Embed < Katalyst::Content::Item
+      #     has_one :embed_detail, autosave: true, dependent: :destroy
+      #   end
+      #
+      #   # good
+      #   class Embed < Katalyst::Content::Item
+      #     has_one :embed_detail, autosave: true, dependent: :destroy
+      #     duplicates_association :embed_detail
+      #   end
+      class DuplicatesAssociation < Base
+        extend AutoCorrector
+
+        MSG = "Owned associations are duplicated with the item; " \
+              "declare `duplicates_association :%<name>s`."
+
+        RESTRICT_ON_SEND = %i[has_one has_many].freeze
+
+        BASE_CLASSES_DEFAULT = ["Katalyst::Content::Item"].freeze
+
+        # @!method association(node)
+        def_node_matcher :association, <<~PATTERN
+          (send nil? {:has_one :has_many} (sym $_) $(hash ...))
+        PATTERN
+
+        # @!method duplicates_association_names(node)
+        def_node_search :duplicates_association_names, <<~PATTERN
+          (send nil? :duplicates_association (sym $_)+)
+        PATTERN
+
+        # @!method includes_concern?(node)
+        def_node_search :includes_concern?, <<~PATTERN
+          (send nil? :include (const _ :DuplicatesAssociations))
+        PATTERN
+
+        # @!method nested_attributes(node)
+        def_node_search :nested_attributes, <<~PATTERN
+          $(send nil? :accepts_nested_attributes_for (sym $_) ...)
+        PATTERN
+
+        def on_send(node)
+          association(node) do |name, options|
+            klass = node.each_ancestor(:class).first
+            return unless klass
+            return unless owned?(klass, name, options)
+            return unless duplication_available?(klass)
+            return if declared?(klass, name)
+
+            add_offense(node, message: format(MSG, name:)) do |corrector|
+              anchor = nested_attributes_node(klass, name) || node
+              corrector.insert_after(anchor, "\n#{' ' * anchor.loc.column}duplicates_association :#{name}")
+            end
+          end
+        end
+
+        private
+
+        def owned?(klass, name, options)
+          option?(options, :dependent, :destroy) &&
+            (option?(options, :autosave, true) || nested_attributes_node(klass, name))
+        end
+
+        def option?(options, key, value)
+          options.pairs.any? do |pair|
+            pair.key.sym_type? && pair.key.value == key && option_value?(pair.value, value)
+          end
+        end
+
+        def option_value?(node, value)
+          case value
+          when true then node.true_type?
+          when Symbol then node.sym_type? && node.value == value
+          end
+        end
+
+        def duplication_available?(klass)
+          base_classes.include?(klass.parent_class&.source) ||
+            includes_concern?(klass) ||
+            duplicates_association_names(klass).any?
+        end
+
+        def base_classes
+          cop_config.fetch("BaseClasses", BASE_CLASSES_DEFAULT)
+        end
+
+        def declared?(klass, name)
+          duplicates_association_names(klass).any? { |names| names.include?(name) }
+        end
+
+        def nested_attributes_node(klass, name)
+          nested_attributes(klass).find { |_node, sym| sym == name }&.first
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/koi/table_link_heading.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Koi
+      # Koi admin tables should link to each record exactly once, from the
+      # column that identifies the record, and that link should render as a
+      # row heading (`th`) for accessibility.
+      #
+      # When a table renders a single record link, mark it as the row heading
+      # with `heading: true` (autocorrectable). When a table renders more
+      # than one record link, the extra columns should use `text` instead;
+      # `heading: false` documents an intentional exception. Links that
+      # override `url:` are not record links, so they are ignored, as are
+      # links that forward options (`**options`).
+      #
+      # erb_lint feeds RuboCop one ERB tag at a time, so the fragment being
+      # inspected is not enough context to count links. When linting a view,
+      # this cop reads the whole file from disk and counts record links
+      # across all of its ERB tags. Outside a view file it counts links in
+      # the current source. Counting is per file, so a view that renders two
+      # tables is treated as one.
+      #
+      # This cop only takes effect through erb_lint: plain `rubocop` does not
+      # inspect `.erb` files, and the `Include` configuration restricts it to
+      # Koi admin views.
+      #
+      # @example
+      #   # bad
+      #   row.link(:name)
+      #
+      #   # good
+      #   row.link(:name, heading: true)
+      #
+      #   # good - not a record link
+      #   row.link(:name, url: :edit_admin_page_path)
+      #
+      #   # good - intentional extra link
+      #   row.link(:name, heading: true)
+      #   row.link(:homepage, heading: false)
+      class TableLinkHeading < Base
+        extend AutoCorrector
+
+        MSG_HEADING = "The record link should be the row heading; add `heading: true`."
+        MSG_EXTRA   = "Tables should link to the record once, from the column that identifies it. " \
+                      "Use `text` instead, or `heading: false` to keep an intentional extra link."
+
+        RESTRICT_ON_SEND = %i[link].freeze
+
+        # How erb_lint trims trailing block expressions from ERB tags, copied
+        # from Rails: action_view/template/handlers/erb/erubi.rb
+        BLOCK_EXPR = /\s*((\s+|\))do|\{)(\s*\|[^|]*\|)?\s*\Z/
+
+        ERB_TAG = /<%(?:(?!%>).)*%>/m
+
+        # @!method row_link?(node)
+        def_node_matcher :row_link?, <<~PATTERN
+          (send {(send nil? :row) (lvar :row)} :link _ ...)
+        PATTERN
+
+        def on_new_investigation
+          super
+          @record_link_count = nil
+        end
+
+        def on_send(node)
+          return unless row_link?(node)
+
+          options = options(node)
+          return if options && explicit_options?(options)
+
+          anchor = node.arguments.reject(&:block_pass_type?).last
+          return unless anchor
+
+          if record_link_count > 1
+            add_offense(node, message: MSG_EXTRA)
+          else
+            add_offense(node, message: MSG_HEADING) do |corrector|
+              corrector.insert_after(anchor, ", heading: true")
+            end
+          end
+        end
+
+        private
+
+        def options(node)
+          arg = node.arguments.reject(&:block_pass_type?).last
+          arg if arg&.hash_type?
+        end
+
+        # Skip if heading is already set, options are forwarded (splat), or
+        # the link is not a record link (url override).
+        def explicit_options?(options)
+          options.children.any?(&:kwsplat_type?) ||
+            options.pairs.any? { |pair| pair.key.sym_type? && %i[heading url].include?(pair.key.value) }
+        end
+
+        # A `row.link` renders a record link unless it overrides `url:`.
+        # Links that forward options are indeterminate, so they don't count.
+        def record_link?(node)
+          return false unless row_link?(node)
+
+          options = options(node)
+          return true if options.nil?
+
+          options.children.none?(&:kwsplat_type?) &&
+            options.pairs.none? { |pair| pair.key.sym_type? && pair.key.value == :url }
+        end
+
+        def record_link_count
+          @record_link_count ||= if (source = view_source)
+                                   count_record_links_in_erb(source)
+                                 else
+                                   count_record_links(processed_source.ast)
+                                 end
+        end
+
+        def view_source
+          path = processed_source.file_path
+
+          File.read(path) if path&.end_with?(".erb") && File.file?(path)
+        end
+
+        def count_record_links_in_erb(source)
+          source.scan(ERB_TAG).sum do |tag|
+            next 0 if tag.start_with?("<%#")
+
+            code = tag.sub(/\A<%[=-]*/, "").sub(/-?%>\z/, "").sub(BLOCK_EXPR, "")
+            count_record_links(parse_fragment(code))
+          end
+        end
+
+        def count_record_links(ast)
+          return 0 if ast.nil?
+
+          ast.each_node(:send).count { |node| record_link?(node) }
+        end
+
+        def parse_fragment(code)
+          ProcessedSource.new(code, processed_source.ruby_version).ast
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/katalyst.rb

@@ -6,6 +6,8 @@ require "rubocop-rails"
 require "rubocop-rake"
 require "rubocop-rspec"
 
+require_relative "cop/katalyst_cops"
+
 module RuboCop
   module Katalyst
     class Plugin < LintRoller::Plugin

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-katalyst
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.2.0
 platform: ruby
 authors:
 - Katalyst Interactive
@@ -148,6 +148,7 @@ files:
 - config/default.yml
 - config/rubocop-bundler.yml
 - config/rubocop-gemspec.yml
+- config/rubocop-koi.yml
 - config/rubocop-layout.yml
 - config/rubocop-lint.yml
 - config/rubocop-metrics.yml
@@ -158,12 +159,14 @@ files:
 - config/rubocop-rspec.yml
 - config/rubocop-security.yml
 - config/rubocop-style.yml
+- lib/rubocop/cop/katalyst_cops.rb
+- lib/rubocop/cop/koi/duplicates_association.rb
+- lib/rubocop/cop/koi/table_link_heading.rb
 - lib/rubocop/katalyst.rb
 - lib/rubocop/katalyst/erb_lint_task.rb
 - lib/rubocop/katalyst/prettier_task.rb
 - lib/rubocop/katalyst/rake_task.rb
 - lib/tasks/erb_lint.rake
-- package.json
 homepage: https://github.com/katalyst/rubocop-katalyst
 licenses:
 - MIT
@@ -185,7 +188,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Code standards for Katalyst
 test_files: []

data/package.json

@@ -1,10 +0,0 @@
-{
-  "private": true,
-  "scripts": {
-    "lint": "prettier --check *.json app/assets/javascripts app/assets/stylesheets",
-    "autocorrect": "prettier --write *.json app/assets/javascripts app/assets/stylesheets"
-  },
-  "devDependencies": {
-    "prettier": "3.8.3"
-  }
-}