kube_schema 1.0.0 → 1.1.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kube_schema (0.1.1)
+    kube_schema (1.0.0)
       black_hole_struct (~> 0.1)
       json_schemer (~> 2.5)
       rubyshell (~> 1.5)
@@ -14,6 +14,7 @@ GEM
     ast (2.4.3)
     bigdecimal (4.0.1)
     black_hole_struct (0.1.3)
+    diff-lcs (1.6.2)
     hana (1.3.7)
     json (2.19.2)
     json-schema (6.2.0)
@@ -28,7 +29,6 @@ GEM
     lint_roller (1.1.0)
     mcp (0.8.0)
       json-schema (>= 4.1)
-    minitest (5.27.0)
     parallel (1.27.0)
     parser (3.3.10.2)
       ast (~> 2.4.1)
@@ -39,6 +39,19 @@ GEM
     rainbow (3.1.1)
     rake (13.3.1)
     regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
     rubocop (1.85.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
@@ -67,8 +80,8 @@ PLATFORMS
 
 DEPENDENCIES
   kube_schema!
-  minitest (~> 5.0)
   rake (~> 13.0)
+  rspec (~> 3.13)
   rubocop (~> 1.21)
 
 BUNDLED WITH

data/README.md

@@ -1,4 +1,4 @@
-# KubeSchema
+# Kube::Schema
 
 Ruby objects for Kubernetes OpenAPI schemas.
 
@@ -11,7 +11,7 @@ gem "kube_schema"
 ## Usage
 
 ```ruby
-Deployment = KubeSchema["1.33.6"]["Deployment"]
+Deployment = Kube::Schema["1.33.6"]["Deployment"]
 
 app = Deployment.new do
   self.description = "My app"
@@ -24,7 +24,7 @@ app.properties    # => {"apiVersion" => ..., "kind" => ..., ...}
 ```
 
 ```ruby
-class RailsApp < KubeSchema["1.33.6"]["Deployment"]
+class RailsApp < Kube::Schema["1.33.6"]["Deployment"]
   def is_the_best?
     true
   end

data/Rakefile

@@ -1,11 +1,7 @@
 # frozen_string_literal: true
 
-require "rake/testtask"
+require "rspec/core/rake_task"
 
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
-end
+RSpec::Core::RakeTask.new(:spec)
 
-task default: :test
+task default: :spec

data/bin/console

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 require "bundler/setup"
-require "kube_schema"
+require "kube/schema"
 require "irb"
 
 IRB.start(__FILE__)

data/bin/increment-version

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 require "erb"
-require_relative "../lib/kube_schema/version"
+require_relative "../lib/kube/schema/version"
 
 USAGE = <<~TEXT
   Usage: bin/increment-version <major|minor|patch>
@@ -15,7 +15,7 @@ unless %w[major minor patch].include?(segment)
   exit 1
 end
 
-current = KubeSchema::VERSION
+current = Kube::Schema::VERSION
 major, minor, patch = current.split(".").map(&:to_i)
 
 case segment
@@ -32,8 +32,8 @@ end
 
 version = "#{major}.#{minor}.#{patch}"
 
-template_path = File.expand_path("../lib/kube_schema/version.rb.erb", __dir__)
-output_path   = File.expand_path("../lib/kube_schema/version.rb", __dir__)
+template_path = File.expand_path("../lib/kube/schema/version.rb.erb", __dir__)
+output_path   = File.expand_path("../lib/kube/schema/version.rb", __dir__)
 
 template = ERB.new(File.read(template_path))
 result = template.result(binding)
@@ -41,4 +41,3 @@ result = template.result(binding)
 File.write(output_path, result)
 
 puts "#{current} -> #{version}"
-

data/bin/release-gem

@@ -1,9 +1,9 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require_relative "../lib/kube_schema/version"
+require_relative "../lib/kube/schema/version"
 
-local_version = KubeSchema::VERSION
+local_version = Kube::Schema::VERSION
 gem_name = "kube_schema"
 gemspec = "kube_schema.gemspec"
 

data/bin/tag-version

@@ -1,9 +1,9 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require_relative "../lib/kube_schema/version"
+require_relative "../lib/kube/schema/version"
 
-version = KubeSchema::VERSION
+version = Kube::Schema::VERSION
 tag = "v#{version}"
 
 existing = `git tag -l #{tag}`.strip

data/bin/test

@@ -1,14 +1,12 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-$LOAD_PATH.unshift File.expand_path("../test", __dir__)
-
 require "bundler/setup"
 
 Dir.chdir(File.expand_path("..", __dir__))
 
 if ARGV.empty?
-  Dir.glob("test/**/*_test.rb").sort.each { |f| require_relative "../#{f}" }
+  exec("bundle", "exec", "rspec")
 else
-  ARGV.each { |f| require_relative "../#{f}" }
+  exec("bundle", "exec", "rspec", *ARGV)
 end

data/kube_schema.gemspec

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require_relative "lib/kube_schema/version"
+require_relative "lib/kube/schema/version"
 
 Gem::Specification.new do |spec|
   spec.name = "kube_schema"
-  spec.version = KubeSchema::VERSION
+  spec.version = Kube::Schema::VERSION
   spec.authors = ["Nathan K"]
   spec.email = ["nathankidd@hey.com"]
 
@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rspec", "~> 3.13"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rubocop", "~> 1.21"
 

data/lib/kube/schema/instance.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Kube
+  module Schema
+    # Represents a single Kubernetes version's OpenAPI schema.
+    # Lazily loads the JSON and builds an index of group/version/kind strings
+    # mapped back to definition keys.
+    #
+    #   instance = Kube::Schema::Instance.new("v1.33.6")
+    #   instance["Deployment"]
+    #   instance["apps/v1/Deployment"]
+    #   instance.list_resources  #=> sorted array of "group/version/kind" strings
+    #
+    class Instance
+      attr_reader :version
+
+      def initialize(version)
+        @resource_classes = {}
+
+        is_a_version = -> (v) { Gem::Version.correct?(v) }
+
+        if is_a_version.(version)
+          @version = version
+        else
+          raise UnknownVersionError.new(
+            "\n#{version} is an unknown version..." +
+            "\nUse `Kube::Schema.schema_versions` to get a list."
+          )
+        end
+      end
+
+      # Look up a resource by full "group/version/kind" or by bare "Kind".
+      # Returns a class that inherits from Kube::Schema::Resource, or nil.
+      def [](key)
+        Kube::Schema::SchemaIndex.new(version).find(key.downcase).then do |path|
+          if path.nil?
+            raise "No resource schema found for #{key}!!!!!!!"
+          else
+            @resource_classes[key] ||= begin
+              schema_hash = JSON.parse(Kube::Schema::SchemaCache.read(path))
+
+              Class.new(::Kube::Schema::Resource) do
+                @schema = schema_hash
+
+                def self.schema
+                  @schema || superclass.schema
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kube/schema/resource.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "ostruct"
+require "black_hole_struct"
+require "json_schemer"
+
+module Kube
+  module Schema
+    class Resource
+
+      # Subclasses generated by Instance#[] have a class-level .schema.
+      def initialize(hash = {}, &block)
+        hash = deep_stringify_keys(hash)
+
+        if self.class.schema
+          schemer = JSONSchemer.schema(self.class.schema, insert_property_defaults: true)
+          schemer.valid?(hash)
+        end
+
+        @data = BlackHoleStruct.new(hash)
+        @data.instance_exec(&block) if block
+      end
+
+      # Gets overridden by the factory in Kube::Schema::Instance
+      def self.schema
+        nil
+      end
+
+      def valid?
+        return true if self.class.schema.nil?
+
+        schemer = JSONSchemer.schema(self.class.schema)
+        schemer.valid?(deep_stringify_keys(to_h))
+      end
+
+      def to_h
+        @data.to_h
+      end
+
+      def ==(other)
+        other.is_a?(Resource) && to_h == other.to_h
+      end
+
+      private
+
+        def deep_stringify_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) do |(k, v), result|
+              result[k.to_s] = deep_stringify_keys(v)
+            end
+          when Array
+            obj.map { |v| deep_stringify_keys(v) }
+          else
+            obj
+          end
+        end
+    end
+  end
+end

