skip annotations for version results

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}"
+}