Documentation
¶
Overview ¶
Package evidence implements `canary evidence`: the commands that produce and accumulate the passing-test records `canary verify` consumes.
- `evidence from-go-test` turns a `go test -json` stream into evidence records for the tokens that declare those tests.
- `evidence ingest` strictly validates a produced file and merges it into the project's evidence store.
Neither command ever invents a record: from-go-test only emits records for tests that actually reported Action="pass", and ingest refuses any file that does not satisfy the record grammar in pkg/evidence.
Index ¶
- Constants
- Variables
- func Merge(current, incoming []ev.Record) []ev.Record
- func PassingBenches(raw []byte) (map[string]map[string]struct{}, error)
- func PassingTests(raw []byte) (map[string]map[string]struct{}, error)
- func Records(rep canaryscan.Report, passed, benches map[string]map[string]struct{}, ...) []ev.Record
- func RunFromGoTest(opts FromGoTestOptions, stdin io.Reader, stdout, stderr io.Writer) int
- func RunIngest(in, out string, stderr io.Writer) int
- func WriteStore(path string, records []ev.Record) error
- type FromGoTestOptions
Constants ¶
const DefaultStorePath = ".canary/evidence.json"
DefaultStorePath is the evidence store's path relative to the project root.
Variables ¶
var EvidenceCmd = &cobra.Command{ Use: "evidence", Short: "Produce and accumulate passing-test evidence records", Long: `Produce and accumulate the evidence records that 'canary verify' consumes. Subcommands: from-go-test Map a 'go test -json' stream to evidence records (stdout) ingest Validate an evidence file and merge it into the store`, PersistentPreRunE: func(cmd *cobra.Command, args []string) error { return nil }, }
EvidenceCmd is the `canary evidence` command group.
Functions ¶
func Merge ¶
Merge appends the records of incoming that the store does not already hold verbatim, preserving the store's existing order. Two records are the same record only when every field matches: a differing digest, timestamp or runner describes a different observation and is kept.
func PassingBenches ¶ added in v0.3.4
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 Records ¶
func Records(rep canaryscan.Report, passed, benches map[string]map[string]struct{}, projectID, commit, runner, observedAt, digest string) []ev.Record
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.
func RunFromGoTest ¶
RunFromGoTest reads a `go test -json` stream from stdin and writes an evidence file to stdout, returning the process exit code.
func RunIngest ¶
RunIngest validates the evidence file at in and merges it into the store at out, returning the process exit code (0 accepted, 1 rejected). Nothing is written when the input is rejected.
func WriteStore ¶
WriteStore writes records to path atomically (staged in the same directory, fsynced, then renamed), creating the directory when needed. A crash mid-write therefore leaves the previous store intact rather than a truncated one. The store is this command's own output, so replacing it is intended; only a partial write would be a defect.
Types ¶
type FromGoTestOptions ¶
type FromGoTestOptions struct {
Root string
ProjectID string
// Commit, when non-empty, is an optional cross-check against Root's
// derived HEAD -- the actual commit every record binds to is always
// derived, never taken from this field on trust.
Commit string
// AllowDirty accepts a working tree that does not match HEAD. Without
// it, RunFromGoTest refuses: evidence stamped with HEAD would otherwise
// describe a tree that exists at no commit.
AllowDirty bool
Runner string
ObservedAt string
}
FromGoTestOptions are the resolved inputs of one from-go-test run.
Source Files