kube_schema 1.11.0 → 2.0.0

data/lib/kube/schema.rb

@@ -2,9 +2,12 @@
 
 require_relative 'monkey_patches'
 require_relative 'errors'
-require_relative 'schema/version'
+# Requires lib/kube_schema/version.rb, not schema/version.rb.
+# `gem kit bump` derives the version file from the gem name.
+require_relative '../kube_schema/version'
 require_relative 'schema/resource'
 require_relative 'schema/sub_spec'
+require_relative 'schema/lazy'
 require_relative 'schema/instance'
 require_relative 'schema/manifest'
 
@@ -33,15 +36,9 @@ module Kube
       attr_reader :custom_schemas
 
       # Register a standalone JSON Schema for a custom resource kind.
-      #
-      # This lets users add CRD schemas from any source — for example,
-      # the datreeio/CRDs-catalog, operator repos, or their own CRDs.
-      # Registered kinds take precedence over built-in definitions.
-      #
-      # @param kind [String] The Kubernetes Kind (e.g. "Certificate")
-      # @param schema [Hash, String, Pathname] JSON Schema as a Hash,
-      #   a JSON string, or a file path to a .json file
-      # @param api_version [String] The apiVersion (e.g. "cert-manager.io/v1")
+      # @parameter kind [String] the Kubernetes Kind, e.g. "Certificate".
+      # @parameter schema [Hash, String, Pathname] a Hash, a JSON string, or a path to a .json file.
+      # @parameter api_version [String] the apiVersion, e.g. "cert-manager.io/v1".
       #
       # @example Register from a local file
       #   Kube::Schema.register("Certificate",
@@ -59,47 +56,53 @@ module Kube
         require "json"
         require "json_schemer"
 
-        parsed = case schema
-          when Hash
-            schema
-          when String, Pathname
-            path = schema.to_s
-            if File.exist?(path)
-              JSON.parse(File.read(path))
-            else
-              JSON.parse(path)
-            end
+        case schema
+        when Hash
+          parsed = schema
+        when String, Pathname
+          path = schema.to_s
+          if File.exist?(path)
+            parsed = JSON.parse(File.read(path))
           else
-            raise ArgumentError,
-              "schema must be a Hash, a JSON string, or a file path — got #{schema.class}"
+            parsed = JSON.parse(path)
           end
+        else
+          raise ArgumentError,
+            "schema must be a Hash, a JSON string, or a file path — got #{schema.class}"
+        end
 
-        # Key by full GVK ("group/version/Kind") so a registered CRD resolves
-        # on fully-qualified lookups (e.g. the api_version/kind path that
-        # Resource#rebuild reconstructs), not just kind-only lookups. Keying by
-        # bare kind also collided when two CRDs shared a kind across groups.
-        key = api_version ? "#{api_version}/#{kind}" : kind
+        # Key by GVK so lookups can be fully-qualified.
+        # A bare kind key collides when two CRDs share a kind.
+        if api_version
+          key = "#{api_version}/#{kind}"
+        else
+          key = kind
+        end
         @custom_schemas[key] = {
-          schema: JSONSchemer.schema(parsed),
-          defaults: { "apiVersion" => api_version, "kind" => kind }.freeze
+          entry:    Lazy::Spill.write(key, parsed),
+          defaults: { "apiVersion" => api_version, "kind" => kind }.freeze,
         }
 
-        # Invalidate cached resource classes on all instances so the
-        # new registration takes effect immediately.
+        # Invalidate cached resource classes so this registration applies.
         @instances.each_value { |inst| inst.send(:clear_resource_cache!) }
 
         kind
       end
 
       # Remove all custom schema registrations.
-      # Useful for test teardown or resetting state.
+      # @returns [void] clears custom schemas and resource caches.
       def reset_custom_schemas!
+        Lazy::Spill.clear
         @custom_schemas.clear
         @instances.each_value { |inst| inst.send(:clear_resource_cache!) }
       end
 
-      # Kube::Schema["1.34"]           => cached Instance (supports ["Deployment"] chaining)
-      # Kube::Schema["Deployment"]     => Resource via the default version
+      # @example
+      #   Kube::Schema["1.34"]       # => cached Instance (supports ["Deployment"] chaining)
+      #   Kube::Schema["Deployment"] # => Resource via the default version
+      #
+      # @parameter key [String] a version string or a Kind name.
+      # @returns [Instance, Class] the version Instance or a Resource subclass.
       def [](key)
         if key.start_with?("v") && Gem::Version.correct?(key.sub("v", ""))
           raise Kube::IncorrectVersionFormat,
