feat: support reasons for ignores (#258)

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

Author: henryiii

README.md

@@ -64,6 +64,8 @@ select = ["A", "B", "C100"]
 ignore = ["A100"]
 ```
 
+The ignore list can also be a table, with reasons for values.
+
 If `--select` or `--ignore` are given on the command line, they will override
 the `pyproject.toml` config. You can use `--extend-select` and `--extend-ignore`
 on the command line to extend the `pyproject.toml` config. These CLI options

docs/intro.md

@@ -51,10 +51,26 @@ You can explicitly list checks to select or skip in your `pyproject.toml`:
 
 ```toml
 [tool.repo-review]
-select = ["..."]
-ignore = ["..."]
+select = ["A", "B", "C100"]
+ignore = ["A100"]
 ```
 
+You can list the letter prefix or the exact check name. The ignore list can also
+be a table, with reasons for values. These will be shown explicitly in the report if
+a reason is given.
+
+```toml
+[tool.repo-review.ignore]
+A = "Skipping this whole family"
+B101 = "Skipping this specific check"
+C101 = ""  # Hidden from report, like a normal ignore
+```
+
+If `--select` or `--ignore` are given on the command line, they will override
+the `pyproject.toml` config. You can use `--extend-select` and `--extend-ignore`
+on the command line to extend the `pyproject.toml` config. These CLI options
+are comma separated.
+
 ## Pre-commit
 
 You can also use this from pre-commit:

src/repo_review/__main__.py

@@ -163,6 +163,13 @@ def rich_printer(
             msg.append(rich.text.Text.from_markup(description, style=style))
             if result.result is None:
                 msg.append(" [skipped]", style="yellow bold")
+                if result.skip_reason:
+                    sr_style = "yellow"
+                    msg.append(" (", style=sr_style)
+                    msg.append(
+                        rich.text.Text.from_markup(result.skip_reason, style=sr_style)
+                    )
+                    msg.append(")", style=sr_style)
                 tree.add(msg)
             elif result.result:
                 msg.append(rich.text.Text.from_markup(" :white_check_mark:"))

src/repo_review/checks.py

@@ -6,7 +6,7 @@
 
 from .fixtures import apply_fixtures
 
-__all__ = ["Check", "collect_checks", "get_check_url", "is_allowed"]
+__all__ = ["Check", "collect_checks", "get_check_url", "is_allowed", "name_matches"]
 
 
 def __dir__() -> list[str]:
@@ -70,6 +70,25 @@ def collect_checks(fixtures: Mapping[str, Any]) -> dict[str, Check]:
     }
 
 
+def name_matches(name: str, selectors: Set[str]) -> str:
+    """
+    Checks if the name is contained in the matchers. The selectors can be the
+    exact name or just the non-number prefix. Returns the selector that matched,
+    or an empty string if no match.
+
+    :param name: The name to check.
+    :param expr: The expression to check against.
+
+    :return: The matched selector if the name matches a selector, or an empty string if no match.
+    """
+    if name in selectors:
+        return name
+    short_name = name.rstrip("0123456789")
+    if short_name in selectors:
+        return short_name
+    return ""
+
+
 def is_allowed(select: Set[str], ignore: Set[str], name: str) -> bool:
     """
     Skips the check if the name is in the ignore list or if the name without the
@@ -82,15 +101,10 @@ def is_allowed(select: Set[str], ignore: Set[str], name: str) -> bool:
 
     :return: True if this check is allowed, False otherwise.
     """
-    if (
-        select
-        and name not in select
-        and name.rstrip("0123456789") not in select
-        and "*" not in select
-    ):
+    if select and not name_matches(name, select) and "*" not in select:
         return False
 
-    return name not in ignore and name.rstrip("0123456789") not in ignore
+    return not name_matches(name, ignore)
 
 
 def get_check_url(name: str, check: Check) -> str:

src/repo_review/html.py

@@ -61,7 +61,7 @@ def to_html(
                 else "red"
             )
             icon = (
-                "⚠️"
+                ("🔷" if result.skip_reason else "⚠️")
                 if result.result is None
                 else "✅"
                 if result.result
@@ -79,6 +79,11 @@ def to_html(
                 if result.url
                 else result.description
             )
+            if result.skip_reason:
+                description += (
+                    f'<br/><span style="color:DarkKhaki;"><b>Skipped:</b> '
+                    f"<em>{md.render(result.skip_reason)}</em></span>"
+                )
             print(f'<tr style="color: {color};">')
             print(f'<td><span role="img" aria-label="{result_txt}">{icon}</span></td>')
             print(f'<td nowrap="nowrap">{result.name}</td>')

src/repo_review/processor.py

@@ -17,6 +17,7 @@
     collect_checks,
     get_check_url,
     is_allowed,
+    name_matches,
     process_result_bool,
 )
 from .families import Family, collect_families
@@ -63,6 +64,7 @@ class ResultDict(typing.TypedDict):
     result: bool | None  #: The result, None means skip
     err_msg: str  #: The error message if the result is false, in markdown format
     url: str  #: An optional URL (empty string if missing)
+    skip_reason: str  #: The reason for the skip, if given (empty string if not)
 
 
 @dataclasses.dataclass(frozen=True, kw_only=True)
@@ -75,6 +77,7 @@ class Result:
     name: str  #: The name of the check
     description: str  #: The short description of what the check looks for
     result: bool | None  #: The result, None means skip
+    skip_reason: str = ""  #: The reason for the skip, if given
     err_msg: str = ""  #: The error message if the result is false, in markdown format
     url: str = ""  #: An optional URL (empty string if missing)
 
@@ -201,12 +204,12 @@ def process(
 
     # Collect our own config
     config = pyproject(package).get("tool", {}).get("repo-review", {})
+    ignore_pyproject: list[str] | dict[str, str] = config.get("ignore", [])
     select_checks = (
-        select if select else frozenset(config.get("select", ())) | extend_select
-    )
-    skip_checks = (
-        ignore if ignore else frozenset(config.get("ignore", ())) | extend_ignore
-    )
+        select if select else frozenset(config.get("select", ()))
+    ) | extend_select
+    skip_checks = (ignore if ignore else frozenset(ignore_pyproject)) | extend_ignore
+    skip_reasons = ignore_pyproject if isinstance(ignore_pyproject, dict) else {}
 
     # Make a graph of the check's interdependencies
     graph: dict[str, Set[str]] = {
@@ -240,9 +243,14 @@ def process(
         result = None if completed[task_name] is None else not completed[task_name]
         doc = check.__doc__ or ""
         err_msg = completed[task_name] or ""
+        skip_reason = ""
 
         if not is_allowed(select_checks, skip_checks, task_name):
-            continue
+            key = name_matches(task_name, skip_reasons.keys())
+            if not key or not skip_reasons.get(key, ""):
+                continue
+            result = None
+            skip_reason = skip_reasons[key]
 
         result_list.append(
             Result(
@@ -252,6 +260,7 @@ def process(
                 result=result,
                 err_msg=textwrap.dedent(err_msg),
                 url=get_check_url(task_name, check),
+                skip_reason=skip_reason,
             )
         )
 

tests/test_self.py

@@ -11,7 +11,9 @@ def patch_entry_points(local_entry_points: object) -> None:
 
 
 def test_pyproject() -> None:
-    families, results = repo_review.processor.process(Path())
+    families, results = repo_review.processor.process(
+        Path(), extend_ignore={"X", "PP303"}
+    )
 
     assert families == {
         "general": {},
@@ -26,7 +28,9 @@ def test_pyproject() -> None:
 
 
 def test_no_pyproject() -> None:
-    families, results = repo_review.processor.process(Path("tests"))
+    families, results = repo_review.processor.process(
+        Path("tests"), extend_ignore={"X", "PP303"}
+    )
 
     assert families == {
         "general": {},
@@ -58,12 +62,13 @@ def test_empty_pyproject() -> None:
             "description": "Has flit_core.buildapi backend",
             "name": "PyProject",
         },
+        "skipped": {},
     }
-    assert len(results) == 9
+    assert len(results) == 12
 
     assert (
         sum(result.result is None for result in results if result.family == "pyproject")
-        == 1
+        == 2
     )
     assert (
         sum(result.result for result in results if isinstance(result.result, bool)) == 6
@@ -72,3 +77,6 @@ def test_empty_pyproject() -> None:
         sum(result.result is None for result in results if result.family == "general")
         == 0
     )
+    assert sum(1 for result in results if result.skip_reason) == 3
+    assert sum(1 for result in results if result.skip_reason == "One skip") == 1
+    assert sum(1 for result in results if result.skip_reason == "Group skip") == 2

tests/test_utilities/pyproject.py

@@ -142,10 +142,51 @@ def check(pyproject: dict[str, Any]) -> bool:
         return "minversion" in options and float(options["minversion"]) >= 6
 
 
-def repo_review_checks() -> dict[str, PyProject | General]:
-    return {p.__name__: p() for p in PyProject.__subclasses__()} | {
+class PP999(PyProject):
+    "Skipped check (single)"
+
+    @staticmethod
+    def check() -> bool:
+        "Not used"
+        return False
+
+
+class X101:
+    "Skipped check (multi)"
+
+    family = "skipped"
+
+    @staticmethod
+    def check() -> bool:
+        "Not used"
+        return False
+
+
+class X102:
+    "Skipped check (multi)"
+
+    family = "skipped"
+
+    @staticmethod
+    def check() -> bool:
+        "Not used"
+        return False
+
+
+def repo_review_checks(
+    pyproject: dict[str, Any],
+) -> dict[str, PyProject | General | X101 | X102]:
+    ret = {p.__name__: p() for p in PyProject.__subclasses__()} | {
         p.__name__: p() for p in General.__subclasses__()
     }
+    extra_checks = (
+        pyproject.get("tool", {}).get("repo-review-local", {}).get("extra", False)
+    )
+    return (
+        (ret | {"X101": X101()} | {"X102": X102()})
+        if extra_checks
+        else {k: v for k, v in ret.items() if k != "PP999"}
+    )
 
 
 def repo_review_families(pyproject: dict[str, Any]) -> dict[str, dict[str, str]]:

tests/test_utilities/pyproject.toml

@@ -16,3 +16,11 @@ pyproject = "pyproject:repo_review_checks"
 pyproject = "pyproject:repo_review_families"
 
 [tool.example]
+
+
+[tool.repo-review.ignore]
+"PP999" = "One skip"
+"X" = "Group skip"
+
+[tool.repo-review-local]
+extra = true