rubocop-legion 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0668cc51aab49685f7ecb368113a7103253ec4d3aca22de2970c88ff4ae351f3'
-  data.tar.gz: abc9644c2e563387778df1459aa7abd81f49e79c14e7cc13e038546ceab40a56
+  metadata.gz: 4d9316d83d8676fe5adb80fd7500f3daece09203ece25f0ce0c81887d19982ca
+  data.tar.gz: 646cab78aebc73b233882dcfc594d6c0efbea0acb3e2881e02a1f888ec5513e4
 SHA512:
-  metadata.gz: 43d9efec4fb9f8fc5af8eced138ed626c29211017382b4c71b84f3191b2b5316624e64821e657cf4e8a61426f51404c147c32522d623c3cce3c50d51f9738afe
-  data.tar.gz: 17807228e3e91cd2e4ac0be778a469256adbe691e7b0f1b6399344cb6d1ecffe6e699a5db7ffcf274a42d1a0df531842b32e218f89230d1ae1ced828ef733fbd
+  metadata.gz: 83f63897f48898014d992e98b11cdfd9f2b830e405b2fd49bff484acffdaaeafd853dea8016baaa280787302a0c15a701e2f1d0c71274d1bf0fa04761574e8bd
+  data.tar.gz: 69aa65b8634cef75041fe37a57b87ca54bdc911a59fc12710193a66550b71c01926831618ef9100b775c5fc498d0705d8eaab50af11c5c1446d36ab801be51ae

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.1.10] - 2026-07-31
+
+### Fixed
+- `Legion/Llm/TaxonomyEnum` no longer over-matches: `:type` is only validated when it appears alongside `:tier` or `:circuit_state` in the same hash (taxonomy context). Previously any `{ type: :string }` or schema hash triggered a false positive.
+- Added `Legion/Llm` department to `config/default.yml` — all four cops (`TaxonomyEnum`, `SettingsAccessPath`, `NoLoopDo`, `RescueLogLevel`) were loaded but never registered in the config, causing consumer repos to report "unrecognized cop" when referencing `Legion/Llm/TaxonomyEnum`.
+- `TaxonomyEnum` is now Include-scoped to `lib/legion/llm/**/*.rb` and `lib/legion/extensions/llm/**/*.rb` so it only runs on LLM routing code.
+
 ## [0.1.8] - 2026-06-16
 
 ### Added

data/config/default.yml

@@ -363,3 +363,38 @@ Legion/Framework/NoShapeDuckTyping:
   Severity: convention
   VersionAdded: '0.1.8'
   Safe: false
+
+# Legion/Llm — cops specific to legion-llm and lex-llm-* provider pipelines
+
+Legion/Llm:
+  Enabled: true
+  Include:
+    - 'lib/legion/llm/**/*.rb'
+    - 'lib/legion/extensions/llm/**/*.rb'
+
+Legion/Llm/TaxonomyEnum:
+  Description: 'Validate :tier, :type, and :circuit_state literals against LegionIO taxonomy enums.'
+  Enabled: true
+  Severity: convention
+  VersionAdded: '0.1.9'
+  Include:
+    - 'lib/legion/llm/**/*.rb'
+    - 'lib/legion/extensions/llm/**/*.rb'
+
+Legion/Llm/SettingsAccessPath:
+  Description: 'Use `Legion::Settings.dig(...)` instead of `Legion::Settings.loader.settings[...][...]`.'
+  Enabled: true
+  Severity: convention
+  VersionAdded: '0.1.9'
+
+Legion/Llm/NoLoopDo:
+  Description: 'Ban `loop do` — use bounded iteration (`N.times`, `each`, or `while` with explicit bound).'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1.9'
+
+Legion/Llm/RescueLogLevel:
+  Description: 'Minimum log level for `handle_exception` in rescue blocks is `:warn`.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1.9'