@@ -113,7 +116,7 @@ module Kube
           else
             raise Kube::UnknownVersionError.new(
               "\n#{key} is an unknown version..." +
-              "\nAvailable: #{schema_versions.join(", ")}"
+              "\nAvailable: #{schema_versions.join(", ")}",
             )
           end
         else
@@ -123,31 +126,31 @@ module Kube
         end
       end
 
-      # Build a typed Resource from a raw hash.
-      #
-      # Looks up the "kind" key in the hash and resolves it to the
-      # correct Resource subclass via the schema registry. The hash
-      # may use string or symbol keys.
+      # Build a typed Resource from a raw hash's "kind".
       #
+      # @example
       #   Kube::Schema.parse("kind" => "Deployment", "apiVersion" => "apps/v1")
       #   Kube::Schema.parse(kind: "Pod", apiVersion: "v1", metadata: { name: "web" })
       #
-      # @param hash [Hash] a Kubernetes resource hash with at least a "kind" key
-      # @return [Resource] a schema-validated Resource instance
-      # @raise [ArgumentError] if the hash is nil, not a Hash, or missing "kind"
+      # @parameter hash [Hash] a resource hash with at least a "kind" key.
+      # @returns [Resource] a schema-validated Resource instance.
+      # @raises [ArgumentError] if the hash is nil, not a Hash, or missing "kind".
       def parse(hash)
-        raise ArgumentError, "Expected a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+        unless hash.is_a?(Hash)
+          raise ArgumentError, "Expected a Hash, got #{hash.class}"
+        end
 
         kind = hash["kind"] || hash[:kind]
-        raise ArgumentError, "Hash must contain a \"kind\" key" if kind.nil?
+        if kind.nil?
+          raise ArgumentError, "Hash must contain a \"kind\" key"
+        end
 
         resource_class = self[kind]
         resource_class.new(hash)
       end
 
-      # Available Kubernetes versions, read from the local schemas directory.
-      #
-      # @return [Array<String>] sorted version strings like ["1.19", "1.20", ...]
+      # Available Kubernetes versions, read from the schemas directory.
+      # @returns [Array(String)] sorted version strings like ["1.19", "1.20", ...].
       def schema_versions
         @schema_versions ||=
           Dir.glob(File.join(SCHEMAS_DIR, "v*.json")).map do |file_path|
@@ -155,17 +158,18 @@ module Kube
           end.sort_by { Gem::Version.new(_1) }
       end
 
-      # The latest Kubernetes version available in the schemas directory.
+      # The latest Kubernetes version in the schemas directory.
+      # @returns [String] the latest available version string.
       def latest_version
         schema_versions.last
       end
 
-      # All API groups known to the default schema version, including any
-      # custom schemas registered via .register. The core group is "".
+      # All API groups for the default version, plus custom ones.
       #
+      # @example
       #   Kube::Schema.api_groups # => ["", "apps", "argoproj.io", "batch", ...]
       #
-      # @return [Array<String>] sorted, deduplicated group names
+      # @returns [Array(String)] sorted, deduplicated group names.
       def api_groups
         self[schema_version || DEFAULT_VERSION].api_groups
       end
@@ -178,161 +182,158 @@ module Kube
 end
 
 
-if __FILE__ == $0
-  require "bundler/setup"
-  require "rspec/autorun"
 
-  RSpec.describe Kube::Schema do
-    describe "::VERSION" do
-      it "is defined" do
-        expect(Kube::Schema::VERSION).not_to be_nil
-      end
+__END__
 
-      it "is a valid semver string" do
-        expect(Kube::Schema::VERSION).to match(/\A\d+\.\d+\.\d+\z/)
-      end
-    end
+require "kube/schema"
 
-    describe "::DEFAULT_VERSION" do
-      it "is a version present in schema_versions" do
-        expect(Kube::Schema.schema_versions).to include(Kube::Schema::DEFAULT_VERSION)
-      end
+describe "Kube::Schema" do
+  describe "::VERSION" do
+    it "is defined" do
+      Kube::Schema::VERSION.should.not.be.nil
     end
 
-    describe ".schema_versions" do
-      it "returns an array of version strings" do
-        versions = Kube::Schema.schema_versions
-        expect(versions).to be_an(Array)
-        expect(versions).not_to be_empty
-        expect(versions).to all(match(/\A\d+\.\d+/))
-      end
+    it "is a valid semver string" do
+      Kube::Schema::VERSION.should.match(/\A\d+\.\d+\.\d+\z/)
+    end
+  end
 
