From cec1e8e3f1c0d4024e4646dac74428811b2d2c90 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 22 Apr 2022 00:05:39 -1000 Subject: [PATCH] doc: errors status update (#1436) --- hledger/test/errors/README.md | 173 +++++++++++++++------------------- 1 file changed, 75 insertions(+), 98 deletions(-) diff --git a/hledger/test/errors/README.md b/hledger/test/errors/README.md index f6e96c136..c9492f039 100644 --- a/hledger/test/errors/README.md +++ b/hledger/test/errors/README.md @@ -20,36 +20,6 @@ Some files contain extra declarations to ease flycheck testing. [flycheck-hledger-10]: https://github.com/DamienCassou/flycheck-hledger/pull/10 [#1436]: https://github.com/simonmichael/hledger/issues/1436 -## Status - -Here is the current status -(hledger 1.25, flycheck 87b275b9): - -| | format | accurate line(s) | accurate column(s) | visual | flycheck detects | flycheck region | -|--------------------------|---------|------------------|--------------------|--------|------------------|-----------------| -| parseable | format1 | Y | Y | YY | Y | Y | -| parseable-dates | format1 | Y | Y | YY | Y | Y | -| parseable-regexps | format1 | Y | Y | YY | Y | Y | -| balanced | | Y | - | Y | Y | | -| balancednoautoconversion | | Y | - | Y | Y | | -| assertions | | Y | | Y | Y | Y | -| accounts | format2 | | | Y | Y | | -| commodities | format2 | | | Y | Y | | -| payees | format2 | | | Y | Y | Y | -| ordereddates | format2 | | | Y | Y | Y | -| uniqueleafnames | | | | Y | Y | | - -Key: -- format: the error message follows a standard format - (format1: location on first line, megaparsec-like. - format2: summary on first line, location on second line, rustc-like. - std: new standard format) -- accurate line - the optimal line(s) is(are) selected -- accurate column - the optimal column(s) is(are) selected -- visual - the CLI error message shows a relevant excerpt (Y), ideally with the error highlighted (YY) -- flycheck detects - flycheck recognises the error output, reports the error and doesn't give a "suspicious" warning -- flycheck region - flycheck highlights a reasonably accurate text region containing the error - ## Goals - [x] phase 1: update flycheck to detect journal errors of current hledger release (and keep a branch updated to detect errors of latest hledger master) @@ -67,14 +37,73 @@ Key: - [x] 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.25, flycheck 87b275b9): + +| | std format | accurate line(s) | accurate column(s) | visual | flycheck detects | flycheck region | +|--------------------------|------------|------------------|--------------------|--------|------------------|-----------------| +| parseable | Y | Y | Y | YY | Y | Y | +| parseable-dates | Y | Y | Y | YY | Y | Y | +| parseable-regexps | Y | Y | Y | YY | Y | Y | +| balanced | | Y | - | Y | Y | | +| balancednoautoconversion | | Y | - | Y | Y | | +| assertions | | Y | | Y | Y | Y | +| accounts | Y | | | Y | Y | | +| commodities | | | | Y | Y | | +| payees | | | | Y | Y | Y | +| ordereddates | | | | Y | Y | Y | +| uniqueleafnames | | | | Y | Y | | + +Key: +- std format - the error message follows a standard format + (location on first line, megaparsec-like excerpt, description). +- accurate line - the optimal line(s) is(are) selected +- accurate column - the optimal column(s) is(are) selected +- visual - the CLI error message shows a relevant excerpt (Y), ideally with the error highlighted (YY) +- flycheck detects - flycheck recognises the error output, reports the error and doesn't give a "suspicious" warning +- flycheck region - flycheck highlights a reasonably accurate text 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]]` +- 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 later + ## Current journal errors -hledger 1.25.99-g133c54434-20220414 error messages, last updated 2022-04-15: +hledger 1.25.99-gb8d78661e-20220422 error messages, last updated 2022-04-22: ### parseable ``` -hledger: /Users/simon/src/hledger/hledger/test/errors/./parseable.j:3:2: +hledger: Error: /Users/simon/src/hledger/hledger/test/errors/parseable.j:3:2: | 3 | 1 | ^ @@ -85,7 +114,7 @@ expecting date separator or digit ### parseable-dates ``` -hledger: /Users/simon/src/hledger/hledger/test/errors/./parseable-dates.j:3:1: +hledger: Error: /Users/simon/src/hledger/hledger/test/errors/parseable-dates.j:3:1: | 3 | 2022/1/32 | ^^^^^^^^^ @@ -95,7 +124,7 @@ well-formed but invalid date: 2022/1/32 ### parseable-regexps ``` -hledger: /Users/simon/src/hledger/hledger/test/errors/./parseable-regexps.j:3:8: +hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./parseable-regexps.j:3:8: | 3 | alias /(/ = a | ^ @@ -105,7 +134,7 @@ this regular expression could not be compiled: ( ### balanced ``` -hledger: /Users/simon/src/hledger/hledger/test/errors/./balanced.j:3-4 +hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./balanced.j:3-4 could not balance this transaction: real postings' sum should be 0 but is: 1 2022-01-01 @@ -115,7 +144,7 @@ real postings' sum should be 0 but is: 1 ### balancednoautoconversion ``` -hledger: /Users/simon/src/hledger/hledger/test/errors/./balancednoautoconversion.j:6-8 +hledger: Error: /Users/simon/src/hledger/hledger/test/errors/./balancednoautoconversion.j:6-8 could not balance this transaction: real postings' sum should be 0 but is: 1 A -1 B @@ -127,7 +156,7 @@ real postings' sum should be 0 but is: 1 A ### assertions ``` -hledger: balance assertion: /Users/simon/src/hledger/hledger/test/errors/./assertions.j:4:8 +hledger: Error: balance assertion: /Users/simon/src/hledger/hledger/test/errors/./assertions.j:4:8 transaction: 2022-01-01 a 0 = 1 @@ -144,17 +173,17 @@ difference: 1 ### accounts ``` -Error: undeclared account "a" -in transaction at: /Users/simon/src/hledger/hledger/test/errors/./accounts.j:3-4 - - 2022-01-01 - (a) 1 +hledger: Error: /Users/simon/src/hledger/hledger/test/errors/accounts.j:4:6: + | 2022-01-01 +4 | (a) 1 + | ^ +undeclared account "a" ``` ### commodities ``` -Error: undeclared commodity "A" +hledger: Error: undeclared commodity "A" in transaction at: /Users/simon/src/hledger/hledger/test/errors/./commodities.j:5-6 2022-01-01 @@ -164,7 +193,7 @@ in transaction at: /Users/simon/src/hledger/hledger/test/errors/./commodities.j: ### payees ``` -Error: undeclared payee "p" +hledger: Error: undeclared payee "p" at: /Users/simon/src/hledger/hledger/test/errors/./payees.j:6-7 > 2022-01-01 p @@ -174,7 +203,7 @@ at: /Users/simon/src/hledger/hledger/test/errors/./payees.j:6-7 ### ordereddates ``` -Error: transaction date is out of order +hledger: Error: transaction date is out of order at /Users/simon/src/hledger/hledger/test/errors/./ordereddates.j:10-11: 2022-01-02 p @@ -188,7 +217,7 @@ at /Users/simon/src/hledger/hledger/test/errors/./ordereddates.j:10-11: ### uniqueleafnames ``` -Error: account leaf names are not unique +hledger: Error: account leaf names are not unique leaf name "c" appears in account names: "a:c", "b:c" seen in "a:c" in transaction at: /Users/simon/src/hledger/hledger/test/errors/./uniqueleafnames.j:8-9 @@ -196,55 +225,3 @@ seen in "a:c" in transaction at: /Users/simon/src/hledger/hledger/test/errors/./ > (a:c) 1 ``` - - -## New error format - -The preferred standard error format for now is the following, -similar to the one megaparsec gives us -and probably the easiest to implement consistently: - -``` -Error: FILE:LOCATION: -EXCERPT -SUMMARY -[DETAILS] -``` - -Other format notes (see also [#1436][]): - -megaparsec-like: - -``` -Error: [ID] FILE:LOCATION -EXCERPT -SUMMARY -[DETAILS] -``` - -- begins with the word "Error" -- ID is an optional error id, eg `HL1001` (in brackets ?). We might adopt these, similar to ShellCheck. -- FILE is the file path. -- LOCATION is `LINE[-ENDLINE][:COLUMN[-ENDCOLUMN]]`. Having location on the first line helps some tools, like Emacs M-x compile. -- 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. Currently we use dynamic summaries including contextual data for clarity. ShellCheck uses static summaries, which might have some advantages. -- DETAILS is optional additional details/advice when needed. - -rustc-like: - -``` -Error[ID]: SUMMARY -at FILE:LOCATION -EXCERPT -[DETAILS] -``` - -- Having summary on the first line can be helpful eg when grepping logged errors. - -Questions: - -- location needed on first line for maximum tool support ? -- summary needed on first line for maximum concision/greppability ? -- allow long, much-wider-than-80-char first lines or not ? -- dynamic or static summary ? -- error ids/explanations needed ? local and/or web based ? easily editable ? document old hledger versions ?