rubocop-legion 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 95a23a8136fd63ac2b841d9a8812c04f261854fac9e752f40e9817f3e8288fc0
+  data.tar.gz: 4512d622e170d83a4fb5d1911d6f91d12130157bdd4adbbd422d8aca5e401649
+SHA512:
+  metadata.gz: febd09cfcb352235365fead149fc2679fec7a4f7c2836ca9f85c06a9e2fc25a3bdb4a6e3914ef79cfc3f636acba681c9d84cdf3b22945be6e43bd8b276a01bd7
+  data.tar.gz: efe2d65b67d0bfa191d0db52d894e87f1cec09c14f0a1bab8a286bc496ad67d1bac8ea98e856dff89c16fe61c0793c766e2ef0711867eae5d746d8b5953c3841

data/.gitignore

@@ -0,0 +1,6 @@
+/.bundle/
+/Gemfile.lock
+/pkg/
+/tmp/
+*.gem
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,22 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+  SuggestExtensions: false
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20
+
+Naming/FileName:
+  Exclude:
+    - 'lib/rubocop-legion.rb'
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2026-03-29
+
+### Added
+- Initial release with 31 cops across 6 departments
+- New RuboCop Plugin API (1.72+, lint_roller based)
+- **Legion/HelperMigration** (6 cops): enforce `log.method`, `json_load`/`json_dump`, `cache_get`/`cache_set`, `vault_get`/`vault_exist?` helpers over direct singleton calls. All auto-correctable.
+- **Legion/ConstantSafety** (4 cops): prevent `Data.define`, `Process`, `JSON` namespace resolution bugs inside `module Legion`; enforce `const_defined?(name, false)`. All auto-correctable.
+- **Legion/Singleton** (1 cop): enforce `.instance` over `.new` for configurable list of singleton classes. Auto-correctable.
+- **Legion/RescueLogging** (3 cops): require rescue blocks to capture exceptions and log or re-raise them. Partial auto-correct (adds `=> e` capture).
+- **Legion/Framework** (7 cops): catch Sequel eager model loading, Sinatra 4.0 host auth, Thor reserved `run`, Faraday XML middleware removal, `module_function`+`private` conflict, cache time coercion, API string keys. `ApiStringKeys` auto-correctable.
+- **Legion/Extension** (10 cops): enforce LEX structural conventions — `module Actor` singular, `extend Core` guard, runner module structure, self-contained actor `runner_class`, `Settings` API correctness, `LLM.ask` signature, `data_required?` migration check. 4 auto-correctable.

