ecfr 1.0.0

data/lib/ecfr/testing/factories/search_service/date_facet_factory.rb

@@ -0,0 +1,12 @@
+FactoryBot.define do
+  factory :date_facet, class: "Ecfr::SearchService::DateFacet" do
+    skip_create
+
+    date { "2017-01-01" }
+    count { 1 }
+
+    initialize_with {
+      new(attributes.deep_stringify_keys)
+    }
+  end
+end

data/lib/ecfr/testing/factories/versioner_service/ancestors_factory.rb

@@ -0,0 +1,26 @@
+FactoryBot.define do
+  factory :ancestors, class: "Ecfr::VersionerService::Ancestors" do
+    skip_create
+
+    ancestors {
+      [ecfr_attribute_hash(:node_summary)]
+    }
+
+    metadata {
+      {
+        previous_node: ecfr_attribute_hash(:metadata_node_info),
+        next_node: ecfr_attribute_hash(:metadata_node_info)
+      }
+    }
+
+    trait :with_structure do
+      structure { ecfr_attribute_hash(:structure)["data"] }
+    end
+
+    source_xml_filesize { 2096 }
+
+    initialize_with {
+      new(attributes.deep_stringify_keys)
+    }
+  end
+end

data/lib/ecfr/testing/factories/versioner_service/metadata_node_info_factory.rb

@@ -0,0 +1,15 @@
+FactoryBot.define do
+  factory :metadata_node_info, class: "Ecfr::VersionerService::Ancestors::MetadataNodeInfo" do
+    skip_create
+
+    hierarchy {
+      ecfr_attribute_hash(:hierarchy, :with_defaults)
+    }
+
+    label { "Part 100 - Standards of Conduct" }
+
+    initialize_with {
+      new(attributes.deep_stringify_keys)
+    }
+  end
+end

data/lib/ecfr/testing/factories/versioner_service/node_summary_factory.rb

@@ -0,0 +1,16 @@
+FactoryBot.define do
+  factory :node_summary, class: "Ecfr::VersionerService::Ancestors::MetadataNodeInfo" do
+    skip_create
+
+    identifier { "3" }
+    label { "Title 3 - The President" }
+    label_level { "Title 3" }
+    label_description { "The President" }
+    reserved { false }
+    type { "title" }
+
+    initialize_with {
+      new(attributes.deep_stringify_keys)
+    }
+  end
+end

data/lib/ecfr/testing/factories/versioner_service/structure_factory.rb

