rvgp 0.3.2

data/lib/rvgp/fakers/fake_feed.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require_relative 'faker_helpers'
+require_relative '../journal/currency'
+
+module RVGP
+  module Fakers
+    # Contains faker implementations that produce CSV files, for use as a data feed
+    class FakeFeed < Faker::Base
+      class << self
+        include FakerHelpers
+
+        # This error is thrown when there is a mismatch between two parameter arrays, passed to
+        # a function, whose lengths are required to match.
+        class ParameterLengthError < StandardError
+          # @!visibility private
+          MSG_FORMAT = 'Expected %<expected>s elements in %<parameter>s, but found %<found>s'
+
+          def initialize(parameter, expected, found)
+            super format(MSG_FORMAT, expected: expected, parameter: parameter, found: found)
+          end
+        end
+
+        # @!visibility private
+        DEFAULT_LENGTH_IN_DAYS = 365 / 4
+        # @!visibility private
+        DEFAULT_POST_COUNT = 300
+        # @!visibility private
+        FEED_COLUMNS = ['Date', 'Type', 'Description', 'Withdrawal (-)', 'Deposit (+)', 'RunningBalance'].freeze
+        # @!visibility private
+        DEFAULT_CURRENCY = RVGP::Journal::Currency.from_code_or_symbol('$')
+
+        # Generates a basic csv feed string, that resembles thos
+
+        # Generates a basic csv feed string, that resembles those offered by banking institutions
+        #
+        # @param from [Date] The date to start generated feed from
+        # @param to [Date] The date to end generated feed
+        # @param income_descriptions [Array] Strings containing the pool of available income descriptions, for use in
+        #                                    random selection
+        # @param expense_descriptions [Array] Strings containing the pool of available expense descriptions, for use in
+        #                                     random selection
+        # @param deposit_average [RVGP::Journal::Commodity] The average deposit amount
+        # @param deposit_stddev [Float] The stand deviation, on random deposits
+        # @param withdrawal_average [RVGP::Journal::Commodity] The average withdrawal amount
+        # @param withdrawal_stddev [Float] The stand deviation, on random withdrawals
+        # @param starting_balance [RVGP::Journal::Commodity]
+        #        The balance of the account, before generating the transactions in the feed
+        # @param post_count [Numeric] The number of transactions to generate, in this csv feed
+        # @param deposit_ratio [Float] The odds ratio, for a given transaction, to be a deposit
+        # @param entries [Array] An array of Array's, that are appended to the generated entries (aka 'lines')
+        # @return [String] A CSV, containing the generated transactions
+        def basic_checking(from: ::Date.today,
+                           to: from + DEFAULT_LENGTH_IN_DAYS,
+                           expense_descriptions: nil,
+                           income_descriptions: nil,
+                           deposit_average: RVGP::Journal::Commodity.from_symbol_and_amount('$', 6000),
+                           deposit_stddev: 500.0,
+                           withdrawal_average: RVGP::Journal::Commodity.from_symbol_and_amount('$', 300),
+                           withdrawal_stddev: 24.0,
+                           post_count: DEFAULT_POST_COUNT,
+                           starting_balance: RVGP::Journal::Commodity.from_symbol_and_amount('$', 5000),
+                           deposit_ratio: 0.05,
+                           entries: [])
+
+          running_balance = starting_balance.dup
+
+          entry_to_row = lambda do |entry|
+            FEED_COLUMNS.map do |column|
+              if column == 'RunningBalance'
+                deposit = entry['Deposit (+)']
+                withdrawal = entry['Withdrawal (-)']
+
+                running_balance = withdrawal.nil? ? running_balance + deposit : running_balance - withdrawal
+              else
+                entry[column]
+              end
+            end
+          end
+
+          # Newest to oldest:
+          to_csv do |csv|
+            dates = entries_over_date_range from, to, post_count
+
+            dates.each_with_index do |date, i|
+              # If there are any :entries to insert, in this date, do that now:
+              entries.each do |entry|
+                csv << entry_to_row.call(entry) if entry['Date'] <= date && (i.zero? || entry['Date'] > dates[i - 1])
+              end
+
+              accumulator, mean, stddev, type, description = *(
+                if Faker::Boolean.boolean true_ratio: deposit_ratio
+                  [:+, deposit_average.to_f, deposit_stddev, 'ACH',
+                   format('%s DIRECT DEP',
+                          income_descriptions ? income_descriptions.sample : Faker::Company.name.upcase)]
+                else
+                  [:-, withdrawal_average.to_f, withdrawal_stddev, 'VISA',
+                   expense_descriptions ? expense_descriptions.sample : Faker::Company.name.upcase]
+                end)
+
+              amount = RVGP::Journal::Commodity.from_symbol_and_amount(
+                DEFAULT_CURRENCY.symbol,
+                Faker::Number.normal(mean: mean, standard_deviation: stddev)
+              )
+
+              running_balance = running_balance.send accumulator, amount
+
+              amounts = [nil, amount]
+              csv << ([date, type, description] + (accumulator == :- ? amounts.reverse : amounts) + [running_balance])
+            end
+
+            # Are there any more entries? If so, sort 'em and push them:
+            entries.each { |entry| csv << entry_to_row.call(entry) if entry['Date'] > dates.last }
+          end
+        end
+
+        # Generates a basic csv feed string, that resembles those offered by banking institutions. Unlike
+        # #basic_checking, this faker supports a set of parameters that will better conform the output to a
+        # typical model of commerence for an employee with a paycheck and living expenses. As such, the
+        # parameters are a bit different, and suited to plotting aesthetics.
+        #
+        # @param from [Date] The date to start generated feed from
+        # @param to [Date] The date to end generated feed
+        # @param income_sources [Array] Strings containing the pool of income companies, to use for growing our assets
+        # @param expense_sources [Array] Strings containing the pool of available expense companies, to use for
+        #                                shrinking our assets
+        # @param opening_liability_balance [RVGP::Journal::Commodity] The opening balance of the liability account,
+        #                                                            preceeding month zero
+        # @param opening_asset_balance [RVGP::Journal::Commodity] The opening balance of the asset account, preceeding
+        #                                                        month zero
+        # @param liability_sources [Array] Strings containing the pool of available liability sources (aka 'companies')
+        # @param liabilities_by_month [Array] An array of RVGP::Journal::Commodity entries, indicatiing the liability
+        #                                     balance for a month with offset n, from the from date
+        # @param assets_by_month [Array] An array of RVGP::Journal::Commodity entries, indicating the asset
+        #                                balance for a month with offset n, from the from date
+        # @return [String] A CSV, containing the generated transactions
+        def personal_checking(from: ::Date.today,
+                              to: from + DEFAULT_LENGTH_IN_DAYS,
+                              expense_sources: [Faker::Company.name.tr('^a-zA-Z0-9 ', '')],
+                              income_sources: [Faker::Company.name.tr('^a-zA-Z0-9 ', '')],
+                              monthly_expenses: {},
+                              opening_liability_balance: '$ 0.00'.to_commodity,
+                              opening_asset_balance: '$ 0.00'.to_commodity,
+                              liability_sources: [Faker::Company.name.tr('^a-zA-Z0-9 ', '')],
+                              liabilities_by_month: months_in_range(from, to).map.with_index do |_, n|
+                                RVGP::Journal::Commodity.from_symbol_and_amount('$', 200 + ((n + 1) * 800))
+                              end,
+                              assets_by_month: months_in_range(from, to).map.with_index do |_, n|
+                                RVGP::Journal::Commodity.from_symbol_and_amount('$', 500 * ((n + 1) * 5))
+                              end)
+
+          num_months_in_range = ((to.year * 12) + to.month) - ((from.year * 12) + from.month) + 1
+
+          ['liabilities_by_month', liabilities_by_month.length,
+           'assets_by_month', assets_by_month.length].each_slice(2) do |attr, length|
+            raise ParameterLengthError.new(attr, num_months_in_range, length) unless num_months_in_range == length
+          end
+
+          monthly_expenses.each_pair do |company, expenses_by_month|
+            unless num_months_in_range == expenses_by_month.length
+              attr = format('monthly_expenses: %s', company)
+              raise ParameterLengthError.new(attr, num_months_in_range, expenses_by_month.length)
+            end
+          end
+
+          liability_balance = opening_liability_balance
+          asset_balance = opening_asset_balance
+
+          # Newest to oldest:
+          to_csv do |csv|
+            months_in_range(from, to).each_with_index do |first_of_month, i|
+              expected_liability = liabilities_by_month[i]
+
+              # Let's adjust the liability to suit
+              csv << if expected_liability > liability_balance
+                       # We need to borrow some more money:
+                       deposit = (expected_liability - liability_balance).abs
+                       asset_balance += deposit
+                       liability_balance += deposit
+                       [first_of_month, 'ACH', liability_sources.sample, nil, deposit, asset_balance]
+                     elsif expected_liability < liability_balance
+                       # We want to pay off our balance:
+                       payment = (expected_liability - liability_balance).abs
+                       asset_balance -= payment
+                       liability_balance -= payment
+                       [first_of_month, 'ACH', liability_sources.sample, payment, nil, asset_balance]
+                     end
+
+              expected_assets = assets_by_month[i]
+
+              monthly_expenses.each_pair do |company, expenses_by_month|
+                asset_balance -= expenses_by_month[i]
+                csv << [first_of_month, 'VISA', company, expenses_by_month[i], nil, asset_balance]
+              end
+
+              # Let's adjust the assets to suit
+              if expected_assets > asset_balance
+                # We need a paycheck:
+
+                deposit = expected_assets - asset_balance
+                asset_balance += deposit
+                csv << [first_of_month, 'ACH', income_sources.sample, nil, deposit, asset_balance]
+              elsif expected_assets < asset_balance
+                # We need to generate some expenses:
+                payment = asset_balance - expected_assets
+                asset_balance -= payment
+                csv << [first_of_month, 'VISA', expense_sources.sample, payment, nil, asset_balance]
+              end
+            end
+          end
+        end
+
+        private
+
+        def months_in_range(from, to)
+          ret = []
+          i = 0
+          loop do
+            ret << (Date.new(from.year, from.month, 1) >> i)
+            i += 1
+            break if ret.last.year == to.year && ret.last.month == to.month
+          end
+
+          ret
+        end
+
+        def to_csv(&block)
+          converter = lambda do |field|
+            case field
+            when Date
+              field.strftime('%m/%d/%Y')
+            when RVGP::Journal::Commodity
+              field.to_s(precision: DEFAULT_CURRENCY.minor_unit)
+            else
+              field
+            end
+          end
+
+          CSV.generate force_quotes: true, headers: FEED_COLUMNS, write_headers: true, write_converters: [converter],
+                       &block
+        end
+      end
+    end
+  end
+end

