GitHub annotations (#432)

* Add GitHub annotation generator

* Rename to github-annotations

* Add (unused) annotations type

* Formatting

* Adds open_file() and updates tests

* Adds ability to use stdout and stderr in --format

* Adds missing tests

* Updates test_report_generator.py to be more pytest-ic

* Expose the issues to the PR

* Fully tested

* Adds more tests

* chore: rename format argument to github-annotations

* Rename another instance of github to github-annotations

* Rename file to remove reference to warning, update doc string

* Undo change to open_file

* Remove github-annotations error type for CI coverage job

* Remove default as it does not work

---------

Co-authored-by: kingbuzzman <buzzi.javier@gmail.com>

Author: timkrins

.github/workflows/verify.yaml

@@ -97,7 +97,7 @@ jobs:
           cp .coverage htmlcov/.coverage
       - name: Complete coverage
         run: |
-          poetry run diff-cover coverage.xml --include-untracked
+          poetry run diff-cover coverage.xml --include-untracked --format github-annotations:warning
           poetry run diff-quality --violations flake8 --include-untracked
           poetry run diff-quality --violations pylint --include-untracked
       - name: Upload single coverage artifact

diff_cover/diff_cover_tool.py

@@ -12,6 +12,7 @@
 from diff_cover.git_diff import GitDiffFileTool, GitDiffTool
 from diff_cover.git_path import GitPathTool
 from diff_cover.report_generator import (
+    GitHubAnnotationsReportGenerator,
     HtmlReportGenerator,
     JsonReportGenerator,
     MarkdownReportGenerator,
@@ -269,6 +270,15 @@ def generate_coverage_report(
         with open_file(markdown_report, "wb") as output_file:
             reporter.generate_report(output_file)
 
+    if "github-annotations" in report_formats:
+        # Github annotations are always written to stdout, but we can use different types
+        reporter = GitHubAnnotationsReportGenerator(
+            coverage,
+            diff,
+            report_formats["github-annotations"],
+        )
+        reporter.generate_report(sys.stdout.buffer)
+
     # Generate the report for stdout
     reporter = StringReportGenerator(coverage, diff, show_uncovered)
     output_file = io.BytesIO() if quiet else sys.stdout.buffer

diff_cover/report_generator.py

@@ -420,6 +420,27 @@ def __init__(self, violations_reporter, diff_reporter, show_uncovered=False):
         self.include_snippets = show_uncovered
 
 
+class GitHubAnnotationsReportGenerator(TemplateReportGenerator):
+    """
+    Generate a diff coverage report for GitHub annotations.
+    https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-a-debug-message
+    https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-a-notice-message
+    https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-a-warning-message
+    https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-error-message
+    """
+
+    template_path = "github_coverage_annotations.txt"
+
+    def __init__(self, violations_reporter, diff_reporter, annotations_type):
+        super().__init__(violations_reporter, diff_reporter)
+        self.annotations_type = annotations_type
+
+    def _context(self):
+        context = super().report_dict()
+        context.update({"annotations_type": self.annotations_type})
+        return context
+
+
 class HtmlReportGenerator(TemplateReportGenerator):
     """
     Generate an HTML formatted diff coverage report.

diff_cover/templates/github_coverage_annotations.txt

@@ -0,0 +1,10 @@
+{% if src_stats %}
+{% for src_path, stats in src_stats|dictsort %}
+{% if stats.percent_covered < 100 %}
+{% for line in stats.violation_lines %}
+{% set splitLines = line.split("-") %}
+::{{ annotations_type }} file={{ src_path }},line={{ splitLines[0] }}{% if splitLines[1] %},endLine={{ splitLines[1] }}{% endif %},title=Missing Coverage::Line {{ line }} missing coverage
+{% endfor %}
+{% endif %}
+{% endfor %}
+{% endif %}

tests/test_integration.py

@@ -2,12 +2,12 @@
 # pylint: disable=use-implicit-booleaness-not-comparison
 
 """High-level integration tests of diff-cover tool."""
-
 import json
 import os
 import os.path
 import re
 import shutil
+import textwrap
 from collections import defaultdict
 from pathlib import Path
 from subprocess import Popen
@@ -429,6 +429,54 @@ def test_expand_coverage_report_uncomplete_report(
         assert runbin(["coverage_missing_lines.xml", "--expand-coverage-report"]) == 0
         compare_console("expand_console_report.txt", capsys.readouterr().out)
 
+    def test_github_silent(self, runbin, patch_git_command, capsys):
+        patch_git_command.set_stdout("git_diff_add.txt")
+        assert (
+            runbin(["coverage.xml", "--format", "github-annotations:notice", "-q"]) == 0
+        )
+        expected = textwrap.dedent(
+            """\
+        ::notice file=test_src.txt,line=2,title=Missing Coverage::Line 2 missing coverage
+        ::notice file=test_src.txt,line=4,title=Missing Coverage::Line 4 missing coverage
+        ::notice file=test_src.txt,line=6,title=Missing Coverage::Line 6 missing coverage
+        ::notice file=test_src.txt,line=8,title=Missing Coverage::Line 8 missing coverage
+        ::notice file=test_src.txt,line=10,title=Missing Coverage::Line 10 missing coverage
+        """
+        )
+        assert capsys.readouterr().out == expected
+
+    @pytest.mark.usefixtures("patch_git_command")
+    def test_github_fully_covered(self, runbin, capsys):
+        assert runbin(["coverage2.xml", "--format", "github-annotations:notice"]) == 0
+        expected = textwrap.dedent(
+            """\
+        -------------
+        Diff Coverage
+        Diff: origin/main...HEAD, staged and unstaged changes
+        -------------
+        No lines with coverage information in this diff.
+        -------------
+
+        """
+        )
+        assert capsys.readouterr().out == expected
+
+    def test_github_empty_diff(self, runbin, patch_git_command, capsys):
+        patch_git_command.set_stdout("")
+        assert runbin(["coverage.xml", "--format", "github-annotations:notice"]) == 0
+        expected = textwrap.dedent(
+            """\
+        -------------
+        Diff Coverage
+        Diff: origin/main...HEAD, staged and unstaged changes
+        -------------
+        No lines with coverage information in this diff.
+        -------------
+
+        """
+        )
+        assert capsys.readouterr().out == expected
+
     def test_real_world_cpp_lcov_coverage(self, runbin, patch_git_command, capsys):
         """Test with real C++ LCOV coverage data"""
         # Create git diff for C++ files

tests/test_report_generator.py

@@ -10,6 +10,7 @@
 from diff_cover.diff_reporter import BaseDiffReporter
 from diff_cover.report_generator import (
     BaseReportGenerator,
+    GitHubAnnotationsReportGenerator,
     HtmlReportGenerator,
     JsonReportGenerator,
     MarkdownReportGenerator,
@@ -407,6 +408,64 @@ def test_empty_report(self):
         self.assert_report(expected)
 
 
+class TestGitHubAnnotationsReportGenerator(BaseReportGeneratorTest):
+
+    @pytest.fixture
+    def report(self, coverage, diff):
+        # Create a concrete instance of a report generator
+        return GitHubAnnotationsReportGenerator(coverage, diff, "warning")
+
+    @pytest.mark.usefixtures("use_default_values")
+    def test_generate_report(self):
+        # Verify that we got the expected string
+        expected = dedent(
+            """
+        ::warning file=file1.py,line=10,endLine=11,title=Missing Coverage::Line 10-11 missing coverage
+        ::warning file=subdir/file2.py,line=10,endLine=11,title=Missing Coverage::Line 10-11 missing coverage
+        """
+        ).strip()
+
+        self.assert_report(expected)
+
+    def test_single_line(
+        self, diff, diff_lines_changed, coverage_violations, coverage_measured_lines
+    ):
+        diff.src_paths_changed.return_value = ["file.py"]
+        diff_lines_changed.update({"file.py": list(range(100))})
+        coverage_violations.update({"file.py": [Violation(10, None)]})
+        coverage_measured_lines.update({"file.py": [2]})
+
+        # Verify that we got the expected string
+        expected = dedent(
+            """
+        ::warning file=file.py,line=10,title=Missing Coverage::Line 10 missing coverage
+        """
+        ).strip()
+
+        self.assert_report(expected)
+
+    def test_hundred_percent(
+        self, diff, diff_lines_changed, coverage_violations, coverage_measured_lines
+    ):
+        # Have the dependencies return an empty report
+        diff.src_paths_changed.return_value = ["file.py"]
+        diff_lines_changed.update({"file.py": list(range(100))})
+        coverage_violations.update({"file.py": []})
+        coverage_measured_lines.update({"file.py": [2]})
+
+        expected = ""
+
+        self.assert_report(expected)
+
+    def test_empty_report(self):
+        # Have the dependencies return an empty report
+        # (this is the default)
+
+        expected = ""
+
+        self.assert_report(expected)
+
+
 class TestHtmlReportGenerator(BaseReportGeneratorTest):
 
     @pytest.fixture