Documentation
¶
Overview ¶
Package gotestevents parses `go test -json` event streams into passing tests/benches and re-derives whether an evidence.Record is actually backed by them. It is a leaf package -- it imports only stdlib + pkg/evidence -- so that BOTH pkg/gotest (which needs pkg/canaryscan for Records) and pkg/canaryscan (which cannot import pkg/gotest without creating an import cycle) can share the same semantic artifact-derivation logic instead of each maintaining its own copy.
Index ¶
- Constants
- func ArtifactPath(base, artifactDigest string) string
- func BenchObservedPackages(declaredName string, observed map[string]map[string]struct{}) (pkgs map[string]struct{}, ok bool)
- func ParseStream(raw []byte) (passed, benches map[string]map[string]struct{}, err error)
- func RecordDerivable(rec ev.Record, passed, benched map[string]map[string]struct{}) bool
- func SplitQualified(entry string) (name, pkg string)
Constants ¶
const MaxEventLineBytes = 4 << 20
MaxEventLineBytes bounds one `go test -json` event line. Test output is embedded in events, so a test that prints a large blob produces a large line; anything past this is not an event worth reading.
Variables ¶
This section is empty.
Functions ¶
func ArtifactPath ¶
ArtifactPath returns the path to the retained raw-stream artifact for a "sha256:<hex>" digest under base (the directory holding the evidence store, usually "<root>/.canary"): "<base>/artifacts/<hex>.json".
func BenchObservedPackages ¶
func BenchObservedPackages(declaredName string, observed map[string]map[string]struct{}) (pkgs map[string]struct{}, ok bool)
BenchObservedPackages resolves a declared BENCH= name (already split from any "pkg:" qualifier by SplitQualified) against observed -- the benches/benched map ParseStream returns, keyed by the exact benchmark name `go test -json` reported for each event -- applying the parent/leaf mapping rule (C6-08).
A table-driven benchmark (func BenchmarkX(b *testing.B) { b.Run("caseA", ...); b.Run("caseB", ...) }) never emits an event keyed by the bare "BenchmarkX" -- only by its sub-benchmarks' full "BenchmarkX/caseA" and "BenchmarkX/caseB" paths -- so a BENCH=BenchmarkX declaration naming the parent must still resolve against those leaves, or it silently proves nothing (a false-negative completion). declaredName matches an observed key that is either EXACTLY declaredName (a leaf declaration such as "BenchmarkX/caseA", or a non-table benchmark observed directly under its own name) OR has declaredName+"/" as a prefix (any sub-benchmark of a table-driven parent). The match is anchored on that "/" path boundary only: "BenchmarkX" matches "BenchmarkX/caseA" but never "BenchmarkXY" -- a plain strings.HasPrefix(name, declaredName) without the trailing "/" would wrongly accept that. The returned set is the union of every matching key's packages; ok is false when declaredName matched nothing at all (an invalid BENCH= name), mirroring a plain map miss so callers can treat it exactly like today's "no record" case.
func ParseStream ¶
ParseStream parses raw as a `go test -json` event stream exactly once and returns both the passing tests and the completed benches it observed -- the minimal single-pass entry point for a caller that needs both results without scanning the stream twice.
func RecordDerivable ¶
RecordDerivable reports whether rec's (TestID, Package) claim is actually backed by passed/benched -- the maps ParseStream returns from re-parsing rec's retained artifact. For an ordinary test record it looks rec.TestID up in passed directly (exact name match only -- tests have no parent/leaf concept). For a bench record (rec.Kind == "bench") it resolves rec.TestID against benched via BenchObservedPackages, so a record produced from a declared parent name (matched against its observed sub-benchmarks, C6-08) re-derives the same way it was produced -- production and verification apply the identical rule. Either way, an unqualified rec.Package ("") matches the name having passed/completed/resolved in ANY package, mirroring evaluateKey's find closure in pkg/evidence/complete.go; a non-empty rec.Package must find that exact package.
This is the single semantic re-derivation predicate shared by every consumer that must prove an "executed" record from a local artifact rather than merely trust its digest: pkg/cmds/evidence's RunIngest (demoting a record it cannot re-derive) and `canary verify`'s artifact re-check (C5-01) both call this instead of duplicating the (TestID, Package) membership logic.
func SplitQualified ¶
SplitQualified splits an optionally package-qualified TEST=/BENCH= entry. "pkg/path:TestX" pins the name to one import path; a bare "TestX" matches any package it passed/completed in.
Types ¶
This section is empty.
Source Files