A platform for community discussion. Free, open, simple.
DEV: Add version changes to the JSON:API kit (#43196)
Loïc Guitaut44cb8b773cc8
diff --git a/app/controllers/json_api_kit/base_controller/versioning.rb b/app/controllers/json_api_kit/base_controller/versioning.rbindex 4c4c515327a..664ccd8996f 100644--- a/app/controllers/json_api_kit/base_controller/versioning.rb+++ b/app/controllers/json_api_kit/base_controller/versioning.rb@@ -10,14 +10,16 @@ module JsonApiKitprivatedef resolve_version- response.headers[ApiVersion::HEADER] = Timeline.resolve(requested_version).to_s+ response.headers[ApiVersion::HEADER] = version.to_srescue Error => errorrender_document(Document::Errors.new(error))end+ def version = @version ||= Timeline.resolve(requested_version)+def requested_version = request.headers[ApiVersion::HEADER]- def glossary = @glossary ||= Glossary.resource+ def glossary = @glossary ||= Glossary.resource(version)endendenddiff --git a/config/api_changes/.keep b/config/api_changes/.keepnew file mode 100644index 00000000000..e69de29bb2ddiff --git a/config/initializers/json_api_kit.rb b/config/initializers/json_api_kit.rbnew file mode 100644index 00000000000..f9f14e04f4c--- /dev/null+++ b/config/initializers/json_api_kit.rb@@ -0,0 +1,3 @@+# frozen_string_literal: true++Rails.application.config.after_initialize { JsonApiKit::VersionChange.all }diff --git a/lib/json_api_kit/api_version.rb b/lib/json_api_kit/api_version.rbindex b80d2e190c2..99efa090a4c 100644--- a/lib/json_api_kit/api_version.rb+++ b/lib/json_api_kit/api_version.rb@@ -64,6 +64,10 @@ module JsonApiKitdate <=> other.dateend+ def eql?(other) = (self <=> other) == 0++ def hash = date.hash+def future? = date.future?def to_s = date.iso8601diff --git a/lib/json_api_kit/document.rb b/lib/json_api_kit/document.rbindex fcd42bc10c6..bc0e29694bd 100644--- a/lib/json_api_kit/document.rb+++ b/lib/json_api_kit/document.rb@@ -3,7 +3,8 @@module JsonApiKitclass Documentdef self.build(parameters, resource:, urls:, glossary:)- declared_parameters = Request::Parameters.new(parameters.to_hash, glossary:).to_h+ declared_parameters =+ Request::Parameters.new(parameters.to_hash.deep_stringify_keys, glossary:, resource:).to_hcontract_class.new(**declared_parameters.deep_dup,diff --git a/lib/json_api_kit/document/resource_object.rb b/lib/json_api_kit/document/resource_object.rbindex dad3f279e9c..3456fa8dbf9 100644--- a/lib/json_api_kit/document/resource_object.rb+++ b/lib/json_api_kit/document/resource_object.rb@@ -18,11 +18,17 @@ module JsonApiKitattr_reader :record, :urls, :glossary, :meta- def attributes = record.attributes.transform_keys { glossary.member_name(it) }+ def field(value) = Name::Field.new(value:, type:)++ def relationship(value) = Name::Relationship.new(value:, type:)++ def member_value(name) = glossary.member_name(name).value++ def attributes = record.attributes.transform_keys { member_value(field(it)) }def relationshipsrecord.relationships.to_h do |name, linkage|- member = glossary.member_name(name)+ member = member_value(relationship(name))[member, RelationshipObject.new(linkage, urls:, owner: record, name: member).to_h]endenddiff --git a/lib/json_api_kit/glossary.rb b/lib/json_api_kit/glossary.rbindex 7bf2bf809ef..ea55a93528e 100644--- a/lib/json_api_kit/glossary.rb+++ b/lib/json_api_kit/glossary.rb@@ -2,18 +2,47 @@module JsonApiKitclass Glossary+ class Correction < StandardError+ attr_reader :name++ def initialize(name)+ @name = name+ super("Use #{name}.")+ end+ end++ class NotAMemberName < BadRequest+ attr_reader :raw, :member++ def initialize(raw, member, parameter: nil)+ @raw = raw+ @member = member+ @parameter = parameter+ super("Use #{member}, not #{raw}.")+ end++ def title = "Invalid member name"++ def source = { parameter: @parameter }.compact++ def at(parameter) = self.class.new(raw, member, parameter:)+ end+class << selfdef kit = new([CasingRule])- # TODO: add the versioning rule here (next PR)- def resource = kit+ def resource(version) = new([CasingRule, VersionRule.new(version)])enddef initialize(rules)@rules = rulesend- def declared_name(raw) = rules.reduce(raw) { |name, rule| rule.declared_name(name) }+ def declared_name(name)+ rules.reduce(name) { |result, rule| rule.declared_name(result) }+ rescue Correction => correction+ raise NotAMemberName.new(name, member_name(correction.name))+ enddef member_name(name)rules.reverse_each.reduce(name) { |member, rule| rule.member_name(member) }diff --git a/lib/json_api_kit/glossary/casing_rule.rb b/lib/json_api_kit/glossary/casing_rule.rbindex ea250f81939..6c4d6a0870f 100644--- a/lib/json_api_kit/glossary/casing_rule.rb+++ b/lib/json_api_kit/glossary/casing_rule.rb@@ -6,33 +6,19 @@ module JsonApiKitCAMEL_BOUNDARY = /(?<before>[a-z\d])(?<capital>[A-Z])/SNAKE_BOUNDARY = /_(?<letter>[a-z\d])/- class NotAMemberName < BadRequest- attr_reader :raw, :member-- def initialize(raw, member, parameter: nil)- @raw = raw- @member = member- @parameter = parameter- super("Use #{member}, not #{raw}.")- end-- def title = "Invalid member name"-- def source = { parameter: @parameter }.compact-- def at(parameter) = self.class.new(raw, member, parameter:)- end-class << self- def declared_name(raw)- name = raw.to_s.gsub(CAMEL_BOUNDARY, '\k<before>_\k<capital>').downcase- member = member_name(name)- raise NotAMemberName.new(raw, member) unless member == raw.to_s- name+ def declared_name(name)+ snake_case(name).tap { raise Correction.new(it) unless member_name(it) == name }enddef member_name(name)- name.to_s.gsub(SNAKE_BOUNDARY) { Regexp.last_match[:letter].upcase }+ name.convert { it.gsub(SNAKE_BOUNDARY) { Regexp.last_match[:letter].upcase } }+ end++ private++ def snake_case(name)+ name.convert { it.gsub(CAMEL_BOUNDARY, '\k<before>_\k<capital>').downcase }endendenddiff --git a/lib/json_api_kit/glossary/version_rule.rb b/lib/json_api_kit/glossary/version_rule.rbnew file mode 100644index 00000000000..b11a4dcc8da--- /dev/null+++ b/lib/json_api_kit/glossary/version_rule.rb@@ -0,0 +1,25 @@+# frozen_string_literal: true++module JsonApiKit+ class Glossary+ class VersionRule+ def initialize(version)+ @changes = VersionChange.after(version)+ end++ def declared_name(name)+ current_name(name).tap { raise Correction.new(it) unless member_name(it) == name }+ end++ def member_name(name)+ changes.reverse_each.reduce(name) { |result, change| change.previous(result) }+ end++ private++ attr_reader :changes++ def current_name(name) = changes.reduce(name) { |result, change| change.current(result) }+ end+ end+enddiff --git a/lib/json_api_kit/name.rb b/lib/json_api_kit/name.rbnew file mode 100644index 00000000000..3b2d4022fb1--- /dev/null+++ b/lib/json_api_kit/name.rb@@ -0,0 +1,9 @@+# frozen_string_literal: true++module JsonApiKit+ module Name+ def convert = with(value: yield(value))++ def to_s = value+ end+enddiff --git a/lib/json_api_kit/name/anchor.rb b/lib/json_api_kit/name/anchor.rbnew file mode 100644index 00000000000..7ce5bbea41b--- /dev/null+++ b/lib/json_api_kit/name/anchor.rb@@ -0,0 +1,12 @@+# frozen_string_literal: true++module JsonApiKit+ module Name+ Anchor =+ Data.define(:value, :type) do+ include Name++ def kind = :anchor+ end+ end+enddiff --git a/lib/json_api_kit/name/field.rb b/lib/json_api_kit/name/field.rbnew file mode 100644index 00000000000..b44a3e0bd62--- /dev/null+++ b/lib/json_api_kit/name/field.rb@@ -0,0 +1,12 @@+# frozen_string_literal: true++module JsonApiKit+ module Name+ Field =+ Data.define(:value, :type) do+ include Name++ def kind = :field+ end+ end+enddiff --git a/lib/json_api_kit/name/filter.rb b/lib/json_api_kit/name/filter.rbnew file mode 100644index 00000000000..7af6576c613--- /dev/null+++ b/lib/json_api_kit/name/filter.rb@@ -0,0 +1,12 @@+# frozen_string_literal: true++module JsonApiKit+ module Name+ Filter =+ Data.define(:value, :type) do+ include Name++ def kind = :filter+ end+ end+enddiff --git a/lib/json_api_kit/name/member.rb b/lib/json_api_kit/name/member.rbnew file mode 100644index 00000000000..50b399d49ba--- /dev/null+++ b/lib/json_api_kit/name/member.rb@@ -0,0 +1,12 @@+# frozen_string_literal: true++module JsonApiKit+ module Name+ Member =+ Data.define(:value) do+ include Name++ def kind = :member+ end+ end+enddiff --git a/lib/json_api_kit/name/relationship.rb b/lib/json_api_kit/name/relationship.rbnew file mode 100644index 00000000000..9703d8b9269--- /dev/null+++ b/lib/json_api_kit/name/relationship.rb@@ -0,0 +1,12 @@+# frozen_string_literal: true++module JsonApiKit+ module Name+ Relationship =+ Data.define(:value, :type) do+ include Name++ def kind = :relationship+ end+ end+enddiff --git a/lib/json_api_kit/name/sort.rb b/lib/json_api_kit/name/sort.rbnew file mode 100644index 00000000000..9a6ea28f791--- /dev/null+++ b/lib/json_api_kit/name/sort.rb@@ -0,0 +1,12 @@+# frozen_string_literal: true++module JsonApiKit+ module Name+ Sort =+ Data.define(:value, :type) do+ include Name++ def kind = :sort+ end+ end+enddiff --git a/lib/json_api_kit/request/contract/error.rb b/lib/json_api_kit/request/contract/error.rbindex 3c07da50bf8..e9976fc74b1 100644--- a/lib/json_api_kit/request/contract/error.rb+++ b/lib/json_api_kit/request/contract/error.rb@@ -26,12 +26,12 @@ module JsonApiKitdef meta = @meta&.call(self) || {}def parameter- ParameterName.new(*error.attribute.to_s.split(".").map { member_name(it) })+ ParameterName.new(*error.attribute.to_s.split(".").map { member_value(member(it)) })end- def name = member_name(options[:name])+ def name = member_value(options[:name])- def key = member_name(options[:key])+ def key = member_value(options[:key])def member_parameter(member = name) = parameter.member(member)@@ -45,9 +45,11 @@ module JsonApiKitattr_reader :error, :glossary- def member_name(name) = glossary.member_name(name)+ def member_value(name) = glossary.member_name(name).value- def page_parameter(name) = parameter.family.member(member_name(name))+ def member(value) = Name::Member.new(value: value.to_s)++ def page_parameter(name) = parameter.family.member(member_value(member(name)))endendenddiff --git a/lib/json_api_kit/request/contract/fields.rb b/lib/json_api_kit/request/contract/fields.rbindex f2306f21d5f..d473c01cce5 100644--- a/lib/json_api_kit/request/contract/fields.rb+++ b/lib/json_api_kit/request/contract/fields.rb@@ -36,7 +36,7 @@ module JsonApiKitdef check_fieldsfields.each_key do |type|next if fields[type].is_a?(Array)- errors.add(:fields, :bad_value, name: type, message: "bad value")+ errors.add(:fields, :bad_value, type:, message: "bad value")endendenddiff --git a/lib/json_api_kit/request/contract/filtering.rb b/lib/json_api_kit/request/contract/filtering.rbindex 8bf1c63586f..4c61916fcf2 100644--- a/lib/json_api_kit/request/contract/filtering.rb+++ b/lib/json_api_kit/request/contract/filtering.rb@@ -15,12 +15,24 @@ module JsonApiKitprivate- def check_filter_names = refuse_unknown(:filter, filter.keys - resource.filter_names)+ def check_filter_names+ refuse_unknown(+ :filter,+ (filter.keys - resource.filter_names).map do+ Name::Filter.new(value: it.to_s, type: resource.type)+ end,+ )+ enddef check_filter_valuesfilter.each_key do |name|next if comparable?(filter[name]) || listed?(filter[name])- errors.add(:filter, :bad_value, name:, message: "bad value")+ errors.add(+ :filter,+ :bad_value,+ name: Name::Filter.new(value: name.to_s, type: resource.type),+ message: "bad value",+ )endenddiff --git a/lib/json_api_kit/request/contract/including.rb b/lib/json_api_kit/request/contract/including.rbindex ff19d7fc2f2..d3203a3680b 100644--- a/lib/json_api_kit/request/contract/including.rb+++ b/lib/json_api_kit/request/contract/including.rb@@ -26,7 +26,13 @@ module JsonApiKitprivatedef check_include_paths- refuse_unknown(:include, Paths.new(include).reject { resource.paths_include?(it) })+ refuse_unknown(+ :include,+ Paths+ .new(include)+ .reject { resource.paths_include?(it) }+ .map { Name::Member.new(value: it.to_s) },+ )endendenddiff --git a/lib/json_api_kit/request/contract/mapper.rb b/lib/json_api_kit/request/contract/mapper.rbindex cf6c4a533c8..02765e4910f 100644--- a/lib/json_api_kit/request/contract/mapper.rb+++ b/lib/json_api_kit/request/contract/mapper.rb@@ -84,9 +84,9 @@ module JsonApiKit%i[fields bad_value] => {title: "Invalid fields value",detail: ->(error) do- "#{error.member_parameter(error.options[:name])} must be a list of field names."+ "#{error.member_parameter(error.options[:type])} must be a list of field names."end,- source: ->(error) { error.member_parameter(error.options[:name]) },+ source: ->(error) { error.member_parameter(error.options[:type]) },},%i[sort bad_shape] => {title: "Invalid sort parameter",diff --git a/lib/json_api_kit/request/contract/paging.rb b/lib/json_api_kit/request/contract/paging.rbindex a3997aab18e..edebe2cc9bf 100644--- a/lib/json_api_kit/request/contract/paging.rb+++ b/lib/json_api_kit/request/contract/paging.rb@@ -115,13 +115,23 @@ module JsonApiKitdef check_anchor_name([anchor_name.to_s] - resource.anchor_names).each do- errors.add(:anchor, :no_such_name, name: it, message: "no such name")+ errors.add(+ :anchor,+ :no_such_name,+ name: Name::Anchor.new(value: it.to_s, type: resource.type),+ message: "no such name",+ )endenddef check_anchor_valuereturn unless anchor_value.is_a?(Enumerable)- errors.add(:anchor, :bad_value, name: anchor_name, message: "bad value")+ errors.add(+ :anchor,+ :bad_value,+ name: Name::Anchor.new(value: anchor_name.to_s, type: resource.type),+ message: "bad value",+ )enddef check_anchor_ordering@@ -129,8 +139,12 @@ module JsonApiKiterrors.add(:anchor,:not_the_sort,- name: anchor_name,- key: resource.order(ordering).leading.name,+ name: Name::Anchor.new(value: anchor_name.to_s, type: resource.type),+ key:+ Name::Sort.new(+ value: resource.order(ordering).leading.name.to_s,+ type: resource.type,+ ),message: "not the sort",)enddiff --git a/lib/json_api_kit/request/contract/sorting.rb b/lib/json_api_kit/request/contract/sorting.rbindex 57c0673aa62..24c98de4b65 100644--- a/lib/json_api_kit/request/contract/sorting.rb+++ b/lib/json_api_kit/request/contract/sorting.rb@@ -37,7 +37,14 @@ module JsonApiKitprivate- def check_sort_names = refuse_unknown(:sort, sort.keys - resource.sort_names)+ def check_sort_names+ refuse_unknown(+ :sort,+ (sort.keys - resource.sort_names).map do+ Name::Sort.new(value: it.to_s, type: resource.type)+ end,+ )+ enddef check_sort_directionssort.each_value do |direction|diff --git a/lib/json_api_kit/request/family.rb b/lib/json_api_kit/request/family.rbnew file mode 100644index 00000000000..83905dbf525--- /dev/null+++ b/lib/json_api_kit/request/family.rb@@ -0,0 +1,43 @@+# frozen_string_literal: true++module JsonApiKit+ class Request+ class Family+ LIST = ","+ LIST_ITEM = /\A(?<direction>-?)(?<name>.*)\z/m++ def initialize(glossary:, type:)+ @glossary = glossary+ @type = type+ end++ private++ attr_reader :glossary, :type++ def names(value, path, &name_for)+ case value+ when Hash+ value.transform_keys { declared_name(name_for.call(it), path + [it]) }+ when Array+ value.map { names(it, path, &name_for) }+ when String, Symbol+ value.to_s.split(LIST, -1).map { list_item(it, path, &name_for) }.join(LIST)+ else+ value+ end+ end++ def list_item(value, path)+ direction, name = LIST_ITEM.match(value).captures+ "#{direction}#{declared_name(yield(name), path)}"+ end++ def declared_name(name, path)+ glossary.declared_name(name).value+ rescue Glossary::NotAMemberName => error+ raise error.at(ParameterName.new(*path).to_s)+ end+ end+ end+enddiff --git a/lib/json_api_kit/request/family/fields.rb b/lib/json_api_kit/request/family/fields.rbnew file mode 100644index 00000000000..8d893094eaf--- /dev/null+++ b/lib/json_api_kit/request/family/fields.rb@@ -0,0 +1,21 @@+# frozen_string_literal: true++module JsonApiKit+ class Request+ class Family+ class Fields < Family+ def declared_value(value, path)+ return value unless value.is_a?(Hash)+ value.to_h do |fieldset_type, fields|+ [+ fieldset_type,+ names(fields, path + [fieldset_type]) do+ Name::Field.new(value: it, type: fieldset_type)+ end,+ ]+ end+ end+ end+ end+ end+enddiff --git a/lib/json_api_kit/request/family/filter.rb b/lib/json_api_kit/request/family/filter.rbnew file mode 100644index 00000000000..2fa716dedac--- /dev/null+++ b/lib/json_api_kit/request/family/filter.rb@@ -0,0 +1,14 @@+# frozen_string_literal: true++module JsonApiKit+ class Request+ class Family+ class Filter < Family+ def declared_value(value, path)+ return value unless value.is_a?(Hash)+ value.transform_keys { declared_name(Name::Filter.new(value: it, type:), path + [it]) }+ end+ end+ end+ end+enddiff --git a/lib/json_api_kit/request/family/include.rb b/lib/json_api_kit/request/family/include.rbnew file mode 100644index 00000000000..3289b29ac2f--- /dev/null+++ b/lib/json_api_kit/request/family/include.rb@@ -0,0 +1,11 @@+# frozen_string_literal: true++module JsonApiKit+ class Request+ class Family+ class Include < Family+ def declared_value(value, path) = names(value, path) { Name::Member.new(value: it) }+ end+ end+ end+enddiff --git a/lib/json_api_kit/request/family/other.rb b/lib/json_api_kit/request/family/other.rbnew file mode 100644index 00000000000..f0217aa64b6--- /dev/null+++ b/lib/json_api_kit/request/family/other.rb@@ -0,0 +1,11 @@+# frozen_string_literal: true++module JsonApiKit+ class Request+ class Family+ class Other < Family+ def declared_value(value, _path) = value+ end+ end+ end+enddiff --git a/lib/json_api_kit/request/family/page.rb b/lib/json_api_kit/request/family/page.rbnew file mode 100644index 00000000000..530b2da38f1--- /dev/null+++ b/lib/json_api_kit/request/family/page.rb@@ -0,0 +1,23 @@+# frozen_string_literal: true++module JsonApiKit+ class Request+ class Family+ class Page < Family+ ANCHOR = "anchor"++ def declared_value(value, path)+ return value unless value.is_a?(Hash)+ value.to_h do |member, member_value|+ key = declared_name(Name::Member.new(value: member), path + [member])+ [key, key == ANCHOR ? anchor(member_value, path + [key]) : member_value]+ end+ end++ private++ def anchor(value, path) = names(value, path) { Name::Anchor.new(value: it, type:) }+ end+ end+ end+enddiff --git a/lib/json_api_kit/request/family/sort.rb b/lib/json_api_kit/request/family/sort.rbnew file mode 100644index 00000000000..841e9fe6849--- /dev/null+++ b/lib/json_api_kit/request/family/sort.rb@@ -0,0 +1,11 @@+# frozen_string_literal: true++module JsonApiKit+ class Request+ class Family+ class Sort < Family+ def declared_value(value, path) = names(value, path) { Name::Sort.new(value: it, type:) }+ end+ end+ end+enddiff --git a/lib/json_api_kit/request/parameters.rb b/lib/json_api_kit/request/parameters.rbindex 85653547a15..8f5f272a397 100644--- a/lib/json_api_kit/request/parameters.rb+++ b/lib/json_api_kit/request/parameters.rb@@ -3,56 +3,37 @@module JsonApiKitclass Requestclass Parameters- FIELDSETS_AT = %w[fields].freeze- NAMES_AT = [%w[sort], %w[include], %w[page anchor]].freeze-- def initialize(raw, glossary:)+ FAMILIES = {+ "fields" => Family::Fields,+ "sort" => Family::Sort,+ "filter" => Family::Filter,+ "page" => Family::Page,+ "include" => Family::Include,+ }.freeze++ def initialize(raw, glossary:, resource:)@raw = raw@glossary = glossary+ @resource = resourceend- def to_h = declared_names(raw, [])-- private-- attr_reader :raw, :glossary-- def declared_names(parameters, path)- parameters.to_h do |name, value|- key = declared_at(name, path + [name.to_s])- [key, declared_value(value, path + [key])]+ def to_h+ raw.to_h do |family, value|+ key = declared_name(family)+ [key, family_for(key).declared_value(value, [key])]endend- def declared_value(value, path)- return fieldsets(value, path) if path == FIELDSETS_AT- return names(value, path) if path.in?(NAMES_AT)- return declared_names(value, path) if value.is_a?(Hash)- value- end+ private- def fieldsets(value, path)- return value unless value.is_a?(Hash)- value.to_h { |type, fields| [type, names(fields, path + [type.to_s])] }- end+ attr_reader :raw, :glossary, :resource- def names(value, path)- case value- when Hash- value.transform_keys { declared_at(it, path + [it.to_s]) }- when Array- value.map { names(it, path) }- when String, Symbol- declared_at(value, path)- else- value- end- end+ def family_for(key) = FAMILIES.fetch(key, Family::Other).new(glossary:, type: resource.type)- def declared_at(raw, path)- glossary.declared_name(raw)- rescue Glossary::CasingRule::NotAMemberName => error- raise error.at(ParameterName.new(*path).to_s)+ def declared_name(family)+ glossary.declared_name(Name::Member.new(value: family)).value+ rescue Glossary::NotAMemberName => error+ raise error.at(ParameterName.new(family).to_s)endendenddiff --git a/lib/json_api_kit/timeline.rb b/lib/json_api_kit/timeline.rbindex 930dba58dd6..8e96ceb8043 100644--- a/lib/json_api_kit/timeline.rb+++ b/lib/json_api_kit/timeline.rb@@ -10,7 +10,7 @@ module JsonApiKitprivate- def core = @core ||= new([FIRST_RELEASE])+ def core = new([FIRST_RELEASE, *VersionChange.all.map(&:version)].uniq)enddef initialize(versions)diff --git a/lib/json_api_kit/url.rb b/lib/json_api_kit/url.rbindex 0383677581a..e04f0e25c34 100644--- a/lib/json_api_kit/url.rb+++ b/lib/json_api_kit/url.rb@@ -7,8 +7,7 @@ module JsonApiKitKIT = Glossary.kitREPLACED_MEMBERS =%w[after before anchor before_size after_size include_anchor]- .map { KIT.member_name(it) }- .freeze+ .map { KIT.member_name(Name::Member.new(value: it)).value }.freezedef initialize(address, parameters = {})@@ -33,7 +32,9 @@ module JsonApiKitdef page_parameters = parameters.fetch(PAGE, {})- def member_names(page) = page.transform_keys { KIT.member_name(it) }+ def member_names(page)+ page.transform_keys { KIT.member_name(Name::Member.new(value: it.to_s)).value }+ enddef query_string = Rack::Utils.build_nested_query(parameters).presence.try { "?#{it}" }enddiff --git a/lib/json_api_kit/version_change.rb b/lib/json_api_kit/version_change.rbnew file mode 100644index 00000000000..06db6587afd--- /dev/null+++ b/lib/json_api_kit/version_change.rb@@ -0,0 +1,80 @@+# frozen_string_literal: true++module JsonApiKit+ class VersionChange+ CHANGES_DIRECTORY = Rails.root.join("config/api_changes")+ DATE_PREFIX = /\A\d{4}-\d{2}-\d{2}_/++ class << self+ def all = @all ||= read(CHANGES_DIRECTORY)++ def after(version) = all.select { it.version > version }++ def read(directory)+ Dir+ .glob(directory.join("*.rb"))+ .map { change_in(it) }+ .each(&:verify!)+ .sort_by { [it.version, it.source] }+ end++ def version(raw = nil)+ @version = ApiVersion.parse(raw) if raw+ @version+ rescue ApiVersion::NotADate+ raise ArgumentError, "The version of #{self}, #{raw}, is not a date."+ end++ def description(text = nil)+ @description = text if text+ @description+ end++ def resource(type, &declarations)+ transformations.concat(Declarations.new(type).tap { it.instance_eval(&declarations) }.to_a)+ end++ def transformations = @transformations ||= []++ private++ def change_in(source)+ constant = File.basename(source, ".rb").sub(DATE_PREFIX, "").camelize+ Object.send(:remove_const, constant) if Object.const_defined?(constant, false)+ load source+ constant.constantize.new(source)+ end+ end++ delegate :version, :description, :transformations, to: :class++ attr_reader :source++ def initialize(source)+ @source = source+ end++ def verify!+ raise ArgumentError, "#{source} has no version." if version.nil?+ raise ArgumentError, "#{source} is dated in the future." if version.future?+ if version <= Timeline::FIRST_RELEASE+ raise ArgumentError, "#{source} is dated on or before the first release."+ end+ raise ArgumentError, "#{source} has no description." if description.blank?+ return if File.basename(source).start_with?(version.to_s)+ raise ArgumentError, "The file name must start with the version #{version}: #{source}."+ end++ def current(name)+ transformations.reduce(name) { |result, transformation| transformation.current(result) }+ end++ def previous(name)+ transformations+ .reverse_each+ .reduce(name) { |result, transformation| transformation.previous(result) }+ end++ def introduces?(name) = transformations.any? { it.introduces?(name) }+ end+enddiff --git a/lib/json_api_kit/version_change/declarations.rb b/lib/json_api_kit/version_change/declarations.rbnew file mode 100644index 00000000000..50aa15ea8bc--- /dev/null+++ b/lib/json_api_kit/version_change/declarations.rb@@ -0,0 +1,26 @@+# frozen_string_literal: true++module JsonApiKit+ class VersionChange+ class Declarations+ DERIVED_FROM_AN_ATTRIBUTE = %i[field sort anchor].freeze++ def initialize(type)+ @type = type.to_s+ @transformations = []+ end++ def renamed_attribute(from:, to:)+ DERIVED_FROM_AN_ATTRIBUTE.each do+ transformations << Rename.new(kind: it, type:, from: from.to_s, to: to.to_s)+ end+ end++ def to_a = transformations++ private++ attr_reader :type, :transformations+ end+ end+enddiff --git a/lib/json_api_kit/version_change/rename.rb b/lib/json_api_kit/version_change/rename.rbnew file mode 100644index 00000000000..bb0749e2cf8--- /dev/null+++ b/lib/json_api_kit/version_change/rename.rb@@ -0,0 +1,24 @@+# frozen_string_literal: true++module JsonApiKit+ class VersionChange+ Rename =+ Data.define(:kind, :type, :from, :to) do+ def current(name)+ return name unless applies_to?(name) && name.value == from+ name.with(value: to)+ end++ def previous(name)+ return name unless introduces?(name)+ name.with(value: from)+ end++ def introduces?(name) = applies_to?(name) && name.value == to++ private++ def applies_to?(name) = name.kind == kind && name.type == type+ end+ end+enddiff --git a/spec/fixtures/json_api_kit/api_changes/2026-09-01_rename_widgets_label_to_name.rb b/spec/fixtures/json_api_kit/api_changes/2026-09-01_rename_widgets_label_to_name.rbnew file mode 100644index 00000000000..f5139302ece--- /dev/null+++ b/spec/fixtures/json_api_kit/api_changes/2026-09-01_rename_widgets_label_to_name.rb@@ -0,0 +1,10 @@+# frozen_string_literal: true++class RenameWidgetsLabelToName < JsonApiKit::VersionChange+ version "2026-09-01"+ description "The `label` attribute of the widgets resource is renamed to `name`."++ resource :widgets do+ renamed_attribute from: :label, to: :name+ end+enddiff --git a/spec/fixtures/json_api_kit/api_changes/2026-09-02_another_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes/2026-09-02_another_widgets_change.rbnew file mode 100644index 00000000000..9d65dafa31d--- /dev/null+++ b/spec/fixtures/json_api_kit/api_changes/2026-09-02_another_widgets_change.rb@@ -0,0 +1,6 @@+# frozen_string_literal: true++class AnotherWidgetsChange < JsonApiKit::VersionChange+ version "2026-09-02"+ description "A later change."+enddiff --git a/spec/fixtures/json_api_kit/api_changes_before_first_release/2026-08-01_rename_widgets_early.rb b/spec/fixtures/json_api_kit/api_changes_before_first_release/2026-08-01_rename_widgets_early.rbnew file mode 100644index 00000000000..80e33e4cc41--- /dev/null+++ b/spec/fixtures/json_api_kit/api_changes_before_first_release/2026-08-01_rename_widgets_early.rb@@ -0,0 +1,6 @@+# frozen_string_literal: true++class RenameWidgetsEarly < JsonApiKit::VersionChange+ version "2026-08-01"+ description "A change dated before the first release."+enddiff --git a/spec/fixtures/json_api_kit/api_changes_in_the_future/2099-01-01_future_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_in_the_future/2099-01-01_future_widgets_change.rbnew file mode 100644index 00000000000..06a3254c0cd--- /dev/null+++ b/spec/fixtures/json_api_kit/api_changes_in_the_future/2099-01-01_future_widgets_change.rb@@ -0,0 +1,6 @@+# frozen_string_literal: true++class FutureWidgetsChange < JsonApiKit::VersionChange+ version "2099-01-01"+ description "A change dated in the future."+enddiff --git a/spec/fixtures/json_api_kit/api_changes_misdated/2026-09-01_misdated_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_misdated/2026-09-01_misdated_widgets_change.rbnew file mode 100644index 00000000000..a86b701eda1--- /dev/null+++ b/spec/fixtures/json_api_kit/api_changes_misdated/2026-09-01_misdated_widgets_change.rb@@ -0,0 +1,6 @@+# frozen_string_literal: true++class MisdatedWidgetsChange < JsonApiKit::VersionChange+ version "2026-09-02"+ description "A change whose file name does not start with its version."+enddiff --git a/spec/fixtures/json_api_kit/api_changes_misnamed/2026-09-01_misnamed_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_misnamed/2026-09-01_misnamed_widgets_change.rbnew file mode 100644index 00000000000..280f9c02c78--- /dev/null+++ b/spec/fixtures/json_api_kit/api_changes_misnamed/2026-09-01_misnamed_widgets_change.rb@@ -0,0 +1,6 @@+# frozen_string_literal: true++class SomeOtherWidgetsChange < JsonApiKit::VersionChange+ version "2026-09-01"+ description "A change whose class does not match its file."+enddiff --git a/spec/fixtures/json_api_kit/api_changes_with_a_bad_date/2026-09-01_bad_date_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_with_a_bad_date/2026-09-01_bad_date_widgets_change.rbnew file mode 100644index 00000000000..e95b862326a--- /dev/null+++ b/spec/fixtures/json_api_kit/api_changes_with_a_bad_date/2026-09-01_bad_date_widgets_change.rb@@ -0,0 +1,6 @@+# frozen_string_literal: true++class BadDateWidgetsChange < JsonApiKit::VersionChange+ version "01/09/2026"+ description "A change whose version is not a date."+enddiff --git a/spec/fixtures/json_api_kit/api_changes_without_description/2026-09-02_undescribed_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_without_description/2026-09-02_undescribed_widgets_change.rbnew file mode 100644index 00000000000..7dd24316468--- /dev/null+++ b/spec/fixtures/json_api_kit/api_changes_without_description/2026-09-02_undescribed_widgets_change.rb@@ -0,0 +1,5 @@+# frozen_string_literal: true++class UndescribedWidgetsChange < JsonApiKit::VersionChange+ version "2026-09-02"+enddiff --git a/spec/fixtures/json_api_kit/api_changes_without_version/undated_widgets_change.rb b/spec/fixtures/json_api_kit/api_changes_without_version/undated_widgets_change.rbnew file mode 100644index 00000000000..94c820a42f6--- /dev/null+++ b/spec/fixtures/json_api_kit/api_changes_without_version/undated_widgets_change.rb@@ -0,0 +1,5 @@+# frozen_string_literal: true++class UndatedWidgetsChange < JsonApiKit::VersionChange+ description "A change with no version."+enddiff --git a/spec/integration/json_api_kit/support.rb b/spec/integration/json_api_kit/support.rbindex 7717b7b2cf1..c15fa1a641d 100644--- a/spec/integration/json_api_kit/support.rb+++ b/spec/integration/json_api_kit/support.rb@@ -98,7 +98,7 @@ RSpec.shared_context "with a listing of topics" dolet(:current) { "https://example.com/api/topics" }let(:query) { {} }let(:scoped_to) { nil }- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }+ let(:glossary) { JsonApiKit::Glossary.kit }let(:urls) { JsonApiKit::Urls.new(base:, current:, parameters: query) }let(:document) dodiff --git a/spec/integration/json_api_kit/version_changes_spec.rb b/spec/integration/json_api_kit/version_changes_spec.rbnew file mode 100644index 00000000000..5c00ea5f1ee--- /dev/null+++ b/spec/integration/json_api_kit/version_changes_spec.rb@@ -0,0 +1,160 @@+# frozen_string_literal: true++require_relative "support"++module JsonApiKitSpec+ class ChangedTopicsController < JsonApiKit::BaseController+ resource :topics+ end++ class RenameTopicsPostedAtToCreatedAt < JsonApiKit::VersionChange+ version "2026-10-01"+ description "The `posted_at` attribute of the topics resource is renamed to `created_at`."++ resource :topics do+ renamed_attribute from: :posted_at, to: :created_at+ end+ end+end++RSpec.describe "JSON:API version changes", type: :request do+ include_context "with a listing of topics"++ let(:first_version) { JsonApiKit::Timeline::FIRST_RELEASE }+ let(:change) { JsonApiKitSpec::RenameTopicsPostedAtToCreatedAt.new(__FILE__) }+ let(:change_version) { change.version }+ let(:version) { first_version.to_s }+ let(:parsed_body) { JSON.parse(response.body) }+ let(:error) { parsed_body["errors"].sole }+ let(:attributes) { parsed_body["data"].first["attributes"] }+ let(:ids) { parsed_body["data"].map { it["id"] } }++ before do+ freeze_time(change_version.date + 1.day)+ allow(JsonApiKit::VersionChange).to receive(:all).and_return([change])+ Rails.application.routes.disable_clear_and_finalize = true+ Rails.application.routes.draw do+ get "/api/changed-topics" => "json_api_kit_spec/changed_topics#index"+ end+ Rails.application.routes.disable_clear_and_finalize = false+ get "/api/changed-topics", headers: { "HTTP_API_VERSION" => version }, params: query+ end++ after { Rails.application.reload_routes! }++ context "when the client is pinned before the change" do+ it "sends the version of the pin" do+ expect(response.headers["Api-Version"]).to eq(first_version.to_s)+ end++ it "sends the attributes under the names of that version" do+ expect(attributes.keys).to contain_exactly("title", "postedAt")+ end++ context "when the request selects the renamed field" do+ let(:query) { { "fields" => { "topics" => "postedAt" } } }++ it "sends that field only" do+ expect(attributes.keys).to contain_exactly("postedAt")+ end+ end++ context "when the request sorts by the renamed field" do+ let(:query) { { "sort" => "postedAt" } }++ it "orders the rows by that attribute" do+ expect(ids).to eq([oldest.id.to_s, middle.id.to_s, newest.id.to_s])+ end+ end++ context "when the request anchors a window on the renamed field" do+ let(:query) do+ {+ "sort" => "postedAt",+ "page" => {+ "anchor" => {+ "postedAt" => middle.created_at.iso8601(6),+ },+ "beforeSize" => "1",+ "afterSize" => "0",+ },+ }+ end++ it "sends the rows of the window" do+ expect(ids).to eq([oldest.id.to_s, middle.id.to_s])+ end+ end++ context "when a refusal includes the renamed field" do+ let(:query) do+ {+ "sort" => "title",+ "page" => {+ "anchor" => {+ "postedAt" => middle.created_at.iso8601(6),+ },+ },+ }+ end++ it "sends the name of that version" do+ expect(error).to eq(+ refusal(+ title: "Anchor does not match the sort",+ detail: "The anchor is postedAt, but this request sorts by title.",+ parameter: "page[anchor][postedAt]",+ ).deep_stringify_keys,+ )+ end+ end++ context "when the request uses the new name" do+ let(:query) { { "fields" => { "topics" => "createdAt" } } }++ it { expect(response).to have_http_status(:bad_request) }++ it "sends the reason" do+ expect(error).to eq(+ refusal(+ title: "Invalid member name",+ detail: "Use postedAt, not createdAt.",+ parameter: "fields[topics]",+ ).deep_stringify_keys,+ )+ end+ end+ end++ context "when the client is pinned between the first version and the change" do+ let(:version) { (first_version.date + 1.day).to_s }++ it "sends the first version" do+ expect(response.headers["Api-Version"]).to eq(first_version.to_s)+ end++ it "sends the attributes under the names of the first version" do+ expect(attributes.keys).to contain_exactly("title", "postedAt")+ end+ end++ context "when the client is pinned at the change" do+ let(:version) { change_version.to_s }++ it "sends the version of the change" do+ expect(response.headers["Api-Version"]).to eq(change_version.to_s)+ end++ it "sends the attributes under the names of that version" do+ expect(attributes.keys).to contain_exactly("title", "createdAt")+ end++ context "when the request selects the field" do+ let(:query) { { "fields" => { "topics" => "createdAt" } } }++ it "sends that field only" do+ expect(attributes.keys).to contain_exactly("createdAt")+ end+ end+ end+enddiff --git a/spec/lib/json_api_kit/api_version_spec.rb b/spec/lib/json_api_kit/api_version_spec.rbindex b42b9b86073..324f22f9af4 100644--- a/spec/lib/json_api_kit/api_version_spec.rb+++ b/spec/lib/json_api_kit/api_version_spec.rb@@ -43,6 +43,28 @@ RSpec.describe JsonApiKit::ApiVersion doendend+ describe "#eql?" do+ context "when the other version has the same date" do+ let(:other) { described_class.parse("2026-09-01") }++ it { expect(version).to eql(other) }+ end++ context "when the other version has another date" do+ let(:other) { described_class.parse("2026-11-15") }++ it { expect(version).not_to eql(other) }+ end+ end++ describe "#hash" do+ let(:other) { described_class.parse("2026-09-01") }++ it "is the same for two versions of one date" do+ expect(version.hash).to eq(other.hash)+ end+ end+describe "#<=>" docontext "when the other version is later" dolet(:other) { described_class.parse("2026-11-15") }diff --git a/spec/lib/json_api_kit/document/collection_spec.rb b/spec/lib/json_api_kit/document/collection_spec.rbindex c93cf307499..9394547fbd0 100644--- a/spec/lib/json_api_kit/document/collection_spec.rb+++ b/spec/lib/json_api_kit/document/collection_spec.rb@@ -3,7 +3,7 @@RSpec.describe JsonApiKit::Document::Collection dosubject(:document) { described_class.new(listing, urls:, glossary:) }- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }+ let(:glossary) { JsonApiKit::Glossary.kit }fab!(:first_topic) doFabricate(:topic, title: "Segments of a listing", created_at: Time.utc(2026, 8, 1))diff --git a/spec/lib/json_api_kit/document/individual_spec.rb b/spec/lib/json_api_kit/document/individual_spec.rbindex 94f5ee6894b..935a3ee63de 100644--- a/spec/lib/json_api_kit/document/individual_spec.rb+++ b/spec/lib/json_api_kit/document/individual_spec.rb@@ -3,7 +3,7 @@RSpec.describe JsonApiKit::Document::Individual dosubject(:document) { described_class.new(reading, urls:, glossary:) }- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }+ let(:glossary) { JsonApiKit::Glossary.kit }fab!(:topic) { Fabricate(:topic, title: "One record read on its own") }diff --git a/spec/lib/json_api_kit/document/resource_object_spec.rb b/spec/lib/json_api_kit/document/resource_object_spec.rbindex 948993bf1a7..08ad1c9726b 100644--- a/spec/lib/json_api_kit/document/resource_object_spec.rb+++ b/spec/lib/json_api_kit/document/resource_object_spec.rb@@ -3,7 +3,7 @@RSpec.describe JsonApiKit::Document::ResourceObject dosubject(:resource_object) { described_class.new(record, urls:, glossary:, meta:) }- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }+ let(:glossary) { JsonApiKit::Glossary.kit }fab!(:topic) { Fabricate(:topic, title: "A row a document renders") }diff --git a/spec/lib/json_api_kit/document_spec.rb b/spec/lib/json_api_kit/document_spec.rbindex 6c58061f589..b9747b9d069 100644--- a/spec/lib/json_api_kit/document_spec.rb+++ b/spec/lib/json_api_kit/document_spec.rb@@ -18,7 +18,7 @@ RSpec.describe JsonApiKit::Document doendendlet(:guardian) { Guardian.new }- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }+ let(:glossary) { JsonApiKit::Glossary.kit }let(:urls) doJsonApiKit::Urls.new(base: "https://example.com/api", current: "https://example.com/api/topics")enddiff --git a/spec/lib/json_api_kit/glossary/casing_rule_spec.rb b/spec/lib/json_api_kit/glossary/casing_rule_spec.rbindex 124ed1c60d8..9e858cc031a 100644--- a/spec/lib/json_api_kit/glossary/casing_rule_spec.rb+++ b/spec/lib/json_api_kit/glossary/casing_rule_spec.rb@@ -1,70 +1,86 @@# frozen_string_literal: trueRSpec.describe JsonApiKit::Glossary::CasingRule do- subject(:rule) { described_class }+ let(:rule) { described_class }+ let(:name) { JsonApiKit::Name::Field.new(value:, type: "topics") }+ let(:value) { "createdAt" }describe "#declared_name" do+ subject(:declared_name) { rule.declared_name(name) }+it "returns the name in snake case" do- expect(rule.declared_name("createdAt")).to eq("created_at")+ expect(declared_name).to eq(name.with(value: "created_at"))endcontext "when the value is a list of names" do+ let(:name) { JsonApiKit::Name::Member.new(value: "-createdAt,title") }+it "returns every name in snake case" do- expect(rule.declared_name("-createdAt,title")).to eq("-created_at,title")+ expect(declared_name).to eq(name.with(value: "-created_at,title"))endendcontext "when the value is a path" do+ let(:name) { JsonApiKit::Name::Member.new(value: "solvedStatus.answeredAt") }+it "returns every segment" do- expect(rule.declared_name("solvedStatus.answeredAt")).to eq("solved_status.answered_at")+ expect(declared_name).to eq(name.with(value: "solved_status.answered_at"))endendcontext "when the name has a hyphen" do+ let(:name) { JsonApiKit::Name::Member.new(value: "solved-statuses") }+it "keeps the hyphen" do- expect(rule.declared_name("solved-statuses")).to eq("solved-statuses")+ expect(declared_name).to eq(name)endendcontext "when the name starts with a capital" do- it do- expect { rule.declared_name("CreatedAt") }.to raise_error(described_class::NotAMemberName)- end+ let(:value) { "CreatedAt" }++ it { expect { declared_name }.to raise_error(JsonApiKit::Glossary::Correction) }endcontext "when the name ends with capitals" do- it do- expect { rule.declared_name("createdAT") }.to raise_error(described_class::NotAMemberName)- end+ let(:value) { "createdAT" }++ it { expect { declared_name }.to raise_error(JsonApiKit::Glossary::Correction) }endcontext "when the name has an underscore" do- it do- expect { rule.declared_name("created_at") }.to raise_error(described_class::NotAMemberName)- end+ let(:value) { "created_at" }- it "suggests the name to use instead" do- expect { rule.declared_name("created_at") }.to raise_error(- /Use createdAt, not created_at\./,- )+ it { expect { declared_name }.to raise_error(JsonApiKit::Glossary::Correction) }++ it "raises a correction with the name in snake case" do+ expect { declared_name }.to raise_error(having_attributes(name:))endendenddescribe "#member_name" do+ subject(:member_name) { rule.member_name(name) }++ let(:value) { "created_at" }+it "returns the name in camel case" do- expect(rule.member_name("created_at")).to eq("createdAt")+ expect(member_name).to eq(name.with(value: "createdAt"))endcontext "when the name is a path" do+ let(:name) { JsonApiKit::Name::Member.new(value: "last_poster.last_seen_at") }+it "returns every segment" do- expect(rule.member_name("last_poster.last_seen_at")).to eq("lastPoster.lastSeenAt")+ expect(member_name).to eq(name.with(value: "lastPoster.lastSeenAt"))endendcontext "when the name has a hyphen" do+ let(:name) { JsonApiKit::Name::Member.new(value: "solved-statuses") }+it "keeps the hyphen" do- expect(rule.member_name("solved-statuses")).to eq("solved-statuses")+ expect(member_name).to eq(name)endendenddiff --git a/spec/lib/json_api_kit/glossary/version_rule_spec.rb b/spec/lib/json_api_kit/glossary/version_rule_spec.rbnew file mode 100644index 00000000000..b3e9a53b532--- /dev/null+++ b/spec/lib/json_api_kit/glossary/version_rule_spec.rb@@ -0,0 +1,117 @@+# frozen_string_literal: true++module JsonApiKitSpec+ class FirstRuleChange < JsonApiKit::VersionChange+ version "2026-09-15"+ description "The first change."++ resource :topics do+ renamed_attribute from: :posted_at, to: :created_at+ end+ end++ class SecondRuleChange < JsonApiKit::VersionChange+ version "2026-10-01"+ description "The second change."++ resource :topics do+ renamed_attribute from: :created_at, to: :published_at+ end+ end++ class NameToTitleChange < JsonApiKit::VersionChange+ version "2026-09-15"+ description "The `name` attribute of the topics resource is renamed to `title`."++ resource :topics do+ renamed_attribute from: :name, to: :title+ end+ end++ class LabelToNameChange < JsonApiKit::VersionChange+ version "2026-10-01"+ description "The `label` attribute of the topics resource is renamed to `name`."++ resource :topics do+ renamed_attribute from: :label, to: :name+ end+ end+end++RSpec.describe JsonApiKit::Glossary::VersionRule do+ subject(:rule) { described_class.new(version) }++ let(:version) { JsonApiKit::ApiVersion.parse("2026-09-01") }+ let(:first_change) { JsonApiKitSpec::FirstRuleChange.new(__FILE__) }+ let(:second_change) { JsonApiKitSpec::SecondRuleChange.new(__FILE__) }+ let(:name) { JsonApiKit::Name::Field.new(value:, type: "topics") }+ let(:value) { "posted_at" }++ before do+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(+ [first_change, second_change],+ )+ end++ describe "#declared_name" do+ subject(:declared_name) { rule.declared_name(name) }++ it "returns the current name of an old name" do+ expect(declared_name).to eq(name.with(value: "published_at"))+ end++ context "when a later change reuses a spelling of this version" do+ let(:first_change) { JsonApiKitSpec::NameToTitleChange.new(__FILE__) }+ let(:second_change) { JsonApiKitSpec::LabelToNameChange.new(__FILE__) }+ let(:value) { "name" }++ it "returns the current name of the old name" do+ expect(declared_name).to eq(name.with(value: "title"))+ end++ context "when the name belongs to a later version" do+ let(:value) { "title" }++ it "raises a correction with the declared name" do+ expect { declared_name }.to raise_error(having_attributes(name:))+ end+ end+ end++ context "when no change touches the name" do+ let(:value) { "title" }++ it "returns the name" do+ expect(declared_name).to eq(name)+ end+ end++ context "when the name belongs to a later version" do+ let(:value) { "published_at" }++ it "raises a correction with the declared name" do+ expect { declared_name }.to raise_error(+ an_instance_of(JsonApiKit::Glossary::Correction).and(having_attributes(name:)),+ )+ end+ end+ end++ describe "#member_name" do+ subject(:member_name) { rule.member_name(name) }++ let(:value) { "published_at" }++ it "returns the name of this version for a current name" do+ expect(member_name).to eq(name.with(value: "posted_at"))+ end++ context "when no change touches the name" do+ let(:value) { "title" }++ it "returns the name" do+ expect(member_name).to eq(name)+ end+ end+ end+enddiff --git a/spec/lib/json_api_kit/glossary_spec.rb b/spec/lib/json_api_kit/glossary_spec.rbindex 4b7431bf01f..bdd76d2f148 100644--- a/spec/lib/json_api_kit/glossary_spec.rb+++ b/spec/lib/json_api_kit/glossary_spec.rb@@ -3,14 +3,37 @@module JsonApiKitSpecMarkingRule =Struct.new(:mark) do- def declared_name(name) = "#{name}<#{mark}"+ def declared_name(name) = name.convert { "#{it}<#{mark}" }- def member_name(name) = "#{name}>#{mark}"+ def member_name(name) = name.convert { "#{it}>#{mark}" }end++ class GlossaryChange < JsonApiKit::VersionChange+ version "2026-09-15"+ description "The `posted_at` attribute of the topics resource is renamed to `created_at`."++ resource :topics do+ renamed_attribute from: :posted_at, to: :created_at+ end+ end++ class GlossaryReuseChange < JsonApiKit::VersionChange+ version "2026-10-01"+ description "The `label` attribute of the topics resource is renamed to `posted_at`."++ resource :topics do+ renamed_attribute from: :label, to: :posted_at+ end+ endendRSpec.describe JsonApiKit::Glossary do- subject(:glossary) { described_class.new([JsonApiKit::Glossary::CasingRule]) }+ subject(:glossary) { described_class.new([described_class::CasingRule]) }++ let(:version) { JsonApiKit::Timeline::FIRST_RELEASE }+ let(:change) { JsonApiKitSpec::GlossaryChange.new(__FILE__) }+ let(:name) { JsonApiKit::Name::Field.new(value:, type: "topics") }+ let(:value) { "createdAt" }describe ".kit" dosubject(:kit) { described_class.kit }@@ -19,24 +42,92 @@ RSpec.describe JsonApiKit::Glossary doit "builds a glossary with the wire format rules" dokit- expect(described_class).to have_received(:new).with([JsonApiKit::Glossary::CasingRule])+ expect(described_class).to have_received(:new).with([described_class::CasingRule])endenddescribe ".resource" do- subject(:resource) { described_class.resource }+ subject(:resource) { described_class.resource(version) }- before { allow(described_class).to receive(:new).and_call_original }+ before do+ allow(described_class).to receive(:new).and_call_original+ allow(described_class::VersionRule).to receive(:new).and_call_original+ end- it "builds a glossary with the rules for a resource" do+ it "builds a glossary with the wire format rules and the version rule" doresource- expect(described_class).to have_received(:new).with([JsonApiKit::Glossary::CasingRule])+ expect(described_class).to have_received(:new).with(+ [described_class::CasingRule, an_instance_of(described_class::VersionRule)],+ )+ end++ it "builds the version rule for the version" do+ resource+ expect(described_class::VersionRule).to have_received(:new).with(version)endenddescribe "#declared_name" do+ subject(:declared_name) { glossary.declared_name(name) }+it "returns the declared name" do- expect(glossary.declared_name("createdAt")).to eq("created_at")+ expect(declared_name).to eq(name.with(value: "created_at"))+ end++ context "when the name is not a member name" do+ let(:value) { "created_at" }++ it "raises a refusal" do+ expect { declared_name }.to raise_error(described_class::NotAMemberName)+ end++ it "suggests the name to use instead" do+ expect { declared_name }.to raise_error(/Use createdAt, not created_at\./)+ end+ end++ context "with a version rule" do+ subject(:glossary) { described_class.resource(version) }++ let(:value) { "postedAt" }++ before do+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return([change])+ end++ it "returns the current name" do+ expect(declared_name).to eq(name.with(value: "created_at"))+ end++ context "when the name belongs to a later version" do+ let(:value) { "createdAt" }++ it "suggests the name of this version, on the wire" do+ expect { declared_name }.to raise_error(/Use postedAt, not createdAt\./)+ end+ end++ context "when the name is in snake case" do+ let(:value) { "created_at" }++ it "suggests the name of this version, on the wire" do+ expect { declared_name }.to raise_error(/Use postedAt, not created_at\./)+ end+ end++ context "when a later change reuses a spelling of this version" do+ let(:value) { "createdAt" }++ before do+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(+ [change, JsonApiKitSpec::GlossaryReuseChange.new(__FILE__)],+ )+ end++ it "suggests the name of this version, converted once" do+ expect { declared_name }.to raise_error(/Use postedAt, not createdAt\./)+ end+ endendcontext "with several rules" do@@ -46,14 +137,30 @@ RSpec.describe JsonApiKit::Glossary dolet(:mark_b) { JsonApiKitSpec::MarkingRule.new("b") }it "applies them in order" do- expect(glossary.declared_name("x")).to eq("x<a<b")+ expect(declared_name).to eq(name.with(value: "createdAt<a<b"))endendenddescribe "#member_name" do+ subject(:member_name) { glossary.member_name(name) }++ let(:value) { "created_at" }+it "returns the member name" do- expect(glossary.member_name("created_at")).to eq("createdAt")+ expect(member_name).to eq(name.with(value: "createdAt"))+ end++ context "with a version rule" do+ subject(:glossary) { described_class.resource(version) }++ before do+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return([change])+ end++ it "returns the name of this version, on the wire" do+ expect(member_name).to eq(name.with(value: "postedAt"))+ endendcontext "with several rules" do@@ -63,7 +170,7 @@ RSpec.describe JsonApiKit::Glossary dolet(:mark_b) { JsonApiKitSpec::MarkingRule.new("b") }it "applies them in reverse order" do- expect(glossary.member_name("x")).to eq("x>b>a")+ expect(member_name).to eq(name.with(value: "created_at>b>a"))endendenddiff --git a/spec/lib/json_api_kit/name/anchor_spec.rb b/spec/lib/json_api_kit/name/anchor_spec.rbnew file mode 100644index 00000000000..c39281f6399--- /dev/null+++ b/spec/lib/json_api_kit/name/anchor_spec.rb@@ -0,0 +1,9 @@+# frozen_string_literal: true++require_relative "support"++RSpec.describe JsonApiKit::Name::Anchor do+ subject(:name) { described_class.new(value: "posted_at", type: "topics") }++ it_behaves_like "a name", :anchor+enddiff --git a/spec/lib/json_api_kit/name/field_spec.rb b/spec/lib/json_api_kit/name/field_spec.rbnew file mode 100644index 00000000000..e3b30d135a7--- /dev/null+++ b/spec/lib/json_api_kit/name/field_spec.rb@@ -0,0 +1,9 @@+# frozen_string_literal: true++require_relative "support"++RSpec.describe JsonApiKit::Name::Field do+ subject(:name) { described_class.new(value: "posted_at", type: "topics") }++ it_behaves_like "a name", :field+enddiff --git a/spec/lib/json_api_kit/name/filter_spec.rb b/spec/lib/json_api_kit/name/filter_spec.rbnew file mode 100644index 00000000000..ac22a60d0f5--- /dev/null+++ b/spec/lib/json_api_kit/name/filter_spec.rb@@ -0,0 +1,9 @@+# frozen_string_literal: true++require_relative "support"++RSpec.describe JsonApiKit::Name::Filter do+ subject(:name) { described_class.new(value: "posted_at", type: "topics") }++ it_behaves_like "a name", :filter+enddiff --git a/spec/lib/json_api_kit/name/member_spec.rb b/spec/lib/json_api_kit/name/member_spec.rbnew file mode 100644index 00000000000..1ca32cff057--- /dev/null+++ b/spec/lib/json_api_kit/name/member_spec.rb@@ -0,0 +1,9 @@+# frozen_string_literal: true++require_relative "support"++RSpec.describe JsonApiKit::Name::Member do+ subject(:name) { described_class.new(value: "after_size") }++ it_behaves_like "a name", :member+enddiff --git a/spec/lib/json_api_kit/name/relationship_spec.rb b/spec/lib/json_api_kit/name/relationship_spec.rbnew file mode 100644index 00000000000..8d41e7517ed--- /dev/null+++ b/spec/lib/json_api_kit/name/relationship_spec.rb@@ -0,0 +1,9 @@+# frozen_string_literal: true++require_relative "support"++RSpec.describe JsonApiKit::Name::Relationship do+ subject(:name) { described_class.new(value: "posted_at", type: "topics") }++ it_behaves_like "a name", :relationship+enddiff --git a/spec/lib/json_api_kit/name/sort_spec.rb b/spec/lib/json_api_kit/name/sort_spec.rbnew file mode 100644index 00000000000..79ec71ca4cc--- /dev/null+++ b/spec/lib/json_api_kit/name/sort_spec.rb@@ -0,0 +1,9 @@+# frozen_string_literal: true++require_relative "support"++RSpec.describe JsonApiKit::Name::Sort do+ subject(:name) { described_class.new(value: "posted_at", type: "topics") }++ it_behaves_like "a name", :sort+enddiff --git a/spec/lib/json_api_kit/name/support.rb b/spec/lib/json_api_kit/name/support.rbnew file mode 100644index 00000000000..5148140a637--- /dev/null+++ b/spec/lib/json_api_kit/name/support.rb@@ -0,0 +1,21 @@+# frozen_string_literal: true++RSpec.shared_examples "a name" do |kind|+ describe "#kind" do+ it "returns #{kind.inspect}" do+ expect(name.kind).to eq(kind)+ end+ end++ describe "#convert" do+ it "returns the name with the converted value" do+ expect(name.convert(&:upcase)).to eq(name.with(value: name.value.upcase))+ end+ end++ describe "#to_s" do+ it "returns the value" do+ expect(name.to_s).to eq(name.value)+ end+ end+enddiff --git a/spec/lib/json_api_kit/request/contract/collection_spec.rb b/spec/lib/json_api_kit/request/contract/collection_spec.rbindex e5c072ef018..697dead9842 100644--- a/spec/lib/json_api_kit/request/contract/collection_spec.rb+++ b/spec/lib/json_api_kit/request/contract/collection_spec.rb@@ -69,6 +69,18 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model doit { is_expected.not_to allow_value("secrets", "created_at,secrets").for(:sort) }it { is_expected.not_to allow_value(%w[created_at], 5).for(:sort) }+ context "when a sort is unknown" do+ let(:params) { { sort: { posted_at: :asc } } }++ before { contract.valid? }++ it "adds an error with the sort name of the resource" do+ expect(contract.errors.where(:sort, :no_such_name).sole.options[:name]).to eq(+ JsonApiKit::Name::Sort.new(value: "posted_at", type: "topics"),+ )+ end+ end+context "when sort is a string" dolet(:params) { { sort: "-created_at,title" } }@@ -162,6 +174,17 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model dobefore { contract.valid? }+ context "when the anchor is not the sort" do+ let(:params) { { sort: { created_at: :asc }, page: { anchor: { title: "A" } } } }++ it "adds an error with the anchor name and the sort name of the resource" do+ expect(contract.errors.where(:"page.anchor", :not_the_sort).sole.options).to include(+ name: JsonApiKit::Name::Anchor.new(value: "title", type: "topics"),+ key: JsonApiKit::Name::Sort.new(value: "created_at", type: "topics"),+ )+ end+ end+it { is_expected.to validate_length_of(:anchor).as_array.is_equal_to(1).allow_nil }it { is_expected.to allow_value({ id: 12 }, :first_unread).for(:anchor) }it { is_expected.not_to allow_value({}, { id: 12, title: "a topic" }).for(:anchor) }diff --git a/spec/lib/json_api_kit/request/parameters_spec.rb b/spec/lib/json_api_kit/request/parameters_spec.rbindex 81f240331a3..8c24a2bee96 100644--- a/spec/lib/json_api_kit/request/parameters_spec.rb+++ b/spec/lib/json_api_kit/request/parameters_spec.rb@@ -1,9 +1,30 @@# frozen_string_literal: true+module JsonApiKitSpec+ class ParametersResource < JsonApiKit::Resource+ type :topics+ end++ class ParametersChange < JsonApiKit::VersionChange+ version "2026-09-15"+ description "Two resources rename a field."++ resource :topics do+ renamed_attribute from: :posted_at, to: :created_at+ end++ resource :users do+ renamed_attribute from: :handle, to: :username+ end+ end+end+RSpec.describe JsonApiKit::Request::Parameters do- subject(:declared_parameters) { described_class.new(parameters, glossary:).to_h }+ subject(:declared_parameters) do+ described_class.new(parameters, glossary:, resource: JsonApiKitSpec::ParametersResource).to_h+ end- let(:glossary) { JsonApiKit::Glossary.new([JsonApiKit::Glossary::CasingRule]) }+ let(:glossary) { JsonApiKit::Glossary.kit }let(:parameters) { { "sort" => "-createdAt" } }it "converts the sort names" do@@ -52,7 +73,7 @@ RSpec.describe JsonApiKit::Request::Parameters doit "raises with the parameter that holds it" doexpect { declared_parameters }.to raise_error(- an_instance_of(JsonApiKit::Glossary::CasingRule::NotAMemberName).and(+ an_instance_of(JsonApiKit::Glossary::NotAMemberName).and(having_attributes(source: { parameter: "sort" }),),)@@ -69,6 +90,86 @@ RSpec.describe JsonApiKit::Request::Parameters doendend+ context "with a version change" do+ let(:glossary) { JsonApiKit::Glossary.resource(version) }+ let(:version) { JsonApiKit::Timeline::FIRST_RELEASE }+ let(:change) { JsonApiKitSpec::ParametersChange.new(__FILE__) }++ before do+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return([change])+ end++ context "when a fieldset has a renamed field" do+ let(:parameters) { { "fields" => { "topics" => "postedAt" } } }++ it "converts the field to its current name" do+ expect(declared_parameters).to eq("fields" => { "topics" => "created_at" })+ end+ end++ context "when a fieldset of another type has a renamed field" do+ let(:parameters) { { "fields" => { "users" => "handle" } } }++ it "converts the field with the names of that type" do+ expect(declared_parameters).to eq("fields" => { "users" => "username" })+ end+ end++ context "when the sort has a renamed field" do+ let(:parameters) { { "sort" => "-postedAt" } }++ it "converts the field to its current name" do+ expect(declared_parameters).to eq("sort" => "-created_at")+ end+ end++ context "when the sort has several fields" do+ let(:parameters) { { "sort" => "-postedAt,title" } }++ it "converts every field" do+ expect(declared_parameters).to eq("sort" => "-created_at,title")+ end+ end++ context "when a fieldset has several fields" do+ let(:parameters) { { "fields" => { "topics" => "title,postedAt" } } }++ it "converts every field" do+ expect(declared_parameters).to eq("fields" => { "topics" => "title,created_at" })+ end+ end++ context "when the anchor has a renamed field" do+ let(:parameters) { { "page" => { "anchor" => { "postedAt" => "2026-08-01" } } } }++ it "converts the field to its current name" do+ expect(declared_parameters).to eq(+ "page" => {+ "anchor" => {+ "created_at" => "2026-08-01",+ },+ },+ )+ end+ end++ context "when a filter has the name of a renamed field" do+ let(:parameters) { { "filter" => { "postedAt" => "2026-08-01" } } }++ it "converts the case of the filter name only" do+ expect(declared_parameters).to eq("filter" => { "posted_at" => "2026-08-01" })+ end+ end+ end++ context "when a name has a newline" do+ let(:parameters) { { "sort" => "createdAt\n" } }++ it "converts the case and keeps the newline for the contract" do+ expect(declared_parameters).to eq("sort" => "created_at\n")+ end+ end+context "when the parameters have a filter" dolet(:parameters) { { "filter" => { "postCount" => "SomeTopic Title" } } }diff --git a/spec/lib/json_api_kit/timeline_spec.rb b/spec/lib/json_api_kit/timeline_spec.rbindex cc214ef4369..ca8878a0d6f 100644--- a/spec/lib/json_api_kit/timeline_spec.rb+++ b/spec/lib/json_api_kit/timeline_spec.rb@@ -1,26 +1,50 @@# frozen_string_literal: true+module JsonApiKitSpec+ class MiddleTimelineChange < JsonApiKit::VersionChange+ version "2026-11-15"+ description "The middle change on the timeline."+ end++ class LatestTimelineChange < JsonApiKit::VersionChange+ version "2027-01-05"+ description "The latest change on the timeline."+ end+end+RSpec.describe JsonApiKit::Timeline do- let(:earliest) { JsonApiKit::ApiVersion.parse("2026-09-01") }+ let(:first) { described_class::FIRST_RELEASE }let(:middle) { JsonApiKit::ApiVersion.parse("2026-11-15") }let(:latest) { JsonApiKit::ApiVersion.parse("2027-01-05") }- let(:timeline) { described_class.new([earliest, middle, latest]) }before dofreeze_time(Date.new(2027, 1, 20))- allow(described_class).to receive(:core).and_return(timeline)+ allow(JsonApiKit::VersionChange).to receive(:all).and_return(+ [+ JsonApiKitSpec::MiddleTimelineChange.new(__FILE__),+ JsonApiKitSpec::LatestTimelineChange.new(__FILE__),+ ],+ )enddescribe ".first" do- it "returns the earliest version" do- expect(described_class.first).to eq(earliest)+ it "returns the first release" do+ expect(described_class.first).to eq(first)endenddescribe ".current" do- it "returns the latest version" do+ it "returns the version of the latest change" doexpect(described_class.current).to eq(latest)end++ context "when there is no change" do+ before { allow(JsonApiKit::VersionChange).to receive(:all).and_return([]) }++ it "returns the first release" do+ expect(described_class.current).to eq(first)+ end+ endenddescribe ".resolve" do@@ -57,7 +81,7 @@ RSpec.describe JsonApiKit::Timeline doendcontext "when the date is earlier than the first version" do- let(:raw) { (earliest.date - 1.day).to_s }+ let(:raw) { (first.date - 1.day).to_s }it { expect { version }.to raise_error(JsonApiKit::ApiVersion::Unknown) }enddiff --git a/spec/lib/json_api_kit/version_change/rename_spec.rb b/spec/lib/json_api_kit/version_change/rename_spec.rbnew file mode 100644index 00000000000..101d03dce6b--- /dev/null+++ b/spec/lib/json_api_kit/version_change/rename_spec.rb@@ -0,0 +1,59 @@+# frozen_string_literal: true++RSpec.describe JsonApiKit::VersionChange::Rename do+ subject(:rename) do+ described_class.new(kind: :field, type: "topics", from: "posted_at", to: "created_at")+ end++ let(: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+ it "returns the new name for the old one" do+ expect(rename.current(old_name)).to eq(new_name)+ end++ context "when the name is of another kind" do+ let(:old_name) { JsonApiKit::Name::Sort.new(value: "posted_at", type: "topics") }++ it "returns the name" do+ expect(rename.current(old_name)).to eq(old_name)+ end+ end++ context "when the name is of another type" do+ let(:old_name) { JsonApiKit::Name::Field.new(value: "posted_at", type: "users") }++ it "returns the name" do+ expect(rename.current(old_name)).to eq(old_name)+ end+ end+ end++ describe "#previous" do+ it "returns the old name for the new one" do+ expect(rename.previous(new_name)).to eq(old_name)+ end++ context "when the name is of another kind" do+ let(:new_name) { JsonApiKit::Name::Sort.new(value: "created_at", type: "topics") }++ it "returns the name" do+ expect(rename.previous(new_name)).to eq(new_name)+ end+ end++ context "when the name is of another type" do+ let(:new_name) { JsonApiKit::Name::Field.new(value: "created_at", type: "users") }++ it "returns the name" do+ expect(rename.previous(new_name)).to eq(new_name)+ end+ end+ end++ describe "#introduces?" do+ it { expect(rename).to be_introduces(new_name) }+ it { expect(rename).not_to be_introduces(old_name) }+ end+enddiff --git a/spec/lib/json_api_kit/version_change_spec.rb b/spec/lib/json_api_kit/version_change_spec.rbnew file mode 100644index 00000000000..efbd87b2661--- /dev/null+++ b/spec/lib/json_api_kit/version_change_spec.rb@@ -0,0 +1,193 @@+# frozen_string_literal: true++module JsonApiKitSpec+ class RenameThingsLabelToName < JsonApiKit::VersionChange+ version "2026-09-15"+ description "The `label` attribute of the things resource is renamed to `name`."++ resource :things do+ renamed_attribute from: :label, to: :name+ end+ end++ class RenameThingsAndPeople < JsonApiKit::VersionChange+ version "2026-10-01"+ description "Two resources change their names."++ resource :things do+ renamed_attribute from: :label, to: :name+ end++ resource :people do+ renamed_attribute from: :handle, to: :username+ end+ end+end++RSpec.describe JsonApiKit::VersionChange do+ subject(:change) { JsonApiKitSpec::RenameThingsLabelToName.new(__FILE__) }++ let(:version) { JsonApiKit::ApiVersion.parse("2026-09-15") }+ let(:later_version) { JsonApiKit::ApiVersion.parse("2026-10-01") }+ let(:fixtures) { Rails.root.join("spec/fixtures/json_api_kit") }+ let(:name) { JsonApiKit::Name::Field.new(value: "label", type: "things") }++ describe ".read" do+ subject(:changes) { described_class.read(fixtures.join(directory)) }++ let(:directory) { "api_changes" }++ it "returns the change of each file, oldest version first" do+ expect(changes.map(&:class)).to eq([RenameWidgetsLabelToName, AnotherWidgetsChange])+ end++ it "gives each change the file it came from" do+ expect(changes.first.source.to_s).to end_with("2026-09-01_rename_widgets_label_to_name.rb")+ end++ context "when the file name does not start with the version" do+ let(:directory) { "api_changes_misdated" }++ it do+ expect { changes }.to raise_error(ArgumentError, /must start with the version 2026-09-02/)+ end+ end++ context "when a change is dated in the future" do+ let(:directory) { "api_changes_in_the_future" }++ it { expect { changes }.to raise_error(ArgumentError, /in the future/) }+ end++ context "when the version of a change is not a date" do+ let(:directory) { "api_changes_with_a_bad_date" }++ it { expect { changes }.to raise_error(ArgumentError, /is not a date/) }+ end++ context "when the class of a change does not match its file" do+ let(:directory) { "api_changes_misnamed" }++ it { expect { changes }.to raise_error(NameError, /MisnamedWidgetsChange/) }+ end++ context "when a change has no version" do+ let(:directory) { "api_changes_without_version" }++ it { expect { changes }.to raise_error(ArgumentError, /has no version/) }+ end++ context "when a change is dated on or before the first release" do+ let(:directory) { "api_changes_before_first_release" }++ it { expect { changes }.to raise_error(ArgumentError, /on or before the first release/) }+ end++ context "when a change has no description" do+ let(:directory) { "api_changes_without_description" }++ it { expect { changes }.to raise_error(ArgumentError, /has no description/) }+ end+ end++ describe ".after" do+ subject(:changes) { described_class.after(pin) }++ let(:pin) { version }+ let(:later_change) { JsonApiKitSpec::RenameThingsAndPeople.new(__FILE__) }++ before { allow(described_class).to receive(:all).and_return([change, later_change]) }++ it "returns the changes dated after the version" do+ expect(changes).to eq([later_change])+ end++ context "when the version is the latest" do+ let(:pin) { later_version }++ it "returns no change" do+ expect(changes).to be_empty+ end+ end+ end++ describe "#version" do+ it "returns the version of the change" do+ expect(change.version).to eq(version)+ end+ end++ describe "#description" do+ it "returns the description of the change" do+ expect(change.description).to eq(+ "The `label` attribute of the things resource is renamed to `name`.",+ )+ end+ end++ describe "#current" do+ subject(:current_name) { change.current(name) }++ it "returns the name after the change" do+ expect(current_name).to eq(name.with(value: "name"))+ end++ context "when the name is the sort derived from the attribute" do+ let(:name) { JsonApiKit::Name::Sort.new(value: "label", type: "things") }++ it "renames it" do+ expect(current_name).to eq(name.with(value: "name"))+ end+ end++ context "when the name is the anchor derived from the attribute" do+ let(:name) { JsonApiKit::Name::Anchor.new(value: "label", type: "things") }++ it "renames it" do+ expect(current_name).to eq(name.with(value: "name"))+ end+ end++ context "when the name is a filter with that name" do+ let(:name) { JsonApiKit::Name::Filter.new(value: "label", type: "things") }++ it "returns the name" do+ expect(current_name).to eq(name)+ end+ end++ context "with several resources" do+ subject(:change) { JsonApiKitSpec::RenameThingsAndPeople.new(__FILE__) }++ let(:other_name) { JsonApiKit::Name::Field.new(value: "handle", type: "people") }++ it "renames the names of every resource" do+ expect([change.current(name), change.current(other_name)]).to eq(+ [name.with(value: "name"), other_name.with(value: "username")],+ )+ end+ end+ end++ describe "#previous" do+ subject(:previous_name) { 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+ end++ describe "#introduces?" do+ context "when the change renames another name to this one" do+ let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }++ it { expect(change).to be_introduces(name) }+ end++ context "when the change renames this name away" do+ it { expect(change).not_to be_introduces(name) }+ end+ end+enddiff --git a/spec/resources/group_resource_spec.rb b/spec/resources/group_resource_spec.rbindex ed399c4e189..f1055de249d 100644--- a/spec/resources/group_resource_spec.rb+++ b/spec/resources/group_resource_spec.rb@@ -4,7 +4,7 @@ RSpec.describe GroupResource dofab!(:group) { Fabricate(:group, name: "a_group") }let(:guardian) { Guardian.new }- let(:glossary) { JsonApiKit::Glossary.resource }+ let(:glossary) { JsonApiKit::Glossary.kit }let(:urls) doJsonApiKit::Urls.new(base: "https://example.com/api", current: "https://example.com/api/groups")enddiff --git a/spec/resources/user_resource_spec.rb b/spec/resources/user_resource_spec.rbindex 7280d3f9bc3..d03631fcd89 100644--- a/spec/resources/user_resource_spec.rb+++ b/spec/resources/user_resource_spec.rb@@ -4,7 +4,7 @@ RSpec.describe UserResource dofab!(:user) { Fabricate(:user, username: "someone") }let(:guardian) { Guardian.new }- let(:glossary) { JsonApiKit::Glossary.resource }+ let(:glossary) { JsonApiKit::Glossary.kit }let(:urls) doJsonApiKit::Urls.new(base: "https://example.com/api", current: "https://example.com/api/users")end