data/Gemfile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LegionIO
+
+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,37 @@
+# rubocop-legion
+
+LegionIO code quality cops for [RuboCop](https://rubocop.org/).
+
+Custom cops for the LegionIO async job engine ecosystem. Enforces helper usage, constant safety, rescue logging, framework conventions, and LEX extension structure.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'rubocop-legion', require: false, group: :development
+```
+
+## Usage
+
+Add to your `.rubocop.yml`:
+
+```yaml
+plugins:
+  - rubocop-legion
+```
+
+## Departments
+
+| Department | Cops | Description |
+|---|---|---|
+| `Legion/HelperMigration` | 6 | Use per-extension helpers, not global singletons |
+| `Legion/ConstantSafety` | 4 | Prevent namespace resolution bugs inside `module Legion` |
+| `Legion/Singleton` | 1 | Enforce `.instance` on singleton classes |
+| `Legion/RescueLogging` | 3 | Every rescue must log or re-raise |
+| `Legion/Framework` | 7 | Sequel, Sinatra, Thor, Faraday, and API gotchas |
+| `Legion/Extension` | 10 | LEX structural convention enforcement |
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/config/default.yml

@@ -0,0 +1,233 @@
+# Legion/HelperMigration — use per-extension helpers, not global singletons
+
+Legion/HelperMigration:
+  Enabled: true
+  Include:
+    - 'lib/**/*.rb'
+  Exclude:
+    - 'spec/**/*'
+
+Legion/HelperMigration/DirectLogging:
+  Description: 'Use `log.method` helper instead of `Legion::Logging.method`.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+
+Legion/HelperMigration/OldLoggingMethods:
+  Description: 'Use `log.method` instead of deprecated `log_method` helpers.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+
+Legion/HelperMigration/DirectJson:
+  Description: 'Use `json_load`/`json_dump` helpers instead of `Legion::JSON.load`/`.dump`.'
+  Enabled: true
+  Severity: convention
+  VersionAdded: '0.1'
+
+Legion/HelperMigration/DirectCache:
+  Description: 'Use `cache_get`/`cache_set`/`cache_delete` helpers instead of `Legion::Cache` methods.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+
+Legion/HelperMigration/DirectLocalCache:
+  Description: 'Use `local_cache_get`/`local_cache_set` helpers instead of `Legion::Cache::Local` methods.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+
+Legion/HelperMigration/DirectCrypt:
+  Description: 'Use `vault_get`/`vault_exist?` helpers instead of `Legion::Crypt` methods.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+
+# Legion/ConstantSafety — prevent namespace resolution bugs inside module Legion
+
+Legion/ConstantSafety:
+  Enabled: true
+
+Legion/ConstantSafety/BareDataDefine:
+  Description: 'Use `::Data.define` inside `module Legion` to avoid resolving to `Legion::Data`.'
+  Enabled: true
+  Severity: error
+  VersionAdded: '0.1'
+
+Legion/ConstantSafety/BareProcess:
+  Description: 'Use `::Process` inside `module Legion` to avoid resolving to `Legion::Process`.'
+  Enabled: true
+  Severity: error
+  VersionAdded: '0.1'
+
+Legion/ConstantSafety/BareJson:
+  Description: 'Use `::JSON` inside `module Legion` to avoid resolving to `Legion::JSON`.'
+  Enabled: true
+  Severity: error
+  VersionAdded: '0.1'
+
+Legion/ConstantSafety/InheritParam:
+  Description: 'Pass `false` as inherit param to `const_defined?`/`const_get` on dynamic modules.'
+  Enabled: true
+  Severity: convention
+  VersionAdded: '0.1'
+
+# Legion/Singleton — enforce .instance on singleton classes
+
+Legion/Singleton:
+  Enabled: true
+
+Legion/Singleton/UseInstance:
+  Description: 'Use `.instance` instead of `.new` for singleton classes.'
+  Enabled: true
+  Severity: error
+  VersionAdded: '0.1'
+  SingletonClasses:
+    - TokenCache
+    - Registry
+    - Catalog
+
+# Legion/RescueLogging — every rescue must log or re-raise
+
+Legion/RescueLogging:
+  Enabled: true
+  Include:
+    - 'lib/**/*.rb'
+  Exclude:
+    - 'spec/**/*'
+
+Legion/RescueLogging/BareRescue:
+  Description: 'Bare `rescue` swallows exceptions silently. Capture with `rescue => e`.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+
+Legion/RescueLogging/NoCapture:
+  Description: 'Exception class specified but not captured. Use `rescue Error => e`.'
+  Enabled: true
+  Severity: convention
+  VersionAdded: '0.1'
+
+Legion/RescueLogging/SilentCapture:
+  Description: 'Captured exception variable is never logged or re-raised.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+
+# Legion/Framework — Sequel, Sinatra, Thor, Faraday, concurrency, cache, API gotchas
+
+Legion/Framework:
+  Enabled: true
+
+Legion/Framework/EagerSequelModel:
+  Description: '`Sequel::Model(:table)` introspects schema at require time. Use lazy define pattern.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+
+Legion/Framework/SinatraHostAuth:
+  Description: 'Sinatra 4.0+ requires `set :host_authorization` or all requests get 403.'
+  Enabled: true
+  Severity: convention
+  VersionAdded: '0.1'
+
+Legion/Framework/ThorReservedRun:
+  Description: 'Thor 1.5+ reserves `run`. Rename the method or use `map`.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+  Include:
+    - 'lib/**/cli/**/*.rb'
+
+Legion/Framework/FaradayXmlMiddleware:
+  Description: 'Faraday >= 2.0 removed built-in `:xml` middleware.'
+  Enabled: true
+  Severity: error
+  VersionAdded: '0.1'
+
+Legion/Framework/ModuleFunctionPrivate:
+  Description: '`private` after `module_function` resets visibility. Do not use both together.'
+  Enabled: true
+  Severity: convention
+  VersionAdded: '0.1'
+
+Legion/Framework/CacheTimeCoercion:
+  Description: 'Time objects become Strings after cache round-trip. Coerce at read boundaries.'
+  Enabled: true
+  Severity: convention
+  VersionAdded: '0.1'
+
+Legion/Framework/ApiStringKeys:
+  Description: '`Legion::JSON.load` returns symbol keys. Use `body[:key]` not `body["key"]`.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+  Include:
+    - 'lib/**/*.rb'
+  Exclude:
+    - 'spec/**/*'
+
+# Legion/Extension — LEX structural convention enforcement
+
+Legion/Extension:
+  Enabled: true
+
+Legion/Extension/ActorSingularModule:
+  Description: 'Use `module Actor` (singular). Framework discovers actors in `Actor`, not `Actors`.'
+  Enabled: true
+  Severity: error
+  VersionAdded: '0.1'
+
+Legion/Extension/CoreExtendGuard:
+  Description: 'Guard `extend Core` with `const_defined?` for standalone test compatibility.'
+  Enabled: true
+  Severity: error
+  VersionAdded: '0.1'
+
+Legion/Extension/RunnerMustBeModule:
+  Description: 'Runners must be modules, not classes.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+
+Legion/Extension/RunnerIncludeHelpers:
+  Description: 'Runner modules need `include Helpers::Lex` or `extend self`.'
+  Enabled: true
+  Severity: convention
+  VersionAdded: '0.1'
+
+Legion/Extension/SelfContainedActorRunnerClass:
+  Description: 'Self-contained actors must override `runner_class`.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'
+
+Legion/Extension/RunnerReturnHash:
+  Description: 'Runner methods must return a Hash.'
+  Enabled: true
+  Severity: convention
+  VersionAdded: '0.1'
+
+Legion/Extension/SettingsKeyMethod:
+  Description: '`Legion::Settings` has no `key?` method. Use `!Settings[:key].nil?`.'
+  Enabled: true
+  Severity: error
+  VersionAdded: '0.1'
+
+Legion/Extension/SettingsBracketMultiArg:
+  Description: '`Settings#[]` takes 1 arg. Use `Settings.dig(...)` for nested access.'
+  Enabled: true
+  Severity: error
+  VersionAdded: '0.1'
+
+Legion/Extension/LlmAskKwargs:
+  Description: '`Legion::LLM.ask` only accepts `message:`. No extra kwargs.'
+  Enabled: true
+  Severity: error
+  VersionAdded: '0.1'
+
+Legion/Extension/DataRequiredWithoutMigrations:
+  Description: '`data_required?` returns true but migrations may be missing.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1'

data/lib/rubocop/cop/legion/constant_safety/bare_data_define.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module ConstantSafety
+        # Detects bare `Data.define` inside `module Legion` namespaces where it
+        # resolves to `Legion::Data.define` instead of the stdlib `Data.define`.
+        #
+        # @example
+        #   # bad (inside module Legion)
+        #   module Legion
+        #     Point = Data.define(:x, :y)
+        #   end
+        #
+        #   # good
+        #   module Legion
+        #     Point = ::Data.define(:x, :y)
+        #   end
+        class BareDataDefine < RuboCop::Cop::Base
+          extend AutoCorrector
+
+          MSG = 'Inside `module Legion`, bare `Data.define` resolves to `Legion::Data.define`. ' \
+                'Use `::Data.define`.'
+
+          RESTRICT_ON_SEND = %i[define].freeze
+
+          # @!method bare_data_define?(node)
+          def_node_matcher :bare_data_define?, <<~PATTERN
+            (send (const nil? :Data) :define ...)
+          PATTERN
+
+          def on_send(node)
+            return unless bare_data_define?(node)
+            return unless inside_legion_namespace?(node)
+
+            receiver = node.receiver
+            add_offense(receiver) do |corrector|
+              corrector.replace(receiver.source_range, '::Data')
+            end
+          end
+
+          private
+
+          def inside_legion_namespace?(node)
+            node.each_ancestor(:module, :class).any? do |ancestor|
+              name = ancestor.identifier.source
+              name == 'Legion' || name.start_with?('Legion::')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/constant_safety/bare_json.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module ConstantSafety
+        # Detects bare `JSON` method calls inside `module Legion` namespaces
+        # where `JSON` resolves to `Legion::JSON` instead of the stdlib.
+        #
+        # @example
+        #   # bad (inside module Legion)
+        #   module Legion
+        #     JSON.parse(raw)
+        #   end
+        #
+        #   # good
+        #   module Legion
+        #     ::JSON.parse(raw)
+        #   end
+        class BareJson < RuboCop::Cop::Base
+          extend AutoCorrector
+
+          MSG = 'Inside `module Legion`, bare `JSON` resolves to `Legion::JSON`. ' \
+                'Use `::JSON` for stdlib.'
+
+          RESTRICT_ON_SEND = %i[parse generate pretty_generate dump load fast_generate].freeze
+
+          # @!method bare_json_send?(node)
+          def_node_matcher :bare_json_send?, <<~PATTERN
+            (send (const nil? :JSON) _ ...)
+          PATTERN
+
+          def on_send(node)
+            return unless bare_json_send?(node)
+            return unless inside_legion_namespace?(node)
+
+            receiver = node.receiver
+            add_offense(receiver) do |corrector|
+              corrector.replace(receiver.source_range, '::JSON')
+            end
+          end
+
+          private
+
+          def inside_legion_namespace?(node)
+            node.each_ancestor(:module, :class).any? do |ancestor|
+              name = ancestor.identifier.source
+              name == 'Legion' || name.start_with?('Legion::')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/constant_safety/bare_process.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module ConstantSafety
+        # Detects bare `Process` method calls inside `module Legion` namespaces
+        # where `Process` resolves to `Legion::Process` instead of the stdlib.
+        #
+        # @example
+        #   # bad (inside module Legion)
+        #   module Legion
+        #     Process.pid
+        #   end
+        #
+        #   # good
+        #   module Legion
+        #     ::Process.pid
+        #   end
+        class BareProcess < RuboCop::Cop::Base
+          extend AutoCorrector
+
+          MSG = 'Inside `module Legion`, bare `Process` resolves to `Legion::Process`. ' \
+                'Use `::Process`.'
+
+          RESTRICT_ON_SEND = %i[
+            pid ppid kill detach fork wait wait2 waitpid waitpid2
+            getpgid setpgid daemon exit spawn times groups
+            uid gid euid egid
+          ].freeze
+
+          # @!method bare_process_send?(node)
+          def_node_matcher :bare_process_send?, <<~PATTERN
+            (send (const nil? :Process) _ ...)
+          PATTERN
+
+          def on_send(node)
+            return unless bare_process_send?(node)
+            return unless inside_legion_namespace?(node)
+
+            receiver = node.receiver
+            add_offense(receiver) do |corrector|
+              corrector.replace(receiver.source_range, '::Process')
+            end
+          end
+
+          private
+
+          def inside_legion_namespace?(node)
+            node.each_ancestor(:module, :class).any? do |ancestor|
+              name = ancestor.identifier.source
+              name == 'Legion' || name.start_with?('Legion::')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/constant_safety/inherit_param.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module ConstantSafety
+        # Detects `const_defined?` or `const_get` called with only one argument.
+        # Without `false` as the second argument, Ruby searches the entire inheritance
+        # chain including `Object`, which can cause false positives and namespace leaks.
+        #
+        # @example
+        #   # bad
+        #   mod.const_defined?('Foo')
+        #   mod.const_get('Bar')
+        #
+        #   # good
+        #   mod.const_defined?('Foo', false)
+        #   mod.const_get('Bar', false)
+        class InheritParam < RuboCop::Cop::Base
+          extend AutoCorrector
+
+          MSG = 'Pass `false` as inherit parameter: `%<method>s(%<arg>s, false)`. ' \
+                'Default `true` leaks through `Object`.'
+
+          RESTRICT_ON_SEND = %i[const_defined? const_get].freeze
+
+          def on_send(node)
+            return unless node.arguments.size == 1
+
+            arg = node.first_argument
+            message = format(MSG, method: node.method_name, arg: arg.source)
+
+            add_offense(node, message: message) do |corrector|
+              corrector.insert_after(arg.source_range, ', false')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/extension/actor_singular_module.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Extension
+        # Detects `module Actors` (plural) inside `Legion::Extensions::*` namespaces
+        # and auto-corrects it to `module Actor` (singular), which is what the LEX
+        # framework uses when discovering actor classes.
+        #
+        # @example
+        #   # bad
+        #   module Legion::Extensions::Foo
+        #     module Actors
+        #     end
+        #   end
+        #
+        #   # good
+        #   module Legion::Extensions::Foo
+        #     module Actor
+        #     end
+        #   end
+        class ActorSingularModule < RuboCop::Cop::Base
+          extend AutoCorrector
+
+          MSG = 'Use `module Actor` (singular), not `module Actors`. ' \
+                'The framework discovers actors inside `Actor`.'
+
+          def on_module(node)
+            name_node = node.identifier
+            return unless name_node.short_name == :Actors
+
+            return unless inside_legion_extensions_namespace?(node)
+
+            add_offense(name_node) do |corrector|
+              corrector.replace(name_node.loc.name, 'Actor')
+            end
+          end
+
+          private
+
+          def inside_legion_extensions_namespace?(node)
+            # Build the full namespace path from all ancestor module/class nodes.
+            # This handles both compact (`module Legion::Extensions::Foo`) and
+            # nested (`module Legion; module Extensions; module Foo`) forms.
+            full_path = ancestor_namespace_parts(node).join('::')
+            full_path.include?('Legion') && full_path.include?('Extensions')
+          end
+
+          def ancestor_namespace_parts(node)
+            parts = []
+            current = node.parent
+            while current
+              parts.unshift(*resolve_const_parts(current.identifier)) if current.module_type? || current.class_type?
+              current = current.parent
+            end
+            parts
+          end
+
+          def resolve_const_parts(const_node)
+            parts = []
+            node = const_node
+            while node&.const_type?
+              parts.unshift(node.short_name.to_s)
+              node = node.namespace
+            end
+            parts
+          end
+        end
+      end
+    end
+  end
+end