-      it "is sorted by Gem::Version" do
-        versions = Kube::Schema.schema_versions
-        sorted = versions.sort_by { |v| Gem::Version.new(v) }
-        expect(versions).to eq(sorted)
-      end
+  describe "::DEFAULT_VERSION" do
+    it "is a version present in schema_versions" do
+      Kube::Schema.schema_versions.should.include Kube::Schema::DEFAULT_VERSION
+    end
+  end
 
-      it "does not include a leading 'v' prefix" do
-        expect(Kube::Schema.schema_versions).to all(satisfy { |v| !v.start_with?("v") })
-      end
+  describe ".schema_versions" do
+    it "returns an array of version strings" do
+      versions = Kube::Schema.schema_versions
+      versions.should.be.kind_of Array
+      versions.should.not.be.empty
+      versions.should.satisfy("every version looks like a minor release") { |vs| vs.all? { |v| v =~ /\A\d+\.\d+/ } }
     end
 
-    describe ".latest_version" do
-      it "returns the last element of schema_versions" do
-        expect(Kube::Schema.latest_version).to eq(Kube::Schema.schema_versions.last)
-      end
+    it "is sorted by Gem::Version" do
+      versions = Kube::Schema.schema_versions
+      versions.should == versions.sort_by { |v| Gem::Version.new(v) }
     end
 
-    describe ".[]" do
-      context "with a version string" do
-        it "returns an Instance for a known version" do
-          instance = Kube::Schema["1.34"]
-          expect(instance).to be_a(Kube::Schema::Instance)
-          expect(instance.version).to eq("1.34")
-        end
+    it "does not include a leading 'v' prefix" do
+      Kube::Schema.schema_versions.should.satisfy("no 'v' prefix") { |vs| vs.none? { |v| v.start_with?("v") } }
+    end
+  end
 
-        it "caches Instance objects by version" do
-          a = Kube::Schema["1.34"]
-          b = Kube::Schema["1.34"]
-          expect(a).to be(b)
-        end
+  describe ".latest_version" do
+    it "returns the last element of schema_versions" do
+      Kube::Schema.latest_version.should == Kube::Schema.schema_versions.last
+    end
+  end
 
-        it "raises UnknownVersionError for an invalid version" do
-          expect { Kube::Schema["0.0.1"] }.to raise_error(Kube::UnknownVersionError)
-        end
+  describe ".[]" do
+    describe "with a version string" do
+      it "returns an Instance for a known version" do
+        instance = Kube::Schema["1.34"]
+        instance.should.be.kind_of Kube::Schema::Instance
+        instance.version.should == "1.34"
       end
 
-      context "with a resource name" do
-        it "returns a Class that subclasses Resource" do
-          klass = Kube::Schema["Deployment"]
-          expect(klass).to be_a(Class)
-          expect(klass).to be < Kube::Schema::Resource
-        end
+      it "caches Instance objects by version" do
+        Kube::Schema["1.34"].should.be.identical_to Kube::Schema["1.34"]
       end
 
-      context "with a 'v'-prefixed version string" do
-        it "raises IncorrectVersionFormat" do
-          expect { Kube::Schema["v1.34"] }.to raise_error(
-            Kube::IncorrectVersionFormat,
-            /Don't preface the version with a "v"/
-          )
-        end
-
-        it "suggests the correct format in the error message" do
-          expect { Kube::Schema["v1.34"] }.to raise_error(
-            Kube::IncorrectVersionFormat,
-            /Use Kube::Schema\["1\.34"\] instead/
-          )
-        end
+      it "raises UnknownVersionError for an invalid version" do
+        lambda { Kube::Schema["0.0.1"] }.should.raise(Kube::UnknownVersionError)
       end
     end
 
-    describe ".parse" do
-      it "returns a typed Resource for a known kind" do
-        resource = Kube::Schema.parse("kind" => "Deployment", "apiVersion" => "apps/v1")
-        expect(resource).to be_a(Kube::Schema::Resource)
-        expect(resource.kind).to eq("Deployment")
-        expect(resource.apiVersion).to eq("apps/v1")
+    describe "with a resource name" do
+      it "returns a Class that subclasses Resource" do
+        klass = Kube::Schema["Deployment"]
+        klass.should.be.kind_of Class
+        klass.should.be < Kube::Schema::Resource
       end
+    end
 