data/lib/kube/schema/schema_cache.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'net/http'
+require 'uri'
+
+module Kube
+  module Schema
+    # Lazily downloads individual schema JSON files from the schemas branch
+    # on GitHub and caches them locally under Gem.cache_home (XDG_CACHE_HOME).
+    #
+    # Usage:
+    #   Kube::Schema::SchemaCache.fetch("cert-manager.io/certificate_v1")
+    #   # => "/home/user/.cache/kube_schema/schemas/cert-manager.io/certificate_v1.json"
+    #
+    #   Kube::Schema::SchemaCache.read("v1.33.6/deployment")
+    #   # => "{...json contents...}"
+    #
+    module SchemaCache
+      BASE_URL = 'https://raw.githubusercontent.com/general-intelligence-systems/kube_schema/refs/heads/schemas'
+
+      class DownloadError < StandardError; end
+
+      class << self
+        # Root directory for cached schemas.
+        # Defaults to ~/.cache/kube_schema/schemas (or $XDG_CACHE_HOME/kube_schema/schemas).
+        def cache_dir
+          @cache_dir ||= File.join(Gem.cache_home, 'kube_schema', 'schemas')
+        end
+
+        # Override the cache directory (useful for testing).
+        attr_writer :cache_dir
+
+        # Returns the local file path for a schema, downloading it if not cached.
+        # The file_path should NOT include the .json extension.
+        #
+        #   SchemaCache.fetch("cert-manager.io/certificate_v1")
+        #   # => "/home/user/.cache/kube_schema/schemas/cert-manager.io/certificate_v1.json"
+        #
+        def fetch(file_path)
+          local = local_path(file_path)
+
+          if File.exist?(local)
+            local
+          else
+            download!(file_path, local)
+          end
+        end
+
+        # Returns the JSON content as a String, downloading if necessary.
+        def read(file_path)
+          File.read(fetch(file_path))
+        end
+
+        # Returns the local path where a schema would be cached (without downloading).
+        def local_path(file_path)
+          if file_path.end_with?(".json")
+            raise "What are you doing???? don't put .json on the end...."
+          else
+            File.join(cache_dir, "#{file_path}.json")
+          end
+        end
+
+        # Returns true if the schema is already cached locally.
+        def cached?(file_path)
+          File.exist?(local_path(file_path))
+        end
+
+        # Removes a single cached schema file.
+        def evict(file_path)
+          path = local_path(file_path)
+
+          if File.exist?(path)
+            File.delete(path)
+          end
+        end
+
+        # Removes the entire cache directory.
+        def clear!
+          FileUtils.rm_rf(cache_dir)
+        end
+
+        private
+
+          def download!(file_path, local)
+            url = "#{BASE_URL}/#{file_path}.json"
+            uri = URI.parse(url)
+
+            Net::HTTP.get_response(uri).then do |response|
+              unless response.is_a?(Net::HTTPSuccess)
+                raise DownloadError, "Failed to download schema: #{url} (HTTP #{response.code})"
+              end
+
+              FileUtils.mkdir_p(File.dirname(local))
+              File.write(local, response.body)
+              local
+            end
+          end
+      end
+    end
+  end
+end

