Add “Ignore warning” option to cabal check

* Command line option: -i/--ignore.
    e.g.  cabal check --ignore=missing-upper-bounds  will not display
    “Missing upper bounds” warnings.

* Additionally, a filterPackageChecksById function is now exported
  in Distribution.PackageDescription.Check.Warning; this can be
  used by third party tools.

* Add CheckExplanationIDString to `cabal check` messages.
    e.g. from
      Error: The 'license' field is missing or is NONE.
    to
      Error: [license-none] The 'license' field is missing or is NONE.

    This makes using the cabal check `--ignore` option more immediate.

* Spool `MissingField` into separate constructors.
  Introducing five new constructors for `CheckExplanation`
    MissingFieldCategory
    MissingFieldMaintainer
    MissingFieldSynopsis
    MissingFieldDescription
    MissingFieldSynOrDesc
  This provides better ergonomic for `cabal check --ignore` and makes
  it easier to update the manual if the need arises.

* Add tests for desiderable `--ignore` string qualities (not too long,
  without too many '-', unique).

* Warn when `--ignore` string is not recognised.
    Also add a test for this.

* Add documentation.

* Add changelog.

Author: ffaf1

Cabal-tests/Cabal-tests.cabal

@@ -35,6 +35,7 @@ test-suite unit-tests
     UnitTests.Distribution.Compat.Graph
     UnitTests.Distribution.Compat.Time
     UnitTests.Distribution.Described
+    UnitTests.Distribution.PackageDescription.Check
     UnitTests.Distribution.PkgconfigVersion
     UnitTests.Distribution.Simple.Command
     UnitTests.Distribution.Simple.Glob

Cabal-tests/tests/ParserTests/regressions/all-upper-bound.check

@@ -1,4 +1,4 @@
-On library, these packages miss upper bounds:
+[missing-upper-bounds] On library, these packages miss upper bounds:
   - somelib
   - alphalib
   - betalib

Cabal-tests/tests/ParserTests/regressions/assoc-cpp-options.check

@@ -1 +1 @@
-'cpp-options: -traditional' is not a portable C-preprocessor flag.
+[cpp-options] 'cpp-options: -traditional' is not a portable C-preprocessor flag.

Cabal-tests/tests/ParserTests/regressions/bad-glob-syntax.check

@@ -1,2 +1,2 @@
-In the 'extra-source-files' field: invalid file glob 'foo/*/bar'. A wildcard '**' is only allowed as the final parent directory. Stars must not otherwise appear in the parent directories.
-In the 'extra-source-files' field: invalid file glob 'foo/blah-*.hs'. Wildcards '*' may only totally replace the file's base name, not only parts of it.
+[glob-syntax-error] In the 'extra-source-files' field: invalid file glob 'foo/*/bar'. A wildcard '**' is only allowed as the final parent directory. Stars must not otherwise appear in the parent directories.
+[glob-syntax-error] In the 'extra-source-files' field: invalid file glob 'foo/blah-*.hs'. Wildcards '*' may only totally replace the file's base name, not only parts of it.

Cabal-tests/tests/ParserTests/regressions/cc-options-with-optimization.check

@@ -1 +1 @@
-'cc-options: -O[n]' is generally not needed. When building with  optimisations Cabal automatically adds '-O2' for C code. Setting it yourself interferes with the --disable-optimization flag.
+[option-opt-c] 'cc-options: -O[n]' is generally not needed. When building with  optimisations Cabal automatically adds '-O2' for C code. Setting it yourself interferes with the --disable-optimization flag.

Cabal-tests/tests/ParserTests/regressions/cxx-options-with-optimization.check

@@ -1 +1 @@
-'cxx-options: -O[n]' is generally not needed. When building with  optimisations Cabal automatically adds '-O2' for C++ code. Setting it yourself interferes with the --disable-optimization flag.
+[option-opt-c] 'cxx-options: -O[n]' is generally not needed. When building with  optimisations Cabal automatically adds '-O2' for C++ code. Setting it yourself interferes with the --disable-optimization flag.

Cabal-tests/tests/ParserTests/regressions/decreasing-indentation.check

@@ -1,2 +1,2 @@
 decreasing-indentation.cabal:38:3: Inconsistent indentation. Indentation jumps at lines 38, 49, 56, 57, 69
-No 'main-is' field found for executable warnings
+[no-main-is] No 'main-is' field found for executable warnings

Cabal-tests/tests/ParserTests/regressions/denormalised-paths.check

