hledger-forecast 3.2.0 → 3.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5acfd1bbab287a58bfe5ce7237576535b6b927d034da9e3651a4c240653e0f33
-  data.tar.gz: 23eb8d2646996b422473440b8f90797215a7390f4d6e2862b470bd361b6d55d5
+  metadata.gz: 0b3fc72db9564b895f8412f6467b3350700b12e7c4cb393ae48d7640ff0766ef
+  data.tar.gz: 78092306250621f6d6e93df98d600035d85960125d40b2df35bd728f1e38cb73
 SHA512:
-  metadata.gz: 62a027f56e0faf7641769b13928ed61c91e3851fe6b1623df00efd233ec244be03c57d7b94ea2605f01580ba18e0a916807a59c6ef848118d9b80fa9a3e8be28
-  data.tar.gz: 470b89a138eff0a2f5da24d4a4fe31ffd7e9584646094665020d19a40a9303877073bfcbc95eb35eae1498149fbfa96b899bd44c5ee4eab4225f26acec9b2e11
+  metadata.gz: c07f7f68ff23714ec25f2708405d4700f8f0df800e07571d805c548598d23775e70b947ba94c74e72c2f9b6064fefdcef2a9d2931fb4d863856c7f0ad1ec14b3
+  data.tar.gz: b00893cc0d8f03f4d7d89c7396d69a8337889a40957b31b572d150eb432fb22a37ca53948106009c33846c49db6499ec90a49a617ab79ce3b29c8b9c20b8b1c2

data/.github/workflows/manually_publish.yml

@@ -0,0 +1,27 @@
+name: Manually Publish
+
+on:
+  workflow_dispatch: {}
+
+jobs:
+  manually_publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+
+      - name: Publish to RubyGems
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+          gem build *.gemspec
+          gem push *.gem
+        env:
+          GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/.github/workflows/release.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+  workflow_dispatch: {}
 
 jobs:
   release:
@@ -19,7 +20,7 @@ jobs:
     steps:
       - name: Release
         id: release
-        uses: googleapis/release-please-action@v4
+        uses: googleapis/release-please-action@v5
         with:
           release-type: ruby
 

data/.gitignore

