rvgp 0.3.2

data/lib/rvgp/base/validation.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require_relative '../application/descendant_registry'
+
+module RVGP
+  module Base
+    # This class contains methods shared by both {RVGP::Base::JournalValidation} and {RVGP::Base::SystemValidation}.
+    # Validations are run during a project build, after the reconcile tasks.
+    #
+    # Validations are typically defined inside a .rb in your project's app/validations folder, and should inherit from
+    # JournalValidation or SystemValidation (though not this class itself). Your validations can be customized
+    # in ruby, to add warnings or errors to your build. Warnings are non-fatal, and merely output a notice on the
+    # command line. Errors are fatal, and halt a build.
+    #
+    # This Base class contains some common helpers for use in your validations, regardless of whether its a system or
+    # journal validation. Here are the differences between these two validation classes:
+    #
+    # ##Journal Validations
+    # Validate the output of one reconciler at a time<br>
+    #
+    # These validations are run immediately after the reconcile task, and before system validations
+    # are run. Each instance of these validations is applied to a reconcilers output file (typically located in
+    # build/journal). And by default, any journal validations that are defined in a project's app/validations are
+    # instantiated against every reconciler's output, in the project. This behavior can be overwritten, by defining a
+    # 'disable_checks' array in the root of the reconciler's yaml, containing the name(s) of validations to disable
+    # for that journal. These names are expected to be the classname of the validation, underscorized, lowercase, and
+    # with the 'Validation' suffix removed from the class. For example, to disable the
+    # {RVGP::Validations::BalanceValidation} in one of the reconcilers of your project, add the following lines to its
+    # yaml:
+    # ```
+    # disable_checks:
+    #   - balance
+    # ```
+    # A JournalValidation is passed the reconciler corresponding to it's instance in its initialize method. For further
+    # details on how these validations work, see the documentation for this class here {RVGP::Base::JournalValidation}
+    # or check out an example implementation. Here's the BalanceValidation itself, which is a relatively easy example to
+    # {https://github.com/brighton36/rvgp/blob/main/lib/rvgp/validations/balance_validation.rb balance_validation.rb}
+    # follow.
+    #
+    # ##System Validations
+    # Validate the entire, finished, journal output for the project <br>
+    #
+    # Unlike Journal validations, these Validations are run without a target, and are expected to generate warnings and
+    # errors based on the state of queries spanning multiple journals.
+    #
+    # There are no example SystemValidations included in the distribution of rvgp. However, here's an easy one, to serve
+    # as reference. This validation ensures Transfers between accounts are always credited and
+    # debited on both sides:
+    # ```
+    #  class TransferAccountValidation < RVGP::Base::SystemValidation
+    #    STATUS_LABEL = 'Unbalanced inter-account transfers'
+    #    DESCRIPTION = "Ensure that debits and credits through Transfer accounts, complete without remainders"
+    #
+    #    def validate
+    #      warnings = pta.balance('Transfers').accounts.map do |account|
+    #        account.amounts.map do |amount|
+    #          [ account.fullname, RVGP.pastel.yellow('━'), amount.to_s(commatize: true) ].join(' ')
+    #        end
+    #      end.compact.flatten
+    #
+    #      warning! 'Unbalanced Transfer Encountered', warnings if warnings.length > 0
+    #    end
+    #  end
+    # ```
+    #
+    # The above validation works, if you assign transfers between accounts like so:
+    # ```
+    # ; This is how a Credit Card Payment looks in my Checking account, the source of funds:
+    # 2023-01-25 Payment to American Express card ending in 1234
+    #   Transfers:PersonalChecking_PersonalAmex    $ 10000.00
+    #   Personal:Assets:AcmeBank:Checking
+    #
+    # ; This is how a Credit Card Payment looks in my Amex account, the destination of funds:
+    # 2023-01-25 Payment Thank You - Web
+    #   Transfers:PersonalChecking_PersonalAmex    $ -10000.00
+    #   Personal:Liabilities:AmericanExpress
+    # ```
+    #
+    # In this format of transfering money, if either the first or second transfer was omitted, the
+    # TransferAccountValidation will alert you that money has gone missing somewhere at the bank, and/or is taking
+    # longer to complete, than you expected.
+    #
+    # ##Summary of Differences
+    # SystemValidations are largely identical to JournalValidations, with, the following exceptions:
+    #
+    # **Priority**
+    # Journal validations are run sooner in the rake process. Just after reconciliations have completed. System
+    # validations run immediately after all Journal validations have completed.
+    #
+    # **Input**
+    # Journal validations have one input, accessible via its {RVGP::Base::JournalValidation#reconciler}. System
+    # validations have no preconfigured inputs at all. Journal Validations support a disable_checks attribute in the
+    # reconciler yaml, and system validations have no such directive.
+    #
+    # **Labeling**
+    # With Journal validations, tasks are labeled automatically by rvgp, based on their class name. System validations
+    # are expected to define a STATUS_LABEL and DESCRIPTION constant, in order to arrive at these labels.
+    #
+    # Note that for either type of validation, most/all of the integration functionality is provided by way of the
+    # {RVGP::Base::Validation#error!} and {RVGP::Base::Validation#warning!} methods, instigated in the class'
+    # validate method.
+    #
+    # ##Error and Warning formatting
+    # The format of errors and warnings are a bit peculiar, and probably need a bit more polish to the interface.
+    # Nonetheless, it's not complicated. Here's the way it works, for both collections:
+    # - The formatting of :errors and :warnings is identical. These collections contain a hierarchy of errors, which
+    #   is used to display fatal and non-fatal output to the console.
+    # - Every element of these collections are expected to be a two element Array. The first element of which is to
+    #   be a string containing the topmost error/warning. The second element of this Array is optional. If present,
+    #   this second element is expected to be an Array of Strings, which are subordinate to the message in the first
+    #   element.
+    #
+    # @attr_reader [Array<String,Array<String>>] errors Errors encountered by this validation. See the above note on
+    #                                                   'Error and Warning formatting'
+    # @attr_reader [Array<String,Array<String>>] warnings Warnings encountered by this validation. See the above note on
+    #                                                     'Error and Warning formatting'
+    class Validation
+      include RVGP::Pta::AvailabilityHelper
+
+      # @!visibility private
+      NAME_CAPTURE = /([^:]+)Validation\Z/.freeze
+
+      attr_reader :errors, :warnings
+
+      # Create a new Validation
+      def initialize
+        @errors = []
+        @warnings = []
+      end
+
+      # Returns true if there are no warnings or errors present in this validation's instance. Otherwise, returns false.
+      # @return [TrueClass, FalseClass] whether this validation has passed
+      def valid?
+        @errors = []
+        @warnings = []
+        validate
+        (@errors.length + @warnings.length).zero?
+      end
+
+      private
+
+      def format_error_or_warning(msg, citations = nil)
+        [msg, citations || []]
+      end
+
+      # @!visibility public
+      # Add an error to our {RVGP::Base::Validation#errors} collection. The format of this error is expected to match
+      # the formatting indicated in the 'Error and Warning formatting' above.
+      # @param msg [String] A description of the error.
+      # @param citations [Array<String>] Supporting details, subordinate error citations, denotated 'below' the :msg
+      def error!(msg, citations = nil)
+        @errors << format_error_or_warning(msg, citations)
+      end
+
+      # @!visibility public
+      # Add a warning to our {RVGP::Base::Validation#warnings} collection. The format of this warning is expected to
+      # match the formatting indicated in the 'Error and Warning formatting' above.
+      # @param msg [String] A description of the warning.
+      # @param citations [Array<String>] Supporting details, subordinate warning citations, denotated 'below' the :msg
+      def warning!(msg, citations = nil)
+        @warnings << format_error_or_warning(msg, citations)
+      end
+    end
+
+    # A base class, from which your journal validations should inherit. For more information on validations, and your
+    # options, see the documentation notes on {RVGP::Base::JournalValidation}.
+    # @attr_reader [RVGP::Reconcilers::CsvReconciler,RVGP::Reconcilers::JournalReconciler] reconciler
+    #   The reconciler whose output will be inspected by this journal validation instance.
+    class JournalValidation < Validation
+      include RVGP::Application::DescendantRegistry
+
+      register_descendants RVGP, :journal_validations, name_capture: NAME_CAPTURE
+
+      attr_reader :reconciler
+
+      # Create a new Journal Validation
+      # @param [RVGP::Reconcilers::CsvReconciler,RVGP::Reconcilers::JournalReconciler] reconciler
+      #    see {RVGP::Base::JournalValidation#reconciler}
+      def initialize(reconciler)
+        super()
+        @reconciler = reconciler
+      end
+
+      # This helper method will supply the provided arguments to pta.register. And if there are any transactions
+      # returned, the supplied error message will be added to our :errors colection, citing the transactions
+      # that were encountered.
+      # @param [String] with_error_msg A description of the error that corresponds to the returned transactions.
+      # @param [Array<Object>] args These arguments are supplied directly to {RVGP::Pta::AvailabilityHelper#pta}'s
+      #                             #register method
+      def validate_no_transactions(with_error_msg, *args)
+        ledger_opts = args.last.is_a?(Hash) ? args.pop : {}
+
+        results = pta.register(*args, { file: reconciler.output_file }.merge(ledger_opts))
+
+        transactions = block_given? ? yield(results.transactions) : results.transactions
+
+        error_citations = transactions.map do |posting|
+          format '%<date>s: %<payee>s', date: posting.date.to_s, payee: posting.payee
+        end
+
+        error! with_error_msg, error_citations unless error_citations.empty?
+      end
+
+      # This helper method will supply the provided account to pta.balance. And if there is a balance returned,
+      # the supplied error message will be added to our :errors colection, citing the balance that was encountered.
+      # @param [String] with_error_msg A description of the error that corresponds to the returned balances.
+      # @param [Array<String>] account This arguments is supplied directly to {RVGP::Pta::AvailabilityHelper#pta}'s
+      #                                #balance method
+      def validate_no_balance(with_error_msg, account)
+        results = pta.balance account, file: reconciler.output_file
+
+        error_citations = results.accounts.map do |ra|
+          ra.amounts.map { |commodity| [ra.fullname, RVGP.pastel.red('━'), commodity.to_s].join(' ') }
+        end
+
+        error_citations.flatten!
+
+        error! with_error_msg, error_citations unless error_citations.empty?
+      end
+    end
+
+    # A base class, from which your system validations should inherit. For more information on validations, and your
+    # options, see the documentation notes on {RVGP::Base::JournalValidation}.
+    class SystemValidation < Validation
+      include RVGP::Application::DescendantRegistry
+
+      task_names = ->(registry) { registry.names.map { |name| format('validate_system:%s', name) } }
+      register_descendants RVGP, :system_validations,
+                           name_capture: NAME_CAPTURE,
+                           accessors: { task_names: task_names }
+
+      # @!visibility private
+      def mark_validated!
+        FileUtils.touch self.class.build_validation_file_path
+      end
+
+      # @!visibility private
+      def self.validated?
+        FileUtils.uptodate? build_validation_file_path, [
+          RVGP.app.config.build_path('journals/*.journal'),
+          RVGP.app.config.project_path('journals/*.journal')
+        ].map { |glob| Dir.glob glob }.flatten
+      end
+
+      # @!visibility private
+      def self.status_label
+        const_get :STATUS_LABEL
+      end
+
+      # @!visibility private
+      def self.description
+        const_get :DESCRIPTION
+      end
+
+      # @!visibility private
+      def self.build_validation_file_path
+        RVGP.app.config.build_path(format('journals/system-validation-%s.valid', name.to_s))
+      end
+    end
+  end
+end

