conformance

type CLIDetail struct {
	Driver   string
	Version  string
	Argv     []string
	ExitCode int
	Signal   string
	Duration time.Duration
	Stdout   string
	Stderr   string
}

type CLIEnv interface {
	// HasCLI reports whether a CLI executor is available in this env.
	HasCLI() bool

	// CLI returns the executor for driver-using tests. Valid only
	// when HasCLI() is true; nil otherwise. See S04 §CLI drivers for
	// the CLIExecutor contract.
	CLI() CLIExecutor

	// CLIVersion returns the resolved driver version captured at
	// NewEnv time. Equal to the value CLI().Version() returns. Empty
	// when HasCLI() is false. See S04 §CLI drivers / Version pinning.
	CLIVersion() string
}

type CLIExecutor interface {
	// Name reports the driver identifier used in CLIDetail.Driver
	// and in skip / failure messages. Stable across invocations.
	Name() string

	// Version reports the resolved driver version. Resolved exactly
	// once during Module.NewEnv (see S04 §Version pinning) and
	// returned verbatim on every call thereafter. Empty only when
	// version resolution failed and HasCLI() returned false.
	Version() string

	// Run invokes the driver with the supplied argv. The runner
	// passes ctx for cancellation; the implementation MUST honor it
	// via exec.CommandContext per S04 §Invocation contract.
	//
	// Returns CLIResult on every outcome where the process started.
	// Returns a non-nil error only when the process could not be
	// spawned at all (binary not found, permission denied, fork
	// failure). Non-zero exit codes and signals are NOT returned as
	// errors — they are conveyed via CLIResult so the test function
	// can interpret them.
	Run(ctx context.Context, argv []string, opts RunOpts) (CLIResult, error)
}

type CLIResult struct {
	// Argv is the invocation argv with secret-flag values redacted: the
	// built-in --password/--auth/--token set plus any flags the executor
	// declared via WithSecretFlags. A caller building a CLIDetail must
	// populate CLIDetail.Argv from this, not from the raw argv passed to
	// Run, so a secret-bearing flag value never reaches the report
	// (S04 §Secret-bearing argv). Empty when the driver was unavailable
	// and no invocation was attempted.
	Argv []string
	// ExitCode is the process exit code; 0 on success; -1 if killed
	// by a signal.
	ExitCode int
	// Signal is empty unless the process was killed by a signal
	// (e.g. "killed", "terminated").
	Signal string
	// Duration is the wall-clock time the process ran.
	Duration time.Duration
	// Stdout is tail-truncated to 4 KiB with a "... [truncated]"
	// marker on truncation.
	Stdout string
	// Stderr is tail-truncated to 4 KiB with a "... [truncated]"
	// marker on truncation.
	Stderr string
}

type Config struct {
	// Format selects the per-format module: "maven" | "npm" | "oci".
	Format string
	// RegistryURL is the base URL of the registry under test.
	RegistryURL string
	// Credential is the user-supplied secret carried into protocol
	// requests. Zero value (empty Type, all halves empty) means
	// unauthenticated.
	Credential Credential
	// Filter is a path.Match glob pattern. Empty means no filtering;
	// otherwise only TestDescriptor.Name matching the glob runs.
	Filter string
	// Priorities is a non-empty allow-list of priorities to run. nil
	// or empty means no priority filtering. AND-composes with Filter.
	Priorities []Priority
	// RunID is the per-invocation identifier. Empty triggers
	// auto-generation inside Run / RunModule.
	RunID string
	// SettleTimeout is the per-write polling cap for async
	// registries. Zero disables polling.
	SettleTimeout time.Duration
	// HTTPClient is the HTTP client tests use. nil triggers the
	// library default client.
	HTTPClient *http.Client
	// Logger is the structured logger the library derives child
	// loggers from. nil triggers a JSON handler over io.Discard.
	Logger *slog.Logger
	// AllowRedirectHosts is the per-host glob allow-list consulted by
	// the library-default CheckRedirect before following a cross-host
	// redirect. nil or empty preserves strict cross-host rejection.
	AllowRedirectHosts []string
}

type ConfigError struct {
	Field  string
	Reason string
}

type Credential struct {
	Type     CredentialType
	Token    string
	Username string
	Password string
}

type CredentialType string

type Detail struct {
	// HTTP is populated when the failure is HTTP-shaped.
	HTTP *HTTPDetail
	// CLI is populated when the failure is driver-shaped.
	CLI *CLIDetail
}

type Env interface {
	// Close releases resources held by the env (temp dirs,
	// executors).
	Close() error
}

type FilterNoMatchError struct {
	Pattern string
}

