Conversation
|
@sferik Thanks for doing this. Regarding versioned and unversioned schema files, I think the versioned files need to be primary/canonical and the 'latest' or 'current' version a convenience. I think the generated result set data file needs to contain a schema spec that includes the schema version so that it will always be usable when future schema versions are released. I may be misunderstanding though. Here is a ChatGPT discussion of their recommended version strategy and implementation: https://chatgpt.com/share/6a095730-57d0-8322-aac5-38f90035c2ac (References in that chat to 'cov-loupe' are unintentional and should be 'simplecov' instead.) |
| "groups": { "<group name>": { /* per-group stats + files */ } }, | ||
| "errors": { /* minimum_coverage, minimum_coverage_by_file, minimum_coverage_by_group, maximum_coverage_drop violations */ } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Would be nice to get full example for some minimal 'Hello World' script (that covers all features).
|
|
||
| > The JSON formatter was originally a separate gem called [simplecov_json_formatter](https://github.com/codeclimate-community/simplecov_json_formatter). It is now built in and loaded by default. Existing code that does `require "simplecov_json_formatter"` will continue to work. | ||
|
|
||
| ### `coverage.json` schema |
There was a problem hiding this comment.
| ### `coverage.json` schema | |
| ### SimpleCov JSON coverage format schema |
| @@ -0,0 +1,242 @@ | |||
| { | |||
| "$schema": "http://json-schema.org/draft-07/schema#", | |||
There was a problem hiding this comment.
The latest spec is 2020-12. Why not use it?
There was a problem hiding this comment.
I mention my reasoning for this in the PR description above:
I chose JSON Schema Draft-07 over 2020-12, since nothing in the shape needs the newer features and there still seems to be better tooling for Draft-07.
|
|
||
| ### `coverage.json` schema | ||
|
|
||
| The `coverage.json` payload is treated as a public contract. Every emitted file carries a `meta.schema_version` (`"major.minor"`) describing which version of the schema it conforms to. A JSON Schema (draft-07) lives in the repo at [`schemas/coverage.schema.json`](schemas/coverage.schema.json); downstream tools can use it to validate inputs, generate types, or pin themselves to a known shape. |
There was a problem hiding this comment.
| The `coverage.json` payload is treated as a public contract. Every emitted file carries a `meta.schema_version` (`"major.minor"`) describing which version of the schema it conforms to. A JSON Schema (draft-07) lives in the repo at [`schemas/coverage.schema.json`](schemas/coverage.schema.json); downstream tools can use it to validate inputs, generate types, or pin themselves to a known shape. | |
| Generated `coverage.json` is covered by the [JSON Schema](schemas/coverage.schema.json), so that tools can validate and use it as interchangeable format. | |
| The schema is versioned, with the version stored in `meta.schema_version` (`"major.minor"`). |
| gem.required_ruby_version = ">= 3.1" | ||
|
|
||
| gem.files = Dir["lib/**/*.*", "exe/*", "LICENSE", "CHANGELOG.md", "README.md", "doc/*"] | ||
| gem.files = Dir["{lib,schemas}/**/*.*", "exe/*", "LICENSE", "CHANGELOG.md", "README.md", "doc/*"] |
There was a problem hiding this comment.
While we are at it, maybe it is possible to generate human readable documentation with real world examples to close #1030 (comment) ?
There are a couple of documentation generators listed https://json-schema.org/tools#documentation but I haven't found a nice one yet.
|
Since we want third-party tools to use the
coverage.json(and not.resultset.json), we should encourage that by versioning the document and publishing a JSON Schema. This was suggested by @keithrbennett in #1143 (comment) and I agree that it’s a good idea.This PR adds:
schemas/coverage.schema.json, which includes meta, total, per-file coverage, groups, and all four errors shapes. The gemspec has also been modified to add theschemasdirectory.meta.schema_version(currently "1.0"), which is intentionally independent of the gem version, so we can bump the gem version without bumping the schema version.JSONFormatteroutput against the schema.json_schemeras a development dependency to validate the schema.A few choices worth mentioning:
docs/tree, since that’s where people land and I don’t think there’s enough documentation to warrant its own directory at this point.