rvgp 0.3.2

data/lib/rvgp/reconcilers/shorthand/investment.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module RVGP
+  module Reconcilers
+    # This module contains the built-in Shorthand classes that ship with RVGP. For more details on this
+    # feature, see the 'Shorthand' section of the {RVGP::Reconcilers} module.
+    module Shorthand
+      # This reconciler module will automatically allocate the proceeds (or losses) from a stock sale.
+      # This module will allocate capital gains or losses, given a symbol, amount, and price.
+      #
+      # The module parameters we support are:
+      # - **symbol** [String] -  A commodity or currency code, that represents the purchased asset
+      # - **amount** [Integer] - The amount of :symbol that was purchased, or if negative, sold.
+      # - **price** [Commodity] - A unit price, for the symbol. This field should be delimited if :total is omitted.
+      # - **total** [Commodity] - A lot price, the symbol. This represents the net  purchase price, which, would be
+      #   divided by the amount, in order to arrive at a unit price. This field should be delimited if :price is
+      #   omitted.
+      # - **capital_gains** [Commodity] - The amount of the total, to allocate to a capital gains account. Presumably
+      #   for tax reporting.
+      # - **gains_account** [String] - The account name to allocate capital gains to.
+      #
+      # # Example
+      # Here's how this module might be used in your reconciler:
+      # ```
+      # ...
+      # - match: /Acme Stonk Exchange/
+      #   to_shorthand: Investment
+      #   shorthand_params:
+      #     symbol: VOO
+      #     price: "$ 400.00"
+      #     amount: "-1000"
+      #     capital_gains: "$ -100000.00"
+      #     gains_account: Personal:Income:AcmeExchange:VOO
+      # ...
+      # ```
+      # And here's how that will reconcile, in your build:
+      # ```
+      # ...
+      # 2023-06-01 Acme Stonk Exchange ACH CREDIT 123456 Yukihiro Matsumoto
+      #   Personal:Assets                   -1000 VOO @@ $ 400000.00
+      #   Personal:Income:AcmeExchange:VOO    $ 100000.00
+      #   Personal:Assets:AcmeChecking
+      #   ...
+      # ```
+      #
+      class Investment
+        # @!visibility private
+        attr_reader :tag, :symbol, :price, :amount, :total, :capital_gains,
+                    :remainder_amount, :remainder_account, :targets, :is_sell,
+                    :to, :gains_account
+
+        def initialize(rule)
+          @tag = rule[:tag]
+          @targets = rule[:targets]
+          @to = rule[:to] || 'Personal:Assets'
+
+          if rule.key? :shorthand_params
+            @symbol = rule[:shorthand_params][:symbol]
+            @amount = rule[:shorthand_params][:amount]
+            @gains_account = rule[:shorthand_params][:gains_account]
+
+            %w[price total capital_gains].each do |key|
+              if rule[:shorthand_params].key? key.to_sym
+                instance_variable_set "@#{key}".to_sym, rule[:shorthand_params][key.to_sym].to_commodity
+              end
+            end
+          end
+
+          unless [symbol, amount].all?
+            raise StandardError, format('Investment at line:%s missing fields', rule[:line].inspect)
+          end
+
+          @is_sell = (amount.to_f <= 0)
+
+          # I mostly just think this doesn't make any sense... I guess if we took a
+          # loss...
+          raise StandardError, format('Unimplemented %s', rule.inspect) if capital_gains && !is_sell
+
+          if (gains_account.nil? || capital_gains.nil?) && is_sell
+            raise StandardError, format('Investment at line:%s missing gains_account', rule.inspect)
+          end
+
+          unless total || price
+            raise StandardError, format('Investment at line:%s missing an price or total', rule[:line].inspect)
+          end
+
+          if total && price
+            raise StandardError, format('Investment at line:%s specified both price and total', rule[:line].inspect)
+          end
+        end
+
+        # @!visibility private
+        def to_tx(from_posting)
+          income_targets = []
+
+          # NOTE: I pulled most of this from: https://hledger.org/investments.html
+          if is_sell && capital_gains
+            # NOTE: I'm not positive about this .abs....
+            cost_basis = (total || (price * amount.to_f.abs)) - capital_gains
+
+            income_targets << { to: to,
+                                complex_commodity: RVGP::Journal::ComplexCommodity.new(
+                                  left: [amount, symbol].join(' ').to_commodity,
+                                  operation: :per_lot,
+                                  right: cost_basis
+                                ) }
+
+            income_targets << { to: gains_account, commodity: capital_gains.dup.invert! } if capital_gains
+          else
+            income_targets << { to: to,
+                                complex_commodity: RVGP::Journal::ComplexCommodity.new(
+                                  left: [amount, symbol].join(' ').to_commodity,
+                                  operation: (price ? :per_unit : :per_lot),
+                                  right: price || total
+                                ) }
+          end
+
+          if targets
+            income_targets += targets.map do |t|
+              ret = { to: t[:to] }
+              if t.key? :amount
+                # TODO: I think there's a bug here, in that amounts with commodities, won't parse...
+                ret[:commodity] = RVGP::Journal::Commodity.from_symbol_and_amount t[:currency] || '$', t[:amount].to_s
+              end
+
+              if t.key? :complex_commodity
+                ret[:complex_commodity] = RVGP::Journal::ComplexCommodity.from_s t[:complex_commodity]
+              end
+
+              ret
+            end
+          end
+
+          RVGP::Base::Reconciler::Posting.new from_posting.line_number,
+                                              date: from_posting.date,
+                                              description: from_posting.description,
+                                              from: from_posting.from,
+                                              tags: from_posting.tags,
+                                              targets: income_targets
+        end
+      end
+    end
+  end
+end

