hledger-forecast 3.3.1 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b3fc72db9564b895f8412f6467b3350700b12e7c4cb393ae48d7640ff0766ef
-  data.tar.gz: 78092306250621f6d6e93df98d600035d85960125d40b2df35bd728f1e38cb73
+  metadata.gz: e8f490f679ec154468837d25878ef658fd0225d73cdd30f291679475e247d00f
+  data.tar.gz: bcc7247a985c775b2b053c43d25f4e5269ed224ee6f396afdaa4339f6ddf4c52
 SHA512:
-  metadata.gz: c07f7f68ff23714ec25f2708405d4700f8f0df800e07571d805c548598d23775e70b947ba94c74e72c2f9b6064fefdcef2a9d2931fb4d863856c7f0ad1ec14b3
-  data.tar.gz: b00893cc0d8f03f4d7d89c7396d69a8337889a40957b31b572d150eb432fb22a37ca53948106009c33846c49db6499ec90a49a617ab79ce3b29c8b9c20b8b1c2
+  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

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/.github/workflows/release.yml

@@ -22,7 +22,8 @@ jobs:
         id: release
         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
@@ -30,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/.release-please-manifest.json

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

data/AGENTS.md

@@ -25,3 +25,5 @@ In non-verbose mode, `Generator.build_groups` (lib/hledger_forecast/generator.rb
 ## 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,12 @@
 # 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)
 
 

data/README.md

@@ -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/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.1"
+  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

@@ -38,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/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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hledger-forecast
 version: !ruby/object:Gem::Version
-  version: 3.3.1
+  version: 3.4.0
 platform: ruby
 authors:
 - Oli Morris
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-28 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: abbrev
@@ -136,6 +136,7 @@ files:
 - ".github/workflows/release.yml"
 - ".gitignore"
 - ".mise.toml"
+- ".release-please-manifest.json"
 - ".rubocop.yml"
 - AGENTS.md
 - CHANGELOG.md
@@ -156,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
@@ -179,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
@@ -226,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