rvgp 0.3.2

data/lib/rvgp/utilities.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RVGP
+  # This module contains helper methods used throughout RVGP. These are just common
+  # codepaths, that have little in common, save for their general utility.
+  module Utilities
+    # This returns each month in a series from the first date, to the last, in the
+    # provided array of dates
+    # @overload months_through(date, ...)
+    #   @param [Array<Date>] date A date, that will be used to calculate the range of months to construct a range from.
+    #   @param [Array<Date>] ... More dates. This method will automatically select the max and min from the sample
+    #                            provided.
+    # @return [Array<Date>] An array, containing a Date, set to the first of every month, in the provided range.
+    def months_through(*args)
+      dates = args.flatten.uniq.sort
+
+      ret = []
+      unless dates.empty?
+        d = Date.new dates.first.year, dates.first.month, 1 # start_at
+        while d <= Date.new(dates.last.year, dates.last.month, 1) # end_at
+          ret << d
+          d = d >> 1
+        end
+      end
+      ret
+    end
+
+    # Convert the provided string, into a Regexp. Note that the the ixm suffixes are supported, unlike
+    # ruby's Regexp.new(str) method
+    # @param [String] str A string, in the 'standard' regexp format: '/Running (?:to|at) the Park/i'
+    # @return [Regexp] The conversion to a useable regexp, for the provided string
+    def string_to_regex(str)
+      if %r{\A/(.*)/([imx]?[imx]?[imx]?)\Z}.match str
+        Regexp.new(::Regexp.last_match(1), ::Regexp.last_match(2).chars.map do |c|
+          case c
+          when 'i' then Regexp::IGNORECASE
+          when 'x' then Regexp::EXTENDED
+          when 'm' then Regexp::MULTILINE
+          end
+        end.reduce(:|))
+      end
+    end
+  end
+end

data/lib/rvgp/validations/balance_validation.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RVGP
+  module Validations
+    # This validation asserts that the ledger-reported balance, matches a provided
+    # balance, on a given day. These balances, should be stipulated in a section
+    # of your reconciler, that looks like this:
+    # ```
+    # balances:
+    #   '2022-01-01': $ 105.63
+    #   '2022-09-01': $ 300.29
+    #   '2022-10-01': $ 400.33
+    # ```
+    # These balances are expected to come from a bank statement, and this validation
+    # ensures that rvgp is matching the records of your financial institution
+    class BalanceValidation < RVGP::Base::JournalValidation
+      # If there are no checkpoints in the 'balances' line of the reconciler, this
+      # fires a warning. If there are checkpoints, then, we scan the register to
+      # ensure that the balance of the reconciler.from, on the checkpoint date,
+      # matches the ledger/hledger balance, on that date. (and if it doesnt,
+      # fires an error)
+      def validate
+        if reconciler.balances.nil? || reconciler.balances.empty?
+          warning! 'No balance checkpoints found.'
+        else
+          is_account_valid = true
+          cite_balances = reconciler.balances.map do |d, expected_balance_s|
+            expected_balance = expected_balance_s.to_commodity
+
+            balances_on_day = pta.balance format('^%s$', reconciler.from),
+                                          depth: 1,
+                                          end: d.to_s,
+                                          file: RVGP.app.config.project_journal_path
+
+            balances_found = balances_on_day.accounts.map(&:amounts).flatten.find_all do |amount|
+              amount.code == expected_balance.code
+            end
+
+            found = if balances_found.empty?
+                      # Rather than operate from nil, we'll establish that we're '0' of units
+                      # of the expected symbol
+                      RVGP::Journal::Commodity.from_symbol_and_amount expected_balance.code, 0
+                    else
+                      balances_found.sum
+                    end
+
+            found_as_s = if found
+                           format('Found: %s', found.to_s)
+                         else
+                           found = RVGP::Journal::Commodity.from_symbol_and_amount expected_balance.code, 0
+                           '(Nil)'
+                         end
+
+            is_valid = expected_balance == found
+            is_account_valid = false unless is_valid
+
+            format('(%<day>s) Expected: %<expected>s %<indicator>s',
+                   day: d.to_s,
+                   expected: expected_balance.to_s,
+                   indicator: RVGP.pastel.send(is_valid ? :green : :red, found_as_s))
+          end
+
+          error! 'Failed Checkpoint(s):', cite_balances unless is_account_valid
+        end
+      end
+    end
+  end
+end

