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 PassingTests(raw []byte) map[string]string
- func Records(rep canaryscan.Report, passed map[string]string, ...) []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 PassingTests ¶
PassingTests returns the test names that reported Action="pass" in a `go test -json` stream, mapped to the package they ran in — but only for names that never also reported Action="fail" anywhere in the stream. A test name that passed in one package and failed in another (e.g. the same subtest name reused across packages) is vetoed entirely: it is a lie to call that name "passing" when the stream also shows it failing, so no record is emitted for it at all, regardless of how many packages it passed in.
The stream is read line by line and any line that is not a JSON event is skipped: `go test -json` can interleave raw build/vet output with events, and a build log line must not cost the whole run its evidence. Skipping is safe in the only direction that matters — an unreadable line can only produce FEWER records, never a record for a test that did not pass.
func Records ¶
func Records(rep canaryscan.Report, passed map[string]string, projectID, commit, runner, observedAt, digest string) []ev.Record
Records builds one evidence record per (requirement, feature, aspect, test) whose test is in passed. Records are sorted by requirement, feature, aspect then test 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.
Source Files