kube_schema 1.11.0 → 2.0.0

data/cops/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 Cop
+    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/cops/use_tap.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# Requires `tap` when a method opens by assigning a local variable and closes by
+# returning that same variable:
+#
+#   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
+#
+#   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
+#
+# The assign-work-return shape states the return value twice — once as the
+# assignment target, once as a bare mention on the last line — and puts the two
+# far enough apart that the trailing `column` reads as a stray expression.
+# `tap` names the value once, scopes it to the block that works on it, and makes
+# "the value flows through unchanged" structural rather than something you check
+# by comparing the first and last lines.
+#
+# A body that REASSIGNS the variable is left alone: `tap` yields the original
+# object and returns it, so that rewrite would change the result.
+module RuboCop
+  module Cop
+    module Local
+      class UseTap < Base
+        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 = %i[lvasgn op_asgn or_asgn and_asgn masgn].freeze
+
+        def on_def(node)
+          check(node.body)
+        end
+
+        def on_defs(node)
+          check(node.body)
+        end
+
+        private
+
+          def check(body)
+            if tap_shaped?(body)
+              add_offense(body, message: format(MSG, name: 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&.begin_type? &&
+              body.children.size >= 2 &&
+              body.children.first.lvasgn_type? &&
+              returns_assigned?(body) &&
+              !reassigned?(body)
+          end
+
+          def assigned_name(body)
+            body.children.first.name
+          end
+
+          def returns_assigned?(body)
+            last = body.children.last
+
+            last.lvar_type? && last.children.first == 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 = assigned_name(body)
+
+            body.children[1..-2].any? do |statement|
+              statement.each_node(*REASSIGNMENTS).any? do |write|
+                writes_name?(write, name)
+              end
+            end
+          end
+
+          def writes_name?(node, name)
+            if node.masgn_type?
+              node.assignments.any? { |target| target == name }
+            else
+              node.children.first == name
+            end
+          end
+      end
+    end
+  end
+end

data/flake.lock

@@ -1,23 +1,45 @@
 {
   "nodes": {
+    "mine": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1790610895,
+        "narHash": "sha256-sansiZlrb60MrGFzTXNCVVMTU5EsGM6KWvZkA/aNp14=",
+        "owner": "n-at-han-k",
+        "repo": "flake.nix",
+        "rev": "0f3388742debac3e78751796f4568f441c0dee57",
+        "type": "github"
+      },
+      "original": {
+        "owner": "n-at-han-k",
+        "repo": "flake.nix",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1776169885,
-        "narHash": "sha256-l/iNYDZ4bGOAFQY2q8y5OAfBBtrDAaPuRQqWaFHVRXM=",
+        "lastModified": 1780902259,
+        "narHash": "sha256-q8yYEC5f1mFlQO9RGna4LTc9QrcvWunX6FYp83munkQ=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "4bd9165a9165d7b5e33ae57f3eecbcb28fb231c9",
+        "rev": "bd0ff2d3eac24699c3664d5966b9ef36f388e2ca",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
-        "ref": "nixos-unstable",
         "repo": "nixpkgs",
+        "rev": "bd0ff2d3eac24699c3664d5966b9ef36f388e2ca",
         "type": "github"
       }
     },
     "root": {
       "inputs": {
+        "mine": "mine",
         "nixpkgs": "nixpkgs",
         "utils": "utils"
       }
@@ -37,9 +59,24 @@
         "type": "github"
       }
     },
+    "systems_2": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
     "utils": {
       "inputs": {
-        "systems": "systems"
+        "systems": "systems_2"
       },
       "locked": {
         "lastModified": 1731533236,

data/flake.nix

@@ -2,38 +2,45 @@
   description = "Ruby gem flake";
 
   inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    nixpkgs.url = "github:NixOS/nixpkgs/bd0ff2d3eac24699c3664d5966b9ef36f388e2ca"; # == this machine's system nixpkgs
     utils.url = "github:numtide/flake-utils";
+    mine.url = "github:n-at-han-k/flake.nix";
+    mine.inputs.nixpkgs.follows = "nixpkgs";
   };
-  outputs = { self, nixpkgs, utils }:
+  outputs = { self, nixpkgs, utils, mine }:
     utils.lib.eachDefaultSystem (system:
       let
         pkgs = nixpkgs.legacyPackages.${system};
-        ruby = pkgs.ruby_3_4; # Specify version
+        lib = mine.lib.${system};
+
+        gems = pkgs.bundlerEnv {
+          name = "kube_schema-gems";
+          ruby = pkgs.ruby_3_4;
+          gemfile = ./Gemfile;
+          lockfile = ./Gemfile.lock;
+          gemset = ./gemset.nix;
+        };
       in
       {
-        devShells.default = pkgs.mkShell {
-          nativeBuildInputs = [
-            pkgs.pkg-config # native extension discovery
-          ];
-
+        devShells.default = lib.mkRubyShell {
           buildInputs = [
-            pkgs.trufflehog
-            ruby
-            pkgs.libyaml # psych gem
-            pkgs.openssl # openssl gem
+            gems
+            gems.wrappedRuby
+            pkgs.ripgrep # scampi shells out to `rg` to discover __END__ spec sections
           ];
 
-          shellHook = ''
-          export GEM_HOME="$HOME/.gem-${ruby.version}"
-          export GEM_PATH="$GEM_HOME"
-          export PATH="$GEM_HOME/bin:$PATH"
-          export BUNDLE_GEMFILE="$PWD/Gemfile"
-          export BUNDLE_PATH="$GEM_HOME"
-          export BUNDLE_BIN="$GEM_HOME/bin"
-        '';
+          shellHook = /* bash */ ''
+            unset RUBYOPT
+            export BUNDLE_FORCE_RUBY_PLATFORM=false
+            export BUNDLE_GEMFILE="$PWD/Gemfile"
+            export BUNDLE_FROZEN=false
+
+            export LANG="''${LANG:-C.UTF-8}"
+            export LC_ALL="''${LC_ALL:-$LANG}"
+
+            export RUBYLIB="$PWD/lib''${RUBYLIB:+:$RUBYLIB}"
+          '';
         };
       }
     );
 }
-