hub_kernel-api 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db1ce3a434c4f5c216ee183a431c31b983481255e1b277d74b061e9c6fbd57bd
-  data.tar.gz: 2e70a8aa06c9602d9b30cc9b9946bd432b5f58fefb54368e05829f4f4b20f66d
+  metadata.gz: d449e53f3b0c99bed3034c73374ef10b6136d6c6043b086ac0521b893dc47fac
+  data.tar.gz: eafda1fe30594c65ad7dcc7d79c5b13c57886c394ca0bb697951a49de7f6a9fb
 SHA512:
-  metadata.gz: d872502bd39dd53ccad7391f327c1184aad52334ee0779d6f1491d1fb336118d0f0ee34f93164f70c0dda48a480b890173a46c500ef0731971ecb41ee4b79793
-  data.tar.gz: 5c372f040e56f64de05b83f1752928083105cfae076c20dd1ad09850152a990d918698e51cdd20c55c6495bc8890f79ec4b59557e2561306dc0dcae28a3cc162
+  metadata.gz: cef4c91d77d71525529b67f6c41b333867fe5cbc9e2653d138c024c984ff603da50a69bf9ab22eec86a3f8c0d0c8bb5495f0223f26bef55f7153d109c68c85c9
+  data.tar.gz: 589cb4b0125b5289c5e1f1e28043b9bb456d924933b6309ea6493448e9bb57509b1bf92b16b561551b40a36ed3a61fdf9746aa9a1b7eb00580619855935f6146

data/README.md

@@ -29,8 +29,9 @@ JSON API's own setting is used when it is set.
 
 `HubKernel::Api.check!` raises `HubKernel::Api::UnservableHubError` when a served entry
 exposes no methods, when two served hubs answer at the same address, or when a served
