ecfr 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e01bffb47225f9d31bd9a6d862f8b6e967586b4ac296ec25814e04dd254dacbe
+  data.tar.gz: 0b1f9d5b015063e167a27fc98036299ceb8b10d486a8a3d188044da99ad4c903
+SHA512:
+  metadata.gz: a294244d1e845f3ea9d3b6a128c557f85f9bc5b5c9eebea84ea507437b0101b27a9c87528c26e6dfb0ebb9d7c3888963569698b366b653399e2bf79eb37d579b
+  data.tar.gz: dc588b8531cb89e27a69a53c6a47deb8648c493d4fdc176e17bf51018ef88fd884876ebf69a875d44c30421be6735775555038cd4c6d19f3d7a8b3c6da399633

data/.circleci/config.yml

@@ -0,0 +1,11 @@
+version: 2.1
+
+orbs:
+  cj: criticaljuncture/cj-orb@0.1
+
+workflows:
+  build_and_notify:
+    jobs:
+      - cj/build_gem:
+          channel: ofr
+          context: orb-slack

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rspec_parallel

@@ -0,0 +1,4 @@
+--color
+--require spec_helper
+--format progress
+--format RspecJunitFormatter --out tmp/test-results/rspec/rspec<%= ENV["TEST_ENV_NUMBER"] %>.xml

data/.rubocop.yml

