Add --allow-errors option

This option can be used as a ratchet [1] to make it easier to adopt
docstub gradually. Basically, limit the allowed number of errors and
decrease it when errors are fixed. This should prevent unrelated
development efforts from adding new errors.

[1] https://qntm.org/ratchet

Author: lagru

src/docstub/_cli.py

@@ -132,37 +132,55 @@ def report_execution_time():
 
 @click.command()
 @click.version_option(__version__)
-@click.argument("root_path", type=click.Path(exists=True))
+@click.argument("root_path", type=click.Path(exists=True), metavar="PACKAGE_PATH")
 @click.option(
     "-o",
     "--out-dir",
     type=click.Path(file_okay=False),
+    metavar="PATH",
     help="Set output directory explicitly.",
 )
 @click.option(
     "--config",
     "config_path",
     type=click.Path(exists=True, dir_okay=False),
+    metavar="PATH",
     help="Set configuration file explicitly.",
 )
 @click.option(
     "--group-errors",
     is_flag=True,
-    help="Group errors by type and content. "
-    "Will delay showing errors until all files have been processed.",
+    help="Group identical errors together and list where they occured. "
+    "Will delay showing errors until all files have been processed. "
+    "Otherwise, simply report errors as the occur.",
 )
-@click.option("-v", "--verbose", count=True, help="Log more details.")
+@click.option(
+    "--allow-errors",
+    type=click.IntRange(min=0),
+    default=0,
+    show_default=True,
+    metavar="INT",
+    help="Allow this many or fewer errors. "
+    "If docstub reports more, exit with error code '1'.",
+)
+@click.option("-v", "--verbose", count=True, help="Print more details (repeatable).")
 @click.help_option("-h", "--help")
 @report_execution_time()
-def main(root_path, out_dir, config_path, group_errors, verbose):
-    """Generate Python stub files from docstrings.
+def main(root_path, out_dir, config_path, group_errors, allow_errors, verbose):
+    """Generate Python stub files with type annotations from docstrings.
+
+    Given a path `PACKAGE_PATH` to a Python package, generate stub files for it.
+    Type descriptions in docstrings will be used to fill in missing inline type
+    annotations or to override them.
     \f
 
     Parameters
     ----------
     source_dir : Path
     out_dir : Path
     config_path : Path
+    group_errors : bool
+    allow_errors : int
     verbose : str
     """
 
@@ -232,10 +250,18 @@ def main(root_path, out_dir, config_path, group_errors, verbose):
 
     unknown_doctypes = types_db.stats["unknown_doctypes"]
     if unknown_doctypes:
-        click.secho(f"{len(unknown_doctypes)} unknown doctypes:", fg="red")
+        click.secho(f"{len(unknown_doctypes)} unknown doctypes", fg="red")
         counter = Counter(unknown_doctypes)
-        for item, count in sorted(counter.items(), key=lambda x: x[1]):
+        sorted_item_counts = sorted(counter.items(), key=lambda x: x[1], reverse=True)
+        for item, count in sorted_item_counts:
             click.echo(f"  {item} (x{count})")
 
-    if unknown_doctypes or syntax_error_count:
+    total_errors = len(unknown_doctypes) + syntax_error_count
+    total_msg = f"{total_errors} total errors"
+    if allow_errors:
+        total_msg = f"{total_msg} (allowed {allow_errors})"
+    click.secho(total_msg, bold=True)
+
+    if allow_errors < total_errors:
+        logger.debug("number of allowed errors %i was exceeded")
         sys.exit(1)