cancer_registry_reporting_test_kit 0.9.0

data/lib/cancer_registry_reporting_test_kit/search_test_properties.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CancerRegistryReportingTestKit
+  class SearchTestProperties
+    ATTRIBUTES = %i[
+      resource_type
+      search_param_names
+      first_search
+      fixed_value_search
+      saves_delayed_references
+      possible_status_search
+      test_medication_inclusion
+      token_search_params
+      test_reference_variants
+      params_with_comparators
+      multiple_or_search_params
+      test_post_search
+    ].freeze
+
+    ATTRIBUTES.each { |name| attr_reader name }
+
+    def initialize(**properties)
+      properties.each do |key, value|
+        raise StandardError, "Unkown search test property: #{key}" unless ATTRIBUTES.include?(key)
+
+        instance_variable_set(:"@#{key}", value)
+      end
+    end
+
+    def first_search?
+      !!first_search
+    end
+
+    def fixed_value_search?
+      !!fixed_value_search
+    end
+
+    def saves_delayed_references?
+      !!saves_delayed_references
+    end
+
+    def possible_status_search?
+      !!possible_status_search
+    end
+
+    def test_medication_inclusion?
+      !!test_medication_inclusion
+    end
+
+    def test_reference_variants?
+      !!test_reference_variants
+    end
+
+    def test_post_search?
+      !!test_post_search
+    end
+  end
+end

data/lib/cancer_registry_reporting_test_kit/validation_test.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module CancerRegistryReportingTestKit
+  module ValidationTest
+    DAR_CODE_SYSTEM_URL = 'http://terminology.hl7.org/CodeSystem/data-absent-reason'
+    DAR_EXTENSION_URL = 'http://hl7.org/fhir/StructureDefinition/data-absent-reason'
+
+    def perform_validation_test(resourceType = resource_type,
+                                resources,
+                                profile_url,
+                                profile_version,
+                                skip_if_empty: true)
+      find_validation_errors(resourceType, resources, profile_url, profile_version, skip_if_empty: )
+      errors_found = messages.any? { |message| message[:type] == 'error' }
+
+      profile_with_version = "#{profile_url}|#{profile_version}"
+      assert !errors_found, "Resource does not conform to the profile #{profile_with_version}"
+    end
+
+    def find_validation_errors(resourceType = resource_type,
+                          resources,
+                          profile_url,
+                          profile_version,
+                          skip_if_empty: true)
+      skip_if skip_if_empty && resources.blank?,
+              "No #{resourceType} resources conforming to the #{profile_url} profile were returned"
+
+      omit_if resources.blank?,
+              "No #{resourceType} resources provided so the #{profile_url} profile does not apply"
+
+      profile_with_version = "#{profile_url}|#{profile_version}"
+      resources.each do |resource|
+        resource_is_valid?(resource: resource, profile_url: profile_with_version)
+        # DAR checks are a SHOULD requirement in CCRR 1.0.1
+        # check_for_dar(resource)
+      end
+    end
+
+
+    def check_for_dar(resource)
+      unless scratch[:dar_code_found]
+        resource.each_element do |element, _meta, _path|
+          next unless element.is_a?(FHIR::Coding)
+
+          check_for_dar_code(element)
+        end
+      end
+
+      return if scratch[:dar_extension_found]
+
+      check_for_dar_extension(resource)
+    end
+
+    def check_for_dar_code(coding)
+      return unless coding.code == 'unknown' && coding.system == DAR_CODE_SYSTEM_URL
+
+      scratch[:dar_code_found] = true
+      output dar_code_found: 'true'
+    end
+
+    def check_for_dar_extension(resource)
+      return unless resource.source_contents&.include? DAR_EXTENSION_URL
+
+      scratch[:dar_extension_found] = true
+      output dar_extension_found: 'true'
+    end
+  end
+end

data/lib/cancer_registry_reporting_test_kit/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module CancerRegistryReportingTestKit
+  VERSION = '0.9.0'
+  LAST_UPDATED = '2025-05-07' # TODO: update next release
+end

data/lib/cancer_registry_reporting_test_kit.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'cancer_registry_reporting_test_kit/metadata'
+require_relative 'inferno_requirements_tools/ext/inferno_core/runnable'
+require_relative 'cancer_registry_reporting_test_kit/ehr_suite'
+require_relative 'cancer_registry_reporting_test_kit/hdea_suite'

data/lib/inferno_requirements_tools/ext/inferno_core/runnable.rb

