feat: JSON Summary Reports, Coverage Comparison & CI Enforcement

[twilsonco]

This PR introduces a suite of robust coverage reporting, comparison, and continuous integration (CI) enforcement capabilities to LocalCoverage.jl. These additions allow developers and automated CI pipelines to generate Jest-compatible JSON summaries, compare current coverage with baseline summaries, display coverage deltas in a clear table, and fail builds or scripts if overall coverage decreases or falls below a target percentage threshold.

This PR addresses all requirements for coverage summary reporting.

Key Features & Improvements

1. Jest-Compatible JSON Coverage Summary

• Added a new function generate_json_summary(coverage::PackageCoverage, filename = "coverage-summary.json"; test_args = [""]) which outputs a coverage report mimicking the structure of Jest's json-summary reporter (tracking lines, statements, functions, and branches).
• Fully integrated JSON generation into the main generate_coverage pipeline via keywords:
  • json_summary::Bool = false (automatically set to true if comparison is requested).
  • json_summary_filename::String = "coverage-summary.json".
• Supports replacing the default top-level "total" key in the summary with customized test set names derived from test_args.

2. Coverage Comparison & Delta Reporting

• Added compare_coverage_json_summaries(old::AbstractString, new::AbstractString, io::IO = stdout) to parse and compare coverage summaries (from either JSON strings or files).
• Generates a beautifully formatted terminal/CI table using PrettyTables detailing:
  • Each individual file and the overall package.
  • Old coverage % vs. New coverage %.
  • Precise delta percentages (e.g. +8.57% or -2.30%).
• Supports automatic pass gracefully if no prior baseline file exists, ensuring seamless bootstrapping of CI/CD loops.
• Integrated strict enforcement in generate_coverage:
  • json_comparison_summary_filename::Union{Nothing,String} = nothing specifies the baseline JSON path to compare against.
  • json_summary_comparison_fail_on_decrease::Bool = false determines whether to throw an error and halt execution if overall coverage has dropped.

3. CI-Friendly CLI Enforcement (report_coverage_and_exit)

• Added report_coverage_and_exit to facilitate CLI/CI automation.
• This method prints the coverage summary and exits with status code 0 if the target coverage threshold is met, or status code 1 otherwise.
• Can be invoked directly from command-line scripts:

  julia --project=@. -e 'using LocalCoverage; report_coverage_and_exit(; target_coverage=90)'

4. PrettyTables 3.0 Compatibility

• Implemented compile-time compatibility branching (@static if pkgversion(PrettyTables) < v"3.0.0") to support both older PrettyTables releases and the modern v3.0 API. This includes adaptive usage of Highlighter/TextHighlighter, tabular keywords, layout configurations, and text format styling.

---

File Changes & Coverage Analysis

• Project.toml: Added dependency on JSON with appropriate [compat] bounds.
• README.md: Extensively documented the new functions, inputs, options, CLI usage, and CI integration, complete with layout previews.
• src/LocalCoverage.jl: Refactored the core logic to return the PackageCoverage object on success, implemented XML generation utilities, added generate_json_summary, comparison routines, and report_coverage_and_exit.
• test/Project.toml: Added test-environment dependencies.
• test/runtests.jl: Added comprehensive test coverage (~200 lines of robust tests) to validate JSON parsing/saving, file comparisons, CLI subprocess exit codes, edge cases, missing file paths, and Aqua quality assurance checks.

---

Usage Examples

Generating a JSON summary:

using LocalCoverage
generate_coverage(pkg; json_summary = true)

CI check failing on coverage decrease:

using LocalCoverage
generate_coverage(pkg; 
                  json_comparison_summary_filename = "coverage/previous-summary.json",
                  json_summary_comparison_fail_on_decrease = true)

CI check enforcing a 90% threshold:

julia --project=@. -e 'using LocalCoverage; report_coverage_and_exit(target_coverage=90)'

---

Verification & Testing

Tests pass locally with 100% success, confirming:

1. Valid JSON format structures (matching the Jest standard).
2. Proper detection of coverage increases (passing), unchanged metrics (passing), and coverage decreases (raising errors when requested).
3. CLI exit codes matching the coverage thresholds across mock test scenarios.

