Add “Ignore warning” option to cabal check

* Introduce `-i/--ignore` command-line option.
    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.

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.

Cabal-tests/tests/ParserTests/regressions/issue-6288-d.check

@@ -1 +1 @@
-Packages using 'cabal-version: >= 1.10' and before 'cabal-version: 3.4' must specify the 'default-language' field for each component (e.g. Haskell98 or Haskell2010). If a component uses different languages in different modules then list the other ones in the 'other-languages' field.
+[no-default-language] Packages using 'cabal-version: >= 1.10' and before 'cabal-version: 3.4' must specify the 'default-language' field for each component (e.g. Haskell98 or Haskell2010). If a component uses different languages in different modules then list the other ones in the 'other-languages' field.

Cabal-tests/tests/ParserTests/regressions/issue-774.check

@@ -1,6 +1,6 @@
 issue-774.cabal:13:22: Packages with 'cabal-version: 1.12' or later should specify a specific version of the Cabal spec of the form 'cabal-version: x.y'. Use 'cabal-version: 1.12'.
-'ghc-options: -rtsopts' has no effect for libraries. It should only be used for executables.
-'ghc-options: -with-rtsopts' has no effect for libraries. It should only be used for executables.
-No 'category' field.
-No 'maintainer' field.
-The 'license' field is missing or is NONE.
+[option-rtsopts] 'ghc-options: -rtsopts' has no effect for libraries. It should only be used for executables.
+[option-with-rtsopts] 'ghc-options: -with-rtsopts' has no effect for libraries. It should only be used for executables.
+[no-category] No 'category' field.
+[no-maintainer] No 'maintainer' field.
+[license-none] The 'license' field is missing or is NONE.

Cabal-tests/tests/ParserTests/regressions/issue-7776-a.check

@@ -1 +1 @@
-Potential duplicate modules (subject to conditionals) in library: GHC.Hs.Type
+[maybe-duplicate-modules] Potential duplicate modules (subject to conditionals) in library: GHC.Hs.Type

Cabal-tests/tests/ParserTests/regressions/issue-7776-b.check

@@ -1 +1 @@
-Potential duplicate modules (subject to conditionals) in benchmark: Data.Hashable.RandomSource
+[maybe-duplicate-modules] Potential duplicate modules (subject to conditionals) in benchmark: Data.Hashable.RandomSource

Cabal-tests/tests/ParserTests/regressions/issue-7776-c.check

@@ -1 +1 @@
-Duplicate modules in library: GHC.Hs.Type
+[duplicate-modules] Duplicate modules in library: GHC.Hs.Type

Cabal-tests/tests/ParserTests/regressions/multiple-libs-2.check

@@ -1,6 +1,6 @@
 multiple-libs-2.cabal:17:3: The field "visibility" is available only since the Cabal specification version 3.0. This field will be ignored.
-No 'category' field.
-No 'maintainer' field.
-No 'description' field.
-The 'license' field is missing or is NONE.
-The dependency 'build-depends: base' does not specify an upper bound on the version number. Each major release of the 'base' package changes the API in various ways and most packages will need some changes to compile with it. The recommended practice is to specify an upper bound on the version of the 'base' package. This ensures your package will continue to build when a new major version of the 'base' package is released. If you are not sure what upper bound to use then use the next  major version. For example if you have tested your package with 'base' version 4.5 and 4.6 then use 'build-depends: base >= 4.5 && < 4.7'.
+[no-category] No 'category' field.
+[no-maintainer] No 'maintainer' field.
+[no-description] No 'description' field.
+[license-none] The 'license' field is missing or is NONE.
+[missing-bounds-important] The dependency 'build-depends: base' does not specify an upper bound on the version number. Each major release of the 'base' package changes the API in various ways and most packages will need some changes to compile with it. The recommended practice is to specify an upper bound on the version of the 'base' package. This ensures your package will continue to build when a new major version of the 'base' package is released. If you are not sure what upper bound to use then use the next  major version. For example if you have tested your package with 'base' version 4.5 and 4.6 then use 'build-depends: base >= 4.5 && < 4.7'.

Cabal-tests/tests/ParserTests/regressions/nothing-unicode.check

