benchfixtures

Documentation

Overview

Package benchfixtures provides immutable, content-addressed benchmark inputs.

The fixtures are snapshots rather than reads from the working tree so benchmark results do not silently change when the source files used to select them move.

Index

• Constants
• func Issue454CSource() []byte
• func Issue454PHPSource() []byte
• func VerifyGoFullParseSuiteNodeKindCoverage(coverage NodeKindCoverage) error
• func VerifyGoGrammarIdentity(commit, blobSHA256 string) error
• type DeepNode
• type DeepTreeDigest
  • func NewDeepTreeDigest() *DeepTreeDigest
  • func (d *DeepTreeDigest) Add(node DeepNode) error
  • func (d *DeepTreeDigest) Hex() (string, error)
  • func (d *DeepTreeDigest) Inspection() (DeepTreeInspection, error)
• type DeepTreeInspection
  • func InspectGoTree(root *gotreesitter.Node, lang *gotreesitter.Language) (DeepTreeInspection, error)
• type Fixture
  • func GoFullParseFixtures() []Fixture
  • func (f Fixture) Load() ([]byte, error)
  • func (f Fixture) VerifyDeepTreeDigest(digest string) error
  • func (f Fixture) VerifyNodeKindCoverage(coverage NodeKindCoverage) error
  • func (f Fixture) VerifyRuntimeIdentity(runtime gotreesitter.ParseRuntime) error
  • func (f Fixture) VerifySource(source []byte) error
  • func (f Fixture) VerifyWorkloadIdentity(runtime gotreesitter.ParseRuntime, coverage NodeKindCoverage) error
• type LoadedFixture
  • func LoadGoFullParseFixtures() ([]LoadedFixture, error)
• type NodeKindCoverage
  • func (c NodeKindCoverage) Merge(other NodeKindCoverage)
• type WorkloadIdentity

Constants

const (
	// GoFixtureOriginRevision is the gotreesitter revision from which the human
	// source snapshots were selected.
	GoFixtureOriginRevision = "a5df0aa5b3c5b20ce12bb21250bd166b9f47bd68"
	// GoGrammarCommit is the tree-sitter-go revision pinned by languages.lock.
	GoGrammarCommit = "2346a3ab1bb3857b48b29d779a1ef9799a248cd7"
	// GoGrammarBlobSHA256 identifies the exact gotreesitter Go grammar blob.
	// Regenerated 2026-09-20 with cmd/grammargen (no -lr-split; see
	// grammargen/README.md and docs/grammar-ownership.md).
	GoGrammarBlobSHA256 = "df63fc35604c4e4e7a484abde9eb2110b61640045601c23991723f323a48310d"
)

const DeepTreeDigestVersion = "gts-deep-tree-v1"

DeepTreeDigestVersion names the byte-stable structural digest contract.

const Issue454CFixtureBytes = 137 * 1024

Issue454CFixtureBytes is the exact size of the downstream C edit workload reported in issue #454 (a repeated-function fixture grown to ~137 KiB, matching the generator shape the field report used for c_sharp and php).

const Issue454PHPFixtureBytes = 137 * 1024

Issue454PHPFixtureBytes is the exact size of the downstream PHP edit workload reported in issue #454.

Functions

func Issue454CSource

func Issue454CSource() []byte

Issue454CSource builds the deterministic issue #454 C workload. The first local variable contains the edit site for the x0 to 0 deletion (a transient-error edit: the declarator "x0" loses its leading letter and becomes the bare integer literal "0").

func Issue454PHPSource

func Issue454PHPSource() []byte

Issue454PHPSource builds the deterministic issue #454 PHP workload. The first local variable contains the edit site for the $x0 to $0 deletion.

func VerifyGoFullParseSuiteNodeKindCoverage

func VerifyGoFullParseSuiteNodeKindCoverage(coverage NodeKindCoverage) error

VerifyGoFullParseSuiteNodeKindCoverage validates syntax features that only need to be represented once across the complete canonical fixture matrix.

func VerifyGoGrammarIdentity

func VerifyGoGrammarIdentity(commit, blobSHA256 string) error

VerifyGoGrammarIdentity fails closed unless both Go parser implementations are tied to the same pinned grammar revision and exact gotreesitter blob. The C parity harness calls this before it performs deep tree parity and starts either timer.

Types

type DeepNode

type DeepNode struct {
	Type        string
	Field       string
	StartByte   uint32
	EndByte     uint32
	StartRow    uint32
	StartColumn uint32
	EndRow      uint32
	EndColumn   uint32
	Named       bool
	Extra       bool
	Missing     bool
	Error       bool
	HasError    bool
	ChildCount  uint32
}

DeepNode is one node in a preorder, child-order-preserving tree stream. Field is the field name on the edge from the parent; it is empty for the root.

type DeepTreeDigest

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