data/lib/rvgp/fakers/fake_journal.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'faker_helpers'
+
+module RVGP
+  # This module encapsulate various faker objects that we use (mostly) in our test cases.
+  # The new_project command uses some of these classes as well.
+  module Fakers
+    # Contains faker implementation(s) that produce pta journals
+    class FakeJournal < Faker::Base
+      class << self
+        include FakerHelpers
+
+        # Generates a basic journal, that credits/debits from a Cash account
+        #
+        # @param from [Date] The date to start generated postings from
+        # @param to [Date] The date to end generated postings
+        # @param sum [RVGP::Journal::Commodity]
+        #        The amount that all postings in the generated journal, will add up to
+        # @param post_count [Numeric] The number of postings to generate, in this journal
+        # @param postings [Array] An array of RVGP::Journal::Posting objects, for inclusion in the output
+        # @return [RVGP::Journal] A fake journal, conforming to the provided params
+        def basic_cash(from: ::Date.today,
+                       to: from + 9,
+                       sum: '$ 100.00'.to_commodity,
+                       post_count: 10,
+                       postings: [])
+
+          raise StandardError unless sum.is_a?(RVGP::Journal::Commodity)
+
+          amount_increment = (sum / post_count).floor sum.precision
+          running_sum = nil
+
+          generated_postings = entries_over_date_range(from, to, post_count).map.with_index do |date, i|
+            post_amount = i + 1 == post_count ? (sum - running_sum) : amount_increment
+
+            running_sum = running_sum.nil? ? post_amount : (running_sum + post_amount)
+
+            simple_posting date, post_amount
+          end
+          RVGP::Journal.new((postings + generated_postings).sort_by(&:date))
+        end
+
+        private
+
+        def simple_posting(date, amount)
+          transfers = [to_transfer('Expense', commodity: amount), to_transfer('Cash')]
+          RVGP::Journal::Posting.new date, Faker::Company.name, transfers: transfers
+        end
+
+        def to_transfer(*args)
+          RVGP::Journal::Posting::Transfer.new(*args)
+        end
+      end
+    end
+  end
+end

