verification

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 30, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package verification defines and assembles the portable change-verification report shared by the CLI, GitHub Action, and MCP adapters.

Index

Constants

View Source 
const (
	// SchemaVersion identifies the frozen unified verification contract.
	SchemaVersion = "agentic.verify/v1"
	// ArchivedBetaSchemaVersion identifies reports emitted before the v1 freeze.
	ArchivedBetaSchemaVersion = "agentic.verify/v1beta1"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AnalysisSummary 

type AnalysisSummary struct {
	Base       int `json:"base"`
	Current    int `json:"current"`
	Introduced int `json:"introduced"`
	Existing   int `json:"existing"`
	Resolved   int `json:"resolved"`
	Unknown    int `json:"unknown"`
}

AnalysisSummary contains base/current analyzer comparison counts.

type BaselineState 

type BaselineState string

BaselineState describes how an analyzer diagnostic compares with the base. 

const (
	BaselineIntroduced BaselineState = "introduced"
	BaselineExisting   BaselineState = "existing"
	BaselineResolved   BaselineState = "resolved"
	BaselineUnknown    BaselineState = "unknown"
)

Baseline states classify diagnostics relative to the merge-base snapshot.

type Change 

type Change struct {
	Files                 []ChangedFile        `json:"files"`
	FilesTotal            int                  `json:"files_total"`
	FilesTruncated        bool                 `json:"files_truncated"`
	Declarations          []ChangedDeclaration `json:"declarations"`
	DeclarationsTotal     int                  `json:"declarations_total"`
	DeclarationsTruncated bool                 `json:"declarations_truncated"`
}

Change contains the source facts in a change snapshot.

type ChangeAnalysis 

type ChangeAnalysis struct {
	Repository       Repository
	Files            []SourceFile
	Packages         []ExecutionTarget
	Uncertainties    []Uncertainty
	Risks            []RiskArea
	Change           Change
	Impact           Impact
	ObservedPackages int
	Complete         bool
}

ChangeAnalysis is the complete discovery handoff consumed by Engine.

type ChangeAnalyzer 

type ChangeAnalyzer interface {
	Analyze(context.Context, ChangeOptions) (ChangeAnalysis, error)
	MaterializeBase(context.Context, Repository, string) (string, error)
}

ChangeAnalyzer discovers the final source snapshot and affected unit closure. The interface keeps Git and Go package mechanics outside the verification engine without introducing a general plugin abstraction.

type ChangeKind 

type ChangeKind string

ChangeKind describes a final-snapshot file or declaration change. 

const (
	ChangeAdded     ChangeKind = "added"
	ChangeModified  ChangeKind = "modified"
	ChangeDeleted   ChangeKind = "deleted"
	ChangeRenamed   ChangeKind = "renamed"
	ChangeUntracked ChangeKind = "untracked"
)

Change kinds describe final-worktree paths and declarations.

type ChangeOptions 

type ChangeOptions struct {
	Base        string
	Package     string
	MaxPackages int
}

ChangeOptions bounds adapter-independent change discovery.

type ChangedDeclaration 

type ChangedDeclaration struct {
	Kind            string     `json:"kind"`
	Package         string     `json:"package"`
	Name            string     `json:"name"`
	Change          ChangeKind `json:"change"`
	BaseLocation    *Location  `json:"base_location,omitempty"`
	CurrentLocation *Location  `json:"current_location,omitempty"`
}

ChangedDeclaration is one source declaration intersecting a changed range.

type ChangedFile 

type ChangedFile struct {
	Path                   string      `json:"path"`
	PreviousPath           string      `json:"previous_path,omitempty"`
	Change                 ChangeKind  `json:"change"`
	BaseRanges             []LineRange `json:"base_ranges"`
	BaseRangesTotal        int         `json:"base_ranges_total"`
	BaseRangesTruncated    bool        `json:"base_ranges_truncated"`
	CurrentRanges          []LineRange `json:"current_ranges"`
	CurrentRangesTotal     int         `json:"current_ranges_total"`
	CurrentRangesTruncated bool        `json:"current_ranges_truncated"`
}

ChangedFile is one path in the final change snapshot.

type Check 

type Check struct {
	ID               string    `json:"id"`
	Kind             CheckKind `json:"kind"`
	Required         bool      `json:"required"`
	Targets          []string  `json:"targets"`
	TargetsTotal     int       `json:"targets_total"`
	TargetsTruncated bool      `json:"targets_truncated"`
	Reason           string    `json:"reason"`
}

Check is one semantic operation in a verification plan.

type CheckKind 

type CheckKind string

CheckKind identifies a semantic verification check independently of an adapter or command name. 

const (
	CheckTests       CheckKind = "go.test"
	CheckCoverage    CheckKind = "go.coverage"
	CheckRace        CheckKind = "go.race"
	CheckConcurrency CheckKind = "go.analysis.concurrency"
	CheckErrors      CheckKind = "go.analysis.errors"
	CheckDiagnostics CheckKind = "go.diagnostics"
	CheckContract    CheckKind = "go.contract"
)

Check kinds identify the language-native evidence shipped in v0.2.

type Collection 

type Collection struct {
	Report   Report
	Policy   Policy
	Analysis ChangeAnalysis
}

Collection retains the unfinalized report and its private analysis handoff so the intelligence layer can attach snapshot-consistent semantic evidence before policy evaluation and detail truncation.

type ContractSummary 

type ContractSummary struct {
	ContractID          string              `json:"contract_id"`
	Violations          []ContractViolation `json:"violations"`
	ViolationsTotal     int                 `json:"violations_total"`
	ViolationsTruncated bool                `json:"violations_truncated"`
	Forbidden           int                 `json:"forbidden"`
	Warnings            int                 `json:"warnings"`
}

ContractSummary records optional Change Contract compliance evidence.

type ContractViolation 

type ContractViolation struct {
	Code               string     `json:"code"`
	Policy             string     `json:"policy"`
	Message            string     `json:"message"`
	Locations          []Location `json:"locations"`
	LocationsTotal     int        `json:"locations_total"`
	LocationsTruncated bool       `json:"locations_truncated"`
}

ContractViolation is one normalized machine-checkable contract deviation.

type CoverageSummary 

type CoverageSummary struct {
	TotalStatements    int           `json:"total_statements"`
	CoveredStatements  int           `json:"covered_statements"`
	Percent            float64       `json:"percent"`
	Uncovered          []SourceRange `json:"uncovered"`
	UncoveredTotal     int           `json:"uncovered_total"`
	UncoveredTruncated bool          `json:"uncovered_truncated"`
}

CoverageSummary contains statement-weighted coverage of changed code.

type Diagnostic 

type Diagnostic struct {
	Source   string   `json:"source"`
	Code     string   `json:"code,omitempty"`
	Severity string   `json:"severity"`
	Message  string   `json:"message"`
	Location Location `json:"location"`
}

Diagnostic records one normalized compiler or semantic-provider observation at a workspace-relative location.

type DiagnosticSummary 

type DiagnosticSummary struct {
	Items     []Diagnostic `json:"items"`
	Total     int          `json:"total"`
	Errors    int          `json:"errors"`
	Warnings  int          `json:"warnings"`
	Truncated bool         `json:"truncated"`
}

DiagnosticSummary contains bounded current-snapshot semantic evidence. Diagnostics are evidence only until a base comparison can classify them.

type Engine 

type Engine struct {
	// contains filtered or unexported fields
}

Engine assembles one portable report from injected change discovery and the shared contained execution infrastructure.

func NewEngine 

func NewEngine(ws *workspace.Workspace, runner *execution.Runner, analyzer ChangeAnalyzer, providerVersion string) (*Engine, error)

NewEngine constructs the deep verification module.

func (*Engine) Collect 

func (e *Engine) Collect(ctx context.Context, request Request) (Collection, error)

Collect runs the established change, execution, and analyzer evidence path without finalizing the portable report. Callers must finalize exactly once after attaching any additional neutral evidence.

func (*Engine) Verify 

func (e *Engine) Verify(ctx context.Context, request Request) (Report, error)

Verify discovers impact, executes the selected evidence once, and evaluates the report policy. Caller cancellation and the shared deadline remain request errors; ordinary check failures are represented in the report.

type Evidence 

type Evidence struct {
	CheckID     string             `json:"check_id"`
	Kind        CheckKind          `json:"kind"`
	Status      EvidenceStatus     `json:"status"`
	DurationMS  int64              `json:"duration_ms"`
	Summary     string             `json:"summary"`
	Error       string             `json:"error,omitempty"`
	Tests       *TestSummary       `json:"tests,omitempty"`
	Coverage    *CoverageSummary   `json:"coverage,omitempty"`
	Analysis    *AnalysisSummary   `json:"analysis,omitempty"`
	Race        *RaceSummary       `json:"race,omitempty"`
	Diagnostics *DiagnosticSummary `json:"diagnostics,omitempty"`
	Contract    *ContractSummary   `json:"contract,omitempty"`
}

Evidence records the outcome of one planned check.

type EvidenceStatus 

type EvidenceStatus string

EvidenceStatus records whether a planned check completed and what it found. 

const (
	EvidencePassed  EvidenceStatus = "passed"
	EvidenceFailed  EvidenceStatus = "failed"
	EvidenceSkipped EvidenceStatus = "skipped"
	EvidenceError   EvidenceStatus = "error"
)

Evidence states distinguish executed outcomes from unavailable checks.

type ExecutionTarget 

type ExecutionTarget struct {
	ID               string
	Dir              string
	ModulePath       string
	ModuleDir        string
	Reasons          []string
	Distance         int
	Cgo              bool
	BuildConstrained bool
}

ExecutionTarget is one language-native unit that can be verified. Absolute directories are internal infrastructure and never enter the report.

type FailOn 

type FailOn string

FailOn controls which introduced analyzer severities block policy. 

const (
	FailOnError   FailOn = "error"
	FailOnWarning FailOn = "warning"
	FailOnInfo    FailOn = "info"
	FailOnNone    FailOn = "none"
)

Fail-on thresholds control which introduced severities block policy.

type Finding 

type Finding struct {
	Kind       string        `json:"kind"`
	Rule       string        `json:"rule,omitempty"`
	Severity   Severity      `json:"severity"`
	Message    string        `json:"message"`
	Suggestion string        `json:"suggestion,omitempty"`
	Location   *Location     `json:"location,omitempty"`
	CheckID    string        `json:"check_id,omitempty"`
	Baseline   BaselineState `json:"baseline,omitempty"`
}

Finding is an observed issue produced by executed evidence.

type Impact 

type Impact struct {
	Packages          []ImpactedPackage `json:"packages"`
	PackagesTotal     int               `json:"packages_total"`
	PackagesTruncated bool              `json:"packages_truncated"`
}

Impact contains the conservative package closure for a change.

type ImpactedPackage 

type ImpactedPackage struct {
	Kind     string   `json:"kind"`
	ID       string   `json:"id"`
	Distance int      `json:"distance"`
	Reasons  []string `json:"reasons"`
}

ImpactedPackage is one directly changed or reverse-dependent Go package.

type LineEdit 

type LineEdit struct {
	BaseStart    int
	BaseCount    int
	CurrentStart int
	CurrentCount int
}

LineEdit retains the paired zero-context hunk coordinates required to map unchanged base locations into the final snapshot.

type LineRange 

type LineRange struct {
	Start int `json:"start"`
	End   int `json:"end"`
}

LineRange is an inclusive source-line range.

type Location 

type Location struct {
	File string `json:"file"`
	Line int    `json:"line"`
	Col  int    `json:"col,omitempty"`
}

Location is a workspace-relative source position.

type Policy 

type Policy struct {
	MinChangedCoverage *float64
	FailOn             FailOn
}

Policy controls report evaluation without changing collected evidence.

type PolicyResult 

type PolicyResult struct {
	Status           ResultStatus `json:"status"`
	ExitCode         int          `json:"exit_code"`
	BlockingFindings int          `json:"blocking_findings"`
	IncompleteChecks int          `json:"incomplete_checks"`
	Summary          string       `json:"summary"`
}

PolicyResult is the report's automation result, not a safety verdict.

type Provenance 

type Provenance struct {
	Context   []ProvenanceReference `json:"context"`
	Refactors []ProvenanceReference `json:"refactors"`
}

Provenance retains bounded context and refactor lineage without source contents, prompts, goals, or absolute paths.

type ProvenanceReference 

type ProvenanceReference struct {
	Kind             string `json:"kind"`
	Operation        string `json:"operation"`
	Reference        string `json:"reference,omitempty"`
	InputSnapshotID  string `json:"input_snapshot_id"`
	OutputSnapshotID string `json:"output_snapshot_id"`
	Applied          bool   `json:"applied,omitempty"`
}

ProvenanceReference records a source-grounded context or deterministic refactor operation that preceded verification in this service process.

type Provider 

type Provider struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

Provider identifies the implementation that produced a report.

type ProviderCapability 

type ProviderCapability struct {
	Name         string   `json:"name"`
	Version      string   `json:"version"`
	Capabilities []string `json:"capabilities"`
}

ProviderCapability records one effective implementation and its normalized portable capabilities.

type RaceSummary 

type RaceSummary struct {
	Conflicts int `json:"conflicts"`
}

RaceSummary contains bounded race-detector evidence.

type Report 

type Report struct {
	SchemaVersion     string               `json:"schema_version"`
	ID                string               `json:"id"`
	Provider          Provider             `json:"provider"`
	Providers         []ProviderCapability `json:"providers"`
	Repository        Repository           `json:"repository"`
	Snapshot          SnapshotLineage      `json:"snapshot"`
	Provenance        Provenance           `json:"provenance"`
	Change            Change               `json:"change"`
	Impact            Impact               `json:"impact"`
	Plan              []Check              `json:"plan"`
	Evidence          []Evidence           `json:"evidence"`
	Findings          []Finding            `json:"findings"`
	FindingsTotal     int                  `json:"findings_total"`
	FindingsTruncated bool                 `json:"findings_truncated"`
	Risks             []RiskArea           `json:"risks"`
	Uncertainties     []Uncertainty        `json:"uncertainties"`
	Result            PolicyResult         `json:"result"`
}

Report is the portable result shared by every delivery adapter.

func NewReport 

func NewReport(providerVersion string, repository Repository) Report

NewReport initializes the canonical schema and every collection.

func (*Report) Finalize 

func (r *Report) Finalize(policy Policy) error

Finalize normalizes ordering and applies policy to a complete report.

func (Report) ValidateID 

func (r Report) ValidateID() error

ValidateID verifies that a report carries the exact content address assigned by Finalize without mutating the caller's value.

func (Report) ValidateStoredID 

func (r Report) ValidateStoredID() error

ValidateStoredID accepts the current schema and the archived beta schema while still verifying the exact content address.

type Repository 

type Repository struct {
	RequestedBase   string `json:"requested_base"`
	BaseCommit      string `json:"base_commit"`
	MergeBaseCommit string `json:"merge_base_commit"`
	HeadCommit      string `json:"head_commit"`
	SnapshotID      string `json:"snapshot_id"`
	Workspace       string `json:"workspace"`
	Dirty           bool   `json:"dirty"`
}

Repository identifies the compared repository state without absolute paths.

type Request 

type Request struct {
	MinChangedCoverage *float64
	Base               string
	Package            string
	FailOn             FailOn
	ContractID         string
	ExpectedSnapshotID string
	MaxPackages        int
	Race               bool
}

Request configures one complete verification run independently of its CLI or MCP adapter.

type ResultStatus 

type ResultStatus string

ResultStatus is the automation state of a completed report. 

const (
	ResultPass       ResultStatus = "pass"
	ResultFindings   ResultStatus = "findings"
	ResultIncomplete ResultStatus = "incomplete"
)

Report result states distinguish complete evidence from findings and gaps.

type RiskArea 

type RiskArea struct {
	Code               string     `json:"code"`
	Reason             string     `json:"reason"`
	Guidance           string     `json:"guidance"`
	Locations          []Location `json:"locations"`
	LocationsTotal     int        `json:"locations_total"`
	LocationsTruncated bool       `json:"locations_truncated"`
}

RiskArea is a change-grounded reason for focused review or another check.

type Severity 

type Severity string

Severity is the portable importance of a finding. 

const (
	SeverityInfo    Severity = "info"
	SeverityWarning Severity = "warning"
	SeverityError   Severity = "error"
)

Finding severities are ordered from advisory information to blocking errors.

type SnapshotLineage 

type SnapshotLineage struct {
	CurrentID       string               `json:"current_id"`
	ExpectedID      string               `json:"expected_id,omitempty"`
	ContractInitial string               `json:"contract_initial,omitempty"`
	ContractLatest  string               `json:"contract_latest,omitempty"`
	Transitions     []SnapshotTransition `json:"transitions"`
}

SnapshotLineage binds verification evidence to the semantic snapshot and optional Change Contract lineage observed by the intelligence service.

type SnapshotTransition 

type SnapshotTransition struct {
	CheckpointID string `json:"checkpoint_id"`
	PreviousID   string `json:"previous_id"`
	CurrentID    string `json:"current_id"`
}

SnapshotTransition records one exact immutable checkpoint edge.

type SourceFile 

type SourceFile struct {
	BaseContent    []byte
	CurrentContent []byte
	Edits          []LineEdit
	Change         ChangedFile
}

SourceFile retains the content used to derive one changed-file record. It is an internal handoff from language-specific discovery to verification checks.

type SourceRange 

type SourceRange struct {
	File       string `json:"file"`
	StartLine  int    `json:"start_line"`
	StartCol   int    `json:"start_col,omitempty"`
	EndLine    int    `json:"end_line"`
	EndCol     int    `json:"end_col,omitempty"`
	Statements int    `json:"statements"`
}

SourceRange is a workspace-relative source range with a statement count.

type TestCaseSummary 

type TestCaseSummary struct {
	Package  string  `json:"package"`
	Name     string  `json:"name"`
	Status   string  `json:"status"`
	ElapsedS float64 `json:"elapsed_s"`
	Output   string  `json:"output,omitempty"`
}

TestCaseSummary is a retained failed or skipped test case.

type TestPackageSummary 

type TestPackageSummary struct {
	Package string `json:"package"`
	Status  string `json:"status"`
	Passed  int    `json:"passed"`
	Failed  int    `json:"failed"`
	Skipped int    `json:"skipped"`
	Output  string `json:"output,omitempty"`
}

TestPackageSummary aggregates terminal test outcomes for one package.

type TestSummary 

type TestSummary struct {
	Passed              int                  `json:"passed"`
	Failed              int                  `json:"failed"`
	Skipped             int                  `json:"skipped"`
	Packages            []TestPackageSummary `json:"packages"`
	PackagesTotal       int                  `json:"packages_total"`
	PackagesTruncated   bool                 `json:"packages_truncated"`
	Nonpassing          []TestCaseSummary    `json:"nonpassing"`
	NonpassingTotal     int                  `json:"nonpassing_total"`
	NonpassingTruncated bool                 `json:"nonpassing_truncated"`
}

TestSummary contains bounded test evidence without passing test records.

type Uncertainty 

type Uncertainty struct {
	Code               string     `json:"code"`
	Message            string     `json:"message"`
	CheckID            string     `json:"check_id,omitempty"`
	Locations          []Location `json:"locations"`
	LocationsTotal     int        `json:"locations_total"`
	LocationsTruncated bool       `json:"locations_truncated"`
}

Uncertainty is a known limit on a report's conclusion.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.