-hub's exposed list has a problem, naming each. Inside `to_prepare` it runs again after
-every code reload.
+hub's exposed list has a problem, naming each. It also names each mistake in the host's
+versions, as [Versions](#versions) describes, in the same error, so every problem is named
+at once. Inside `to_prepare` it runs again after every code reload.
 
 `HubKernel::Api.hubs` reads and writes hub_kernel-interface's one served list,
 `HubKernel::Interface.hubs`, so every interface gem in the host, such as hub_kernel-mcp,
@@ -73,6 +74,234 @@ is shown nothing.
 | A permitted call sends a value the method is not listed with | 422 | `{"error": "<method> does not take <values>"}` |
 | A record the call names does not exist | 404 | `{"error": "No <record> has the id <id>"}` |
 
+## Versions
+
+A host lists the major versions it serves, each by its full version in major.minor.patch
+form. The major is the first part of that version:
+
+```ruby
+HubKernel::Api.versions = [
+  HubKernel::Api::MajorVersion.new(version: "1.4.0"),
+  HubKernel::Api::MajorVersion.new(version: "2.0.1")
+]
+```
+
+A host marks a major it no longer serves retired, and keeps it listed:
+
+```ruby
+HubKernel::Api::MajorVersion.new(version: "1.4.0", retired: true)
+```
+
+A method answers at the same address at every major. A caller names the major it was built
+for in an `Accept-Version` request header, such as `Accept-Version: 1`. A call that sends no
+`Accept-Version` header is answered at the oldest major listed that is not retired.
+
+A hub method answers in the newest major's shape. A method whose answer changed in a newer
+major declares its earlier answers with `exposes`, as hub_kernel-interface's readme
+describes:
+
+```ruby
+exposes :shelf_of, takes: %i[item], writes: false, earlier_answers: {
+  1 => ->(answer) { answer.transform_keys(aisle: :shelf) }
+}
+```
+
+A call naming an older major answers with the method's answer passed through each earlier
+answer the method declares for the majors from the newest down to the one named, newest
+first. A call naming the newest major answers with the method's own answer.
+
+Every answer at a listed major, including a hub listing and a hub's refusal, carries an
+`Api-Version` header giving the full version it was answered at. Every answer, including
+the refusal below, carries a `Vary: Accept-Version` header.
+
+A host marks a major it still serves but plans to stop serving deprecated, and gives the
+date it was deprecated and the date it stops being served:
+
+```ruby
+HubKernel::Api::MajorVersion.new(version: "1.4.0", deprecated: true, deprecated_on: Date.new(2026, 9, 30), sunset: Date.new(2027, 3, 31))
+```
+
+Every answer at a major older than the newest listed carries an `Api-Newest-Version` header
+giving the newest major's full version. Every answer at a deprecated major also carries a
+`Deprecation` header giving the date it was deprecated as `@` and the Unix seconds of that
+date's midnight UTC, as RFC 9745 defines it, and a `Sunset` header giving the date it stops
+being served as an HTTP date:
+
+```
+Api-Version: 1.4.0
+Api-Newest-Version: 2.0.1
+Deprecation: @1790726400
+Sunset: Wed, 31 Mar 2027 00:00:00 GMT
+```
+
+An answer at the newest
+major carries no `Api-Newest-Version` header, and carries no `Deprecation` or `Sunset`
+header unless the newest major is itself deprecated. The headers never change an answer's
+body.
+
+A call naming a major the host does not list is answered with status 406 and no
+`Api-Version` header. The controller raises `HubKernel::Api::UnservedMajorError` and
+renders its message, which names every listed major that is not retired:
+
+```json
+{ "error": "Major 7 is not served, the majors served are 1 and 2" }
+```
+
+A call or a listing naming a retired major is answered with status 410 and no
+`Api-Version` header, whether or not the hub it names is served. The controller raises
+`HubKernel::Api::RetiredMajorError` and renders its message:
+
+```json
+{ "error": "Major 1 is no longer served, the newest major is 2" }
+```
+
+A host that lists no majors ignores any `Accept-Version` header, answers every call with
+the method's own answer, and sends no version headers.
+
+`HubKernel::Api.check!` refuses to start a host whose versions hold a mistake, and names
+each of these:
+
+- An earlier answer declared for a major the host does not list.
+- An earlier answer declared for the newest major, which has no newer answer to translate
+  from.
+- A listed version not a string in major.minor.patch form, such as `"2.1"` or the number
+  `2`.
+- A major listed more than once.
+- A deprecated major with no `deprecated_on:` date or no `sunset:` date.
+- A `deprecated_on:` or `sunset:` date given as something other than a `Date`.
+- A version list in which every major is retired, since a call with no `Accept-Version`
+  header would have no major to be answered at.
+
+```
+Major 1 is deprecated with no sunset: date it stops being served
+Supplies declares an earlier answer to shelf_of for major 3, the newest major, which has no newer answer to translate from
+```
+
+A host that lists no majors has none of these checked.
+
+## Answer shapes
+
+A method can declare the JSON Schema of its answer, and each earlier answer can declare
+the shape of the answer at its major, with `exposes` as hub_kernel-interface's readme
+describes:
+
+```ruby
+exposes :shelf_of, takes: %i[item], writes: false, answer_shape: { "type" => "object", "required" => [ "aisle" ] }, earlier_answers: {
+  1 => { translation: ->(answer) { answer.transform_keys(aisle: :shelf) }, answer_shape: { "type" => "object", "required" => [ "shelf" ] } }
+}
+```
+
+A hub listing, `/<hub>`, gives each method's `answer_shape` at the major the caller names
+in `Accept-Version`, or at the oldest major listed that is not retired when it names none:
+
+```json
+[{ "name": "shelf_of", "takes": ["item"], "verb": "GET", "answer_shape": { "type": "object", "required": ["shelf"] } }]
+```
+
+A method's shape at the newest major is its own `answer_shape`. Its shape at an older major
+is the shape of the earlier answer declared for that major, or else its shape at the major
+after it. A method with no declared shape at that major, including one whose earlier answer
+for it declares none, is listed with no `answer_shape` key. A host that lists no majors
+lists each method's own shape.
+
+A GET at the API's root address, `/`, lists every served hub's methods the caller may call,
+keyed by the hub's address, each as a hub listing gives it, together with the full version
+of the major it describes:
+
+```json
+{ "version": "1.4.0", "hubs": { "supplies": [{ "name": "shelf_of", "takes": ["item"], "verb": "GET", "answer_shape": { "type": "object", "required": ["shelf"] } }] } }
+```
+
+A host that lists no majors gives no `version` key. The root address listing refuses a
+major the host does not list with status 406 and a retired major with status 410, as a call
+does.
+
+## Description files
+
+A host writes one JSON description file for each major it lists that is not retired:
+
+```sh
+bin/rails hub_kernel_api:describe
+```
+
+The task writes each major's file into the host's `api_descriptions` folder, named after
+the major, such as `api_descriptions/v1.json`. A file gives the major's full version and
+every served hub's methods, keyed by the hub's address, each with its values, its verb and
+its answer shape at that major, as the root address listing gives them:
+
+```json
+{ "version": "1.4.0", "hubs": { "supplies": [{ "name": "shelf_of", "takes": ["item"], "verb": "GET", "answer_shape": { "type": "object", "required": ["shelf"] } }] } }
+```
+
+Unlike a listing, a file holds every served method, whatever any caller may call, and it
+is written without a request, so it names no caller. Running the task again with no change
+to any hub writes identical files, so the host can commit them. A client repo copies a
+major's file in and checks a recorded answer against a method's `answer_shape` with a JSON
+Schema library, without reaching a running host. The task writes no file for a retired
+major, and a host that lists no majors writes no files.
+
+### Checking for breaking changes
+
+A host's CI compares each major's current description with its committed file:
+
+```sh
+bin/rails hub_kernel_api:check_descriptions
+```
+
+The task raises `HubKernel::Api::BreakingChangeError`, naming every problem at once, when a
+major that is not retired and already has a committed file breaks it in either of two ways:
+
+- Its current description no longer holds something the file holds: a hub, a method, a
+  value the method takes, its verb, or a key or value in its answer shape. A rename shows
+  as the old name removed. An object in a list that has no `name` key, such as a choice
+  in an `anyOf`, is matched by its position in the list.
+- Its current description adds something the file does not hold, and the minor of its full
+  version is not higher than the minor in the file.
+
+```
+Major 2 removes or renames supplies.shelf_of.answer_shape.required.shelf, which its committed file holds
+Major 2 adds supplies.shelf_of.takes.size without raising its minor above 2.1.0
+```
+
+A change that keeps every key and value but changes what a value means passes. A retired
+major's file is not compared, and a major with no committed file has nothing to compare.
+Once a major only adds and its minor is raised, the check passes and
+`bin/rails hub_kernel_api:describe` rewrites its file. The describe task refuses to write
+any file while the check would fail, raising the same error naming each problem.
+
+## Testing an answer against its shape
+
+A call never checks its answer against a declared shape, so a shape can stop describing what
+its method answers. A host's test catches that with `assert_answer_shape`, which needs the
+json_schemer gem in the host's test group:
+
+```ruby
+group :test do
+  gem "json_schemer"
+end
+```
+
+```ruby
+require "hub_kernel/api/test_helper"
+
+class SuppliesShapeTest < ActiveSupport::TestCase
+  include HubKernel::Api::TestHelper
+
+  test "shelf_of answers in its shape at major 1" do
+    assert_answer_shape(Supplies, :shelf_of, Supplies.shelf_of(item: "flour"), major: 1)
+  end
+end
+```
+
+The assertion takes the hub, the method's name, the method's own answer and a major the
+host lists. It translates the answer down to that major through the earlier answers the hub
+declares, as a call does, and checks it against the method's shape at that major, as a hub
+listing gives it. A failing assertion names the method and the major, then each place the
+answer differs from the shape, one to a line. It also fails naming the major and the method
+when the host lists no such major, or when the method declares no shape at it. Used without
+json_schemer installed, it raises a `LoadError` naming the gem to add. hub_kernel-api loads
+json_schemer only when the assertion runs, so a host without it still loads the gem.
+
 ## Installation
 
 ```ruby

data/app/controllers/hub_kernel/api/hub_calls_controller.rb

@@ -10,13 +10,19 @@ module HubKernel
         raise ActionController::RoutingError, "Not found" unless asked_with_the_right_verb?
 
         HubKernel::Interface::CallReasons.refuse_unlisted_values(hub, params[:name], values: values, person: caller_person, account: caller_account)
-        render json: { answer: hub.call_exposed(params[:name], values: values, person: caller_person, account: caller_account) }
+        render json: { answer: at_major(hub.call_exposed(params[:name], values: values, person: caller_person, account: caller_account)) }
       end
 
       private
 
       def asked_with_the_right_verb? = hub.exposed(params[:name])&.writes == request.post?
 
+      def at_major(answer)
+        return answer if HubKernel::Api.versions.empty?
+
+        HubKernel::Api::EarlierAnswers.translate(answer, hub.exposed(params[:name]), major)
+      end
+
       def values = request.query_parameters.merge(request.request_parameters).deep_symbolize_keys
 
       def refused(refusal) = render(json: { error: refusal.message }, status: :unprocessable_content)

data/app/controllers/hub_kernel/api/hub_controller.rb

@@ -1,17 +1,61 @@
+require "date"
+require "active_support/core_ext/array/conversions"
+
 module HubKernel
   module Api
     class HubController < HubKernel::Api.base_controller.constantize
       rescue_from ActionController::RoutingError, HubKernel::NotAllowed, with: :not_found
+      rescue_from HubKernel::Api::UnservedMajorError, with: :unserved_major
+      rescue_from HubKernel::Api::RetiredMajorError, with: :retired_major
+
+      before_action :report_major, if: -> { HubKernel::Api.versions.any? }
 
       private
 
       def hub = @hub ||= HubKernel::Api.find(params[:hub]) || raise(ActionController::RoutingError, "Not found")
 
+      def major = @major ||= named_version ? named_major : HubKernel::Api.versions.reject(&:retired?).min_by(&:major)
+
+      def named_version = request.headers["Accept-Version"]
+
+      def named_major
+        listed = HubKernel::Api.versions.find { |version| version.major.to_s == named_version } || raise(HubKernel::Api::UnservedMajorError, "Major #{named_version} is not served, the majors served are #{served_majors}")
+        raise HubKernel::Api::RetiredMajorError, "Major #{named_version} is no longer served, the newest major is #{newest_major}" if listed.retired?
+
+        listed
+      end
+
+      def newest = HubKernel::Api.versions.max_by(&:major)
+
+      def newest_major = newest.major
+
+      def served_majors = HubKernel::Api.versions.reject(&:retired?).map(&:major).to_sentence(last_word_connector: " and ")
+
+      def report_major
+        response.headers["Vary"] = "Accept-Version"
+        response.headers["Api-Version"] = major.version
+        response.headers["Api-Newest-Version"] = newest.version unless major == newest
+        report_deprecation if major.deprecated?
+      end
+
+      def report_deprecation
+        response.headers["Deprecation"] = "@#{Time.utc(major.deprecated_on.year, major.deprecated_on.month, major.deprecated_on.day).to_i}" if major.deprecated_on
+        response.headers["Sunset"] = major.sunset.httpdate if major.sunset
+      end
+
+      def listing_of(hub) = hub.exposures_for(person: caller_person, account: caller_account).map { |exposure| HubKernel::Api::Description.described(exposure, listed_major) }
+
+      def listed_major = (major if HubKernel::Api.versions.any?)
+
       def caller_person = send(HubKernel::Api.person_method || HubKernel::Interface.person_method)
 
       def caller_account = send(HubKernel::Api.account_method || HubKernel::Interface.account_method)
 
       def not_found = render(json: { error: "Not found" }, status: :not_found)
+
+      def unserved_major(refusal) = render(json: { error: refusal.message }, status: :not_acceptable)
+
+      def retired_major(refusal) = render(json: { error: refusal.message }, status: :gone)
     end
   end
 end

data/app/controllers/hub_kernel/api/hubs_controller.rb

@@ -2,12 +2,8 @@ module HubKernel
   module Api
     class HubsController < HubController
       def show
-        render json: hub.exposures_for(person: caller_person, account: caller_account).map { |exposure| listed(exposure) }
+        render json: listing_of(hub)
       end
-
-      private
-
-      def listed(exposure) = { name: exposure.name, takes: exposure.takes, verb: exposure.writes ? "POST" : "GET" }
     end
   end
 end

data/app/controllers/hub_kernel/api/versions_controller.rb

@@ -0,0 +1,15 @@
+module HubKernel
+  module Api
+    class VersionsController < HubController
+      def show
+        render json: { version: described_version, hubs: HubKernel::Interface.served.transform_values { |served| listing_of(served) } }.compact
+      end
+
+      private
+
+      def described_version
+        major.version if HubKernel::Api.versions.any?
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -1,4 +1,5 @@
 HubKernel::Api::Engine.routes.draw do
+  get "/", to: "versions#show"
   get ":hub", to: "hubs#show"
   match ":hub/:name", to: "hub_calls#answer", via: [ :get, :post ]
 end

data/lib/hub_kernel/api/description.rb

@@ -0,0 +1,17 @@
+module HubKernel
+  module Api
+    module Description
+      def self.at(major) = { version: major.version, hubs: HubKernel::Interface.served.transform_values { |hub| hub.exposures.map { |exposure| described(exposure, major) } } }
+
+      def self.described(exposure, major) = { name: exposure.name, takes: exposure.takes, verb: exposure.writes ? "POST" : "GET", answer_shape: answer_shape_at(exposure, major) }.compact
+
+      def self.answer_shape_at(exposure, major)
+        return exposure.answer_shape if major.nil?
+
+        (exposure.earlier_answers.select { |earlier| earlier.major >= major.major }.min_by(&:major) || exposure).answer_shape
+      end
+
+      private_class_method :answer_shape_at
+    end
+  end
+end

data/lib/hub_kernel/api/description_check.rb

@@ -0,0 +1,54 @@
+require "json"
+
+module HubKernel
+  module Api
+    class BreakingChangeError < StandardError; end
+
+    module DescriptionCheck
+      def self.check!(directory)
+        problems = removals(directory) + unraised_additions(directory)
+        raise BreakingChangeError, problems.join("\n") if problems.any?
+      end
+
+      def self.removals(directory)
+        committed_majors(directory).flat_map do |major|
+          missing(keyed(committed_hubs(directory, major)), keyed(current_hubs(major))).map { |path| "Major #{major.major} removes or renames #{path.join(".")}, which its committed file holds" }
+        end
+      end
+
+      def self.unraised_additions(directory)
+        committed_majors(directory).reject { |major| minor(major.version) > minor(committed(directory, major)["version"]) }.flat_map do |major|
+          missing(keyed(current_hubs(major)), keyed(committed_hubs(directory, major))).map do |path|
+            "Major #{major.major} adds #{path.join(".")} without raising its minor above #{committed(directory, major)["version"]}"
+          end
+        end
+      end
+
+      def self.committed_majors(directory) = HubKernel::Api.versions.reject(&:retired?).select { |major| File.exist?(file(directory, major)) }
+
+      def self.file(directory, major) = File.join(directory, "v#{major.major}.json")
+
+      def self.committed(directory, major) = JSON.parse(File.read(file(directory, major)))
+
+      def self.committed_hubs(directory, major) = committed(directory, major)["hubs"]
+
+      def self.current_hubs(major) = JSON.parse(Description.at(major).to_json)["hubs"]
+
+      def self.minor(version) = version.split(".").second.to_i
+
+      def self.keyed(value)
+        case value
+        when Hash then value.transform_values { |inner| keyed(inner) }
+        when Array then value.each_with_index.to_h { |element, position| element.is_a?(Hash) ? [ element.fetch("name", position), keyed(element) ] : [ element, {} ] }
+        else { value => {} }
+        end
+      end
+
+      def self.missing(held, current, path = [])
+        held.flat_map { |key, inner| current.key?(key) ? missing(inner, current[key], path + [ key ]) : [ path + [ key ] ] }
+      end
+
+      private_class_method :unraised_additions, :committed_majors, :file, :committed, :committed_hubs, :current_hubs, :minor, :keyed, :missing
+    end
+  end
+end

data/lib/hub_kernel/api/description_files.rb

@@ -0,0 +1,13 @@
+require "json"
+
+module HubKernel
+  module Api
+    module DescriptionFiles
+      def self.write(directory)
+        DescriptionCheck.check!(directory)
+
+        HubKernel::Api.versions.reject(&:retired?).each { |major| File.write(File.join(directory, "v#{major.major}.json"), JSON.pretty_generate(Description.at(major))) }
+      end
+    end
+  end
+end

data/lib/hub_kernel/api/earlier_answers.rb

@@ -0,0 +1,11 @@
+module HubKernel
+  module Api
+    module EarlierAnswers
+      def self.translate(answer, exposure, major) = down_to(exposure, major).reduce(answer) { |translated, earlier| earlier.translate(translated) }
+
+      def self.down_to(exposure, major) = exposure.earlier_answers.select { |earlier| earlier.major >= major.major }.sort_by(&:major).reverse
+
+      private_class_method :down_to
+    end
+  end
+end

data/lib/hub_kernel/api/major_version.rb

@@ -0,0 +1,13 @@
+module HubKernel
+  module Api
+    MajorVersion = Data.define(:version, :retired, :deprecated, :deprecated_on, :sunset) do
+      def initialize(version:, retired: false, deprecated: false, deprecated_on: nil, sunset: nil) = super
+
+      def major = version.split(".").first.to_i
+
+      def retired? = retired
+
+      def deprecated? = deprecated
+    end
+  end
+end

data/lib/hub_kernel/api/test_helper.rb

@@ -0,0 +1,24 @@
+module HubKernel
+  module Api
+    module TestHelper
+      def assert_answer_shape(hub, name, answer, major:)
+        require_json_schemer
+
+        exposure = hub.exposed(name)
+        listed = HubKernel::Api.versions.find { |version| version.major == major } || flunk("The host lists no major #{major} to check #{name} at")
+        declared = HubKernel::Api::Description.described(exposure, listed)[:answer_shape] || flunk("#{name} declares no answer shape at major #{major}")
+        shape = JSONSchemer.schema(declared)
+        differences = shape.validate(HubKernel::Api::EarlierAnswers.translate(answer, exposure, listed)).map { |difference| difference["error"] }
+        assert differences.empty?, [ "The answer to #{name} at major #{major} does not match its shape", *differences ].join("\n")
+      end
+
+      private
+
+      def require_json_schemer
+        require "json_schemer"
+      rescue LoadError
+        raise LoadError, 'assert_answer_shape needs the json_schemer gem, add gem "json_schemer" to the test group of your Gemfile'
+      end
+    end
+  end
+end

data/lib/hub_kernel/api/version.rb

@@ -1,5 +1,5 @@
 module HubKernel
   module Api
-    VERSION = "0.9.0"
+    VERSION = "0.10.0"
   end
 end

data/lib/hub_kernel/api.rb

@@ -1,14 +1,23 @@
+require "date"
 require "hub_kernel-interface"
 require "hub_kernel/api/version"
+require "hub_kernel/api/major_version"
+require "hub_kernel/api/earlier_answers"
+require "hub_kernel/api/description"
+require "hub_kernel/api/description_files"
+require "hub_kernel/api/description_check"
 require "hub_kernel/api/engine"
 
 module HubKernel
   module Api
     UnservableHubError = HubKernel::Interface::UnservableHubError
+    class UnservedMajorError < StandardError; end
+    class RetiredMajorError < StandardError; end
 
     mattr_accessor :base_controller, default: "ActionController::API"
     mattr_accessor :person_method
     mattr_accessor :account_method
+    mattr_accessor :versions, default: []
 
     def self.hubs = HubKernel::Interface.hubs
 
@@ -18,6 +27,68 @@ module HubKernel
 
     def self.find(name) = HubKernel::Interface.find(name)
 
-    def self.check! = HubKernel::Interface.check!
+    def self.check!
+      problems = served_list_problems + version_problems
+      raise UnservableHubError, problems.join("\n") if problems.any?
+    end
+
+    def self.version_problems
+      return [] if versions.empty?
+
+      unlisted_earlier_answers + newest_earlier_answers + unformed_versions + doubled_majors + undated(:deprecated_on, "it was deprecated") + undated(:sunset, "it stops being served") +
+        non_dates(:deprecated_on) + non_dates(:sunset) + all_retired
+    end
+
+    def self.served_list_problems
+      HubKernel::Interface.check!
+      []
+    rescue UnservableHubError => error
+      error.message.split("\n")
+    end
+
+    def self.unlisted_earlier_answers
+      earlier_answers.reject { |_hub, _exposure, earlier| formed_versions.map(&:major).include?(earlier.major) }.map do |hub, exposure, earlier|
+        "#{hub.name} declares an earlier answer to #{exposure.name} for major #{earlier.major}, which the host does not list"
+      end
+    end
+
+    def self.newest_earlier_answers
+      earlier_answers.select { |_hub, _exposure, earlier| earlier.major == formed_versions.map(&:major).max }.map do |hub, exposure, earlier|
+        "#{hub.name} declares an earlier answer to #{exposure.name} for major #{earlier.major}, the newest major, which has no newer answer to translate from"
+      end
+    end
+
+    def self.unformed_versions
+      (versions - formed_versions).map { |listed| "The listed version #{listed.version} is not in major.minor.patch form" }
+    end
+
+    def self.formed_versions = versions.select { |listed| listed.version.to_s.match?(/\A\d+\.\d+\.\d+\z/) }
+
+    def self.doubled_majors
+      formed_versions.group_by(&:major).select { |_major, listed| listed.size > 1 }.keys.map { |major| "Major #{major} is listed more than once" }
+    end
+
+    def self.undated(field, meaning)
+      formed_versions.select { |listed| listed.deprecated? && listed.public_send(field).nil? }.map { |listed| "Major #{listed.major} is deprecated with no #{field}: date #{meaning}" }
+    end
+
+    def self.all_retired
+      return [] unless versions.all?(&:retired?)
+
+      [ "Every listed major is retired, so a call with no Accept-Version has no major to be answered at" ]
+    end
+
+    def self.non_dates(field)
+      formed_versions.reject { |listed| listed.public_send(field).nil? || listed.public_send(field).is_a?(Date) }.map do |listed|
+        "Major #{listed.major} gives #{field}: as #{listed.public_send(field).inspect}, which is not a Date"
+      end
+    end
+
+    def self.earlier_answers
+      exposing_hubs.flat_map { |hub| hub.exposures.flat_map { |exposure| exposure.earlier_answers.map { |earlier| [ hub, exposure, earlier ] } } }
+    end
+
+    def self.exposing_hubs = HubKernel::Interface.served.values.uniq.select { |hub| hub.respond_to?(:exposures) }
+    private_class_method :served_list_problems, :version_problems, :unlisted_earlier_answers, :newest_earlier_answers, :unformed_versions, :formed_versions, :doubled_majors, :undated, :all_retired, :non_dates, :earlier_answers, :exposing_hubs
   end
 end

data/lib/tasks/hub_kernel_api.rake

@@ -0,0 +1,14 @@
+require "fileutils"
+
+namespace :hub_kernel_api do
+  desc "Write one JSON description file for each listed major that is not retired into the api_descriptions folder, refusing while a major removes or renames something its committed file holds, or adds something without raising its minor"
+  task describe: :environment do
+    FileUtils.mkdir_p(Rails.root.join("api_descriptions"))
+    HubKernel::Api::DescriptionFiles.write(Rails.root.join("api_descriptions"))
+  end
+
+  desc "Fail when a listed major that is not retired removes or renames something its committed file in the api_descriptions folder holds, or adds something without raising its minor"
+  task check_descriptions: :environment do
+    HubKernel::Api::DescriptionCheck.check!(Rails.root.join("api_descriptions"))
+  end
+end