wire

package
v0.8.1 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2026 License: AGPL-3.0, AGPL-3.0-or-later Imports: 9 Imported by: 0

Documentation

Overview

Package wire reads and validates CEM 0.1/0.2 wire documents.

The reader is a strict JSON parser implementing interop/cem-0.1/ALGORITHMS.md "JSON and version dispatch": it rejects malformed UTF-8, duplicate object keys at any depth, non-integer or non-finite numbers, integers outside 0..9007199254740991, unpaired surrogates after JSON decoding, and inputs nested deeper than the documented operational depth bound.

Index

Constants

View Source 
const (
	Spec01          = "cem/0.1"
	Spec02          = "cem/0.2"
	Spec03          = "cem/0.3"
	ExcludedCEMPath = ".corvint/change.cem.json"

	MaxMapBytes    = 4 << 20
	MaxEvidence    = 4096
	MaxHunks       = 2048
	MaxBases       = 32
	MaxPathBytes   = 512
	EvidencePrefix = "evidence:sha256:"
	HunkPrefix     = "hunk:sha256:"
)

Frozen wire constants.

View Source 
const (
	CoverageCovered   = "covered"
	CoverageUncovered = "uncovered"
	MaxTestRunBytes   = 256
)

Frozen coverage witness vocabulary.

View Source 
const (
	DiscriminationDiscriminates = "discriminates"
	DiscriminationSurvived      = "survived"
	DiscriminationNotRun        = "not-run"
	MaxDiscriminationTextBytes  = 512
)

Frozen discrimination witness vocabulary.

View Source 
const MaxWireInteger = 9007199254740991

MaxWireInteger is the largest integer a CEM wire document may carry.

Variables

View Source 
var Relations = map[string]bool{
	"call-site": true, "decision": true, "dependency": true, "implementation": true,
	"incident": true, "specification": true, "test-claim": true,
}

Relations enumerates the frozen basis relations.

View Source 
var StructuralReasons = map[string]bool{
	"rename": true, "move": true, "import-reorder": true, "formatter-only": true,
}

StructuralReasons enumerates the cem/0.3 mechanical reasons proved by Go structural comparison (CEM-SM-001); 0.1 and 0.2 documents reject them.

Functions

func Canonical added in v0.7.0 

func Canonical(spec string) bool

Canonical reports whether spec is a canonical committed-change profile: cem/0.2, or cem/0.3 which adds the structural reason vocabulary and the optional hunk coverage witness.

func CanonicalString 

func CanonicalString(text string) string

CanonicalString encodes one JSON string with the frozen escape profile.

func CanonicalValue 

func CanonicalValue(value Value) []byte

CanonicalValue encodes one strict JSON value in the frozen canonical form: UTF-8, lexicographically sorted object keys, minimal separators, shortest signed decimal integers, no terminal LF. It is the single implementation of the `canonical-json-value` primitive every content address in the workspace hashes over, so a second approximation would silently fork identity.

func EvidenceIdentity 

func EvidenceIdentity(blobOid, path string, span Span, spanSha256 string) string

EvidenceIdentity derives the frozen evidence ID for one evidence record.

func HunkIdentity 

func HunkIdentity(contentSha256 string, oldPath, newPath *string, oldRange, newRange Range) string

HunkIdentity derives the frozen hunk ID. oldPath and newPath are nil for the created-from and deleted-to sides respectively.

func IsGitOid 

func IsGitOid(text string) bool

IsGitOid reports whether text is a full 40- or 64-hex lowercase Git OID.

func IsSha256 

func IsSha256(text string) bool

IsSha256 reports whether text is exactly 64 lowercase hex bytes.

func MechanicalReason added in v0.7.0 

func MechanicalReason(spec, reason string) bool

MechanicalReason reports whether reason is registered for spec.

func ValidatePath 

func ValidatePath(path string) error

ValidatePath enforces the frozen relative POSIX path grammar.

func ValidateTestRun added in v0.7.0 

func ValidateTestRun(text string) error