DeepTreeDigest incrementally computes SHA-256 over an authenticated preorder node stream. NewDeepTreeDigest writes the ASCII version string followed by a NUL byte. Add then writes, for every node:

• uint32 little-endian type byte length, then UTF-8 type bytes
• uint32 little-endian field byte length, then UTF-8 field bytes
• start byte, end byte, start row, start column, end row, end column as six uint32 little-endian values
• one flag byte: named=bit 0, extra=bit 1, missing=bit 2, is-error=bit 3, has-error=bit 4
• uint32 little-endian child count

Type plus the named flag is the cross-runtime visible symbol identity. Numeric grammar symbol IDs are intentionally absent: the generated Go blob and pinned C grammar assign different IDs to some identical visible symbols. Nodes must be added in preorder with children in parser order. Child counts make the stream self-delimiting and are validated before Hex succeeds.

func NewDeepTreeDigest

func NewDeepTreeDigest() *DeepTreeDigest

NewDeepTreeDigest starts an empty v1 digest.

func (*DeepTreeDigest) Add

func (d *DeepTreeDigest) Add(node DeepNode) error

Add appends one preorder node and validates the tree framing seen so far.

func (*DeepTreeDigest) Hex

func (d *DeepTreeDigest) Hex() (string, error)

Hex returns the lowercase SHA-256 digest for one complete rooted tree.

func (*DeepTreeDigest) Inspection

func (d *DeepTreeDigest) Inspection() (DeepTreeInspection, error)

Inspection returns the completed digest and a defensive copy of its node kind census.

type DeepTreeInspection

type DeepTreeInspection struct {
	SHA256    string
	NodeKinds NodeKindCoverage
}

DeepTreeInspection pairs the authenticated tree digest with the node kinds observed while computing it.

func InspectGoTree

func InspectGoTree(root *gotreesitter.Node, lang *gotreesitter.Language) (DeepTreeInspection, error)

InspectGoTree computes the shared digest and node-kind coverage in one untimed admission traversal. The static C oracle implements the same DeepTreeDigestVersion stream.

type Fixture

type Fixture struct {
	ID                string
	Origin            string
	OriginRevision    string
	UncompressedBytes int
	SHA256            string
	CompressedSHA256  string
	DeepTreeSHA256    string
	WorkloadIdentity  WorkloadIdentity
	// contains filtered or unexported fields
}

Fixture describes one frozen human-authored Go full-parse input.

func GoFullParseFixtures

func GoFullParseFixtures() []Fixture

GoFullParseFixtures returns the frozen fixture metadata in stable order.

func (Fixture) Load

func (f Fixture) Load() ([]byte, error)

Load decompresses and authenticates a frozen fixture. Both the compressed asset and uncompressed source must match their recorded identities.

func (Fixture) VerifyDeepTreeDigest

func (f Fixture) VerifyDeepTreeDigest(digest string) error

VerifyDeepTreeDigest fails closed unless a parser produced the frozen deep structural identity for this fixture.

func (Fixture) VerifyNodeKindCoverage

func (f Fixture) VerifyNodeKindCoverage(coverage NodeKindCoverage) error

VerifyNodeKindCoverage fails closed when a fixture loses the real-code syntax features that distinguish it from the historical generated control.

func (Fixture) VerifyRuntimeIdentity

func (f Fixture) VerifyRuntimeIdentity(runtime gotreesitter.ParseRuntime) error

VerifyRuntimeIdentity fails closed when the parser no longer enters the GLR regime that qualified this fixture for headline use.

func (Fixture) VerifySource

func (f Fixture) VerifySource(source []byte) error

VerifySource fails closed unless source is the exact frozen input.

func (Fixture) VerifyWorkloadIdentity

func (f Fixture) VerifyWorkloadIdentity(runtime gotreesitter.ParseRuntime, coverage NodeKindCoverage) error

VerifyWorkloadIdentity validates both the parser regime and untimed syntax coverage for one fixture.

type LoadedFixture

type LoadedFixture struct {
	Fixture Fixture
	Source  []byte
}

LoadedFixture pairs verified metadata with source bytes decompressed outside the timed benchmark region.

func LoadGoFullParseFixtures

func LoadGoFullParseFixtures() ([]LoadedFixture, error)

LoadGoFullParseFixtures loads and authenticates every frozen fixture.

type NodeKindCoverage

type NodeKindCoverage map[string]uint64

NodeKindCoverage records visible tree node kinds observed during an untimed deep-tree admission walk.

func (NodeKindCoverage) Merge

func (c NodeKindCoverage) Merge(other NodeKindCoverage)

Merge adds another coverage census into c.

type WorkloadIdentity

type WorkloadIdentity struct {
	MinMaxStacksSeen        int
	MinMultiStackIterations int
	MinMultiStackTokens     uint64
}

WorkloadIdentity defines the minimum GLR regime a fixture must retain to qualify for the canonical full-parse matrix.