Add HTML coverage reporting (--format=html)

Closes #27.

Generates a report directory: an index page plus one annotated source page
per file, with syntax highlighting and per-line run/missing/partial marking.
--out names the output directory (default htmlcov/); HTML is never written
to stdout.

Repeat runs are incremental. A status.json records a hash of each file's
source, its coverage data and its prev/next navigation, so unchanged pages
are not rewritten. A page deleted by hand is regenerated rather than
skipped.

The index sorts by any column, filters by file name, and can hide fully
covered files. While a filter is active the footer subtotals the visible
rows and relabels itself; with no filter it shows the report's own totals
verbatim. The pages are usable with JavaScript disabled.

No new dependencies: highlighting uses stdlib tokenize.

The pages, stylesheet and script are slipcover's own; the stylesheet uses
the palette from the project logo. Line status is carried by a left border
as well as a tint, so the four categories stay distinguishable in greyscale,
in print, and for colour-blind readers.

Derived from coverage.py (Apache-2.0, as is this project), following the
precedent set by xmlreport.py: phystokens.py is a port of its tokenizer, and
htmlreport.py takes the incremental status file and the shape of the report
loop. Both retain coverage.py's original licence notices, and NOTICE
reproduces the attributions from its NOTICE.txt.

Differences from coverage.py worth noting:

  - Line categories are pln/run/mis/par only. _filter_excluded_lines strips
    excluded lines from the coverage data before reporting and the schema
    has no excluded field, so there is nothing for an "exc" category or an
    "excluded" column to show.
  - A source file missing at report time renders a notice and keeps its
    index row, rather than omitting the file or aborting -- the ordinary
    case after --merge of coverage produced on another machine.
  - The per-file hash includes prev/next navigation, so adding a file
    refreshes its neighbours' links instead of leaving them stale.
  - status.json is written atomically (tmp + rename); a truncated one still
    self-heals into a full regeneration.
  - The footer is only recomputed while a filter is actually applied, and
    says so when it is. Recomputing unconditionally makes the footer
    disagree with the heading under --skip-covered, which omits rows that
    still count.

Under --format=html a forked child returns from the atexit handler without
writing, so two processes cannot interleave into one output directory.
Other formats are untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: ronaldorcampos

.gitignore

@@ -5,5 +5,6 @@ __pycache__/
 build/
 dist/
 .coverage
+htmlcov/
 .tox/
 *.swp

NOTICE

