rubocop-bottrall 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e0a08ed9eac30511ec7903e3d93b3cab636a0eff14f68382bc25803f6f915949
+  data.tar.gz: 947e300fe8c054f27a9ff33cd04a2ee08e5c97440f9a6ad3e877cd7f57d04e3c
+SHA512:
+  metadata.gz: c2a290b46ed43cb27c02fe83abf86cd2ccfa53c5d3b1c7074084f6f0acfce31a9857c298633662f0f71ec34fe77bebc47bce860d77287c26ecb05f3cc4c62876
+  data.tar.gz: cc0549fd0868c0ba96fe076d95a78a2c82e97b4409b41f780aa6d93d6a259288bfa491b75be309c2ce01c217d691850ca78ab1cefe3a754542acc18945b17b56

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2026-11-14)
+
+
+### Features
+
+* add rubocop-bottrall with the shared Ruby style and cops ([#1](https://github.com/bottrall/blueprint/issues/1)) ([b693705](https://github.com/bottrall/blueprint/commit/b6937056c768e6d69e55e0ac60ca846f7ce3dcf1))

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jake Bottrall
+
+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,78 @@
+# rubocop-bottrall
+
+The shared Ruby style for bottrall projects, as a [RuboCop](https://rubocop.org) plugin. One gem brings:
+
+- `config/base.yml`: the shared style (new cops enabled, one-argument-per-line layout, `Metrics` off except `Metrics/BlockNesting`, compact class nesting, `extend_self` modules, one assertion per Minitest test), with [rubocop-minitest](https://github.com/rubocop/rubocop-minitest), [rubocop-performance](https://github.com/rubocop/rubocop-performance) and [rubocop-rake](https://github.com/rubocop/rubocop-rake) as dependencies and plugins.
+- `config/rbs-inline.yml`: lets `Layout/LeadingCommentSpace` and `Layout/LineLength` accept [rbs-inline](https://github.com/soutaro/rbs-inline) annotations.
+- Three cops in the `Bottrall/` department:
+  - `Bottrall/NoInheritance`: compose instead of inheriting. A superclass is allowed only when it's listed in `AllowedParents`, its name ends in `Error`, or it's a core class that is `Exception` or a `StandardError` descendant.
+  - `Bottrall/NoMocking`: no `stub`, no `Minitest::Mock`, and (for code under `OwnedNamespaces`) no methods patched in with `define_singleton_method` / `define_method`. Inject a real lightweight fake instead. Only checks test files (`**/test/**/*`, `**/*_test.rb`).
+  - `Bottrall/RequireDisableReason`: every `rubocop:disable` / `rubocop:todo` ends with `-- <reason>`.
+
+Requires RuboCop 1.72 or later (the plugin system) and Ruby 3.3 or later.
+
+## Usage
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem 'rubocop-bottrall', require: false
+```
+
+Then point `.rubocop.yml` at it:
+
+```yaml
+plugins:
+  - rubocop-bottrall
+
+inherit_gem:
+  rubocop-bottrall:
+    - config/base.yml
+    - config/rbs-inline.yml # only if the project writes rbs-inline annotations
+
+inherit_mode:
+  merge:
+    - Exclude
+```
+
+`inherit_mode: merge: [Exclude]` adds your own `AllCops: Exclude` entries to the shared ones (`bin/`, `vendor/`, `sig/`, `pkg/`, `tmp/`, `.claude/`, `node_modules/`) instead of replacing them.
+
+### Configuring the cops
+
+`Bottrall/NoInheritance` allows no parents beyond errors until you list your framework-mandated ones, by fully qualified constant name:
+
+```yaml
+Bottrall/NoInheritance:
+  AllowedParents:
+    - ApplicationRecord
+    - ApplicationController
+```
+
+For a one-off parent, use a scoped disable with a reason instead: `# rubocop:disable Bottrall/NoInheritance -- <reason>`.
+
+`Bottrall/NoMocking` flags `stub` and `Minitest::Mock` everywhere. To also flag methods patched onto your own code (`MyGem::Client.define_singleton_method(...)`, `MyGem::Client.singleton_class.define_method(...)`, or `define_singleton_method` on a local built from `MyGem::...` in the same test), list the namespaces you own:
+
+```yaml
+Bottrall/NoMocking:
+  OwnedNamespaces:
+    - MyGem
+```
+
+## Development
+
+| Command | What it does |
+|---|---|
+| `bin/setup` | Install dependencies |
+| `bin/test [paths] [minitest flags]` | Run the tests |
+| `bin/lint [--fix] [paths]` | Lint the gem with its own plugin and `config/base.yml` |
+| `bin/build` | Build the gem into `pkg/`, install it into an empty `GEM_HOME`, and check it loads |
+| `bin/check` | `bin/lint --fix`, then `bin/test` |
+| `bin/ci` | Exactly what CI runs: tests, lint, build |
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/bottrall/blueprint.
+
+## License
+
+Released under the [MIT License](LICENSE).

data/config/base.yml

@@ -0,0 +1,60 @@
+# The shared Ruby style. A project inherits it with
+#
+#   plugins:
+#     - rubocop-bottrall
+#   inherit_gem:
+#     rubocop-bottrall:
+#       - config/base.yml
+#   inherit_mode:
+#     merge:
+#       - Exclude
+
+plugins:
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+
+AllCops:
+  NewCops: enable
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
+    - '**/sig/**/*'
+    - 'pkg/**/*'
+    - 'tmp/**/*'
+    - '.claude/**/*'
+    - 'node_modules/**/*'
+
+Layout/FirstMethodArgumentLineBreak:
+  Enabled: true
+
+Layout/FirstMethodParameterLineBreak:
+  Enabled: true
+
+Layout/MultilineMethodArgumentLineBreaks:
+  Enabled: true
+
+Layout/MultilineMethodParameterLineBreaks:
+  Enabled: true
+
+Layout/RedundantLineBreak:
+  Enabled: true
+  InspectBlocks: false
+
+Metrics:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: true
+
+Minitest/MultipleAssertions:
+  Max: 1
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact
+
+Style/Documentation:
+  Enabled: false
+
+Style/ModuleFunction:
+  EnforcedStyle: extend_self

data/config/default.yml

@@ -0,0 +1,32 @@
+# Defaults for the Bottrall/ cops, loaded by RuboCop::Bottrall::Plugin.
+
+Bottrall/NoInheritance:
+  Description: >-
+    Compose instead of inheriting: a superclass is allowed only when it's an
+    error class or a framework-mandated parent listed in AllowedParents.
+  Enabled: true
+  VersionAdded: '0.1'
+  # Framework-mandated parents, as fully qualified constant names
+  # (e.g. `ApplicationRecord`, `RuboCop::Cop::Base`).
+  AllowedParents: []
+
+Bottrall/NoMocking:
+  Description: >-
+    Don't stub, use Minitest::Mock, or patch methods onto code you own:
+    inject a real lightweight fake instead.
+  Enabled: true
+  VersionAdded: '0.1'
+  Include:
+    - '**/test/**/*'
+    - '**/*_test.rb'
+  # Namespaces whose constants (and locals built from them) may not have
+  # methods patched in with define_singleton_method / define_method. With
+  # none listed, only `stub` and `Minitest::Mock` are flagged.
+  OwnedNamespaces: []
+
+Bottrall/RequireDisableReason:
+  Description: >-
+    Every `rubocop:disable` / `rubocop:todo` directive carries a reason
+    after ` -- `.
+  Enabled: true
+  VersionAdded: '0.1'

data/config/rbs-inline.yml

@@ -0,0 +1,7 @@
+# For projects that write rbs-inline annotations (`#: Type`, `# @rbs ...`).
+
+Layout/LeadingCommentSpace:
+  AllowRBSInlineAnnotation: true
+
+Layout/LineLength:
+  AllowRBSInlineAnnotation: true

data/lib/rubocop/bottrall/plugin.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'lint_roller'
+
+# Registers the cops' defaults (config/default.yml) with RuboCop's plugin
+# system, so `plugins: [rubocop-bottrall]` is all a project needs to load them.
+class RuboCop::Bottrall::Plugin < LintRoller::Plugin
+  def about
+    LintRoller::About.new(
+      name: 'rubocop-bottrall',
+      version: RuboCop::Bottrall::VERSION,
+      homepage: 'https://github.com/bottrall/blueprint/tree/main/ruby',
+      description: 'The shared Ruby style and custom cops for bottrall projects.'
+    )
+  end
+
+  def supported?(context)
+    context.engine == :rubocop
+  end
+
+  def rules(_context)
+    LintRoller::Rules.new(
+      type: :path,
+      config_format: :rubocop,
+      value: Pathname.new(__dir__).join('../../../config/default.yml')
+    )
+  end
+end

data/lib/rubocop/bottrall/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Bottrall
+    VERSION = '0.1.0'
+  end
+end

data/lib/rubocop/bottrall.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The plugin's namespace; its cops live under RuboCop::Cop::Bottrall.
+module RuboCop::Bottrall
+end

data/lib/rubocop/cop/bottrall/no_inheritance.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Flags a class with a superclass, unless the superclass is
+#
+# - listed in `AllowedParents` (framework-mandated parents),
+# - named `...Error`, or
+# - a core class that is `Exception` or descends from `StandardError`.
+class RuboCop::Cop::Bottrall::NoInheritance < RuboCop::Cop::Base
+  MSG = "Compose, don't inherit: pass collaborators in, share code through a mixin, and describe " \
+        'contracts as RBS interfaces. Only errors and the framework parents in AllowedParents may be ' \
+        'superclasses; for a one-off framework parent, add a scoped disable with a reason.'
+
+  def on_class(node)
+    parent = node.parent_class
+    return unless parent
+    return if parent.const_type? && allowed?(parent.const_name.delete_prefix('::'))
+
+    add_offense(parent)
+  end
+
+  private
+
+  def allowed?(name)
+    allowed_parents.include?(name) || name.end_with?('Error') || core_error?(name)
+  end
+
+  def allowed_parents
+    Array(cop_config['AllowedParents']).map { |parent| parent.delete_prefix('::') }
+  end
+
+  # Only core classes, defined in C, resolve the same in every process: a
+  # gem's or the project's own error classes aren't loaded when the cop runs.
+  def core_error?(name)
+    return false unless Object.const_defined?(name) && Object.const_source_location(name) == []
+
+    parent = Object.const_get(name)
+    parent.is_a?(Class) && (parent.equal?(Exception) || parent <= StandardError)
+  end
+end

data/lib/rubocop/cop/bottrall/no_mocking.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Flags `stub`, `Minitest::Mock`, and, for code under one of the
+# `OwnedNamespaces`, methods patched in with `define_singleton_method` or
+# `define_method` (directly, through `singleton_class`, or via `send`).
+class RuboCop::Cop::Bottrall::NoMocking < RuboCop::Cop::Base
+  MSG = "Don't mock code you own: inject a real lightweight fake instead. " \
+        'Mock a genuine third party only at its API boundary.'
+
+  def_node_matcher :singleton_patch, <<~PATTERN
+    {
+      (send $_ :define_singleton_method ...)
+      (send (send $_ :singleton_class) :define_method ...)
+      (send (send $_ :singleton_class) {:send :__send__} (sym :define_method) ...)
+    }
+  PATTERN
+
+  def_node_matcher :class_patch, <<~PATTERN
+    {
+      (send $const :define_method ...)
+      (send $const {:send :__send__} (sym :define_method) ...)
+    }
+  PATTERN
+
+  def on_const(node)
+    add_offense(node) if node.const_name.delete_prefix('::') == 'Minitest::Mock'
+  end
+
+  def on_send(node)
+    add_offense(node) if node.method?(:stub) || patches_owned_code?(node)
+  end
+
+  private
+
+  def owned_namespaces
+    @owned_namespaces ||= Array(cop_config['OwnedNamespaces']).map { |namespace| namespace.delete_prefix('::') }
+  end
+
+  def patches_owned_code?(node)
+    return false if owned_namespaces.empty?
+
+    receiver = singleton_patch(node) || class_patch(node)
+    receiver ? owned?(receiver, node) : false
+  end
+
+  def owned?(receiver, node)
+    case receiver.type
+    when :const then owned_constant?(receiver)
+    when :lvar then built_from_owned_constant?(receiver, node)
+    else false
+    end
+  end
+
+  def owned_constant?(node)
+    name = node.const_name.delete_prefix('::')
+    owned_namespaces.any? { |namespace| name == namespace || name.start_with?("#{namespace}::") }
+  end
+
+  # Only a local built in the patch's own scope has a type the cop can see:
+  # a block parameter or a helper's return value could be anything.
+  def built_from_owned_constant?(receiver, node)
+    patch = node.parent&.any_block_type? && node.parent.send_node.equal?(node) ? node.parent : node
+    scope = patch.each_ancestor(:any_block, :any_def).first || processed_source.ast
+    scope.each_descendant(:lvasgn).any? do |assignment|
+      value = assignment.expression
+      assignment.name == receiver.children.first &&
+        value&.send_type? && value.receiver&.const_type? && owned_constant?(value.receiver)
+    end
+  end
+end

data/lib/rubocop/cop/bottrall/require_disable_reason.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Every `rubocop:disable` / `rubocop:todo` has to say why: end it with `-- <reason>`.
+class RuboCop::Cop::Bottrall::RequireDisableReason < RuboCop::Cop::Base
+  MSG = 'Add a reason to the disable directive: end it with `-- <reason>`.'
+
+  DISABLE_DIRECTIVE = /\A#\s*rubocop\s*:\s*(?:disable|todo)\b/
+  REASON = /\s--\s*\S/
+
+  def on_new_investigation
+    processed_source.comments
+                    .select { |comment| DISABLE_DIRECTIVE.match?(comment.text) && !REASON.match?(comment.text) }
+                    .each { |comment| add_offense(comment) }
+  end
+end

data/lib/rubocop/cop/bottrall.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The `Bottrall/` cop department.
+module RuboCop::Cop::Bottrall
+end
+
+require_relative 'bottrall/no_inheritance'
+require_relative 'bottrall/no_mocking'
+require_relative 'bottrall/require_disable_reason'

data/lib/rubocop-bottrall.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'rubocop'
+
+require_relative 'rubocop/bottrall'
+require_relative 'rubocop/bottrall/version'
+require_relative 'rubocop/bottrall/plugin'
+require_relative 'rubocop/cop/bottrall'

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: rubocop-bottrall
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jake Bottrall
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lint_roller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.37'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.37'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.24'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description: A RuboCop plugin bundling a shared style (config/base.yml), an rbs-inline
+  layer (config/rbs-inline.yml), and the Bottrall/NoInheritance, Bottrall/NoMocking
+  and Bottrall/RequireDisableReason cops.
+email:
+- jakebottrall@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- config/base.yml
+- config/default.yml
+- config/rbs-inline.yml
+- lib/rubocop-bottrall.rb
+- lib/rubocop/bottrall.rb
+- lib/rubocop/bottrall/plugin.rb
+- lib/rubocop/bottrall/version.rb
+- lib/rubocop/cop/bottrall.rb
+- lib/rubocop/cop/bottrall/no_inheritance.rb
+- lib/rubocop/cop/bottrall/no_mocking.rb
+- lib/rubocop/cop/bottrall/require_disable_reason.rb
+homepage: https://github.com/bottrall/blueprint/tree/main/ruby#readme
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bottrall/blueprint/tree/main/ruby#readme
+  source_code_uri: https://github.com/bottrall/blueprint/tree/main/ruby
+  changelog_uri: https://github.com/bottrall/blueprint/blob/main/ruby/CHANGELOG.md
+  bug_tracker_uri: https://github.com/bottrall/blueprint/issues
+  rubygems_mfa_required: 'true'
+  default_lint_roller_plugin: RuboCop::Bottrall::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: 4.0.20
+specification_version: 4
+summary: The shared RuboCop style and custom cops for bottrall projects.
+test_files: []