Add HTML coverage reporting (--format=html)

Closes #27.

Generates a coverage.py-style 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: 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 that was deleted by hand is regenerated
rather than skipped.

Adapted from coverage.py (Apache-2.0) -- templite.py, phystokens.py and
the htmlfiles/ assets are ports; see NOTICE. Departures from it:

  - Line categories are pln/run/mis/par only. Excluded lines are removed
    from the coverage data before reporting, so there is nothing for an
    "excluded" category or 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 report --
    this is the common case after --merge of coverage produced elsewhere.
  - 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 index footer keeps the report's own totals when no row is
    filtered out, so --skip-covered cannot show a footer that disagrees
    with the header percentage.

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

No new dependencies: highlighting uses stdlib tokenize.

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,23 @@
+SlipCover
+Copyright the SlipCover authors.
+
+This product includes software developed as part of coverage.py
+(https://github.com/nedbat/coveragepy), copyright Ned Batchelder and
+contributors, licensed under the Apache License, Version 2.0.
+
+The following files are derived from coverage.py:
+
+  src/slipcover/templite.py            (from coverage/templite.py)
+  src/slipcover/phystokens.py          (from coverage/phystokens.py)
+  src/slipcover/htmlreport.py          (from coverage/html.py)
+  src/slipcover/htmlfiles/index.html   (from coverage/htmlfiles/index.html)
+  src/slipcover/htmlfiles/pyfile.html  (from coverage/htmlfiles/pyfile.html)
+  src/slipcover/htmlfiles/style.css    (from coverage/htmlfiles/style.css)
+  src/slipcover/htmlfiles/coverage_html.js
+                                       (from coverage/htmlfiles/coverage_html.js)
+  src/slipcover/htmlfiles/keybd_closed.png
+  src/slipcover/htmlfiles/favicon_32.png
+
+You may obtain a copy of the Apache License, Version 2.0 at
+
+    http://www.apache.org/licenses/LICENSE-2.0

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.

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