skip annotations for version results

Add support for an ebuild to declare a skip annotation for a class of
*version* results. This skip annotation must be declared before any
non-comment non-empty line (most of the times it would be before the
EAPI declaration). Empty lines between the copyright and the annotation
are allowed.
The annotation line must be precise, only one class per line and every
space is required.

For example, it would look like:

  # Copyright 2023 Gentoo Authors
  # Distributed under the terms of the GNU General Public License v2

  # pkgcheck skip: PythonCompatUpdate

  EAPI=8

Resolves: pkgcore#478
Signed-off-by: Arthur Zamarin <[email protected]>

Author: arthurzam

doc/index.rst

@@ -10,6 +10,18 @@ Contents:
     news
     api
     man/pkgcheck
+    man/pkgcheck/scan
+    man/pkgcheck/keywords
+    man/pkgcheck/checks
+    man/config
+    man/skip
+
+Reporting Bugs
+==============
+
+Please submit an issue via github:
+
+https://github.com/pkgcore/pkgcheck/issues
 
 Indices and tables
 ==================

doc/man/pkgcheck.rst

@@ -12,6 +12,7 @@ pkgcheck
 .. include:: pkgcheck/reporters.rst
 
 .. include:: config.rst
+.. include:: skip.rst
 
 Reporting Bugs
 ==============

doc/man/skip.rst

@@ -0,0 +1,28 @@
+Skip results annotations
+========================
+
+pkgcheck supports skipping ebuilds results via special annotation. This is
+useful in cases where you are aware of false positive in pkgcheck check, and
+fixing pkgcheck is hard or impossible.
+
+The annotation must appear in the ebuild before any non-comment non-empty line
+(most of the times it would be just before the EAPI declaration line and after
+the copyright lines). Empty lines between the copyright and the annotation are
+allowed.
+
+You can't skip *error* level results. Skipping *warning* level results requires
+QA team member approval (should include name and RFC 3339 data). *info* and
+*style* level can be skipped without approval. Do consider to just ignore them
+instead of skipping.
+
+An example of skipping a *info* and *warning* level results::
+
+    # Copyright 2023 Gentoo Authors
+    # Distributed under the terms of the GNU General Public License v2
+
+    # pkgcheck skip: PythonCompatUpdate
+
+    # Approved by larry 2023-04-31
+    # pkgcheck skip: VariableScope
+
+    EAPI=8

src/pkgcheck/results.py

@@ -225,6 +225,12 @@ def __init__(self, pkg, **kwargs):
         self.version = pkg.fullver
         self._attr = "version"
 
+        if (
+            self.__class__.__name__ in getattr(pkg, "skipped_results", ())
+            and getattr(self, "level", "") != "error"
+        ):
+            self._filtered = True
+
     @klass.jit_attr
     def ver_rev(self):
         version, _, revision = self.version.partition("-r")

src/pkgcheck/sources.py

@@ -292,13 +292,21 @@ def itermatch(self, restrict, **kwargs):
 class _SourcePkg(WrappedPkg):
     """Package object with file contents injected as an attribute."""
 
-    __slots__ = ("lines",)
+    __slots__ = ("lines", "skipped_results")
 
     def __init__(self, pkg):
         super().__init__(pkg)
         with pkg.ebuild.text_fileobj() as fileobj:
             self.lines = tuple(fileobj)
 
+            skipped_results: set[str] = set()
+            for line in map(str.rstrip, self.lines):
+                if line and not line.startswith("#"):
+                    break  # stop after first non-comment non-empty line
+                elif line.startswith("# pkgcheck skip:"):
+                    skipped_results.add(line[16:].strip())
+            self.skipped_results = frozenset(skipped_results)
+
 
 class EbuildFileRepoSource(RepoSource):
     """Ebuild repository source yielding package objects and their file contents."""
@@ -311,6 +319,17 @@ def itermatch(self, restrict, **kwargs):
 class _ParsedPkg(ParseTree, WrappedPkg):
     """Parsed package object."""
 
+    def __init__(self, data: bytes, **kwargs):
+        super().__init__(data, **kwargs)
+
+        skipped_results: set[str] = set()
+        for line in data.splitlines():
+            if line and not line.startswith(b"#"):
+                break  # stop after first non-comment non-empty line
+            elif line.startswith(b"# pkgcheck skip:"):
+                skipped_results.add(line[16:].strip().decode("utf8"))
+        self.skipped_results = frozenset(skipped_results)
+
 
 class EbuildParseRepoSource(RepoSource):
     """Ebuild repository source yielding parsed packages."""

testdata/repos/standalone/DoCompressedFilesCheck/InstallCompressedInfo/InstallCompressedInfo-1.ebuild

@@ -0,0 +1,13 @@
+# pkgcheck skip: InstallCompressedInfo
+
+EAPI=7
+
+DESCRIPTION="Ebuild installing compressed info, but with result marked skipped"
+HOMEPAGE="https://github.com/pkgcore/pkgcheck"
+SLOT="0"
+LICENSE="BSD"
+
+src_install() {
+	doinfo 'test.gz' "${PN}.bz2"
+	doinfo "${PN}"
+}