reporters: add GithubReporter

Emit results as GitHub Actions workflow commands, so a CI scan renders
them as error/warning/notice annotations on the run summary and inline
in the pull request diff.

Signed-off-by: Arthur Zamarin <arthurzam@gentoo.org>

Author: arthurzam

NEWS.rst

@@ -25,6 +25,10 @@ pkgcheck 0.10.45 (unreleased)
   others, instead of alone on the main process once the rest had finished
   (Arthur Zamarin)
 
+- New ``GithubReporter``, emitting results as GitHub Actions workflow commands
+  so they render as error/warning/notice annotations on the run summary and
+  inline in pull request diffs (Arthur Zamarin)
+
 **Fixes:**
 
 - ``pkgcheck scan``: fail the scan when a worker process dies from a signal

src/pkgcheck/reporters.py

@@ -11,6 +11,7 @@
 
 from snakeoil.formatters import Formatter as snakeoil_Formatter
 from snakeoil.klass import immutable
+from snakeoil.mappings import ImmutableDict
 
 from . import base
 from .results import BaseLinesResult, InvalidResult, Result
@@ -379,6 +380,77 @@ def _consume_reports_generator(self) -> T_process_report:
                 self.out.write(f"{file}:{lineno}:{result.level}:{message}")
 
 
+class GithubReporter(StreamReporter):
+    """Reporter formatting results as GitHub Actions workflow commands [#]_.
+
+    Results are emitted as error, warning, or notice annotations anchored to
+    the relevant file and line, so they show up on the workflow run summary
+    and inline in pull request diffs.
+
+    .. [#] https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions
+    """
+
+    __slots__ = ()
+    priority = -1001
+
+    # result level to annotation level mapping, anything else is a notice
+    level_map = ImmutableDict({"error": "error", "warning": "warning"})
+    # scope to repo relative path mapping
+    path_map = ImmutableDict(
+        {
+            base.version_scope: "{category}/{package}/{package}-{version}.ebuild",
+            # results naming a file relative to the pkg/category dir point at it, the
+            # rest fall back to the dir itself once the trailing slash is stripped
+            base.package_scope: "{category}/{package}/{filename}",
+            base.category_scope: "{category}/{filename}",
+            base.eclass_scope: "eclass/{eclass}.eclass",
+            base.profiles_scope: "profiles/{path}",
+            base.profile_node_scope: "profiles/{path}",
+        }
+    )
+
+    @staticmethod
+    def _escape(s: str) -> str:
+        return s.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+    @classmethod
+    def _escape_property(cls, s: str) -> str:
+        return cls._escape(s).replace(":", "%3A").replace(",", "%2C")
+
+    def _consume_reports_generator(self) -> T_process_report:
+        while True:
+            result = yield
+            level = self.level_map.get(result.level, "notice")
+
+            file_prop = ()
+            if template := self.path_map.get(result.scope):
+                # missing attrs collapse to empty strings, leaving the enclosing dir
+                path = template.format_map(defaultdict(str, vars(result))).rstrip("/")
+                if path:
+                    file_prop = (f"file={self._escape_property(path)}",)
+            title_prop = f"title={self._escape_property(result.name)}"
+
+            desc = result.desc
+            if isinstance(result, BaseLinesResult):
+                # the line numbers are carried by the annotations themselves
+                desc = desc.replace(result.lines_str, "").strip()
+                linenos = result.lines
+            elif lineno := getattr(result, "lineno", 0):
+                linenos = (lineno,)
+            else:
+                linenos = ()
+
+            msg = self._escape(desc)
+            if linenos:
+                for lineno in linenos:
+                    props = ",".join(file_prop + (f"line={lineno}", title_prop))
+                    self.out.write(f"::{level} {props}::{msg}")
+            else:
+                props = ",".join(file_prop + (title_prop,))
+                self.out.write(f"::{level} {props}::{msg}")
+            self.out.stream.flush()
+
+
 class CallbackReporter(Reporter):
     """Reporter that calls back for every result"""
 

tests/test_reporters.py

@@ -219,6 +219,37 @@ class TestFlycheckReporter(BaseReporter):
     )
 
 
+class TestGithubReporter(BaseReporter):
+    reporter_cls = reporters.GithubReporter
+    add_report_output = dedent(
+        """\
+            ::warning file=profiles,title=ProfileWarning::profile warning
+            ::error file=profiles,title=ProfileError::profile error
+            ::notice title=InvalidCommitMessage::commit 8d86269bb4c7: no commit message
+            ::error file=dev-libs/metadata.xml,title=CatMissingMetadataXml::category is missing metadata.xml
+            ::error file=dev-libs/foo,title=InvalidPN::invalid package names: [ bar, baz ]
+            ::warning file=dev-libs/foo/foo-0.ebuild,title=BadFilename::bad filenames: [ 0.tar.gz, foo.tar.gz ]
+            ::warning file=dev-libs/foo/foo-0.ebuild,line=7,title=ReadonlyVariable::read-only variable 'P' assigned, line 7: P=6
+            ::warning file=dev-libs/foo/foo-0.ebuild,line=5,title=UnquotedVariable::unquoted variable D
+            ::warning file=dev-libs/foo/foo-0.ebuild,line=7,title=UnquotedVariable::unquoted variable D
+            """
+    )
+
+    def test_escapes(self, capsys):
+        result = metadata_xml.PkgInvalidXml(
+            "metadata.xml", "line 1: 100% bad\nline 2:", pkg=self.pkg
+        )
+        with self.mk_reporter() as report:
+            report(result)
+        out, err = capsys.readouterr()
+        assert not err
+        # colons are only escaped in property values, newlines and percents everywhere
+        assert out == (
+            "::error file=dev-libs/foo/metadata.xml,title=PkgInvalidXml::"
+            "package metadata.xml violates metadata.xsd:%0Aline 1: 100%25 bad%0Aline 2:\n"
+        )
+
+
 class TestCallbackReporter:
     results = BaseReporter.results