@@ -1,6 +1,6 @@
-No 'category' field.
-No 'maintainer' field.
-No 'description' field.
-The 'license' field is missing or is NONE.
-Suspicious flag names: 無. To avoid ambiguity in command line interfaces, a flag shouldn't start with a dash. Also for better compatibility, flag names shouldn't contain non-ascii characters.
-Non ascii custom fields: x-無. For better compatibility, custom field names shouldn't contain non-ascii characters.
+[no-category] No 'category' field.
+[no-maintainer] No 'maintainer' field.
+[no-description] No 'description' field.
+[license-none] The 'license' field is missing or is NONE.
+[suspicious-flag] Suspicious flag names: 無. To avoid ambiguity in command line interfaces, a flag shouldn't start with a dash. Also for better compatibility, flag names shouldn't contain non-ascii characters.
+[non-ascii] Non ascii custom fields: x-無. For better compatibility, custom field names shouldn't contain non-ascii characters.

Cabal-tests/tests/ParserTests/regressions/pre-1.6-glob.check

@@ -1 +1 @@
-In the 'extra-source-files' field: invalid file glob 'foo/*.hs'. Using star wildcards requires 'cabal-version: >= 1.6'. Alternatively if you require compatibility with earlier Cabal versions then list all the files explicitly.
+[glob-syntax-error] In the 'extra-source-files' field: invalid file glob 'foo/*.hs'. Using star wildcards requires 'cabal-version: >= 1.6'. Alternatively if you require compatibility with earlier Cabal versions then list all the files explicitly.

Cabal-tests/tests/ParserTests/regressions/pre-2.4-globstar.check

@@ -1,3 +1,3 @@
-In the 'data-files' field: invalid file glob 'foo/**/*.dat'. Using the double-star syntax requires 'cabal-version: 2.4' or greater. Alternatively, for compatibility with earlier Cabal versions, list the included directories explicitly.
-In the 'extra-doc-files' field: invalid file glob 'foo/**/*.html'. Using the double-star syntax requires 'cabal-version: 2.4' or greater. Alternatively, for compatibility with earlier Cabal versions, list the included directories explicitly.
-In the 'extra-source-files' field: invalid file glob 'foo/**/*.hs'. Using the double-star syntax requires 'cabal-version: 2.4' or greater. Alternatively, for compatibility with earlier Cabal versions, list the included directories explicitly.
+[glob-syntax-error] In the 'data-files' field: invalid file glob 'foo/**/*.dat'. Using the double-star syntax requires 'cabal-version: 2.4' or greater. Alternatively, for compatibility with earlier Cabal versions, list the included directories explicitly.
+[glob-syntax-error] In the 'extra-doc-files' field: invalid file glob 'foo/**/*.html'. Using the double-star syntax requires 'cabal-version: 2.4' or greater. Alternatively, for compatibility with earlier Cabal versions, list the included directories explicitly.
+[glob-syntax-error] In the 'extra-source-files' field: invalid file glob 'foo/**/*.hs'. Using the double-star syntax requires 'cabal-version: 2.4' or greater. Alternatively, for compatibility with earlier Cabal versions, list the included directories explicitly.

Cabal-tests/tests/ParserTests/regressions/pre-3.8-globstar-literal.check

@@ -1 +1 @@
-In the 'extra-source-files' field: invalid file glob 'foo/**/bar'. Prior to 'cabal-version: 3.8' if a wildcard '**' is used as a parent directory, the file's base name must be a wildcard '*'.
+[glob-syntax-error] In the 'extra-source-files' field: invalid file glob 'foo/**/bar'. Prior to 'cabal-version: 3.8' if a wildcard '**' is used as a parent directory, the file's base name must be a wildcard '*'.

Cabal-tests/tests/ParserTests/regressions/public-multilib-1.check

@@ -1,2 +1,2 @@
-No 'maintainer' field.
-No 'description' field.
+[no-maintainer] No 'maintainer' field.
+[no-description] No 'description' field.

Cabal-tests/tests/ParserTests/regressions/public-multilib-2.check

@@ -1,2 +1,2 @@
-No 'maintainer' field.
-No 'description' field.
+[no-maintainer] No 'maintainer' field.
+[no-description] No 'description' field.

Cabal-tests/tests/UnitTests.hs

@@ -15,6 +15,7 @@ import Distribution.Compat.Time
 
 import qualified UnitTests.Distribution.Compat.Time
 import qualified UnitTests.Distribution.Compat.Graph
+import qualified UnitTests.Distribution.PackageDescription.Check
 import qualified UnitTests.Distribution.Simple.Command
 import qualified UnitTests.Distribution.Simple.Glob
 import qualified UnitTests.Distribution.Simple.Program.GHC
