diff-cover 10.2.1__tar.gz → 10.3.0__tar.gz

{diff_cover-10.2.1 → diff_cover-10.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: diff_cover
-Version: 10.2.1
+Version: 10.3.0
 Summary: Run coverage and linting reports on diffs
 License: Apache-2.0
 Author: See Contributors
@@ -320,6 +320,83 @@ It can be enabled by using the ``-q``/``--quiet`` flag:
 
 If enabled, the tool will only print errors and failures but no information or warning messages.
 
+Showing Covered and Uncovered Lines
+-----------------------------------
+By default the console report only lists the percentage of covered lines.
+
+``diff-cover`` can also show the individual lines that lack coverage on the
+console with ``--show-uncovered``:
+
+.. code:: bash
+
+    diff-cover coverage.xml --show-uncovered
+
+When generating an HTML report, ``--show-covered`` additionally highlights the
+covered diff lines (in green), alongside the existing missing-line (red)
+highlighting:
+
+.. code:: bash
+
+    diff-cover coverage.xml --html-report report.html --show-covered
+
+Source Roots
+------------
+For ``jacoco`` coverage reports, ``diff-cover`` needs to know the source
+directories in order to map coverage data back to source files. Provide one or
+more directories with ``--src-roots`` (defaults to ``src/main/java`` and
+``src/test/java``):
+
+.. code:: bash
+
+    diff-cover coverage.xml --src-roots src/main/java src/test/java
+
+Report Root Path
+----------------
+``diff-quality`` resolves violation report paths relative to the current working
+directory. If your quality tool was run from a different directory, use
+``--report-root-path`` to specify the root path that should be used when
+generating the report:
+
+.. code:: bash
+
+    diff-quality --violations=pycodestyle --report-root-path=path/to/root
+
+External CSS File
+-----------------
+By default an HTML report embeds its styles inline. To write the CSS into a
+separate file instead, use ``--external-css-file``:
+
+.. code:: bash
+
+    diff-cover coverage.xml --html-report report.html --external-css-file report.css
+    diff-quality --violations=pycodestyle --html-report report.html --external-css-file report.css
+
+Diff Range Notation
+-------------------
+When comparing branches, ``diff-cover`` and ``diff-quality`` use the ``...``
+git diff range notation by default (changes on the current branch since it
+diverged from the compare branch). To use the ``..`` notation instead (all
+differences between the two branches), pass ``--diff-range-notation``:
+
+.. code:: bash
+
+    diff-cover coverage.xml --diff-range-notation=..
+    diff-quality --violations=pycodestyle --diff-range-notation=..
+
+See the `git diff documentation`_ for details on the two notations.
+
+.. _git diff documentation: https://git-scm.com/docs/git-diff
+
+Ignore Whitespace
+-----------------
+To ignore any and all whitespace changes when computing the diff, use
+``--ignore-whitespace``:
+
+.. code:: bash
+
+    diff-cover coverage.xml --ignore-whitespace
+    diff-quality --violations=pycodestyle --ignore-whitespace
+
 Compatibility with multi-line statements
 ----------------------------------------
 ``diff-cover`` relies on the comparison of diff reports and coverage reports, and does not report

{diff_cover-10.2.1 → diff_cover-10.3.0}/README.rst

@@ -288,6 +288,83 @@ It can be enabled by using the ``-q``/``--quiet`` flag:
 
 If enabled, the tool will only print errors and failures but no information or warning messages.
 
+Showing Covered and Uncovered Lines
+-----------------------------------
+By default the console report only lists the percentage of covered lines.
+
+``diff-cover`` can also show the individual lines that lack coverage on the
+console with ``--show-uncovered``:
+
+.. code:: bash
+
+    diff-cover coverage.xml --show-uncovered
+
+When generating an HTML report, ``--show-covered`` additionally highlights the
+covered diff lines (in green), alongside the existing missing-line (red)
+highlighting:
+
+.. code:: bash
+
+    diff-cover coverage.xml --html-report report.html --show-covered
+
+Source Roots
+------------
+For ``jacoco`` coverage reports, ``diff-cover`` needs to know the source
+directories in order to map coverage data back to source files. Provide one or
+more directories with ``--src-roots`` (defaults to ``src/main/java`` and
+``src/test/java``):
+
+.. code:: bash
+
+    diff-cover coverage.xml --src-roots src/main/java src/test/java
+
+Report Root Path
+----------------
+``diff-quality`` resolves violation report paths relative to the current working
+directory. If your quality tool was run from a different directory, use
+``--report-root-path`` to specify the root path that should be used when
+generating the report:
+
+.. code:: bash
+
+    diff-quality --violations=pycodestyle --report-root-path=path/to/root
+
+External CSS File
+-----------------
+By default an HTML report embeds its styles inline. To write the CSS into a
+separate file instead, use ``--external-css-file``:
+
+.. code:: bash
+
+    diff-cover coverage.xml --html-report report.html --external-css-file report.css
+    diff-quality --violations=pycodestyle --html-report report.html --external-css-file report.css
+
+Diff Range Notation
+-------------------
+When comparing branches, ``diff-cover`` and ``diff-quality`` use the ``...``
+git diff range notation by default (changes on the current branch since it
+diverged from the compare branch). To use the ``..`` notation instead (all
+differences between the two branches), pass ``--diff-range-notation``:
+
+.. code:: bash
+
+    diff-cover coverage.xml --diff-range-notation=..
+    diff-quality --violations=pycodestyle --diff-range-notation=..
+
+See the `git diff documentation`_ for details on the two notations.
+
+.. _git diff documentation: https://git-scm.com/docs/git-diff
+
+Ignore Whitespace
+-----------------
+To ignore any and all whitespace changes when computing the diff, use
+``--ignore-whitespace``:
+
+.. code:: bash
+
+    diff-cover coverage.xml --ignore-whitespace
+    diff-quality --violations=pycodestyle --ignore-whitespace
+
 Compatibility with multi-line statements
 ----------------------------------------
 ``diff-cover`` relies on the comparison of diff reports and coverage reports, and does not report

{diff_cover-10.2.1 → diff_cover-10.3.0}/diff_cover/diff_cover_tool.py

@@ -45,6 +45,10 @@ DIFF_RANGE_NOTATION_HELP = (
 )
 QUIET_HELP = "Only print errors and failures"
 SHOW_UNCOVERED = "Show uncovered lines on the console"
+SHOW_COVERED_HELP = (
+    "Also highlight covered diff lines (in green) in the HTML coverage report, "
+    "in addition to the existing missing-line (red) highlighting."
+)
 EXPAND_COVERAGE_REPORT = (
     "Append missing lines in coverage reports based on the hits of the previous line."
 )
@@ -99,6 +103,13 @@ def parse_coverage_args(argv):
         "--show-uncovered", action="store_true", default=None, help=SHOW_UNCOVERED
     )
 
