8.7 KiB
hledger error messages are currently quite varied in format. Tools like flycheck-hledger parse them and need updating whenever they change (#1436). Getting consistent high-quality errors and accurate flycheck region highlighting, not to mention LSP support, for all of our journal errors is a big project, but it’s crowd-sourceable and every bit of progress brings immediate practical benefits.
Here are journals/scripts for reproducing hledger’s journal error messages. They are named similarly to hledger check’s checks. In the CLI, execute them to see the error messages.
In Emacs with flycheck-hledger, customize flycheck-hledger-* to enable all appropriate checks, and open the files to see how flycheck handles them. Some files contain extra declarations to ease flycheck testing.
Goals
- phase 1: update flycheck to detect journal errors of current hledger release (and keep a branch updated to detect errors of latest hledger master)
- phase 2: survey/document current journal errors & status
- phase 3: pick a new standard format
- phase 4: implement standard format for all
- phase 5: implement accurate lines for all
- phase 6: implement accurate columns for all
- phase 7: implement useful highlighted excerpts for all
- phase 8: implement accurate flycheck region for all
- phase 9: do likewise for timeclock errors
- phase 10: do likewise for timedot errors
- phase 11: do likewise for csv errors
- phase 12: do likewise for other command line errors
- phase 13: decide/add error ids/explanations/web pages ? not needed
- phase 14: support Language Server Protocol & Visual Code
Current status
Here is the current status (hledger 1.26.99-gb7e6583a7-20220710, flycheck 87b275b9):
| std format | line | column | excerpt | flycheck | flycheck region | |
|---|---|---|---|---|---|---|
| accounts | ✓ | ✓ | ✓ | ✓✓ | ||
| assertions | ✓ | ✓ | ✓ | ✓✓ | ||
| balanced | ✓ | ✓ | - | ✓ | ||
| balancednoautoconversion | ✓ | ✓ | - | ✓ | ||
| commodities | ✓ | ✓ | ✓(approx) | ✓✓ | ||
| ordereddates | ✓ | ✓ | ✓ | ✓✓ | ||
| parseable | ✓ | ✓ | ✓ | ✓✓ | ||
| parseable-dates | ✓ | ✓ | ✓ | ✓✓ | ||
| parseable-regexps | ✓ | ✓ | ✓ | ✓✓ | ||
| payees | ✓ | ✓ | ✓ | ✓✓ | ||
| uniqueleafnames | ✓ | ✓ | ✓ | ✓✓ |
Key: - std format - the error message follows a standard format (location on first line, megaparsec-like excerpt, description). - line - the optimal line(s) are reported - column - the optimal column(s) are reported - excerpt - a useful excerpt is shown, ideally with the error highlighted (✓✓) - flycheck - the current flycheck release recognises and reports the error, with no “suspicious state” warning - flycheck region - flycheck highlights a reasonably accurate region containing the error
Preferred error format
Here is our preferred error message layout for now:
hledger: Error: FILE:LOCATION:
EXCERPT
SUMMARY
[DETAILS]
Notes (see also #1436):
the “hledger:” prefix could be dropped later with a bit more effort
includes the word “Error” and the error position on line 1
FILE is the file path
LOCATION is
LINE[-ENDLINE][:COLUMN[-ENDCOLUMN]]we may show 0 for LINE or COLUMN when unknown
EXCERPT is a short visual snippet whenever possible, with the error region highlighted, line numbers, and colour when supported. This section must be easy for flycheck to ignore.
SUMMARY is a one line description/explanation of the problem. These are currently dynamic, they can include helpful contextual info. ShellCheck uses static summaries.
DETAILS is optional additional details/advice when needed.
this layout is based on megaparsec’s. For comparison, rustc puts summary on line 1 and location on line 2:
Error[ID]: SUMMARY at FILE:LOCATION EXCERPT [DETAILS]try https://github.com/mesabloo/diagnose / https://hackage.haskell.org/package/errata / https://hackage.haskell.org/package/chapelure later
Current journal errors
hledger 1.26.99-gc22e9f6cc-20220713 error messages:
accounts
hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./accounts.j:4:
| 2022-01-01
4 | (a) 1
| ^
Strict account checking is enabled, and
account "a" has not been declared.
Consider adding an account directive. Examples:
account a
account a ; type:A ; (L,E,R,X,C,V)
assertions
hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./assertions.j:4:8:
| 2022-01-01
4 | a 0 = 1
| ^^^
This balance assertion failed.
In account: a
and commodity:
this balance was asserted: 1
but the actual balance is: 0
a difference of: 1
Consider viewing this account's register to troubleshoot. Eg:
hledger reg -I 'a$' cur:''
balanced
hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./balanced.j:3-4:
3 | 2022-01-01
| a 1
This transaction is unbalanced.
The real postings' sum should be 0 but is: 1
Consider adjusting this entry's amounts, or adding missing postings.
balancednoautoconversion
hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./balancednoautoconversion.j:6-8:
6 | 2022-01-01
| a 1 A
| b -1 B
This multi-commodity transaction is unbalanced.
Automatic commodity conversion is not enabled.
The real postings' sum should be 0 but is: 1 A, -1 B
Consider adjusting this entry's amounts, adding missing postings,
or recording conversion price(s) with @, @@ or equity postings.
commodities
hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./commodities.j:6:
| 2022-01-01
6 | (a) A 1
| ^^^
Strict commodity checking is enabled, and
commodity "A" has not been declared.
Consider adding a commodity directive. Examples:
commodity A1000.00
commodity 1.000,00 A
ordereddates
hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./ordereddates.j:10:
7 | 2022-01-02 p
| (a) 1
10 | 2022-01-01 p
| ^^^^^^^^^^
| (a) 1
Ordered dates checking is enabled, and this transaction's
date (2022-01-01) is out of order with the previous transaction.
Consider moving this entry into date order, or adjusting its date.
parseable-dates
hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./parseable-dates.j:3:1:
|
3 | 2022/1/32
| ^^^^^^^^^
This date is invalid, please correct it: 2022/1/32
parseable-regexps
hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./parseable-regexps.j:3:8:
|
3 | alias /(/ = a
| ^
This regular expression is malformed, please correct it:
(
parseable
hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./parseable.j:3:2:
|
3 | 1
| ^
unexpected newline
expecting date separator or digit
payees
hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./payees.j:6:
6 | 2022-01-01 p
| ^
| (a) A 1
Strict payee checking is enabled, and
payee "p" has not been declared.
Consider adding a payee directive. Examples:
payee p
uniqueleafnames
hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./uniqueleafnames.j:12:
| 2022-01-01 p
9 | (a:c) 1
...
| 2022-01-01 p
12 | (b:c) 1
| ^
Checking for unique account leaf names is enabled, and
account leaf name "c" is not unique.
It appears in these account names, which are used in 2 places:
a:c
b:c
Consider changing these account names so their last parts are different.