verify

type Check struct {
	// Kind is the check's plancontract kind (build or test).
	Kind plancontract.Kind `json:"kind"`
	// Items are the ids of the plan acceptance items this check covers
	// (empty for baseline checks and when the plan declares none).
	Items []string `json:"items,omitempty"`
	// Command is the trusted command that ran, or "" when the check was
	// skipped because no command was configured.
	Command string `json:"command,omitempty"`
	// Skipped marks a check that did not run: no trusted command was
	// available, or the run was cancelled. Skipped checks do not gate
	// the result (see Result.Passed) but are listed in it, so the
	// result always says what could not be verified.
	Skipped bool `json:"skipped,omitempty"`
	// Passed reports whether the check passed. For a skipped check it is
	// false.
	Passed bool `json:"passed,omitempty"`
	// Reason explains a skipped or abnormal check (timeout, executor
	// error, cancellation). It is empty for a clean pass or a normal
	// non-zero exit (the output excerpt carries the evidence there).
	Reason string `json:"reason,omitempty"`
	// Excerpt is a bounded excerpt of the check's combined output
	// (the evidence).
	Excerpt string `json:"excerpt,omitempty"`
	// Routes are the routes a page check attempted, in manifest order
	// (page checks only; empty for every other kind).
	Routes []string `json:"routes,omitempty"`
	// Screenshots are the per-route screenshot file paths, parallel to
	// Routes ("" where a capture failed or the route never reached a
	// browser capture; page checks only).
	Screenshots []string `json:"screenshots,omitempty"`
	// Steps are the scripted browser steps an interaction check ran, in
	// execution order (interaction checks only; empty for every other kind).
	// They come from the plan's interaction acceptance item.
	Steps []plancontract.BrowseStep `json:"steps,omitempty"`
	// Duration is the wall time the check took to execute.
	Duration time.Duration `json:"duration,omitempty"`
}

type Commands struct {
	// Build is the trusted build command, or "" when none is configured.
	Build string `json:"build,omitempty"`
	// Test is the trusted test command, or "" when none is configured.
	Test string `json:"test,omitempty"`
}

type ConfigCommandsProvider func(root string) (Commands, error)

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

type Executor interface {
	// Run executes command in dir (the project root) and returns its
	// outcome. A non-nil error marks a launch/setup failure; a non-zero
	// exit is an Outcome, not an error.
	Run(ctx context.Context, dir, command string) (Outcome, error)
}

type ManifestLoader func(root string) (*startermanifest.StarterManifest, error)

type Outcome struct {
	// Passed is true when the command exited 0.
	Passed bool
	// Output is the command's combined stdout and stderr.
	Output string
	// Reason is set when the command did not complete normally
	// (timeout, cancellation); empty for a clean run, pass or fail.
	Reason string
}

type PageBrowser interface {
	// Open opens url in a headless browser, optionally writing a
	// screenshot to screenshotPath ("" = no screenshot), and reports the
	// observation. A nil error means the route rendered; the caller
	// inspects the observation's ConsoleErrors/PageErrors for failures.
	// errors.Is(err, webcontent.ErrBrowserUnavailable) marks a browser that
	// cannot render here (skipped, not a failure).
	Open(ctx context.Context, url string, screenshotPath string) (*PageObservation, error)
}

type PageObservation struct {
	// URL is the route that was opened.
	URL string
	// Title is the page title after rendering ("" when unknown).
	Title string
	// ConsoleErrors are the console.error-level messages captured on the
	// page (the page's own console.error calls, not the level tag).
	ConsoleErrors []string
	// PageErrors are window errors and unhandled promise rejections.
	PageErrors []string
	// ScreenshotPath is the file the screenshot was saved to, or "" when the
	// capture did not complete (the route is still checked for console
	// errors).
	ScreenshotPath string
}

type PlanLoader func(root string) (*plancontract.Plan, error)