data/lib/rvgp/validations/duplicate_tags_validation.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RVGP
+  module Validations
+    # This class implements a journal validation that ensures a given transfer, hasn't
+    # been tagged more than once, with the same tag.
+    class DuplicateTagsValidation < RVGP::Base::JournalValidation
+      # Reviews every transfer, and post, to ensure that there are no tags occurring more than once, in
+      # any given entry. Unlike most of the validations in RVGP, this one doesn't use ledger or hledger
+      # to validate. This validation parses the file itself, in ruby, and ensures based on the contents.
+      def validate
+        journal = RVGP::Journal.parse File.read(reconciler.output_file)
+        dupe_messages = []
+
+        journal.postings.each do |posting|
+          posting_tag_names = posting.tags.map(&:key)
+          found_dupes = posting_tag_names.find_all { |tag| posting_tag_names.count(tag) > 1 }.uniq
+
+          if found_dupes.empty?
+            posting.transfers.each do |transfer|
+              transfer_tag_names = transfer.tags.map(&:key) + posting_tag_names
+
+              found_dupes = transfer_tag_names.find_all { |tag| transfer_tag_names.count(tag) > 1 }.uniq
+
+              next if found_dupes.empty?
+
+              dupe_messages << format('Line %<line>d: %<date>s %<desc>s (Transfer: %<tags>s)',
+                                      line: posting.line_number,
+                                      date: posting.date,
+                                      desc: posting.description,
+                                      tags: found_dupes.join(', '))
+            end
+          else
+            dupe_messages << format('Line %<line>d: %<date>s %<desc>s (%<tags>s)',
+                                    line: posting.line_number,
+                                    date: posting.date,
+                                    desc: posting.description,
+                                    tags: found_dupes.join(','))
+          end
+        end
+
+        unless dupe_messages.empty?
+          error! 'These postings have been tagged with the same tag, more than once', dupe_messages
+        end
+      end
+    end
+  end
+end

data/lib/rvgp/validations/uncategorized_validation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RVGP
+  # This module provides a number of basic, and common, validations for use in your projects
+  module Validations
+    # This class implements a journal validation that ensures there are no uncategorized
+    # expenses in the journal
+    class UncategorizedValidation < RVGP::Base::JournalValidation
+      # Ensures that there is no balance for 'Unknown' categories in a journal
+      def validate
+        validate_no_balance 'Uncategorized Transactions', 'Unknown'
+      end
+    end
+  end
+end

data/lib/rvgp.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'rvgp/utilities/yaml'
+require_relative 'rvgp/application'
+require_relative 'rvgp/commands'
+require_relative 'rvgp/base/reconciler'
+
+# NOTE: Reconcilers & shorthand may want to go into a registry system at
+# some point, akin to grids/validations.
+require_relative 'rvgp/reconcilers/csv_reconciler'
+require_relative 'rvgp/reconcilers/journal_reconciler'
+require_relative 'rvgp/reconcilers/shorthand/mortgage'
+require_relative 'rvgp/reconcilers/shorthand/investment'
+require_relative 'rvgp/reconcilers/shorthand/international_atm'
+
+require_relative 'rvgp/base/validation'
+
+require_relative 'rvgp/journal'
+require_relative 'rvgp/pta/ledger'
+require_relative 'rvgp/pta/hledger'
+
+require_relative 'rvgp/base/grid'
+
+# Gem Paths / Resources:
+require_relative 'rvgp/gem'
+
+I18n.load_path << Dir[RVGP::Gem.root('resources/i18n/*.yml')]
+RVGP::Journal::Currency.currencies_config = RVGP::Gem.root('resources/iso-4217-currencies.json')
+
+# The base module, under which all RVGP code is filed
+module RVGP
+  # @param from_path [String] The directory path, to an RVGP project.
+  # @return [RVGP::Application] The initialized application, that was stored in RVGP.app
+  def self.initialize_app(from_path)
+    raise StandardError, 'Application is already initialized' if @app
+
+    @app = Application.new from_path
+  end
+
+  # @return [RVGP::Application] The currently-initialized RVGP:Application
+  def self.app
+    @app
+  end
+
+  # @return [Pastel] The global pastel object, used to output to the console.
+  def self.pastel
+    @pastel ||= Pastel.new enabled: $stdout.tty?
+  end
+
+  # @!attribute [r] self.commands
+  #   Contains an array of all available objects, with parent of type {RVGP::Base::Command}.
+  #   @return [Array<RVGP::Base::Command>] the commands that are available in this project
+  # @!attribute [r] self.grids
+  #   Contains an array of all available objects, with parent of type {RVGP::Base::Grid}.<br>
+  #   **NOTE:** RVGP.app.task_names => Array<String>, will return all grid-building tasks that have been defined in the
+  #   project.
+  #   @return [Array<RVGP::Base::Grid>] the grids that are available in this project
+  # @!attribute [r] self.journal_validations
+  #   Contains an array of all available objects, with parent of type {RVGP::Base::JournalValidation}.
+  #   @return [Array<RVGP::Base::JournalValidation>] the journal validations that are available in this project
+  # @!attribute [r] self.system_validations
+  #   Contains an array of all available objects, with parent of type {RVGP::Base::SystemValidation}.<br>
+  #   **NOTE:** RVGP.system_validations.task_names => Array<String>, will return all system validation tasks that have
+  #   been defined in the project.
+  #   @return [Array<RVGP::Base::SystemValidation>] the system validations that are available in this project
+end

