Documentation
¶
Overview ¶
Package gotest parses `go test -json` event streams into evidence records, independent of the `canary evidence` command package. It exists so other consumers (e.g. `canary verify`'s executed-evidence re-derivation) can call the same stream parser and record-derivation logic without importing a cobra command package.
Index ¶
- func ArtifactPath(base, artifactDigest string) string
- func ParseStream(raw []byte) (passed, benches map[string]map[string]struct{}, err error)
- func PassingBenches(raw []byte) (map[string]map[string]struct{}, error)
- func PassingTests(raw []byte) (map[string]map[string]struct{}, error)
- func RecordDerivable(rec ev.Record, passed, benched map[string]map[string]struct{}) bool
- func Records(rep canaryscan.Report, passed, benches map[string]map[string]struct{}, ...) ([]ev.Record, error)
- type Drops
Constants ¶
This section is empty.
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 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 (such as `emitFromStream`) that needs both results without scanning the stream twice.
func PassingBenches ¶
PassingBenches parses a `go test -json` event stream and returns, per benchmark name, the set of package import paths in which it ran to completion: an output event carried its result line, AND that package's terminal action was "pass". A benchmark inside a package whose run failed -- even if its own result line was printed before the failure -- produces no evidence, mirroring PassingTests' fail-vetoes-everywhere discipline at the only granularity benchmarks report: the package.
func PassingTests ¶
PassingTests parses a `go test -json` event stream and returns, per test name, the set of package import paths in which it passed. A test name that failed in ANY package is vetoed everywhere: passing in package A does not excuse failing in package B.
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. It selects passed for an ordinary test record and benched for a bench record (rec.Kind == "bench"), then checks that rec.TestID appears there: an unqualified rec.Package ("") matches the name having passed/completed 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 Records ¶
func Records(rep canaryscan.Report, passed, benches map[string]map[string]struct{}, projectID, commit, runner, observedAt, digest, origin string, dirty bool) ([]ev.Record, error)
Records builds one evidence record per (requirement, feature, aspect, test x passing package) declared by a token whose test is in passed, plus one per (requirement, feature, aspect, bench x completed package) declared by a token whose bench is in benches. Records are sorted by requirement, feature, aspect, test/bench, then package so repeated runs over the same inputs produce byte-identical output.
A declared name that is not package-qualified (no "pkg:Name" prefix) and was observed passing in more than one package is ambiguous -- an unrelated same-named test in another package could otherwise satisfy the declaration -- and Records refuses to emit any record for it, returning an error instead. Qualify the declaration as "pkg:Name" to disambiguate.
origin and dirty are stamped onto every emitted record: origin records how the evidence was produced ("executed" or "imported"), and dirty records whether the working tree matched HEAD when it was produced.
Types ¶
type Drops ¶
Drops counts the records LoadEligible removed from a store, broken out by reason: Dirty (working tree was not HEAD when recorded), Imported (origin other than "executed", refused unless the policy allows it), and Artifactless (an "executed" record whose local artifact is missing or whose bytes do not re-hash to the record's digest).
func LoadEligible ¶
LoadEligible loads <root>/.canary/evidence.json and filters it under policy p, applying the SAME trust rules `canary verify` enforces by default so that a record the verifier would refuse cannot suppress work in `next`, satisfy a `deps check`, or unlock a `ticket sync` transition (C5-02):
- a Dirty record is always dropped: it describes a working tree that was not HEAD when it was produced, and can never prove anything about the tree in front of the caller.
- a record whose Origin is not "executed" (imported, or unset) is dropped unless p.AllowImported is true.
- an "executed" record is dropped when its local artifact -- at ArtifactPath(<root>/.canary, record.ArtifactDigest) -- is missing, or when the artifact's bytes do not re-hash to the record's ArtifactDigest. This is the CHEAP integrity check only: it proves the artifact exists and is unmodified, not that it actually contains a pass for this specific record's (TestID, Package). The full semantic re-derivation (RecordDerivable, re-parsing the artifact's events) stays verify-only -- LoadEligible's callers (next, deps, ticket) get the cheaper guarantee, not the full one.
A missing evidence store is not an error -- nothing has been proven yet -- and returns (nil, Drops{}, nil). A malformed one IS an error: treating unparseable evidence as merely absent would hide tampering behind an outcome ("dependency incomplete", "no work available") that reads like ordinary progress.
Source Files