Require "parse" subcommand when calling

We intend to add more functionality to this tool, so it no longer makes
sense to have the error parsing functionality at the top level when
calling the script.

This change introduces (and requires) a new "parse" subcommand, under
which the existing parsing function is moved.

Because we're using argparse to do this, we also get a new "--help" flag
on the command.

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- *Action required:* Move existing behaviour under "parse" subcommand.
+  Invocations of `mypy-json-report` should now be replaced with `mypy-json-report parse`.
 - Use GA version of Python 3.11 in test matrix.
 
 ## v0.1.3 [2022-09-07]

README.md

@@ -14,7 +14,7 @@ Pipe the output of mypy through the `mypy-json-report` CLI app.
 Store the output to a file, and commit it to your git repo.
 
 ```
-mypy . --strict | mypy-json-report > known-mypy-errors.json
+mypy . --strict | mypy-json-report parse > known-mypy-errors.json
 git add known-mypy-errors.json
 git commit -m "Add mypy errors lockfile"
 ```
@@ -80,7 +80,7 @@ jobs:
 
       - name: Run mypy
         run: |
-          mypy . --strict | mypy-json-report > known-mypy-errors.json
+          mypy . --strict | mypy-json-report parse > known-mypy-errors.json
 
       - name: Check for mypy changes
         run: |

mypy_json_report.py

@@ -12,17 +12,45 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import argparse
+import enum
 import json
 import sys
 from collections import Counter, defaultdict
 from dataclasses import dataclass
 from typing import Counter as CounterType, Dict, Iterator
 
 
+class ErrorCodes(enum.IntEnum):
+    DEPRECATED = 1
+
+
 def main() -> None:
+    parser = argparse.ArgumentParser()
+    subparsers = parser.add_subparsers(title="subcommand")
+
+    parser.set_defaults(func=_deprecated_command)
+
+    parse_parser = subparsers.add_parser(
+        "parse", help="Transform Mypy output into JSON."
+    )
+
+    parse_parser.set_defaults(func=_parser_command)
+
+    args = sys.argv[1:]
+    parsed = parser.parse_args(args)
+    parsed.func(parsed)
+
+
+def _parser_command(args: object) -> None:
     report_errors()
 
 
+def _deprecated_command(args: object) -> None:
+    print("A subcommand is required. Pass --help for usage info.")
+    sys.exit(ErrorCodes.DEPRECATED)
+
+
 def report_errors() -> None:
     errors = parse_errors_report(sys.stdin)
     error_json = json.dumps(errors, sort_keys=True, indent=2)

tox.ini

@@ -39,5 +39,5 @@ allowlist_externals =
 commands_pre =
     poetry install
 commands =
-    poetry run bash -c "mypy . --strict | mypy-json-report > known-mypy-errors.json"
+    poetry run bash -c "mypy . --strict | mypy-json-report parse > known-mypy-errors.json"
     git diff --exit-code known-mypy-errors.json