hledger-forecast 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e605f8a4436c2b52e4b37e06aec308ef70d0fb4a7572d0791820c73ddafeaa1f
+  data.tar.gz: f62dc41d637ea7107ec282b41d61ed0040c3fc3f4b84ec139a1711cf09f94af5
+SHA512:
+  metadata.gz: b44389e7cc8ee05d8f6d35a0a649e11d96c2bcc3149f5b2ccf92c563db206dae54ee65a39eb9982f9c9e0dc16688ca42ef012e95aa38b99c9ef378f0ab57d3f9
+  data.tar.gz: 5d64a7679916fa88216dc7daf3a4fc3607002114b025925d4e65e84c1c0a6b4243c1f389d7cb8ca0ba28209c6736ed9cf1ec5c8bcf3ddd264949d6be387f321a

data/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: Continuous Integration
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version:
+          - 3.1.2
+          - 3.0
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Update package
+        run: sudo apt-get update
+      - name: Install packages
+        run: sudo apt-get -y install ledger hledger
+      - name: Set up Ruby
+        # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+        # change this to (see https://github.com/ruby/setup-ruby#versioning):
+        uses: ruby/setup-ruby@v1
+        # uses: ruby/setup-ruby@473e4d8fe5dd94ee328fdfca9f8c9c7afc9dae5e
+        with:
+          bundler-cache: true # runs 'bundle install' and caches installed gems
+          ruby-version: ${{ matrix.ruby-version }}
+      - name: Run tests
+        run: rspec

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+*.journal
+forecast.yml
+todo.md

data/.rubocop.yml

@@ -0,0 +1,20 @@
+Layout/LineLength:
+  Max: 120
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/RedundantReturn:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: False
+
+Metrics/MethodLength:
+  Enabled: False
+
+Metrics/AbcSize:
+  Enabled: False
+
+Style/NumericPredicate:
+  Enabled: False

data/.ruby-version

@@ -0,0 +1 @@
+3.0.0

data/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem 'money'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,41 @@
+PATH
+  remote: .
+  specs:
+    hledger-forecast (0.1.0)
+      highline (~> 2.1.0)
+      money (~> 6.16.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    concurrent-ruby (1.2.2)
+    diff-lcs (1.5.0)
+    highline (2.1.0)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    money (6.16.0)
+      i18n (>= 0.6.4, <= 2)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.1)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+
+PLATFORMS
+  arm64-darwin-21
+
+DEPENDENCIES
+  hledger-forecast!
+  money
+  rspec (~> 3.12)
+
+BUNDLED WITH
+   2.4.10

data/LICENSE

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

data/README.md

