rubocop-nathank 1.0.0

data/lib/rubocop/nathank/support/prism_source.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+# Reads the file under inspection with Prism, which ships with Ruby, instead of through the parser gem syntax tree RuboCop hands a cop.
+#
+# A cop which includes this does not use the `on_<type>` callbacks: those are driven by the parser gem tree, so a cop which reads a different tree walks it itself from `on_new_investigation`. What it gains is one parse of the file by the same Prism which runs the program, and a uniform walk over every node.
+#
+# Offences are still reported against `Parser::Source::Range`, because that is what RuboCop and its correctors take. THE TWO DO NOT MEASURE THE SAME WAY: a Prism location counts BYTES and a `Parser::Source::Range` counts CHARACTERS, so a range built from `start_offset` is correct only until the first multibyte character in the file and silently wrong after it. Prism gives both, and `prism_range` takes the character pair.
+#
+# Prism does not track parentage - a node does not name the node it is written inside - so the walk records the parent of each node as it descends.
+
+require "prism"
+
+module RuboCop
+  module Nathank
+    module PrismSource
+      # @returns [Prism::ParseResult] the file, parsed once however many times this is called.
+      def prism_result
+        self.prism_state.fetch(:result)
+      end
+
+      # Every node in the file, outermost first, in source order.
+      #
+      # @returns [Array(Prism::Node)] the nodes.
+      def prism_nodes
+        self.prism_state.fetch(:nodes)
+      end
+
+      # @parameter classes [Array(Class)] the Prism node classes wanted.
+      # @returns [Array(Prism::Node)] the nodes which are one of them.
+      def prism_each(*classes)
+        if classes.empty?
+          self.prism_nodes
+        else
+          self.prism_nodes.select{|node| classes.any?{|klass| node.is_a?(klass)}}
+        end
+      end
+
+      # @parameter node [Prism::Node] the node whose parent is wanted.
+      # @returns [Prism::Node | nil] the node it is written inside, or nil at the root.
+      def prism_parent(node)
+        self.prism_state.fetch(:parents)[node]
+      end
+
+      # The nodes a node is written inside, innermost first.
+      #
+      # @returns [Array(Prism::Node)] the ancestors.
+      def prism_ancestors(node)
+        [].tap do |found|
+          current = self.prism_parent(node)
+
+          while current
+            found << current
+            current = self.prism_parent(current)
+          end
+        end
+      end
+
+      # @returns [Array(Prism::Node)] the nodes written directly inside the given node.
+      def prism_children(node)
+        node.compact_child_nodes
+      end
+
+      # Everything written inside the given node, at any depth, outermost first.
+      #
+      # @parameter classes [Array(Class)] the Prism node classes wanted, or none for all of them.
+      # @returns [Array(Prism::Node)] the nodes.
+      def prism_descendants(node, *classes)
+        [].tap do |found|
+          pending = node.compact_child_nodes.dup
+
+          until pending.empty?
+            current = pending.shift
+
+            if classes.empty? or classes.any?{|klass| current.is_a?(klass)}
+              found << current
+            end
+
+            pending.concat(current.compact_child_nodes)
+          end
+        end
+      end
+
+      # Whether the given node contains a heredoc, whose content lives below the line it opens on.
+      def prism_heredoc?(node)
+        [node].concat(self.prism_descendants(node)).any? do |current|
+          case current
+          when ::Prism::StringNode, ::Prism::InterpolatedStringNode,
+               ::Prism::XStringNode, ::Prism::InterpolatedXStringNode
+            current.heredoc?
+          else
+            false
+          end
+        end
+      end
+
+      # The statements of a body, whether it holds one or many.
+      #
+      # @parameter body [Prism::StatementsNode | nil] the body of a method, module, or block.
+      # @returns [Array(Prism::Node)] its statements, which is empty when there is no body.
+      def prism_statements(body)
+        if body.nil?
+          []
+        else
+          body.body
+        end
+      end
+
+      # A Prism location as the range RuboCop reports an offence against.
+      #
+      # @parameter location [Prism::Location] where the offence is.
+      # @returns [Parser::Source::Range] the same place, measured for RuboCop.
+      def prism_range(location)
+        # CHARACTER OFFSETS, NOT `start_offset`. A `Parser::Source::Range` indexes the buffer by character and a Prism location counts bytes, so a range built from the byte pair lands further and further past where it should as the multibyte characters above it accumulate. A corrector handed such a range replaces the wrong text and writes a file which no longer parses.
+        ::Parser::Source::Range.new(
+          processed_source.buffer,
+          location.start_character_offset,
+          location.end_character_offset,
+        )
+      end
+
+      # One range reaching from the start of the first location to the end of the last, for an offence over a run of statements rather than a single node.
+      #
+      # @returns [Parser::Source::Range] the span.
+      def prism_span(first, last)
+        ::Parser::Source::Range.new(
+          processed_source.buffer,
+          first.start_character_offset,
+          last.end_character_offset,
+        )
+      end
+
+      # @returns [Parser::Source::Range] the whole of the given node.
+      def prism_node_range(node)
+        self.prism_range(node.location)
+      end
+
+      # The column a node starts at, counted the way a Ruby String is indexed.
+      #
+      # @returns [Integer] the character column.
+      def prism_column(node)
+        # `Prism::Location#start_column` counts bytes, so indexing a line from `processed_source.lines` with it cuts in the wrong place once anything above or before it on that line is multibyte.
+        node.location.start_character_column
+      end
+
+      # @returns [String] the source of the given node.
+      def prism_source(node)
+        node.location.slice
+      end
+
+      # @returns [Array(Prism::InlineComment)] every comment in the file, in source order.
+      def prism_comments
+        self.prism_result.comments
+      end
+
+      # The run of comment lines written directly above a declaration, which is what documents it.
+      #
+      # @returns [Array(Prism::InlineComment)] the comments, in source order.
+      def prism_leading_comments(node)
+        self.prism_state.fetch(:leading)[node] ||= self.contiguous_above(node)
+      end
+
+      # Every comment a declaration owns, which is the same run: a comment belongs to whatever it is written above.
+      #
+      # @returns [Array(Prism::InlineComment)] the comments, in source order.
+      def prism_owned_comments(node)
+        self.prism_leading_comments(node)
+      end
+
+      private
+
+      # Everything read from the file, discarded when RuboCop moves to the next one.
+      def prism_state
+        source = processed_source
+
+        unless @prism_state and @prism_source.equal?(source)
+          @prism_source = source
+          @prism_state = self.read(source)
+        end
+
+        @prism_state
+      end
+
+      def read(source)
+        result = ::Prism.parse(source.buffer.source)
+
+        nodes = []
+        parents = {}.compare_by_identity
+
+        self.descend(result.value, nil, nodes, parents)
+
+        by_line = {}
+
+        result.comments.each do |comment|
+          by_line[comment.location.start_line] = comment
+        end
+
+        {
+          result: result,
+          nodes: nodes,
+          parents: parents,
+          by_line: by_line,
+          leading: {}.compare_by_identity,
+        }
+      end
+
+      # The tree, recorded flat with the parent of each node, since Prism does not say.
+      def descend(node, parent, nodes, parents)
+        nodes << node
+        parents[node] = parent
+
+        node.compact_child_nodes.each do |child|
+          self.descend(child, node, nodes, parents)
+        end
+      end
+
+      # The run of comment lines ending on the line above the node, stopping at the first gap.
+      def contiguous_above(node)
+        by_line = self.prism_state.fetch(:by_line)
+        found = []
+        line = node.location.start_line - 1
+
+        while comment = by_line[line]
+          found.unshift(comment)
+          line -= 1
+        end
+
+        found
+      end
+    end
+  end
+end