data/lib/rubocop/cop/legion/llm/no_loop_do.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Llm
+        # Flags `loop do` in legion-llm production code. Unbounded loops have caused
+        # runaway threads and hard-to-debug hangs. Use `N.times`, `each`, or a
+        # `while` with an explicit counter instead.
+        #
+        # No auto-correct is provided — the fix requires choosing the correct bound.
+        #
+        # @example
+        #   # bad
+        #   loop do
+        #     attempt = dispatch_request
+        #     break if attempt.success?
+        #   end
+        #
+        #   # good
+        #   MAX_ATTEMPTS.times do
+        #     attempt = dispatch_request
+        #     break if attempt.success?
+        #   end
+        class NoLoopDo < Base
+          MSG = '`loop do` is prohibited — use bounded iteration (`N.times`, `each`, ' \
+                'or `while` with an explicit decrement) instead.'
+
+          def on_block(node)
+            return unless node.send_node.method_name == :loop
+            return unless node.send_node.receiver.nil?
+
+            add_offense(node.send_node)
+          end
+
+          alias on_numblock on_block
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/llm/rescue_log_level.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Llm
+        # Flags `handle_exception(e, level: :debug)` in rescue blocks. Exception
+        # handlers must use at least `:warn` so that errors are visible in
+        # production logs without enabling debug mode.
+        #
+        # @example
+        #   # bad
+        #   rescue StandardError => e
+        #     handle_exception(e, level: :debug, operation: 'foo')
+        #   end
+        #
+        #   # good
+        #   rescue StandardError => e
+        #     handle_exception(e, level: :warn, operation: 'foo')
+        #   end
+        class RescueLogLevel < Base
+          MSG = '`handle_exception` called with `level: :debug` in a rescue. ' \
+                'Minimum log level for exceptions is `:warn`.'
+
+          DEBUG_LEVELS = %i[debug trace verbose].freeze
+
+          def on_send(node)
+            return unless node.method_name == :handle_exception
+            return unless inside_rescue?(node)
+            return unless debug_level?(node)
+
+            add_offense(node)
+          end
+
+          private
+
+          def debug_level?(node)
+            pairs = node.arguments.flat_map do |arg|
+              if arg.hash_type?
+                arg.children
+              elsif arg.pair_type?
+                [arg]
+              else
+                []
+              end
+            end
+            pairs.any? do |pair|
+              key, val = pair.children
+              key.sym_type? && key.value == :level &&
+                val.sym_type? && DEBUG_LEVELS.include?(val.value)
+            end
+          end
+
+          def inside_rescue?(node)
+            node.each_ancestor(:resbody).any?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/llm/settings_access_path.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Llm
+        # Flags direct write-path access to `Legion::Settings.loader.settings[...][...]`
+        # outside test files. Production code must use `Legion::Settings.dig(...)` so all
+        # reads go through the typed, validated accessor.
+        #
+        # @example
+        #   # bad
+        #   Legion::Settings.loader.settings[:extensions][:llm][:default_model] = 'gemma-12b'
+        #   Legion::Settings.loader.settings[:llm][:timeout]
+        #
+        #   # good
+        #   Legion::Settings.dig(:extensions, :llm, :default_model)
+        class SettingsAccessPath < Base
+          MSG = 'Use `Legion::Settings.dig(...)` instead of ' \
+                '`Legion::Settings.loader.settings[...][...]`.'
+
+          def on_send(node)
+            return unless loader_settings_chain?(node)
+
+            add_offense(node)
+          end
+
+          private
+
+          def loader_settings_chain?(node)
+            return false unless %i[[] []=].include?(node.method_name)
+
+            # For []=, the second index arg and the value are children[1] and [2]
+            # The receiver of the outer []= is the inner [] node
+            receiver = node.receiver
+            return false unless receiver&.send_type? && receiver.method_name == :[]
+
+            # receiver.receiver should be Legion::Settings.loader.settings
+            inner = receiver.receiver
+            return false unless inner&.send_type? && inner.method_name == :settings
+
+            loader_recv = inner.receiver
+            return false unless loader_recv&.send_type? && loader_recv.method_name == :loader
+
+            settings_const?(loader_recv.receiver)
+          end
+
+          def settings_const?(node)
+            return false unless node&.const_type?
+            return false unless node.children.last == :Settings
+
+            parent = node.children.first
+            return true if parent.nil?
+            return false unless parent.const_type? && parent.children.last == :Legion
+
+            parent.children.first.nil?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/llm/taxonomy_enum.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Llm
+        # Validates lane field literals against the LegionIO taxonomy enums.
+        # Flags `:tier`, `:type`, and `:circuit_state` literals that are not in
+        # the known-valid sets, catching typos at lint time.
+        #
+        # `:tier` and `:circuit_state` are domain-specific keys and are always
+        # validated. `:type` is only validated when it appears in a hash that
+        # also contains `:tier` or `:circuit_state`, since `:type` alone is too
+        # common in non-taxonomy contexts.
+        #
+        # Valid values (from Inventory::DEFAULT_PROVIDER_TIERS and the SSOT design):
+        #   tier:          :local, :fleet, :cloud, :frontier, :direct
+        #   type:          :inference, :embedding, :moderation, :rerank, :image
+        #   circuit_state: :closed, :open, :half_open
+        #
+        # @example
+        #   # bad  (typo)
+        #   { tier: :fronteir }
+        #   health[:circuit_state] = :half_opened
+        #   { tier: :cloud, type: :inferencing }
+        #
+        #   # good
+        #   { tier: :frontier }
+        #   health[:circuit_state] = :half_open
+        #   { tier: :cloud, type: :inference }
+        #
+        #   # ignored (`:type` alone, no taxonomy context)
+        #   { type: :string }
+        #   { type: :integer }
+        class TaxonomyEnum < Base
+          VALID_TIERS          = %i[local fleet cloud frontier direct].freeze
+          VALID_TYPES          = %i[inference embedding moderation rerank image].freeze
+          VALID_CIRCUIT_STATES = %i[closed open half_open].freeze
+
+          TAXONOMY_KEYS = %i[tier type circuit_state].freeze
+          CONTEXT_KEYS  = %i[tier circuit_state].freeze
+
+          MSG_TIER    = 'Unknown tier `%<val>s`. Valid: %<valid>s.'
+          MSG_TYPE    = 'Unknown type `%<val>s`. Valid: %<valid>s.'
+          MSG_CIRCUIT = 'Unknown circuit_state `%<val>s`. Valid: %<valid>s.'
+
+          def on_pair(node)
+            key, value = node.children
+            return unless key.sym_type? && value.sym_type?
+
+            check_taxonomy(key.value, value, node)
+          end
+
+          def on_send(node)
+            return unless node.method_name == :[]=
+            return unless node.arguments.size == 2
+
+            key_node, val_node = node.arguments
+            return unless key_node.sym_type? && val_node.sym_type?
+
+            check_taxonomy(key_node.value, val_node, node)
+          end
+
+          private
+
+          def check_taxonomy(key, val_node, parent_node)
+            val = val_node.value
+            case key
+            when :tier
+              return if VALID_TIERS.include?(val)
+
+              add_offense(parent_node,
+                          message: format(MSG_TIER, val: val, valid: VALID_TIERS.join(', ')))
+            when :type
+              return if VALID_TYPES.include?(val)
+              return unless taxonomy_context?(parent_node)
+
+              add_offense(parent_node,
+                          message: format(MSG_TYPE, val: val, valid: VALID_TYPES.join(', ')))
+            when :circuit_state
+              return if VALID_CIRCUIT_STATES.include?(val)
+
+              add_offense(parent_node,
+                          message: format(MSG_CIRCUIT, val: val, valid: VALID_CIRCUIT_STATES.join(', ')))
+            end
+          end
+
+          def taxonomy_context?(pair_node)
+            hash_node = pair_node.parent
+            return false unless hash_node&.hash_type?
+
+            sibling_keys = hash_node.pairs.filter_map do |pair|
+              pair.key.value if pair.key.sym_type?
+            end
+
+            sibling_keys.intersect?(CONTEXT_KEYS)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/legion/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Legion
-    VERSION = '0.1.8'
+    VERSION = '0.1.10'
   end
 end

