Documentation
¶
Overview ¶
Package contractverify runs a consumer repo's contract validators against the configured fixtures and reports verdicts. It is the engine half of contract verification; the CLI verb (`aiwf contract verify`) and the pre-push integration (`aiwf check`) are thin callers.
Two passes per contract:
- Verify pass: the *current* fixture-tree version (lexicographically highest directory name) is exercised. Every file in `valid/` is expected to pass; every file in `invalid/` is expected to fail.
- Evolve pass: every *non-current* version's `valid/` fixtures are run against the HEAD schema. Failures here flag silent breakage introduced by a schema change that broke historical compatibility.
The engine is validator-agnostic. It executes the user-declared command + args (with four documented substitution variables) and makes one judgment: exit code 0 means accepted; non-zero means rejected. stdout and stderr are captured as opaque text and surfaced in finding details so the user can see what their tool said.
One reclassification keeps noise down: when *every* `valid/` fixture for a contract is rejected, the schema itself is the more likely culprit. The per-fixture findings collapse into a single `validator-error` for the contract.
Index ¶
Constants ¶
const ( CodeFixtureRejected = "fixture-rejected" CodeFixtureAccepted = "fixture-accepted" CodeEvolutionRegression = "evolution-regression" CodeValidatorError = "validator-error" CodeEnvironment = "environment" )
Finding code constants. The set is closed and matches §10 of docs/pocv3/plans/contracts-plan.md.
CodeValidatorUnavailable is distinct from CodeEnvironment: the former means "binary is not on PATH" (a per-machine env issue that should not block teammates from pushing); the latter is for genuine env errors during a *successful* exec lookup (binary disappeared between LookPath and exec, etc.). The downstream wiring renders validator-unavailable as a warning by default and as an error only when strict_validators is set.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// RepoRoot is the consumer repo root. Validators run with this
// as their working directory; schema and fixture paths in
// Contracts are resolved relative to it.
RepoRoot string
// Contracts is the parsed `contracts:` block from aiwf.yaml.
// Pass a non-nil value with empty Entries for a no-op pass.
Contracts *aiwfyaml.Contracts
// SkipIDs lists contract entity ids that should be excluded from
// verification. Callers fill this with ids whose status is
// `rejected` or `retired`; the package itself has no entity
// awareness.
SkipIDs map[string]bool
}
Options configures one verify-and-evolve pass over the consumer repo's contract bindings.
type Result ¶
type Result struct {
Code string
Message string
Detail string
EntityID string
Version string
FixturePath string
}
Result is one verdict produced by the verify or evolve pass. Code corresponds to the documented finding codes in §10 of the contracts plan; see the constants below for the closed set.
Detail carries the raw stderr/stdout of the validator invocation for fixture-level findings, or a free-form explanation for contract-level findings.
func Run ¶
Run executes the verify and evolve passes for every binding in opts.Contracts.Entries (skipping ids listed in opts.SkipIDs) and returns the resulting findings. The slice is sorted: contract id first, then code, then version, then fixture path — so output is stable regardless of filesystem walk order.
Run never returns a Go error: every failure mode (missing binary, missing fixture path, bad exit code) becomes a Result.
Source Files