From de4d637def1edcbbc61ecbbcab59e5a164dfaf1b Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Wed, 11 Jun 2025 07:18:53 -1000
Subject: [PATCH] dev: transaction balancing: cleanup [#2402]

---
 hledger-lib/Hledger/Data/Balancing.hs   |  1 -
 hledger-lib/Hledger/Data/Transaction.hs | 25 ++++++++++---------------
 hledger-lib/Hledger/Read/Common.hs      |  3 +--
 hledger/Hledger/Cli/CliOptions.hs       |  1 -
 4 files changed, 11 insertions(+), 19 deletions(-)

diff --git a/hledger-lib/Hledger/Data/Balancing.hs b/hledger-lib/Hledger/Data/Balancing.hs
index 8bf67b8db..285f3d8a9 100644
--- a/hledger-lib/Hledger/Data/Balancing.hs
+++ b/hledger-lib/Hledger/Data/Balancing.hs
@@ -115,7 +115,6 @@ transactionCheckBalanced BalancingOpts{commodity_styles_=_mglobalstyles, txn_bal
       where
         roundforbalancecheck = case txn_balancing_ of
           TBPOld    -> maybe id styleAmounts _mglobalstyles
-          -- TBPCompat -> styleAmounts (transactionstyles `limitprecisionsto` commoditydirectivestyles)
           TBPExact  -> styleAmounts transactionstyles
           where
             transactionstyles = transactionCommodityStylesWith HardRounding t
diff --git a/hledger-lib/Hledger/Data/Transaction.hs b/hledger-lib/Hledger/Data/Transaction.hs
index 285ce4a59..b34f5f670 100644
--- a/hledger-lib/Hledger/Data/Transaction.hs
+++ b/hledger-lib/Hledger/Data/Transaction.hs
@@ -87,24 +87,19 @@ import Data.List (union)
 
 
 -- | How to determine the precision used for checking that transactions are balanced. See #2402.
-data TransactionBalancingPrecision
-  = -- | Legacy behaviour, as in hledger <=1.43:
+data TransactionBalancingPrecision =
+    TBPOld
+    -- ^ Legacy behaviour, as in hledger <1.44, included to ease upgrades.
     -- use precision inferred from the whole journal, overridable by commodity directive or -c.
     -- Display precision is also transaction balancing precision; increasing it can break journal reading.
-    -- Some journals from ledger or beancount are rejected until commodity directives are added.
-    TBPOld
-  -- | -- | Use precision inferred from the transaction, reducible by commodity directive (or -c ?)
-  --   -- This is more robust when there is no commodity directive, because it's not affected by other transactions or P directives.
-  --   -- Increasing display precision does not increase balancing precision, so it does not break journal reading.
-  --   -- But reducing it does reduce balancing precision, so existing hledger journals which rely on this can still be read.
-  --   -- Journals from ledger or beancount are accepted without needing commodity directives.
-  --   TBPCompat
-  | -- | Use precision inferred from the transaction.
-    -- This is the most strict; transactions that worked with hledger <=1.43 may need to be adjusted.
-    -- It's also the simplest, and most robust overall ?
+    -- Some valid journals are rejected until commodity directives are added.
+    -- Small unbalanced remainders can be hidden, and in accounts that are never reconciled, can accumulate over time.
+  | TBPExact
+    -- ^ Simpler, more robust behaviour, as in Ledger: use precision inferred from the transaction.
     -- Display precision and transaction balancing precision are independent; display precision never affects journal reading.
-    -- Journals from ledger or beancount are accepted without needing commodity directives.
-    TBPExact
+    -- Valid journals from ledger or beancount are accepted without needing commodity directives.
+    -- Every imbalance in a transaction is visibly accounted for in that transaction's journal entry.
+
   deriving (Bounded, Enum, Eq, Ord, Read, Show)
 
 instance HasAmounts Transaction where
diff --git a/hledger-lib/Hledger/Read/Common.hs b/hledger-lib/Hledger/Read/Common.hs
index 95b8922f6..bf5911218 100644
--- a/hledger-lib/Hledger/Read/Common.hs
+++ b/hledger-lib/Hledger/Read/Common.hs
@@ -284,9 +284,8 @@ transactionBalancingPrecisionFromOpts rawopts =
   case maybestringopt "txn-balancing" rawopts of
     Nothing      -> Right TBPExact
     Just "old"   -> Right TBPOld
-    -- Just "compat" -> Right TBPCompat
     Just "exact" -> Right TBPExact
-    Just s       -> Left $ s<>", should be one of: old, exact" -- compat
+    Just s       -> Left $ s<>", should be one of: old, exact"
 
 -- | Given a parser to ParsedJournal, input options, file path and
 -- content: run the parser on the content, and finalise the result to
diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs
index 575d51537..cdbe6669a 100644
--- a/hledger/Hledger/Cli/CliOptions.hs
+++ b/hledger/Hledger/Cli/CliOptions.hs
@@ -167,7 +167,6 @@ inputflags = [
   ,flagReq  ["txn-balancing"] (\s opts -> Right $ setopt "txn-balancing" s opts) "..." (unlines [
      "how to check that transactions are balanced:"
     ,"'old':   - use global display precision"
-    -- ,"'compat': - use transaction precision, reducible"
     ,"'exact': - use transaction precision (default)"
     ])
   ,flagNone ["infer-costs"] (setboolopt "infer-costs") "infer conversion equity postings from costs"