@@ -0,0 +1,22 @@
+module Inferno
+  module DSL
+    # This module contains the DSL for defining child entities in the test
+    # definition framework.
+    module Runnable
+      # Set/Get the IDs of requirements verifed by this runnable
+      # Set with [] to clear the list
+      #
+      # @param requirements [Array<String>]
+      # @return [Array<String>] the requirement IDs
+      def verifies_requirements(*requirement_ids)
+        if requirement_ids.empty?
+          @requirement_ids || []
+        elsif requirement_ids == [[]]
+          @requirement_ids = []
+        else
+          @requirement_ids = requirement_ids
+        end
+      end
+    end
+  end
+end

data/lib/inferno_requirements_tools/tasks/requirements_coverage.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require 'csv'
+require 'yaml'
+require_relative '../ext/inferno_core/runnable'
+
+module InfernoRequirementsTools
+  module Tasks
+    # This class manages the mapping of test kit tests to requirements that they verify
+    # and creates a CSV file with the tests that cover each requirement.
+    # It expects a CSV file in the repo at `lib/[test kit id]/requirements/[test kit id]_requirements.csv`
+    # that serves as the source of the requirement set for the test kit. The requirements in
+    # this files are identified by a requirement set and an id and tests, groups, and suites
+    # within in the test kit can claim that they verify a requirement by including a reference
+    # to that requirementin the form <requirement set>@<id> in their `verifies_requirements` field.
+    # Requirements that are out of scope can be listed in a companion file
+    # `lib/[test kit id]/requirements/[test kit id]_out_of_scope_requirements.csv`.
+    #
+    # The `run` method generates a CSV file at
+    # `lib/[test kit id]/requirements/generated/[test kit id]_requirements_coverage.csv``.
+    # This file will be identical to the input spreadsheet, plus an additional column which holds a comma separated
+    # list of inferno test IDs that test each requirement. These test IDs are Inferno short form IDs that represent the
+    # position of the test within its group and suite. For example, the fifth test in the second group will have an ID
+    # of 2.05. This ID is also shown in the Inferno web UI.
+    #
+    # The `run_check` method will check whether the previously generated file is up-to-date.
+    class RequirementsCoverage
+      VERSION = '0.2.0' # update when making meaningful changes to this method for tracking used versions
+      CONFIG = YAML.load_file(File.join('lib', 'requirements_config.yaml'))
+
+      TEST_KIT_ID = CONFIG['test_kit_id']
+      TEST_SUITES = CONFIG['suites'].map do |test_suite|
+        Object.const_get(test_suite['class_name'])
+      end
+
+      SUITE_ID_TO_ACTOR_MAP = CONFIG['suites'].each_with_object({}) do |test_suite, hash|
+        hash[test_suite['id']] = test_suite['suite_actor']
+      end
+
+      # Derivative constants
+      TEST_KIT_CODE_FOLDER = TEST_KIT_ID
+      DASHERIZED_TEST_KIT_ID = TEST_KIT_ID.gsub('_', '-')
+      INPUT_HEADERS = [
+        'Req Set',
+        'ID',
+        'URL',
+        'Requirement',
+        'Conformance',
+        'Actor',
+        'Sub-Requirement(s)',
+        'Conditionality'
+      ].freeze
+      SHORT_ID_HEADER = 'Short ID(s)'
+      FULL_ID_HEADER = 'Full ID(s)'
+      INPUT_FILE_NAME = "#{DASHERIZED_TEST_KIT_ID}_requirements.csv".freeze
+      INPUT_FILE = File.join('lib', TEST_KIT_CODE_FOLDER, 'requirements', INPUT_FILE_NAME).freeze
+      NOT_TESTED_FILE_NAME = "#{DASHERIZED_TEST_KIT_ID}_out_of_scope_requirements.csv".freeze
+      NOT_TESTED_FILE = File.join('lib', TEST_KIT_CODE_FOLDER, 'requirements', NOT_TESTED_FILE_NAME).freeze
+      OUTPUT_HEADERS = INPUT_HEADERS + TEST_SUITES.flat_map do |suite|
+                                         ["#{suite.title} #{SHORT_ID_HEADER}", "#{suite.title} #{FULL_ID_HEADER}"]
+                                       end
+      OUTPUT_FILE_NAME = "#{DASHERIZED_TEST_KIT_ID}_requirements_coverage.csv".freeze
+      OUTPUT_FILE_DIRECTORY = File.join('lib', TEST_KIT_CODE_FOLDER, 'requirements', 'generated')
+      OUTPUT_FILE = File.join(OUTPUT_FILE_DIRECTORY, OUTPUT_FILE_NAME).freeze
+
+      def input_rows
+        @input_rows ||=
+          CSV.parse(File.open(INPUT_FILE, 'r:bom|utf-8'), headers: true).map do |row|
+            row.to_h.slice(*INPUT_HEADERS)
+          end
+      end
+
+      def not_tested_requirements_map
+        @not_tested_requirements_map ||= load_not_tested_requirements
+      end
+
+      def load_not_tested_requirements
+        return {} unless File.exist?(NOT_TESTED_FILE)
+
+        not_tested_requirements = {}
+        CSV.parse(File.open(NOT_TESTED_FILE, 'r:bom|utf-8'), headers: true).each do |row|
+          row_hash = row.to_h
+          not_tested_requirements["#{row_hash['Req Set']}@#{row_hash['ID']}"] = row_hash
+        end
+
+        not_tested_requirements
+      end
+
+      # Of the form:
+      # {
+      #     'req-id-1': [
+      #       { short_id: 'short-id-1', full_id: 'long-id-1', suite_id: 'suite-id-1' },
+      #       { short_id: 'short-id-2', full_id: 'long-id-2', suite_id: 'suite-id-2' }
+      #     ],
+      #     'req-id-2': [{ short_id: 'short-id-3', full_id: 'long-id-3', suite_id: 'suite-id-3' }],
+      #     ...
+      # }
+      def inferno_requirements_map
+        @inferno_requirements_map ||= TEST_SUITES.each_with_object({}) do |suite, requirements_map|
+          serialize_requirements(suite, 'suite', suite.id, requirements_map)
+          suite.groups.each do |group|
+            map_group_requirements(group, suite.id, requirements_map)
+          end
+        end
+      end
+
+      def new_csv
+        @new_csv ||=
+          CSV.generate(+"\xEF\xBB\xBF") do |csv|
+            csv << OUTPUT_HEADERS
+            input_rows.each do |row| # NOTE: use row order from source file
+              next if row['Conformance'] == 'DEPRECATED' # filter out deprecated rows
+
+              TEST_SUITES.each do |suite|
+                suite_actor = SUITE_ID_TO_ACTOR_MAP[suite.id]
+                if row['Actor']&.include?(suite_actor)
+                  add_suite_tests_for_row(row, suite)
+                else
+                  row["#{suite.title} #{SHORT_ID_HEADER}"] = 'NA'
+                  row["#{suite.title} #{FULL_ID_HEADER}"] = 'NA'
+                end
+              end
+              csv << row.values
+            end
+          end
+      end
+
+      def add_suite_tests_for_row(row, suite)
+        set_and_req_id = "#{row['Req Set']}@#{row['ID']}"
+        items = get_items_for_requirement(set_and_req_id, suite)
+        short_ids = items[0]
+        full_ids = items[1]
+        if short_ids.blank? && not_tested_requirements_map.key?(set_and_req_id)
+          row["#{suite.title} #{SHORT_ID_HEADER}"] = 'Not Tested'
+          row["#{suite.title} #{FULL_ID_HEADER}"] = 'Not Tested'
+        else
+          row["#{suite.title} #{SHORT_ID_HEADER}"] = short_ids&.join(', ')
+          row["#{suite.title} #{FULL_ID_HEADER}"] = full_ids&.join(', ')
+        end
+      end
+
+      def get_items_for_requirement(set_and_req_id, suite)
+        suite_requirement_items = inferno_requirements_map[set_and_req_id]&.filter do |item|
+          item[:suite_id] == suite.id
+        end
+        [
+          suite_requirement_items&.map { |item| item[:short_id] },
+          suite_requirement_items&.map { |item| item[:full_id] }
+        ]
+      end
+
+      def input_requirement_ids
+        @input_requirement_ids ||= input_rows.map { |row| "#{row['Req Set']}@#{row['ID']}" }
+      end
+
+      # The requirements present in Inferno that aren't in the input spreadsheet
+      def unmatched_requirements_map
+        @unmatched_requirements_map ||= inferno_requirements_map.except(*input_requirement_ids)
+      end
+
+      def old_csv
+        @old_csv ||= File.read(OUTPUT_FILE)
+      end
+
+      def run
+        unless File.exist?(INPUT_FILE)
+          puts "Could not find input file: #{INPUT_FILE}. Aborting requirements coverage generation..."
+          exit(1)
+        end
+
+        if unmatched_requirements_map.any?
+          puts "WARNING: The following requirements indicated in the test kit are not present in #{INPUT_FILE_NAME}"
+          output_requirements_map_table(unmatched_requirements_map)
+        end
+
+        if File.exist?(OUTPUT_FILE)
+          if old_csv == new_csv
+            puts "'#{OUTPUT_FILE_NAME}' file is up to date."
+            return
+          else
+            puts 'Requirements coverage has changed.'
+          end
+        else
+          puts "No existing #{OUTPUT_FILE_NAME}."
+        end
+
+        puts "Writing to file #{OUTPUT_FILE}..."
+        FileUtils.mkdir_p(OUTPUT_FILE_DIRECTORY)
+        File.write(OUTPUT_FILE, new_csv)
+        puts 'Done.'
+      end
+
+      def run_check
+        unless File.exist?(INPUT_FILE)
+          puts "Could not find input file: #{INPUT_FILE}. Aborting requirements coverage check..."
+          exit(1)
+        end
+
+        if unmatched_requirements_map.any?
+          puts "The following requirements indicated in the test kit are not present in #{INPUT_FILE_NAME}"
+          output_requirements_map_table(unmatched_requirements_map)
+        end
+
+        if File.exist?(OUTPUT_FILE)
+          if old_csv == new_csv
+            puts "'#{OUTPUT_FILE_NAME}' file is up to date."
+            return unless unmatched_requirements_map.any?
+          else
+            puts <<~MESSAGE
+              #{OUTPUT_FILE_NAME} file is out of date.
+              To regenerate the file, run:
+
+                  bundle exec rake requirements:generate_coverage
+
+            MESSAGE
+          end
+        else
+          puts <<~MESSAGE
+            No existing #{OUTPUT_FILE_NAME} file.
+            To generate the file, run:
+
+                  bundle exec rake requirements:generate_coverage
+
+          MESSAGE
+        end
+
+        puts 'Check failed.'
+        exit(1)
+      end
+
+      def map_group_requirements(group, suite_id, requirements_map)
+        serialize_requirements(group, group.short_id, suite_id, requirements_map)
+        group.tests&.each { |test| serialize_requirements(test, test.short_id, suite_id, requirements_map) }
+        group.groups&.each { |subgroup| map_group_requirements(subgroup, suite_id, requirements_map) }
+      end
+
+      def serialize_requirements(runnable, short_id, suite_id, requirements_map)
+        runnable.verifies_requirements&.each do |requirement_id|
+          requirement_id_string = requirement_id.to_s
+
+          requirements_map[requirement_id_string] ||= []
+          requirements_map[requirement_id_string] << { short_id:, full_id: runnable.id, suite_id: }
+        end
+      end
+
+      # Output the requirements in the map like so:
+      #
+      # requirement_id | short_id   | full_id
+      # ---------------+------------+----------
+      # req-id-1       | short-id-1 | full-id-1
+      # req-id-2       | short-id-2 | full-id-2
+      #
+      def output_requirements_map_table(requirements_map)
+        headers = %w[requirement_id short_id full_id]
+        col_widths = headers.map(&:length)
+        col_widths[0] = [col_widths[0], requirements_map.keys.map(&:length).max].max
+        col_widths[1] = ([col_widths[1]] + requirements_map.values.flatten.map { |item| item[:short_id].length }).max
+        col_widths[2] = ([col_widths[2]] + requirements_map.values.flatten.map { |item| item[:full_id].length }).max
+        col_widths.map { |width| width + 3 }
+
+        puts [
+          headers[0].ljust(col_widths[0]),
+          headers[1].ljust(col_widths[1]),
+          headers[2].ljust(col_widths[2])
+        ].join(' | ')
+        puts col_widths.map { |width| '-' * width }.join('-+-')
+        output_requirements_map_table_contents(requirements_map, col_widths)
+        puts
+      end
+
+      def output_requirements_map_table_contents(requirements_map, col_widths)
+        requirements_map.each do |requirement_id, runnables|
+          runnables.each do |runnable|
+            puts [
+              requirement_id.ljust(col_widths[0]),
+              runnable[:short_id].ljust(col_widths[1]),
+              runnable[:full_id].ljust(col_widths[2])
+            ].join(' | ')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/requirements_config.yaml

@@ -0,0 +1,22 @@
+test_kit_id: cancer_registry_reporting_test_kit
+
+suites: 
+  - id: ccrr_ehr
+    class_name: CancerRegistryReportingTestKit::EHRSuite
+    suite_actor: EHR
+  - id: ccrr_v100_report_generation
+    class_name: CancerRegistryReportingTestKit::CCRRV100::HDEASuite
+    suite_actor: HDEA
+
+requirement_sets:
+  - id: hl7.fhir.us.central-cancer-registry-reporting_1.0.0
+    folder: Central Cancer Registry Reporting
+    requirements: All
+    actor_map:
+      - {spec: EHR, test_kit: EHR}
+      - {spec: HDEA, test_kit: HDEA}
+  - id: hl7.fhir.us.mcode_3.0.0
+    folder: mCode
+    requirements: Referenced
+    actor_map:
+      - {spec: mCode Data Sender, test_kit: EHR}