Documentation
¶
Overview ¶
Package verify implements `canary verify`: the evidence-backed answer to "are this project's claims true right now?". It reads declarations from the tree, claims from a gap-analysis file, and passing-test evidence from the evidence store, then delegates the verdict to pkg/evidence.Complete — the single completion function. Nothing here decides completeness on its own.
Index ¶
Constants ¶
const ( FormatJSON = "json" FormatText = "text" )
Format values accepted by --format.
const DefaultEvidencePath = ".canary/evidence.json"
DefaultEvidencePath is the evidence store's path relative to the project root.
Variables ¶
var VerifyCmd = &cobra.Command{ Use: "verify [flags]", Short: "Verify claimed requirements against passing-test evidence", Long: `Verify that every requirement claimed in a gap-analysis file has passing evidence recorded at the current commit. Claims are lines like "✅ <REQ-ID>" in the claims file. For each claimed requirement, every feature/aspect it declares in source must have a PASS evidence record for this project at HEAD. Declarations alone (STATUS=TESTED, TEST=...) never verify anything. Exit codes: 0 verified, 1 not verified (or unknowable). Flags: --root <dir> Project root to scan (default ".") --claims <file> Claims file (default "GAP_ANALYSIS.md") --evidence <file> Evidence store (default ".canary/evidence.json") --format json|text Output format (default "json") --project <id> Override the configured project key --allow-empty Treat a claims file with no claims as verified --allow-unknown-external Do not block on unresolvable external dependencies --allow-dirty Accept a working tree that does not match HEAD --allow-imported Accept evidence imported from a stream (from-go-test/ingest) rather than executed by canary evidence run --require-attestation Require a valid, trusted-key-signed attestation for every executed record (see 'canary evidence keygen'); default off --trusted-keys <path|dir> ed25519 public key(s) trusted for --require-attestation (default: configured evidence.trusted_keys) Examples: canary verify canary verify --format text --claims GAP_ANALYSIS.md`, PersistentPreRunE: func(cmd *cobra.Command, args []string) error { return nil }, RunE: func(cmd *cobra.Command, args []string) error { opts := Options{} opts.Root, _ = cmd.Flags().GetString("root") opts.ClaimsPath, _ = cmd.Flags().GetString("claims") opts.EvidencePath, _ = cmd.Flags().GetString("evidence") opts.Format, _ = cmd.Flags().GetString("format") opts.ProjectID, _ = cmd.Flags().GetString("project") opts.AllowEmpty, _ = cmd.Flags().GetBool("allow-empty") opts.AllowUnknownExternal, _ = cmd.Flags().GetBool("allow-unknown-external") opts.AllowDirty, _ = cmd.Flags().GetBool("allow-dirty") opts.AllowImported, _ = cmd.Flags().GetBool("allow-imported") opts.RequireAttestation, _ = cmd.Flags().GetBool("require-attestation") opts.TrustedKeys, _ = cmd.Flags().GetString("trusted-keys") if opts.Format != FormatJSON && opts.Format != FormatText { return fmt.Errorf("unknown --format %q (want %q or %q)", opts.Format, FormatJSON, FormatText) } if code := RunContext(cmd.Context(), opts, cmd.OutOrStdout(), cmd.ErrOrStderr()); code != 0 { telemetry.Flush() os.Exit(code) } return nil }, }
CANARY: REQ=CP-236; FEATURE="EvidenceVerify"; ASPECT=CLI; STATUS=TESTED; TEST=TestAuditF01CLI,TestAuditF01CLI_PartialDeclaredTestsUnproven,TestAuditF15CLI,TestAuditF22,TestVerifyRun_EvidenceMissing,TestVerifyRun_Verified,TestVerifyRun_WrongCommitIsNotVerified,TestVerifyRun_TextFormat,TestVerifyRun_ScanIssueIsIncomplete,TestVerifyRun_UndeclaredClaim,TestVerifyRun_MissingClaimsFileIsUnknown,TestVerifyRun_ExternalUnknownBlocks,TestVerifyRun_ProjectOverride,TestVerifyRun_DirtyTreeRefused,TestVerifyRun_AllowDirtyOptsOut,TestVerifyRun_RelativeClaimsResolvesUnderRoot,TestVerifyRun_ImportedEvidenceIneligibleByDefault,TestVerifyRun_DirtyEvidenceNeverEligible,TestVerifyRun_ArtifactMismatchIsUnknown,TestVerifyRun_MissingArtifactMakesExecutedIneligible,TestVerifyRun_ArtifactSemanticMismatchIsUnknown,TestVerifyRun_ReceiptFieldsOnSuccess,TestVerifyRun_OverridesVisible,TestAuditC606,TestAuditC608; UPDATED=2026-09-01 VerifyCmd is the `canary verify` command.
Functions ¶
func Run ¶
Run performs one verification and returns the process exit code: 0 when the verdict is OK, 1 otherwise. Exactly one line is ever written to stdout (the verdict); every diagnostic goes to stderr.
Run delegates to RunContext with context.Background(); callers that have a context available (e.g. a cobra command) should call RunContext directly so cancellation and future tracing spans thread through verification.
func RunContext ¶ added in v0.3.8
RunContext is Run's context-aware form: identical behavior, but an already-cancelled (or later-cancelled) ctx makes verification abort with the UNKNOWN/SCAN_INCOMPLETE verdict rather than proceeding -- a cancelled caller must never receive a verdict computed from a scan it asked to stop.
Types ¶
type Options ¶
type Options struct {
Root string
ClaimsPath string
// ClaimsReader, when supplied, is an already-authorized stream opened by
// the caller. ClaimsPath remains provenance; it is not reopened.
ClaimsReader io.Reader
EvidencePath string
Format string
// ProjectID overrides the configured project.key when non-empty.
ProjectID string
AllowEmpty bool
AllowUnknownExternal bool
// AllowDirty accepts a working tree that does not match HEAD. Without
// it, Run refuses with DIRTY_TREE: evidence bound to HEAD cannot answer
// for a tree HEAD no longer describes.
AllowDirty bool
// AllowImported accepts evidence records whose origin is "imported"
// (from-go-test/ingest) rather than "executed" (canary evidence run).
// Without it, imported records are dropped before verification: they
// were not produced by canary's own dedicated verifier and are not, by
// default, trusted to prove a claim.
AllowImported bool
// RequireAttestation and TrustedKeys are Plan-8 Task 6 additions
// (C6-01b/C6-02): when RequireAttestation is true, an "executed" record
// is eligible ONLY when it carries a valid attestation sidecar --
// verified against a key in TrustedKeys and matching the record's own
// project/commit/source/artifact/toolchain fields (see
// gotest.AttestationValid) -- everything else is dropped, counted as
// "unattested" in EVIDENCE_DROPPED. TrustedKeys names a file or
// directory of ed25519 public keys (pkg/attest.LoadPublicKeys). DEFAULT
// (RequireAttestation false, the flag's zero value): this whole gate is
// skipped and the pre-Task-6 behavior is exactly unchanged -- filesystem
// trust in the operator-named toolchain remains the only basis for
// "executed" evidence.
RequireAttestation bool
TrustedKeys string
}
Options are the resolved inputs of one verification run.
Source Files