closes #47

[jakobjpeters]

Cool! The JSON schema should be documented so that users know what to expect and this package is semantically versioned to support that. I like documentating JSON similar to this:

- `a`: description...
- `b`:
- `c`:
- `d`:
- `e`: an `Object2` used for ...

### Object1
```json
{
    "a": number
    "b": array
    "c": null
    "d": string
    "e": object
}
```

### Object2

```json
{ ... }
```

[twilsonco]

@jakobjpeters I don't entirely understand, but how's this (from the updated readme)?

---

JSON Summary Schema

The JSON summary mimics Jest's standard json-summary reporter format (relevant section of Jest docs). It contains a top-level key for the package total (or the name of the test set if customized), followed by keys for each individual tracked file path.

Each section contains sub-metrics for lines, statements, functions, and branches with the following structure:

• total: Total number of lines tracked.
• covered: Number of lines hit.
• skipped: Always 0 (included for compatibility).
• pct: Coverage percentage (as a float).

{
  "total": {
    "lines": { "total": 10, "covered": 5, "skipped": 0, "pct": 50.0 },
    "statements": { "total": 10, "covered": 5, "skipped": 0, "pct": 50.0 },
    "functions": { "total": 10, "covered": 5, "skipped": 0, "pct": 50.0 },
    "branches": { "total": 10, "covered": 5, "skipped": 0, "pct": 50.0 }
  },
  "src/bar.jl": {
    "lines": { "total": 5, "covered": 2, "skipped": 0, "pct": 40.0 },
    "statements": { "total": 5, "covered": 2, "skipped": 0, "pct": 40.0 },
    "functions": { "total": 5, "covered": 2, "skipped": 0, "pct": 40.0 },
    "branches": { "total": 5, "covered": 2, "skipped": 0, "pct": 40.0 }
  }
}

[jakobjpeters]

That's great, thank you! I think it needs to be part of the docstring too. Here's an example, if it's helpful, which provides more details for each field. I'm not set on the structure of it though so feel free to adapt if it suits you :)

"""
$(SIGNATURES)

Generate a coverage JSON summary in the package `coverage` directory, mimicking the structure
of the Jest `json-summary` reporter.

If `test_args` are provided, the top level `"total"` key is replaced with the name of the test set.

# JSON Schema

The JSON summary implements [Jest's standard json-summary reporter format](https://stackoverflow.com/a/60968723) ([relevant section of Jest docs](https://jestjs.io/docs/configuration#coveragereporters-arraystring--string-options)).

The top-level object contains a variable number of keys, including the package `total` (or the name of the test set, if customized) followed by keys for each individual tracked file path.

- top-level object
    - 'total`: the combined results of all other keys
    - `file`: the results for the specified file

```json
{
  "total": node,
  "src/foo.jl": node
}
```

- `node`
    - `lines`: ?
    - `statements`: ?
    - `functions`: ?
    - `branches`: ?

```json
{
  "lines": data,
  "statements": data,
  "functions": data,
  "branches": data  
}
```

- `data`
    - `total`: the number of identified nodes
    - `covered: the number of nodes ran by tests
    - `skipped`: the number of nodes not ran in tests
    - `pct`: the percentage of covered nodes `100 * covered / total`

```json
{
  "total": number,
  "covered": number,
  "skipped": number,
  "pct": number
}
```
"""

[tpapp]

I think that this function has too many keyword arguments now (not this PR's fault, it is just following existing style, but this may be a good time to fix things).

I am wondering if it would make sense to have a

json_summary::Union{Nothing,JSONSummaryOptions} = nothing

default, with the alternative

Base.@kwdef struct JSONSummaryOptions
    flename = "coverage-summary.json"
    comparison_filename = nothing
    comparison_fail_on_decrease = false
end

This is just a sketch, typed in the browser, names up to bikeshedding, etc.

[twilsonco]

I agree. Great idea to simplify the function signature. I'll implement this.

[tpapp]

Thanks for this very nice PR! I especially appreciate the thorough tests and documentation. I am very busy now so I just made a quick comment, I will play around with it in detail. If you do not hear from me in a week, feel free to ping, I don't want this to get forgotten.