type QualityCheck struct {
	// Kind is the step (format or lint).
	Kind QualityKind `json:"kind"`
	// Command is the trusted command that ran, or "" when the step was
	// skipped because no command was configured.
	Command string `json:"command,omitempty"`
	// Skipped marks a step that did not run (no command configured, or the
	// run was cancelled before it started). A skipped step does not gate the
	// result but is listed in it.
	Skipped bool `json:"skipped,omitempty"`
	// Passed reports whether the step passed. For a skipped step it is false.
	Passed bool `json:"passed,omitempty"`
	// Reason explains a skipped or abnormal step (timeout, executor error,
	// cancellation). Empty for a clean pass or a normal non-zero exit (the
	// excerpt carries the evidence there).
	Reason string `json:"reason,omitempty"`
	// Excerpt is a bounded excerpt of the step's combined output.
	Excerpt string `json:"excerpt,omitempty"`
	// Changed reports whether the step rewrote files in the workspace.
	// Reported only for the formatter, whose in-place rewrite is the
	// runtime's own repair (the linter is informational).
	Changed bool `json:"changed,omitempty"`
	// Duration is the wall time the step took to execute.
	Duration time.Duration `json:"duration,omitempty"`
}

type QualityCommands struct {
	// Format is the trusted formatter command, or "" when none is configured.
	Format string `json:"format,omitempty"`
	// Lint is the trusted linter command, or "" when none is configured.
	Lint string `json:"lint,omitempty"`
}

type QualityConfigCommandsProvider func(root string) (QualityCommands, error)

type QualityKind string

type QualityResult struct {
	// Checks are the step outcomes, in run order (format then lint).
	Checks []QualityCheck `json:"checks"`
	// Errors are run-level findings (a corrupt manifest, a configuration
	// source failure) that prevented some commands from resolving. They are
	// reported, never swallowed.
	Errors []string `json:"errors,omitempty"`
}

type QualityRunner struct {
	// Manifest loads the project's starter manifest. Default:
	// starterstore.LoadStarterManifest (.sprout/starter.json).
	Manifest ManifestLoader
	// ConfigCommands resolves the project's explicit formatter/linter
	// commands. Nil means "no explicit configuration source".
	ConfigCommands QualityConfigCommandsProvider
	// Exec executes each resolved step command. Default: &ShellExecutor{}.
	Exec Executor
	// Timeout bounds a single step. Default: DefaultTimeout; a non-positive
	// value uses DefaultTimeout.
	Timeout time.Duration
	// MaxExcerptBytes bounds QualityCheck.Excerpt. Default:
	// DefaultMaxExcerptBytes.
	MaxExcerptBytes int
	// Fingerprint bounds the workspace change detection: it walks the root,
	// skipping a fixed set of heavy directories, and hashes each regular
	// file's content up to MaxFileBytes. Nil uses the default fingerprint
	// (defaultFingerprint). Injectable so a test can force a deterministic
	// before/after comparison.
	Fingerprint func(root string) (workspaceFingerprint, error)
}

type QualitySnapshot struct {
	// Commands are the resolved formatter and linter commands.
	Commands QualityCommands
	// Errors are the run-level findings the resolution produced (a corrupt
	// manifest, a configuration source failure).
	Errors []string
}

type RequireTestInput struct {
	// Enabled gates the check. Off is the default and a complete no-op: the
	// run's checks are unchanged when it is false.
	Enabled bool
	// PlanHasTestItem reports whether the active plan declares at least one
	// acceptance item of kind test. Such an item satisfies the requirement on
	// its own.
	PlanHasTestItem bool
	// ChangedApplicationPaths are the turn's changed paths that count as
	// application code (already filtered by the caller's documentation /
	// bookkeeping rule). An empty set means the turn changed no application
	// code — no new behavior — and the check is not applied.
	ChangedApplicationPaths []string
}

