Add task to verify yard docs are up to date

Author: bdurand

CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - The default data directory in a Rails application can be set with the `config.support_table.data_directory` option in the Rails application configuration.
-- Added rake task `support_table_data:add_yard_docs` for Rails applications that will add YARD documentation to support table models for the named instance helpers.
+- Added rake task `support_table_data:add_yard_docs` for Rails applications that will add YARD documentation to support table models for the named instance helpers. There is also a task `support_table_data:verify_yard_docs` that can be used in a build pipeline to verify that the documentation is up to date.
 - The data synchronization task is now automatically attached to several Rails tasks: `db:seed`, `db:seed:replant`, `db:prepare`, `db:test:prepare`, `db:fixtures:load`. Support tables will be synced after running any of these tasks. This can be disabled by setting `config.support_table.auto_sync = false` in the Rails application configuration.
 
 ### Changed

README.md

@@ -196,7 +196,7 @@ The default behavior is to add the documentation comments at the end of the mode
 # End YARD docs for support_table_data
 ```
 
-A good practice is to add a check to your CI pipeline to ensure the documentation is always up to date.
+A good practice is to add a check to your CI pipeline to ensure the documentation is always up to date. You can run the rake task `support_table_data:verify_yard_docs` to do this. It will exit with an error if any models do not have up to date documentation.
 
 ### Caching
 

lib/tasks/support_table_data.rake

@@ -36,4 +36,26 @@ namespace :support_table_data do
       puts "Added YARD documentation to #{source_file.klass.name}."
     end
   end
+
+  desc "Verify that all the support table models have up to date YARD documentation for named instance methods."
+  task verify_yard_docs: :environment do
+    require_relative "../support_table_data/documentation"
+    require_relative "utils"
+
+    SupportTableData::Tasks::Utils.eager_load!
+
+    all_up_to_date = true
+    SupportTableData::Tasks::Utils.support_table_sources.each do |source_file|
+      unless source_file.yard_docs_up_to_date?
+        puts "YARD documentation is not up to date for #{source_file.klass.name}."
+        all_up_to_date = false
+      end
+    end
+
+    if all_up_to_date
+      puts "All support table models have up to date YARD documentation."
+    else
+      raise
+    end
+  end
 end

spec/tasks_spec.rb

@@ -3,7 +3,7 @@
 require_relative "spec_helper"
 require "rake"
 
-RSpec.describe "support_table_data" do
+RSpec.describe "support_table_data rake tasks" do
   let(:out) { StringIO.new }
 
   before do
@@ -60,4 +60,38 @@
       expect(color_write[:content]).to include("@!method self.red")
     end
   end
+
+  describe "verify_yard_docs" do
+    it "verifies YARD documentation is up to date" do
+      require_relative "../lib/support_table_data/documentation"
+      require_relative "../lib/tasks/utils"
+
+      allow($stdout).to receive(:puts)
+      allow_any_instance_of(SupportTableData::Documentation::SourceFile)
+        .to receive(:yard_docs_up_to_date?).and_return(true)
+
+      # Run the task
+      Rake.application.invoke_task "support_table_data:verify_yard_docs"
+
+      # Verify output indicates all docs are up to date
+      expect($stdout).to have_received(:puts).with("All support table models have up to date YARD documentation.")
+    end
+
+    it "raises an error if any YARD documentation is out of date" do
+      require_relative "../lib/support_table_data/documentation"
+      require_relative "../lib/tasks/utils"
+
+      allow($stdout).to receive(:puts)
+      allow_any_instance_of(SupportTableData::Documentation::SourceFile)
+        .to receive(:yard_docs_up_to_date?).and_return(false)
+
+      # Run the task and expect an error
+      expect {
+        Rake.application.invoke_task "support_table_data:verify_yard_docs"
+      }.to raise_error(RuntimeError)
+
+      # Verify output indicates which docs are out of date
+      expect($stdout).to have_received(:puts).at_least(:once)
+    end
+  end
 end