data/lib/rvgp/reconcilers/shorthand/mortgage.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+gem 'finance'
+require 'finance'
+require_relative './finance_gem_hacks'
+
+module RVGP
+  module Reconcilers
+    module Shorthand
+      # This reconciler module will automatically allocate the the escrow, principal, and interest components of a
+      # mortage debit, into constituent accounts. The amounts of each, are automatically calculated, based on the loan
+      # terms, and taking the residual leftover, into a escrow account, presumably for taxes and insurance to be paid by
+      # the mortgage provider.
+      #
+      # Its important to note, that a single reconciler rule will match every mortgage payment encountered. And, that
+      # each of these payments will generate four transactions in the output file:
+      # - The initial payment, which, will be transferred to an :intermediary_account
+      # - A principal payment, which, will be debited from the :intermediary account, to the :payee_principal
+      # - An interest payment, which, will be debited from the :intermediary account, to the :payee_interest
+      # - An escrow payment, which, will be debited from the :intermediary account, to the :escrow_account
+      # You can see details of this expansion under the example section below.
+      #
+      # With regards to the :escrow_account, It's likely that you'll want to either (choose one):
+      # - Manually transcribe debits from the escrow account, to escrow payees, in your project's
+      #   ./journal/property-name-escrow.journal, based on when your mortgage provider alerts you to these payments.
+      # - Download a csv from your mortgage provider, of your escrow account (if they offer one), and define a
+      #   reconciler to allocate escrow payments.
+      #
+      # The module parameters we support are:
+      # - **label** [String] - This is a prefix, used in the description of Principal, Interest, and Escrow transactions
+      # - **principal** [Commodity] - The mortgage principal
+      # - **rate** [Float] - The mortgage rate
+      # - **payee_principal** [String] - The account to ascribe principal payments to
+      # - **payee_interest** [String] - The account to ascribe interest payments to
+      # - **escrow_account** [String] - Te account to ascribe escrow payments to
+      # - **intermediary_account** [String] - The account to ascribe intermediary payments to, from the source account,
+      #   before being assigned to principal, interest, and escrow break-outs.
+      # - **start_at_installment_number** [Integer] - The installment number, of the first matching transaction,
+      #   encountered by this module. Year one of a mortgage would start at zero. Subsequent annual reconcilers would
+      #   be expected to define an installment number from which calculations can automatically pick-up the work
+      #   from years prior.
+      # - **additional_payments** [Array<Hash>] - Any additional payments, to apply to the principal, can be listed
+      #   here. This field is expected to be an array of hashes, which, are composed of the following fields:
+      #   - **before_installment** [Integer] - The payment number, before which, this :amount should apply
+      #   - **amount** [Float] - A float that will be deducted from the principal. No commodity is necessary to
+      #     delineate, as we assume the same commodity as the :principle.
+      # - **override_payments** [Array<Hash>] - I can't explain why this is necessary. But, it seems that the interest
+      #   calculations used by some mortgage providers ... aren't accurate. This happened to me, at least. The
+      #   calculation being used was off by a penny, on a single installment. And, I didn't care enough to call the
+      #   institution and figure out why. So, I added this feature, to allow an override of the automatic calculation,
+      #   with the amount provided. This field is expected to be an array of hashes, which are composed of the following
+      #   fields:
+      #   - **at_installment** [Integer] - The payment number to assert the :interest value.
+      #   - **interest** [Float] - The amount of the interest calculation. No commodity is neccessary to delineate, as
+      #     we assume the same commodity as the :principle.
+      #
+      # # Example
+      # Here's how this module might be used in your reconciler:
+      # ```
+      # ...
+      # - match: /AcmeFinance Servicing/
+      #   to_shorthand: Mortgage
+      #   shorthand_params:
+      #     label: 1-8-1 Yurakucho Dori Mortgage
+      #     intermediary_account: Personal:Expenses:Banking:MortgagePayment:181Yurakucho
+      #     payee_principal: Personal:Liabilities:Mortgage:181Yurakucho
+      #     payee_interest: Personal:Expenses:Banking:Interest:181Yurakucho
+      #     escrow_account: Personal:Assets:AcmeFinance:181YurakuchoEscrow
+      #     principal: 260000.00
+      #     rate: 0.0499
+      #     start_at_installment_number: 62
+      # ...
+      # ```
+      # And here's how that will reconcile one of your payments, in your build:
+      # ```
+      # ...
+      # 2023-01-03 AcmeFinance Servicing MTG PYMT 012345 Yukihiro Matsumoto
+      #   Personal:Expenses:Banking:MortgagePayment:181Yurakucho    $ 3093.67
+      #   Personal:Assets:AcmeBank:Checking
+      #
+      # 2023-01-03 1-8-1 Yurakucho Dori Mortgage (#61) Principal
+      #   Personal:Liabilities:Mortgage:181Yurakucho    $ 403.14
+      #   Personal:Expenses:Banking:MortgagePayment:181Yurakucho
+      #
+      # 2023-01-03 1-8-1 Yurakucho Dori Mortgage (#61) Interest
+      #   Personal:Expenses:Banking:Interest:181Yurakucho    $ 991.01
+      #   Personal:Expenses:Banking:MortgagePayment:181Yurakucho
+      #
+      # 2023-01-03 1-8-1 Yurakucho Dori Mortgage (#61) Escrow
+      #   Personal:Assets:AcmeFinance:181YurakuchoEscrow    $ 1699.52
+      #   Personal:Expenses:Banking:MortgagePayment:181Yurakucho
+      # ...
+      # ```
+      # Note that you'll have an automatically calculated reconcilation for each payment you
+      # make, during the year. A single reconciler rule, will take care of reconciling every
+      # payment, automatically.
+      class Mortgage
+        # @!visibility private
+        attr_accessor :principal, :rate, :start_at_installment_number,
+                      :additional_payments, :amortization, :payee_principal, :payee_interest,
+                      :intermediary_account, :currency, :label, :escrow_account, :override_payments
+
+        # @!visibility private
+        def initialize(rule)
+          @label = rule[:shorthand_params][:label]
+          @currency = rule[:currency] || '$'
+          @principal = rule[:shorthand_params][:principal].to_commodity
+          @rate = rule[:shorthand_params][:rate]
+          @payee_principal = rule[:shorthand_params][:payee_principal]
+          @payee_interest = rule[:shorthand_params][:payee_interest]
+          @intermediary_account = rule[:shorthand_params][:intermediary_account]
+          @escrow_account = rule[:shorthand_params][:escrow_account]
+          @start_at_installment_number = rule[:shorthand_params][:start_at_installment_number]
+          @additional_payments = rule[:shorthand_params][:additional_payments]
+          @override_payments = {}
+          if rule[:shorthand_params].key? :override_payments
+            rule[:shorthand_params][:override_payments].each do |override|
+              unless %i[at_installment interest].all? { |k| override.key? k }
+                raise StandardError, format('Invalid Payment Override : %s', override)
+              end
+
+              @override_payments[ override[:at_installment] ] = {
+                interest: RVGP::Journal::Commodity.from_symbol_and_amount(currency, override[:interest])
+              }
+            end
+          end
+
+          unless [principal, rate, payee_principal, payee_interest, intermediary_account, escrow_account, label].all?
+            raise StandardError, format('Mortgage at line:%d missing fields', rule[:line])
+          end
+
+          fr = Finance::Rate.new rate, :apr, duration: 360
+          @amortization = principal.to_f.amortize(fr) do |period, amortization|
+            additional_payments&.each do |ap|
+              if period == ap[:before_installment]
+                amortization.balance = amortization.balance - DecNum.new(ap[:amount].to_s)
+              end
+            end
+          end
+
+          @installment_i = start_at_installment_number ? (start_at_installment_number - 1) : 0
+        end
+
+        # @!visibility private
+        def to_tx(from_posting)
+          payment = RVGP::Journal::Commodity.from_symbol_and_amount(currency, amortization.payments[@installment_i]).abs
+          interest = RVGP::Journal::Commodity.from_symbol_and_amount(currency, amortization.interest[@installment_i])
+
+          interest = @override_payments[@installment_i][:interest] if @override_payments.key? @installment_i
+
+          principal = payment - interest
+          escrow = from_posting.commodity.abs - payment
+          total = principal + interest + escrow
+
+          @installment_i += 1
+
+          intermediary_opts = { date: from_posting.date, from: intermediary_account, tags: from_posting.tags }
+
+          [RVGP::Base::Reconciler::Posting.new(from_posting.line_number,
+                                               date: from_posting.date,
+                                               description: from_posting.description,
+                                               from: from_posting.from,
+                                               tags: from_posting.tags,
+                                               targets: [to: intermediary_account, commodity: total]),
+           # Principal:
+           RVGP::Base::Reconciler::Posting.new(
+             from_posting.line_number,
+             intermediary_opts.merge({ description: format('%<label>s (#%<num>d) Principal',
+                                                           label: label,
+                                                           num: @installment_i - 1),
+                                       targets: [{ to: payee_principal, commodity: principal }] })
+           ),
+
+           # Interest:
+           RVGP::Base::Reconciler::Posting.new(
+             from_posting.line_number,
+             intermediary_opts.merge({ description: format('%<label>s (#%<num>d) Interest',
+                                                           label: label,
+                                                           num: @installment_i - 1),
+                                       targets: [{ to: payee_interest, commodity: interest }] })
+           ),
+
+           # Escrow:
+           RVGP::Base::Reconciler::Posting.new(
+             from_posting.line_number,
+             intermediary_opts.merge({ description: format('%<label>s (#%<num>d) Escrow',
+                                                           label: label,
+                                                           num: @installment_i - 1),
+                                       targets: [{ to: escrow_account, commodity: escrow }] })
+           )]
+        end
+      end
+    end
+  end
+end