data/lib/rubocop-legion.rb

@@ -68,3 +68,9 @@ require 'rubocop/cop/legion/extension/absorber_missing_pattern'
 require 'rubocop/cop/legion/extension/absorber_missing_absorb_method'
 require 'rubocop/cop/legion/extension/definition_call_mismatched'
 require 'rubocop/cop/legion/extension/actor_enabled_side_effects'
+
+# Legion/Llm
+require 'rubocop/cop/legion/llm/settings_access_path'
+require 'rubocop/cop/legion/llm/no_loop_do'
+require 'rubocop/cop/legion/llm/rescue_log_level'
+require 'rubocop/cop/legion/llm/taxonomy_enum'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-legion
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 platform: ruby
 authors:
 - Esity
@@ -163,6 +163,10 @@ files:
 - lib/rubocop/cop/legion/helper_migration/logging_guard.rb
 - lib/rubocop/cop/legion/helper_migration/old_logging_methods.rb
 - lib/rubocop/cop/legion/helper_migration/require_defined_guard.rb
+- lib/rubocop/cop/legion/llm/no_loop_do.rb
+- lib/rubocop/cop/legion/llm/rescue_log_level.rb
+- lib/rubocop/cop/legion/llm/settings_access_path.rb
+- lib/rubocop/cop/legion/llm/taxonomy_enum.rb
 - lib/rubocop/cop/legion/rescue_logging/bare_rescue.rb
 - lib/rubocop/cop/legion/rescue_logging/no_capture.rb
 - lib/rubocop/cop/legion/rescue_logging/silent_capture.rb