Documentation
¶
Overview ¶
Package evidence holds strict parsing of CANARY evidence records and the single completion function ("has every claimed requirement been proven at the current commit") that downstream verification consumes. It is self-contained: stdlib only, no imports from the rest of this repo, so any package may depend on it without creating a cycle.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompleteReq ¶
func CompleteReq(reqID string, keys []FeatureKey, recs []Record, projectID, commit string) bool
CompleteReq is the single-requirement form of Complete, and the shared entry point behind the two surfaces that answer "is this local dependency satisfied?" -- `canary next`'s dependency gate and `canary deps check`. reqID is complete iff every key has a PASS record for projectID at commit. An empty keys slice yields false (EMPTY_CLAIMS): a dependency with nothing to prove is not proven. Routing both callers through here keeps ONE completion definition -- a declared STATUS=TESTED is a claim on both surfaces, never proof.
Types ¶
type FeatureKey ¶
type FeatureKey struct {
Feature string `json:"feature"`
Aspect string `json:"aspect"`
Tests []string `json:"tests,omitempty"` // declared TEST= names, optionally "pkg/path:Name"
Benches []string `json:"benches,omitempty"` // declared BENCH= names, optionally qualified
}
FeatureKey identifies one claimed feature/aspect within a requirement, and optionally the exact declared TEST=/BENCH= names that must each have their own passing evidence record. An entry may be package-qualified as "pkg/path:Name"; a bare name matches any package.
type File ¶
type File struct {
SchemaVersion int `json:"schema_version"` // must be 1
Records []Record `json:"records"`
}
File is the top-level shape of an evidence document.
func Load ¶
Load reads and strictly parses the evidence file at path. A missing file returns an error wrapping fs.ErrNotExist so callers can distinguish it (via errors.Is) from a malformed one.
func Parse ¶
Parse strictly decodes an evidence file from r. It rejects, with an error naming the offending record index and field: unknown fields anywhere, duplicate fields anywhere (encoding/json silently keeps the last value on a duplicate key, so this is caught with an explicit token walk before the struct decode), a schema_version other than 1, any empty required field, a result other than exactly "PASS", and a malformed commit_sha, artifact_digest, or observed_at.
type Missing ¶
type Missing struct {
RequirementID string `json:"requirement_id"`
Key FeatureKey `json:"key"`
Reason string `json:"reason"` // "no_evidence" | "wrong_commit" | "scope_mismatch" | "test_unproven" | "bench_unproven"
}
Missing describes one required feature/aspect that Complete could not find satisfying evidence for.
type Record ¶
type Record struct {
ProjectID string `json:"project_id"`
RequirementID string `json:"requirement_id"`
Feature string `json:"feature"`
Aspect string `json:"aspect"`
TestID string `json:"test_id"`
Package string `json:"package,omitempty"` // import path the test ran in; "" in legacy records
Kind string `json:"kind,omitempty"` // "" or "test" means test; "bench" means benchmark
Command string `json:"command"`
Result string `json:"result"` // must be exactly "PASS"
CommitSHA string `json:"commit_sha"` // exactly 40 lowercase hex
ObservedAt string `json:"observed_at"` // RFC3339, must be UTC (Z or +00:00)
Runner string `json:"runner"`
ArtifactDigest string `json:"artifact_digest"` // "sha256:" + 64 lowercase hex
}
Record is one evidence claim: a single passing test run, tying a requirement's feature/aspect to a commit via a reproducible command and an observed result.
type Verdict ¶
type Verdict struct {
OK bool `json:"ok"`
State string `json:"state"` // "VERIFIED" | "UNVERIFIED" | "UNKNOWN"
Code string `json:"code"` // "OK" | "EVIDENCE_MISSING" | "EMPTY_CLAIMS" | "SCAN_INCOMPLETE" | "EXTERNAL_UNKNOWN"
Message string `json:"message"`
Missing []Missing `json:"-"`
}
Verdict is the result of a completion check.
func Complete ¶
func Complete(required map[string][]FeatureKey, recs []Record, projectID, commit string, allowEmpty bool) Verdict
Complete is THE completion function: every required feature/aspect of every required requirement must have at least one record with Result=PASS (guaranteed by Parse), ProjectID==projectID, and CommitSHA==commit. An empty required map yields EMPTY_CLAIMS unless allowEmpty is set, in which case it is treated as trivially satisfied.
The Missing list, when non-empty, is sorted deterministically by (RequirementID, Feature, Aspect) so repeated runs over the same inputs produce byte-identical output.
Source Files