type Result struct {
	// Baseline is true when the run happened without an active
	// plan: the build and test commands ran as a baseline.
	Baseline bool `json:"baseline,omitempty"`
	// PlanRevision is the revision of the plan whose acceptance items
	// the checks cover (0 in baseline mode).
	PlanRevision int `json:"plan_revision,omitempty"`
	// Checks are the individual check outcomes, in run order.
	Checks []Check `json:"checks"`
	// Errors are run-level findings (an unreadable plan or manifest, a
	// configuration source failure) that prevented some commands from
	// resolving. They are reported, never swallowed.
	Errors []string `json:"errors,omitempty"`
}

type Runner struct {
	// Manifest loads the project's starter manifest. Default:
	// starterstore.LoadStarterManifest (.sprout/starter.json).
	Manifest ManifestLoader
	// Plans loads the active plan. Default: planstore
	// (.sprout/plan.json), not-found as planstore.ErrNoPlan.
	Plans PlanLoader
	// ConfigCommands resolves the project's explicit build/test commands.
	// Nil means "no explicit configuration source".
	ConfigCommands ConfigCommandsProvider
	// Exec executes each resolved check command. Default: &ShellExecutor{}.
	Exec Executor
	// Browser opens routes for page checks. Nil → page
	// checks are skipped with reason "no browser configured". Default:
	// NewWebcontentPageBrowser().
	Browser PageBrowser
	// StepBrowser runs the plan's scripted browser steps for interaction
	// checks. Nil → interaction checks are skipped with
	// reason "no browser configured". Default: NewWebcontentStepBrowser().
	StepBrowser StepBrowser
	// Timeout bounds a single check. Default: DefaultTimeout; a
	// non-positive value uses DefaultTimeout.
	Timeout time.Duration
	// DevServerTimeout bounds how long a page check waits for the manifest's
	// dev server to come up. Default: DefaultDevServerTimeout; a
	// non-positive value uses DefaultDevServerTimeout.
	DevServerTimeout time.Duration
	// ScreenshotDir is where page-check screenshots are written. "" →
	// <root>/.sprout/verify/screenshots (the .sprout/ directory is
	// gitignored project state).
	ScreenshotDir string
	// MaxExcerptBytes bounds Check.Excerpt (see boundedExcerpt).
	// Default: DefaultMaxExcerptBytes.
	MaxExcerptBytes int
	// RequireTest is the mechanical input to the require-a-test-for-new-
	// behavior check: when Enabled, a turn that added new behavior must
	// either carry an active-plan test acceptance item or add/change a test
	// file, and the run reports a failing check otherwise. The default (zero
	// value) is disabled — the run's checks are then unchanged.
	RequireTest RequireTestInput
}

type ShellExecutor struct {
	// Shell is the shell the command runs through (default "sh").
	Shell string
}

type Snapshot struct {
	// Manifest is the starter manifest captured at snapshot time, or nil
	// when the project has no usable one.
	Manifest *startermanifest.StarterManifest
	// ManifestError is the run-level finding a corrupt manifest produces
	// ("" when the manifest is present or absent).
	ManifestError string
	// Plan is the active plan captured at snapshot time, or nil when the
	// project has no usable plan (absent → baseline; corrupt → baseline
	// plus PlanError).
	Plan *plancontract.Plan
	// PlanError is the run-level finding a corrupt plan produces ("" when
	// the plan is present or absent).
	PlanError string
}

type StepBrowser interface {
	// RunSteps runs the steps in order against baseURL (the dev server root)
	// and reports the executed actions (evidence). A nil error means every
	// step, including assert-style expected-outcome steps, succeeded.
	// errors.Is(err, webcontent.ErrBrowserUnavailable) marks a browser that
	// cannot render here (skipped, not a failure).
	RunSteps(ctx context.Context, baseURL string, steps []plancontract.BrowseStep) (*StepObservation, error)
}

type StepObservation struct {
	// FinalURL is the page URL after the last step navigated ("" when
	// unknown).
	FinalURL string
	// Title is the page title after the last step ("" when unknown).
	Title string
	// Actions are the executed step descriptions in order — the evidence an
	// interaction check's excerpt carries (the confirmed outcome).
	Actions []string
}