validation

Documentation

Overview

Package validation evaluates closed structural predicates against a trusted persisted Gograph snapshot. It is transport-neutral and never rebuilds a graph.

Index

• Constants
• type Analysis
• type Binding
  • func ParseBinding(data []byte) (Binding, string, error)
• type Diagnostic
• type Evaluation
• type Evaluator
  • func NewEvaluator(version string) *Evaluator
  • func NewEvaluatorWithLoader(version string, loader SnapshotLoader) *Evaluator
  • func (e *Evaluator) Validate(ctx context.Context, request Request) Result
• type Evidence
• type Location
• type MatchedRelation
• type Outcome
• type Precision
• type Predicate
• type Reason
• type Reference
• type ReferenceKind
• type Repository
• type RepositoryLoader
  • func (loader RepositoryLoader) Load(ctx context.Context, repositoryRoot string) (Snapshot, error)
  • func (loader RepositoryLoader) VerifyCurrent(ctx context.Context, snapshot Snapshot) error
• type Request
• type RequestRecord
• type ResolvedReference
• type Result
  • func InvalidRequestResult(version, root, message string) Result
• type Snapshot
• type SnapshotError
  • func (e *SnapshotError) Error() string
• type SnapshotLoader
• type VersionDocument

Constants

const (
	BindingSchemaVersion = "gograph.binding.v1"
	ResultSchemaVersion  = "gograph.validation.v1"
	VersionSchemaVersion = "gograph.version.v1"
)

Types

type Analysis

type Analysis struct {
	GraphSchemaVersion      string     `json:"graph_schema_version,omitempty"`
	SourcePolicyVersion     int        `json:"source_policy_version,omitempty"`
	GraphFingerprint        string     `json:"graph_fingerprint,omitempty"`
	BuildContextFingerprint string     `json:"build_context_fingerprint,omitempty"`
	Mode                    string     `json:"mode,omitempty"`
	Precision               Precision  `json:"precision,omitempty"`
	Completeness            string     `json:"completeness,omitempty"`
	Freshness               string     `json:"freshness,omitempty"`
	GraphGeneratedAt        *time.Time `json:"graph_generated_at,omitempty"`
}

type Binding

type Binding struct {
	SchemaVersion     string     `json:"schema_version"`
	Predicate         Predicate  `json:"predicate"`
	Subject           Reference  `json:"subject"`
	Object            *Reference `json:"object,omitempty"`
	RequiredPrecision Precision  `json:"required_precision"`
}

func ParseBinding

func ParseBinding(data []byte) (Binding, string, error)

type Diagnostic

type Diagnostic struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Path    string `json:"path,omitempty"`
}

type Evaluation

type Evaluation struct {
	Outcome     Outcome      `json:"outcome"`
	Reason      Reason       `json:"reason"`
	Diagnostics []Diagnostic `json:"diagnostics"`
}

type Evaluator

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

func NewEvaluator

func NewEvaluator(version string) *Evaluator

func NewEvaluatorWithLoader

func NewEvaluatorWithLoader(version string, loader SnapshotLoader) *Evaluator

func (*Evaluator) Validate

func (e *Evaluator) Validate(ctx context.Context, request Request) Result

type Evidence

type Evidence struct {
	ResolvedSubject  *ResolvedReference `json:"resolved_subject,omitempty"`
	ResolvedObject   *ResolvedReference `json:"resolved_object,omitempty"`
	MatchedRelations []MatchedRelation  `json:"matched_relations"`
}

type Location

type Location struct {
	Path   string `json:"path"`
	Line   int    `json:"line,omitempty"`
	Column int    `json:"column,omitempty"`
}

type MatchedRelation

type MatchedRelation struct {
	Kind           string     `json:"kind"`
	SubjectID      string     `json:"subject_id"`
	ObjectID       string     `json:"object_id"`
	Classification string     `json:"classification,omitempty"`
	Locations      []Location `json:"locations"`
}

type Outcome

type Outcome string

const (
	OutcomePass           Outcome = "pass"
	OutcomeFail           Outcome = "fail"
	OutcomeCannotEvaluate Outcome = "cannot_evaluate"
)

type Precision

type Precision string

const (
	PrecisionAST     Precision = "ast"
	PrecisionPrecise Precision = "precise"
)

type Predicate

type Predicate string

const (
	PredicateSymbolExists   Predicate = "symbol_exists"
	PredicatePackageImports Predicate = "package_imports"
	PredicateCallEdgeExists Predicate = "call_edge_exists"
	PredicateTypeImplements Predicate = "type_implements"
)