data/resources/gnuplot/default.yml

@@ -0,0 +1,80 @@
+colors:
+  base:
+    # Solarized Light:
+    base03:  '#002b36'
+    base02:  '#073642'
+    base01:  '#586e75'
+    base00:  '#657b83'
+    base0:   '#839496'
+    base1:   '#93a1a1'
+    base2:   '#eee8d5'
+    base3:   '#fdf6e3'
+    yellow:  '#b58900'
+    orange:  '#cb4b16'
+    red:     '#dc322f'
+    magenta: '#d33682'
+    violet:  '#6c71c4'
+    blue:    '#268bd2'
+    cyan:    '#2aa198'
+    green:   '#859900'
+    font:       :base03
+    title:      :font
+    grid:       :base02
+    axis:       :base02
+    key_text:   :font
+    background: :base3
+  series:
+    # https://www.heavy.ai/blog/12-color-palettes-for-telling-better-stories-with-your-data
+    # Spring Pastels
+    - "#7eb0d5"
+    - "#fd7f6f"
+    - "#b2e061"
+    - "#bd7ebe"
+    - "#ffb55a"
+    - "#ffee65"
+    - "#beb9db"
+    - "#fdcce5"
+    - "#8bd3c7"
+    # Retro Metro
+    - "#ea5545"
+    - "#f46a9b"
+    - "#ef9b20"
+    - "#edbf33"
+    - "#ede15b"
+    - "#bdcf32"
+    - "#87bc45"
+    - "#27aeef"
+    # http://www.gnuplotting.org/data/dark2.pal
+    - '#1B9E77'
+    - '#D95F02'
+    - '#7570B3'
+    - '#E7298A'
+    - '#66A61E'
+    - '#E6AB02'
+    - '#A6761D'
+    # Blue to Yellow
+    - "#115f9a"
+    - "#1984c5"
+    - "#22a7f0"
+    - "#48b5c4"
+    - "#76c68f"
+    - "#a6d75b"
+    - "#c9e52f"
+    - "#d0ee11"
+    - "#d0f400"
+header: |+
+  set datafile separator ","
+  set title "%{title}" font "sans,11" textcolor rgb "%{title_rgb}" enhanced
+  set terminal wxt size 1200,400 persist enhanced font 'sans,10' background rgb '%{background_rgb}'
+  set style line 102 lc rgb '%{grid_rgb}' lt 0 lw 1
+  set grid back ls 102
+  set style line 101 lc rgb '%{axis_rgb}' lt 1 lw 1
+  set border 3 front ls 101
+  set xtics font ",9"
+  set ytics font ",11"
+  set timefmt "%%m-%%y"
+  set format x "%%b-%%y"
+  set format y "$ %%'.0f"
+  unset colorbox
+  set key on under center textcolor rgb "%{key_text_rgb}" enhanced font 'sans,9'
+  set decimal locale

data/resources/i18n/en.yml