data/lib/rvgp/commands/cashflow.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative '../utilities/grid_query'
+require_relative '../dashboard'
+
+module RVGP
+  module Commands
+    # @!visibility private
+    # This class contains the logic necessary to display the 'cashflow' dashboard
+    class Cashflow < RVGP::Base::Command
+      accepts_options OPTION_ALL, OPTION_LIST, [:date, :d, { has_value: 'DATE' }]
+
+      # @!visibility private
+      # This class handles the target argument, passed on the cli
+      class Target < RVGP::Base::Command::Target
+        # @!visibility private
+        def self.all
+          RVGP::Commands::Cashflow.grids_by_targetname.keys.map { |s| new s }
+        end
+      end
+
+      # @!visibility private
+      def initialize(*args)
+        super(*args)
+
+        options[:date] = Date.strptime options[:date] if options.key? :date
+
+        minimum_width = RVGP::Dashboard.table_width_given_column_widths(column_widths[0..1])
+
+        unless TTY::Screen.width > minimum_width
+          @errors << I18n.t(
+            'commands.cashflow.errors.screen_too_small',
+            screen_width: TTY::Screen.width,
+            minimum_width: minimum_width
+          )
+        end
+      end
+
+      # @!visibility private
+      def execute!
+        puts dashboards.map { |dashboard|
+          dashboard.to_s(
+            column_widths: column_widths[0...show_columns],
+            rows_ordered_by: lambda { |row|
+              series = row[0]
+              data = row[1..]
+              # Sort by the series type [Expenses/Income/etc], then by 'consistency',
+              # then by total amount
+              [series.split(':')[1], data.count(&:nil?), data.compact.sum * -1]
+            },
+            # Hide rows without any data
+            show_row: ->(row) { !row[1..].all?(&:nil?) }
+          )
+        }.join("\n\n")
+      end
+
+      # @!visibility private
+      def self.cashflow_grid_files
+        Dir.glob RVGP.app.config.build_path('grids/*-cashflow-*.csv')
+      end
+
+      # @!visibility private
+      def self.grids_by_targetname
+        @grids_by_targetname ||= cashflow_grid_files.each_with_object({}) do |file, sum|
+          unless /([^-]+)\.csv\Z/.match file
+            raise StandardError, I18n.t('commands.cashflow.errors.unrecognized_path', file: file)
+          end
+
+          tablename = ::Regexp.last_match(1).capitalize
+
+          sum[tablename] ||= []
+          sum[tablename] << file
+
+          sum
+        end
+      end
+
+      private
+
+      def dashboards
+        @dashboards ||= targets.map do |target|
+          RVGP::Dashboard.new(
+            target.name,
+            RVGP::Utilities::GridQuery.new(
+              self.class.grids_by_targetname[target.name],
+              store_cell: lambda { |cell|
+                cell ? RVGP::Journal::Commodity.from_symbol_and_amount('$', cell) : cell
+              },
+              select_columns: lambda { |col, column|
+                if options.key?(:date)
+                  Date.strptime(col, '%m-%y') <= options[:date]
+                else
+                  column.any? { |cell| !cell.nil? }
+                end
+              }
+            ),
+            { pastel: RVGP.pastel,
+              series_column_label: I18n.t('commands.cashflow.account'),
+              format_data_cell: ->(cell) { cell&.to_s commatize: true, precision: 2 },
+              columns_ordered_by: ->(a, b) { [b, a].map { |d| Date.strptime d, '%m-%y' }.reduce :<=> },
+              summaries: [
+                {
+                  label: I18n.t('commands.cashflow.expenses'),
+                  prettify: ->(row) { [RVGP.pastel.bold(row[0])] + row[1..].map { |s| RVGP.pastel.red(s) } },
+                  contents: ->(series, data) { sum_column 'Expenses', series, data }
+                },
+                {
+                  label: I18n.t('commands.cashflow.income'),
+                  prettify: ->(row) { [RVGP.pastel.bold(row[0])] + row[1..].map { |s| RVGP.pastel.green(s) } },
+                  contents: ->(series, data) { sum_column 'Income', series, data }
+                },
+                {
+                  label: I18n.t('commands.cashflow.cash_flow'),
+                  prettify: lambda { |row|
+                    [RVGP.pastel.bold(row[0])] + row[1..].map do |cell|
+                      /\$ *-/.match(cell) ? RVGP.pastel.red(cell) : RVGP.pastel.green(cell)
+                    end
+                  },
+                  contents: lambda { |series, data|
+                    %w[Expenses Income].map { |s| sum_column s, series, data }.sum.invert!
+                  }
+                }
+              ] }
+          )
+        end
+      end
+
+      def column_widths
+        # We want every table being displayed, to have the same column widths.
+        # probably we can move most of this code into a Dashboard class method. But, no
+        # rush on that.
+        @column_widths ||= dashboards.map(&:column_data_widths)
+                                     .inject([]) do |sum, widths|
+                                       widths.map.with_index { |w, i| sum[i].nil? || sum[i] < w ? w : sum[i] }
+                                     end
+      end
+
+      def show_columns
+        return @show_columns if @show_columns
+
+        # Now let's calculate how many columns fit on screen:
+        @show_columns = 0
+        0.upto(column_widths.length - 1) do |i|
+          break if RVGP::Dashboard.table_width_given_column_widths(column_widths[0..i]) > TTY::Screen.width
+
+          @show_columns += 1
+        end
+        @show_columns
+      end
+
+      def sum_column(for_series, series, data)
+        # NOTE: This for_series determination is a bit 'magic' and specific to our
+        # current accounting categorization taxonomy
+        0.upto(series.length - 1).map do |i|
+          series[i].split(':')[1] == for_series && data[i] ? data[i] : '$0.00'.to_commodity
+        end.compact.sum
+      end
+    end
+  end
+end

