kube_cluster 1.9.1 → 2.0.0

data/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [2.0.0] - 2026-10-17
+
+### Added
+- `require "kube_cluster"` now works as an entry point alongside the existing
+  `require "kube/cluster"`.
+
+### Changed
+- **Breaking:** requires kube_schema `~> 2.0`, which compiles schema
+  definitions lazily, one at a time, on demand, instead of compiling the
+  whole OpenAPI document at boot. `Kube::Cluster[kind].schema` is now a
+  `Kube::Schema::Lazy::Source` rather than a `JSONSchemer::Schema`; it answers
+  the same `#value`/`#valid?`/`#validate`, so call sites that only use those
+  methods need no changes, but code that inspects the schema object's class
+  will need updating.
+
 ## [1.9.1] - 2026-09-28
 
 ### Fixed

data/Gemfile

@@ -2,7 +2,19 @@
 
 source "https://rubygems.org"
 
-gemspec
+gem "activesupport", "~> 8.0"
+gem "kube_kubectl", "~> 2.0"
+gem "kube_schema", "~> 2.0"
+
+gem "lefthook", "~> 2.1"
+gem "rake", "~> 13.0"
+gem "scampi", "~> 1.0"
+gem "rubocop"
+gem "decode"
+
+group :release do
+	gem "gem_kit-release", "~> 0.3"
+end
 
 group :maintenance, optional: true do
 	gem "utopia-project"

data/Gemfile.lock

@@ -1,11 +1,3 @@
-PATH
-  remote: .
-  specs:
-    kube_cluster (1.8.0)
-      activesupport (~> 8.0)
-      kube_kubectl (~> 2.0)
-      kube_schema (~> 1.11.0)
-
 GEM
   remote: https://rubygems.org/
   specs:
@@ -22,6 +14,7 @@ GEM
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
+    ast (2.4.3)
     async (2.39.0)
       console (~> 1.29)
       fiber-annotation
@@ -73,7 +66,7 @@ GEM
       bake (~> 0.21)
       markly (~> 0.8)
     base64 (0.3.0)
-    bigdecimal (4.1.2)
+    bigdecimal (4.1.3)
     build-files (1.10.2)
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
@@ -107,6 +100,10 @@ GEM
     fiber-local (1.1.0)
       fiber-storage
     fiber-storage (1.0.1)
+    gem_kit (0.2.0)
+    gem_kit-release (0.3.2)
+      gem_kit (>= 0.1, < 1.0)
+      thor (~> 1.3)
     hana (1.3.7)
     http-accept (2.2.1)
     i18n (1.14.8)
@@ -132,10 +129,13 @@ GEM
       rubyshell (~> 1.5)
       shellwords (~> 0.2.2)
       string_builder (~> 1.2.2)
-    kube_schema (1.11.0)
+    kube_schema (2.0.0)
+      gem_kit (~> 0.2)
       json_schemer (~> 2.5.0)
       rubyshell (~> 1.5.0)
+    language_server-protocol (3.17.0.6)
     lefthook (2.1.10)
+    lint_roller (1.1.0)
     localhost (1.8.0)
       bake
     logger (1.7.0)
@@ -167,6 +167,10 @@ GEM
     net-smtp (0.5.1)
       net-protocol
     openssl (4.0.2)