-      it "works with symbol keys" do
-        resource = Kube::Schema.parse(kind: "Pod", apiVersion: "v1", metadata: { name: "web" })
-        expect(resource).to be_a(Kube::Schema::Resource)
-        expect(resource.kind).to eq("Pod")
-        expect(resource.metadata.name).to eq("web")
+    describe "with a 'v'-prefixed version string" do
+      it "raises IncorrectVersionFormat" do
+        error = lambda { Kube::Schema["v1.34"] }.should.raise(Kube::IncorrectVersionFormat)
+        error.message.should.match(/Don't preface the version with a "v"/)
       end
 
-      it "returns a class backed by the correct schema" do
-        resource = Kube::Schema.parse("kind" => "Service", "apiVersion" => "v1")
-        expect(resource.class.schema).not_to be_nil
-        expect(resource.class.defaults).to eq({ "apiVersion" => "v1", "kind" => "Service" })
+      it "suggests the correct format in the error message" do
+        error = lambda { Kube::Schema["v1.34"] }.should.raise(Kube::IncorrectVersionFormat)
+        error.message.should.match(/Use Kube::Schema\["1\.34"\] instead/)
       end
+    end
+  end
 
-      it "round-trips through to_h" do
-        original = Kube::Schema["Deployment"].new {
-          metadata.name = "web"
-          spec.replicas = 3
-          spec.selector.matchLabels = { app: "web" }
-          spec.template.metadata.labels = { app: "web" }
-          spec.template.spec.containers = [{ name: "web", image: "nginx" }]
-        }
-        parsed = Kube::Schema.parse(original.to_h)
-        expect(parsed.kind).to eq("Deployment")
-        expect(parsed.metadata.name).to eq("web")
-      end
+  describe ".parse" do
+    it "returns a typed Resource for a known kind" do
+      resource = Kube::Schema.parse("kind" => "Deployment", "apiVersion" => "apps/v1")
+      resource.should.be.kind_of Kube::Schema::Resource
+      resource.kind.should == "Deployment"
+      resource.apiVersion.should == "apps/v1"
+    end
 
-      it "raises ArgumentError for a non-Hash" do
-        expect { Kube::Schema.parse("not a hash") }.to raise_error(ArgumentError, /Expected a Hash/)
-      end
+    it "works with symbol keys" do
+      resource = Kube::Schema.parse(kind: "Pod", apiVersion: "v1", metadata: { name: "web" })
+      resource.should.be.kind_of Kube::Schema::Resource
+      resource.kind.should == "Pod"
+      resource.metadata.name.should == "web"
+    end
 
-      it "raises ArgumentError when kind is missing" do
-        expect { Kube::Schema.parse("apiVersion" => "v1") }.to raise_error(ArgumentError, /kind/)
-      end
+    it "returns a class backed by the correct schema" do
+      resource = Kube::Schema.parse("kind" => "Service", "apiVersion" => "v1")
+      resource.class.schema.should.not.be.nil
+      resource.class.defaults.should == { "apiVersion" => "v1", "kind" => "Service" }
+    end
 
-      it "raises RuntimeError for an unknown kind" do
-        expect { Kube::Schema.parse("kind" => "BogusKind", "apiVersion" => "v1") }.to raise_error(RuntimeError)
-      end
+    it "round-trips through to_h" do
+      original = Kube::Schema["Deployment"].new {
+        metadata.name = "web"
+        spec.replicas = 3
+        spec.selector.matchLabels = { app: "web" }
+        spec.template.metadata.labels = { app: "web" }
+        spec.template.spec.containers = [{ name: "web", image: "nginx" }]
+      }
+      parsed = Kube::Schema.parse(original.to_h)
+      parsed.kind.should == "Deployment"
+      parsed.metadata.name.should == "web"
     end
 
-    describe ".has_version?" do
-      it "returns true for a known version" do
-        expect(Kube::Schema.has_version?(Kube::Schema::DEFAULT_VERSION)).to be true
-      end
+    it "raises ArgumentError for a non-Hash" do
+      error = lambda { Kube::Schema.parse("not a hash") }.should.raise(ArgumentError)
+      error.message.should.match(/Expected a Hash/)
+    end
 
-      it "returns false for an unknown version" do
-        expect(Kube::Schema.has_version?("0.0.1")).to be false
-      end
+    it "raises ArgumentError when kind is missing" do
+      error = lambda { Kube::Schema.parse("apiVersion" => "v1") }.should.raise(ArgumentError)
+      error.message.should.match(/kind/)
     end
 
-    describe ".api_groups" do
-      it "delegates to the default version's instance" do
-        expect(Kube::Schema.api_groups).to eq(Kube::Schema[Kube::Schema::DEFAULT_VERSION].api_groups)
-      end
+    it "raises RuntimeError for an unknown kind" do
+      lambda { Kube::Schema.parse("kind" => "BogusKind", "apiVersion" => "v1") }.should.raise(RuntimeError)
+    end
+  end
 
-      it "includes core and built-in groups" do
-        expect(Kube::Schema.api_groups).to include("", "apps", "batch")
-      end
+  describe ".has_version?" do
+    it "returns true for a known version" do
+      Kube::Schema.has_version?(Kube::Schema::DEFAULT_VERSION).should.be.true
+    end
+
+    it "returns false for an unknown version" do
+      Kube::Schema.has_version?("0.0.1").should.be.false
+    end
+  end
+
+  describe ".api_groups" do
+    it "delegates to the default version's instance" do
+      Kube::Schema.api_groups.should == Kube::Schema[Kube::Schema::DEFAULT_VERSION].api_groups
+    end
+
+    it "includes core and built-in groups" do
+      Kube::Schema.api_groups.should.include ""
+      Kube::Schema.api_groups.should.include "apps"
+      Kube::Schema.api_groups.should.include "batch"
     end
   end
 end

data/lib/{kube/schema → kube_schema}/version.rb

@@ -2,6 +2,6 @@
 
 module Kube
   module Schema
-    VERSION = "1.11.0"
+    VERSION = "2.0.0"
   end
 end

data/lib/kube_schema.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# The entry point named after the gem.
+# `Kube::Schema` itself lives in lib/kube/schema.rb.
+# `require "kube_schema"` is what installing the gem expects to work.
+require_relative "kube/schema"

data/readme.md

@@ -16,6 +16,11 @@ Please see the [project documentation](https://general-intelligence-systems.gith
 
   - [Schema Versions](https://general-intelligence-systems.github.io/kube_schema/guides/schema-versions/index) - This guide covers working with different Kubernetes schema versions.
 
+## Contributing
+
+- [RELEASE.md](RELEASE.md) -- how a version is cut: `gem kit bump`, the changelog, and the gates that run before anything reaches RubyGems.
+- [DEPRECATIONS.md](DEPRECATIONS.md) -- the deprecation policy those gates enforce.
+
 ## Related Projects
 
 - [kube_cluster](https://github.com/general-intelligence-systems/kube_cluster) -- OOP resource management with dirty tracking and persistence

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kube_schema
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Nathan K
@@ -10,19 +10,33 @@ cert_chain: []
 date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: gem_kit-release
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.13'
+        version: '0.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.13'
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: scampi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +65,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: gem_kit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rubyshell
   requirement: !ruby/object:Gem::Requirement
@@ -90,6 +118,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".envrc"
+- ".github/FUNDING.yml"
 - ".github/workflows/convert-schemas.yml"
 - ".github/workflows/gh-pages.yml"
 - ".github/workflows/update-crds-catalog.yml"
@@ -98,21 +127,31 @@ files:
 - ".gitignore"
 - ".rubocop.yml"
 - CHANGELOG.md
+- DEPRECATIONS.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
+- RELEASE.md
 - Rakefile
 - assets/validation-error.png
 - bin/console
 - bin/copy-schemas-over
 - bin/create-cdi-x-values
 - bin/create-kubevirt-x-values
-- bin/increment-version
-- bin/release-gem
+- bin/rubocop
 - bin/setup
-- bin/tag-version
 - bin/test
 - bin/update-schema-index
+- cops/begin_block_assignment.rb
+- cops/comment_structure.rb
+- cops/constant_matches_path.rb
+- cops/multiline_method_arguments.rb
+- cops/no_conditional_assignment.rb
+- cops/no_console_logging.rb
+- cops/no_modifier_if.rb
+- cops/no_return.rb
+- cops/support/prism_source.rb
+- cops/use_tap.rb
 - examples/basic.rb
 - examples/custom_crds.rb
 - examples/manifest.rb
@@ -120,6 +159,7 @@ files:
 - examples/vcluster.rb
 - flake.lock
 - flake.nix
+- gemset.nix
 - guides/block-dsl/readme.md
 - guides/getting-started/readme.md
 - guides/links.yaml
@@ -132,11 +172,12 @@ files:
 - lib/kube/monkey_patches.rb
 - lib/kube/schema.rb
 - lib/kube/schema/instance.rb
+- lib/kube/schema/lazy.rb
 - lib/kube/schema/manifest.rb
 - lib/kube/schema/resource.rb
 - lib/kube/schema/sub_spec.rb
-- lib/kube/schema/version.rb
-- lib/kube/schema/version.rb.erb
+- lib/kube_schema.rb
+- lib/kube_schema/version.rb
 - readme.md
 - schemas/cdi-definitions.json
 - schemas/crd-definitions.json