data/lib/rvgp/commands/grid.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RVGP
+  module Commands
+    # @!visibility private
+    # This class contains the handling of the 'grid' command and task. This
+    # code provides the list of grids that are available in the application, and
+    # dispatches requests to build these grids.
+    class Grid < RVGP::Base::Command
+      accepts_options OPTION_ALL, OPTION_LIST
+
+      include RakeTask
+      rake_tasks :grid
+
+      # @!visibility private
+      def execute!(&block)
+        RVGP.app.ensure_build_dir! 'grids'
+        super(&block)
+      end
+
+      # @!visibility private
+      # This class represents a grid, available for building. In addition, the #.all
+      # method, returns the list of available targets.
+      class Target < RVGP::Base::Command::Target
+        # @!visibility private
+        def initialize(grid_klass, starting_at, ending_at)
+          @starting_at = starting_at
+          @ending_at = ending_at
+          @grid_klass = grid_klass
+          super [year, grid_klass.name.tr('_', '-')].join('-'), grid_klass.status_name(year)
+        end
+
+        # @!visibility private
+        def description
+          I18n.t 'commands.grid.target_description', description: @grid_klass.description, year: year
+        end
+
+        # @!visibility private
+        def uptodate?
+          @grid_klass.uptodate? year
+        end
+
+        # @!visibility private
+        def execute(_options)
+          @grid_klass.new(@starting_at, @ending_at).to_file!
+        end
+
+        # @!visibility private
+        def self.all
+          starting_at = RVGP.app.config.grid_starting_at
+          ending_at = RVGP.app.config.grid_ending_at
+
+          starting_at.year.upto(ending_at.year).map do |y|
+            RVGP.grids.classes.map do |klass|
+              new klass,
+                  y == starting_at.year ? starting_at : Date.new(y, 1, 1),
+                  y == ending_at.year ? ending_at : Date.new(y, 12, 31)
+            end
+          end.flatten
+        end
+
+        private
+
+        def year
+          @starting_at.year
+        end
+      end
+    end
+  end
+end

