Allow maximum-issues to be set via command-line

This change allows the maximum issues to be passed in as an argument.
If nothing is passed, then the existing build-in maximum is
used.

Retaining the existing built-in value makes sense for home
users to keep track of their local build (otherwise they would have
to remember the prior number of warnings and pass that value
in for subsequent builds).

Motivation: until now the built-in maximum covers the build permutation
that happens to generate the most warnings versus other builds.
In some cases new warnings may not be cause if they elicit a warning
from the lesser-warning build(s) or compilers, but not in the
maximum-warning build.

This change lets us tighten-down the warning uniquely for each build,
so we can be sure all new warnings are flagged to the developer.

scripts/count-warnings.py

@@ -2,29 +2,27 @@
 
 # Copyright (c) 2019 Patryk Obara <patryk.obara@gmail.com>
 # SPDX-License-Identifier: GPL-2.0-or-later
-
-# This script counts all compiler warnings and prints a summary.
 #
-# Usage: ./count-warnings.py build.log
-# Usage: cat "*.log" | ./count-warnings.py -
-#
-# note: new compilers include additional flag -fdiagnostics-format=[text|json],
-# which could be used instead of parsing using regex, but we want to preserve
-# human-readable output in standard log.
-
 # pylint: disable=invalid-name
 # pylint: disable=missing-docstring
 
+"""
+This script counts all compiler warnings and prints a summary.
+
+It returns success to the shell if the number or warnings encountered
+is less than or equal to the desired maximum warnings. See --help
+for a description of how to set the maximum.
+
+note: new compilers include additional flag -fdiagnostics-format=[text|json],
+which could be used instead of parsing using regex, but we want to preserve
+human-readable output in standard log.
+"""
+
+import argparse
 import os
 import re
 import sys
 
-# Maximum allowed number of issues; if build will include more warnings,
-# then script will return with status 1. Simply change this line if you
-# want to set a different limit.
-#
-MAX_ISSUES = 384
-
 # For recognizing warnings in GCC format in stderr:
 #
 WARNING_PATTERN = re.compile(r'([^:]+):(\d+):\d+: warning: .* \[-W(.+)\]')
@@ -76,20 +74,52 @@ def print_summary(issues):
             text=warning, count=count, field_size=size))
     print()
 
+def to_int(value):
+    return int(value) if value is not None else None
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        formatter_class=argparse.RawTextHelpFormatter, description=__doc__)
+
+    parser.add_argument(
+        'logfile',
+        metavar='LOGFILE',
+        help=("Path to the logfile, or use - to read from stdin"))
+
+    max_warnings = to_int(os.getenv('MAX_WARNINGS', None))
+    parser.add_argument(
+        '-m', '--max-warnings',
+        type=int,
+        required=not isinstance(max_warnings, int),
+        default=max_warnings,
+        help='Defines the maximum number of warnings permitted to exist\n'
+             'in the log file before returning a failure to the shell.\n'
+             'If not provided, the script will attempt to read it from\n'
+             'the MAX_WARNINGS environment variable, which is currently\n'
+             'set to: {}.  If a maximum of -1 is set then success is\n'
+             'always returned to the shell.\n\n'.format(str(max_warnings)))
+
+    return parser.parse_args()
 
 def main():
+    rcode = 0
     total = 0
     warning_types = {}
-    for line in get_input_lines(sys.argv[1]):
+    args = parse_args()
+    for line in get_input_lines(args.logfile):
         total += count_warning(line, warning_types)
     if warning_types:
         print("Warnings grouped by type:\n")
         print_summary(warning_types)
-    print('Total: {} warnings (out of {} allowed)\n'.format(total, MAX_ISSUES))
-    if total > MAX_ISSUES:
-        print('Error: upper limit of allowed warnings is', MAX_ISSUES)
-        sys.exit(1)
-
+    print('Total: {} warnings'.format(total), end='')
+    if args.max_warnings >= 0:
+        print(' (out of {} allowed)\n'.format(args.max_warnings))
+        if total > args.max_warnings:
+            print('Error: upper limit of allowed warnings is', args.max_warnings)
+            rcode = 1
+    else:
+        print('\n')
+    return rcode
 
 if __name__ == '__main__':
-    main()
+    sys.exit(main())