A platform for community discussion. Free, open, simple.
DEV: Support attribute splits in JSON:API versions (#43647)
Loïc Guitauta44968f9a217
diff --git a/lib/json_api_kit/glossary.rb b/lib/json_api_kit/glossary.rbindex 947eb248020..32c739eb89a 100644--- a/lib/json_api_kit/glossary.rb+++ b/lib/json_api_kit/glossary.rb@@ -55,7 +55,7 @@ module JsonApiKitenddef declared_attributes(attributes)- attributes.each_key { declared_name(it) }+ attributes.each_key { declared_names(it) }rules.each_with_index.reduce(attributes) do |result, (rule, index)|@@ -65,8 +65,10 @@ module JsonApiKitendend- def declared_name(name)- declared_names[name] ||= declare_name(name, rules)+ def declared_name(name) = declared_names(name).sole++ def declared_names(name)+ @declared_names[name] ||= declare_names(name, rules)rescue Correction => correctionraise NotAMemberName.new(name, member_name(correction.name))end@@ -97,7 +99,7 @@ module JsonApiKitprivate- attr_reader :rules, :declared_names, :member_names+ attr_reader :rules, :member_namesdef member_names_before(names, rule_index)rules@@ -106,17 +108,16 @@ module JsonApiKit.reduce(names) { |result, rule| result.map { rule.member_name(it) } }end- def declare_name(name, remaining_rules)- remaining_rules.reduce(name) do |result, rule|- rule.declared_name(result)- rescue Correction => correction- raise Correction.new(- declare_name(- correction.name,- remaining_rules.drop(remaining_rules.index(rule) + 1),- ),- )- end+ def declare_names(name, remaining_rules)+ remaining_rules+ .each_with_index+ .reduce([name]) do |names, (rule, index)|+ names.flat_map { rule.declared_names(it) }.uniq+ rescue Correction => correction+ raise Correction.new(+ declare_names(correction.name, remaining_rules.drop(index + 1)).first,+ )+ endendendenddiff --git a/lib/json_api_kit/glossary/casing_rule.rb b/lib/json_api_kit/glossary/casing_rule.rbindex 39fad511454..8885efee565 100644--- a/lib/json_api_kit/glossary/casing_rule.rb+++ b/lib/json_api_kit/glossary/casing_rule.rb@@ -14,6 +14,8 @@ module JsonApiKitsnake_case(name).tap { raise Correction.new(it) unless camel_case(it) == name }end+ def declared_names(name) = [declared_name(name)]+def member_name(name) = camel_case(name)def member_attributes(attributes) = attributes.transform_keys { MEMBER_NAMES[it] }diff --git a/lib/json_api_kit/glossary/version_rule.rb b/lib/json_api_kit/glossary/version_rule.rbindex 2b8895e74fa..b79bc53299a 100644--- a/lib/json_api_kit/glossary/version_rule.rb+++ b/lib/json_api_kit/glossary/version_rule.rb@@ -13,17 +13,17 @@ module JsonApiKit.reduce(attributes) do |result, (change, index)|change.current_attributes(result)rescue VersionChange::Converter::Failure => failure- raise failure.convert_names { member_names(it, changes: changes.take(index)) }+ raise failure.convert_names { previous_names(it, changes: changes.take(index)) }endend- def declared_name(name)- current_name(name).tap { raise Correction.new(it) if member_names(it).exclude?(name) }+ def declared_names(name)+ current_names(name).tap do |names|+ names.each { raise Correction.new(it) if previous_names(it).exclude?(name) }+ endend- def member_name(name)- changes.reverse_each.reduce(name) { |result, change| change.previous(result) }- end+ def member_name(name) = previous_names(name).firstdef member_attributes(attributes)changes@@ -35,12 +35,14 @@ module JsonApiKitattr_reader :changes- def current_name(name) = changes.reduce(name) { |result, change| change.current(result) }+ def current_names(name)+ changes.reduce([name]) { |names, change| names.flat_map { change.current_names(it) }.uniq }+ end- def member_names(name, changes: self.changes)+ def previous_names(name, changes: self.changes)changes.reverse_each- .reduce([name]) { |names, change| names.flat_map { change.previous_names(it) } }+ .reduce([name]) { |names, change| names.flat_map { change.previous_names(it) }.uniq }endendenddiff --git a/lib/json_api_kit/request/family.rb b/lib/json_api_kit/request/family.rbindex 26bfc56ee8c..6f107cf8d52 100644--- a/lib/json_api_kit/request/family.rb+++ b/lib/json_api_kit/request/family.rb@@ -32,8 +32,10 @@ module JsonApiKit"#{direction}#{declared_name(yield(name), path)}"end- def declared_name(name, path)- glossary.declared_name(name).value+ def declared_name(name, path) = declared_names(name, path).sole++ def declared_names(name, path)+ glossary.declared_names(name).map(&:value)rescue Glossary::NotAMemberName => errorraise error.at(ParameterName.new(*path).to_s)enddiff --git a/lib/json_api_kit/request/family/fields.rb b/lib/json_api_kit/request/family/fields.rbindex 5887811dbac..d63ff50769d 100644--- a/lib/json_api_kit/request/family/fields.rb+++ b/lib/json_api_kit/request/family/fields.rb@@ -21,7 +21,10 @@ module JsonApiKitFieldsets::Fieldset.parse(raw).try do |fieldset|- fieldset.names.map { declared_name(Name::Field.new(value: it, type:), path) }+ fieldset+ .names+ .flat_map { declared_names(Name::Field.new(value: it, type:), path) }+ .uniqend || rawendenddiff --git a/lib/json_api_kit/version_change.rb b/lib/json_api_kit/version_change.rbindex 25a221cc19d..af8d9afc62d 100644--- a/lib/json_api_kit/version_change.rb+++ b/lib/json_api_kit/version_change.rb@@ -2,8 +2,6 @@module JsonApiKitclass VersionChange- PASS_THROUGH = ->(_index, name) { PassThrough.new(name) }-class << selfdef version(raw = nil)@version = ApiVersion.parse(raw) if raw@@ -33,16 +31,14 @@ module JsonApiKitdef type_renames = @type_renames ||= []end- delegate :version, :description, :transformations, :type_renames, to: :class+ delegate :version, :description, to: :classattr_reader :sourcedef initialize(source)@source = source- @upward = index_by(transformations, &:previous_names)- @downward = index_by(transformations) { [it.current] }- @type_upward = index_by(type_renames, &:previous_names)- @type_downward = index_by(type_renames) { [it.current] }+ @transformations = Transformations.new(self.class.transformations)+ @type_renames = TypeRenames.new(self.class.type_renames)enddef verify!@@ -52,58 +48,34 @@ module JsonApiKitraise ArgumentError, "#{source} is dated on or before the first release."endraise ArgumentError, "#{source} has no description." if description.blank?- duplicate_name(&:previous_names).try { raise ArgumentError, "#{source} changes #{it} twice." }- duplicate_name { [it.current] }.try do- raise ArgumentError, "#{source} changes two names into #{it}."- end+ transformations.verify!+ type_renames.verify!return if File.basename(source).start_with?(version.to_s)raise ArgumentError, "The file name must start with the version #{version}: #{source}."+ rescue NameChanges::Conflict => conflict+ raise ArgumentError, "#{source} #{conflict.message}"end- def current(name) = upward[current_type(name)].current+ def current_names(name) = transformations.current_names(current_type(name))def current_attributes(attributes)- current_values(attributes.transform_keys { current_type(it) })+ transformations.current_values(attributes.transform_keys { current_type(it) })rescue Converter::Failure => failureraise failure.convert_names { previous_type(it) }end- def previous(name) = previous_names(name).first-- def previous_names(name) = downward[name].previous_names.map { previous_type(it) }+ def previous_names(name) = transformations.previous_names(name).map { previous_type(it) }def previous_attributes(attributes)- attributes- .flat_map { |name, value| downward[name].previous_pairs(value) }- .to_h- .transform_keys { previous_type(it) }+ transformations.previous_values(attributes).transform_keys { previous_type(it) }endprivate- attr_reader :upward, :downward, :type_upward, :type_downward+ attr_reader :transformations, :type_renames- def current_type(name)- name.convert_type { type_upward[Name::Type.new(value: it)].current.value }- end-- def previous_type(name)- name.convert_type { type_downward[Name::Type.new(value: it)].previous_names.first.value }- end+ def current_type(name) = name.convert_type { type_renames.current(it) }- def current_values(attributes)- attributes.keys.map { upward[it] }.uniq.flat_map { it.current_pairs(attributes) }.to_h- end-- def index_by(transformations, &names)- transformations- .flat_map { |transformation| names.call(transformation).map { [it, transformation] } }- .to_h- .tap { it.default_proc = PASS_THROUGH }- end-- def duplicate_name(&)- (transformations + type_renames).flat_map(&).tally.detect { |_name, count| count > 1 }&.first- end+ def previous_type(name) = name.convert_type { type_renames.previous(it) }endenddiff --git a/lib/json_api_kit/version_change/converter.rb b/lib/json_api_kit/version_change/converter.rbindex 4869944dc44..f3eb196802d 100644--- a/lib/json_api_kit/version_change/converter.rb+++ b/lib/json_api_kit/version_change/converter.rb@@ -3,6 +3,11 @@module JsonApiKitclass VersionChangeclass Converter+ def self.for(direction, callable, from:, to:)+ return new(direction, callable, from) unless to.many?+ Tuple.new(direction, callable, from, to:)+ end+class Failure < StandardErrorattr_reader :names@@ -11,7 +16,7 @@ module JsonApiKitsuper("cannot convert the value of #{names.join(", ")}")end- def convert_names(&) = self.class.new(names.flat_map(&))+ def convert_names(&) = self.class.new(names.flat_map(&).uniq)enddef initialize(direction, callable, names)diff --git a/lib/json_api_kit/version_change/converter/tuple.rb b/lib/json_api_kit/version_change/converter/tuple.rbnew file mode 100644index 00000000000..e53c6ab6fde--- /dev/null+++ b/lib/json_api_kit/version_change/converter/tuple.rb@@ -0,0 +1,28 @@+# frozen_string_literal: true++module JsonApiKit+ class VersionChange+ class Converter+ class Tuple < Converter+ def initialize(direction, callable, names, to:)+ @destinations = to+ super(direction, callable, names)+ end++ def call(...)+ Array(super).tap do |values|+ next if values.size == destinations.size+ raise ArgumentError,+ "#{direction} converter for #{names.join(", ")} must return " \+ "#{destinations.size} #{"value".pluralize(destinations.size)} " \+ "(#{destinations.join(", ")}). It returned #{values.size}."+ end+ end++ private++ attr_reader :destinations+ end+ end+ end+enddiff --git a/lib/json_api_kit/version_change/declaration.rb b/lib/json_api_kit/version_change/declaration.rbindex 8a3993b9a01..8c18a9e9b67 100644--- a/lib/json_api_kit/version_change/declaration.rb+++ b/lib/json_api_kit/version_change/declaration.rb@@ -5,7 +5,7 @@ module JsonApiKitclass Declarationclass Fault < ArgumentErrordef initialize(message, from:, to:)- super("#{message}, to change #{Array(from).join(", ")} into #{to}.")+ super("#{message}, to change #{Array(from).join(", ")} into #{Array(to).join(", ")}.")endend@@ -39,8 +39,9 @@ module JsonApiKitdef converters@converters ||= {- up: Converter.new(:up, up, names(Name::Field, from)),- down: Converter.new(:down, down, names(Name::Field, to)),+ up: Converter.for(:up, up, from: names(Name::Field, from), to: names(Name::Field, to)),+ down:+ Converter.for(:down, down, from: names(Name::Field, to), to: names(Name::Field, from)),}rescue ArgumentError => errorraise fault(error.message)diff --git a/lib/json_api_kit/version_change/declaration/split_attribute.rb b/lib/json_api_kit/version_change/declaration/split_attribute.rbnew file mode 100644index 00000000000..ca9738028f4--- /dev/null+++ b/lib/json_api_kit/version_change/declaration/split_attribute.rb@@ -0,0 +1,27 @@+# frozen_string_literal: true++module JsonApiKit+ class VersionChange+ class Declaration+ class SplitAttribute < Declaration+ def initialize(type, from:, to:, up:, down:)+ super(type, from:, to: Array(to), up:, down:)+ end++ private++ def kinds = [Name::Field]++ def verify!+ raise fault("Declare one source name") if from.is_a?(Array) || from.nil?+ raise fault("Declare at least two names") unless to.many?+ raise fault("Declare distinct names") unless to.map(&:to_s).uniq.size == to.size+ end++ def transformation(kind)+ Split.new(from: name(kind, from), to: names(kind, to), **converters)+ end+ end+ end+ end+enddiff --git a/lib/json_api_kit/version_change/declarations.rb b/lib/json_api_kit/version_change/declarations.rbindex f427e722d35..dd2db96e394 100644--- a/lib/json_api_kit/version_change/declarations.rb+++ b/lib/json_api_kit/version_change/declarations.rb@@ -12,6 +12,8 @@ module JsonApiKitdef merged_attributes(**) = declare(Declaration::MergedAttributes.new(type, **))+ def split_attribute(**) = declare(Declaration::SplitAttribute.new(type, **))+def renamed_sort(from:, to:)declare(Declaration::RenamedName.new(type, [Name::Sort], from:, to:))enddiff --git a/lib/json_api_kit/version_change/merge.rb b/lib/json_api_kit/version_change/merge.rbindex f1e2f18b03b..4bbbe42c251 100644--- a/lib/json_api_kit/version_change/merge.rb+++ b/lib/json_api_kit/version_change/merge.rb@@ -4,24 +4,13 @@ module JsonApiKitclass VersionChangeMerge =Data.define(:from, :to, :up, :down) do- def current = to+ def current_names = [to]def current_pairs(attributes) = [[to, up.call(*attributes.values_at(*from))]]def previous_names = from- def previous_pairs(value) = from.zip(previous_values(value))-- private-- def previous_values(value)- Array(down.call(value)).tap do |values|- next if values.size == from.size- raise ArgumentError,- "down: answers #{values.size} #{"value".pluralize(values.size)} for " \- "#{from.size} names, to split #{to}."- end- end+ def previous_pairs(attributes) = from.zip(down.call(attributes.fetch(to)))endendenddiff --git a/lib/json_api_kit/version_change/name_changes.rb b/lib/json_api_kit/version_change/name_changes.rbnew file mode 100644index 00000000000..31304821042--- /dev/null+++ b/lib/json_api_kit/version_change/name_changes.rb@@ -0,0 +1,44 @@+# frozen_string_literal: true++module JsonApiKit+ class VersionChange+ class NameChanges+ Conflict = Class.new(StandardError)+ PASS_THROUGH = ->(_index, name) { PassThrough.new(name) }++ def initialize(changes)+ @changes = changes.dup+ @upward = index_by(&:previous_names)+ @downward = index_by(&:current_names)+ end++ def current_names(name) = upward[name].current_names++ def previous_names(name) = downward[name].previous_names++ def verify!+ duplicate_name(&:previous_names).try { raise Conflict, "changes #{it} twice." }+ duplicate_name(&:current_names).try { raise Conflict, "changes two names into #{it}." }+ end++ private++ attr_reader :changes, :upward, :downward++ def current_changes(names) = names.map { upward[it] }.uniq++ def previous_changes(names) = names.map { downward[it] }.uniq++ def index_by(&names)+ changes+ .flat_map { |change| names.call(change).map { [it, change] } }+ .to_h+ .tap { it.default_proc = PASS_THROUGH }+ end++ def duplicate_name(&)+ changes.flat_map(&).tally.detect { |_name, count| count > 1 }&.first+ end+ end+ end+enddiff --git a/lib/json_api_kit/version_change/pass_through.rb b/lib/json_api_kit/version_change/pass_through.rbindex ab381e769b4..afe57668c90 100644--- a/lib/json_api_kit/version_change/pass_through.rb+++ b/lib/json_api_kit/version_change/pass_through.rb@@ -4,13 +4,13 @@ module JsonApiKitclass VersionChangePassThrough =Data.define(:name) do- def current = name+ def current_names = [name]def current_pairs(attributes) = [[name, attributes[name]]]def previous_names = [name]- def previous_pairs(value) = [[name, value]]+ def previous_pairs(attributes) = [[name, attributes.fetch(name)]]endendenddiff --git a/lib/json_api_kit/version_change/rename.rb b/lib/json_api_kit/version_change/rename.rbindex 15d22aa1c2f..9033bf1d95e 100644--- a/lib/json_api_kit/version_change/rename.rb+++ b/lib/json_api_kit/version_change/rename.rb@@ -4,13 +4,13 @@ module JsonApiKitclass VersionChangeRename =Data.define(:from, :to, :up, :down) do- def current = to+ def current_names = [to]def current_pairs(attributes) = [[to, up.call(attributes[from])]]def previous_names = [from]- def previous_pairs(value) = [[from, down.call(value)]]+ def previous_pairs(attributes) = [[from, down.call(attributes.fetch(to))]]endendenddiff --git a/lib/json_api_kit/version_change/split.rb b/lib/json_api_kit/version_change/split.rbnew file mode 100644index 00000000000..4ad33e2ee52--- /dev/null+++ b/lib/json_api_kit/version_change/split.rb@@ -0,0 +1,19 @@+# frozen_string_literal: true++module JsonApiKit+ class VersionChange+ Split =+ Data.define(:from, :to, :up, :down) do+ def current_names = to++ def current_pairs(attributes) = to.zip(up.call(attributes.fetch(from)))++ def previous_names = [from]++ def previous_pairs(attributes)+ return [] unless to.all? { attributes.key?(it) }+ [[from, down.call(*attributes.values_at(*to))]]+ end+ end+ end+enddiff --git a/lib/json_api_kit/version_change/transformations.rb b/lib/json_api_kit/version_change/transformations.rbnew file mode 100644index 00000000000..2d8c5b7e035--- /dev/null+++ b/lib/json_api_kit/version_change/transformations.rb@@ -0,0 +1,15 @@+# frozen_string_literal: true++module JsonApiKit+ class VersionChange+ class Transformations < NameChanges+ def current_values(attributes)+ current_changes(attributes.keys).flat_map { it.current_pairs(attributes) }.to_h+ end++ def previous_values(attributes)+ previous_changes(attributes.keys).flat_map { it.previous_pairs(attributes) }.to_h+ end+ end+ end+enddiff --git a/lib/json_api_kit/version_change/type_rename.rb b/lib/json_api_kit/version_change/type_rename.rbindex 5dfdfe36ba7..34f021b85e6 100644--- a/lib/json_api_kit/version_change/type_rename.rb+++ b/lib/json_api_kit/version_change/type_rename.rb@@ -4,7 +4,7 @@ module JsonApiKitclass VersionChangeTypeRename =Data.define(:from, :to) do- def current = to+ def current_names = [to]def previous_names = [from]enddiff --git a/lib/json_api_kit/version_change/type_renames.rb b/lib/json_api_kit/version_change/type_renames.rbnew file mode 100644index 00000000000..70c770fb09e--- /dev/null+++ b/lib/json_api_kit/version_change/type_renames.rb@@ -0,0 +1,11 @@+# frozen_string_literal: true++module JsonApiKit+ class VersionChange+ class TypeRenames < NameChanges+ def current(type) = current_names(Name::Type.new(value: type)).sole.value++ def previous(type) = previous_names(Name::Type.new(value: type)).sole.value+ end+ end+enddiff --git a/spec/integration/json_api_kit/split_attributes_spec.rb b/spec/integration/json_api_kit/split_attributes_spec.rbnew file mode 100644index 00000000000..7d2b8f8aaea--- /dev/null+++ b/spec/integration/json_api_kit/split_attributes_spec.rb@@ -0,0 +1,213 @@+# frozen_string_literal: true++module JsonApiKitSpec+ class SplitImage < Upload+ def get_dimension(key) = self[key]+ end++ class SplitImageResource < JsonApiKit::Resource+ model SplitImage+ type :images++ attribute :original_filename+ attribute :width, readable: ->(guardian) { guardian.user.present? }+ attribute :height, readable: ->(guardian, upload) { upload.user_id == guardian.user&.id }+ end++ class SplitImageOwnerResource < JsonApiKit::Resource+ model User+ type :users++ attribute :username+ has_many :uploads, resource: SplitImageResource+ includes "uploads"+ end++ class SplitImagesController < JsonApiKit::BaseController+ resource SplitImageResource+ end++ class SplitImageOwnersController < JsonApiKit::BaseController+ resource SplitImageOwnerResource+ end++ class SplitPictureDimensions < JsonApiKit::VersionChange+ version "2026-09-01"+ description "The pixel_dimensions attribute becomes pixel_width and pixel_height."++ resource :pictures do+ split_attribute from: :pixel_dimensions,+ to: %i[pixel_width pixel_height],+ up: ->(dimensions) { dimensions },+ down: ->(width, height) { [width, height] }+ end+ end++ class RenameSplitPictureFields < JsonApiKit::VersionChange+ version "2026-09-02"+ description "Pictures become images with width and height attributes."++ renamed_type from: :pictures, to: :images++ resource :images do+ renamed_attribute from: :pixel_width, to: :width+ renamed_attribute from: :pixel_height, to: :height+ end+ end+end++RSpec.describe "JSON:API split attributes", type: :request do+ fab!(:owner, :user)+ fab!(:other_user, :user)+ fab!(:upload) { Fabricate(:upload, user: owner, width: 640, height: 480) }++ let(:version) { JsonApiKit::Timeline::FIRST_RELEASE.to_s }+ let(:user) { owner }+ let(:dimensions) { { width: 640, height: 480 } }+ let(:path) { "/api/images/#{upload.id}" }+ let(:query) { { "fields" => { "pictures" => "pixelDimensions" } } }+ let(:version_changes) do+ JsonApiKit::VersionChanges.new(+ [+ JsonApiKitSpec::SplitPictureDimensions.new(__FILE__),+ JsonApiKitSpec::RenameSplitPictureFields.new(__FILE__),+ ],+ )+ end+ let(:body) { JSON.parse(response.body) }+ let(:primary) { body.fetch("data") }+ let(:attributes) { primary.fetch("attributes", {}) }++ before do+ freeze_time(Date.new(2026, 9, 3))+ allow(JsonApiKit::VersionChanges).to receive(:core).and_return(version_changes)+ upload.update_columns(dimensions)+ sign_in(user) if user+ Rails.application.routes.disable_clear_and_finalize = true+ Rails.application.routes.draw do+ get "/api/images/:id" => "json_api_kit_spec/split_images#show"+ get "/api/image-owners/:id" => "json_api_kit_spec/split_image_owners#show"+ end+ Rails.application.routes.disable_clear_and_finalize = false+ end++ after { Rails.application.reload_routes! }++ describe "GET resource" do+ before { get path, headers: { "HTTP_API_VERSION" => version }, params: query }++ it "reconstructs only the selected historical attribute" do+ expect(attributes).to eq("pixelDimensions" => [640, 480])+ end++ it "uses the historical resource type" do+ expect(primary.fetch("type")).to eq("pictures")+ end++ context "when the request excludes the split attribute" do+ let(:query) { { "fields" => { "pictures" => "originalFilename" } } }++ it "returns only the selected attribute" do+ expect(attributes).to eq("originalFilename" => upload.original_filename)+ end+ end++ context "when the request selects no attributes" do+ let(:query) { { "fields" => { "pictures" => "" } } }++ it "returns no attributes" do+ expect(attributes).to be_empty+ end+ end++ context "when the request has no fieldset" do+ let(:query) { {} }++ it "returns the reconstructed attribute with the other readable attributes" do+ expect(attributes).to eq(+ "originalFilename" => upload.original_filename,+ "pixelDimensions" => [640, 480],+ )+ end+ end++ context "when one destination is unreadable" do+ let(:user) { other_user }+ let(:query) { { "fields" => { "pictures" => "pixelDimensions,originalFilename" } } }++ it "omits the historical attribute" do+ expect(attributes).to eq("originalFilename" => upload.original_filename)+ end++ it "accepts the fieldset" do+ expect(response).to have_http_status(:ok)+ end+ end++ context "when neither destination is readable" do+ let(:user) { nil }++ it "omits the historical attribute" do+ expect(attributes).to be_empty+ end+ end++ context "when one destination has a null value" do+ let(:dimensions) { super().merge(height: nil) }++ it "passes the null value to the converter" do+ expect(attributes).to eq("pixelDimensions" => [640, nil])+ end+ end++ context "when both destinations have null values" do+ let(:dimensions) { { width: nil, height: nil } }++ it "passes both null values to the converter" do+ expect(attributes).to eq("pixelDimensions" => [nil, nil])+ end+ end++ context "when an old client requests a destination name" do+ let(:query) { { "fields" => { "pictures" => "pixelWidth" } } }++ it "refuses the name with the historical attribute" do+ expect(body.fetch("errors").sole).to include(+ "detail" => "Use pixelDimensions, not pixelWidth.",+ "source" => {+ "parameter" => "fields[pictures]",+ },+ )+ end+ end++ context "when the pin includes the split but not the later renames" do+ let(:version) { "2026-09-01" }+ let(:query) { { "fields" => { "pictures" => "pixelHeight" } } }++ it "returns only the selected destination under its historical name" do+ expect(attributes).to eq("pixelHeight" => 480)+ end+ end++ context "when the client uses the current version" do+ let(:version) { "2026-09-02" }+ let(:query) { { "fields" => { "images" => "width" } } }++ it "returns only the selected current attribute" do+ expect(attributes).to eq("width" => 640)+ end+ end++ context "when the split resource is included" do+ let(:path) { "/api/image-owners/#{owner.id}" }+ let(:query) { super().merge("include" => "uploads") }++ it "reconstructs the selected attribute on the included resource" do+ expect(body.fetch("included").sole.fetch("attributes")).to eq(+ "pixelDimensions" => [640, 480],+ )+ end+ end+ end+enddiff --git a/spec/lib/json_api_kit/glossary/split_attributes_spec.rb b/spec/lib/json_api_kit/glossary/split_attributes_spec.rbnew file mode 100644index 00000000000..7b7171a2305--- /dev/null+++ b/spec/lib/json_api_kit/glossary/split_attributes_spec.rb@@ -0,0 +1,230 @@+# frozen_string_literal: true++RSpec.describe JsonApiKit::Glossary do+ subject(:glossary) { described_class.resource(JsonApiKit::Timeline::FIRST_RELEASE) }++ let(:size) { JsonApiKit::Name::Field.new(value: "sizePair", type: "pictures") }+ let(:width) { JsonApiKit::Name::Field.new(value: "image_width", type: "images") }+ let(:height) { width.with(value: "image_height") }+ let(:up) { ->(dimensions) { dimensions.map { Integer(it) } } }+ let(:down) { ->(width, height) { [width, height] } }+ let(:rename) do+ Class+ .new(JsonApiKit::VersionChange) do+ version "2026-09-01"+ description "The size_pair attribute becomes pixel_dimensions."++ resource :pictures do+ renamed_attribute from: :size_pair, to: :pixel_dimensions+ end+ end+ .new(__FILE__)+ end+ let(:split) do+ converter_up = up+ converter_down = down++ Class+ .new(JsonApiKit::VersionChange) do+ version "2026-09-02"+ description "The dimensions become width and height."++ resource :pictures do+ split_attribute from: :pixel_dimensions,+ to: %i[pixel_width pixel_height],+ up: converter_up,+ down: converter_down+ end+ end+ .new(__FILE__)+ end+ let(:later_change) do+ Class+ .new(JsonApiKit::VersionChange) do+ version "2026-09-03"+ description "Pictures become images with new attribute names."++ renamed_type from: :pictures, to: :images++ resource :images do+ renamed_attribute from: :pixel_width, to: :image_width+ renamed_attribute from: :pixel_height, to: :image_height+ end+ end+ .new(__FILE__)+ end+ let(:changes) { [rename, split, later_change] }+ let(:version_changes) { JsonApiKit::VersionChanges.new(changes) }++ before { allow(JsonApiKit::VersionChanges).to receive(:core).and_return(version_changes) }++ describe "#declared_names" do+ subject(:declared_names) { glossary.declared_names(size) }++ it "expands the historical name through the later renames" do+ expect(declared_names).to eq([width, height])+ end++ context "when the field belongs to a later version" do+ let(:size) { super().with(value: "pixelWidth") }++ it "reports the name available to the client" do+ expect { declared_names }.to raise_error(+ described_class::NotAMemberName,+ "Use sizePair, not pixelWidth.",+ )+ end+ end++ context "when the client uses the wrong casing" do+ let(:size) { super().with(value: "size_pair") }++ it "reports the historical name with its casing" do+ expect { declared_names }.to raise_error(+ described_class::NotAMemberName,+ "Use sizePair, not size_pair.",+ )+ end+ end+ end++ describe "#declared_attributes" do+ subject(:declared_attributes) { glossary.declared_attributes(attributes) }++ let(:attributes) { { size => %w[640 480] } }++ it "converts the old value into both current attributes" do+ expect(declared_attributes).to eq(width => 640, height => 480)+ end++ context "when the old attribute is absent" do+ let(:attributes) { {} }++ it "does not produce either destination" do+ expect(declared_attributes).to be_empty+ end+ end++ context "when the old value is null" do+ let(:attributes) { { size => nil } }+ let(:up) { ->(dimensions) { dimensions || [nil, nil] } }++ it "uses the converter's null representation" do+ expect(declared_attributes).to eq(width => nil, height => nil)+ end+ end++ context "when the split converter rejects the value" do+ let(:attributes) { { size => %w[invalid 480] } }++ it "reports the attribute under the client's name" do+ expect { declared_attributes }.to raise_error(+ described_class::BadValue,+ "This version cannot convert the value of sizePair.",+ )+ end+ end++ context "when the split converter returns too few values" do+ let(:up) { ->(dimensions) { [dimensions.first] } }++ it "reports an invalid converter result" do+ expect { declared_attributes }.to raise_error(+ ArgumentError,+ "up converter for pixel_dimensions must return 2 values (pixel_width, pixel_height). It returned 1.",+ )+ end+ end++ context "when a later converter rejects both split destinations" do+ let(:later_change) do+ Class+ .new(JsonApiKit::VersionChange) do+ version "2026-09-03"+ description "The dimensions become an area."++ resource :pictures do+ merged_attributes from: %i[pixel_width pixel_height],+ to: :area,+ up: ->(_width, _height) { raise ArgumentError },+ down: ->(area) { [area, 1] }+ end+ end+ .new(__FILE__)+ end++ it "reports the historical source once" do+ expect { declared_attributes }.to raise_error(+ described_class::BadValue,+ "This version cannot convert the value of sizePair.",+ )+ end+ end+ end++ describe "#member_attributes" do+ subject(:member_attributes) { glossary.member_attributes(attributes) }++ let(:attributes) { { height => 480, width => 640 } }++ it "combines the current values through the earlier renames" do+ expect(member_attributes).to eq(size => [640, 480])+ end++ context "when a destination is absent" do+ let(:attributes) { super().except(height) }++ it "omits the historical attribute" do+ expect(member_attributes).to be_empty+ end+ end++ context "when the resource type has another attribute with the same name" do+ let(:attributes) { super().merge(width.with(type: "other_images") => 20) }++ it "preserves the unrelated attribute" do+ expect(member_attributes).to eq(+ size => [640, 480],+ width.with(value: "imageWidth", type: "otherImages") => 20,+ )+ end+ end+ end++ context "when a later change merges the destinations" do+ let(:later_change) do+ Class+ .new(JsonApiKit::VersionChange) do+ version "2026-09-03"+ description "The width and height become dimensions."++ resource :pictures do+ merged_attributes from: %i[pixel_width pixel_height],+ to: :dimensions,+ up: ->(width, height) { [width, height] },+ down: ->(dimensions) { dimensions }+ end+ end+ .new(__FILE__)+ end+ let(:dimensions) { size.with(value: "dimensions") }++ describe "#declared_names" do+ it "returns the merged destination once" do+ expect(glossary.declared_names(size)).to eq([dimensions])+ end+ end++ describe "#declared_attributes" do+ it "splits the source before merging its destinations" do+ expect(glossary.declared_attributes(size => %w[640 480])).to eq(dimensions => [640, 480])+ end+ end++ describe "#member_attributes" do+ it "reconstructs the source after reversing the merge" do+ expect(glossary.member_attributes(dimensions => [640, 480])).to eq(size => [640, 480])+ end+ end+ end+enddiff --git a/spec/lib/json_api_kit/glossary/version_rule_spec.rb b/spec/lib/json_api_kit/glossary/version_rule_spec.rbindex 283ca2e2e1a..f64266a75b3 100644--- a/spec/lib/json_api_kit/glossary/version_rule_spec.rb+++ b/spec/lib/json_api_kit/glossary/version_rule_spec.rb@@ -118,11 +118,11 @@ RSpec.describe JsonApiKit::Glossary::VersionRule doendend- describe "#declared_name" do- subject(:declared_name) { rule.declared_name(name) }+ describe "#declared_names" do+ subject(:declared_names) { rule.declared_names(name) }it "returns the current name of an old name" do- expect(declared_name).to eq(name.with(value: "published_at"))+ expect(declared_names).to eq([name.with(value: "published_at")])endcontext "when a later change reuses a spelling of this version" do@@ -131,14 +131,14 @@ RSpec.describe JsonApiKit::Glossary::VersionRule dolet(:value) { "name" }it "returns the current name" do- expect(declared_name).to eq(name.with(value: "title"))+ expect(declared_names).to eq([name.with(value: "title")])endcontext "when the name belongs to a later version" dolet(:value) { "title" }it "raises a correction with the declared name" do- expect { declared_name }.to raise_error(having_attributes(name:))+ expect { declared_names }.to raise_error(having_attributes(name:))endendend@@ -147,7 +147,7 @@ RSpec.describe JsonApiKit::Glossary::VersionRule dolet(:value) { "title" }it "returns the name" do- expect(declared_name).to eq(name)+ expect(declared_names).to eq([name])endend@@ -156,14 +156,14 @@ RSpec.describe JsonApiKit::Glossary::VersionRule dolet(:value) { "posted_time" }it "returns the current name" do- expect(declared_name).to eq(name.with(value: "published_at"))+ expect(declared_names).to eq([name.with(value: "published_at")])endcontext "when the name is the one they merge into" dolet(:value) { "posted_at" }it "raises a correction with the declared name" do- expect { declared_name }.to raise_error(+ expect { declared_names }.to raise_error(having_attributes(name: name.with(value: "published_at")),)end@@ -174,7 +174,7 @@ RSpec.describe JsonApiKit::Glossary::VersionRule dolet(:value) { "published_at" }it "raises a correction with the declared name" do- expect { declared_name }.to raise_error(+ expect { declared_names }.to raise_error(an_instance_of(JsonApiKit::Glossary::Correction).and(having_attributes(name:)),)end@@ -199,6 +199,17 @@ RSpec.describe JsonApiKit::Glossary::VersionRule doname.with(value: "posted_time") => "00:00:00",)end++ context "when the merge converter returns too few values" do+ subject(:member_attributes) { rule.member_attributes(name => "2026-08-01") }++ it "reports an invalid converter result" do+ expect { member_attributes }.to raise_error(+ ArgumentError,+ "down converter for posted_at must return 2 values (posted_date, posted_time). It returned 1.",+ )+ end+ endendend@@ -227,5 +238,46 @@ RSpec.describe JsonApiKit::Glossary::VersionRule doexpect(member_name).to eq(name.with(value: "posted_date"))endend++ context "when a split and a merge produce the same historical name" do+ let(:changes) { [first_change, split_change, merge_change] }+ let(:split_change) do+ Class+ .new(JsonApiKit::VersionChange) do+ resource :topics do+ split_attribute from: :created_at,+ to: %i[posted_date posted_time],+ up: ->(time) { time.split(" ") },+ down: ->(date, time) { "#{date} #{time}" }+ end+ end+ .new(__FILE__)+ end+ let(:merge_change) do+ Class+ .new(JsonApiKit::VersionChange) do+ resource :topics do+ merged_attributes from: %i[posted_date posted_time],+ to: :published_at,+ up: ->(date, time) { "#{date} #{time}" },+ down: ->(time) { time.split(" ") }+ end+ end+ .new(__FILE__)+ end++ before { allow(first_change).to receive(:previous_names).and_call_original }++ it "translates the converged name once" do+ member_name+ expect(first_change).to have_received(:previous_names).with(+ name.with(value: "created_at"),+ ).once+ end++ it "returns the historical name" do+ expect(member_name).to eq(name.with(value: "posted_at"))+ end+ endendenddiff --git a/spec/lib/json_api_kit/glossary_spec.rb b/spec/lib/json_api_kit/glossary_spec.rbindex d092fd5c5ba..f08c7a91bc6 100644--- a/spec/lib/json_api_kit/glossary_spec.rb+++ b/spec/lib/json_api_kit/glossary_spec.rb@@ -5,6 +5,8 @@ module JsonApiKitSpecStruct.new(:mark) dodef declared_name(name) = name.convert { "#{it}<#{mark}" }+ def declared_names(name) = [declared_name(name)]+def member_name(name) = name.convert { "#{it}>#{mark}" }def declared_attributes(attributes) = attributes.transform_keys { declared_name(it) }@@ -15,6 +17,8 @@ module JsonApiKitSpecmodule BrokenRuledef self.declared_name(name) = name+ def self.declared_names(name) = [name]+def self.declared_attributes(_attributes) = raise NoMethodError, "a fault in the kit"end@@ -159,6 +163,8 @@ RSpec.describe JsonApiKit::Glossary do.new dodef declared_name(name) = name+ def declared_names(name) = [name]+def declared_attributes(attributes)raise JsonApiKit::VersionChange::Converter::Failure.new(attributes.keys)enddiff --git a/spec/lib/json_api_kit/version_change/converter/failure_spec.rb b/spec/lib/json_api_kit/version_change/converter/failure_spec.rbindex a142173ef75..1df742f9e9d 100644--- a/spec/lib/json_api_kit/version_change/converter/failure_spec.rb+++ b/spec/lib/json_api_kit/version_change/converter/failure_spec.rb@@ -31,5 +31,17 @@ RSpec.describe JsonApiKit::VersionChange::Converter::Failure do)endend++ context "when several names share one historical source" do+ subject(:conversion_failure) { failure.convert_names { field } }++ let(:failure) do+ described_class.new([field.with(value: "width"), field.with(value: "height")])+ end++ it "reports the historical source once" do+ expect(conversion_failure.names).to eq([field])+ end+ endendenddiff --git a/spec/lib/json_api_kit/version_change/converter/tuple_spec.rb b/spec/lib/json_api_kit/version_change/converter/tuple_spec.rbnew file mode 100644index 00000000000..6323c8bdce4--- /dev/null+++ b/spec/lib/json_api_kit/version_change/converter/tuple_spec.rb@@ -0,0 +1,81 @@+# frozen_string_literal: true++RSpec.describe JsonApiKit::VersionChange::Converter::Tuple do+ subject(:converter) { described_class.new(:up, callable, [dimensions], to: [width, height]) }++ let(:dimensions) { JsonApiKit::Name::Field.new(value: "dimensions", type: "images") }+ let(:width) { dimensions.with(value: "width") }+ let(:height) { dimensions.with(value: "height") }+ let(:callable) { ->(dimensions) { dimensions.map { Integer(it) } } }+ let(:input) { %w[640 480] }++ describe "#call" do+ subject(:conversion) { converter.call(input) }++ it "returns one value per destination in order" do+ expect(conversion).to eq([640, 480])+ end++ context "when a destination value is an array" do+ let(:callable) { ->(dimensions) { [dimensions, dimensions.reverse] } }++ it "preserves each attribute value" do+ expect(conversion).to eq([%w[640 480], %w[480 640]])+ end+ end++ context "when the destination values are null" do+ let(:callable) { ->(_dimensions) { [nil, nil] } }++ it "preserves the null values" do+ expect(conversion).to eq([nil, nil])+ end+ end++ context "when the callable returns too few values" do+ let(:callable) { ->(dimensions) { [dimensions.first] } }++ it "reports the expected output count" do+ expect { conversion }.to raise_error(+ ArgumentError,+ "up converter for dimensions must return 2 values (width, height). It returned 1.",+ )+ end+ end++ context "when the callable returns too many values" do+ let(:callable) { ->(dimensions) { [*dimensions, 10] } }++ it "reports the expected output count" do+ expect { conversion }.to raise_error(ArgumentError, /It returned 3\./)+ end+ end++ context "when the callable returns a scalar" do+ let(:callable) { ->(dimensions) { dimensions.first } }++ it "reports one value for several destinations" do+ expect { conversion }.to raise_error(ArgumentError, /It returned 1\./)+ end+ end++ context "when the callable returns null" do+ let(:callable) { ->(_dimensions) { nil } }++ it "reports no values for the destinations" do+ expect { conversion }.to raise_error(ArgumentError, /It returned 0\./)+ end+ end++ context "when the callable rejects the input" do+ let(:input) { %w[invalid 480] }++ it "reports a conversion failure with the source name" do+ expect { conversion }.to raise_error(+ JsonApiKit::VersionChange::Converter::Failure,+ "cannot convert the value of dimensions",+ )+ end+ end+ end+enddiff --git a/spec/lib/json_api_kit/version_change/converter_spec.rb b/spec/lib/json_api_kit/version_change/converter_spec.rbindex 76c1a3a88eb..900c131989a 100644--- a/spec/lib/json_api_kit/version_change/converter_spec.rb+++ b/spec/lib/json_api_kit/version_change/converter_spec.rb@@ -8,6 +8,33 @@ RSpec.describe JsonApiKit::VersionChange::Converter dolet(:date_name) { JsonApiKit::Name::Field.new(value: "posted_date", type: "topics") }let(:time_name) { JsonApiKit::Name::Field.new(value: "posted_time", type: "topics") }+ describe ".for" do+ subject(:converter) { described_class.for(:up, callable, from: names, to: destinations) }++ let(:destinations) { [date_name.with(value: "posted_at")] }++ it "builds a converter for one destination" do+ expect(converter).to be_an_instance_of(described_class)+ end++ context "when the declaration has several destinations" do+ let(:destinations) { [date_name, time_name] }+ let(:callable) { ->(date, time) { [date, time] } }++ it "builds a tuple converter" do+ expect(converter).to be_an_instance_of(described_class::Tuple)+ end+ end++ context "when one attribute has an array value" do+ let(:callable) { ->(date, time) { [date, time] } }++ it "preserves the array as one attribute value" do+ expect(converter.call("2026-08-01", "00:00:00")).to eq(%w[2026-08-01 00:00:00])+ end+ end+ end+describe ".new" docontext "when the callable does not respond to call" dolet(:callable) { nil }diff --git a/spec/lib/json_api_kit/version_change/declaration/split_attribute_spec.rb b/spec/lib/json_api_kit/version_change/declaration/split_attribute_spec.rbnew file mode 100644index 00000000000..46f245f1839--- /dev/null+++ b/spec/lib/json_api_kit/version_change/declaration/split_attribute_spec.rb@@ -0,0 +1,83 @@+# frozen_string_literal: true++RSpec.describe JsonApiKit::VersionChange::Declaration::SplitAttribute do+ subject(:declaration) { described_class.new("images", from:, to:, up:, down:) }++ let(:from) { :dimensions }+ let(:to) { %i[width height] }+ let(:up) { ->(dimensions) { dimensions } }+ let(:down) { ->(width, height) { [width, height] } }+ let(:dimensions) { JsonApiKit::Name::Field.new(value: "dimensions", type: "images") }++ describe "#transformations" do+ subject(:transformations) { declaration.transformations }++ it "declares a split for the attribute only" do+ expect(transformations).to contain_exactly(+ an_instance_of(JsonApiKit::VersionChange::Split).and(+ having_attributes(+ previous_names: [dimensions],+ current_names: [dimensions.with(value: "width"), dimensions.with(value: "height")],+ ),+ ),+ )+ end++ context "when the source holds several names" do+ let(:from) { %i[dimensions other] }++ it "requires one source name" do+ expect { transformations }.to raise_error(described_class::Fault, /Declare one source name/)+ end+ end++ context "when the declaration holds one destination" do+ let(:to) { :width }++ it "requires at least two destinations" do+ expect { transformations }.to raise_error(+ described_class::Fault,+ /Declare at least two names/,+ )+ end+ end++ context "when two destinations have the same name" do+ let(:to) { [:width, "width"] }++ it "requires distinct destination names" do+ expect { transformations }.to raise_error(described_class::Fault, /Declare distinct names/)+ end+ end++ context "when a converter is not callable" do+ let(:up) { nil }++ it "reports the converter" do+ expect { transformations }.to raise_error(+ described_class::Fault,+ /up: must respond to call/,+ )+ end+ end++ context "when the up converter takes several values" do+ let(:up) { ->(width, height) { [width, height] } }++ it "requires one argument" do+ expect { transformations }.to raise_error(described_class::Fault, /up: must take 1 value/)+ end+ end++ context "when the down converter takes one value" do+ let(:down) { ->(dimensions) { dimensions } }++ it "requires one argument per destination" do+ expect { transformations }.to raise_error(+ described_class::Fault,+ /down: must take 2 values/,+ )+ end+ end+ end+enddiff --git a/spec/lib/json_api_kit/version_change/merge_spec.rb b/spec/lib/json_api_kit/version_change/merge_spec.rbindex e15f0fff307..a23b791c757 100644--- a/spec/lib/json_api_kit/version_change/merge_spec.rb+++ b/spec/lib/json_api_kit/version_change/merge_spec.rb@@ -9,9 +9,9 @@ RSpec.describe JsonApiKit::VersionChange::Merge dolet(:time_name) { JsonApiKit::Name::Field.new(value: "posted_time", type: "topics") }let(:new_name) { JsonApiKit::Name::Field.new(value: "posted_at", type: "topics") }- describe "#current" do+ describe "#current_names" doit "returns the new name" do- expect(merge.current).to eq(new_name)+ expect(merge.current_names).to eq([new_name])endend@@ -40,26 +40,10 @@ RSpec.describe JsonApiKit::VersionChange::Merge doenddescribe "#previous_pairs" do- subject(:previous_pairs) { merge.previous_pairs("2026-08-01 00:00:00") }+ subject(:previous_pairs) { merge.previous_pairs(new_name => "2026-08-01 00:00:00") }it "returns one pair per old name, in the order of the declaration" doexpect(previous_pairs).to eq([[date_name, "2026-08-01"], [time_name, "00:00:00"]])end-- context "when the converter answers another count of values" do- let(:down) { ->(posted_at) { [posted_at] } }-- it "raises with the two counts" do- expect { previous_pairs }.to raise_error(ArgumentError, /1 value for 2 names/)- end- end-- context "when the converter answers one value and not an array" do- let(:down) { ->(posted_at) { posted_at } }-- it "raises with the two counts" do- expect { previous_pairs }.to raise_error(ArgumentError, /1 value for 2 names/)- end- endendenddiff --git a/spec/lib/json_api_kit/version_change/name_changes_spec.rb b/spec/lib/json_api_kit/version_change/name_changes_spec.rbnew file mode 100644index 00000000000..2e42e55a8d1--- /dev/null+++ b/spec/lib/json_api_kit/version_change/name_changes_spec.rb@@ -0,0 +1,89 @@+# frozen_string_literal: true++RSpec.describe JsonApiKit::VersionChange::NameChanges do+ subject(:name_changes) { described_class.new(changes) }++ let(:previous_type) { JsonApiKit::Name::Type.new(value: "pictures") }+ let(:current_type) { previous_type.with(value: "images") }+ let(:rename) { JsonApiKit::VersionChange::TypeRename.new(from: previous_type, to: current_type) }+ let(:changes) { [rename] }++ describe "#current_names" do+ subject(:current_names) { name_changes.current_names(name) }++ let(:name) { previous_type }++ it "returns the destination names" do+ expect(current_names).to eq([current_type])+ end++ context "when the name has no change" do+ let(:name) { previous_type.with(value: "users") }++ it "preserves the name" do+ expect(current_names).to eq([name])+ end+ end++ context "when another kind of name has the same value" do+ let(:name) { JsonApiKit::Name::Member.new(value: "pictures") }++ it "preserves the unrelated name" do+ expect(current_names).to eq([name])+ end+ end+ end++ describe "#previous_names" do+ subject(:previous_names) { name_changes.previous_names(name) }++ let(:name) { current_type }++ it "returns the source names" do+ expect(previous_names).to eq([previous_type])+ end++ context "when the name has no change" do+ let(:name) { current_type.with(value: "users") }++ it "preserves the name" do+ expect(previous_names).to eq([name])+ end+ end+ end++ describe "#verify!" do+ subject(:verify) { name_changes.verify! }++ it "accepts distinct sources and destinations" do+ expect { verify }.not_to raise_error+ end++ context "when the collection is empty" do+ let(:changes) { [] }++ it "accepts the collection" do+ expect { verify }.not_to raise_error+ end+ end++ context "when two changes share a source" do+ let(:changes) { [rename, rename.with(to: current_type.with(value: "uploads"))] }++ it "reports the repeated source" do+ expect { verify }.to raise_error(described_class::Conflict, "changes pictures twice.")+ end+ end++ context "when two changes share a destination" do+ let(:changes) { [rename, rename.with(from: previous_type.with(value: "uploads"))] }++ it "reports the repeated destination" do+ expect { verify }.to raise_error(+ described_class::Conflict,+ "changes two names into images.",+ )+ end+ end+ end+enddiff --git a/spec/lib/json_api_kit/version_change/pass_through_spec.rb b/spec/lib/json_api_kit/version_change/pass_through_spec.rbindex 2b452f886a0..780735e58dd 100644--- a/spec/lib/json_api_kit/version_change/pass_through_spec.rb+++ b/spec/lib/json_api_kit/version_change/pass_through_spec.rb@@ -5,9 +5,9 @@ RSpec.describe JsonApiKit::VersionChange::PassThrough dolet(:name) { JsonApiKit::Name::Field.new(value: "title", type: "topics") }- describe "#current" do+ describe "#current_names" doit "returns the name" do- expect(pass_through.current).to eq(name)+ expect(pass_through.current_names).to eq([name])endend@@ -25,7 +25,7 @@ RSpec.describe JsonApiKit::VersionChange::PassThrough dodescribe "#previous_pairs" doit "returns the name with the value" do- expect(pass_through.previous_pairs("A")).to eq([[name, "A"]])+ expect(pass_through.previous_pairs(name => "A")).to eq([[name, "A"]])endendenddiff --git a/spec/lib/json_api_kit/version_change/rename_spec.rb b/spec/lib/json_api_kit/version_change/rename_spec.rbindex f54f11e64f0..886ffb6f674 100644--- a/spec/lib/json_api_kit/version_change/rename_spec.rb+++ b/spec/lib/json_api_kit/version_change/rename_spec.rb@@ -8,9 +8,9 @@ RSpec.describe JsonApiKit::VersionChange::Rename dolet(:old_name) { JsonApiKit::Name::Field.new(value: "posted_at", type: "topics") }let(:new_name) { JsonApiKit::Name::Field.new(value: "created_at", type: "topics") }- describe "#current" do+ describe "#current_names" doit "returns the new name" do- expect(rename.current).to eq(new_name)+ expect(rename.current_names).to eq([new_name])endend@@ -48,7 +48,7 @@ RSpec.describe JsonApiKit::VersionChange::Rename doenddescribe "#previous_pairs" do- subject(:previous_pairs) { rename.previous_pairs(value) }+ subject(:previous_pairs) { rename.previous_pairs(new_name => value) }let(:value) { "2026-08-01" }diff --git a/spec/lib/json_api_kit/version_change/split_attributes_spec.rb b/spec/lib/json_api_kit/version_change/split_attributes_spec.rbnew file mode 100644index 00000000000..a3eb78d533d--- /dev/null+++ b/spec/lib/json_api_kit/version_change/split_attributes_spec.rb@@ -0,0 +1,122 @@+# frozen_string_literal: true++RSpec.describe JsonApiKit::VersionChange do+ subject(:version_change) { change_class.new("2026-09-01_split_dimensions.rb") }++ let(:change_class) do+ Class.new(described_class) do+ version "2026-09-01"+ description "The dimensions attribute becomes width and height."++ resource :images do+ split_attribute from: :dimensions,+ to: %i[width height],+ up: ->(dimensions) { dimensions },+ down: ->(width, height) { [width, height] }+ end+ end+ end+ let(:dimensions) { JsonApiKit::Name::Field.new(value: "dimensions", type: "images") }+ let(:width) { dimensions.with(value: "width") }+ let(:height) { dimensions.with(value: "height") }++ describe "#verify!" do+ subject(:verify) { version_change.verify! }++ before { freeze_time(Date.new(2026, 9, 3)) }++ it "accepts the split declaration" do+ expect { verify }.not_to raise_error+ end++ context "when another declaration changes the source" do+ before { change_class.resource(:images) { renamed_attribute from: :dimensions, to: :size } }++ it "rejects the repeated source" do+ expect { verify }.to raise_error(ArgumentError, /changes dimensions twice/)+ end+ end++ context "when another declaration produces a destination" do+ before { change_class.resource(:images) { renamed_attribute from: :size, to: :height } }++ it "rejects the conflicting destination" do+ expect { verify }.to raise_error(ArgumentError, /changes two names into height/)+ end+ end++ context "when a relationship produces a destination" do+ before { change_class.resource(:images) { renamed_relationship from: :size, to: :height } }++ it "rejects the conflicting field name" do+ expect { verify }.to raise_error(ArgumentError, /changes two names into height/)+ end+ end+ end++ describe "#current_names" do+ subject(:current_names) { version_change.current_names(name) }++ let(:name) { dimensions }++ it "returns every destination in declaration order" do+ expect(current_names).to eq([width, height])+ end++ context "when the name belongs to another resource" do+ let(:name) { dimensions.with(type: "other_images") }++ it "preserves the unrelated name" do+ expect(current_names).to eq([name])+ end+ end++ context "when a sort has the historical attribute name" do+ let(:name) { JsonApiKit::Name::Sort.new(value: "dimensions", type: "images") }++ it "preserves the sort name" do+ expect(current_names).to eq([name])+ end+ end++ context "when an anchor has the historical attribute name" do+ let(:name) { JsonApiKit::Name::Anchor.new(value: "dimensions", type: "images") }++ it "preserves the anchor name" do+ expect(current_names).to eq([name])+ end+ end++ context "when the same change renames the resource type" do+ let(:name) { dimensions.with(type: "pictures") }++ before { change_class.renamed_type from: :pictures, to: :images }++ it "changes the owning type before expanding the field" do+ expect(current_names).to eq([width, height])+ end+ end+ end++ describe "#previous_names" do+ it "maps either destination to the historical source" do+ expect([width, height].map { version_change.previous_names(it) }).to eq(+ [[dimensions], [dimensions]],+ )+ end+ end++ describe "#previous_attributes" do+ subject(:previous_attributes) { version_change.previous_attributes(attributes) }++ let(:attributes) { { height => 480, width => 640 } }++ context "when the same change renames the resource type" do+ before { change_class.renamed_type from: :pictures, to: :images }++ it "reconstructs the field before translating its owning type" do+ expect(previous_attributes).to eq(dimensions.with(type: "pictures") => [640, 480])+ end+ end+ end+enddiff --git a/spec/lib/json_api_kit/version_change/split_spec.rb b/spec/lib/json_api_kit/version_change/split_spec.rbnew file mode 100644index 00000000000..8301ae6b79d--- /dev/null+++ b/spec/lib/json_api_kit/version_change/split_spec.rb@@ -0,0 +1,75 @@+# frozen_string_literal: true++RSpec.describe JsonApiKit::VersionChange::Split do+ subject(:split) { described_class.new(from: dimensions, to: [width, height], up:, down:) }++ let(:dimensions) { JsonApiKit::Name::Field.new(value: "dimensions", type: "images") }+ let(:width) { dimensions.with(value: "width") }+ let(:height) { dimensions.with(value: "height") }+ let(:up) { ->(dimensions) { dimensions } }+ let(:down) { ->(width, height) { [width, height] } }++ describe "#current_names" do+ it "returns the destination names in declaration order" do+ expect(split.current_names).to eq([width, height])+ end+ end++ describe "#previous_names" do+ it "returns the historical name" do+ expect(split.previous_names).to eq([dimensions])+ end+ end++ describe "#current_pairs" do+ subject(:current_pairs) { split.current_pairs(dimensions => [640, 480]) }++ it "pairs the converted values with the destination names" do+ expect(current_pairs).to eq([[width, 640], [height, 480]])+ end+ end++ describe "#previous_pairs" do+ subject(:previous_pairs) { split.previous_pairs(attributes) }++ let(:attributes) { { height => 480, width => 640 } }++ it "reconstructs the historical value in declaration order" do+ expect(previous_pairs).to eq([[dimensions, [640, 480]]])+ end++ context "when a destination is absent" do+ let(:attributes) { super().except(height) }+ let(:down) { ->(width, height) { width * height } }++ it "omits the historical attribute without converting an incomplete group" do+ expect(previous_pairs).to be_empty+ end+ end++ context "when every destination is absent" do+ let(:attributes) { {} }+ let(:down) { ->(width, height) { width * height } }++ it "omits the historical attribute" do+ expect(previous_pairs).to be_empty+ end+ end++ context "when a destination has a null value" do+ let(:attributes) { super().merge(height => nil) }++ it "passes the null value to the converter" do+ expect(previous_pairs).to eq([[dimensions, [640, nil]]])+ end+ end++ context "when every destination has a null value" do+ let(:attributes) { { width => nil, height => nil } }++ it "passes every null value to the converter" do+ expect(previous_pairs).to eq([[dimensions, [nil, nil]]])+ end+ end+ end+enddiff --git a/spec/lib/json_api_kit/version_change/transformations_spec.rb b/spec/lib/json_api_kit/version_change/transformations_spec.rbnew file mode 100644index 00000000000..3fb637f493a--- /dev/null+++ b/spec/lib/json_api_kit/version_change/transformations_spec.rb@@ -0,0 +1,144 @@+# frozen_string_literal: true++RSpec.describe JsonApiKit::VersionChange::Transformations do+ subject(:transformations) { described_class.new([split, rename]) }++ let(:dimensions) { JsonApiKit::Name::Field.new(value: "dimensions", type: "images") }+ let(:width) { dimensions.with(value: "width") }+ let(:height) { dimensions.with(value: "height") }+ let(:title) { dimensions.with(value: "title") }+ let(:caption) { dimensions.with(value: "caption") }+ let(:other) { dimensions.with(value: "original_filename") }+ let(:split_down) { ->(width, height) { [width, height] } }+ let(:split) do+ JsonApiKit::VersionChange::Split.new(+ from: dimensions,+ to: [width, height],+ up: ->(value) { value },+ down: split_down,+ )+ end+ let(:rename) do+ JsonApiKit::VersionChange::Rename.new(+ from: title,+ to: caption,+ up: ->(title) { title.upcase },+ down: ->(caption) { caption.downcase },+ )+ end++ describe "#current_names" do+ it "returns all destinations of a split" do+ expect(transformations.current_names(dimensions)).to eq([width, height])+ end+ end++ describe "#previous_names" do+ it "finds the source from either split destination" do+ expect([width, height].map { transformations.previous_names(it) }).to eq(+ [[dimensions], [dimensions]],+ )+ end+ end++ describe "#current_values" do+ subject(:current_values) { transformations.current_values(attributes) }++ let(:attributes) { { title => "photo", dimensions => [640, 480], other => nil } }++ it "returns the current attributes" do+ expect(current_values).to eq(caption => "PHOTO", width => 640, height => 480, other => nil)+ end++ context "when the collection is empty" do+ let(:transformations) { described_class.new([]) }++ it "preserves the attributes" do+ expect(current_values).to eq(attributes)+ end+ end++ context "when several attributes select one merge" do+ let(:transformations) { described_class.new([merge]) }+ let(:attributes) { { width => 640, height => 480 } }+ let(:merge_up) { ->(width, height) { [width, height] } }+ let(:merge) do+ JsonApiKit::VersionChange::Merge.new(+ from: [width, height],+ to: dimensions,+ up: merge_up,+ down: ->(value) { value },+ )+ end++ before { allow(merge_up).to receive(:call).and_call_original }++ it "applies the merge once" do+ current_values+ expect(merge_up).to have_received(:call).with(640, 480).once+ end++ it "combines the source values" do+ expect(current_values).to eq(dimensions => [640, 480])+ end+ end+ end++ describe "#previous_values" do+ subject(:previous_values) { transformations.previous_values(attributes) }++ let(:attributes) { { caption => "PHOTO", height => 480, width => 640, other => nil } }++ it "returns the historical attributes" do+ expect(previous_values).to eq(title => "photo", dimensions => [640, 480], other => nil)+ end++ context "when several attributes select one split" do+ before { allow(split_down).to receive(:call).and_call_original }++ it "applies the split once" do+ previous_values+ expect(split_down).to have_received(:call).with(640, 480).once+ end+ end++ context "when a split destination is absent" do+ let(:attributes) { super().except(height) }++ it "omits the incomplete historical attribute" do+ expect(previous_values).to eq(title => "photo", other => nil)+ end+ end++ context "when no attribute is present" do+ let(:attributes) { {} }++ it "produces no attributes" do+ expect(previous_values).to be_empty+ end+ end+ end++ describe "#verify!" do+ subject(:verify) { transformations.verify! }++ context "when a rename produces a split destination" do+ let(:rename) { super().with(to: height) }++ it "reports the conflicting destination" do+ expect { verify }.to raise_error(+ described_class::Conflict,+ "changes two names into height.",+ )+ end+ end++ context "when another resource has the same destination" do+ let(:rename) { super().with(to: height.with(type: "other_images")) }++ it "accepts the distinct names" do+ expect { verify }.not_to raise_error+ end+ end+ end+enddiff --git a/spec/lib/json_api_kit/version_change/type_renames_spec.rb b/spec/lib/json_api_kit/version_change/type_renames_spec.rbindex dd62cc65d3b..2ac9843acf9 100644--- a/spec/lib/json_api_kit/version_change/type_renames_spec.rb+++ b/spec/lib/json_api_kit/version_change/type_renames_spec.rb@@ -1,5 +1,66 @@# frozen_string_literal: true+RSpec.describe JsonApiKit::VersionChange::TypeRenames do+ subject(:type_renames) { described_class.new(renames) }++ let(:previous_type) { JsonApiKit::Name::Type.new(value: "pictures") }+ let(:current_type) { JsonApiKit::Name::Type.new(value: "images") }+ let(:rename) { JsonApiKit::VersionChange::TypeRename.new(from: previous_type, to: current_type) }+ let(:renames) { [rename] }++ describe "#current" do+ subject(:current) { type_renames.current(type) }++ let(:type) { "pictures" }++ it "returns the current type string" do+ expect(current).to eq("images")+ end++ context "when the type has no rename" do+ let(:type) { "users" }++ it "preserves the type" do+ expect(current).to eq("users")+ end+ end++ context "when the collection is empty" do+ let(:renames) { [] }++ it "preserves the type" do+ expect(current).to eq("pictures")+ end+ end+ end++ describe "#previous" do+ subject(:previous) { type_renames.previous(type) }++ let(:type) { "images" }++ it "returns the historical type string" do+ expect(previous).to eq("pictures")+ end++ context "when the type has no rename" do+ let(:type) { "users" }++ it "preserves the type" do+ expect(previous).to eq("users")+ end+ end++ context "when the collection is empty" do+ let(:renames) { [] }++ it "preserves the type" do+ expect(previous).to eq("images")+ end+ end+ end+end+RSpec.describe JsonApiKit::VersionChange dosubject(:version_change) { change_class.new("2026-09-02_rename_types.rb") }@@ -64,20 +125,20 @@ RSpec.describe JsonApiKit::VersionChange doendend- describe "#current" do- subject(:current_name) { version_change.current(name) }+ describe "#current_names" do+ subject(:current_names) { version_change.current_names(name) }let(:name) { field }it "changes the owning type before the field name" do- expect(current_name).to eq(field.with(value: "name", type: "items"))+ expect(current_names).to eq([field.with(value: "name", type: "items")])endcontext "when the name is a type" dolet(:name) { JsonApiKit::Name::Type.new(value: "things") }it "changes the type value" do- expect(current_name).to eq(name.with(value: "items"))+ expect(current_names).to eq([name.with(value: "items")])endend@@ -85,7 +146,7 @@ RSpec.describe JsonApiKit::VersionChange dolet(:name) { JsonApiKit::Name::Member.new(value: "things") }it "preserves the member name" do- expect(current_name).to eq(name)+ expect(current_names).to eq([name])endend@@ -93,7 +154,7 @@ RSpec.describe JsonApiKit::VersionChange dolet(:name) { field.with(type: "people") }it "preserves the field name" do- expect(current_name).to eq(name)+ expect(current_names).to eq([name])endend@@ -101,7 +162,7 @@ RSpec.describe JsonApiKit::VersionChange dolet(:name) { JsonApiKit::Name::Relationship.new(value: "things", type: "things") }it "changes only the owning type" do- expect(current_name).to eq(name.with(type: "items"))+ expect(current_names).to eq([name.with(type: "items")])endend@@ -109,7 +170,7 @@ RSpec.describe JsonApiKit::VersionChange dolet(:name) { JsonApiKit::Name::Sort.new(value: "things.first", type: "things") }it "preserves the path" do- expect(current_name).to eq(name.with(type: "items"))+ expect(current_names).to eq([name.with(type: "items")])endendend@@ -148,34 +209,24 @@ RSpec.describe JsonApiKit::VersionChange doendend- describe "#previous" do- subject(:previous_name) { version_change.previous(name) }+ describe "#previous_names" do+ subject(:previous_names) { version_change.previous_names(name) }let(:name) { field.with(value: "name", type: "items") }- it "changes the field before its owning type" do- expect(previous_name).to eq(field)+ it "reverses the type change for each merge component" do+ expect(previous_names).to eq([field, field.with(value: "last")])endcontext "when the name is a type" dolet(:name) { JsonApiKit::Name::Type.new(value: "items") }it "reverses the type change" do- expect(previous_name).to eq(name.with(value: "things"))+ expect(previous_names).to eq([name.with(value: "things")])endendend- describe "#previous_names" do- subject(:previous_names) do- version_change.previous_names(field.with(value: "name", type: "items"))- end-- it "reverses the type change for each merge component" do- expect(previous_names).to eq([field, field.with(value: "last")])- end- end-describe "#previous_attributes" dosubject(:previous_attributes) { version_change.previous_attributes(attributes) }diff --git a/spec/lib/json_api_kit/version_change_spec.rb b/spec/lib/json_api_kit/version_change_spec.rbindex e44f9e32ac9..5bd3a7d7b02 100644--- a/spec/lib/json_api_kit/version_change_spec.rb+++ b/spec/lib/json_api_kit/version_change_spec.rb@@ -151,18 +151,18 @@ RSpec.describe JsonApiKit::VersionChange doendend- describe "#current" do- subject(:current_name) { version_change.current(name) }+ describe "#current_names" do+ subject(:current_names) { version_change.current_names(name) }it "returns the name after the change" do- expect(current_name).to eq(name.with(value: "name"))+ expect(current_names).to eq([name.with(value: "name")])endcontext "when the name is the sort derived from the attribute" dolet(:name) { JsonApiKit::Name::Sort.new(value: "label", type: "things") }it "renames it" do- expect(current_name).to eq(name.with(value: "name"))+ expect(current_names).to eq([name.with(value: "name")])endend@@ -170,7 +170,7 @@ RSpec.describe JsonApiKit::VersionChange dolet(:name) { JsonApiKit::Name::Anchor.new(value: "label", type: "things") }it "renames it" do- expect(current_name).to eq(name.with(value: "name"))+ expect(current_names).to eq([name.with(value: "name")])endend@@ -178,14 +178,14 @@ RSpec.describe JsonApiKit::VersionChange dolet(:name) { JsonApiKit::Name::Filter.new(value: "label", type: "things") }it "returns the name" do- expect(current_name).to eq(name)+ expect(current_names).to eq([name])endcontext "when the change renames the filter" dolet(:change_class) { JsonApiKitSpec::RenameThingsSortAndFilter }it "returns the new name of the filter" do- expect(current_name).to eq(name.with(value: "name"))+ expect(current_names).to eq([name.with(value: "name")])endendend@@ -195,18 +195,18 @@ RSpec.describe JsonApiKit::VersionChange dolet(:name) { JsonApiKit::Name::Field.new(value: "posted_time", type: "things") }it "returns the name it merges into" do- expect(current_name).to eq(name.with(value: "posted_at"))+ expect(current_names).to eq([name.with(value: "posted_at")])endendcontext "with several resources" do+ subject(:current_names) { [name, other_name].flat_map { version_change.current_names(it) } }+let(:change_class) { JsonApiKitSpec::RenameThingsAndPeople }let(:other_name) { JsonApiKit::Name::Field.new(value: "handle", type: "people") }it "renames the names of every resource" do- expect([version_change.current(name), version_change.current(other_name)]).to eq(- [name.with(value: "name"), other_name.with(value: "username")],- )+ expect(current_names).to eq([name.with(value: "name"), other_name.with(value: "username")])endendend@@ -255,25 +255,6 @@ RSpec.describe JsonApiKit::VersionChange doendend- describe "#previous" do- subject(:previous_name) { version_change.previous(name) }-- let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }-- it "returns the name before the change" do- expect(previous_name).to eq(name.with(value: "label"))- end-- context "when the change merges several names into the name" do- let(:change_class) { JsonApiKitSpec::MergeThingsDateAndTimeIntoPostedAt }- let(:name) { JsonApiKit::Name::Field.new(value: "posted_at", type: "things") }-- it "returns the first of them" do- expect(previous_name).to eq(name.with(value: "posted_date"))- end- end- end-describe "#previous_names" dosubject(:previous_names) { version_change.previous_names(name) }