data/lib/rvgp/utilities/grid_query.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'csv'
+
+module RVGP
+  module Utilities
+    # This class provides a number of utility functions to query, and merge, grids
+    # that have been built. The primary purpose of these tools, is to decrease
+    # the overhead that would otherwise exist, if we were to operate directly on
+    # the pta output, every time we referenced this data. As well as to maintain
+    # auditability for this data, in the project build.
+    # @attr_reader [Array<String>] headers The first row of a grid, without the keystone included
+    # @attr_reader [Hash<String,Hash<String,Object>>] data A hash whose key is the series name, whose value is a hash of
+    #                                                      headername to value pairs
+    # @attr_reader [String] keystone The cell in the upper-left of the grid. Often this cell is used as a superordinate
+    #                                label for the series below it.
+    class GridQuery
+      # NOTE: I'm not exactly sure what this class wants to be just yet...
+      # Let's see if we end up using it for graphing... It might just be a 'Spreadsheet'
+      # and we may want/need to move the summary columns into here
+      attr_reader :headers, :data, :keystone
+
+      # Setup a GridQuery
+      # @param [Array<String>] from_files An array of paths, to grid files
+      # @param [Hash] options Additional options
+      # @option options [String] keystone see {RVGP::Utilities::GridQuery#keystone}
+      # @option options [Proc] store_cell  This proc is provided one parameter, a data cell. The return value of this
+      #                                    proc is then stored in :data, in lieu of the parameter.
+      # @option options [Proc] select_columns This proc is provided two parameters, a header (String), and the cells
+      #                                       underneath it in the grid (Array<Object>). If this proc returns true,
+      #                                       that column is stored in :data. If this proc returns false, that column
+      #                                       is not retained in this query.
+      # @option options [Proc] select_rows This proc is provided two parameters, a series_name (String), and the cells
+      #                                    to the right of it in the grid (Array<Object>). If this proc returns true,
+      #                                    that column is stored in :data. If this proc returns false, that column
+      #                                    is not retained in this query.
+      def initialize(from_files, options = {})
+        @headers = []
+        @data = {}
+
+        from_files.each do |file|
+          csv = CSV.open file, 'r', headers: true
+          rows = csv.read
+          headers = csv.headers
+
+          # We assume the first column of the row, is the series name
+          @keystone = headers.shift
+
+          if options[:select_columns]
+            selected_headers = headers.select do |header|
+              options[:select_columns].call(header, rows.map { |row| row[header] })
+            end
+          end
+          selected_headers ||= headers
+
+          add_columns selected_headers
+
+          rows.each do |row|
+            series_data = row.to_h
+            series_name = series_data.delete @keystone
+            if options.key? :store_cell
+              series_data.each do |col, cell|
+                next unless !options.key?(:select_columns) || selected_headers.include?(col)
+
+                series_data[col] = options[:store_cell].call cell
+              end
+            end
+
+            if !options.key?(:select_rows) || options[:select_rows].call(series_name, series_data)
+              add_data series_name, series_data
+            end
+          end
+        end
+
+        # This needs to be assigned after we've processed the csv's
+        @keystone = options[:keystone] if options.key? :keystone
+      end
+
+      # Returns the results of a query.
+      # @param [Hash] opts Additional options
+      # @option opts [Proc] sort_cols_by Columns are sorted by the value returned by this proc. This proc is provided
+      #                                  the grid :headers, and this proc is handled according to the rules of
+      #                                  Enumerable#sort_by.
+      # @option opts [Proc] sort_rows_by Rows are sorted by the value returned by this proc. This proc is provided
+      #                                  each row in this grid, with the series_name of the row at position zero.
+      #                                  This proc is handled according to the rules of Enumerable#sort_by.
+      # @option opts [Integer] truncate_columns Restrict the total number of columns to a maximum this number
+      # @option opts [Integer] truncate_rows Restrict the total number of rows to a maximum this number
+      # @option opts [String] truncate_remainder_row If the columns are truncated, the 'chopped' columns are summed into
+      #                                              'the last column'. The value of this option, is used as  the label
+      #                                              for that column. Candidly... this feature makes a lot of
+      #                                              assumptions, and probably needs a bit more refinement.
+      # @option opts [TrueClass,FalseClass] switch_rows_columns Rotates the grid, so that series labels and headers are
+      #                                     swapped. All data is preserved under/adjacent to the same series label and
+      #                                     header, in the returned grid. Google offers this option in its GUI, but
+      #                                     doesn't seem to support it via the API. So, we can just do that ourselves
+      #                                     here.
+      # @return [Array<Array<Object>>] A grid of cells, composed of the provided grids, and transformed by the given
+      #                                parameters.
+      def to_grid(opts = {})
+        # First we'll collect the header row, possibly sorted :
+        if opts[:sort_cols_by]
+          # We collect the data under the column, and feed that into sort_cols_by
+          grid_columns = headers.map do |col|
+            [col] + data.map { |_, values| values[col] }
+          end.sort_by(&opts[:sort_cols_by]).map(&:first)
+        end
+        grid_columns ||= headers
+
+        # Then we collect the non-header rows:
+        grid = data.map { |series, values| [series] + grid_columns.map { |col| values[col] } }
+
+        # Sort those rows, if necessesary:
+        grid.sort_by!(&opts[:sort_rows_by]) if opts[:sort_rows_by]
+
+        # Affix the header row to the top of the grid. Now it's assembled.
+        grid.unshift [keystone] + grid_columns
+
+        # Do we Truncate Rows?
+        if opts[:truncate_rows] && grid.length > opts[:truncate_rows]
+          # We can only have about 26 columns on Google. And, since we're (sometimes)
+          # transposing rows to columns, we have to truncate the rows.
+
+          # NOTE: The 1 is for the truncate_remainder_row, the 'overflow' column
+          chop_length = grid.length - opts[:truncate_rows]
+
+          if chop_length.positive?
+            chopped_rows = grid.pop chop_length
+            truncate_row = chopped_rows.inject([]) do |sum, row|
+              # Starting at the second cell (the first is the series name) merge
+              # the contents of the current row, into the collection cell.
+              row[1...].each_with_index.map do |cell, i|
+                # This rigamarole is mostly to help prevent type issues...
+                if cell
+                  sum[i] ? sum[i] + cell : cell
+                else
+                  sum[i]
+                end
+              end
+            end
+
+            grid << ([(opts[:truncate_remainder_row]) || 'Other'] + truncate_row)
+          end
+        end
+
+        # Do we Truncate Columns?
+        if opts[:truncate_columns] && grid[0].length > opts[:truncate_columns]
+          # Go through each row, pop off the excess cells, and sum them onto the end
+          grid.each_with_index do |row, i|
+            # The plus one is to make room for the 'Other' column
+            chop_length = row.length - opts[:truncate_columns] + 1
+
+            chopped_cols = row.pop chop_length
+            truncate_cell = if i.zero?
+                              opts[:truncate_remainder_row] || 'Other'
+                            else
+                              chopped_cols.all?(&:nil?) ? nil : chopped_cols.compact.sum
+                            end
+
+            row << truncate_cell
+          end
+        end
+
+        # Google offers this option in its GUI, but doesn't seem to support it via
+        # the API. So, we can just do that ourselves:
+        grid = 0.upto(grid[0].length - 1).map { |i| grid.map { |row| row[i] } } if opts[:switch_rows_columns]
+
+        grid
+      end
+
+      private
+
+      def add_columns(headers)
+        @headers += headers.reject { |header| @headers.include? header }
+      end
+
+      # NOTE: that we're assuming value here, is always a commodity. Not sure about
+      # that over time.
+      def add_data(series_name, colname_to_value)
+        @data[series_name] ||= {}
+
+        colname_to_value.each do |colname, value|
+          raise StandardError, 'Unimplemented. How to merge?' if @data[series_name].key? colname
+
+          @data[series_name][colname] = value
+        end
+      end
+    end
+  end
+end