@@ -62,6 +63,8 @@ tests mtimeChangeCalibrated =
         UnitTests.Distribution.Utils.Json.tests
     , testGroup "Distribution.Utils.NubList"
         UnitTests.Distribution.Utils.NubList.tests
+    , testGroup "Distribution.PackageDescription.Check"
+        UnitTests.Distribution.PackageDescription.Check.tests
     , testGroup "Distribution.Utils.ShortText"
         UnitTests.Distribution.Utils.ShortText.tests
     , testGroup "Distribution.System"

Cabal-tests/tests/UnitTests/Distribution/PackageDescription/Check.hs

@@ -0,0 +1,34 @@
+module UnitTests.Distribution.PackageDescription.Check (tests) where
+
+import Distribution.Compat.Prelude.Internal
+import Prelude ()
+
+import Distribution.PackageDescription.Check
+
+import Test.Tasty
+import Test.Tasty.HUnit
+
+-- instances
+import Test.QuickCheck.Instances.Cabal ()
+
+
+tests :: [TestTree]
+tests =
+    [ testCase "Unique ignore strings" (uniqueNames @?= True)
+    , testCase "Short ignore identifiers" (longerThan @?= [])
+    , testCase "Parsimonious '-' use" (usingTooManyDashes @?= [])
+    ]
+  where
+    allExplanationIdStrings :: [CheckExplanationIDString]
+    allExplanationIdStrings = map ppCheckExplanationId [minBound..maxBound]
+
+    uniqueNames :: Bool
+    uniqueNames = length allExplanationIdStrings == length (nub allExplanationIdStrings)
+
+    longerThan :: [CheckExplanationIDString]
+    longerThan = filter ((>25). length) allExplanationIdStrings
+
+    usingTooManyDashes :: [CheckExplanationIDString]
+    usingTooManyDashes = filter ((>2) . length . filter (=='-'))
+                           allExplanationIdStrings
+

Cabal/src/Distribution/PackageDescription/Check.hs

@@ -23,12 +23,17 @@
 module Distribution.PackageDescription.Check
   ( -- * Package Checking
     CheckExplanation (..)
+  , CheckExplanationID
+  , CheckExplanationIDString
   , PackageCheck (..)
   , checkPackage
   , checkConfiguredPackage
   , wrapParseWarning
   , ppPackageCheck
+  , ppCheckExplanationId
   , isHackageDistError
+  , filterPackageChecksById
+  , filterPackageChecksByIdString
 
     -- ** Checking package contents
   , checkPackageFiles
@@ -52,6 +57,7 @@ import Distribution.PackageDescription.Check.Conditional
 import Distribution.PackageDescription.Check.Monad
 import Distribution.PackageDescription.Check.Paths
 import Distribution.PackageDescription.Check.Target
+import Distribution.PackageDescription.Check.Warning
 import Distribution.Parsec.Warning (PWarning)
 import Distribution.Pretty (prettyShow)
 import Distribution.Simple.Glob
@@ -416,19 +422,19 @@ checkPackageDescription
     -- § Fields check.
     checkNull
       category_
-      (PackageDistSuspicious $ MissingField CEFCategory)
+      (PackageDistSuspicious MissingFieldCategory)
     checkNull
       maintainer_
-      (PackageDistSuspicious $ MissingField CEFMaintainer)
+      (PackageDistSuspicious MissingFieldMaintainer)
     checkP
       (ShortText.null synopsis_ && not (ShortText.null description_))
-      (PackageDistSuspicious $ MissingField CEFSynopsis)
+      (PackageDistSuspicious MissingFieldSynopsis)
     checkP
       (ShortText.null description_ && not (ShortText.null synopsis_))
-      (PackageDistSuspicious $ MissingField CEFDescription)
+      (PackageDistSuspicious MissingFieldDescription)
     checkP
       (all ShortText.null [synopsis_, description_])
-      (PackageDistInexcusable $ MissingField CEFSynOrDesc)
+      (PackageDistInexcusable MissingFieldSynOrDesc)
     checkP
       (ShortText.length synopsis_ > 80)
       (PackageDistSuspicious SynopsisTooLong)

Cabal/src/Distribution/PackageDescription/Check/Monad.hs

@@ -22,7 +22,6 @@ module Distribution.PackageDescription.Check.Monad
   , TargetAnnotation (..)
   , PackageCheck (..)
   , CheckExplanation (..)
-  , CEField (..)
   , CEType (..)
   , WarnLang (..)
   , CheckCtx (..)