data/lib/rubocop/nathank/use_tap.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+# Requires `tap` where a method assigns and returns a local.
+#
+# @example
+#   def require_existing_column!                                    # NO
+#     column = params[:id].to_s
+#     unless connection.columns(@table).any? { |c| c.name == column }
+#       render json: { error: "unknown column" }, status: :not_found
+#     end
+#     column
+#   end
+#
+# @example
+#   def require_existing_column!                                    # YES
+#     params[:id].to_s.tap do |column|
+#       unless connection.columns(@table).any? { |c| c.name == column }
+#         render json: { error: "unknown column" }, status: :not_found
+#       end
+#     end
+#   end
+
+require_relative "support/prism_source"
+
+module RuboCop
+  module Nathank
+    class UseTap < ::RuboCop::Cop::Base
+      include PrismSource
+
+      MSG = "Assigning `%<name>s` and returning it at the end is `tap`; " \
+            "write `<expression>.tap do |%<name>s| ... end`."
+
+      # Every way a local can be written to after the opening assignment.
+      REASSIGNMENTS = [
+        ::Prism::LocalVariableWriteNode,
+        ::Prism::LocalVariableOperatorWriteNode,
+        ::Prism::LocalVariableOrWriteNode,
+        ::Prism::LocalVariableAndWriteNode,
+        ::Prism::MultiWriteNode,
+      ].freeze
+
+      def on_new_investigation
+        self.prism_each(::Prism::DefNode).each do |node|
+          self.check(node.body)
+        end
+      end
+
+      private
+
+      def check(body)
+        if self.tap_shaped?(body)
+          add_offense(self.prism_node_range(body), message: format(MSG, name: self.assigned_name(body)))
+        end
+      end
+
+      # First statement assigns a local; last statement is that same local, read and nothing else.
+      def tap_shaped?(body)
+        body.is_a?(::Prism::StatementsNode) &&
+          body.body.size >= 2 &&
+          body.body.first.is_a?(::Prism::LocalVariableWriteNode) &&
+          self.returns_assigned?(body) &&
+          !self.reassigned?(body)
+      end
+
+      def assigned_name(body)
+        body.body.first.name
+      end
+
+      def returns_assigned?(body)
+        last = body.body.last
+
+        last.is_a?(::Prism::LocalVariableReadNode) && last.name == self.assigned_name(body)
+      end
+
+      # `tap` yields the object the receiver evaluated to, so a body that points the name at something else partway through is a different program and must not be flagged.
+      def reassigned?(body)
+        name = self.assigned_name(body)
+
+        body.body[1..-2].any? do |statement|
+          [statement].concat(self.prism_descendants(statement)).any? do |write|
+            REASSIGNMENTS.any?{|klass| write.is_a?(klass)} && self.writes_name?(write, name)
+          end
+        end
+      end
+
+      def writes_name?(node, name)
+        if node.is_a?(::Prism::MultiWriteNode)
+          node.lefts.concat(node.rights).any? do |target|
+            target.respond_to?(:name) && target.name == name
+          end
+        else
+          node.name == name
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/nathank/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Nathan Kidd.
+
+module RuboCop
+  module Nathank
+    VERSION = "1.0.0"
+  end
+end

