Add changelog entry

changelog.d/pr-10644

@@ -0,0 +1,165 @@
+---
+synopsis: Show source of project parse error or warning
+packages: [cabal-install]
+prs: 10644
+issues: 10635
+---
+
+Improves warning and error messages shown when parsing project files and their
+imports.
+
+## Warning Messages
+
+To trigger these warning messages, the examples use badly formed comments that
+have a single dash instead of two as is required of a line comment in `.cabal`
+and `.project` files (and imported `.config` files).
+
+
+* Before the fix:
+
+    The `cabal.project` file name is repeated. Warnings are misattributed to
+    having been in the project rather than from a configuration file imported by
+    the project. Warnings are shown in reverse line number order.
+
+    ```
+    $ ~/.ghcup/bin/cabal-3.12.1.0 build all --dry-run
+    ...
+    Warning:
+    /.../ParseWarningProvenance/cabal.project,
+    cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
+    section '-' on line 123
+    /.../ParseWarningProvenance/cabal.project,
+    cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
+    section '-' on line 3
+    /.../ParseWarningProvenance/cabal.project,
+    cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
+    section '-' on line 2
+    /.../ParseWarningProvenance/cabal.project,
+    cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
+    section '-' on line 1
+    /.../ParseWarningProvenance/cabal.project,
+    cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
+    section '-' on line 123
+    /.../ParseWarningProvenance/cabal.project,
+    cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
+    section '-' on line 3
+    /.../ParseWarningProvenance/cabal.project,
+    cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
+    section '-' on line 2
+    /.../ParseWarningProvenance/cabal.project,
+    cabal.project, cabal.project, cabal.project, cabal.project: Unrecognized
+    section '-' on line 1
+    ```
+
+* After the fix:
+
+    The warnings are shown in a list. For warnings within the same `.project` or
+    imported `.config` file, warnings are sorted by line number. The file that
+    is the source of the warning is shown.
+
+    The warnings in import configuration files are shown in the order they were
+    imported by the project:
+
+    ```
+    $ cat cabal.project
+    packages: no-pkg-dir
+    import: dir-x/a.config
+    import: dir-y/a.config
+    import: x.config
+    import: y.config
+    ```
+
+    ```
+    $ cabal build all --dry-run
+    ...
+    Warnings found while parsing the project file, cabal.project:
+    - dir-x/a.config: Unrecognized section '-' on line 1
+    - dir-x/a.config: Unrecognized section '-' on line 2
+    - dir-x/a.config: Unrecognized section '-' on line 3
+    - dir-y/a.config: Unrecognized section '-' on line 123
+    - x.config: Unrecognized section '-' on line 1
+    - x.config: Unrecognized section '-' on line 2
+    - x.config: Unrecognized section '-' on line 3
+    - y.config: Unrecognized section '-' on line 123
+    ```
+
+## Error Messages from Project
+
+To trigger these error messages, the examples use badly formed conditions:
+
+```
+$ cat cabal.project
+-- The following failing condition is not on the first line so we can check the
+-- line number:
+if _
+```
+
+* Before the fix:
+
+    The parse error is shown with hard line breaks.
+
+    ```
+    $ ~/.ghcup/bin/cabal-3.12.1.0 build all --dry-run
+    ...
+    Error: [Cabal-7090]
+    Error parsing project file /.../ParseErrorProvenance/cabal.project:3:
+    "<condition>" (line 1, column 1):
+    unexpected SecArgName (Position 1 4) "_"
+    ```
+
+* After the fix:
+
+    The snippet that failed to parse may be shown and the parse error is shown
+    as one line, with no hard line breaks.
+
+    ```
+    $ cabal build all --dry-run
+    ...
+    Error: [Cabal-7090]
+    Error parsing project file cabal.project:3:
+    - Failed to parse 'if(_)' with error:
+        "<condition>" (line 1, column 1): unexpected SecArgName (Position 1 4) "_"
+    ```
+
+## Error Messages from Imported Config
+
+With the same setup but now with the error in an imported file:
+
+```
+$ cat elif.project
+import: dir-elif/elif.config
+
+$ cat dir-elif/elif.config
+-- The following failing condition is not on the first line so we can check the
+-- line number:
+if false
+elif _
+```
+
+* Before the fix:
+
+    The project rather than the imported configuration file is shown as the source file.
+
+    ```
+    $ ~/.ghcup/bin/cabal-3.12.1.0 build all --dry-run
+    ...
+    Error: [Cabal-7090]
+    Error parsing project file /.../ParseErrorProvenance/elif.project:4:
+    "<condition>" (line 1, column 1):
+    unexpected SecArgName (Position 1 6) "_"
+    ```
+
+* After the fix:
+
+    The imported configuration file is shown as the source with a snippet of the error.
+
+    ```
+    $ cabal build all --dry-run
+    ...
+    Error: [Cabal-7090]
+    Error parsing project file dir-elif/elif.config:4:
+      - dir-elif/elif.config
+          imported by: elif.project
+      - Failed to parse 'elif(_)' with error:
+        "<condition>" (line 1, column 1): unexpected SecArgName (Position 1 6) "_"
+    ```