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,23 +12,59 @@
 # 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:
-    report_errors()
+    """
+    The primary entrypoint of the program.
+
+    Parses the CLI flags, and delegates to other functions as appropriate.
+    For details of how to invoke the program, call it with `--help`.
+    """
+    parser = argparse.ArgumentParser()
+    subparsers = parser.add_subparsers(title="subcommand")
+
+    parser.set_defaults(func=_no_command)
+
+    parse_parser = subparsers.add_parser(
+        "parse", help="Transform Mypy output into JSON."
+    )
 
+    parse_parser.set_defaults(func=_parse_command)
 
-def report_errors() -> None:
+    args = sys.argv[1:]
+    parsed = parser.parse_args(args)
+    parsed.func(parsed)
+
+
+def _parse_command(args: object) -> None:
+    """Handle the `parse` command."""
     errors = parse_errors_report(sys.stdin)
     error_json = json.dumps(errors, sort_keys=True, indent=2)
     print(error_json)
 
 
+def _no_command(args: object) -> None:
+    """
+    Handle the lack of an explicit command.
+
+    This will be hit when the program is called without arguments.
+    """
+    print("A subcommand is required. Pass --help for usage info.")
+    sys.exit(ErrorCodes.DEPRECATED)
+
+
 @dataclass(frozen=True)
 class MypyError:
     filename: str

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