data/lib/rvgp/fakers/fake_reconciler.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'faker_helpers'
+
+module RVGP
+  module Fakers
+    # Contains faker implementations that produce reconciler yamls
+    class FakeReconciler < Faker::Base
+      class << self
+        include FakerHelpers
+
+        # @!visibility private
+        DEFAULT_FORMAT = <<~FORMAT_TEMPLATE
+          csv_headers: true
+          reverse_order: true
+          default_currency: $
+          fields:
+            date: !!proc Date.strptime(row['Date'], '%m/%d/%Y')
+            amount: !!proc >
+              withdrawal, deposit = row[3..4].collect {|a| a.to_commodity unless a.empty?};
+              ( deposit ? deposit.invert! : withdrawal ).quantity_as_s
+            description: !!proc row['Description']
+        FORMAT_TEMPLATE
+
+        # @!visibility private
+        BASIC_CHECKING_FEED = <<~FEED_TEMPLATE
+          from: "%<from>s"
+          label: "%<label>s"
+          format: %<format>s
+          input: %<input_path>s
+          output: %<output_path>s
+          balances:
+            # TODO: Transcribe some expected balances, based off bank statements,
+            # here, in the form :
+            # '2023-01-04': $ 1000.00
+          income: %<income>s
+          expense: %<expense>s
+        FEED_TEMPLATE
+
+        # Generates a basic reconciler, for use in reconciling a basic_checking feed
+        # @param from [String] The from parameter to write into our yaml
+        # @param label [String] The label parameter to write into our yaml
+        # @param format_path [String] A path to the format yaml, for use in the format parameter of our yaml
+        # @param input_path [String] A path to the input feed, for use in the input parameter of our yaml
+        # @param output_path [String] A path to the output journal, for use in the output parameter of our yaml
+        # @param income [Array] An array of hashes, containing the income rules, to write into our yaml
+        # @param expense [Array] An array of hashes, containing the expense rules, to write into our yaml
+        # @return [String] A YAML file, containing the generated reconciler
+        def basic_checking(from: 'Personal:Assets:AcmeBank:Checking',
+                           label: nil,
+                           format_path: nil,
+                           input_path: nil,
+                           output_path: nil,
+                           income: nil,
+                           expense: nil)
+
+          raise StandardError if [from, label, input_path, output_path].any?(&:nil?)
+
+          format = "!!include #{format_path}" if format_path
+          format ||= format("\n%s", DEFAULT_FORMAT.gsub(/^/, '  ').chomp)
+
+          format BASIC_CHECKING_FEED,
+                 from: from,
+                 label: label,
+                 format: format,
+                 input_path: input_path,
+                 output_path: output_path,
+                 income: hashes_to_yaml_array(
+                   [income, { match: '/.*/', to: 'Personal:Income:Unknown' }].flatten.compact
+                 ),
+                 expense: hashes_to_yaml_array(
+                   [expense, { match: '/.*/', to: 'Personal:Expenses:Unknown' }].flatten.compact
+                 )
+        end
+
+        private
+
+        def hashes_to_yaml_array(hashes)
+          format("\n%s", hashes.map do |hash|
+            hash.each_with_index.map do |pair, i|
+              (i.zero? ? '  - ' : '    ') + pair.join(': ')
+            end
+          end.flatten.join("\n"))
+        end
+      end
+    end
+  end
+end