@@ -0,0 +1,119 @@
+# Hledger-Forecast
+
+![Tests](https://github.com/olimorris/hledger-forecast/workflows/ci/badge.svg)
+
+> **Warning**: This is still in the early stages of development and the API is likely to change
+
+Uses a YAML file to generate monthly, quarterly, yearly and one-off transactions for better forecasting in [Hledger](https://github.com/simonmichael/hledger).
+
+See the [rationale](#brain-rationale) section for why this gem may be useful to you.
+
+## :sparkles: Features
+
+- :book: Uses a simple YAML config file to generate periodic transactions
+- :date: Specify start and end dates for forecasts
+- :heavy_dollar_sign: Full currency support (uses the [RubyMoney](https://github.com/RubyMoney/money) gem)
+- :computer: Simple and easy to use CLI
+
+## :package: Installation
+
+Assuming you have Ruby and [Rubygems](http://rubygems.org/pages/download) installed on your system, simply run:
+
+    gem install --user hledger-forecast
+
+## :rocket: Usage
+
+Simply run:
+
+    hledger-forecast
+
+Running `hledger-forecast -h` shows the available options:
+
+    Usage: Hledger-Forecast [options]
+
+        -f, --forecast FILE              The FORECAST yaml file to generate from
+        -t, --transaction FILE           The base TRANSACTIONS file to extend from
+        -o, --output-file FILE           The OUTPUT file to create
+        -s, --start-date DATE            The date to start generating from (yyyy-mm-dd)
+        -e, --end-date DATE              The date to start generating to (yyyy-mm-dd)
+        -h, --help                       Show this message
+            --version                    Show version
+
+To then include in Hledger:
+
+    hledger -f transactions.journal -f forecast.journal
+
+where `transactions.journal` might be your bank transactions (your "actuals") and `forecast.journal` is the file generated with the `-o` option from above (your "forecast").
+
+### A simple config file
+
+Firstly, create a `yml` file which will contain the transactions you'd like to forecast:
+
+```yaml
+# forecast.yml
+monthly:
+  - account: "[Assets:Bank]"
+    start: "2023-03-01"
+    transactions:
+      - amount: 2000
+        category: "[Expenses:Mortgage]"
+        description: Mortgage
+      - amount: 500
+        category: "[Expenses:Food]"
+        description: Food
+```
+
+Let's examine what's going on in this config file:
+
+- Firstly, we're telling the app to create two monthly transactions and repeat them, forever, starting from March 2023. In this case, forever will be the `end_date` specified when running the app
+- If you ran the app with `hledger-forecast -s 2023-04-01` then no transactions would be generated for March as the start date is greater than the periodic start date
+- Notice we're also using [virtual postings](https://hledger.org/1.29/hledger.html#virtual-postings) (designated by the brackets) to be explicit to Hledger. This also makes it easy to filter them out with the `-R` or `--real` option in Hledger
+- We also have not specified a currency; the default (`USD`) will be used
+
+### Extending the config file
+
+#### Periods
+
+If you'd like to add quarterly, yearly or one-off transactions, use the following keys:
+
+- `quarterly`
+- `yearly`
+- `once`
+
+The structure of the config file remains exactly the same.
+
+> **Note**: A quarterly transaction will repeat for every 3 months from the start date
+
+#### Currency
+
+To specify a currency:
+
+```yaml
+# forecast.yml
+settings:
+  currency: GBP
+```
+
+#### Additional settings
+
+Additional settings in the config file:
+
+```yaml
+# forecast.yml
+settings:
+  show_symbol: true             # Show the currency symbol?
+  sign_before_symbol: true      # Show the negative sign before the symbol?
+  thousands_separator: true     # Separate thousands with a comma?
+```
+
+## :brain: Rationale
+
+Firstly, I've come to realise from reading countless blog and Reddit posts on [plain text accounting](https://plaintextaccounting.org), that everyone does it __completely__ differently!
+
+My days working in financial modelling have meant that a big macro-enabled spreadsheet was my go-to tool. Growing tired with the manual approach of importing transactions, heavily manipulating them, watching Excel become increasingly slower lead me to PTA. It's been a wonderful discovery.
+
+One of the aspects of my previous approach to personal finance that I liked was the monthly recap of my performance and the looking ahead to the future. Am I still on track to hit my year-end savings goal? Am I still on track to hit my savings goal for 12, 24 months time? It was at this point in my shift to PTA that I hit a wall.
+
+While Hledger provides support for [forecasting](https://hledger.org/1.29/hledger.html#forecasting) using periodic transactions, these are computed virtually at runtime. If I notice a big difference in my forecasted year-end balance compared to what I'm expecting, I want to investigate and start reconcilling. Computed transactions make this difficult and tiresome.
+
+With this gem, my aim was to make it easy for users to change a config file, re-run a CLI command and be able to open a text file and see the changes. No guesswork. No surprises.

data/bin/hledger-forecast

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/hledger_forecast'
+# require 'hledger_forecast'
+
+begin
+  options = HledgerForecast::Options.parse_command_line_options
+rescue RuntimeError => e
+  puts("ERROR: #{e}")
+  exit(1)
+end
+
+HledgerForecast::Command.run(options)

data/example.yaml

@@ -0,0 +1,26 @@
+monthly:
+  - date: "2023-03-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: Mortgage
+        category: "[Expenses:Mortgage]"
+        amount: £1,000.00
+      - description: Food
+        category: "[Expenses:Food]"
+        amount: £500.00
+
+quarterly:
+  - date: "2023-04-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: Bonus
+        category: "[Income:Bonus]"
+        amount: -£1,000.00
+
+yearly:
+  - date: "2023-04-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: Annual Bonus
+        category: "[Income:Bonus]"
+        amount: -£2,000.00

data/hledger-forecast.gemspec

@@ -0,0 +1,25 @@
+require 'hledger_forecast/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'hledger-forecast'
+  s.version     = HledgerForecast::VERSION
+  s.authors     = ['Oli Morris']
+  s.summary     = 'Utility to generate forecasts in Hledger'
+  s.description = 'Uses a YAML file to generate monthly, quarterly, yearly and one-off transactions for better forecasting in Hledger'
+  s.email       = 'olimorris@users.noreply.github.com'
+  s.homepage    = 'https://github.com/olimorris/hledger-forecast'
+  s.license     = 'MIT'
+
+  s.required_ruby_version = '>= 3.0.0'
+
+  s.add_dependency "highline", "~> 2.1.0"
+  s.add_dependency "money", "~> 6.16.0"
+  s.add_development_dependency 'rspec', '~> 3.12'
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- spec/*`.split("\n")
+  s.executables = `git ls-files -- bin/*`.split("\n").map do |f|
+    File.basename(f)
+  end
+  s.require_paths = ['lib']
+end

data/lib/hledger_forecast/command.rb

@@ -0,0 +1,30 @@
+module HledgerForecast
+  class Command
+    def self.run(args)
+      end_date = args[:end_date]
+      start_date = args[:start_date]
+      forecast = File.read(args[:forecast_file])
+      transactions = args[:transactions_file] ? File.read(args[:transactions_file]) : nil
+
+      puts "[Using default dates: #{start_date} to #{end_date}]" if args[:default_dates]
+
+      transactions = Generator.create_journal_entries(transactions, forecast, start_date, end_date)
+
+      output_file = args[:output_file]
+      if File.exist?(output_file)
+        print "File '#{output_file}' already exists. Overwrite? (y/n): "
+        overwrite = gets.chomp.downcase
+
+        if overwrite == 'y'
+          File.write(output_file, transactions)
+          puts "File '#{output_file}' has been overwritten."
+        else
+          puts "Operation aborted. File '#{output_file}' was not overwritten."
+        end
+      else
+        File.write(output_file, transactions)
+        puts "File '#{output_file}' has been created."
+      end
+    end
+  end
+end

data/lib/hledger_forecast/generator.rb

@@ -0,0 +1,93 @@
+module HledgerForecast
+  # Generates journal entries based on a YAML forecast file.
+  # on forecast data and optional existing transactions.
+  #
+  class Generator
+    class << self
+      attr_accessor :settings
+    end
+
+    self.settings = {}
+
+    def self.configure_settings(forecast_data)
+      @settings[:currency] = Money::Currency.new(forecast_data.fetch('settings', {}).fetch('currency', 'USD'))
+      @settings[:show_symbol] = forecast_data.fetch('settings', {}).fetch('show_symbol', true)
+      @settings[:sign_before_symbol] = forecast_data.fetch('settings', {}).fetch('sign_before_symbol', true)
+      @settings[:thousands_separator] = forecast_data.fetch('settings', {}).fetch('thousands_separator', true)
+    end
+
+    def self.write_transactions(output, date, account, transaction)
+      output.concat("#{date} * #{transaction['description']}\n")
+      output.concat("    #{transaction['category']}                #{transaction['amount']}\n")
+      output.concat("    #{account}\n\n")
+    end
+
+    def self.format_transaction(transaction)
+      formatted_transaction = transaction.clone
+
+      formatted_transaction['amount'] =
+        Money.from_cents(formatted_transaction['amount'].to_i * 100, @settings[:currency]).format(
+          symbol: @settings[:show_symbol],
+          sign_before_symbol: @settings[:sign_before_symbol],
+          thousands_separator: @settings[:thousands_separator] ? ',' : nil
+        )
+
+      formatted_transaction
+    end
+
+    def self.process_forecast(output_file, forecast_data, type, date)
+      forecast_data[type]&.each do |forecast|
+        start_date = Date.parse(forecast['start'])
+        end_date = forecast['end'] ? Date.parse(forecast['end']) : nil
+        account = forecast['account']
+
+        next if end_date && date > end_date
+
+        date_matches = case type
+                       when 'monthly'
+                         date.day == start_date.day
+                       when 'quarterly'
+                         date.day == start_date.day && date.month % 3 == start_date.month % 3
+                       when 'yearly'
+                         date.day == start_date.day && date.month == start_date.month
+                       when 'once'
+                         date == start_date
+                       end
+
+        if date_matches
+          forecast['transactions'].each do |transaction|
+            end_date = transaction['end'] ? Date.parse(transaction['end']) : nil
+
+            next unless end_date.nil? || date <= end_date
+
+            write_transactions(output_file, date, account, format_transaction(transaction))
+          end
+        end
+      end
+    end
+
+    def self.create_journal_entries(transactions, forecast, start_date, end_date)
+      start_date = Date.parse(start_date)
+      end_date = Date.parse(end_date)
+      forecast_data = YAML.safe_load(forecast)
+
+      configure_settings(forecast_data)
+
+      output = ''
+      output.concat(transactions) if transactions
+
+      date = start_date
+
+      while date <= end_date
+        process_forecast(output, forecast_data, 'monthly', date)
+        process_forecast(output, forecast_data, 'quarterly', date)
+        process_forecast(output, forecast_data, 'yearly', date)
+        process_forecast(output, forecast_data, 'once', date)
+
+        date = date.next_day
+      end
+
+      output
+    end
+  end
+end

data/lib/hledger_forecast/options.rb

@@ -0,0 +1,67 @@
+module HledgerForecast
+  class Options
+    def self.parse_command_line_options(args = ARGV, _stdin = $stdin)
+      cli = HighLine.new
+      options = {}
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: Hledger-Forecast [options]"
+        opts.separator ""
+
+        opts.on("-f", "--forecast FILE",
+                "The FORECAST yaml file to generate from") do |file|
+          options[:forecast_file] = file
+        end
+
+        opts.on("-t", "--transaction FILE",
+                "The base TRANSACTIONS file to extend from") do |file|
+          options[:transactions_file] = file if file && !file.empty?
+        end
+
+        opts.on("-o", "--output-file FILE",
+                "The OUTPUT file to create") do |file|
+          options[:output_file] = file
+        end
+
+        opts.on("-s", "--start-date DATE",
+                "The date to start generating from (yyyy-mm-dd)") do |a|
+          options[:start_date] = a
+        end
+
+        opts.on("-e", "--end-date DATE",
+                "The date to start generating to (yyyy-mm-dd)") do |a|
+          options[:end_date] = a
+        end
+
+        opts.on_tail("-h", "--help", "Show this message") do
+          puts opts
+          exit
+        end
+
+        opts.on_tail("--version", "Show version") do
+          puts VERSION
+          exit
+        end
+
+        opts.parse!(args)
+      end
+
+      options[:forecast_file] = "forecast.yml" unless options[:forecast_file]
+      options[:output_file] = "forecast.journal" unless options[:output_file]
+
+      today = Date.today
+
+      unless options[:start_date]
+        options[:default_dates] = true
+        options[:start_date] =
+          Date.new(today.year, today.month, 1).next_month.to_s
+      end
+      unless options[:end_date]
+        options[:default_dates] = true
+        options[:end_date] = Date.new(today.year + 3, 12, 31).to_s
+      end
+
+      return options
+    end
+  end
+end

data/lib/hledger_forecast/version.rb

@@ -0,0 +1,3 @@
+module HledgerForecast
+  VERSION = "0.1.0"
+end

data/lib/hledger_forecast.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'date'
+require 'highline'
+require 'money'
+require 'optparse'
+require 'yaml'
+
+Money.locale_backend = nil
+Money.rounding_mode = BigDecimal::ROUND_HALF_UP
+
+require_relative 'hledger_forecast/version'
+require_relative 'hledger_forecast/options'
+require_relative 'hledger_forecast/generator'
+require_relative 'hledger_forecast/command'

data/spec/monthly_spec.rb

@@ -0,0 +1,33 @@
+require_relative '../lib/hledger_forecast'
+
+RSpec.describe 'generate' do
+  it 'generates a forecast with correct MONTHLY transactions' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/monthly/forecast_monthly.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2023-05-30')
+
+    expected_output = File.read('spec/stubs/monthly/output_monthly.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+
+  it 'generates a forecast with correct MONTHLY transactions that have an end date' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/monthly/forecast_monthly_enddate.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2023-08-30')
+
+    expected_output = File.read('spec/stubs/monthly/output_monthly_enddate.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+
+  it 'generates a forecast with correct MONTHLY transactions that have an end date, at the top level' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/monthly/forecast_monthly_enddate_top.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2023-08-30')
+
+    expected_output = File.read('spec/stubs/monthly/output_monthly_enddate_top.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+end

data/spec/once_spec.rb

@@ -0,0 +1,13 @@
+require_relative '../lib/hledger_forecast'
+
+RSpec.describe 'generate' do
+  it 'generates a forecast with correct ONCE transactions' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/once/forecast_once.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2024-04-30')
+
+    expected_output = File.read('spec/stubs/once/output_once.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+end

data/spec/quarterly_spec.rb

@@ -0,0 +1,13 @@
+require_relative '../lib/hledger_forecast'
+
+RSpec.describe 'generate' do
+  it 'generates a forecast with correct QUARTERLY transactions' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/quarterly/forecast_quarterly.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2023-10-30')
+
+    expected_output = File.read('spec/stubs/quarterly/output_quarterly.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+end

data/spec/stubs/monthly/forecast_monthly.yml

@@ -0,0 +1,13 @@
+monthly:
+  - account: "[Assets:Bank]"
+    start: "2023-03-01"
+    transactions:
+      - amount: 2000
+        category: "[Expenses:Mortgage]"
+        description: Mortgage
+      - amount: 100
+        category: "[Expenses:Food]"
+        description: Food
+
+settings:
+  currency: GBP

data/spec/stubs/monthly/forecast_monthly_enddate.yml

@@ -0,0 +1,14 @@
+settings:
+  currency: GBP
+
+monthly:
+  - start: "2023-03-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: Mortgage
+        end: "2023-06-01"
+        category: "[Expenses:Mortgage]"
+        amount: 2,000.00
+      - description: Food
+        category: "[Expenses:Food]"
+        amount: 100.00

data/spec/stubs/monthly/forecast_monthly_enddate_top.yml

@@ -0,0 +1,14 @@
+settings:
+  currency: GBP
+
+monthly:
+  - start: "2023-03-01"
+    end: "2023-06-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: Mortgage
+        category: "[Expenses:Mortgage]"
+        amount: 2,000.00
+      - description: Food
+        category: "[Expenses:Food]"
+        amount: 100.00

data/spec/stubs/monthly/forecast_monthly_modifier.yml

@@ -0,0 +1,11 @@
+settings:
+  currency: GBP
+
+monthly:
+  - start: "2023-03-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: Mortgage
+        category: "[Expenses:Mortgage]"
+        amount: 2,000.00
+        modifier: 1.1x

data/spec/stubs/once/forecast_once.yml

@@ -0,0 +1,10 @@
+settings:
+  currency: GBP
+
+once:
+  - start: "2023-07-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: New Kitchen
+        category: "[Expense:House]"
+        amount: 5,000.00

data/spec/stubs/quarterly/forecast_quarterly.yml

@@ -0,0 +1,10 @@
+settings:
+  currency: GBP
+
+quarterly:
+  - start: "2023-04-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: Bonus
+        category: "[Income:Bonus]"
+        amount: -1,000.00

data/spec/stubs/transactions.journal

@@ -0,0 +1,8 @@
+2023-02-01 * Opening balance
+    Assets:Bank                             £1,000.00
+    Equity:Opening balance
+
+2023-02-05 * Mortgage payment
+    Expenses:Mortgage                 £1,500.00
+    Assets:Bank
+

data/spec/stubs/yearly/forecast_yearly.yml

@@ -0,0 +1,10 @@
+settings:
+  currency: GBP
+
+yearly:
+  - start: "2023-04-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: Bonus
+        category: "[Income:Bonus]"
+        amount: -3,000.00

data/spec/yearly_spec.rb

@@ -0,0 +1,13 @@
+require_relative '../lib/hledger_forecast'
+
+RSpec.describe 'generate' do
+  it 'generates a forecast with correct YEARLY transactions' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/yearly/forecast_yearly.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2024-04-30')
+
+    expected_output = File.read('spec/stubs/yearly/output_yearly.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: hledger-forecast
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Oli Morris
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-04-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: highline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+- !ruby/object:Gem::Dependency
+  name: money
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.16.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.16.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: Uses a YAML file to generate monthly, quarterly, yearly and one-off transactions
+  for better forecasting in Hledger
+email: olimorris@users.noreply.github.com
+executables:
+- hledger-forecast
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- bin/hledger-forecast
+- example.yaml
+- hledger-forecast.gemspec
+- lib/hledger_forecast.rb
+- lib/hledger_forecast/command.rb
+- lib/hledger_forecast/generator.rb
+- lib/hledger_forecast/options.rb
+- lib/hledger_forecast/version.rb
+- spec/monthly_spec.rb
+- spec/once_spec.rb
+- spec/quarterly_spec.rb
+- spec/stubs/monthly/forecast_monthly.yml
+- spec/stubs/monthly/forecast_monthly_enddate.yml
+- spec/stubs/monthly/forecast_monthly_enddate_top.yml
+- spec/stubs/monthly/forecast_monthly_modifier.yml
+- spec/stubs/once/forecast_once.yml
+- spec/stubs/quarterly/forecast_quarterly.yml
+- spec/stubs/transactions.journal
+- spec/stubs/yearly/forecast_yearly.yml
+- spec/yearly_spec.rb
+homepage: https://github.com/olimorris/hledger-forecast
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Utility to generate forecasts in Hledger
+test_files:
+- spec/monthly_spec.rb
+- spec/once_spec.rb
+- spec/quarterly_spec.rb
+- spec/stubs/monthly/forecast_monthly.yml
+- spec/stubs/monthly/forecast_monthly_enddate.yml
+- spec/stubs/monthly/forecast_monthly_enddate_top.yml
+- spec/stubs/monthly/forecast_monthly_modifier.yml
+- spec/stubs/once/forecast_once.yml
+- spec/stubs/quarterly/forecast_quarterly.yml
+- spec/stubs/transactions.journal
+- spec/stubs/yearly/forecast_yearly.yml
+- spec/yearly_spec.rb