ValidateTestRun checks the verbatim test run identity a coverage witness records: non-empty, at most MaxTestRunBytes, and free of control characters.

func WriteCanonicalValue 

func WriteCanonicalValue(output *strings.Builder, value Value)

WriteCanonicalValue appends the canonical encoding of value to output.

Types

type Basis 

type Basis struct {
	EvidenceID string
	Relation   string
}

Basis is one typed evidence reference.

type CoverageWitness added in v0.7.0 

type CoverageWitness struct {
	ProfileSha256 string
	TestRun       string
	Mode          string
	State         string
	Covered       []Range
}

CoverageWitness is one hunk's optional cem/0.3 patch-coverage witness: the added lines one identified test run executed according to one local coverprofile (TCQ-V0-051). Covered ranges are one-based new-side line ranges inside the hunk's newRange, ascending and non-adjacent; an empty list is State CoverageUncovered, never an omitted witness.

type DiscriminationBounds added in v0.7.0 

type DiscriminationBounds struct {
	MaxHunks        int64
	MaxMutants      int64
	WallTimeSeconds int64
}

DiscriminationBounds are the caps one discriminate run declared.

type DiscriminationWitness added in v0.7.0 

type DiscriminationWitness struct {
	TreeRevision    string
	SelectionSha256 string
	Mutants         int64
	Killed          int64
	Survived        int64
	Survivors       []SurvivingMutant
	Bounds          DiscriminationBounds
	State           string
	Detail          string
}

DiscriminationWitness is one hunk's optional cem/0.3 mutation witness: whether the tests its test claims cite kill bounded mutants of the hunk's new-side lines on one tree revision (TCQ-V0-056). Survivors describe every mutant that lived; a hunk the run never judged carries State DiscriminationNotRun with zero counts and its Detail, never an omitted witness.

type Evidence 

type Evidence struct {
	ID         string
	BlobOid    string
	Path       string
	Span       Span
	SpanSha256 string
}

Evidence is one immutable evidence record.

type Hunk 

type Hunk struct {
	ID            string
	Path          string
	OldRange      Range
	NewRange      Range
	Disposition   string
	Reason        string
	Basis         []Basis
	Coverage      *CoverageWitness
	Discriminates *DiscriminationWitness
}

Hunk is one mapped patch hunk. Coverage and Discriminates are nil unless a cem/0.3 witness is recorded.

type Kind 

type Kind int

Kind enumerates strict JSON value kinds. 

const (
	KindNull Kind = iota
	KindBool
	KindInt
	KindString
	KindArray
	KindObject
)

type Map 

type Map struct {
	Spec         string
	BaseRevision string
	PatchSha256  string
	ExcludedPath string // empty for 0.1; the frozen literal for 0.2 and 0.3
	Evidence     []Evidence
	Hunks        []Hunk
}

Map is a validated CEM 0.1, 0.2, or 0.3 document.

func ParseMap 

func ParseMap(data []byte) (*Map, error)

ParseMap reads and validates one CEM wire document with the frozen stage-2 precedence: JSON errors, root object and spec, missing required fields, unknown fields, then field values in normative wire order.

type Object 

type Object struct {
	Keys   []string
	Values map[string]Value
}

Object preserves member order and rejects duplicate keys at insertion.

func (*Object) Get 

func (o *Object) Get(key string) (Value, bool)

Get returns the member value and whether it is present.

type Range 

type Range struct{ Start, Count int64 }

Range is a unified-diff line range.

type Span 

type Span struct{ Start, End int64 }

Span is a zero-based half-open raw-byte range.

type SurvivingMutant added in v0.7.0 

type SurvivingMutant struct {
	Operator    string
	Line        int64
	Description string
}

SurvivingMutant is one mutant the selected tests let live.

type Value 

type Value struct {
	Kind Kind
	Bool bool
	Int  int64
	Str  string
	Arr  []Value
	Obj  *Object
}

Value is one strict JSON value.

func Parse 

func Parse(data []byte) (Value, error)

Parse reads one strict JSON document occupying the entire input.

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.