data/lib/rvgp/fakers/faker_helpers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'faker'
+
+require_relative '../journal'
+require_relative '../journal/commodity'
+
+module RVGP
+  module Fakers
+    # This module offers code that is shared by a number of our fakers. Mostly,
+    # this just keeps those fakers DRY.
+    module FakerHelpers
+      private
+
+      # Uniformly distribute the transactions over a date range
+      def entries_over_date_range(from, to, count = nil)
+        raise StandardError unless [from.is_a?(::Date), to.is_a?(::Date), count.is_a?(Numeric)].all?
+
+        run_length = ((to - from).to_f + 1) / (count - 1)
+
+        1.upto(count).map { |n| n == count ? to : from + (run_length * (n - 1)) }
+      end
+    end
+  end
+end

data/lib/rvgp/gem.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module RVGP
+  # This class contains information relating to our Gem configuration, and is
+  # used to produce a gemspec.
+  class Gem
+    VERSION = '0.3.2'
+
+    # @!visibility private
+    GEM_DIR = File.expand_path format('%s/../..', File.dirname(__FILE__))
+
+    class << self
+      # Returns the gem specification
+      # @return [Gem::Specification]
+      def specification
+        ::Gem::Specification.new do |s|
+          s.name        = 'rvgp'
+          s.version     = VERSION
+          s.required_ruby_version = '>= 3.0.0'
+          s.licenses    = ['LGPL-2.0']
+          s.authors     = ['Chris DeRose']
+          s.email       = 'chris@chrisderose.com'
+          s.metadata    = {
+            'source_code_uri' => 'https://github.com/brighton36/rvgp',
+            'documentation_uri' => ['https://www.rubydoc.info/gems/rvgp', VERSION].join('/')
+          }
+
+          s.doc_dir 'doc'
+
+          s.summary = 'A workflow tool to: reconcile bank-downloaded csv\'s into ' \
+                      'categorized pta journals. Run finance validations on those ' \
+                      'journals. And generate csvs and plots on the output.'
+          s.homepage = 'https://github.com/brighton36/rvgp'
+
+          s.files = files
+
+          s.executables = ['rvgp']
+
+          s.add_development_dependency 'minitest', '~> 5.16.0'
+          s.add_development_dependency 'yard', '~> 0.9.34'
+          s.add_development_dependency 'redcarpet', '~> 3.6.0'
+
+          s.add_dependency 'open3', '~> 0.1.1'
+          s.add_dependency 'shellwords', '~> 0.1.0'
+          s.add_dependency 'google-apis-sheets_v4', '~> 0.28.0'
+          s.add_dependency 'faker', '~> 3.2.0'
+          s.add_dependency 'finance', '~> 2.0.0'
+          s.add_dependency 'tty-table', '~> 0.12.0'
+        end
+      end
+
+      # This is a git-less alternative to : `git ls-files`.split "\n"
+      # @return [Array<String>] the paths of all rvgp development files in this gem.
+      def files
+        output, exit_code = Open3.capture2(format("find %s -type f -printf '%%P\n'", root))
+        raise StandardError, 'find command failed' unless exit_code.success?
+
+        output.split("\n").reject do |file|
+          ignores = ['.git/*'] + File.read(format('%s/.gitignore', GEM_DIR)).split("\n")
+          ignores.any? { |glob| File.fnmatch glob, file }
+        end
+      end
+
+      # Return all ruby (code) files in this project.
+      # @return [Array<String>] the paths of all ruby files in this gem.
+      def ruby_files
+        files.select { |f| /\A(?:bin.*|Rakefile|.*\.rb)\Z/.match f }
+      end
+
+      # The directory path to the rvgp gem, as calculated from the location of this gem.rb file.
+      # @param [String] sub_path If provided, append this path to the output
+      # @return [String] The full path to the gem root, plus any subpathing, if appropriate
+      def root(sub_path = nil)
+        sub_path ? [GEM_DIR, sub_path].join('/') : GEM_DIR
+      end
+    end
+  end
+end