+    parallel (2.3.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
@@ -186,11 +190,13 @@ GEM
     psych (5.3.1)
       date
       stringio
+    racc (1.8.1)
     rack (3.2.6)
     rackula (1.4.1)
       falcon (~> 0.46)
       samovar (~> 2.1)
       variant
+    rainbow (3.1.1)
     rake (13.4.2)
     rbs (4.0.2)
       logger
@@ -200,9 +206,24 @@ GEM
       erb
       psych (>= 4.0.0)
       tsort
-    regexp_parser (2.12.0)
+    regexp_parser (2.13.1)
     reline (0.6.3)
       io-console (~> 0.5)
+    rubocop (1.92.0)
+      json (>= 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.11.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
     rubyshell (1.5.0)
     rugged (1.9.0)
     samovar (2.4.1)
@@ -211,16 +232,20 @@ GEM
     scampi (1.0.0)
     securerandom (0.4.1)
     shellwords (0.2.2)
-    simpleidn (0.2.3)
+    simpleidn (0.3.0)
     string-format (0.2.0)
     string_builder (1.2.4)
     stringio (3.2.0)
+    thor (1.5.0)
     thread-local (1.1.0)
     timeout (0.6.1)
     traces (0.18.2)
     tsort (0.2.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
     uri (1.1.1)
     utopia (2.32.1)
       bake (~> 0.20)
@@ -254,14 +279,19 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  activesupport (~> 8.0)
   bake-gem
   bake-modernize
   bake-releases
-  kube_cluster!
+  decode
+  gem_kit-release (~> 0.3)
+  kube_kubectl (~> 2.0)
+  kube_schema (~> 2.0)
   lefthook (~> 2.1)
   rake (~> 13.0)
+  rubocop
   scampi (~> 1.0)
   utopia-project
 
 BUNDLED WITH
-   2.6.9
+   2.7.2

data/bin/rubocop

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+exec bundle exec rubocop "$@"

data/cops/begin_block_assignment.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Bans assigning a `begin ... end` to a variable.
+#
+# @example
+#   begin
+#     lvar = ...
+#   end
+module RuboCop
+  module Cop
+    module Local
+      class BeginBlockAssignment < Base
+        MSG = "Do not assign a `begin...end` expression to a variable; " \
+              "move the assignment inside the begin block."
+
+        def on_lvasgn(node)
+          check(node)
+        end
+        alias on_ivasgn on_lvasgn
+        alias on_cvasgn on_lvasgn
+        alias on_gvasgn on_lvasgn
+
+        private
+
+          def check(node)
+            rhs = node.children.last
+            if rhs.is_a?(RuboCop::AST::Node) && rhs.type == :kwbegin
+              add_offense(node)
+            end
+          end
+      end
+    end
+  end
+end

data/cops/comment_structure.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+# Checks the structure of a comment, which decode parses into three parts: the summary, the annotations, and the summary belonging to each annotation.
+#
+# @example
+#   # Connect to the given endpoint, returning the HTTP client and reference.   <- summary
+#   # @parameter endpoint [Endpoint] used to connect to the remote system.      <- annotation
+#   # @returns [Tuple(Client, Reference)] the client and reference.
+#
+# Four things are checked, each measured against how async-rest, async-discord and async-ollama document themselves:
+#
+# A paragraph occupies one line. None of the 99 summary paragraphs in those three projects is wrapped, and async-rest's run to 544 characters.
+#
+# A summary is short, and no longer than the code it describes earns. Across 76 documented methods the median summary is 4 to 9 words whatever the length of the method, so the allowance starts at ten words and grows by three per line of body, to a ceiling of thirty.
+#
+# A module's summary is ten words or fewer. The only commented module in async-rest is exactly ten.
+#
+# A documented method says what it takes and returns. A summary with no annotations describes the method in prose and leaves the signature undocumented, which is what annotations are for. A method with no comment at all is not this cop's business: that is documentation coverage, which decode reports on separately.
+#
+# Nothing here is corrected automatically. A comment which breaks these rules has to be rewritten rather than reflowed, and a correction which only moved the words around would hide that.
+#
+# Each check is configured on its own, because they are not all worth applying everywhere:
+#
+# @example
+#   Local/CommentStructure:
+#     Annotations:
+#       Include:
+#         - "lib/**/*.rb"
+#     Length:
+#       Exclude:
+#         - "bin/**/*"
+#     Wrapping:
+#       Enabled: true
+#
+# A check with no `Include` runs everywhere; given one, it runs only where a path matches. `Exclude` then removes paths from whatever is left. `Annotations` defaults to `lib` alone: a script in `bin` and a case in `test` have no interface for anyone else to call, so annotating them documents nothing.
+#
+# What a declaration says is read from the run of comment lines touching it. Where an offence is reported is read from the wider span the library attributes to the declaration, less any magic comment, because decode reports a part's position within that span rather than the line it came from.
+
+require "decode/language/ruby/generic"
+
+require_relative "support/prism_source"
+
+module RuboCop
+  module Cop
+    module Local
+      class CommentStructure < Base
+        include PrismSource
+
+        MSG_WRAPPED_SUMMARY = "Do not wrap a summary paragraph: a paragraph is one line, however long."
+
+        MSG_WRAPPED_ANNOTATION = "Do not wrap the summary of `@%<directive>s`: an annotation's summary is one line."
+
+        MSG_TOO_LONG = "This summary is %<words>d words; %<allowed>d is the most %<subject>s may have."
+
+        MSG_NO_ANNOTATIONS = "This method is described in prose but its parameters and return value are not: document them with annotations, or say nothing."
+
+        TAGS = Decode::Language::Ruby::Generic::TAGS
+
+        # Each check, and the paths it applies to when the configuration names none.
+        CHECKS = {
+          "Wrapping" => nil,
+          "Length" => nil,
+          "Annotations" => ["lib/**/*.rb"].freeze,
+        }.freeze
+
+        GLOB = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
+        HEADER = /\A#\s*(frozen_string_literal:|Released under|Copyright,|!)/
+
+        # What a Ruby file says to the interpreter rather than to a reader.
+        MAGIC = /\A#\s*(frozen_string_literal:|encoding:|coding:|warn_indent:|shareable_constant_value:|!|-\*-)/
+
+        TERMINAL = [".", ":", "?", "!"].freeze
+
+        # Multi-line content is the point of these, so their summaries are left alone.
+        FREEFORM = [Decode::Comment::Example].freeze
+
+        def on_new_investigation
+          if self.applies?("Wrapping")
+            self.blocks.each do |block|
+              self.check_wrapping(block)
+            end
+          end
+
+          if self.applies?("Length")
+            self.prism_each(::Prism::ModuleNode).each do |node|
+              self.check_summary(node, "a module summary", self.cop_config.fetch("ModuleWords", 10))
+            end
+
+            self.prism_each(::Prism::ClassNode).each do |node|
+              self.check_summary(node, "a class summary", self.cop_config.fetch("MaximumWords", 30))
+            end
+          end
+
+          self.prism_each(::Prism::DefNode).each do |node|
+            self.check_method(node)
+          end
+        end
+
+        private
+
+        # Whether a check applies to the file being inspected.
+        def applies?(check)
+          configuration = self.cop_config[check] || {}
+
+          if configuration["Enabled"] == false
+            false
+          else
+            path = ::RuboCop::PathUtil.relative_path(processed_source.file_path.to_s)
+
+            included = configuration["Include"] || CHECKS.fetch(check)
+            excluded = configuration["Exclude"] || []
+
+            self.matches?(path, included, true) and !self.matches?(path, excluded, false)
+          end
+        end
+
+        # @parameter default [Boolean] what an absent or empty list of patterns means.
+        def matches?(path, patterns, default)
+          if patterns.nil? or patterns.empty?
+            default
+          else
+            patterns.any?{|pattern| File.fnmatch?(pattern, path, GLOB)}
+          end
+        end
+
+        def check_method(node)
+          lines = node.location.end_line - node.location.start_line + 1
+          base = self.cop_config.fetch("BaseWords", 10)
+          per_line = self.cop_config.fetch("WordsPerLine", 3)
+          ceiling = self.cop_config.fetch("MaximumWords", 30)
+
+          allowed = [base + (per_line * lines), ceiling].min
+
+          if self.applies?("Length")
+            self.check_summary(node, "a summary of #{lines} #{lines == 1 ? "line" : "lines"} of code", allowed)
+          end
+
+          if self.applies?("Annotations")
+            self.check_annotations(node)
+          end
+        end
+
+        # The comment which documents a declaration, as the parts decode reads it as.
+        def parts_of(node)
+          comments = self.documenting(node)
+
+          if comments.empty?
+            nil
+          else
+            self.parse(comments)
+          end
+        end
+
+        # The comment above a declaration, without the file's own header.
+        def documenting(node)
+          self.prism_leading_comments(node).reject{|comment| self.prism_source(comment).match?(HEADER)}
+        end
+
+        # Every comment the declaration owns, which is what the parts are indexed against.
+        def owned(node)
+          self.prism_owned_comments(node).drop_while{|comment| self.prism_source(comment).match?(MAGIC)}
+        end
+
+        def check_summary(node, subject, allowed)
+          parts = self.parts_of(node)
+
+          if parts
+            summary = parts.map(&:first).grep(Decode::Comment::Text)
+            words = summary.sum{|text| text.line.split.size}
+
+            if words > allowed
+              message = format(MSG_TOO_LONG, words: words, allowed: allowed, subject: subject)
+
+              add_offense(self.summary_range(node, parts, summary.first), message: message)
+            end
+          end
+        end
+
+        def check_annotations(node)
+          parts = self.parts_of(node)
+
+          if parts and parts.any?{|part, _| part.is_a?(Decode::Comment::Text)}
+            annotations = parts.map(&:first).reject{|part| part.is_a?(Decode::Comment::Text)}
+
+            if annotations.empty?
+              add_offense(self.prism_range(node.name_loc), message: MSG_NO_ANNOTATIONS)
+            end
+          end
+        end
+
+        # Consecutive comment lines: a block is what documents one thing, so a wrap can only happen inside one.
+        def blocks
+          [].tap do |found|
+            current = []
+
+            self.prism_comments.each do |comment|
+              text = self.prism_source(comment)
+
+              if text.match?(HEADER) or text.start_with?("# rubocop:")
+                next
+              end
+
+              if current.empty? or comment.location.start_line == current.last.location.start_line + 1
+                current << comment
+              else
+                found << current
+                current = [comment]
+              end
+            end
+
+            unless current.empty?
+              found << current
+            end
+          end
+        end
+
+        def check_wrapping(block)
+          nodes = self.parse(block)
+
+          nodes.each_with_index do |(node, lines), index|
+            if node.is_a?(Decode::Comment::Text)
+              following = nodes[index + 1]&.first
+
+              if following.is_a?(Decode::Comment::Text) and !self.terminated?(node.line)
+                add_offense(self.prism_range(block[lines.first.first].location), message: MSG_WRAPPED_SUMMARY)
+              end
+            elsif !FREEFORM.include?(node.class)
+              summary = lines.drop(1).reject{|line| line.last.strip.start_with?("@")}
+
+              if summary.size > 1
+                message = format(MSG_WRAPPED_ANNOTATION, directive: node.directive)
+
+                add_offense(self.prism_range(block[summary.first.first].location), message: message)
+              end
+            end
+          end
+        end
+
+        # decode consumes the lines it parses and does not report where they came from, so they are handed over through something which records what it gave away.
+        def parse(block)
+          source = Consumable.new(block.each_with_index.map{|comment, index| [index, self.text_of(comment)]})
+          nodes = []
+          cursor = 0
+
+          TAGS.parse(source) do |node|
+            if node
+              nodes << [node, source.log[cursor..]]
+              cursor = source.log.size
+            end
+          end
+
+          nodes
+        end
+
+        # The comment without its `#`, keeping the indentation which tells decode what is nested.
+        def text_of(comment)
+          self.prism_source(comment).sub(/\A#\s?/, "")
+        end
+
+        # Where to report a summary which is too long: the comment line it starts on, or the declaration itself when the summary cannot be traced back to one.
+        def summary_range(node, parts, text)
+          comments = self.owned(node)
+          entry = text && parts.find{|part, _| part.equal?(text)}
+
+          if entry and comments[entry.last.first.first]
+            self.prism_range(comments[entry.last.first.first].location)
+          else
+            self.prism_node_range(node)
+          end
+        end
+
+        def terminated?(line)
+          text = line.strip
+
+          text.empty? or TERMINAL.any?{|mark| text.end_with?(mark)}
+        end
+
+        # What decode shifts lines off, which remembers them.
+        class Consumable
+          def initialize(entries)
+            @entries = entries
+            @log = []
+          end
+
+          attr :log
+
+          def first = @entries.first&.last
+
+          def shift
+            entry = @entries.shift
+
+            if entry
+              @log << entry
+              entry.last
+            end
+          end
+
+          def empty? = @entries.empty?
+        end
+      end
+    end
+  end
+end

data/cops/constant_matches_path.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# Bans a constant that does not match its file's path.
+#
+# @example
+#   lib/mailers/welcome.rb          -> Mailers::Welcome          # YES
+#   lib/mailers/welcome.rb          -> WelcomeMailer             # NO
+#   lib/models/11_organization.rb   -> Models::Organization      # YES
+#   lib/jobs/sync_tenant_claims.rb  -> Jobs::SyncTenantClaims    # YES
+#   lib/jobs/sync_tenant_claims.rb  -> SyncTenantClaimsJob       # NO
+module RuboCop
+  module Cop
+    module Local
+      class ConstantMatchesPath < Base
+        MSG = "`%<actual>s` does not match its path; this file should define " \
+              "`%<expected>s` (or a constant nested inside it)."
+
+        MSG_EMPTY = "This file defines no namespaced constant; it should define " \
+                    "`%<expected>s`."
+
+        # Directories that are a load path root, not a namespace segment.
+        def roots = Array(cop_config.fetch("Roots", ["lib"]))
+
+        def inflections = cop_config.fetch("Inflections", {})
+
+        # Paths that legitimately define something else, such as monkey patches.
+        def ignored = Array(cop_config.fetch("IgnorePaths", []))
+
+        def on_new_investigation
+          if processed_source.blank?
+            nil
+          else
+            expected_namespace(processed_source.file_path).then do |expected|
+              # A file outside a configured root, or an ignored path, has no namespace to be wrong about. Nor does one that defines no constant at all -- an empty file, or one that only runs code.
+              unless expected.nil?
+                report(top_level_constants(processed_source.ast), expected)
+              end
+            end
+          end
+        end
+
+        private
+
+          def report(defined, expected)
+            defined.each do |name, node|
+              unless matches?(name, expected)
+                add_offense(node, message: format(MSG, actual: name, expected: expected))
+              end
+            end
+          end
+
+          # `Mailers::Welcome` is right for lib/mailers/welcome.rb, and so is `Mailers` alone (a file may open its own namespace to add to it).
+          def matches?(actual, expected)
+            actual == expected ||
+              expected.start_with?("#{actual}::") ||
+              actual.start_with?("#{expected}::")
+          end
+
+          def expected_namespace(path)
+            parts = path.to_s.split(File::SEPARATOR)
+            root  = parts.rindex { |part| roots.include?(part) }
+            segments = root && parts[(root + 1)..]
+
+            if segments.nil? || segments.empty? || ignored?(segments)
+              nil
+            else
+              named = segments.dup
+              named[-1] = named[-1].sub(/\.rb\z/, "")
+              named.map { |segment| camelize(segment) }.join("::")
+            end
+          end
+
+          def ignored?(segments)
+            ignored.any? do |glob|
+              File.fnmatch?(glob, segments.join("/"), File::FNM_PATHNAME)
+            end
+          end
+
+          # `11_organization` -> `Organization`. The prefix orders loading; it is not part of the name.
+          def camelize(segment)
+            name = segment.sub(/\A\d+_/, "")
+
+            if inflections.key?(name)
+              inflections[name]
+            else
+              name.split("_").map { |word| inflections[word] || word.capitalize }.join
+            end
+          end
+
+          # The constants a file opens at its top level, flattened through compact forms so `module A; class B` and `class A::B` both read as `A::B`.
+          def top_level_constants(node, prefix = nil)
+            if node.nil?
+              []
+            elsif node.begin_type?
+              node.children.flat_map { |child| top_level_constants(child, prefix) }
+            elsif node.module_type? || node.class_type?
+              constants_in(node, prefix)
+            else
+              []
+            end
+          end
+
+          def constants_in(node, prefix)
+            name = qualified(node.children.first)
+
+            if name.nil?
+              []
+            else
+              if prefix
+                full = "#{prefix}::#{name}"
+              else
+                full = name
+              end
+
+              body = node.children[node.class_type? ? 2 : 1]
+              nested = top_level_constants(body, full)
+
+              # Report the DEEPEST constant: `module Jobs; class Foo` is an offence about `Jobs::Foo`, not about `Jobs`.
+              if nested.empty?
+                [[full, node]]
+              else
+                nested
+              end
+            end
+          end
+
+          def qualified(const)
+            if const&.const_type?
+              namespace = const.namespace
+
+              if namespace.nil? || namespace.cbase_type?
+                const.short_name.to_s
+              else
+                inner = qualified(namespace)
+                inner && "#{inner}::#{const.short_name}"
+              end
+            end
+          end
+      end
+    end
+  end
+end