Documentation
¶
Overview ¶
Package coverage is the single home for Go statement-coverage attribution in codegrapher: it turns a `go test -coverprofile` profile into per-file and per-function coverage records, and defines the INGR recordset format those records are exported/uploaded/served in.
One library, several callers:
- the `codegrapher coverage` CLI runs Ingest locally on the same checkout the tests ran on (guaranteed matching commit) and emits the recordsets;
- the server validates uploaded recordsets via Validate and stores them next to graph data;
- any other consumer may call Ingest directly against an open *store.Store.
Scope: Go only. Exact blocks and NumStmt are authoritative; lines are a navigation aid. Per-function counts are attributed to the INNERMOST enclosing node (non-overlapping); inclusive roll-ups (a function plus its nested closures) are computed by consumers via the graph's `contains` edges, not stored here.
Index ¶
- Constants
- func EncodeFileCoverage(w io.Writer, recs []FileCoverage) error
- func EncodeNodeCoverage(w io.Writer, recs []NodeCoverage) error
- func LineStates(blocks []Block) map[int]string
- func Pct(covered, uncovered int) float64
- func Validate(recordset string, data []byte) error
- type Block
- type FileCoverage
- type Ingestor
- type NodeCoverage
- type Options
- type Range
- type Summary
Constants ¶
const ( RecordsetCoverage = "coverage" RecordsetNodeCoverage = "node_coverage" )
Recordset names. These are the INGR collection identifiers used on disk ({name}.ingr), in the snapshot manifest counts, and on the wire when the CLI uploads to the server's collect endpoint.
const ( KindHit = "hit" KindMiss = "miss" KindPartial = "partial" )
Variables ¶
This section is empty.
Functions ¶
func EncodeFileCoverage ¶
func EncodeFileCoverage(w io.Writer, recs []FileCoverage) error
EncodeFileCoverage writes recs as the "coverage" INGR recordset, sorted by file path for byte-determinism.
func EncodeNodeCoverage ¶
func EncodeNodeCoverage(w io.Writer, recs []NodeCoverage) error
EncodeNodeCoverage writes recs as the "node_coverage" INGR recordset, sorted by node id for byte-determinism.
func LineStates ¶ added in v0.14.2
LineStates is a navigation aid derived from exact blocks. A line touched by both hit and missed blocks is partial; absent lines are unmeasured.
func Pct ¶
Pct returns the covered percentage for the given line counts, or 0 when there are no measured lines.
func Validate ¶
Validate checks that data is a well-formed INGR recordset for the named collection ("coverage" or "node_coverage"): decodable, every record has a non-empty $ID and content_hash, non-negative counts, and (for coverage) parseable ranges with valid kinds. The server collect endpoint calls this on uploaded bytes before storing them.
Types ¶
type Block ¶ added in v0.14.2
type Block struct {
StartLine int `json:"startLine"`
StartCol int `json:"startCol"`
EndLine int `json:"endLine"`
EndCol int `json:"endCol"`
NumStmt int `json:"numStmt"`
Hit bool `json:"hit"`
}
Block is one exact Go coverprofile block. End is the exclusive source position. Hit records whether this block ran in at least one composed profile.
type FileCoverage ¶
type FileCoverage struct {
FilePath string `json:"filePath"`
ContentHash string `json:"contentHash"`
Mode string `json:"mode"` // go profile mode: set | count | atomic
Ranges []Range `json:"ranges"`
Blocks []Block `json:"blocks,omitempty"`
StatementsCovered int `json:"statementsCovered,omitempty"`
StatementsUncovered int `json:"statementsUncovered,omitempty"`
Ref string `json:"ref,omitempty"`
LinesCovered int `json:"linesCovered"`
LinesUncovered int `json:"linesUncovered"`
PctCovered float64 `json:"pctCovered"`
RunAt int64 `json:"runAt"` // unix ms
}
FileCoverage is per-file Go coverage from one ingest run. ContentHash is the file's hash at ingest time; a later mismatch against the live file marks this record stale (consumers keep + flag it, never drop). PctCovered is derived from statement counts when present, falling back to lines for legacy recordsets; it is not stored in the recordset.
func DecodeFileCoverage ¶
func DecodeFileCoverage(r io.Reader) ([]FileCoverage, error)
DecodeFileCoverage reads a "coverage" INGR recordset. PctCovered is recomputed from the line counts.
func FileCoverageFromStore ¶
func FileCoverageFromStore(st *store.Store) ([]FileCoverage, error)
FileCoverageFromStore reads every per-file coverage row from st and converts it to []FileCoverage (decoding the stored RLE JSON). Used by the CLI and the snapshot exporter to emit the "coverage" recordset.
type Ingestor ¶
type Ingestor interface {
Ingest(ctx context.Context, st *store.Store, profile io.Reader, opts Options) (Summary, error)
IngestMany(ctx context.Context, st *store.Store, profiles []io.Reader, opts Options) (Summary, error)
}
Ingestor parses Go coverage profiles and writes coverage + node_coverage records into st, attributing statements to the innermost enclosing node.
func NewIngestor ¶
func NewIngestor() Ingestor
NewIngestor returns the default Ingestor (the real attribution implementation).
type NodeCoverage ¶
type NodeCoverage struct {
NodeID string `json:"nodeId"`
ContentHash string `json:"contentHash"`
LinesCovered int `json:"linesCovered"`
LinesUncovered int `json:"linesUncovered"`
StatementsCovered int `json:"statementsCovered,omitempty"`
StatementsUncovered int `json:"statementsUncovered,omitempty"`
Ref string `json:"ref,omitempty"`
PctCovered float64 `json:"pctCovered"`
RunAt int64 `json:"runAt"` // unix ms
}
NodeCoverage is innermost-attributed statement and line counts for one function/method node. Blocks inside a nested closure count toward that closure, not its parent (non-overlapping). PctCovered is derived, not stored in the recordset.
func DecodeNodeCoverage ¶
func DecodeNodeCoverage(r io.Reader) ([]NodeCoverage, error)
DecodeNodeCoverage reads a "node_coverage" INGR recordset. PctCovered is recomputed from the line counts.
func NodeCoverageFromStore ¶
func NodeCoverageFromStore(st *store.Store) ([]NodeCoverage, error)
NodeCoverageFromStore reads every per-node coverage row from st and converts it to []NodeCoverage. Used by the CLI and snapshot exporter to emit the "node_coverage" recordset.
type Options ¶
type Options struct {
// Ref is the supplied source ref or run identity, stored in local rows and
// exported recordsets. Go profiles do not prove their source revision.
Ref string
// Root is the repository root used to resolve profile (module) paths to the
// repo-relative file paths stored in the graph.
Root string
// Now overrides the RunAt clock (unix ms). nil uses the real clock.
Now func() int64
// Merge accumulates hits from an earlier ingest only for identical source
// hashes, profile modes, and exact block layouts.
Merge bool
// ProfileModifiedAt is the oldest supplied profile's filesystem mtime in
// Unix milliseconds. CLI ingest refuses source files newer than it.
ProfileModifiedAt int64
// ValidateOnly checks composition for a CLI preflight without writing rows.
ValidateOnly bool
}
Options configure an Ingest run.
Source Files