hledger-forecast 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eb9b09e3db9215ef7d720dcc843f6bf5302e8be64bffd3f6eceeb11b12f9aef
-  data.tar.gz: 41c0bf21e983a5962e0014ee98f65426ad1aebfda891925de98155b9b81db4f0
+  metadata.gz: e8f490f679ec154468837d25878ef658fd0225d73cdd30f291679475e247d00f
+  data.tar.gz: bcc7247a985c775b2b053c43d25f4e5269ed224ee6f396afdaa4339f6ddf4c52
 SHA512:
-  metadata.gz: fe6a4be8caf044b76fe6d74a0a260c42811a060c4bfc0af47c836cb9d0881e898f3c50a6256879d6db647abba08f75d7ed974be0bc4c2d42531e12bdbd04f370
-  data.tar.gz: 461a631a0ec8b6e8d72fcb99a6a688c485a5c6e1aeae27e34c435287b54cbef37a2047f89598f6455c130889af1f0ae8bf954693ab076abdb331a8b395ea77e3
+  metadata.gz: 0cf0966195c657ec869ecf442031c1d9a1e71dca2ebff8544efeb1fda027945a2ed3cbd280241148cfff276fc01fc08878a25f93876ba4c0e71ada81dae67b4c
+  data.tar.gz: 24de22a18a04df4041401495776267beeae94e5eb3e3ee95362b81216cf48e64f484d70bcad441751c63dc74d12400cdd601cbac5ed56f7958c266f43933af02

data/.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
         ruby-version: ['3.3', '3.4']
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Update packages 📦️
         run: sudo apt-get update

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@v7
+
+      - 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,9 +20,10 @@ jobs:
     steps:
       - name: Release
         id: release
-        uses: googleapis/release-please-action@v4
+        uses: googleapis/release-please-action@v5
         with:
-          release-type: ruby
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
 
   publish:
     runs-on: ubuntu-latest
@@ -29,7 +31,7 @@ jobs:
     if: needs.release.outputs.release_created == 'true'
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/.gitignore

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

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "3.4.0"
+}

data/AGENTS.md