@@ -0,0 +1,57 @@
+FactoryBot.define do
+  factory :structure, class: "Ecfr::VersionerService::Structure" do
+    skip_create
+
+    data {
+      {
+        identifier: "3",
+        label: "Title 3 - The President",
+        label_level: "Title 3",
+        label_description: "The President",
+        reserved: false,
+        type: "title",
+        children: [
+          {
+            identifier: "I",
+            label: " Chapter I - Executive Office of the President",
+            label_level: " Chapter I",
+            label_description: "Executive Office of the President",
+            reserved: false,
+            type: "chapter",
+            children: [
+              {
+                identifier: "101",
+                label: "Part 101 - Public Information Provisions of the Administrative Procedures Act",
+                label_level: "Part 101",
+                label_description: "Public Information Provisions of the Administrative Procedures Act",
+                reserved: false,
+                type: "part",
+                volumes: [
+                  "1"
+                ],
+                children: [
+                  {
+                    identifier: "101.1",
+                    label: "§ 101.1 Executive Office of the President.",
+                    label_level: "§ 101.1",
+                    label_description: "Executive Office of the President.",
+                    reserved: false,
+                    type: "section",
+                    volumes: [
+                      "1"
+                    ],
+                    received_on: "2018-10-17T01:00:00-0400"
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }.to_json
+    }
+
+    initialize_with {
+      new(data)
+    }
+  end
+end

data/lib/ecfr/testing/factories/versioner_service/title_factory.rb

@@ -0,0 +1,36 @@
+FactoryBot.define do
+  factory :title, class: "Ecfr::VersionerService::Title" do
+    skip_create
+
+    name { "General Provisions" }
+    number { 1 }
+
+    processing_in_progress { false }
+    reserved { false }
+
+    latest_amended_on { nil }
+    latest_issue_date { nil }
+    up_to_date_as_of { nil }
+
+    meta {
+      {
+        date: metadata_date,
+        import_in_progress: import_in_progress
+      }
+    }
+
+    transient do
+      metadata_date { nil }
+      import_in_progress { false }
+    end
+
+    initialize_with {
+      new(attributes.deep_stringify_keys)
+    }
+
+    trait :processing do
+      processing_in_progress { true }
+      import_in_progress { true }
+    end
+  end
+end

data/lib/ecfr/testing/factory_bot_helpers/content_version.rb

@@ -0,0 +1,38 @@
+module FactoryBotHelpers
+  module ContentVersion
+    extend self
+
+    def hierarchy_headings(attributes)
+      headings = attributes[:hierarchy].compact.each_with_object({}) do |attr, hsh|
+        hsh[attr[0]] = if attr[0] == :section
+          "§ #{attr[1]}"
+        elsif attr[0] == :appendix
+          attr[1]
+        else
+          [attr[0].to_s.capitalize, attr[1]].join(" ")
+        end
+      end
+
+      headings.merge(attributes[:hierarchy_headings])
+    end
+
+    def headings(attributes)
+      default_headings = {
+        title: "Energy",
+        subtitle: "Other Regulations Relating to Nuclear Power",
+        chapter: "Nuclear Regulatory Commission",
+        part: "Agency Rules of Practice and Procedure",
+        subpart: "Procedure for Imposing Requirements",
+        subject_group: "Serious Civil Penalties",
+        section: "Civil penalties",
+        appendix: "Possibilities, Procedures and Probabilities"
+      }
+
+      headings = attributes[:hierarchy].compact.each_with_object({}) do |attr, hsh|
+        hsh[attr[0]] = default_headings[attr[0]]
+      end
+
+      headings.merge(attributes[:headings])
+    end
+  end
+end

data/lib/ecfr/testing/factory_bot_helpers/ecfr_gem_initialize_helpers.rb

@@ -0,0 +1,51 @@
+module FactoryBotHelpers
+  module EcfrGemHelpers
+    extend self
+
+    # Allows an upstream user wants to override the factory defined in this gem
+    # be instantiated as another class defined in thier applicaiton (inheriting
+    # from a gem defined class). See the Extensible module for more details.
+    def override_factory_class(phactory, klass)
+      FactoryBot.modify do
+        factory phactory do
+          initialize_with {
+            attrs = FactoryBotHelpers::EcfrGemHelpers.pre_initialize_attrs_for(
+              phactory,
+              attributes
+            )
+            attrs.deep_stringify_keys! if attrs.respond_to?(:deep_stringify_keys)
+            klass.constantize.new(attrs)
+          }
+        end
+      end
+    end
+
+    # Provides a single method that any factory can call for attribute
+    # manipulation and is used to when override_factory_class is used
+    # to generate a factory definied in this gem but as another class
+    # (that inherits from a gem defined class) defined in their application.
+    def pre_initialize_attrs_for(factory, attrs)
+      case factory
+      when :content_version_result
+        pre_initialize_attrs_for_content_version_result(attrs)
+      when :structure
+        attrs[:data]
+      else
+        attrs
+      end
+    end
+
+    private
+
+    # These preinitialize helpers allow us to modify attributes before they are
+    # passed to the factory class for instantiation.
+
+    def pre_initialize_attrs_for_content_version_result(attrs)
+      # use some helpers to generate these structures based on the data provided
+      attrs.merge(
+        headings: FactoryBotHelpers::ContentVersion.headings(attrs).stringify_keys,
+        hierarchy_headings: FactoryBotHelpers::ContentVersion.hierarchy_headings(attrs).stringify_keys
+      )
+    end
+  end
+end

data/lib/ecfr/testing/helpers/response_helper.rb

@@ -0,0 +1,5 @@
+module ResponseHelper
+  def stubbed_response(body, status = 200)
+    OpenStruct.new(body: body, status: status)
+  end
+end

data/lib/ecfr/testing/strategies/ecfr_attribute_hash_strategy.rb

@@ -0,0 +1,37 @@
+#
+# A build strategy that take the initialized factory and returns the
+# attribute hash. The attribute hash or array of attribute hashes can then
+# be passed to the .build method on the Ecfr class being testing to receive
+# a response object.
+#
+class EcfrAttributeHashStrategy
+  def initialize
+    @strategy = FactoryBot.strategy_by_name(:build).new
+  end
+
+  delegate :association, to: :@strategy
+
+  def result(evaluation)
+    hsh = {}
+
+    hsh.merge!(evaluation.object.attributes) if evaluation.object.attributes
+
+    # handle direct json results like structure that aren't cast to attributes
+    if evaluation.object.respond_to?(:data) && evaluation.object.data
+      hsh[:data] = evaluation.object.data
+    end
+
+    # handle classes that return metadata
+    key = if evaluation.object.class.respond_to?(:metadata_accessor) &&
+        evaluation.object.class.metadata_accessor
+      evaluation.object.class.metadata_accessor
+    else
+      "metadata"
+    end
+    if evaluation.object.respond_to?(:metadata) && evaluation.object.metadata
+      hsh[key] = evaluation.object.metadata.attributes
+    end
+
+    hsh.deep_stringify_keys
+  end
+end

data/lib/ecfr/testing.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# we expect the client that includes the testing items to have
+# factory bot installed
+begin
+  Gem::Specification.find_by_name("factory_bot")
+  require "factory_bot"
+rescue Gem::LoadError
+end
+
+# custom factory bot strategies
+require_relative "testing/strategies/ecfr_attribute_hash_strategy"
+FactoryBot.register_strategy(:ecfr_attribute_hash, EcfrAttributeHashStrategy)
+
+# require all our test support files
+current_path = __dir__
+[
+  # generic testing helpers
+  "helpers",
+  # factory bot specific helper methods
+  "factory_bot_helpers",
+  # testing specific methods for each class
+  "extensions",
+  # factories
+  "factories"
+].each do |dir|
+  Dir.glob(File.join(current_path, "testing/#{dir}/**/*.rb")) { |f| require f }
+end

data/lib/ecfr/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ecfr
+  VERSION = "1.0.0"
+end

data/lib/ecfr/versioner_service/ancestors/metadata_node_info.rb

@@ -0,0 +1,22 @@
+module Ecfr
+  module VersionerService
+    class Ancestors
+      class MetadataNodeInfo
+        include AttributeMethodDefinition
+
+        attribute :hierarchy,
+          type: Ecfr::Common::Hierarchy,
+          desc: "the heirarchy this node resides in"
+
+        attribute :label,
+          desc: "the display value of the hierarchy"
+
+        # currently the API returns null for each key in the object
+        # so we need to do an attribute check
+        def present?
+          @attributes.compact.present?
+        end
+      end
+    end
+  end
+end

data/lib/ecfr/versioner_service/ancestors/node_summary.rb

@@ -0,0 +1,54 @@
+module Ecfr
+  module VersionerService
+    class Ancestors
+      #
+      # This class provides a summary of important data for the
+      # level in the hierarchy that it represents.
+      #
+      # Some levels of the hierarchy (generally subject groups)
+      # use generated identifiers because they are not designated
+      # potions of the CFR hierarchy and thus are not completely
+      # stable over time.
+      #
+      class NodeSummary
+        include AttributeMethodDefinition
+        extend Extensible
+
+        attribute :descendant_range,
+          desc: "the range of sections that are descendents of this level"
+        attribute :identifier,
+          desc: "the shortened identifier portion of the
+            CFR level"
+        attribute :label,
+          desc: "the full description of the CFR level"
+        attribute :label_level,
+          desc: "the full identifier portion of the CFR level"
+        attribute :label_description,
+          desc: "the descriptive portion of the CFR level"
+        attribute :type,
+          desc: "the type of CFR level - the value will be a
+            stringified version of the attribute keys in
+            {Ecfr::Common::Hierarchy}"
+
+        attribute :generated_id,
+          type: :boolean,
+          desc: "whether the identifier was generated"
+        attribute :reserved,
+          type: :boolean,
+          desc: "whether this level represents a portion of
+            the CFR that is Reserved"
+
+        attribute :volumes,
+          type: Array(:string),
+          desc: "the Volumes this level of the hierarchy was present
+            within in the print edition - only appears on Part levels and below"
+
+        # NOTE: this is autogenerated when the parent Ancestors
+        # class is instantiated and not part of the API response
+        attribute :hierarchy,
+          type: Ecfr::Common::Hierarchy,
+          desc: "the hierarchy for this node"
+      end
+    end
+  end
+end

data/lib/ecfr/versioner_service/ancestors.rb

@@ -0,0 +1,152 @@
+module Ecfr
+  module VersionerService
+    #
+    # Ancestors is used to retrieve data about the hierarchical
+    # structure of the CFR. The `.find` method expects to be
+    # provided a limited hierarchy, for example just a title
+    # and part - and will return the ancestors in the hierarchy
+    # that part is located within.
+    #
+    # As a performance optimization the full structure hierarchy
+    # to the provided hierarchy can also be returned as part of
+    # the response.
+    #
+    # Previous and next node attributes are used for navigating
+    # around the same level of hierarchy, for example from
+    # subpart to subpart, or from section to section even when
+    # the next section is in a sibling part (last section of
+    # one subpart -> first section of the next).
+    #
+    # Source xml filesize is an estimate of the size of the
+    # content that would be returned if the provided hierarchy
+    # was retrieved.
+    #
+    class Ancestors < Base
+      require_relative "ancestors/metadata_node_info"
+      require_relative "ancestors/node_summary"
+
+      attribute :ancestors,
+        type: Array(NodeSummary),
+        desc: "an array of ancestor hierarchy levels of the hierarchy found"
+
+      # previously this was structure_as_hierarchy
+      attribute :structure,
+        type: Ecfr::VersionerService::Structure,
+        value_key: "structure",
+        options: {format: "sideloaded", self: true},
+        desc: "the full hierarchy to the requested (limited) hierarchy"
+
+      metadata :previous_node,
+        type: MetadataNodeInfo,
+        desc: "the previous node in the hierarchy"
+      metadata :next_node,
+        type: MetadataNodeInfo,
+        desc: "the next node in the hierarchy"
+
+      metadata :source_xml_filesize,
+        type: :integer,
+        desc: "the approximate file size of the xml for the hierarchy found"
+
+      ANCESTORS_PATH = "v1/ancestry"
+
+      #
+      # Retrive ancestor date about a given (limited) hierarchy
+      # on a particular date
+      #
+      # @param [<Date, String>] date Date object, ISO date string, or 'current'
+      # @param [<Integer>] title_number the title number to search within
+      # @param [<Ecfr::Common::Hierarchy>] hierarchy_args a set
+      #   of hierarchy keys that identify the content for which
+      #   the full hierarchy should be found
+      # @param [<Hash>] options various options that can change
+      #   the behavior of the response
+      # @option options [<Boolean>] :structure used in combination
+      #   with the :descendent_depth option to include the structure
+      #   hierarchy of the requested content
+      # @option options [<Integer>] :descendant_depth the number of
+      #   levels of descendents to include in the structure
+      # @option options [<Integer>] :build_id internal use only - used to
+      #   retreive data about a specific build
+      # @option options [<Boolean>] :metadata whether to include metadata in
+      #   the response
+      # @option options [<Integer>] :max_items
+      # @option options [<Boolean>] :partial_ancestors_ok
+      # @option options [<Boolean>] :smart_folding
+      #
+      # @return [<Ancestors>]
+      #
+      def self.find(date:, title_number:, hierarchy_args: {}, options: {})
+        # ActiveSupport::HashWithIndifferentAccess does not have a ! method
+        hierarchy_args = hierarchy_args.symbolize_keys
+        options = options.symbolize_keys
+
+        options = hierarchy_args.merge(options).except(:title, :metadata)
+        options[:metadata] = true
+
+        perform(
+          :get,
+          ancestors_path(date, title_number),
+          params: options
+        )
+      end
+
+      def self.ancestors_path(date, title_number)
+        "#{ANCESTORS_PATH}/#{date}/title-#{title_number}"
+      end
+      private_class_method :ancestors_path
+
+      # these parameters add items to the base response but do not affect our
+      # ability to cache that base response
+      PARAMETERS_NOT_AFFECTING_BASE_RESPONSE = %w[metadata structure descendant_depth]
+
+      # if the request only includes optional parameters that don't affect the
+      # basic part of the response, then we can catch a base form of that
+      # response by removing those optional return items (this keeps the cache
+      # consistent across request by not including extra items).
+      def self.cache_base_response(response, path, params)
+        if only_safe_params?(params)
+          cache_key = cache_key(method, path, {})
+          RequestStore.fetch(cache_key) do
+            response.except(:metadata, :structure)
+          end
+        end
+      end
+      private_class_method :cache_base_response
+
+      def self.only_safe_params?(params)
+        # are all of the params keys included in the list?
+        params.keys.all? { |p| PARAMETERS_NOT_AFFECTING_BASE_RESPONSE.include?(p) }
+      end
+
+      # override enumerable setup because we don't have
+      # a single result root key
+      delegate(*SUPPORTED_ARRAY_ACCESSORS, to: :ancestors)
+      alias_method :all, :ancestors
+
+      def each
+        ancestors.each { |result| yield result }
+      end
+
+      #
+      # We overload the inherited initialize method in order to modify how we
+      # represent the response to the end user.
+      #   - we add a `hierarchy` key to each ancestor that includes it's parents
+      #   - we set a `structure` attribute if structure was returned in the
+      #     response
+      #
+      def initialize(attributes, options = {})
+        super(attributes, options)
+
+        ancestors.each_with_object({}) do |ancestor, hsh|
+          hsh[ancestor.type] = ancestor.identifier
+          ancestor.attributes["hierarchy"] = hsh.dup
+        end
+
+        # force casting of structure to a structure object
+        # such that it gets cached immediately - see
+        # Structure sideloaded format for details
+        structure if attributes["structure"]
+      end
+    end
+  end
+end

data/lib/ecfr/versioner_service/api_documentation.rb

@@ -0,0 +1,7 @@
+module Ecfr
+  module VersionerService
+    class ApiDocumentation < Base
+      include DefaultDocumentationSetup
+    end
+  end
+end

data/lib/ecfr/versioner_service/base.rb

@@ -0,0 +1,24 @@
+module Ecfr
+  module VersionerService
+    class Base < Ecfr::Base
+      require_relative "api_documentation"
+      require_relative "status"
+
+      # note: structure must be required before ancestors
+      require_relative "structure"
+      require_relative "ancestors"
+      require_relative "title"
+      require_relative "xml_content"
+
+      SERVICE_PATH = "/api/versioner"
+
+      def self.base_url
+        Ecfr.config.versioner_service_url || Ecfr.config.base_url
+      end
+
+      def self.service_name
+        "Versioner Service"
+      end
+    end
+  end
+end

data/lib/ecfr/versioner_service/status.rb

@@ -0,0 +1,7 @@
+module Ecfr
+  module VersionerService
+    class Status < Base
+      include DefaultStatusSetup
+    end
+  end
+end