@@ -0,0 +1,192 @@
+en:
+  help:
+    usage: 'Usage: %{program} [OPTION]... [COMMAND] [TARGET]...'
+    indent: '  '
+    description: >
+      A plain text accounting workflow tool for: (r)econciling, (v)alidating, (g)rid-production and (p)lotting your finances with ruby. See the program github for more details.
+
+    command_introduction: >
+      COMMAND - This is a required parameter. Command-specific options are 
+      further available, once you've specified a command mode. See the 'Available Commands' section for a list of supported commands.
+    target_introduction: >
+      TARGET(s) - Depending on which command you select, a list of targets can be supplied. Typically,
+      supplying the -l option, in lieu of any targets, will output the targets supported by the command.
+      Note that any asterisk encountered in a target parameter, will expand to include all targets that
+      can be matched given the provided (target) string.
+    command_list_introduction: 'Available Commands:'
+    global_option_introduction: >
+      Global Options:
+        The following options are available to all commands:
+
+        -d --dir[=PATH]  Use the supplied PATH as the active rvgp directory.
+                         If unsupplied, this option defaults to the basedir of 
+                         the LEDGER_FILE environment variable.
+    commands:
+      cashflow:
+        description: 'Output a convenient dashboard with income/expense flows, based on intention'
+        options: 
+          all: 'Output a dashboard for every intention in the system'
+          list: 'List all available intention-tag values'
+          date: 'Specify a date to use, when calculatingg the "recent months" to display. Defaults to "today".'
+      new_project:
+        description: 'Create a new plain text accounting project, populated with random data, in the path specified by --dir.'
+      plot:
+        description: 'Build one or more gnuplots, based on a grid variant.'
+        options:
+          all: 'Build all available plots'
+          list: 'List all available plots'
+          stdout: 'Output build to STDOUT instead of output_file'
+      publish_gsheets:
+        description: 'Publish plots, both as a spreadsheet, as well as a graph, into a google sheets workbook.'
+        options: 
+          all: 'Publish all available plots'
+          list: 'List all available plot variants'
+          csvdir: 'Output the provided plots, as csvs, with grid hacks applied, into the specified directory. Mostly useful for debugging.'
+          title: 'The title of the Google doc being published. Defaults to "RVGP Finance Report %m/%d/%y %H:%M". '
+          sleep: 'Seconds to sleep, between each sheet upload. This sleep prevents Google from aborting the publish, under the auspice of api spamming. Defaults to 5.'
+      ireconcile:
+        description: 'Open an interactive vim session, to edit and build a reconcile'
+        options: 
+          all: 'Process all available reconcilers'
+          list: 'List all available reconcilers'
+          vsplit: 'Split the input and output panes vertically, instead of horizontally (the default)'
+      grid:
+        description: "Generate Grid csv's in build/grids"
+        options: 
+          all: 'Process all available grids'
+          list: 'List all available grids'
+      reconcile:
+        description: 'Create/Update the build/*.journal, based on ./reconcilers/*.yml'
+        options: 
+          stdout: 'Output build to STDOUT instead of output_file'
+          all: 'Process all available reconcilers'
+          list: 'List all available reconcilers'
+          concise: "Concise output mode. Strips output that's unrelated to errors and warnings. (Mostly used by the ireconcile command)"
+      rotate_year:
+        description: "Rotate the given reconcilers, for a new year. And, move the last year's input files into the historical directory under your project feeds."
+        options:
+          all: 'Rotate all eligible reconcilers'
+          list: 'List reconcilers eligible for rotation'
+      validate_journal:
+        description: 'Validate reconciled journals, using the app/validations'
+        options: 
+          all: 'Process all available journals'
+          list: 'List all available journals'
+      validate_system:
+        description: 'Run validations on the ledger, once the individual journals are valid'
+        options: 
+          all: 'Process all available system validations'
+          list: 'List all available system validations'
+  commands:
+    cashflow:
+      list_targets: 'The following cashflow intentions are available:'
+      account: 'Account'
+      expenses: 'Expenses'
+      income: 'Income'
+      cash_flow: 'Cash Flow'
+      errors:
+        screen_too_small: 'Screen width "%{screen_width}" is too small. Minimum width is %{minimum_width}.'
+        unrecognized_path: 'Unrecognized path: %{file}'
+    new_project:
+      directory_exists_prompt: "The directory \"%{dir}\" already exists. Continuing will overwrite some of its contents. Are you sure you wish to continue creating a new project in this directory? (Type \"Yes\" to continue) : "
+      project_name_prompt: "Whose project is this? A person's full name or a company name will work: "
+      project_name_confirmation: "You entered \"%{project_name}\". Is that correct? (Type \"Yes\" to continue) : "
+      confirm_operation: "Yes"
+      operation_aborted: "\"new_project\" project operation aborted"
+      completed_banner: "\nThe new project has been generated successfully.\nThough you may want to add the following line to your ~/.bashrc:\n  export LEDGER_FILE=\"%{journal_path}\"\n\nYou're ready to begin working on this project. Try cd'ing into its directory, and running `rake`."
+      initialize:
+        project_directory: "Project directory"
+        bank_feeds: 'Randomized bank feeds'
+        reconcilers: 'Randomized reconcilers'
+      errors:
+        missing_app_dir: "An application directory was not provided, and is required. Set this parameter via --dir argument, or via the LEDGER_FILE environment variable"
+        directory_exists: "The directory \"%{dir}\" could not be created because it already exists."
+    plot:
+      target_description: 'Build the %{name} plot file, and its variants'
+    rotate_year:
+      list_targets: 'The following reconcilers are eligible for annual rotation:'
+      operations_header: 'The following command(s) will be executed:'
+      operation_rotate: 'Rotate "%{name}"'
+      operation_mkdir: 'mkdir %{path}'
+      confirm_operation: "Yes"
+      confirm_operation_prompt: "Would you like to run the above operations? (Type \"Yes\" to continue) "
+      operation_aborted: "\"rotate_year\" project operation aborted"
+      operation_element: '  🟢 %{operation}'
+    publish_gsheets:
+      errors:
+        missing_google_secrets: 'Missing a readable config/google-secrets.yml file in your project directory'
+        unable_to_write_to_csvdir: 'Unable to write to path "%{csvdir}"'
+    grid:
+      list_targets: 'The following grids are available:'
+      target_description: '%{description} for %{year}'
+    rescan_grids:
+      target_description: 'Re-scan the journal directory, and register previously unavaible grid targets into the running build'
+    rescan_plots:
+      target_description: 'Re-scan the grid directory, and register previously unavaible plot targets into the running build'
+    reconcile:
+      list_targets: 'The following reconcilers are available:'
+      target_description: 'Reconcile the "%{input_file}" journal'
+      errors:
+        journal_missing: 'Journal(s) Missing.'
+        either_concise_or_stdout: 'Either -concise or -stdout mode can be specified. But, alas, not both.'
+    validate_journal:
+      list_targets: 'The following journal validations are available:'
+      target_description: 'Validate the "%{input_file}" journal'
+    validate_system:
+      list_targets: 'The following system validations are available:'
+
+  error:
+    error: 'Error'
+    warning: 'Warning'
+    missing_entry_in_prices_db: ": The following entry is missing in the prices database:\n P %{time} %{from} %{to}"
+    end_of_args: 'Missing an expected parameter value, in the argument list'
+    no_targets: "No targets specified"
+    missing_target: "One or more targets not found : %{targets}"
+    missing_command: 'No command specified. Try running --help to view the available program modes'
+    command_unrecognized: '"%{command}" command is unrecognized. Consult the help page.'
+    command_errors: "Unable to %{command}:"
+    command_error: "  🟢 %{error}"
+    no_application_dir: "Unable to determine the directory of your application. Consider setting the LEDGER_FILE environment variable, or providing a directory via the --dir parameter"
+    invalid_application_dir: 'Invalid or missing project found at the directory "%{directory}"'
+  status:
+    indicators:
+      complete: '🟢'
+      complete_and: '%{left} & %{right} '
+      fill: '.'
+      indent: '   '
+      truncated: '…'
+      attention1: '🟢'
+      attention2: ' ▩ '
+    commands:
+      reconcile:
+        icon: '🏗️ '
+        header: Building Journals from Feeds
+        prefix: Expanding
+      generate:
+        icon: 🏦
+        header: Generating Automatic Transactions
+        prefix: Making
+      validate_journal:
+        icon: 📒
+        header: Inspecting Individual Journal Files
+        prefix: Validating
+      validate_system:
+        icon: 📚
+        header: Inspecting System State
+        prefix: Validating
+      grid:
+        icon: ▦
+        header: Generating Grids
+        prefix: Calculating
+      plot:
+        icon: 📈 
+        header: Generating Plots
+        prefix: Plotting
+      publish_gsheets:
+        icon: 📑 
+        header: Publishing to Google Sheets
+        prefix: Sheeting
+      new_project:
+        icon: 📖
+        header: New Project
+        prefix: Initializing