@@ -0,0 +1,29 @@
+# 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.
+
+The bump comes from the release PR, driven by `release-please-config.json`. Two settings there are load-bearing: `version-file` points at `version.rb`, and `package-name` is the gem name the `Gemfile.lock` updater matches on. Without them release-please writes only `CHANGELOG.md`, and because the gemspec reads `HledgerForecast::VERSION`, the publish job then pushes the previous version and RubyGems rejects it as a duplicate. Do not add a `release-type` input to `.github/workflows/release.yml` - it switches the action to standalone mode, which ignores the config file entirely.

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [3.4.0](https://github.com/olimorris/hledger-forecast/compare/v3.3.1...v3.4.0) (2026-09-02)
+
+
+### Features
+
+* better summarisation ([#28](https://github.com/olimorris/hledger-forecast/issues/28)) ([619291d](https://github.com/olimorris/hledger-forecast/commit/619291d61bcb0aeb442edff4dd4bd382295629ab))
+
+## [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)
 
 

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
@@ -107,9 +107,9 @@ This will generate a forecast up to the end of Feb 2027, showing asset balances
 
 > **Tip:** If you use `hledger-ui`, the `--verbose` flag is worth using. It keeps each transaction as its own entry in the journal, making descriptions much easier to read in the UI.
 
-### Summarize
+### Summarise
 
-As your forecast grows, it's useful to see the totals at a glance. Think of this as your income statement, rolled up to whatever period makes sense.
+It can be useful to summarise the entirety of your forecast into a profit and loss statement, rolling up periodic transactions accordingly. This is a great way of being able to see your monthly or yearly profit/loss. .
 
     hledger-forecast summarize -f my_forecast.csv
 
@@ -120,8 +120,45 @@ As your forecast grows, it's useful to see the totals at a glance. Think of this
                                        [yearly], [half-yearly], [quarterly], [monthly], [weekly], [daily]
       -t, --tags TAGS                  Only include transactions with given tags (comma-separated)
       -v, --verbose                    Show additional information in the summary
+          --from DATE                  Only include transactions still running from a given DATE,
+                                       e.g. "Sep 2027", "2027-09" or "01/09/2027"
+          --exclude-once               Exclude one-off transactions from the summary
+      -e, --export FILE                Also write the summary to a CSV FILE
+          --force                      Force an overwrite of the exported file
       -h, --help                       Show this help message
 
+**Scoping** - one-off purchases can distort the overall summary, since a `once` row is counted at its full value alongside your recurring commitments. They can be excluded with `--exclude-once`:
+
+```bash
+hledger-forecast summarize -f forecast.csv --exclude-once
+```
+
+You can use the `--from` flag to enable questions like _"what does my P&L look like at this point in the future?"_. Anything that has finished by then - a mortgage with a `to` date in 2025, a one-off purchase in 2023 - is left out:
+
+```bash
+hledger-forecast summarize -f forecast.csv --from="Sep 2027"
+```
+
+You can also scope for specific tags:
+
+```bash
+hledger-forecast summarize -f forecast.csv --tags=fixed
+```
+
+The above would only show transactions that have been permanently tagged as `fixed` in the CSV file.
+
+```bash
+hledger-forecast summarize -f forecast.csv --tags=-periodic
+```
+
+Whereas the above would show everything _except_ transactions tagged as `periodic`.
+
+**Exporting** - `--export` writes the summary to a CSV file as well as printing the table:
+
+```bash
+hledger-forecast summarize -f forecast.csv --export summary.csv
+```
+
 ### Compare
 
 A core part of managing personal finances is comparing what you _expected_ to happen with what _actually_ happened. The `compare` command makes this easy:

data/lib/hledger_forecast/calculator.rb

@@ -22,6 +22,17 @@ module HledgerForecast
       date >> @calc.evaluate(offset_expr).to_i
     end
 
+    # Parses a user-supplied date such as "Sep 2027", "2027-09" or "01/09/2027"
+    def self.parse_date(value)
+      value = value.to_s.strip
+      value = "#{value}-01" if value.match?(/\A\d{4}-\d{1,2}\z/)
+      value = "#{value}-01-01" if value.match?(/\A\d{4}\z/)
+
+      Date.parse(value)
+    rescue Date::Error
+      raise ArgumentError, "invalid date '#{value}'"
+    end
+
     def self.evaluate_date(from, to)
       return (from >> to) - 1 if to.is_a?(Numeric)
       return Date.parse(to) unless to.start_with?("=") || to.start_with?("+")

data/lib/hledger_forecast/cli.rb

@@ -185,15 +185,39 @@ module HledgerForecast
           options[:verbose] = true
         end
 
-        # opts.on("--from DATE",
-        #         "Include transactions that start FROM a given DATE [yyyy-mm-dd]") do |from|
-        #   options[:from] = from
-        # end
-        #
-        # opts.on("--to DATE",
-        #         "Include transactions that run TO a given DATE [yyyy-mm-dd]") do |to|
-        #   options[:to] = to
-        # end
+        opts
+          .on(
+            "--from DATE",
+            "Only include transactions still running from a given DATE,",
+            "e.g. \"Sep 2027\", \"2027-09\" or \"01/09/2027\""
+          ) do |from|
+            options[:from] = Calculator.parse_date(from)
+          rescue ArgumentError => e
+            puts("\nError: ".bold.red + e.message)
+            exit(1)
+          end
+
+        opts.on(
+          "--exclude-once",
+          "Exclude one-off transactions from the summary"
+        ) do
+          options[:exclude_once] = true
+        end
+
+        opts.on(
+          "-e",
+          "--export FILE",
+          "Also write the summary to a CSV FILE"
+        ) do |file|
+          options[:export] = file
+        end
+
+        opts.on(
+          "--force",
+          "Force an overwrite of the exported file"
+        ) do
+          options[:force] = true
+        end
 
         # opts.on("-s", "--scenario \"NAMES\"",
         #         "Include transactions from given scenarios, e.g.:",
@@ -261,22 +285,7 @@ module HledgerForecast
         exit(1)
       end
 
-      output_file = options[:output_file]
-
-      if File.exist?(output_file) && !options[:force]
-        print("\nFile '#{output_file}' already exists. Overwrite? (y/n): ")
-        overwrite = gets.chomp.downcase
-
-        if overwrite == "y"
-          File.write(output_file, transactions)
-          puts("\nSuccess: ".bold.green + "File '#{output_file}' has been overwritten.")
-        else
-          puts("\nInfo: ".bold.blue + "Operation aborted. File '#{output_file}' was not overwritten.")
-        end
-      else
-        File.write(output_file, transactions)
-        puts("\nSuccess: ".bold.green + "File '#{output_file}' has been created")
-      end
+      write_file(options[:output_file], transactions, options[:force])
     end
 
     def self.summarize(options)
@@ -291,6 +300,27 @@ module HledgerForecast
       end
 
       puts(SummarizerFormatter.format(summarizer[:output], summarizer[:settings]))
+
+      return unless options[:export]
+
+      csv = SummarizerExporter.export(summarizer[:output], summarizer[:settings])
+      write_file(options[:export], csv, options[:force])
+    end
+
+    private_class_method def self.write_file(path, contents, force)
+      if File.exist?(path) && !force
+        print("\nFile '#{path}' already exists. Overwrite? (y/n): ")
+
+        unless gets.chomp.downcase == "y"
+          return puts("\nInfo: ".bold.blue + "Operation aborted. File '#{path}' was not overwritten.")
+        end
+
+        File.write(path, contents)
+        return puts("\nSuccess: ".bold.green + "File '#{path}' has been overwritten.")
+      end
+
+      File.write(path, contents)
+      puts("\nSuccess: ".bold.green + "File '#{path}' has been created")
     end
 
     def self.compare(options)

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/settings.rb

@@ -13,7 +13,9 @@ module HledgerForecast
       :sign_before_symbol,
       :thousands_separator,
       :verbose,
-      :roll_up
+      :roll_up,
+      :from,
+      :exclude_once
     )
 
     def self.parse(settings_rows, cli_options = nil)
@@ -38,6 +40,8 @@ module HledgerForecast
         DEFAULTS[:thousands_separator]
       @verbose = opts[:verbose] || false
       @roll_up = opts[:roll_up]
+      @from = opts[:from]
+      @exclude_once = opts[:exclude_once] || false
     end
   end
 end

data/lib/hledger_forecast/summarizer.rb

@@ -8,6 +8,12 @@ module HledgerForecast
       forecast = Forecast.parse(csv_string, cli_options)
       transactions = forecast.transactions.reject(&:summary_exclude?)
 
+      transactions = transactions.reject(&:once?) if forecast.settings.exclude_once
+
+      if (from = forecast.settings.from)
+        transactions = transactions.select { |t| t.active_on_or_after?(from) }
+      end
+
       if cli_options&.dig(:tags)
         raise "The --tags option requires a 'tag' column in the forecast CSV" unless forecast.has_tags_column?
         transactions = transactions.select { |t| t.matches_tags?(cli_options[:tags]) }

data/lib/hledger_forecast/summarizer_exporter.rb

@@ -0,0 +1,31 @@
+module HledgerForecast
+  # Renders the summary as CSV, mirroring the forecast file's columns and
+  # appending the amounts the summarizer calculated
+  class SummarizerExporter
+    HEADERS = %i[type frequency account from to description category amount annualised_amount].freeze
+    MONEY_FIELDS = %i[amount annualised_amount rolled_up_amount].freeze
+
+    def self.export(output, settings)
+      new.export(output, settings)
+    end
+
+    def export(output, settings)
+      headers = settings.roll_up ? HEADERS + [:rolled_up_amount] : HEADERS
+
+      CSV.generate do |csv|
+        csv << headers
+        output.each { |row| csv << headers.map { |h| format_value(h, row[h]) } }
+      end
+    end
+
+    private
+
+    def format_value(key, value)
+      return nil if value.nil?
+      return value.iso8601 if value.is_a?(Date)
+      return value.to_f.round(2) if MONEY_FIELDS.include?(key)
+
+      value
+    end
+  end
+end

data/lib/hledger_forecast/summarizer_formatter.rb

@@ -25,6 +25,7 @@ module HledgerForecast
 
     def init_table
       title = "FORECAST SUMMARY"
+      title += " FROM #{@settings.from.strftime("%b %Y").upcase}" if @settings.from
       title += " (#{@settings.roll_up.upcase} ROLL UP)" if @settings.roll_up
 
       @table.add_row([{value: title.bold, colspan: 3, alignment: :center}])

data/lib/hledger_forecast/transaction.rb

@@ -67,6 +67,15 @@ module HledgerForecast
 
     def summary_exclude? = !!summary_exclude
 
+    def once? = type == "once"
+
+    # A `once` transaction has no TO date but only ever occurs on its FROM date
+    def ends_on = to || (once? ? from : nil)
+
+    def active_on_or_after?(date)
+      ends_on.nil? || ends_on >= date
+    end
+
     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?

data/lib/hledger_forecast/version.rb

@@ -1,3 +1,3 @@
 module HledgerForecast
-  VERSION = "3.3.0"
+  VERSION = "3.4.0"
 end

data/lib/hledger_forecast.rb

@@ -21,6 +21,7 @@ require_relative "hledger_forecast/formatter"
 require_relative "hledger_forecast/generator"
 require_relative "hledger_forecast/summarizer"
 require_relative "hledger_forecast/summarizer_formatter"
+require_relative "hledger_forecast/summarizer_exporter"
 require_relative "hledger_forecast/comparator"
 require_relative "hledger_forecast/cli"
 require_relative "hledger_forecast/version"

data/release-please-config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "include-component-in-tag": false,
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "hledger-forecast",
+      "version-file": "lib/hledger_forecast/version.rb"
+    }
+  }
+}

