refactor: improve help text for pyright-to-gitlab command

Author: schollm

src/pyright_to_gitlab.py

@@ -172,39 +172,43 @@ def cli() -> None:
     """Parse arguments and call the conversion function."""
     parser = argparse.ArgumentParser(
         description=textwrap.dedent("""
-            Convert pyright.json to GitLab Code Quality report.
-            By default, reads from stdin and writes to stdout."""),
+            Convert Pyright JSON output to a GitLab Code Quality report.
+
+            Input defaults to stdin and output defaults to stdout.
+            Use '-' explicitly for stdin/stdout when mixing with file paths."""),
         epilog=textwrap.dedent(
             """
-            # Example usage:
-              > pyright . --outputjson | pyright-to-gitlab > gitlab_code_quality.json
-              > pyright-to-gitlab -i pyright.json -o gitlab_code_quality.json
+            Examples:
+              pyright . --outputjson | pyright-to-gitlab > gl-code-quality.json
+              pyright-to-gitlab -i pyright.json -o gl-code-quality.json
+              pyright-to-gitlab --prefix backend/ -i pyright.json -o -
+              pyright-to-gitlab -i pyright.json --indent 0
             """
         ),
-        formatter_class=argparse.RawDescriptionHelpFormatter,
+        formatter_class=argparse.RawTextHelpFormatter,
     )
     parser.add_argument(
         "-i",
         "--input",
         type=str,
-        metavar="PYRIGHT_FILE",
+        metavar="INPUT",
         default="-",
-        help="Input file path (default: -). Use '-' to read from stdin.",
+        help="Path to Pyright JSON input (default: -). Use - to read from stdin.",
     )
     parser.add_argument(
         "-o",
         "--output",
         type=str,
         default="-",
-        metavar="GITLAB_CODE_QUALITY_FILE",
-        help="Output file path (default: '-'). Use '-' to write to stdout."
+        metavar="OUTPUT",
+        help="Path for GitLab Code Quality JSON (default: -). Use - to write to stdout.",
     )
     parser.add_argument(
         "--prefix",
         type=str,
+        metavar="PATH_PREFIX",
         default="",
-        help="Prefix path to add to each file entry. This can be used if pyright is run"
-        " from a subdirectory of the repository. (default: empty string)",
+        help="Prefix added to each reported file path, e.g. 'backend/' for monorepos.",
     )
     parser.add_argument("--version", action="version", version=f"%(prog)s {VERSION}")
     args = parser.parse_args()