data/lib/rubocop/nathank.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Nathan Kidd.
+
+require "rubocop"
+
+require_relative "nathank/version"
+require_relative "nathank/plugin"
+require_relative "nathank/begin_block_assignment"
+require_relative "nathank/comment_structure"
+require_relative "nathank/no_conditional_assignment"
+require_relative "nathank/no_modifier_if"
+require_relative "nathank/no_return"
+require_relative "nathank/single_line_methods_for_events"
+require_relative "nathank/use_tap"
+
+# @namespace
+module RuboCop
+  # @namespace
+  module Nathank
+  end
+end

data/lib/rubocop-nathank.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Nathan Kidd.
+
+require_relative "rubocop/nathank"

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2026, by Nathan Kidd.  
+
+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/readme.md

@@ -0,0 +1,54 @@
+# RuboCop::Nathank
+
+House style, as a RuboCop plugin.
+
+[![Development Status](https://github.com/n-at-han-k/rubocop-nathank/workflows/Test/badge.svg)](https://github.com/n-at-han-k/rubocop-nathank/actions?workflow=Test)
+
+## Installation
+
+    bundle add rubocop-nathank
+
+## Usage
+
+``` yaml
+# .rubocop.yml
+plugins:
+  - rubocop-nathank
+```
+
+## Available Cops
+
+* `Nathank/BeginBlockAssignment` - no assigning a `begin...end`; the assignment goes inside.
+* `Nathank/NoConditionalAssignment` - no assigning an `if` / `case`; assign inside each branch.
+* `Nathank/NoModifierIf` - no modifier `if` / `unless`, so a guard cannot hide off the right edge.
+* `Nathank/NoReturn` - no `return`; the last expression is the return value.
+* `Nathank/UseTap` - `tap` where a method assigns a local and returns it.
+* `Nathank/SingleLineMethodsForEvents` - a one-expression body uses the endless form.
+* `Nathank/CommentStructure` - how a comment is built: unwrapped paragraphs, a summary no longer
+  than the code earns, and annotations on a documented interface.
+
+Each one reads the file under inspection with Prism rather than the parser gem tree RuboCop hands a
+cop, so it walks the same tree which runs the program. The defaults, and what `CommentStructure`
+takes, are in [lib/rubocop/nathank/config.yaml](lib/rubocop/nathank/config.yaml).
+
+## Releases
+
+Please see [releases.md](releases.md) for all releases.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,6 @@
+# Releases
+
+## v0.1.0
+
+  - Initial release: the house-style cops, moved out of the `cops/` directories which shared them
+    by copy. The department is now `Nathank` rather than `Local`.

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: rubocop-nathank
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Nathan Kidd
+bindir: bin
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: decode
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: lint_roller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+email:
+- nathankidd@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- lib/rubocop-nathank.rb
+- lib/rubocop/nathank.rb
+- lib/rubocop/nathank/begin_block_assignment.rb
+- lib/rubocop/nathank/comment_structure.rb
+- lib/rubocop/nathank/config.yaml
+- lib/rubocop/nathank/no_conditional_assignment.rb
+- lib/rubocop/nathank/no_modifier_if.rb
+- lib/rubocop/nathank/no_return.rb
+- lib/rubocop/nathank/plugin.rb
+- lib/rubocop/nathank/single_line_methods_for_events.rb
+- lib/rubocop/nathank/support/prism_source.rb
+- lib/rubocop/nathank/use_tap.rb
+- lib/rubocop/nathank/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/n-at-han-k/rubocop-nathank
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/n-at-han-k/rubocop-nathank
+  default_lint_roller_plugin: RuboCop::Nathank::Plugin
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: House style, as a RuboCop plugin.
+test_files: []