@@ -1,14 +1,14 @@
-'hs-source-dirs: ../../assoc/src' is a relative path outside of the source tree. This will not work when generating a tarball with 'sdist'.
-The 'subdir' field of a source-repository is not a good relative path: "trailing same directory segment: ."
-'extra-source-files: files/**/*.txt/' is not a good relative path: "trailing slash"
-'extra-source-files: files/../foo.txt' is not a good relative path: "parent directory segment: .."
-'hs-source-dirs: ../../assoc/src' is not a good relative path: "parent directory segment: .."
-'hs-source-dirs: src/.' is not a good relative path: "trailing same directory segment: ."
-'hs-source-dirs: src/../../assoc/src' is not a good relative path: "parent directory segment: .."
-'hs-source-dirs: src/../src' is not a good relative path: "parent directory segment: .."
-'license-file: .' is not a good relative path: "trailing dot segment"
-'license-file: LICENSE2/' is not a good relative path: "trailing slash"
-The path 'C:foo/bar' is invalid on Windows, which would cause portability problems for this package. Windows file names cannot contain any of the characters ":*?<>|" and there a few reserved names including "aux", "nul", "con", "prn", "com1-9", "lpt1-9" and "clock$".
-The path 'c/**/*.c' is invalid on Windows, which would cause portability problems for this package. Windows file names cannot contain any of the characters ":*?<>|" and there a few reserved names including "aux", "nul", "con", "prn", "com1-9", "lpt1-9" and "clock$".
-The path 'files/<>/*.txt' is invalid on Windows, which would cause portability problems for this package. Windows file names cannot contain any of the characters ":*?<>|" and there a few reserved names including "aux", "nul", "con", "prn", "com1-9", "lpt1-9" and "clock$".
-The path '||s' is invalid on Windows, which would cause portability problems for this package. Windows file names cannot contain any of the characters ":*?<>|" and there a few reserved names including "aux", "nul", "con", "prn", "com1-9", "lpt1-9" and "clock$".
+[relative-path-outside] 'hs-source-dirs: ../../assoc/src' is a relative path outside of the source tree. This will not work when generating a tarball with 'sdist'.
+[repo-malformed-subdir] The 'subdir' field of a source-repository is not a good relative path: "trailing same directory segment: ."
+[malformed-relative-path] 'extra-source-files: files/**/*.txt/' is not a good relative path: "trailing slash"
+[malformed-relative-path] 'extra-source-files: files/../foo.txt' is not a good relative path: "parent directory segment: .."
+[malformed-relative-path] 'hs-source-dirs: ../../assoc/src' is not a good relative path: "parent directory segment: .."
+[malformed-relative-path] 'hs-source-dirs: src/.' is not a good relative path: "trailing same directory segment: ."
+[malformed-relative-path] 'hs-source-dirs: src/../../assoc/src' is not a good relative path: "parent directory segment: .."
+[malformed-relative-path] 'hs-source-dirs: src/../src' is not a good relative path: "parent directory segment: .."
+[malformed-relative-path] 'license-file: .' is not a good relative path: "trailing dot segment"
+[malformed-relative-path] 'license-file: LICENSE2/' is not a good relative path: "trailing slash"
+[invalid-path-win] The path 'C:foo/bar' is invalid on Windows, which would cause portability problems for this package. Windows file names cannot contain any of the characters ":*?<>|" and there a few reserved names including "aux", "nul", "con", "prn", "com1-9", "lpt1-9" and "clock$".
+[invalid-path-win] The path 'c/**/*.c' is invalid on Windows, which would cause portability problems for this package. Windows file names cannot contain any of the characters ":*?<>|" and there a few reserved names including "aux", "nul", "con", "prn", "com1-9", "lpt1-9" and "clock$".
+[invalid-path-win] The path 'files/<>/*.txt' is invalid on Windows, which would cause portability problems for this package. Windows file names cannot contain any of the characters ":*?<>|" and there a few reserved names including "aux", "nul", "con", "prn", "com1-9", "lpt1-9" and "clock$".
+[invalid-path-win] The path '||s' is invalid on Windows, which would cause portability problems for this package. Windows file names cannot contain any of the characters ":*?<>|" and there a few reserved names including "aux", "nul", "con", "prn", "com1-9", "lpt1-9" and "clock$".

Cabal-tests/tests/ParserTests/regressions/extensions-paths-5054.check

@@ -1 +1 @@
-Packages using RebindableSyntax with OverloadedStrings or OverloadedLists in default-extensions, in conjunction with the autogenerated module Paths_*, are known to cause compile failures with Cabal < 2.2. To use these default-extensions with a Paths_* autogen module, specify at least 'cabal-version: 2.2'.
+[rebindable-clash-paths] Packages using RebindableSyntax with OverloadedStrings or OverloadedLists in default-extensions, in conjunction with the autogenerated module Paths_*, are known to cause compile failures with Cabal < 2.2. To use these default-extensions with a Paths_* autogen module, specify at least 'cabal-version: 2.2'.

Cabal-tests/tests/ParserTests/regressions/ghc-option-j.check

@@ -1,2 +1,2 @@
-'ghc-options: -j[N]' can make sense for a particular user's setup, but it is not appropriate for a distributed package. Alternatively, if you want to use this, make it conditional based on a Cabal configuration flag (with 'manual: True' and 'default: False') and enable that flag during development.
-'ghc-shared-options: -j[N]' can make sense for a particular user's setup, but it is not appropriate for a distributed package. Alternatively, if you want to use this, make it conditional based on a Cabal configuration flag (with 'manual: True' and 'default: False') and enable that flag during development.
+[unneeded-j] 'ghc-options: -j[N]' can make sense for a particular user's setup, but it is not appropriate for a distributed package. Alternatively, if you want to use this, make it conditional based on a Cabal configuration flag (with 'manual: True' and 'default: False') and enable that flag during development.
+[unneeded-j] 'ghc-shared-options: -j[N]' can make sense for a particular user's setup, but it is not appropriate for a distributed package. Alternatively, if you want to use this, make it conditional based on a Cabal configuration flag (with 'manual: True' and 'default: False') and enable that flag during development.