@@ -19,3 +19,4 @@ pkg/*
 test_output.journal
 todo.md
 .vscode
+/media

data/AGENTS.md

@@ -0,0 +1,27 @@
+# hledger-forecast
+
+This is a RubyGem that enables users to use a CSV file as a forecast. This then feeds into hledger, generating entries into a journal file.
+
+## Code formatting
+
+After editing any Ruby files, run:
+
+```
+rubyfmt spec lib -i
+```
+
+## Tests
+
+Tests can be run with:
+
+```
+rspec
+```
+
+## Non-verbose grouping
+
+In non-verbose mode, `Generator.build_groups` (lib/hledger_forecast/generator.rb) merges CSV rows into a single hledger periodic transaction only when they share `[type, frequency, from, to, account, category]`. Rows with different categories always produce separate `~` entries, even if they share account/date - hledger treats postings within one transaction as linked, so bundling unrelated line items under one transaction misrepresents them in reports (e.g. `hledger register` shows every posting's account against every row, not just the filtered one). When touching grouping logic, check the effect through `hledger reg`/`register`, not just the raw journal text output.
+
+## version.rb
+
+`lib/hledger_forecast/version.rb` is bumped by release automation (release-please), not manually. If it shows as changed after running tests/tooling and you didn't intend a release bump, `git checkout` it rather than committing the bump.

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [3.3.1](https://github.com/olimorris/hledger-forecast/compare/v3.3.0...v3.3.1) (2026-07-28)
+
+
+### Bug Fixes
+
+* stop grouping transactions by category ([#21](https://github.com/olimorris/hledger-forecast/issues/21)) ([2a718ee](https://github.com/olimorris/hledger-forecast/commit/2a718ee506ea6b7e6058f5321351e959e4267f1c))
+
+## [3.3.0](https://github.com/olimorris/hledger-forecast/compare/v3.2.0...v3.3.0) (2026-04-13)
+
+
+### Features
+
+* better errors ([#19](https://github.com/olimorris/hledger-forecast/issues/19)) ([da16ed8](https://github.com/olimorris/hledger-forecast/commit/da16ed8a1fe2398e5af2e0428339b87b25f7691a))
+
 ## [3.2.0](https://github.com/olimorris/hledger-forecast/compare/v3.1.0...v3.2.0) (2026-04-13)
 
 

data/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-<img src="https://github.com/olimorris/hledger-forecast/assets/9512444/5edb77e3-0ec6-4158-9b16-3978c1259879" alt="hledger-forecast" />
+<img src="https://github.com/user-attachments/assets/f8582e29-c4f0-429d-9e3c-358fb719ed35" alt="hledger-forecast" />
 </p>
 
 <h1 align="center">hledger-forecast</h1>
@@ -10,7 +10,7 @@
 <a href="https://github.com/olimorris/hledger-forecast/releases"><img src="https://img.shields.io/github/v/release/olimorris/hledger-forecast?style=for-the-badge"</a>
 </p>
 
-**"Improved", you say?** Using a _CSV_ file, forecasts can be quickly generated into a _journal_ file ready to be fed into [hledger](https://github.com/simonmichael/hledger). **A 16 line [CSV file](https://github.com/olimorris/hledger-forecast/blob/main/example.csv) can generate a 46 line hledger [forecast file](https://github.com/olimorris/hledger-forecast/blob/main/example.journal)!**
+Using a _CSV_ file, forecasts can be quickly generated into a _journal_ file ready to be fed into [hledger](https://github.com/simonmichael/hledger). **A 16 line [CSV file](https://github.com/olimorris/hledger-forecast/blob/main/example.csv) can generate a 46 line hledger [forecast file](https://github.com/olimorris/hledger-forecast/blob/main/example.journal)!**
 
 ## :sparkles: Features
 
@@ -25,7 +25,7 @@
 
 Forecasting is essential to how I plan and budget with hledger. It enables me to know my financial position in 1 month, 10 months or even 100 months from now.
 
-But forecasting in hledger is verbose and unintelligent. Consider this scenario: you purchase a new $3,000 laptop on a 0% finance deal and spread it over 20 months. In hledger, this would be accounted for with:
+But forecasting in hledger is verbose and manual. Consider this scenario: you purchase a new $3,000 laptop on a 0% finance deal and spread it over 20 months. In hledger, this would be accounted for with:
 
 ```ledger
 ~ monthly from 2026-01-01 to 2027-08-31  * New Laptop

data/lib/hledger_forecast/calculator.rb

@@ -5,7 +5,10 @@ module HledgerForecast
     def self.evaluate(amount)
       return amount.to_f unless amount.is_a?(String)
 
-      @calc.evaluate(amount.slice(1..-1))
+      result = @calc.evaluate(amount.slice(1..-1))
+      raise ArgumentError, "invalid amount '#{amount}'" if result.nil?
+
+      result
     end
 
     def self.evaluate_from_date(value)

data/lib/hledger_forecast/cli.rb

@@ -283,7 +283,12 @@ module HledgerForecast
       config = File.read(options[:forecast_file])
       config = HledgerForecast::CSVParser.parse(config) if options[:file_type] == "csv"
 
-      summarizer = Summarizer.summarize(config, options)
+      begin
+        summarizer = Summarizer.summarize(config, options)
+      rescue StandardError => e
+        puts("An error occurred while summarizing transactions: #{e.message}")
+        exit(1)
+      end
 
       puts(SummarizerFormatter.format(summarizer[:output], summarizer[:settings]))
     end

data/lib/hledger_forecast/forecast.rb

@@ -11,7 +11,15 @@ module HledgerForecast
       )
 
       settings = Settings.parse(rows.select { |r| r[:type] == "settings" }, cli_options)
-      transactions = rows.reject { |r| r[:type] == "settings" }.map { |r| Transaction.from_row(r) }
+
+      transactions = []
+      rows.each_with_index do |r, i|
+        next if r[:type] == "settings"
+
+        transactions << Transaction.from_row(r)
+      rescue StandardError => e
+        raise "CSV row #{i + 2}: #{e.message}"
+      end
 
       new(transactions, settings, rows.headers.include?(:tag))
     end

data/lib/hledger_forecast/generator.rb

@@ -26,7 +26,7 @@ module HledgerForecast
         end
       else
         transactions
-          .group_by { |t| [t.type, t.frequency, t.from, t.to, t.account] }
+          .group_by { |t| [t.type, t.frequency, t.from, t.to, t.account, t.category] }
           .map do |(type, frequency, from, to, account), txns|
             TransactionGroup.new(
               type: type,

data/lib/hledger_forecast/transaction.rb

@@ -24,6 +24,8 @@ module HledgerForecast
     keyword_init: true
   ) do
     def self.from_row(row)
+      validate_required_fields!(row)
+
       from = Calculator.evaluate_from_date(row[:from])
       new(
         type: row[:type],
@@ -64,6 +66,15 @@ module HledgerForecast
     end
 
     def summary_exclude? = !!summary_exclude
+
+    def self.validate_required_fields!(row)
+      %i[type account from category amount].each do |field|
+        next unless row[field].nil? || row[field].to_s.strip.empty?
+
+        hint = row[:description] ? " (description: '#{row[:description]}')" : ""
+        raise ArgumentError, "missing required field '#{field}'#{hint}"
+      end
+    end
   end
 
   TransactionGroup = Struct.new(:type, :frequency, :account, :from, :to, :transactions, keyword_init: true)

data/lib/hledger_forecast/version.rb

@@ -1,3 +1,3 @@
 module HledgerForecast
-  VERSION = "3.2.0"
+  VERSION = "3.3.1"
 end

data/spec/cli_spec.rb

@@ -1,8 +1,11 @@
 require_relative "../lib/hledger_forecast"
 
 output = <<~JOURNAL
-  ~ monthly from 2023-03-01  * Mortgage, Food
+  ~ monthly from 2023-03-01  * Mortgage
       Expenses:Mortgage    £2,000.55
+      Assets:Bank
+
+  ~ monthly from 2023-03-01  * Food
       Expenses:Food        £100.00
       Assets:Bank
 

data/spec/computed_amounts_spec.rb

@@ -9,8 +9,11 @@ config = <<~CSV
 CSV
 
 output = <<~JOURNAL
-  ~ monthly from 2023-05-01  * New kitchen, Monthly food shop, Random food
+  ~ monthly from 2023-05-01  * New kitchen
       Expenses:House    £208.33
+      Liabilities:Amex
+
+  ~ monthly from 2023-05-01  * Monthly food shop, Random food
       Expenses:Food     £107.50
       Expenses:Food     £52.88
       Liabilities:Amex

data/spec/monthly_end_date_spec.rb

@@ -8,8 +8,11 @@ config = <<~CSV
 CSV
 
 output = <<~JOURNAL
-  ~ monthly from 2023-03-01 to 2023-06-01  * Mortgage, Food
+  ~ monthly from 2023-03-01 to 2023-06-01  * Mortgage
       Expenses:Mortgage    £2,000.00
+      Assets:Bank
+
+  ~ monthly from 2023-03-01 to 2023-06-01  * Food
       Expenses:Food        £100.00
       Assets:Bank
 

data/spec/monthly_spec.rb

@@ -9,9 +9,15 @@ config = <<~CSV
 CSV
 
 output = <<~JOURNAL
-  ~ monthly from 2023-03-01  * Bills, Food, Savings
+  ~ monthly from 2023-03-01  * Bills
       Expenses:Bills    £175.00
+      Assets:Bank
+
+  ~ monthly from 2023-03-01  * Food
       Expenses:Food     £500.00
+      Assets:Bank
+
+  ~ monthly from 2023-03-01  * Savings
       Assets:Savings    £-1,000.00
       Assets:Bank
 

data/spec/tags_spec.rb

@@ -18,9 +18,15 @@ CSV
 RSpec.describe "tags" do
   it "outputs hledger tags in posting comments" do
     expected = <<~JOURNAL
-      ~ monthly from 2023-03-01  * Salary, Food, Netflix
+      ~ monthly from 2023-03-01  * Salary
           Income:Salary             £-3,500.00;  fixed:, essential:
+          Assets:Bank
+
+      ~ monthly from 2023-03-01  * Food
           Expenses:Food             £500.00   ;  living:, essential:
+          Assets:Bank
+
+      ~ monthly from 2023-03-01  * Netflix
           Expenses:Subscriptions    £15.00    ;  living:
           Assets:Bank
 
@@ -31,8 +37,11 @@ RSpec.describe "tags" do
 
   it "omits comments when no tags are present" do
     expected = <<~JOURNAL
-      ~ monthly from 2023-03-01  * Salary, Food
+      ~ monthly from 2023-03-01  * Salary
           Income:Salary    £-3,500.00
+          Assets:Bank
+
+      ~ monthly from 2023-03-01  * Food
           Expenses:Food    £500.00
           Assets:Bank
 
@@ -43,8 +52,11 @@ RSpec.describe "tags" do
 
   it "filters transactions by a single tag" do
     expected = <<~JOURNAL
-      ~ monthly from 2023-03-01  * Food, Netflix
+      ~ monthly from 2023-03-01  * Food
           Expenses:Food             £500.00;  living:, essential:
+          Assets:Bank
+
+      ~ monthly from 2023-03-01  * Netflix
           Expenses:Subscriptions    £15.00 ;  living:
           Assets:Bank
 
@@ -55,8 +67,11 @@ RSpec.describe "tags" do
 
   it "filters transactions by multiple tags (OR logic)" do
     expected = <<~JOURNAL
-      ~ monthly from 2023-03-01  * Salary, Food
+      ~ monthly from 2023-03-01  * Salary
           Income:Salary    £-3,500.00;  fixed:, essential:
+          Assets:Bank
+
+      ~ monthly from 2023-03-01  * Food
           Expenses:Food    £500.00   ;  living:, essential:
           Assets:Bank
 
@@ -81,8 +96,11 @@ RSpec.describe "tags" do
 
   it "excludes tags in generator output" do
     expected = <<~JOURNAL
-      ~ monthly from 2023-03-01  * Food, Netflix
+      ~ monthly from 2023-03-01  * Food
           Expenses:Food             £500.00;  living:, essential:
+          Assets:Bank
+
+      ~ monthly from 2023-03-01  * Netflix
           Expenses:Subscriptions    £15.00 ;  living:
           Assets:Bank
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hledger-forecast
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.3.1
 platform: ruby
 authors:
 - Oli Morris
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-13 00:00:00.000000000 Z
+date: 2026-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: abbrev
@@ -132,10 +132,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yml"
+- ".github/workflows/manually_publish.yml"
 - ".github/workflows/release.yml"
 - ".gitignore"
 - ".mise.toml"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - Gemfile
 - LICENSE