Documentation
¶
Overview ¶
Package evidence implements `canary evidence`: the commands that produce and accumulate the passing-test records `canary verify` consumes.
- `evidence run` executes a test command itself and emits evidence records for the tokens that declare the tests it observed pass -- origin "executed", the trusted producer `canary verify` requires by default.
- `evidence from-go-test` turns a `go test -json` stream already on stdin into evidence records -- origin "imported", since the stream was produced by something other than this command.
- `evidence ingest` strictly validates a produced file and merges it into the project's evidence store.
None of these commands ever invents a record: run and from-go-test only emit 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, error)
- func RunExec(opts FromGoTestOptions, argv []string, stdout, stderr io.Writer) int
- 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.
const MaxStreamBytes = 512 << 20
MaxStreamBytes bounds the total go-test event stream. Beyond this the stream is rejected before any evidence is derived (resource exhaustion and truncation are indistinguishable from tampering at this layer).
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: run Execute a test command itself; emit evidence (stdout), origin "executed" from-go-test Map a 'go test -json' stream to evidence records (stdout), origin "imported" 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, 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.
func RunExec ¶ added in v0.3.5
func RunExec(opts FromGoTestOptions, argv []string, stdout, stderr io.Writer) int
RunExec executes argv itself (Dir=opts.Root), captures its stdout bounded by MaxStreamBytes, lets its stderr flow through to stderr, derives HEAD/dirty state exactly like RunFromGoTest, then emits evidence records with origin "executed" and every record's Command set to the actual argv that ran. Unlike from-go-test, canary itself ran the command, so the resulting evidence is the trusted producer `canary verify` requires by default.
func RunFromGoTest ¶
RunFromGoTest reads a `go test -json` stream from stdin and writes an evidence file to stdout, returning the process exit code. Every record's origin is "imported": the stream was produced by something other than this command, so it is trusted only as far as `canary verify --allow-imported` permits.
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