Skip to content

A platform for community discussion. Free, open, simple.

DEV: Separate JSON:API changes from their collection (#43554)

Loïc Guitautd2780d4db049
diff --git a/config/initializers/json_api_kit.rb b/config/initializers/json_api_kit.rb
index f9f14e04f4c..3225bedce8c 100644
--- a/config/initializers/json_api_kit.rb
+++ b/config/initializers/json_api_kit.rb
@@ -1,3 +1,3 @@
# frozen_string_literal: true
-Rails.application.config.after_initialize { JsonApiKit::VersionChange.all }
+Rails.application.config.after_initialize { JsonApiKit::VersionChanges.core }
diff --git a/lib/json_api_kit/glossary/version_rule.rb b/lib/json_api_kit/glossary/version_rule.rb
index bf7fdeedbe1..2b8895e74fa 100644
--- a/lib/json_api_kit/glossary/version_rule.rb
+++ b/lib/json_api_kit/glossary/version_rule.rb
@@ -4,7 +4,7 @@ module JsonApiKit
class Glossary
class VersionRule
def initialize(version)
- @changes = VersionChange.after(version)
+ @changes = VersionChanges.core.after(version)
end
def declared_attributes(attributes)
diff --git a/lib/json_api_kit/timeline.rb b/lib/json_api_kit/timeline.rb
index 8e96ceb8043..a52bff3d086 100644
--- a/lib/json_api_kit/timeline.rb
+++ b/lib/json_api_kit/timeline.rb
@@ -10,7 +10,7 @@ module JsonApiKit
private
- def core = new([FIRST_RELEASE, *VersionChange.all.map(&:version)].uniq)
+ def core = new([FIRST_RELEASE, *VersionChanges.core.map(&:version)].uniq)
end
def initialize(versions)
diff --git a/lib/json_api_kit/version_change.rb b/lib/json_api_kit/version_change.rb
index 7d93b3f2c6a..25a221cc19d 100644
--- a/lib/json_api_kit/version_change.rb
+++ b/lib/json_api_kit/version_change.rb
@@ -2,23 +2,9 @@
module JsonApiKit
class VersionChange
- CHANGES_DIRECTORY = Rails.root.join("config/api_changes")
- DATE_PREFIX = /\A\d{4}-\d{2}-\d{2}_/
PASS_THROUGH = ->(_index, name) { PassThrough.new(name) }
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
@@ -45,15 +31,6 @@ module JsonApiKit
end
def type_renames = @type_renames ||= []
-
- 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, :type_renames, to: :class
diff --git a/lib/json_api_kit/version_changes.rb b/lib/json_api_kit/version_changes.rb
new file mode 100644
index 00000000000..61beed6a9d3
--- /dev/null
+++ b/lib/json_api_kit/version_changes.rb
@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class VersionChanges
+ include Enumerable
+
+ CHANGES_DIRECTORY = Rails.root.join("config/api_changes")
+ DATE_PREFIX = /\A\d{4}-\d{2}-\d{2}_/
+
+ class << self
+ def core = @core ||= load(CHANGES_DIRECTORY)
+
+ def load(directory)
+ new(
+ Dir
+ .glob(directory.join("*.rb"))
+ .map { change_in(it) }
+ .each(&:verify!)
+ .sort_by { [it.version, it.source] },
+ )
+ end
+
+ 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)
+ Kernel.load(source)
+ constant.constantize.new(source)
+ end
+ end
+
+ delegate :each, to: :changes
+
+ def initialize(changes)
+ @changes = changes
+ end
+
+ def after(version) = select { it.version > version }
+
+ private
+
+ attr_reader :changes
+ end
+end
diff --git a/spec/integration/json_api_kit/merged_attributes_spec.rb b/spec/integration/json_api_kit/merged_attributes_spec.rb
index 1ab82c611b4..1b375d65e1c 100644
--- a/spec/integration/json_api_kit/merged_attributes_spec.rb
+++ b/spec/integration/json_api_kit/merged_attributes_spec.rb
@@ -38,6 +38,7 @@ RSpec.describe "JSON:API merged attributes", type: :request do
let(:first_version) { JsonApiKit::Timeline::FIRST_RELEASE }
let(:merge) { JsonApiKitSpec::MergeTopicsPostedDateAndTimeIntoPostedAt.new(__FILE__) }
let(:rename) { JsonApiKitSpec::RenameMergedTopicsPostedAtToCreatedAt.new(__FILE__) }
+ let(:version_changes) { JsonApiKit::VersionChanges.new([merge, rename]) }
let(:version) { first_version.to_s }
let(:parsed_body) { JSON.parse(response.body) }
let(:error) { parsed_body["errors"].sole }
@@ -46,7 +47,7 @@ RSpec.describe "JSON:API merged attributes", type: :request do
before do
freeze_time(rename.version.date + 1.day)
- allow(JsonApiKit::VersionChange).to receive(:all).and_return([merge, rename])
+ allow(JsonApiKit::VersionChanges).to receive(:core).and_return(version_changes)
Rails.application.routes.disable_clear_and_finalize = true
Rails.application.routes.draw do
get "/api/merged-topics" => "json_api_kit_spec/merged_topics#index"
diff --git a/spec/integration/json_api_kit/renamed_types_spec.rb b/spec/integration/json_api_kit/renamed_types_spec.rb
index 70613ffd41c..3c70b6fe8fb 100644
--- a/spec/integration/json_api_kit/renamed_types_spec.rb
+++ b/spec/integration/json_api_kit/renamed_types_spec.rb
@@ -68,6 +68,7 @@ RSpec.describe "JSON:API type renames", type: :request do
].map { it.new(__FILE__) }
end
let(:version) { JsonApiKit::Timeline::FIRST_RELEASE.to_s }
+ let(:version_changes) { JsonApiKit::VersionChanges.new(changes) }
let(:parsed_body) { JSON.parse(response.body) }
let(:primary) { parsed_body.fetch("data").first }
let(:attributes) { primary.fetch("attributes") }
@@ -89,7 +90,7 @@ RSpec.describe "JSON:API type renames", type: :request do
middle.update_columns(last_posted_at: Time.utc(2026, 8, 1))
newest.update_columns(last_posted_at: Time.utc(2026, 8, 2))
freeze_time(Date.new(2026, 9, 5))
- allow(JsonApiKit::VersionChange).to receive(:all).and_return(changes)
+ allow(JsonApiKit::VersionChanges).to receive(:core).and_return(version_changes)
Rails.application.routes.disable_clear_and_finalize = true
Rails.application.routes.draw do
get "/api/topics" => "json_api_kit_spec/renamed_types#index"
diff --git a/spec/integration/json_api_kit/version_changes_spec.rb b/spec/integration/json_api_kit/version_changes_spec.rb
index 0babe81b424..a8f3f433865 100644
--- a/spec/integration/json_api_kit/version_changes_spec.rb
+++ b/spec/integration/json_api_kit/version_changes_spec.rb
@@ -27,8 +27,9 @@ 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_change) { JsonApiKitSpec::RenameTopicsPostedAtToCreatedAt.new(__FILE__) }
+ let(:version_changes) { JsonApiKit::VersionChanges.new([version_change]) }
+ let(:change_version) { version_change.version }
let(:version) { first_version.to_s }
let(:parsed_body) { JSON.parse(response.body) }
let(:error) { parsed_body["errors"].sole }
@@ -40,7 +41,7 @@ RSpec.describe "JSON:API version changes", type: :request do
middle.update_columns(last_posted_at: Time.utc(2026, 8, 1))
newest.update_columns(last_posted_at: Time.utc(2026, 8, 2))
freeze_time(change_version.date + 1.day)
- allow(JsonApiKit::VersionChange).to receive(:all).and_return([change])
+ allow(JsonApiKit::VersionChanges).to receive(:core).and_return(version_changes)
Rails.application.routes.disable_clear_and_finalize = true
Rails.application.routes.draw do
get "/api/changed-topics" => "json_api_kit_spec/changed_topics#index"
diff --git a/spec/lib/json_api_kit/document/relationship_object_spec.rb b/spec/lib/json_api_kit/document/relationship_object_spec.rb
index 51c296994d2..7d65c7560cb 100644
--- a/spec/lib/json_api_kit/document/relationship_object_spec.rb
+++ b/spec/lib/json_api_kit/document/relationship_object_spec.rb
@@ -54,7 +54,9 @@ RSpec.describe JsonApiKit::Document::RelationshipObject do
.new(__FILE__)
end
- before { allow(JsonApiKit::VersionChange).to receive(:after).and_return([version_change]) }
+ before do
+ allow(JsonApiKit::VersionChanges.core).to receive(:after).and_return([version_change])
+ end
it "translates the linkage type" do
expect(relationship_object.to_h[:data]).to eq(type: "topicAuthors", id: author.id.to_s)
diff --git a/spec/lib/json_api_kit/glossary/version_rule_spec.rb b/spec/lib/json_api_kit/glossary/version_rule_spec.rb
index 667d8190904..283ca2e2e1a 100644
--- a/spec/lib/json_api_kit/glossary/version_rule_spec.rb
+++ b/spec/lib/json_api_kit/glossary/version_rule_spec.rb
@@ -60,7 +60,9 @@ RSpec.describe JsonApiKit::Glossary::VersionRule do
let(:name) { JsonApiKit::Name::Field.new(value:, type: "topics") }
let(:value) { "posted_at" }
- before { allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(changes) }
+ before do
+ allow(JsonApiKit::VersionChanges.core).to receive(:after).with(version).and_return(changes)
+ end
describe "#declared_attributes" do
subject(:declared_attributes) { rule.declared_attributes(attributes) }
diff --git a/spec/lib/json_api_kit/glossary_spec.rb b/spec/lib/json_api_kit/glossary_spec.rb
index 3df45e30c13..d092fd5c5ba 100644
--- a/spec/lib/json_api_kit/glossary_spec.rb
+++ b/spec/lib/json_api_kit/glossary_spec.rb
@@ -113,7 +113,7 @@ RSpec.describe JsonApiKit::Glossary do
let(:value) { "words" }
before do
- allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
+ allow(JsonApiKit::VersionChanges.core).to receive(:after).with(version).and_return(
[JsonApiKitSpec::GlossaryShapeChange.new(__FILE__)],
)
end
@@ -208,7 +208,9 @@ RSpec.describe JsonApiKit::Glossary do
.new(__FILE__)
end
- before { allow(JsonApiKit::VersionChange).to receive(:after).and_return([version_change]) }
+ before do
+ allow(JsonApiKit::VersionChanges.core).to receive(:after).and_return([version_change])
+ end
it "translates the correction through the remaining rules" do
expect { declared_name }.to raise_error(
@@ -275,7 +277,7 @@ RSpec.describe JsonApiKit::Glossary do
let(:value) { "postedAt" }
before do
- allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
+ allow(JsonApiKit::VersionChanges.core).to receive(:after).with(version).and_return(
[version_change],
)
end
@@ -304,7 +306,7 @@ RSpec.describe JsonApiKit::Glossary do
let(:value) { "createdAt" }
before do
- allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
+ allow(JsonApiKit::VersionChanges.core).to receive(:after).with(version).and_return(
[version_change, JsonApiKitSpec::GlossaryReuseChange.new(__FILE__)],
)
end
@@ -344,7 +346,9 @@ RSpec.describe JsonApiKit::Glossary do
.new(__FILE__)
end
- before { allow(JsonApiKit::VersionChange).to receive(:after).and_return([version_change]) }
+ before do
+ allow(JsonApiKit::VersionChanges.core).to receive(:after).and_return([version_change])
+ end
it "returns the historical type in camel case" do
expect(member_type).to eq("forumTopics")
@@ -365,7 +369,7 @@ RSpec.describe JsonApiKit::Glossary do
subject(:glossary) { described_class.resource(version) }
before do
- allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
+ allow(JsonApiKit::VersionChanges.core).to receive(:after).with(version).and_return(
[JsonApiKitSpec::GlossaryShapeChange.new(__FILE__)],
)
end
@@ -414,7 +418,7 @@ RSpec.describe JsonApiKit::Glossary do
subject(:glossary) { described_class.resource(version) }
before do
- allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
+ allow(JsonApiKit::VersionChanges.core).to receive(:after).with(version).and_return(
[version_change],
)
end
diff --git a/spec/lib/json_api_kit/request/parameters_spec.rb b/spec/lib/json_api_kit/request/parameters_spec.rb
index 16cda01f044..77900749d22 100644
--- a/spec/lib/json_api_kit/request/parameters_spec.rb
+++ b/spec/lib/json_api_kit/request/parameters_spec.rb
@@ -166,10 +166,12 @@ RSpec.describe JsonApiKit::Request::Parameters do
context "with a version change" do
let(:glossary) { JsonApiKit::Glossary.resource(version) }
let(:version) { JsonApiKit::Timeline::FIRST_RELEASE }
- let(:change) { JsonApiKitSpec::ParametersChange.new(__FILE__) }
+ let(:version_change) { JsonApiKitSpec::ParametersChange.new(__FILE__) }
before do
- allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return([change])
+ allow(JsonApiKit::VersionChanges.core).to receive(:after).with(version).and_return(
+ [version_change],
+ )
end
context "when a fieldset has a renamed field" do
@@ -205,7 +207,7 @@ RSpec.describe JsonApiKit::Request::Parameters do
end
context "when the sort has two fields that merge into one" do
- let(:change) { JsonApiKitSpec::ParametersMergeChange.new(__FILE__) }
+ let(:version_change) { JsonApiKitSpec::ParametersMergeChange.new(__FILE__) }
let(:parameters) { { "sort" => "postedDate,postedTime" } }
it "converts both to the one field" do
@@ -256,7 +258,7 @@ RSpec.describe JsonApiKit::Request::Parameters do
end
context "when the anchor has a reshaped field" do
- let(:change) { JsonApiKitSpec::ParametersShapeChange.new(__FILE__) }
+ let(:version_change) { JsonApiKitSpec::ParametersShapeChange.new(__FILE__) }
let(:parameters) { { "page" => { "anchor" => { "words" => %w[Anchors and pages] } } } }
it "converts the field to its current name and shape" do
@@ -338,7 +340,9 @@ RSpec.describe JsonApiKit::Request::Parameters do
end
before do
- allow(JsonApiKit::VersionChange).to receive(:after).and_return([field_change, type_change])
+ allow(JsonApiKit::VersionChanges.core).to receive(:after).and_return(
+ [field_change, type_change],
+ )
end
context "when the request supplies a fieldset" do
diff --git a/spec/lib/json_api_kit/timeline_spec.rb b/spec/lib/json_api_kit/timeline_spec.rb
index ca8878a0d6f..06d8239e34d 100644
--- a/spec/lib/json_api_kit/timeline_spec.rb
+++ b/spec/lib/json_api_kit/timeline_spec.rb
@@ -16,15 +16,17 @@ RSpec.describe JsonApiKit::Timeline do
let(:first) { described_class::FIRST_RELEASE }
let(:middle) { JsonApiKit::ApiVersion.parse("2026-11-15") }
let(:latest) { JsonApiKit::ApiVersion.parse("2027-01-05") }
+ let(:changes) do
+ [
+ JsonApiKitSpec::MiddleTimelineChange.new(__FILE__),
+ JsonApiKitSpec::LatestTimelineChange.new(__FILE__),
+ ]
+ end
+ let(:version_changes) { JsonApiKit::VersionChanges.new(changes) }
before do
freeze_time(Date.new(2027, 1, 20))
- allow(JsonApiKit::VersionChange).to receive(:all).and_return(
- [
- JsonApiKitSpec::MiddleTimelineChange.new(__FILE__),
- JsonApiKitSpec::LatestTimelineChange.new(__FILE__),
- ],
- )
+ allow(JsonApiKit::VersionChanges).to receive(:core).and_return(version_changes)
end
describe ".first" do
@@ -39,7 +41,7 @@ RSpec.describe JsonApiKit::Timeline do
end
context "when there is no change" do
- before { allow(JsonApiKit::VersionChange).to receive(:all).and_return([]) }
+ let(:changes) { [] }
it "returns the first release" do
expect(described_class.current).to eq(first)
diff --git a/spec/lib/json_api_kit/version_change_spec.rb b/spec/lib/json_api_kit/version_change_spec.rb
index 23fd3ae54be..e44f9e32ac9 100644
--- a/spec/lib/json_api_kit/version_change_spec.rb
+++ b/spec/lib/json_api_kit/version_change_spec.rb
@@ -59,105 +59,12 @@ module JsonApiKitSpec
end
RSpec.describe JsonApiKit::VersionChange do
- subject(:change) { change_class.new(__FILE__) }
+ subject(:version_change) { change_class.new(__FILE__) }
let(:change_class) { JsonApiKitSpec::RenameThingsLabelToName }
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
-
- context "when a change renames one name twice" do
- let(:directory) { "api_changes_with_two_renames_from_one_name" }
-
- it { expect { changes }.to raise_error(ArgumentError, /changes label twice/) }
- end
-
- context "when a change renames two names to one name" do
- let(:directory) { "api_changes_with_two_renames_to_one_name" }
-
- it { expect { changes }.to raise_error(ArgumentError, /changes two names into title/) }
- 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 ".resource" do
subject(:transformations) { change_class.transformations }
@@ -232,20 +139,20 @@ RSpec.describe JsonApiKit::VersionChange do
describe "#version" do
it "returns the version of the change" do
- expect(change.version).to eq(version)
+ expect(version_change.version).to eq(version)
end
end
describe "#description" do
it "returns the description of the change" do
- expect(change.description).to eq(
+ expect(version_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) }
+ subject(:current_name) { version_change.current(name) }
it "returns the name after the change" do
expect(current_name).to eq(name.with(value: "name"))
@@ -297,7 +204,7 @@ RSpec.describe JsonApiKit::VersionChange do
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(
+ expect([version_change.current(name), version_change.current(other_name)]).to eq(
[name.with(value: "name"), other_name.with(value: "username")],
)
end
@@ -305,7 +212,7 @@ RSpec.describe JsonApiKit::VersionChange do
end
describe "#current_attributes" do
- subject(:current_attributes) { change.current_attributes(attributes) }
+ subject(:current_attributes) { version_change.current_attributes(attributes) }
let(:attributes) { { name => "A", other_name => "B" } }
let(:other_name) { JsonApiKit::Name::Field.new(value: "size", type: "things") }
@@ -349,7 +256,7 @@ RSpec.describe JsonApiKit::VersionChange do
end
describe "#previous" do
- subject(:previous_name) { change.previous(name) }
+ subject(:previous_name) { version_change.previous(name) }
let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }
@@ -368,7 +275,7 @@ RSpec.describe JsonApiKit::VersionChange do
end
describe "#previous_names" do
- subject(:previous_names) { change.previous_names(name) }
+ subject(:previous_names) { version_change.previous_names(name) }
let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }
@@ -389,7 +296,7 @@ RSpec.describe JsonApiKit::VersionChange do
end
describe "#previous_attributes" do
- subject(:previous_attributes) { change.previous_attributes(attributes) }
+ subject(:previous_attributes) { version_change.previous_attributes(attributes) }
let(:attributes) { { name => "A", other_name => "B" } }
let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }
diff --git a/spec/lib/json_api_kit/version_changes_spec.rb b/spec/lib/json_api_kit/version_changes_spec.rb
new file mode 100644
index 00000000000..3c0da966742
--- /dev/null
+++ b/spec/lib/json_api_kit/version_changes_spec.rb
@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+RSpec.describe JsonApiKit::VersionChanges do
+ let(:fixtures) { Rails.root.join("spec/fixtures/json_api_kit") }
+
+ before { freeze_time(Date.new(2026, 9, 10)) }
+
+ describe ".core" do
+ subject(:core_changes) { collection_class.core }
+
+ let(:collection_class) { Class.new(described_class) }
+
+ before { allow(collection_class).to receive(:load).and_call_original }
+
+ it "loads the core change directory" do
+ core_changes
+ expect(collection_class).to have_received(:load).with(described_class::CHANGES_DIRECTORY)
+ end
+
+ it "reuses the collection across calls" do
+ expect(core_changes).to equal(collection_class.core)
+ end
+ end
+
+ describe ".load" do
+ subject(:changes) { described_class.load(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 same directory is loaded again" do
+ let(:previous_class) { described_class.load(fixtures.join(directory)).first.class }
+
+ before { previous_class }
+
+ it "replaces the previous class" do
+ expect(changes.first.class).not_to equal(previous_class)
+ end
+ 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
+
+ context "when a change renames one name twice" do
+ let(:directory) { "api_changes_with_two_renames_from_one_name" }
+
+ it { expect { changes }.to raise_error(ArgumentError, /changes label twice/) }
+ end
+
+ context "when a change renames two names to one name" do
+ let(:directory) { "api_changes_with_two_renames_to_one_name" }
+
+ it { expect { changes }.to raise_error(ArgumentError, /changes two names into title/) }
+ end
+ end
+
+ describe "#after" do
+ subject(:changes_after_pin) { version_changes.after(pin) }
+
+ let(:version_changes) { described_class.load(fixtures.join("api_changes")) }
+ let(:pin) { JsonApiKit::ApiVersion.parse("2026-09-01") }
+
+ it "returns only changes after the pin" do
+ expect(changes_after_pin).to contain_exactly(version_changes.to_a.last)
+ end
+
+ context "when the pin precedes every change" do
+ let(:pin) { JsonApiKit::Timeline::FIRST_RELEASE }
+
+ it "preserves the order of the changes" do
+ expect(changes_after_pin.map { it.version.to_s }).to eq(%w[2026-09-01 2026-09-02])
+ end
+ end
+
+ context "when the pin is the latest version" do
+ let(:pin) { JsonApiKit::ApiVersion.parse("2026-09-02") }
+
+ it "returns no change" do
+ expect(changes_after_pin).to be_empty
+ end
+ end
+ end
+end