fingerprint

Documentation

Overview

Package fingerprint computes content digests for test suites.

Fingerprinting is batch-shaped because suite digests need the whole local package graph before any cache key can be trusted. First, package build digests are computed in topological order over build imports. Second, selected test suites become terminal digests over their test files, their package build digest, and discovered local test-only imports.

Only build imports are topological edges. External test packages may import a package that imports the tested package back, so test imports are deliberately excluded from the graph and added only while hashing suite sinks.

The package owns no goroutines or channels. Callers discover packages first, then pass the complete universe to Suites.

Index

• type BuildTrace
• type Explanation
  • func Explain(ctx context.Context, tool gotool.Tool, module gotool.Module, ...) (Explanation, error)
• type SaltRoot
• type SaltTrace
• type Suite
  • func Suites(ctx context.Context, tool gotool.Tool, module gotool.Module, ...) ([]Suite, error)
• type SuiteTrace

Types

type BuildTrace

type BuildTrace struct {
	// ImportPath is the traced package import path.
	ImportPath string

	// Digest is the package build digest.
	Digest string

	// Files are the hashed non-test build inputs relative to the package dir.
	Files []string

	// Imports are the package's direct build imports inside the closure.
	Imports []string
}

BuildTrace records one closure package's build-digest inputs.

type Explanation

type Explanation struct {
	// Salt describes the global inputs shared by every suite digest.
	Salt SaltTrace

	// Builds holds one build trace per package in the discovered closure.
	Builds map[string]BuildTrace

	// Suites holds selected packages with tests, sorted by import path.
	Suites []SuiteTrace
}

Explanation reports every content input behind the selected suite digests.

It exists so `rask why` can show users exactly which files and packages feed a cache key. All digests come from the same hashing code path as Suites, so a traced digest always equals the cache key a test run would compute.

func Explain

func Explain(
	ctx context.Context,
	tool gotool.Tool,
	module gotool.Module,
	packages []gotool.Package,
) (Explanation, error)

Explain traces the fingerprint inputs for every selected suite in packages.

Callers pass the same discovered universe they would pass to Suites; the returned digests are byte-identical to the cache keys of a test run over that universe.

type SaltRoot

type SaltRoot struct {
	// Dir is the canonical module root directory.
	Dir string

	// GoSum reports whether the root's go.sum existed and was hashed.
	GoSum bool
}

SaltRoot records one local module root's hashed metadata files.

type SaltTrace

type SaltTrace struct {
	// Digest is the shared salt over go env, go.work, and module files.
	Digest string

	// GoWork is the active workspace file path, or empty without one.
	GoWork string

	// Roots are the hashed local module roots in salt order.
	Roots []SaltRoot
}

SaltTrace lists the global metadata inputs folded into every digest.

type Suite

type Suite struct {
	// Package is the selected Go package to test.
	Package gotool.Package

	// Digest is the suite content digest used as the cache key.
	Digest string
}

Suite identifies one selected package test suite and its content digest.

func Suites

func Suites(
	ctx context.Context,
	tool gotool.Tool,
	module gotool.Module,
	packages []gotool.Package,
) ([]Suite, error)

Suites fingerprints the package universe into cache-keyed suites.

type SuiteTrace

type SuiteTrace struct {
	// ImportPath is the selected package import path.
	ImportPath string

	// Digest is the suite digest used as the cache key.
	Digest string

	// TestFiles are the hashed test inputs relative to the package dir.
	TestFiles []string

	// TestdataFiles are hashed fixture paths relative to the package dir.
	TestdataFiles []string

	// TestOnlyImports are in-closure test imports beyond the build imports.
	TestOnlyImports []string
}

SuiteTrace records one selected suite's terminal-digest inputs.