Documentation
¶
Overview ¶
Package session implements the experimental Go live-test provider's foreground session: a bounded-file poll loop that debounces edits, computes a current-input identity, and runs the frozen `go test -json` invocation (via gorunner.Run, the same contained runner provider.Execute uses) once per settled edit. It never replaces provider.Execute's authority-gated canonical receipt path and is preview-only, matching docs/specs/go-live-test-provider-v0.md's own preview/experimental separation: no state this package emits is policy evidence.
Index ¶
Constants ¶
const MaxTestProjections = 128
MaxTestProjections bounds Event.Tests so one published event line stays well inside a consumer's per-record byte bound.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run executes the session loop until ctx is cancelled (SIGINT/SIGTERM/stdin close in the caller) or an unrecoverable Config error is found. On return, no run this session started is still executing: shutdown cancels the active run's context and waits for gorunner.Run's bounded cleanup so no descendant survives the call.
Types ¶
type Config ¶
type Config struct {
// Files is the bounded set of absolute, existing regular-file paths this
// session watches by polling mtime+size, then digesting on a candidate
// change. It must include go.mod and go.sum when the module has them:
// the identity is a digest over exactly this set plus ToolchainVersion.
Files []string
// TestFiles is the subset of Files (by exact path) that are Go test
// files. It bounds the affected-scope narrowing in AffectedScope: a
// change touching only TestFiles can be narrowed to their packages,
// because editing a test cannot change another package's behavior; any
// other changed file falls back to Scope.
TestFiles map[string]bool
// Scope is the configured full/fallback package pattern list, e.g.
// []string{"./..."}. It is used for the session's baseline run and for
// every run whose affected selection cannot be justified.
Scope []string
// ModulePath is the module's declared import path (the go.mod `module`
// line). It is required to express a narrowed affected-package pattern
// as a plain import path, since gorunner's Packages validator admits
// dot-relative patterns only in the exact form "./...". An empty
// ModulePath forces every affected-scope decision to fall back to Scope.
ModulePath string
ToolchainVersion string
GoExecutable string
WorkingDirectory string
Environment []gorunner.EnvironmentVariable
Interval time.Duration
Debounce time.Duration
Timeout time.Duration
OutputLimitBytes int64
Publish func(Event)
}
Config is fully explicit; Run performs no ambient defaulting beyond what is documented per field.
type Event ¶
type Event struct {
State State
Identity string
Sequence uint64
Scope []string
Detail string
// Projection restates this event's own classification in the one shared
// internal/testvalidity shape the JavaScript provider already emits, so
// a consumer reads both languages through one representation. It is
// derived from this event alone and adds no fact Detail does not already
// carry.
Projection testvalidity.Projection
// Tests carries one per-test projection for each test the run's retained
// `go test -json` stdout reported, failures first then first-seen order,
// capped at MaxTestProjections (GLTP-V0-051). It is empty for every
// state whose run did not complete as Passed or Failed.
Tests []TestProjection
// TestsOmitted counts reported tests dropped by the MaxTestProjections
// cap; their per-test state is unknown to a consumer.
TestsOmitted int
}
Event is one state transition. Identity names the current-input identity the transition belongs to; a Passed/Failed/Infrastructure event whose Identity no longer equals the session's current identity at completion is reported as Stale instead, regardless of arrival order.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session runs the foreground poll/debounce/execute loop described in the package doc. It holds no state outside one Run call.
type TestProjection ¶
type TestProjection struct {
Package string `json:"package"`
Name string `json:"name"`
Action string `json:"action"`
Projection testvalidity.Projection `json:"projection"`
}
TestProjection is one test's shared testvalidity projection, keyed by the `go test -json` Package and Test fields. Action is the last terminal action observed for it (pass, fail, skip) or "none" when it never reached one; it restates the observation, while Projection is the contract.
Source Files