@@ -0,0 +1,34 @@
+SlipCover
+Copyright the SlipCover authors.
+
+This product includes software developed as part of coverage.py
+(https://github.com/coveragepy/coveragepy).
+
+These files are derived from coverage.py and have been modified:
+
+  src/slipcover/xmlreport.py    from coverage/xmlreport.py
+  src/slipcover/phystokens.py   from coverage/phystokens.py
+  src/slipcover/htmlreport.py   from coverage/html.py, in part: the
+                                data_filename, read_data and write_html
+                                helpers, and the design of the incremental
+                                status file and the report loop
+
+Everything else in slipcover's HTML report -- the pages, the stylesheet and
+the script -- is slipcover's own.
+
+The attribution notices from coverage.py's own NOTICE.txt follow.
+
+    Copyright 2001 Gareth Rees.  All rights reserved.
+    Copyright 2004-2026 Ned Batchelder.  All rights reserved.
+
+    Except where noted otherwise, this software is licensed under the Apache
+    License, Version 2.0 (the "License"); you may not use this work except in
+    compliance with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.

README.md

@@ -111,7 +111,7 @@ branch = true
 source = "src"        # or ["src", "lib"]
 omit = "tests/*"       # or ["tests/*", "*.pyc"]
 fail-under = 80.0
-format = "json"        # "text" (default), "json", "xml", or "lcov"
+format = "json"        # "text" (default), "json", "xml", "lcov", or "html"
 pretty-print = true
 skip-covered = true
 immediate = false
@@ -123,9 +123,9 @@ xml-package-depth = 3
 
 Most command-line flags have a matching key (use hyphens, as shown above);
 `source` and `omit` also accept a TOML array instead of a single
-comma-separated string. `--json`/`--xml`/`--lcov` map to the single `format`
-key shown above rather than one key per flag. `--merge`, `-m`/module, the
-script argument, `--version`, and `--help` are per-invocation choices rather
+comma-separated string. `--json`/`--xml`/`--lcov`/`--html` map to the single
+`format` key shown above rather than one key per flag. `--merge`, `-m`/module,
+the script argument, `--version`, and `--help` are per-invocation choices rather
 than settings, so they aren't configurable this way. Command-line arguments
 always take precedence over values in `pyproject.toml`, so you can override
 any setting on a per-run basis.
@@ -178,9 +178,9 @@ its `box.py` and `image.py` components.
 [//]: # (help-output)
 ```console
 $ python3 -m slipcover --help
-usage: SlipCover [-h] [--branch] [--format {text,json,xml,lcov}] [--json]
+usage: SlipCover [-h] [--branch] [--format {text,json,xml,lcov,html}] [--json]
                  [--pretty-print] [--xml]
-                 [--xml-package-depth XML_PACKAGE_DEPTH] [--lcov]
+                 [--xml-package-depth XML_PACKAGE_DEPTH] [--lcov] [--html]
                  [--lcov-test-name LCOV_TEST_NAME]
                  [--lcov-comment LCOV_COMMENTS] [--out OUT]
                  [--source SRC1,SRC2,...] [--omit PAT1,PAT2,...] [--immediate]
@@ -196,7 +196,7 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   --branch              measure both branch and line coverage
-  --format {text,json,xml,lcov}
+  --format {text,json,xml,lcov,html}
                         select output format
   --json                select JSON output (shortcut for --format=json)
   --pretty-print        pretty-print JSON output
@@ -207,12 +207,14 @@ options:
                         not reported as packages. The default is that all
                         directories are reported as packages.
   --lcov                select LCOV output (shortcut for --format=lcov)
+  --html                select HTML output (shortcut for --format=html)
   --lcov-test-name LCOV_TEST_NAME
                         test name for LCOV TN: entries
   --lcov-comment LCOV_COMMENTS
                         add comment lines at the beginning of LCOV output (can
                         be used multiple times)
-  --out OUT             specify output file name
+  --out OUT             specify output file name (output directory if
+                        --format=html)
   --source SRC1,SRC2,...
                         specify directories to cover; comma-separated for
                         multiple

pyproject.toml

@@ -48,6 +48,9 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools.package-dir]
 "" = "src"
 
+[tool.setuptools.package-data]
+slipcover = ["htmlfiles/*"]
+
 [project.optional-dependencies]
 test = [
     'pytest',

src/slipcover/__init__.py

@@ -1,4 +1,4 @@
 from .version import __version__
-from .slipcover import Slipcover, merge_coverage, print_coverage, print_xml, print_lcov
+from .slipcover import Slipcover, merge_coverage, print_coverage, print_xml, print_lcov, print_html
 from .importer import FileMatcher, ImportManager, wrap_pytest, wrap_spec_from_file_location
 from .fuzz import wrap_function

src/slipcover/__main__.py

@@ -109,6 +109,18 @@ def wrapper(*pargs, **kwargs):
     return wrapper
 
 
+DEFAULT_HTML_DIR = "htmlcov"
+
+
+def html_directory(args):
+    """The output directory for --format=html.
+
+    For HTML, --out names a directory rather than a file; HTML is never
+    written to stdout, so an unset --out means the default directory.
+    """
+    return str(args.out) if args.out else DEFAULT_HTML_DIR
+
+
 def merge_files(args, base_path):
     """Merges coverage files."""
 
@@ -129,6 +141,20 @@ def merge_files(args, base_path):
         return 1
 
     try:
+        if args.format == 'html':
+            sc.print_html(merged, directory=html_directory(args),
+                          with_branches=args.branch, skip_covered=args.skip_covered)
+
+            # print human-readable table for merge results
+            if not args.silent:
+                sc.print_coverage(merged, outfile=sys.stdout, skip_covered=args.skip_covered,
+                                  missing_width=args.missing_width)
+
+            if args.fail_under and merged['summary']['percent_covered'] < args.fail_under:
+                return 2
+
+            return 0
+
         with args.out.open("w", encoding='utf-8') as jf:
             if args.format == 'xml':
                 sc.print_xml(merged, source_paths=[str(base_path)], with_branches=args.branch,
@@ -201,7 +227,7 @@ def build_parser():
     ap = argparse.ArgumentParser(prog='SlipCover')
     ap.add_argument('--branch', action='store_true', help="measure both branch and line coverage")
     fmt = ap.add_mutually_exclusive_group()
-    fmt.add_argument('--format', choices=['text', 'json', 'xml', 'lcov'], default='text',
+    fmt.add_argument('--format', choices=['text', 'json', 'xml', 'lcov', 'html'], default='text',
                      help="select output format")
     fmt.add_argument('--json', dest='format', action='store_const', const='json',
                      help="select JSON output (shortcut for --format=json)")
@@ -214,9 +240,12 @@ def build_parser():
         "The default is that all directories are reported as packages."))
     fmt.add_argument('--lcov', dest='format', action='store_const', const='lcov',
                      help="select LCOV output (shortcut for --format=lcov)")
+    fmt.add_argument('--html', dest='format', action='store_const', const='html',
+                     help="select HTML output (shortcut for --format=html)")
     ap.add_argument('--lcov-test-name', type=str, help="test name for LCOV TN: entries")
     ap.add_argument('--lcov-comment', action='append', dest='lcov_comments', help="add comment lines at the beginning of LCOV output (can be used multiple times)")
-    ap.add_argument('--out', type=Path, help="specify output file name")
+    ap.add_argument('--out', type=Path,
+                    help="specify output file name (output directory if --format=html)")
     ap.add_argument('--source', metavar='SRC1,SRC2,...',
                      help="specify directories to cover; comma-separated for multiple")
     ap.add_argument('--omit', metavar='PAT1,PAT2,...',
@@ -284,8 +313,20 @@ def main():
                 else Path('.').resolve()
 
 
+    # For HTML, --out names a directory; a path that's already something else
+    # can only fail later, when the report is written from an atexit callback
+    # where the traceback is swallowed and the exit status stays 0.  lexists()
+    # rather than exists() so a dangling symlink, which os.makedirs() also
+    # refuses, is caught here too.
+    if args.format == 'html' and args.out and os.path.lexists(args.out) \
+       and not args.out.is_dir():
+        ap.error(f"--out must name a directory with --format=html: {args.out}")
+
     if args.merge:
-        if not args.out: ap.error("--out is required with --merge")
+        # HTML falls back to its default directory rather than stdout, so it
+        # doesn't need --out the way the single-file formats do.
+        if not args.out and args.format != 'html':
+            ap.error("--out is required with --merge")
         return merge_files(args, base_path=base_path)
 
 
@@ -362,6 +403,20 @@ def printit(coverage, outfile):
                                   missing_width=args.missing_width)
 
         if not args.silent:
+            if args.format == 'html':
+                # A forked child reaching normal interpreter shutdown runs this
+                # too; letting it write would interleave a partial report (and
+                # a mutable status.json) with the parent's.  Such a child's
+                # coverage is lost -- output_tmpfile is only ever written by
+                # the os._exit() shim, which atexit doesn't run behind -- but
+                # it is lost the same way for every other format, so this only
+                # keeps the report intact, it doesn't cost anything extra.
+                if output_tmpfile:
+                    return
+                sc.print_html(merged_coverage(sci), directory=html_directory(args),
+                              with_branches=args.branch, skip_covered=args.skip_covered)
+                return
+
             coverage = merged_coverage(sci)
             if args.out:
                 with open(args.out, "w") as outfile:

src/slipcover/config.py

@@ -126,7 +126,7 @@ def _coerce_comments(value):
 
 
 def _coerce_format(value):
-    choices = ("text", "json", "xml", "lcov")
+    choices = ("text", "json", "xml", "lcov", "html")
     if value not in choices:
         raise ValueError(f"must be one of {choices}, got {value!r}")
     return value