+    parser.add_argument(
+        "--show-covered",
+        action="store_true",
+        default=None,
+        help=SHOW_COVERED_HELP,
+    )
+
     parser.add_argument(
         "--expand-coverage-report",
         action="store_true",
@@ -193,6 +204,7 @@ def parse_coverage_args(argv):
 
     defaults = {
         "show_uncovered": False,
+        "show_covered": False,
         "compare_branch": "origin/main",
         "fail_under": 0,
         "ignore_staged": False,
@@ -223,6 +235,7 @@ def generate_coverage_report(
     src_roots=None,
     quiet=False,
     show_uncovered=False,
+    show_covered=False,
     expand_coverage_report=False,
     total_percent_float=False,
 ):
@@ -263,7 +276,11 @@ def generate_coverage_report(
         if css_url is not None:
             css_url = os.path.relpath(css_file, os.path.dirname(html_report))
         reporter = HtmlReportGenerator(
-            coverage, diff, css_url=css_url, total_percent_float=total_percent_float
+            coverage,
+            diff,
+            css_url=css_url,
+            total_percent_float=total_percent_float,
+            show_covered=show_covered,
         )
         with open_file(html_report, "wb") as output_file:
             reporter.generate_report(output_file)
@@ -398,6 +415,7 @@ def main(argv=None, directory=None):
         src_roots=arg_dict["src_roots"],
         quiet=quiet,
         show_uncovered=arg_dict["show_uncovered"],
+        show_covered=arg_dict["show_covered"],
         expand_coverage_report=arg_dict["expand_coverage_report"],
         total_percent_float=arg_dict["total_percent_float"],
     )

{diff_cover-10.2.1 → diff_cover-10.3.0}/diff_cover/report_generator.py

@@ -295,6 +295,7 @@ class TemplateReportGenerator(BaseReportGenerator):
         diff_reporter,
         css_url=None,
         total_percent_float=False,
+        show_covered=False,
     ):
         super().__init__(
             violations_reporter,
@@ -302,6 +303,11 @@ class TemplateReportGenerator(BaseReportGenerator):
             total_percent_float=total_percent_float,
         )
         self.css_url = css_url
+        # When True, the rendered HTML snippet for each source file will
+        # additionally highlight covered diff lines (in green) on top of
+        # the existing violation (red) highlighting. Defaults to False to
+        # preserve historical behaviour.
+        self.show_covered = show_covered
 
     def generate_report(self, output_file):
         """
@@ -406,9 +412,12 @@ class TemplateReportGenerator(BaseReportGenerator):
         # If we cannot load the file, then fail gracefully
         formatted_snippets = {"html": [], "markdown": [], "terminal": []}
         if self.include_snippets:
+            covered_lines = stats["covered_lines"] if self.show_covered else None
             with contextlib.suppress(OSError):
                 formatted_snippets = Snippet.load_formatted_snippets(
-                    src_path, stats["violation_lines"]
+                    src_path,
+                    stats["violation_lines"],
+                    covered_lines=covered_lines,
                 )
 
         stats.update(

{diff_cover-10.2.1 → diff_cover-10.3.0}/diff_cover/snippets.py

@@ -4,6 +4,7 @@ in HTML reports.
 """
 
 import contextlib
+import re
 from tokenize import open as openpy
 
 import chardet
@@ -23,7 +24,10 @@ class Snippet:
     """
 
     VIOLATION_COLOR = "#ffcccc"
+    COVERED_COLOR = "#ddffdd"
     DIV_CSS_CLASS = "snippet"
+    COVERED_LINE_CSS_CLASS = "diff-cover-covered-line"
+    LINESPANS_PREFIX = "diff-cover-src-line"
 
     # Number of extra lines to include before and after
     # each snippet to provide context.
@@ -50,6 +54,7 @@ class Snippet:
         last_line,
         violation_lines,
         lexer_name,
+        covered_lines=None,
     ):
         """
         Create a source code snippet.
@@ -75,6 +80,10 @@ class Snippet:
         programming language for this snippet.
         See https://pygments.org/docs/lexers/
 
+        `covered_lines` is an optional list of line numbers
+        to highlight as covered. When omitted (the default),
+        no covered-line highlighting is rendered.
+
         Raises a `ValueError` if `start_line` is less than 1
         """
         if start_line < 1:
@@ -86,6 +95,7 @@ class Snippet:
         self._last_line = last_line
         self._violation_lines = violation_lines
         self._lexer_name = lexer_name
+        self._covered_lines = covered_lines or []
 
     @classmethod
     def style_defs(cls):
@@ -95,21 +105,74 @@ class Snippet:
         """
         formatter = HtmlFormatter()
         formatter.style.highlight_color = cls.VIOLATION_COLOR
-        return formatter.get_style_defs()
+        base_styles = formatter.get_style_defs()
+        # Append a rule for covered-line highlighting.
+        covered_style = (
+            f".{cls.COVERED_LINE_CSS_CLASS} "
+            f"{{ background-color: {cls.COVERED_COLOR}; }}"
+        )
+        return f"{base_styles}\n{covered_style}"
 
     def html(self):
         """
         Return an HTML representation of the snippet.
+
+        Violation lines are highlighted via Pygments' built-in
+        `hl_lines` mechanism. When the snippet was constructed with
+        `covered_lines`, those lines are additionally marked by adding
+        the covered-line CSS class to their per-line span, produced via
+        the `linespans` formatter option.
         """
-        formatter = HtmlFormatter(
+        formatter_kwargs = dict(
             cssclass=self.DIV_CSS_CLASS,
             linenos=True,
             linenostart=self._start_line,
             hl_lines=self._shift_lines(self._violation_lines, self._start_line),
             lineanchors=self._src_filename,
         )
+        # Only enable per-line `<span id="...">` wrapping when we actually
+        # need it for covered-line highlighting. This keeps the rendered
+        # HTML byte-for-byte identical to the historical output when no
+        # covered lines are supplied.
+        if self._covered_lines:
+            formatter_kwargs["linespans"] = self.LINESPANS_PREFIX
 
-        return pygments.format(self.src_tokens(), formatter)
+        rendered = pygments.format(self.src_tokens(), HtmlFormatter(**formatter_kwargs))
+
+        if self._covered_lines:
+            # NOTE: do NOT shift these line numbers. Unlike `hl_lines`
+            # (which is snippet-relative, 1-based), Pygments' `linespans`
+            # IDs are emitted using the same numbering as `linenostart`,
+            # i.e. the absolute file line number. So we match the raw
+            # values from `_covered_lines` directly.
+            rendered = self._mark_covered_lines(rendered, self._covered_lines)
+
+        return rendered
+
+    @classmethod
+    def _mark_covered_lines(cls, html, covered_file_lines):
+        """
+        Add the covered-line CSS class to per-line spans whose line
+        number is in `covered_file_lines`.
+
+        `covered_file_lines` are absolute (file-relative) line numbers,
+        matching the IDs that Pygments emits via `linespans` when
+        `linenostart` is set to the snippet's starting line number.
+        """
+        wanted = set(covered_file_lines)
+        if not wanted:
+            return html
+
+        prefix = cls.LINESPANS_PREFIX
+        css_class = cls.COVERED_LINE_CSS_CLASS
+
+        def _replace(match):
+            line_num = int(match.group(1))
+            if line_num in wanted:
+                return f'<span id="{prefix}-{line_num}" class="{css_class}">'
+            return match.group(0)
+
+        return re.sub(rf'<span id="{re.escape(prefix)}-(\d+)">', _replace, html)
 
     def markdown(self):
         """
@@ -174,24 +237,38 @@ class Snippet:
         return "".join([val for _, val in self._src_tokens])
 
     @classmethod
-    def load_formatted_snippets(cls, src_path, violation_lines):
+    def load_formatted_snippets(cls, src_path, violation_lines, covered_lines=None):
         """
         Load snippets from the file at `src_path` and format
         them as HTML and as plain text.
         Returns a dictionary containing the two types of formatting
         results for code snippets.
 
+        If `covered_lines` is provided (non-empty), the HTML output will
+        additionally render snippets around those lines and highlight
+        them as covered. Markdown and terminal output is unchanged
+        regardless of `covered_lines`, to keep those formats stable.
+
         See `load_snippets()` for details.
         """
 
-        # load once...
-        snippet_list = cls.load_snippets(src_path, violation_lines)
+        # Snippets used for markdown/terminal output keep the historical
+        # behaviour: ranges only around violation lines, no covered-line
+        # information attached.
+        violation_only_snippets = cls.load_snippets(src_path, violation_lines)
+
+        if covered_lines:
+            # HTML rendering also visualises covered diff lines, so widen
+            # the snippet ranges to include them and pass the covered list
+            # through to the snippet for per-line highlighting.
+            html_snippets = cls.load_snippets(src_path, violation_lines, covered_lines)
+        else:
+            html_snippets = violation_only_snippets
 
-        # ...render twice in different formats
         return {
-            "html": [snippet.html() for snippet in snippet_list],
-            "markdown": [snippet.markdown() for snippet in snippet_list],
-            "terminal": [snippet.terminal() for snippet in snippet_list],
+            "html": [snippet.html() for snippet in html_snippets],
+            "markdown": [snippet.markdown() for snippet in violation_only_snippets],
+            "terminal": [snippet.terminal() for snippet in violation_only_snippets],
         }
 
     @classmethod
@@ -223,12 +300,17 @@ class Snippet:
         return contents
 
     @classmethod
-    def load_snippets(cls, src_path, violation_lines):
+    def load_snippets(cls, src_path, violation_lines, covered_lines=None):
         """
         Load snippets from the file at `src_path` to show
         violations on lines in the list `violation_lines`
         (list of line numbers, starting at index 0).
 
+        If `covered_lines` is provided, those lines are also treated as
+        "interesting" when computing snippet ranges (so a fully-covered
+        file still yields snippets) and are stored on the resulting
+        `Snippet` instances for use during rendering.
+
         The file at `src_path` should be a text file (not binary).
 
         Returns a list of `Snippet` instances.
@@ -237,9 +319,15 @@ class Snippet:
         """
         contents = cls.load_contents(src_path)
 
-        # Construct a list of snippet ranges
+        # Construct a list of snippet ranges. When `covered_lines` is
+        # provided, expand the set of "interesting" lines so we also
+        # render context around covered diff lines, not just violations.
         src_lines = contents.split("\n")
-        snippet_ranges = cls._snippet_ranges(len(src_lines), violation_lines)
+        if covered_lines:
+            interesting_lines = sorted(set(violation_lines) | set(covered_lines))
+        else:
+            interesting_lines = violation_lines
+        snippet_ranges = cls._snippet_ranges(len(src_lines), interesting_lines)
 
         # Parse the source into tokens
         token_stream, lexer = cls._parse_src(contents, src_path)
@@ -248,7 +336,15 @@ class Snippet:
         token_groups = cls._group_tokens(token_stream, snippet_ranges)
 
         return [
-            Snippet(tokens, src_path, start, end, violation_lines, lexer.name)
+            Snippet(
+                tokens,
+                src_path,
+                start,
+                end,
+                violation_lines,
+                lexer.name,
+                covered_lines=covered_lines,
+            )
             for (start, end), tokens in sorted(token_groups.items())
         ]
 

{diff_cover-10.2.1 → diff_cover-10.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "diff_cover"
-version = "10.2.1"
+version = "10.3.0"
 description = "Run coverage and linting reports on diffs"
 authors = ["See Contributors"]
 homepage = "https://github.com/Bachmann1234/diff-cover"

{diff_cover-10.2.1 → diff_cover-10.3.0}/tests/test_diff_cover_tool.py

@@ -37,6 +37,16 @@ def test_parse_with_no_report():
     assert not arg_dict["ignore_unstaged"]
 
 
+def test_show_covered_defaults_false():
+    arg_dict = parse_coverage_args(["reports/coverage.xml"])
+    assert arg_dict["show_covered"] is False
+
+
+def test_show_covered_flag():
+    arg_dict = parse_coverage_args(["reports/coverage.xml", "--show-covered"])
+    assert arg_dict["show_covered"] is True
+
+
 def test_parse_with_multiple_reports():
     argv = [
         "reports/coverage.xml",

{diff_cover-10.2.1 → diff_cover-10.3.0}/tests/test_report_generator.py

@@ -498,6 +498,39 @@ class TestHtmlReportGenerator(BaseReportGeneratorTest):
         expected = load_fixture("html_report.html")
         self.assert_report(expected)
 
+    @pytest.mark.usefixtures("use_default_values")
+    def test_show_covered_passes_covered_lines_to_snippets(self, coverage, diff):
+        """
+        When `show_covered=True`, the html reporter should pass each
+        source file's covered lines into `Snippet.load_formatted_snippets`
+        so the snippet renderer can highlight them.
+        """
+        report = HtmlReportGenerator(coverage, diff, show_covered=True)
+        report.generate_report(BytesIO())
+
+        calls = self._load_formatted_snippets.call_args_list
+        assert calls, "Expected snippet loading to be invoked"
+        for call in calls:
+            assert call.kwargs.get(
+                "covered_lines"
+            ), "Expected covered_lines to be forwarded when show_covered=True"
+
+    @pytest.mark.usefixtures("use_default_values")
+    def test_show_covered_default_false_does_not_pass_covered_lines(
+        self, coverage, diff
+    ):
+        """
+        With the default `show_covered=False`, no covered_lines should be
+        passed to the snippet loader, preserving the historical behaviour.
+        """
+        report = HtmlReportGenerator(coverage, diff)
+        report.generate_report(BytesIO())
+
+        calls = self._load_formatted_snippets.call_args_list
+        assert calls, "Expected snippet loading to be invoked"
+        for call in calls:
+            assert call.kwargs.get("covered_lines") is None
+
     def test_empty_report(self):
         # Have the dependencies return an empty report
         # (this is the default)