data/spec/calculator_spec.rb

@@ -69,3 +69,27 @@ RSpec.describe HledgerForecast::Calculator do
     end
   end
 end
+
+RSpec.describe HledgerForecast::Calculator do
+  describe ".parse_date" do
+    it "parses a month and year" do
+      expect(described_class.parse_date("Sep 2027")).to(eq(Date.new(2027, 9, 1)))
+    end
+
+    it "parses an ISO year-month" do
+      expect(described_class.parse_date("2027-09")).to(eq(Date.new(2027, 9, 1)))
+    end
+
+    it "parses a bare year" do
+      expect(described_class.parse_date("2027")).to(eq(Date.new(2027, 1, 1)))
+    end
+
+    it "parses a day-first date" do
+      expect(described_class.parse_date("15/09/2027")).to(eq(Date.new(2027, 9, 15)))
+    end
+
+    it "raises on an unparseable value" do
+      expect { described_class.parse_date("nonsense") }.to(raise_error(ArgumentError, /invalid date/))
+    end
+  end
+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
 
@@ -35,6 +38,39 @@ RSpec.describe "command" do
     expect(File.read(generated_journal)).to(eq(output))
   end
 
+  it "uses the CLI to export a summary to a CSV file" do
+    exported_csv = "./test_summary.csv"
+    File.delete(exported_csv) if File.exist?(exported_csv)
+
+    system("./bin/hledger-forecast summarize -f ./spec/stubs/forecast.csv --export #{exported_csv} > /dev/null")
+
+    expect(File.read(exported_csv)).to(
+      eq(
+        <<~CSV
+          type,frequency,account,from,to,description,category,amount,annualised_amount
+          monthly,,Assets:Bank,2023-03-01,,Mortgage,Expenses:Mortgage,2000.55,24006.6
+          monthly,,Assets:Bank,2023-03-01,,Food,Expenses:Food,100.0,1200.0
+          monthly,,Assets:Savings,2023-03-01,,Savings,Assets:Bank,-1000.0,-12000.0
+        CSV
+      )
+    )
+  ensure
+    File.delete(exported_csv) if File.exist?(exported_csv)
+  end
+
+  it "does not overwrite an existing export without confirmation" do
+    exported_csv = "./test_summary.csv"
+    File.write(exported_csv, "untouched")
+
+    system(
+      "echo n | ./bin/hledger-forecast summarize -f ./spec/stubs/forecast.csv --export #{exported_csv} > /dev/null"
+    )
+
+    expect(File.read(exported_csv)).to(eq("untouched"))
+  ensure
+    File.delete(exported_csv) if File.exist?(exported_csv)
+  end
+
   it "uses the CLI to compare two CSV files" do
     expected_output = strip_ansi_codes(
       <<~OUTPUT

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/summarizer_exporter_spec.rb

@@ -0,0 +1,62 @@
+require_relative "../lib/hledger_forecast"
+
+EXPORT_CONFIG = <<~CSV
+  type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude
+  monthly,,Assets:Bank,01/03/2023,01/03/2025,Mortgage,Expenses:Mortgage,2000.555,,
+  monthly,,Assets:Bank,01/03/2023,,"Food, drink",Expenses:Food,100,,
+  custom,every 2 weeks,Assets:Bank,01/05/2023,,Hair,Expenses:Personal Care,80,26,
+  settings,currency,GBP,,,,,,,,
+CSV
+
+RSpec.describe HledgerForecast::SummarizerExporter do
+  def exported(options = {})
+    summary = HledgerForecast::Summarizer.summarize(EXPORT_CONFIG, options)
+    CSV.parse(described_class.export(summary[:output], summary[:settings]), headers: true)
+  end
+
+  it "writes a header row mirroring the forecast columns" do
+    expect(exported.headers).to(
+      eq(%w[type frequency account from to description category amount annualised_amount])
+    )
+  end
+
+  it "writes a row per transaction" do
+    expect(exported.length).to(eq(3))
+  end
+
+  it "formats dates as ISO 8601" do
+    expect(exported[0]["from"]).to(eq("2023-03-01"))
+    expect(exported[0]["to"]).to(eq("2025-03-01"))
+  end
+
+  it "leaves an open-ended TO date blank" do
+    expect(exported[1]["to"]).to(be_nil)
+  end
+
+  it "rounds amounts to two decimal places" do
+    expect(exported[0]["amount"]).to(eq("2000.56"))
+  end
+
+  it "writes amounts without currency formatting" do
+    expect(exported[0]["annualised_amount"]).to(eq("24006.66"))
+  end
+
+  it "quotes fields containing a comma" do
+    expect(exported[1]["description"]).to(eq("Food, drink"))
+  end
+
+  it "adds a rolled_up_amount column when rolling up" do
+    rolled = exported({roll_up: "monthly"})
+
+    expect(rolled.headers).to(include("rolled_up_amount"))
+    expect(rolled[2]["rolled_up_amount"]).to(eq(((80.0 * 26) / 12).round(2).to_s))
+  end
+
+  it "omits the rolled_up_amount column without a roll-up" do
+    expect(exported.headers).not_to(include("rolled_up_amount"))
+  end
+
+  it "only exports rows that survived the filters" do
+    expect(exported({from: Date.new(2026, 1, 1)}).map { |r| r["description"] }).to(eq(["Food, drink", "Hair"]))
+  end
+end

data/spec/summarizer_spec.rb

@@ -48,3 +48,46 @@ RSpec.describe HledgerForecast::Summarizer do
     end
   end
 end
+
+FILTER_CONFIG = <<~CSV
+  type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude
+  monthly,,Assets:Bank,01/03/2023,,Food,Expenses:Food,100,,
+  monthly,,Assets:Bank,01/03/2023,01/01/2025,Mortgage,Expenses:Mortgage,2000,,
+  yearly,,Assets:Bank,01/04/2023,01/06/2028,Insurance,Expenses:Insurance,500,,
+  once,,Assets:Bank,05/03/2023,,Laptop refund,Expenses:Shopping,-3000,,
+  once,,Assets:Bank,05/03/2029,,New car,Expenses:Car,10000,,
+CSV
+
+RSpec.describe HledgerForecast::Summarizer do
+  def descriptions(options)
+    described_class.summarize(FILTER_CONFIG, options)[:output].map { |r| r[:description] }
+  end
+
+  describe "#summarize with exclude_once" do
+    it "removes one-off transactions" do
+      expect(descriptions({exclude_once: true})).to(eq(["Food", "Mortgage", "Insurance"]))
+    end
+
+    it "keeps them by default" do
+      expect(descriptions({})).to(include("Laptop refund", "New car"))
+    end
+  end
+
+  describe "#summarize with from" do
+    it "keeps transactions that are still running" do
+      expect(descriptions({from: Date.new(2027, 9, 1)})).to(eq(["Food", "Insurance", "New car"]))
+    end
+
+    it "drops a one-off that has already happened" do
+      expect(descriptions({from: Date.new(2023, 4, 1)})).not_to(include("Laptop refund"))
+    end
+
+    it "drops a transaction that ends before the date" do
+      expect(descriptions({from: Date.new(2028, 7, 1)})).to(eq(["Food", "New car"]))
+    end
+
+    it "combines with exclude_once" do
+      expect(descriptions({from: Date.new(2027, 9, 1), exclude_once: true})).to(eq(["Food", "Insurance"]))
+    end
+  end
+end

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.3.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Oli Morris
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-13 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: abbrev
@@ -132,10 +132,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yml"
+- ".github/workflows/manually_publish.yml"
 - ".github/workflows/release.yml"
 - ".gitignore"
 - ".mise.toml"
+- ".release-please-manifest.json"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - Gemfile
 - LICENSE
@@ -154,10 +157,12 @@ files:
 - lib/hledger_forecast/generator.rb
 - lib/hledger_forecast/settings.rb
 - lib/hledger_forecast/summarizer.rb
+- lib/hledger_forecast/summarizer_exporter.rb
 - lib/hledger_forecast/summarizer_formatter.rb
 - lib/hledger_forecast/transaction.rb
 - lib/hledger_forecast/transactions/default.rb
 - lib/hledger_forecast/version.rb
+- release-please-config.json
 - spec/calculator_spec.rb
 - spec/cli_spec.rb
 - spec/compare_spec.rb
@@ -177,6 +182,7 @@ files:
 - spec/stubs/transactions_found.journal
 - spec/stubs/transactions_found_inverse.journal
 - spec/stubs/transactions_not_found.journal
+- spec/summarizer_exporter_spec.rb
 - spec/summarizer_spec.rb
 - spec/tags_spec.rb
 - spec/verbose_output_spec.rb
@@ -224,6 +230,7 @@ test_files:
 - spec/stubs/transactions_found.journal
 - spec/stubs/transactions_found_inverse.journal
 - spec/stubs/transactions_not_found.journal
+- spec/summarizer_exporter_spec.rb
 - spec/summarizer_spec.rb
 - spec/tags_spec.rb
 - spec/verbose_output_spec.rb