data/lib/rvgp/commands/ireconcile.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+
+module RVGP
+  module Commands
+    # @!visibility private
+    # This class contains the handling of the 'ireconcile' command. Note that
+    # there is no rake integration in this command, as that function is irrelevent
+    # to the notion of an 'export'.
+    class Ireconcile < RVGP::Base::Command
+      accepts_options OPTION_ALL, OPTION_LIST, %i[vsplit v]
+
+      # There's a bug here where we scroll to the top of the file sometimes, on
+      # reload. Not sure what to do about that...
+      # @!visibility private
+      VIMSCRIPT_HEADER = <<-VIMSCRIPT
+        let $LANG='en_US.utf-8'
+
+        function ReloadIfChanged(timer)
+          checktime
+        endfunction
+
+        function ExecuteReconcile()
+          let reconcile_path = expand("%%")
+          let output_path = tempname()
+          let pager = '/bin/less'
+          if len($PAGER) > 0
+            pager = $PAGER
+          endif
+
+          execute('!%<rvgp_path>s reconcile --concise ' .
+            \\ shellescape(reconcile_path, 1) .
+            \\ ' 2>' . shellescape(output_path, 1) .
+            \\ ' > ' . shellescape(output_path, 1))
+          if v:shell_error
+            echoerr "The following error(s) occurred during reconciliation:"
+            execute '!' . pager . ' -r ' . shellescape(output_path, 1)
+            redraw!
+          endif
+          silent execute('!rm '. shellescape(output_path,1))
+        endfunction
+      VIMSCRIPT
+
+      # @!visibility private
+      def initialize(*args)
+        super(*args)
+
+        unless /vim?\Z/.match ENV.fetch('EDITOR')
+          @errors << I18n.t('commands.ireconcile.errors.unsupported_editor', editor: ENV['EDITOR'].inspect)
+        end
+      end
+
+      # @!visibility private
+      def execute!
+        Tempfile.create 'ireconcile.vim' do |file|
+          file.write [format(VIMSCRIPT_HEADER, rvgp_path: $PROGRAM_NAME),
+                      targets.map { |target| target.to_vimscript options[:vsplit] }.join("\ntabnew\n")].join
+
+          file.close
+
+          system [ENV.fetch('EDITOR'), '-S', file.path].join(' ')
+        end
+      end
+
+      # @!visibility private
+      # This class represents a reconciler. See RVGP::Base::Command::ReconcilerTarget, for
+      # most of the logic that this class inherits. Typically, these targets take the form
+      # of "#\\{year}-#\\{reconciler_name}"
+      class Target < RVGP::Base::Command::ReconcilerTarget
+        # @!visibility private
+        VIMSCRIPT_TEMPLATE = <<-VIMSCRIPT
+        edit %<output_file>s
+        setl autoread
+        autocmd VimEnter * let timer=timer_start(1000,'ReloadIfChanged', {'repeat': -1} )
+        call feedkeys("lh")
+        setl nomodifiable
+        %<split>s
+        edit %<input_file>s
+        autocmd BufWritePost * silent call ExecuteReconcile()
+        VIMSCRIPT
+
+        # @!visibility private
+        def to_vimscript(is_vsplit)
+          # NOTE: I guess we don't need to escape these paths, so long as there arent
+          #       any \n's in the path name... I guess
+          format(VIMSCRIPT_TEMPLATE,
+                 output_file: @reconciler.output_file,
+                 input_file: @reconciler.file,
+                 split: is_vsplit ? 'vsplit' : 'split')
+        end
+      end
+    end
+  end
+end