@@ -0,0 +1,28 @@
+AllCops:
+  Exclude:
+    - bin/*
+    - lib/yard/*
+  TargetRubyVersion: 3.1
+
+Layout/EmptyLineBetweenDefs:
+  AllowAdjacentOneLineDefs: true
+
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - spec/ecfr/extensible_spec.rb
+
+# We want Exclude directives from different
+# config files to get merged, not overwritten
+inherit_mode:
+  merge:
+    - Exclude
+
+require:
+  # Performance cops are bundled with Standard
+  - rubocop-performance
+  # Standard's config uses this custom cop,
+  # so it must be loaded
+  - standard/cop/block_single_line_braces
+
+inherit_gem:
+  standard: config/base.yml

data/.yardopts

@@ -0,0 +1,3 @@
+--load ./lib/yard/attribute_handler.rb
+--load ./lib/yard/metadata_handler.rb
+--exclude ./lib/yard

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## [Unreleased]
+
+## [1.0.0] - 2023-04-12
+
+- Initial release
+  - built based on usage from the ecfr-web project

data/Dockerfile

@@ -0,0 +1,6 @@
+FROM ruby:3.0
+
+ADD . /ecfr
+WORKDIR /ecfr
+
+RUN bundle

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in ecfr.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,138 @@
+PATH
+  remote: .
+  specs:
+    ecfr (1.0.0)
+      activemodel (~> 6.0)
+      activesupport (~> 6.0)
+      faraday (~> 2.0)
+      faraday-net_http_persistent (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (6.1.4)
+      activesupport (= 6.1.4)
+    activesupport (6.1.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.2)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.9)
+    connection_pool (2.4.0)
+    diff-lcs (1.4.4)
+    ethon (0.16.0)
+      ffi (>= 1.15.0)
+    factory_bot (6.2.1)
+      activesupport (>= 5.0.0)
+    faraday (2.5.2)
+      faraday-net_http (>= 2.0, < 3.1)
+      ruby2_keywords (>= 0.0.4)
+    faraday-net_http (3.0.0)
+    faraday-net_http_persistent (2.1.0)
+      faraday (~> 2.5)
+      net-http-persistent (~> 4.0)
+    faraday-typhoeus (1.0.0)
+      faraday (~> 2.0)
+      typhoeus (~> 1.4)
+    ffi (1.15.5)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
+    json (2.6.3)
+    language_server-protocol (3.17.0.3)
+    method_source (1.0.0)
+    mini_portile2 (2.8.1)
+    minitest (5.14.4)
+    net-http-persistent (4.0.2)
+      connection_pool (~> 2.2)
+    nokogiri (1.14.0)
+      mini_portile2 (~> 2.8.0)
+      racc (~> 1.4)
+    optparse (0.3.1)
+    parallel (1.22.1)
+    parallel_tests (4.2.0)
+      parallel
+    parser (3.2.2.0)
+      ast (~> 2.4.1)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    racc (1.6.2)
+    rack (3.0.4.1)
+    rainbow (3.1.1)
+    regexp_parser (2.7.0)
+    request_store (1.5.1)
+      rack (>= 1.4)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    rspec_junit_formatter (0.6.0)
+      rspec-core (>= 2, < 4, != 2.12.0)
+    rubocop (1.48.1)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.26.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.28.0)
+      parser (>= 3.2.1.0)
+    rubocop-performance (1.16.0)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    standard (1.26.0)
+      language_server-protocol (~> 3.17.0.2)
+      rubocop (~> 1.48.1)
+      rubocop-performance (~> 1.16.0)
+    turbo_tests (1.0.0)
+      optparse
+      parallel_tests
+      rspec
+    typhoeus (1.4.0)
+      ethon (>= 0.9.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.4.2)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
+    zeitwerk (2.4.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ecfr!
+  factory_bot
+  faraday-typhoeus
+  nokogiri
+  parallel_tests
+  pry
+  request_store
+  rspec (~> 3.0)
+  rspec_junit_formatter
+  rubocop
+  standard (~> 1.0)
+  turbo_tests
+  yard
+
+BUNDLED WITH
+   2.2.33

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Critical Juncture, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+# Ecfr
+
+Provides a Ruby API client for the eCFR.gov APIs.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ecfr'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install ecfr
+
+## Usage
+
+Configuration is supported via a configuration block. Only `user_agent` is required to be configured. See `lib/ecfr/configuration.rb` for options.
+
+```ruby
+Ecfr.configure do |config|
+  config.user_agent = "MyProject(me@myproject.com)"
+end
+```
+
+### XML parsing
+
+Some endpoints return XML (like the Structure) and will be automatically parsed using Nokogiri. However we do not bundle this as a gem dependency since it may not always be used. To use this you will need to add the Nokogiri gem to your code.
+
+### Response caching
+
+Response caching can be enabled via a configuration option. This is a performance feature that allows the calling code to not worry about performance when different parts of the application call the same endpoints at different times in the same request. Responses are cached my HTTP method, api endpoint and requested parameters. You will need to install the [request_store](https://github.com/steveklabnik/request_store) gem when enabling this option.
+
+If you are using request store outside of a Rails project or in a background process (eg Sidekiq) check the RequestStore documentation for how to use the required middleware.
+
+### Parallel client
+
+A basic parallel client is provided to support some use cases (we use it internally for our status page). This requires the use of [faraday-typhoeus](https://github.com/dleavitt/faraday-typhoeus) adapter. However we do not bundle this as a gem dependency since it may not always be used. To use the parallel client you will need to add the typhoeus faraday adapter gem to your code.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Simple endpoints that return an array of data under a single key
+
+For endpoints that return results like:
+
+```
+{
+  items: [
+    {name: "Item 1", active: true},
+    {name: "Item 2", active: true},
+    {name: "Item 3", active: false}
+  ]
+}
+```
+
+We support a `result_key` in the definition. In this example `result_key: :items`. This will cause each item in the items array to be instantiated as an instance of the class and delegate enumerable methods such as `.each`, `.first`, `.last`.
+
+So the following definition:
+```
+class Items < Base
+  result_key: :items
+
+  attribute :name
+  attribute :active, type: boolean
+
+  def self.all
+    new(
+      get(...)
+    )
+  end
+end
+```
+
+could be used `Items.all.each` which would iterate through an array of `Item` instances with `name` and `active` (and `active?`) methods.
+
+
+### More complex endpoints
+
+If however the endpoint returns data more like:
+
+```
+{
+  items: [
+    {name: "Item 1", active: true},
+    {name: "Item 2", active: true},
+    {name: "Item 3", active: false}
+  ],
+  warehouse: "Warehouse 32",
+  dock: "Dock A"
+}
+```
+
+then we support the following definition:
+
+```
+class Items < Base
+  class Item
+    include AttributeMethodDefinition
+
+    attribute :name
+    attribute :active, type: boolean
+  end
+
+  attribute: :items, type: Array(Item)
+  attribute: :dock, :warehouse
+
+  def self.all
+    new(
+      get(...)
+    )
+  end
+end
+```
+
+which can then be used like `result = Items.all; result.items.each...; result.warehouse`.
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/criticaljuncture/ecfr.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ecfr"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/ecfr.gemspec

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "lib/ecfr/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ecfr"
+  spec.version = Ecfr::VERSION
+  spec.authors = ["Peregrinator"]
+  spec.email = ["bob.burbach@gmail.com"]
+
+  spec.summary = "ecfr.federalregister.gov API client"
+  spec.description = "Ruby client for APIs provided by ecfr.federalregister.gov"
+  spec.homepage = "https://github.com/criticaljuncture/ecfr"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/criticaljuncture/ecfr"
+  spec.metadata["changelog_uri"] = "https://github.com/criticaljuncture/ecfr"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activemodel", "~> 6.0"
+  spec.add_dependency "activesupport", "~> 6.0"
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-net_http_persistent", "~> 2.0"
+
+  spec.add_development_dependency "factory_bot"
+  spec.add_development_dependency "parallel_tests"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rspec_junit_formatter"
+  spec.add_development_dependency "rubocop"
+  spec.add_development_dependency "standard", "~> 1.0"
+  spec.add_development_dependency "turbo_tests"
+  spec.add_development_dependency "yard"
+
+  # A parallel client is made available when the faraday-typhoeus adapter
+  # is installed. However we don't bundle this as a dependency. If you want
+  # to use the parallel client make sure to require it in your code.
+  spec.add_development_dependency "faraday-typhoeus"
+
+  # Some features of the gem support parsing XML responses
+  # with Nokogiri.
+  # However we don't bundle this as a dependency. If you want
+  # to use such features make sure to require it in your code.
+  spec.add_development_dependency "nokogiri"
+
+  # Caching of responses can be enabled and require the
+  # request store gem. However we don't bundle this as a
+  # dependency - it will need to be installed in your code.
+  spec.add_development_dependency "request_store"
+
+  spec.post_install_message = '
+    Some features of the eCFR gem support parsing XML responses, response
+    caching, and parallel requests.
+
+    To use these features you will beed to install the appropriate gems
+    (nokogiri, request_store, and faraday-typhoeus respectively) in your
+    application. In order to minimize depedencies and code that is loaded these
+    are not a default dependencies of the eCFR gem.
+
+    See the README for details of these features.
+  '
+end

data/lib/ecfr/admin_service/agency/hierarchy.rb

@@ -0,0 +1,27 @@
+module Ecfr
+  module AdminService
+    class Agency
+      class Hierarchy
+        include AttributeMethodDefinition
+        extend Extensible
+
+        attribute :title,
+          desc: "Title number"
+        attribute :subtitle,
+          desc: "Subtitle identifier"
+        attribute :chapter,
+          desc: "Chapter identifier"
+        attribute :subchapter,
+          desc: "Subchapter identifier"
+        attribute :part,
+          desc: "Part identifier"
+
+        def to_hash
+          @attributes.each_with_object({}) { |attr, hsh|
+            hsh[attr[0]] = attr[1]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ecfr/admin_service/agency.rb

@@ -0,0 +1,34 @@
+module Ecfr
+  module AdminService
+    class Agency < Base
+      require_relative "agency/hierarchy"
+
+      result_key :agencies
+
+      attribute :name, desc: "name of agency"
+
+      attribute :cfr_references, type: Array(Ecfr::Common::Hierarchy),
+        desc: "portions of the CFR this agency is responsible for,
+          expected keys are only :title, :subtitle, :chapter,
+          :subchapter, and :part"
+
+      attribute :children, type: Array(Agency),
+        desc: "sub-agencies of the current agency"
+
+      AGENCIES_PATH = "v1/agencies.json"
+
+      #
+      # Retrieve the list of all agencies, their subagencies
+      # and the portions of the CFR they are responsible for
+      #
+      # @return [[<Agency>]] an array of agency records
+      #
+      def self.all
+        perform(
+          :get,
+          AGENCIES_PATH
+        )
+      end
+    end
+  end
+end

data/lib/ecfr/admin_service/api_documentation.rb

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

data/lib/ecfr/admin_service/base.rb

@@ -0,0 +1,26 @@
+module Ecfr
+  module AdminService
+    class Base < Ecfr::Base
+      require_relative "api_documentation"
+      require_relative "status"
+
+      require_relative "agency"
+      require_relative "build"
+      require_relative "ecfr_correction"
+      require_relative "editorial_note"
+      require_relative "ibr_cfr_range"
+      require_relative "issue"
+      require_relative "site_notification"
+
+      SERVICE_PATH = "/admin/api/admin"
+
+      def self.base_url
+        Ecfr.config.admin_service_url || Ecfr.config.base_url
+      end
+
+      def self.service_name
+        "Admin Service"
+      end
+    end
+  end
+end

data/lib/ecfr/admin_service/build.rb

@@ -0,0 +1,38 @@
+module Ecfr
+  module AdminService
+    class Build < Base
+      result_key :builds
+
+      attribute :id,
+        desc: "build id"
+      attribute :status,
+        desc: "build status - either *Success* or *Failure*"
+
+      attribute :expired,
+        type: :boolean
+      attribute :previewable,
+        type: :boolean
+
+      BUILDS_PATH = "v1/builds"
+
+      #
+      # Retrieve a Build by id
+      #
+      # @param [<String>] build_id - id of the desired build
+      #
+      # @return [<Build>] data for a single build
+      #
+      def self.find(build_id)
+        perform(
+          :get,
+          build_path(build_id)
+        )
+      end
+
+      def self.build_path(build_id)
+        "#{BUILDS_PATH}/#{build_id}"
+      end
+      private_class_method :build_path
+    end
+  end
+end

data/lib/ecfr/admin_service/ecfr_correction/cfr_reference.rb

@@ -0,0 +1,17 @@
+module Ecfr
+  module AdminService
+    class EcfrCorrection
+      class CfrReference
+        include AttributeMethodDefinition
+        extend Extensible
+
+        attribute :cfr_reference,
+          desc: "CFR reference in the form '40 CFR 100'"
+
+        attribute :hierarchy,
+          type: Ecfr::Common::Hierarchy,
+          desc: "hash of CFR hierarchy attributes"
+      end
+    end
+  end
+end