data/lib/kube/schema/schema_index.rb

@@ -0,0 +1,29 @@
+module Kube
+  module Schema
+    class SchemaIndex
+      def initialize(version)
+        @version = version
+      end
+
+      def find(query)
+        all_paths.select { _1.include?(query.downcase) }.first
+      end
+
+      def all_paths
+        kubernetes_paths + custom_resource_paths
+      end
+
+      def custom_resource_paths
+        File.read(SCHEMA_INDEX + "/crds.txt").lines.map do |line|
+          line.chomp.gsub(".json", "")
+        end
+      end
+
+      def kubernetes_paths
+        File.read(SCHEMA_INDEX + "/v#{@version}.txt").lines.map do |line|
+          line.chomp.gsub(".json", "")
+        end
+      end
+    end
+  end
+end

data/lib/kube/schema/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kube
+  module Schema
+    VERSION = "1.1.0"
+  end
+end

data/lib/kube/schema/version.rb.erb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kube
+  module Schema
+    VERSION = "<%= version %>"
+  end
+end

data/lib/kube/schema.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative 'schema/version'
+require_relative 'schema/resource'
+require_relative 'schema/instance'
+require_relative 'schema/schema_cache'
+require_relative 'schema/schema_index'
+
+module Kube
+  module Schema
+    class UnknownVersionError < StandardError; end
+    class IncorrectVersionFormat < StandardError; end
+
+    @schema_version = nil
+    @instances = {}
+
+    GEM_ROOT = File.expand_path("../..", __dir__).freeze
+    SCHEMA_INDEX = File.join(GEM_ROOT, "data").freeze
+    DEFAULT_VERSION = "1.34.4" # 2025-04-16
+
+    class << self
+      # Set a default Kubernetes version for bare lookups like Kube::Schema["Deployment"].
+      # When nil, the latest version found in the schemas directory is used.
+      attr_accessor :schema_version
+
+      # Kube::Schema["1.33.6"]       => cached Instance (supports ["Deployment"] chaining)
+      # Kube::Schema["Deployment"]   => Resource via the default version
+      # Kube::Schema["apps/v1/Deployment"] => Resource via the default version
+      def [](key)
+        is_a_version = -> (key) { Gem::Version.correct?(key) }
+
+        if key.start_with?("v") && Gem::Version.correct?(key.sub("v", ""))
+          raise IncorrectVersionFormat,
+            "\nDon't preface the version with a \"v\"." \
+            "\nUse Kube::Schema[\"#{key.sub("v", "")}\"] instead."
+        end
+
+        if is_a_version.(key)
+          if has_version?(key)
+            @instances[key] ||= Instance.new(key)
+          else
+            raise UnknownVersionError.new(
+              "\n#{key} is an unknown version..." +
+              "\nUse `Kube::Schema.schema_versions` to get a list."
+            )
+          end
+        else
+          Instance.new(schema_version || DEFAULT_VERSION)[key]
+        end
+      end
+
+      # Build a Resource from a hash.
+      #   Kube::Schema.parse(Kube::Schema["Deployment"].to_h) == Kube::Schema["Deployment"]
+      def parse(hash)
+        raise NotImplementedError
+      end
+
+      def schema_versions
+        @schema_versions ||=
+          Dir.glob(SCHEMA_INDEX + "/v*.txt").map do |file_path|
+            file_path.split("/").last.gsub(".txt", "")[1..-1]
+          end.sort_by { Gem::Version.new(_1) }
+      end
+
+      # The latest Kubernetes version available in the schemas directory,
+      # determined by sorting the filenames with Gem::Version.
+      def latest_version
+        schema_versions.last
+      end
+
+      def has_version?(version)
+        schema_versions.include?(version)
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kube_schema
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Nathan K
@@ -10,19 +10,19 @@ cert_chain: []
 date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '3.13'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -109,6 +109,7 @@ files:
 - ".github/workflows/update-schema-index.yml"
 - ".github/workflows/update-schemas.yml"
 - ".gitignore"
