kube_schema 1.11.0 → 2.0.0

data/CHANGELOG.md

@@ -4,7 +4,132 @@ All notable changes to this project are documented here.
 
 This file starts at 1.10.0; for earlier releases see the git history.
 
-## [1.11.0]
+## [Unreleased]
+
+## [2.0.0] - 2026-10-17
+
+### Added
+
+- `require "kube_schema"` now works alongside `require "kube/schema"`.
+  `lib/kube_schema.rb` is a new entry point that loads the library;
+  `Kube::Schema::VERSION` is unchanged.
+
+- `Kube::Schema::Lazy` — `Scanner` (byte-offset index over the schema files),
+  `Index`/`Entry`, `Spill` (temp-file backing for registered schemas), and
+  `Source`, which stands in for a compiled schema: it answers `#value`,
+  `#valid?`, `#validate` and `#ref`, loading the definition for property names
+  and compiling behind a `WeakRef` so repeated validations reuse a live schema
+  while the GC can still reclaim it.
+
+- `Kube::MissingSchemaError`, raised when a definition cannot be read at
+  validation time. A vanished spilled temp file says so explicitly, since that
+  means the `Tempfile` was collected or the tmpdir swept, rather than the
+  install being broken.
+
+### Changed
+
+- **Schemas are compiled per definition, on demand, and collected afterwards.**
+  `Instance#schemer` used to parse `v<version>.json`, merge every
+  `*-definitions.json` into it, and hand the whole document to
+  `JSONSchemer.schema` — one compiled tree held at the class level for the
+  life of the process. That tree was **97,381 `JSONSchemer::Schema` nodes and
+  ~406 MB resident** (one `JSONSchemer::Configuration` per node, plus ~230k
+  vocabulary keyword objects and 1.2M hashes), built in full whether you
+  validated one resource or none.
+
+  Validating a Deployment through the public API now looks like this:
+
+      baseline                        rss=  26.8 MB  schemas=     0
+      Instance.new("1.33")            rss=  26.8 MB  schemas=     0
+      instance["Deployment"]          rss=  68.5 MB  schemas=     0
+      Deployment.new(...)             rss=  68.5 MB  schemas=     0
+      after valid?                    rss=  68.5 MB  schemas=   147
+      after GC.start                  rss=  42.4 MB  schemas=    16
+
+  Nothing is compiled until something is validated, a Deployment needs 147
+  schema nodes rather than 97,381, and they are collectable the moment the
+  validation is done — about **90% less memory** than before.
+
+  This works because `json_schemer` resolves `$ref` lazily:
+  `Draft202012::Vocab::Core::Ref#ref_schema` is memoized inside `#validate`,
+  and an unresolved URI goes through `ref_resolver`. So a single definition is
+  compiled as its own root, its `#/definitions/...` pointers are rewritten to
+  `kube:///<key>`, and a resolver loads referenced definitions on demand —
+  which means the cost scales with the instance being validated, not with the
+  size of the schema document.
+
+- **`Kube::Schema.register` no longer compiles the registered schema.** It
+  writes the definition to a temp file and stores an index entry, so a
+  registered CRD takes the same lazy path as a built-in type. Registering the
+  largest bundled CRD (1.1 MB of `io.argoproj.v1alpha1.Workflow`) now compiles
+  nothing at registration time; its 9,656 nodes appear on first `#valid?` and
+  collect afterwards. `reset_custom_schemas!` removes the temp files.
+
+- `Instance.schemers` is now `Instance.catalogs`, holding a
+  `Kube::Schema::Lazy::Index` (definition key to file offset, group/version/kind,
+  and property names) instead of a compiled schema. The index is built by
+  scanning the JSON for definition boundaries, so the schema documents are
+  never parsed whole and nothing but offsets and small metadata is retained.
+  Callers that reached into `Instance.schemers` must update to `Instance.catalogs`
+  and expect a `Lazy::Index`, not a `JSONSchemer::Schema`.
+
+- **The version constant file moved to `lib/kube_schema/version.rb`** from
+  `lib/kube/schema/version.rb`. `gem kit bump` derives the path from the gem's
+  name and rewrites the literal in place, so the `version.rb.erb` template is
+  gone. External code that `require`d `kube/schema/version` directly must now
+  `require "kube_schema/version"`; the `Kube::Schema::VERSION` constant itself
+  is unchanged.
+
+- **Releases run on `gem kit`, not on `bin/*`.** `bin/increment-version`,
+  `bin/release-gem` and `bin/tag-version` are gone, replaced by the
+  [gem_kit-release](https://github.com/n-at-han-k/gem_kit) RubyGems plugin:
+  `gem kit bump`, `gem kit changelog`, `gem kit release` and `gem kit tag`.
+  The three scripts between them bumped the version, compared it against
+  RubyGems, built, pushed and tagged. What they never did was check that the
+  release was documented or that promises made about it had been kept, and
+  `gem kit` refuses to build without both — see [RELEASE.md](RELEASE.md) and
+  [DEPRECATIONS.md](DEPRECATIONS.md), which are now in the repository.
+
+  `gem_kit` is a new runtime dependency, so a deprecation can be *declared*
+  (`GemKit::Deprecate`) where the deprecated name lives; it has no
+  dependencies of its own beyond RubyGems'. `gem_kit-release`, which does the
+  enforcing, is in the `release` bundle group and is nobody's dependency.
+
+- **Tests run on [scampi](https://github.com/general-intelligence-systems/scampi)
+  instead of RSpec.** The co-located specs moved out of
+  `if __FILE__ == $0` blocks and into each file's `__END__` section, so they no
+  longer load in production — Ruby stops parsing at `__END__`. `bin/test` is now
+  `bundle exec scampi`, which discovers every `.rb` carrying an `__END__` spec
+  section and emits TAP version 14. The assertions are scampi's `should` chain
+  rather than `expect`, and the devshell gained `ripgrep`, which scampi shells
+  out to for discovery.
+
+### Removed
+
+- `bin/increment-version`, `bin/release-gem` and `bin/tag-version`. Use
+  `gem kit bump`, `gem kit release` and `gem kit tag` instead.
+- `lib/kube/schema/version.rb.erb`. `gem kit bump` edits the version literal
+  in `lib/kube_schema/version.rb` directly.
+
+## [1.12.0] - 2026-09-28
+
+### Added
+
+- Ruby pattern matching support. `Resource#deconstruct_keys` exposes `to_h`,
+  so resources match against hash patterns all the way down; `Manifest#deconstruct`
+  exposes the resource array, so manifests match against array patterns.
+
+      resource => {metadata: {name:}}
+
+      Deployment = Kube::Schema["Deployment"]
+      manifest => [Deployment => dep, *rest]
+
+  Note that `Kube::Schema["Deployment"]` cannot be written inline in a pattern:
+  Ruby parses `Const[...]` as array-pattern syntax, not a method call. Assign
+  the class to a constant, or use a pin expression —
+  `^(Kube::Schema["Deployment"])`.
+
+## [1.11.0] - 2026-09-17
 
 ### Added
 
@@ -15,7 +140,7 @@ This file starts at 1.10.0; for earlier releases see the git history.
   from core resource/subresource strings — e.g. building RBAC rules — without
   hardcoding a group list.
 
-## [1.10.0]
+## [1.10.0] - 2026-08-03
 
 ### Added
 

data/DEPRECATIONS.md

@@ -0,0 +1,172 @@
+# Deprecations
+
+A deprecation in kube_schema is a **dated promise**: it names the replacement
+*and* the version the old name stops existing in. That promise is
+machine-readable — every declaration registers itself, and the release tooling
+refuses to ship a version that breaks one.
+
+The mechanism is [`GemKit::Deprecate`](https://rubygems.org/gems/gem_kit),
+built on [`Gem::Deprecate`](https://docs.ruby-lang.org/en/master/Gem/Deprecate.html).
+
+## The rules
+
+1. **Never delete a public name outright.** Leave it working, deprecated, until
+   its deadline.
+2. **Every deprecation names a removal version.** The current version is 2.0.0, so the usual deadline is 3.0.
+3. **Removals happen in major versions only.** A minor or patch release never
+   takes a name away.
+4. **The deadline is enforced, not remembered.** `gem kit bump` and `gem kit release`
+   both refuse to move to a version that has a deprecation coming due.
+5. **Deprecating something is a changelog entry** — under `### Deprecated`,
+   naming the replacement and the removal version.
+
+## Deprecating a method
+
+```ruby
+class Session
+  extend GemKit::Deprecate
+
+  def new_reset
+    # ...
+  end
+
+  def old_reset = new_reset
+
+  deprecate :old_reset, "Session#new_reset", "3.0"
+end
+```
+
+The old method keeps working and warns on every call, naming the caller:
+
+```
+NOTE: Session#old_reset is deprecated; use Session#new_reset instead.
+It will be removed in 3.0
+Session#old_reset called from app.rb:12.
+```
+
+Use `:none` as the replacement when there genuinely isn't one:
+
+```ruby
+deprecate :old_reset, :none, "3.0"
+```
+
+For a class method, follow the `Gem::Deprecate` idiom — the registry records it
+against the class, not its singleton:
+
+```ruby
+class << self
+  extend GemKit::Deprecate
+  deprecate :some_class_method, "Other.method", "3.0"
+end
+```
+
+## Deprecating a renamed or moved constant
+
+Keep the old constant as a subclass of the new one and declare the rename in
+its body:
+
+```ruby
+module Old
+  class Thing < New::Thing
+    extend GemKit::Deprecate
+    superseded_by "New::Thing", "3.0"
+  end
+end
+```
+
+Old code keeps running unchanged; instantiating the old name warns and points at
+the new one. The whole shim is those four lines — the implementation lives in
+one place.
+
+It is `superseded_by` rather than `deprecate_constant` because `Module` already
+has a method by that name, and shadowing it would break callers who use it.
+
+## Finding what is outstanding
+
+```sh
+gem kit deprecations
+```
+
+```
+1 outstanding deprecation(s) (current version 2.0.0):
+  3.0      Session#old_reset -> Session#new_reset
+           lib/session.rb:19
+```
+
+Pass a version to ask "what comes due here?" — it exits non-zero if anything
+does, which is what makes it usable as a gate in CI:
+
+```sh
+gem kit deprecations 3.0.0
+```
+
+Programmatically, the same data:
+
+```ruby
+GemKit::Deprecate.registry                  # every declaration
+GemKit::Deprecate.pending("3.0.0")   # deadlines that have arrived
+GemKit::Deprecate.upcoming("3.0.0")  # still in their grace period
+```
+
+Each entry carries `name`, `replacement`, `removed_in` and `declared_at`.
+
+## Paying the debt
+
+When a major version comes around, the bump is blocked until the deprecated
+code is actually gone:
+
+```
+$ gem kit bump major
+ERROR:  Refusing to bump 2.0.0 -> 3.0.0:
+
+  3.0      Session#old_reset -> Session#new_reset
+           lib/session.rb:19
+
+  Remove them, then bump. Override with --force.
+```
+
+So the order of work is:
+
+1. `gem kit deprecations 3.0.0` — read the list.
+2. Delete each deprecated name and its specs. For a constant shim, that means
+   deleting the whole file.
+3. Update anything in `examples/` and the docs still using the old name.
+4. Record the removals in `CHANGELOG.md` under `### Removed`.
+5. `gem kit bump major` — now it goes through.
+
+`--force` exists for the case where you have decided to extend a grace period,
+and it prints what it is overriding. It is not the normal path: extending a
+deadline properly means editing the declaration's version, which keeps the
+registry honest.
+
+## Testing deprecated code
+
+`Gem::Deprecate.skip_during` silences these warnings too, so a spec can
+exercise the old path without noise:
+
+```ruby
+Gem::Deprecate.skip_during do
+  legacy.old_reset
+end
+```
+
+To assert *that* something warns, stub the single funnel every warning goes
+through:
+
+```ruby
+captured = []
+original = GemKit::Deprecate.method(:warn)
+GemKit::Deprecate.define_singleton_method(:warn) { |message| captured << message }
+begin
+  legacy.old_reset
+ensure
+  GemKit::Deprecate.define_singleton_method(:warn, original)
+end
+```
+
+## See also
+
+- [RELEASE.md](RELEASE.md) — where the deprecation gates sit in the release
+  process.
+- The changelog — its `### Deprecated` and `### Removed` sections are the
+  user-facing half of all this.

data/Gemfile

@@ -2,11 +2,21 @@
 
 source "https://rubygems.org"
 
-gemspec
+gem "gem_kit", "~> 0.2"
+gem "json_schemer", "~> 2.5.0"
+gem "rubyshell", "~> 1.5.0"
+
+gem "lefthook", "~> 2.1"
+gem "rake", "~> 13.0"
+gem "scampi", "~> 1.0"
+gem "rubocop"
+gem "decode", "~> 0.27"
+
+group :release do
+	gem "gem_kit-release", "~> 0.3"
+end
 
 group :maintenance, optional: true do
 	gem "utopia-project"
-	gem "bake-gem"
 	gem "bake-modernize"
-	gem "bake-releases"
 end

data/Gemfile.lock

@@ -1,13 +1,7 @@
-PATH
-  remote: .
-  specs:
-    kube_schema (1.11.0)
-      json_schemer (~> 2.5.0)
-      rubyshell (~> 1.5.0)
-
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.3)
     async (2.39.0)
       console (~> 1.29)
       fiber-annotation
@@ -46,8 +40,6 @@ GEM
     bake (0.24.1)
       bigdecimal
       samovar (~> 2.1)
-    bake-gem (0.13.1)
-      console (~> 1.25)
     bake-modernize (0.54.1)
       async-http
       async-ollama (~> 0.10)
@@ -55,9 +47,6 @@ GEM
       build-files (~> 1.6)
       markly (~> 0.13)
       rugged
-    bake-releases (0.5.4)
-      bake (~> 0.21)
-      markly (~> 0.8)
     bigdecimal (4.1.2)
     build-files (1.10.2)
     concurrent-ruby (1.3.6)
@@ -69,7 +58,6 @@ GEM
     decode (0.27.0)
       prism
       rbs
-    diff-lcs (1.6.2)
     erb (6.0.4)
     falcon (0.55.3)
       async
@@ -88,6 +76,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)
     io-console (0.8.2)
@@ -105,7 +97,9 @@ GEM
       hana (~> 1.3)
       regexp_parser (~> 2.0)
       simpleidn (~> 0.2)
+    language_server-protocol (3.17.0.6)
     lefthook (2.1.10)
+    lint_roller (1.1.0)
     localhost (1.7.0)
     logger (1.7.0)
     mail (2.9.0)
@@ -133,6 +127,10 @@ GEM
     net-smtp (0.5.1)
       net-protocol
     openssl (4.0.1)
+    parallel (2.3.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
@@ -152,11 +150,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
@@ -169,31 +169,38 @@ GEM
     regexp_parser (2.12.0)
     reline (0.6.3)
       io-console (~> 0.5)
-    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.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)
       console (~> 1.0)
       mapping (~> 1.0)
+    scampi (1.0.0)
     simpleidn (0.2.3)
     string-format (0.2.0)
     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)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
     utopia (2.32.1)
       bake (~> 0.20)
       concurrent-ruby (~> 1.2)
@@ -226,14 +233,17 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
-  bake-gem
   bake-modernize
-  bake-releases
-  kube_schema!
+  decode (~> 0.27)
+  gem_kit (~> 0.2)
+  gem_kit-release (~> 0.3)
+  json_schemer (~> 2.5.0)
   lefthook (~> 2.1)
   rake (~> 13.0)
-  rspec (~> 3.13)
+  rubocop
+  rubyshell (~> 1.5.0)
+  scampi (~> 1.0)
   utopia-project
 
 BUNDLED WITH
-   2.6.9
+   2.7.2

data/RELEASE.md

@@ -0,0 +1,161 @@
+# Releasing kube_schema
+
+The whole process, in order:
+
+```sh
+bin/test                      # 1. green suite
+gem kit bump minor            # 2. bump  (prints what to run next)
+gem kit changelog --write     # 3. write the entry
+gem kit changelog <VERSION>   # 4. check it
+git commit -am "Release ..."  # 5. commit the bump + changelog
+gem kit release               # 6. gate, build, push, tag
+```
+
+Steps 2 and 6 are gates: they refuse to proceed when something is missing.
+Everything below is what they check and why.
+
+## Versioning
+
+kube_schema is [semver](https://semver.org/). The version lives in one place —
+`lib/kube_schema/version.rb` — and is only ever changed by `gem kit bump`.
+
+| Segment | When | What it may contain |
+| --- | --- | --- |
+| **major** | A public name disappears or changes meaning | Removals of deprecated names, breaking signature changes |
+| **minor** | New public surface, backwards compatible | New classes and methods; new deprecations |
+| **patch** | Nothing new, nothing gone | Bug fixes, docs, internals |
+
+Two rules follow from this, and both are enforced in code:
+
+- **Removals only ever land in a major version.** A name promised to disappear
+  in 3.0 disappears in 3.0.0, not in a patch.
+- **Deprecating is a minor.** Adding a deprecation puts no obligation on the
+  user *yet*, so it does not need a major — but it starts the clock. See
+  [DEPRECATIONS.md](DEPRECATIONS.md).
+
+## 1. Green suite
+
+```sh
+bin/test
+```
+
+A red suite is not a release candidate; nothing downstream checks this for you.
+
+## 2. Bump
+
+```sh
+gem kit bump <major|minor|patch>
+```
+
+Rewrites `lib/kube_schema/version.rb` — by rendering its `.erb` template if there is
+one, otherwise by substituting the version literal in place — and prints the
+transition:
+
+```
+2.0.0 -> ...
+
+now run: gem kit changelog --write
+```
+
+**It refuses to bump onto a deprecation deadline.** If any registered
+deprecation is due at the new version, it lists them with their source lines
+and fails. Remove the deprecated code first — that is the point of the promise.
+`--force` overrides and says what it overrode. Deprecations *not* yet due are
+reported for information, not blocked on.
+
+## 3. Changelog
+
+```sh
+gem kit changelog --write
+```
+
+Hands the entry to the AI CLI named by `config.changelog_writer` (default:
+`claude`), with a prompt describing the format and this project's conventions.
+It reads the commits since the last tag and edits `CHANGELOG.md` only.
+
+Review what it writes. It is a first draft with the commits in front of it, not
+an oracle — it cannot know which of two changes mattered to users.
+
+The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/):
+
+```md
+## [Unreleased]
+
+## [2.0.0] - 2026-10-17
+
+### Added
+
+- Something users can now do.
+
+### Deprecated
+
+- `Old::Name` — use `New::Name` instead. Removed in 3.0.
+```
+
+Entries go under `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed` or
+`Security` — those six and no others. `[Unreleased]` stays at the top, emptied
+of anything that shipped.
+
+## 4. Lint the changelog
+
+```sh
+gem kit changelog              # format only
+gem kit changelog 2.0.0       # format, plus "is this version ready?"
+```
+
+Checks the title, that every heading is `## [Unreleased]` or
+`## [1.2.3] - YYYY-MM-DD`, that versions are valid, dated, unique and ordered
+newest-first, that `###` sections are one of the six types and none are empty —
+and, given a version, that it has a non-empty section at the top of the released
+list. Every problem is reported as `CHANGELOG.md:<line> <what>`.
+
+## 5. Commit
+
+The version bump, the lockfile and the changelog belong in one commit, before
+anything is pushed to RubyGems. A published gem whose changelog is still
+unwritten in git is the failure this process exists to prevent.
+
+## 6. Release
+
+```sh
+gem kit release             # or --dry-run, which is the CI check
+```
+
+Three gates, all before `gem build` runs:
+
+1. **Changelog** — this version needs its own non-empty, correctly formatted
+   section, sitting at the top of the released list.
+2. **Deprecations** — nothing promised to disappear in this version may still
+   be in the tree.
+3. **The working tree** — everything committed. A gem built from uncommitted
+   files is a gem whose source exists nowhere, and step 2 and step 3 above
+   leave exactly two such files behind. `--allow-dirty` overrides it.
+
+Then `gem build`, `gem push`, and the tag — `v2.0.0`,
+created and pushed *after* the gem, so a tag never names a version that failed
+to publish. `--no-tag` skips it.
+
+Requires RubyGems push credentials.
+
+The tag matters beyond bookkeeping: it is what the next
+`gem kit changelog --write` uses to find the commit range, so a
+missing one makes the following release's changelog harder to write.
+
+`gem kit tag` still exists for tagging on its own.
+
+## When something goes wrong
+
+**Published a broken gem.** Don't delete it — `gem yank kube_schema -v X.Y.Z` if
+it is genuinely dangerous, otherwise ship a patch. Yanking a version other
+people have already locked to breaks their builds.
+
+**Bumped but the release failed.** The bump is just a file. Fix the cause and
+re-run `gem kit release`; there is no need to un-bump.
+
+**Changelog written for the wrong version.** Edit the heading and re-run
+`gem kit changelog <version>`. Nothing downstream caches it.
+
+## See also
+
+- [DEPRECATIONS.md](DEPRECATIONS.md) — the deprecation policy the gates enforce.
+- [CHANGELOG.md](CHANGELOG.md).

data/Rakefile

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 task :test do
-  Dir["lib/**/*.rb"].each { |f| sh "ruby", f }
+  sh "bundle", "exec", "scampi"
 end
 
 task default: :test

data/bin/rubocop

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

data/bin/test

@@ -1,10 +1,3 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
+#!/usr/bin/env sh
 
-Dir.chdir(File.expand_path("..", __dir__))
-
-files = ARGV.empty? ? Dir.glob("lib/**/*.rb").sort : ARGV
-
-files.each do |f|
-  system("bundle", "exec", "ruby", f, exception: true)
-end
+exec bundle exec scampi "$@"