type HTTPDetail struct {
	RequestMethod string
	RequestURL    string
	StatusCode    int
	// ResponseBody preserves the START of the response body up to 4
	// KiB; the END is truncated and a literal "... [truncated]" marker
	// is appended when truncation occurs. The start is preferred
	// because diagnostic content for HTTP errors (status code, error
	// message, structured envelope) typically lives at the beginning.
	// See S04 §570-578.
	ResponseBody string
}

type Module interface {
	// TestCatalog returns the full set of tests this module declares.
	// The runner owns filtering, prefixing, and skip dispatch.
	//
	// Implementations MUST be pure and idempotent per S04 §439-445:
	// TestCatalog may be called more than once per process (e.g. by
	// the `list` subcommand ahead of `run`, or by tests that
	// introspect the catalog). The returned slice and the descriptors
	// within it should be equivalent across calls for the same
	// Config. Do not perform network I/O, filesystem I/O, environment
	// reads, process execution, or shared state mutation inside
	// TestCatalog.
	TestCatalog(cfg Config) []TestDescriptor

	// NewEnv constructs the per-credential environment per S04
	// §448-450. Called once per credential. Returns an error if
	// environment setup fails (tool error).
	NewEnv(ctx context.Context, cfg Config, cred Credential) (Env, error)

	// NegativeAuthTests returns descriptors for auth-failure tests
	// that run outside the credential loop per S04 §452-462 — e.g.,
	// an unauthenticated probe expected to 401. The runner executes
	// each one through the same runOne wrapper as positive
	// descriptors (panic recovery, ctx cancellation, name-format
	// checks), and appends the resulting cases to
	// Report.Cases. A descriptor's Fn is responsible for issuing
	// requests without the env's authenticated client (e.g. by
	// constructing a fresh client or stripping the Authorization
	// header).
	NegativeAuthTests(cfg Config) []TestDescriptor
}

type Priority string

type PriorityNoMatchError struct {
	Priorities []Priority
}

type Report struct {
	RunID     string
	Format    string
	StartedAt time.Time
	Duration  time.Duration
	Cases     []TestCase
}

type RunOpts struct {
	// Dir is the absolute path of the working directory the driver runs
	// in — the per-test temp directory the S04 §Invocation contract
	// working-directory clause requires. The calling test creates it and
	// removes it in its own deferred cleanup. A relative path is resolved
	// against the runner's own working directory by os/exec, which defeats
	// the point, so pass an absolute one.
	//
	// Empty means the driver inherits the runner's working directory,
	// which the clause forbids. Every driver-invoking test should set it.
	// Dir alone does not confine a driver that resolves its own root by
	// walking up from the working directory; see the S04 §Invocation
	// contract working-directory bullet.
	Dir string
	// Stdin is fed to the driver's stdin. nil = /dev/null.
	Stdin io.Reader
	// ExtraEnv is appended to the env-var allow-list (see S04
	// §Invocation contract). Use for per-test secrets that must be
	// passed through (e.g. an npm auth token written to a tmp
	// .npmrc by the test). A value whose key matches a recognized
	// secret-name pattern (password, token, secret, api_key,
	// authorization; case-insensitive) is scrubbed from the captured
	// streams the executor records in CLIDetail; a value under any
	// other key is NOT scrubbed, so callers must not place a secret
	// under an unrecognized key.
	ExtraEnv []string
}

type Status string

type TestCase struct {
	// Name is the canonical test identifier. Set by the test author at
	// construction time (Pass(name), Fail(name, message), etc.); the
	// runner preserves it on output.
	Name string
	// Status is the outcome.
	Status Status
	// Message is the human-readable diagnostic. Empty for pass;
	// carries the skip reason for StatusSkip; carries the
	// panic/failure message for StatusFail.
	Message string
	// StartedAt is the wall-clock UTC start timestamp; populated by
	// runOne, not by test authors.
	StartedAt time.Time
	// Duration is the wall-clock duration the test ran. Zero means
	// not measured.
	Duration time.Duration
	// Detail is the optional failure context. Nil for pass and skip.
	Detail *Detail
}

type TestDescriptor struct {
	// Name is the canonical test identifier per S04 §510-512 and the
	// naming convention at S04 §1066-1079. Format:
	// <format>.<category>.<slug> — lowercase, dot-separated, no
	// spaces.
	Name string
	// Priority is the test's declared importance per S04 §513-517,
	// taken verbatim from the priority column of the test case
	// tables. The runner uses this for cfg.Priorities filtering;
	// rendering of priority counts in summaries is the output
	// layer's concern.
	Priority Priority
	// Fn executes the test per S04 §518-520. Must not panic; the
	// runner wraps each call in a recover. Must not write to stdout
	// or stderr.
	Fn func(ctx context.Context, env Env, runID string) TestCase
}