data/lib/rvgp/utilities/yaml.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'psych'
+require 'pathname'
+
+Psych.add_builtin_type('proc') { |_, val| RVGP::Utilities::Yaml::PsychProc.new val }
+Psych.add_builtin_type('include') { |_, val| RVGP::Utilities::Yaml::PsychInclude.new val }
+
+module RVGP
+  module Utilities
+    # This class wraps the Psych library, and adds functionality we need, to parse
+    # yaml files.
+    # We mostly added this class because the Psych.add_builtin_type wasn't able to
+    # contain state outside it's return values. (which we need, in order to
+    # track include dependencies)
+    class Yaml
+      # This class is needed, in order to capture the dependencies needed to
+      # properly preserve uptodate status in rake builds
+      class PsychInclude
+        attr_reader :path
+
+        # Declare a proc, given the provided proc_as_string code
+        # @param [String] path A relative or absolute path, to include, in the place of this line
+        def initialize(path)
+          @path = path
+        end
+
+        # The contents of this include target.
+        # @param [Array<String>] include_paths A relative or absolute path, to include, in case our path is relative
+        #                                      and we need to load it from a relative location. These paths are
+        #                                      scanned for the include, in the relative order of their place in the
+        #                                      array.
+        # @return [Hash] The contents of the target of this include. Keys are symbolized, and permitted_classes include
+        #                Date, and Symbol
+        def contents(include_paths)
+          content_path = path if Pathname.new(path).absolute?
+          content_path ||= include_paths.map { |p| [p.chomp('/'), path].join('/') }.find do |p|
+            File.readable? p
+          end
+
+          unless content_path
+            raise StandardError, format('Unable to find %<path>s in any of the provided paths: %<paths>s',
+                                        path: path.inspect, paths: include_paths.inspect)
+          end
+
+          Psych.safe_load_file content_path, symbolize_names: true, permitted_classes: [Date, Symbol]
+        end
+      end
+
+      # This class wraps proc types, in the yaml, and offers us the ability to execute
+      # the code in these blocks.
+      class PsychProc
+        # Declare a proc, given the provided proc_as_string code
+        # @param [String] proc_as_string Ruby code, that this block will call.
+        def initialize(proc_as_string)
+          @block = eval(format('proc { %s }', proc_as_string)) # rubocop:disable Security/Eval
+        end
+
+        # Execute the block, using the provided params as locals
+        # NOTE: We expect symbol to value here
+        # @param params [Hash<Symbol, Object>] local values, available in the proc context. Note that keys
+        #                                      are expected to be symbols.
+        # @return [Object] Whatever the proc returns
+        def call(params = {})
+          # params, here, act as instance variables, since we don't support named
+          # params in the provided string, the way you typically would.
+          @params = params
+          @block.call
+        end
+
+        # @!visibility private
+        def respond_to_missing?(name, _include_private = false)
+          @params&.key?(name.to_sym)
+        end
+
+        # @!visibility private
+        def method_missing(name)
+          respond_to_missing?(name) ? @params[name] : super(name)
+        end
+      end
+
+      attr_reader :path, :include_paths, :dependencies
+
+      # @param [String] path The full path to the yaml file you wish to parse
+      # @param [Array<String>] include_paths An array of directories, to search, when locating the target of
+      #                                      a "!!include" line
+      def initialize(path, include_paths = nil)
+        @path = path
+        @dependencies = []
+        @include_paths = Array(include_paths || File.expand_path(File.dirname(path)))
+
+        vanilla_yaml = Psych.safe_load_file(path, symbolize_names: true, permitted_classes: [Date, Symbol])
+        @yaml = replace_each_in_yaml(vanilla_yaml, PsychInclude) do |psych_inc|
+          @dependencies << psych_inc.path
+          psych_inc.contents @include_paths
+        end
+      end
+
+      # Return the specified attribute, in this yaml file
+      # @param [String] attr The attribute you're looking for
+      # @return [Object] The value of the the provided attribute
+      def [](attr)
+        @yaml&.[](attr)
+      end
+
+      # Returns true or false, depending on whether the attribute you're looking for, exists in this
+      # yaml file.
+      # @param [String] attr The attribute you're looking for
+      # @return [TrueClass,FalseClass] Whether the key is defined in this file
+      def key?(attr)
+        @yaml&.key? attr
+      end
+
+      alias has_key? key?
+
+      private
+
+      # This is kind of a goofy function, but, it works
+      def replace_each_in_yaml(obj, of_class, &blk)
+        case obj
+        when Hash
+          obj.transform_values { |v| replace_each_in_yaml v, of_class, &blk }
+        when Array
+          obj.collect { |v| replace_each_in_yaml(v, of_class, &blk) }
+        else
+          obj.is_a?(of_class) ? blk.call(obj) : obj
+        end
+      end
+    end
+  end
+end