type Reason

type Reason string

const (
	ReasonPredicatePassed         Reason = "predicate_passed"
	ReasonPredicateFailed         Reason = "predicate_failed"
	ReasonSymbolNotFound          Reason = "symbol_not_found"
	ReasonSymbolAmbiguous         Reason = "symbol_ambiguous"
	ReasonPackageNotFound         Reason = "package_not_found"
	ReasonRelationNotFound        Reason = "relation_not_found"
	ReasonGraphMissing            Reason = "graph_missing"
	ReasonGraphInvalid            Reason = "graph_invalid"
	ReasonGraphSchemaUnsupported  Reason = "graph_schema_unsupported"
	ReasonSourcePolicyUnsupported Reason = "source_policy_unsupported"
	ReasonGraphStale              Reason = "graph_stale"
	ReasonPrecisionInsufficient   Reason = "precision_insufficient"
	ReasonAnalysisIncomplete      Reason = "analysis_incomplete"
	ReasonSymbolIdentityUnstable  Reason = "symbol_identity_unstable"
	ReasonUnsupportedPredicate    Reason = "unsupported_predicate"
	ReasonUnsupportedLanguage     Reason = "unsupported_language"
	ReasonRepositoryMismatch      Reason = "repository_mismatch"
	ReasonInvalidRequest          Reason = "invalid_request"
	ReasonInternalError           Reason = "internal_error"
)

type Reference

type Reference struct {
	Language string        `json:"language"`
	Kind     ReferenceKind `json:"kind"`
	ID       string        `json:"id"`
}

type ReferenceKind

type ReferenceKind string

const (
	ReferenceSymbol  ReferenceKind = "symbol"
	ReferencePackage ReferenceKind = "package"
)

type Repository

type Repository struct {
	Root              string `json:"root"`
	SourceFingerprint string `json:"source_fingerprint,omitempty"`
	GitRevision       string `json:"git_revision,omitempty"`
}

type RepositoryLoader

type RepositoryLoader struct {
	BuildTags []string
	// AllowCheckoutSourceAuthority permits go.work members outside a nested
	// module root when ToolchainSourceRoots has confined them beneath the
	// nearest real Git checkout. Machine validation leaves this false so its
	// explicit --repo path remains the complete toolchain authority.
	AllowCheckoutSourceAuthority bool
}

func (RepositoryLoader) Load

func (loader RepositoryLoader) Load(ctx context.Context, repositoryRoot string) (Snapshot, error)

func (RepositoryLoader) VerifyCurrent

func (loader RepositoryLoader) VerifyCurrent(ctx context.Context, snapshot Snapshot) error

type Request

type Request struct {
	RepositoryRoot            string
	BindingJSON               []byte
	ExpectedSourceFingerprint string
}

type RequestRecord

type RequestRecord struct {
	BindingFingerprint string   `json:"binding_fingerprint,omitempty"`
	Binding            *Binding `json:"binding,omitempty"`
}

type ResolvedReference

type ResolvedReference struct {
	Kind       ReferenceKind `json:"kind"`
	ID         string        `json:"id"`
	SymbolKind string        `json:"symbol_kind,omitempty"`
	Locations  []Location    `json:"locations"`
}

type Result

type Result struct {
	SchemaVersion  string        `json:"schema_version"`
	Command        string        `json:"command"`
	GographVersion string        `json:"gograph_version"`
	GeneratedAt    time.Time     `json:"generated_at"`
	Repository     Repository    `json:"repository"`
	Analysis       Analysis      `json:"analysis"`
	Request        RequestRecord `json:"request"`
	Evaluation     Evaluation    `json:"evaluation"`
	Evidence       Evidence      `json:"evidence"`
}

func InvalidRequestResult

func InvalidRequestResult(version, root, message string) Result

type Snapshot

type Snapshot struct {
	Root                 string
	Graph                *graph.Graph
	GraphFingerprint     string
	SourceFingerprint    string
	SelectionFingerprint string
	Freshness            string
}

type SnapshotError

type SnapshotError struct {
	Reason     Reason
	Diagnostic Diagnostic
}

func (*SnapshotError) Error

func (e *SnapshotError) Error() string

type SnapshotLoader

type SnapshotLoader interface {
	Load(context.Context, string) (Snapshot, error)
	VerifyCurrent(context.Context, Snapshot) error
}

type VersionDocument

type VersionDocument struct {
	SchemaVersion string `json:"schema_version"`
	Version       string `json:"version"`
}