+- ".rubocop.yml"
 - AGENTS.md
 - Gemfile
 - Gemfile.lock
@@ -123,13 +124,13 @@ files:
 - bin/update-schema-index
 - flake.nix
 - kube_schema.gemspec
-- lib/kube_schema.rb
-- lib/kube_schema/instance.rb
-- lib/kube_schema/resource.rb
-- lib/kube_schema/schema_cache.rb
-- lib/kube_schema/schema_index.rb
-- lib/kube_schema/version.rb
-- lib/kube_schema/version.rb.erb
+- lib/kube/schema.rb
+- lib/kube/schema/instance.rb
+- lib/kube/schema/resource.rb
+- lib/kube/schema/schema_cache.rb
+- lib/kube/schema/schema_index.rb
+- lib/kube/schema/version.rb
+- lib/kube/schema/version.rb.erb
 homepage: https://github.com/n-at-han-k/kube_schema
 licenses:
 - Apache-2.0

data/lib/kube_schema/instance.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module KubeSchema
-  # Represents a single Kubernetes version's OpenAPI schema.
-  # Lazily loads the JSON and builds an index of group/version/kind strings
-  # mapped back to definition keys.
-  #
-  #   instance = KubeSchema::Instance.new("v1.33.6")
-  #   instance["Deployment"]
-  #   instance["apps/v1/Deployment"]
-  #   instance.list_resources  #=> sorted array of "group/version/kind" strings
-  #
-  class Instance
-    attr_reader :version
-
-    def initialize(version)
-      @resource_classes = {}
-
-      is_a_version = -> (v) { Gem::Version.correct?(v) }
-
-      if is_a_version.(version)
-        @version = version
-      else
-        raise UnknownVersionError.new(
-          "\n#{version} is an unknown version..." +
-          "\nUse `KubeSchema.schema_versions` to get a list."
-        )
-      end
-    end
-
-    # Look up a resource by full "group/version/kind" or by bare "Kind".
-    # Returns a class that inherits from KubeSchema::Resource, or nil.
-    def [](key)
-      KubeSchema::SchemaIndex.new(version).find(key.downcase).then do |path|
-        if path.nil?
-          raise "No resource schema found for #{key}!!!!!!!"
-        else
-          @resource_classes[key] ||= begin
-            #schema_hash = @data["definitions"][key]
-            Class.new(::KubeSchema::Resource) do
-              #@schema = schema_hash
-
-              #def self.schema
-              #  @schema || superclass.schema
-              #end
-            end
-          end
-        end
-      end
-    end
-  end
-end