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.
	//
	// Forward-looking, not yet implemented: S08 §Seeding and
	// asynchronous upstreams gives the field a remote carve-out, under
	// which a resolved RepositoryKindRemote makes zero still perform
	// exactly one read-back rather than skipping it. Skipping it would
	// hand the proxy a coordinate the upstream may not serve yet, and
	// that hazard does not go away because the operator declared the
	// registry synchronous. The carve-out arrives with the shared
	// seed-and-settle helper (plan Step 5a); until then every reader
	// branches on "> 0" and the field carries only the meaning above.
	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
	// RepositoryKind is the kind of repository under test per S08
	// §Configuration. Empty resolves to RepositoryKindHosted.
	RepositoryKind RepositoryKind
	// OCINamePrefix is prepended to every OCI conformance repository
	// name, per S07 §Repository naming / Configurable name prefix.
	// Empty, the default, leaves the name at
	// conformance/{runID}/{slug-mapped}.
	//
	// It is OCI-only because OCI is the one format whose repository name
	// is not expressible through RegistryURL: the /v2/ literal is
	// inserted between the base URL and the name, so a prefix that has
	// to live inside the name cannot be carried on the base URL. Maven
	// and npm address their repository root through RegistryURL alone,
	// which is why neither needs an equivalent.
	//
	// A non-empty value under any Format other than "oci" is rejected by
	// Config.Validate with *ConfigError{Field: "oci-name-prefix"}: the
	// field is OCI-only, and a value that is accepted and discarded
	// teaches the operator it took effect. That rule needs only a Format
	// comparison, so this layer owns it.
	//
	// The value's OCI <name> grammar is checked elsewhere. It is protocol
	// knowledge the runner layer does not carry, so the OCI module's
	// NewEnv checks it with pkg/client/oci.ValidateName and returns the
	// same *ConfigError field before any request.
	//
	// Total length is unchecked. ValidateName enforces the per-segment
	// grammar but no overall cap, and the conformance-owned suffix runs
	// to roughly 120 characters at a 64-character RunID, so a prefix past
	// roughly 135 characters can push a generated name over a registry's
	// 255-character limit. The registry's NAME_INVALID then surfaces as a
	// conformance failure rather than as a configuration error.
	OCINamePrefix string
	// OCIUpstreamNamePrefix is prepended to every OCI conformance
	// repository name addressed through UpstreamURL, in place of
	// OCINamePrefix. Empty, the default, means the upstream is addressed
	// under OCINamePrefix like every other name.
	//
	// It exists for the one registry shape OCINamePrefix alone cannot
	// address: a remote repository and the upstream it proxies living on
	// one host, as two repositories distinguished only by name. OCI puts
	// /v2/ first in the path, so the base URL can only be the host, which
	// leaves RegistryURL and UpstreamURL identical and the name as the
	// only thing that can tell the two repositories apart. Maven and npm
	// carry the repository in the base URL, so neither has the shape.
	//
	// Setting it is also what admits an otherwise-rejected pair: a
	// non-empty value differing from OCINamePrefix lifts the
	// UpstreamURL-must-differ-from-RegistryURL rule, because the two
	// names then address two repositories. See
	// compareUpstreamAgainstRegistry in validate.go.
	//
	// A non-empty value is rejected by Config.Validate with
	// *ConfigError{Field: "oci-upstream-name-prefix"} under any Format
	// other than "oci" and under any resolved RepositoryKind other than
	// remote, for the reason OCINamePrefix states: a value accepted and
	// discarded teaches the operator it took effect. Both rules need only
	// field comparisons, so this layer owns them. Neither reaches a remote
	// run declaring UpstreamFreeOnly, which also has no upstream for a
	// second name to address; see validateOCIUpstreamNamePrefix for why
	// that case is left accepted.
	//
	// Its OCI <name> grammar and total length are unchecked here, exactly
	// as OCINamePrefix's are, and for the same reasons.
	OCIUpstreamNamePrefix string
	// UpstreamURL is the base URL of the writable repository the
	// repository under test proxies. Empty means no upstream is
	// available; only a remote kind may set it.
	UpstreamURL string
	// UpstreamFreeOnly declares that no writable upstream is
	// available, so a remote run's fixture-seeding rows skip. Only a
	// remote kind may set it.
	UpstreamFreeOnly bool
}

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. The bound is the producer's: FailWithHTTPDetail
	// and SkipWithDetail take whatever string they are handed. Callers
	// inside this package that source a body themselves apply
	// truncateDetailBody; the format clients apply their own copy at
	// read time, because they cap the body before it is ever buffered;
	// pkg/conformance/{maven,npm,oci} pass an already-capped
	// HTTPError.ResponseBody straight through.
	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
	// Interrupted is the reason the run did not complete, per S04
	// §Report struct. Nil on a completed run. Three values reach it,
	// all set by the runner: ctx.Err() on a cancellation path (S04
	// §Execution order inside RunModule, steps 7 and 8), the
	// TestCase.SetupFailure of a row that could not establish the
	// run's fixture source (step 8), and the wrapped
	// ErrNothingEstablished of a remote run that established nothing
	// (step 9, S08 AC #36). The last two are not cancellations, which
	// is why this is no longer "always ctx.Err()". The JUnit renderer
	// emits an <error> element with the reason so CI consumers can
	// distinguish a truncated run from a legitimately empty one.
	Interrupted error
}

type RepositoryKind string

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 SeedCallback func(context.Context) (SeedResult, error)

type SeedError struct {
	// RunAttributable is true for the run-attributable row of
	// §Preflight's cause table and for a transient failure that
	// survived its one re-attempt; false for the row-attributable
	// residue.
	RunAttributable bool
	// Result is the response the classification was drawn from: the
	// refused write's on the row-attributable and run-attributable
	// rows, and the second attempt's on a transient failure that
	// exhausted its re-attempt.
	Result SeedResult
	// contains filtered or unexported fields
}

type SeedResult struct {
	// Status is the terminal request's HTTP status. Zero means no
	// status arrived, exactly as HTTPError.StatusCode already
	// documents; the cause sort reads it for every failure and never
	// as a success signal.
	Status int
	// Stored is the write callback's "means stored" verdict: the
	// format's own status rule on the terminal request. The shared
	// helper holds no 2xx range check and no 202 case of its own, so a
	// terminal 202 a callback reports not-stored is reissued
	// (S08 §Preflight).
	Stored bool
	// DuplicateRefusal is the write callback's second verdict: this
	// status is this format's refusal of an already-published
	// coordinate. The set is 409 for Maven, 409 or 403 for npm, and
	// empty for OCI, whose push is idempotent, so the helper must
	// never classify a duplicate from a status literal.
	DuplicateRefusal bool
	// Preexisting reports that the write's per-artifact existence
	// check found an artifact already at the coordinate rather than
	// writing it. It is what keeps AC #37's comparison reachable: with
	// the existence check in place a landed first write draws no 409
	// on the re-attempt, so a 409-keyed content check would never run.
	Preexisting bool
	// Method is the terminal request's verb. The sort compares it
	// against SeedSpec.WriteVerb, because a followed 301, 302 or 303
	// is replayed as a GET with the body dropped (S04 §HTTP client
	// policy) and its 200 would otherwise satisfy npm's and Maven's
	// status rule for a coordinate this run never wrote. An empty
	// Method reads as a method switch: no format is exempt from
	// filling it.
	Method string
	// URL is the terminal request's URL, lifted into HTTPDetail by
	// NewSeedFailureCase.
	URL string
	// Body is the served bytes on a read-back's success path, and the
	// error body otherwise. SeedAndSettle scrubs it with
	// redact.RedactURLUserinfo(redact.ScanContent(...)) and then bounds
	// it at detailBodyCap before it reaches a SeedError, because the
	// surfaces the detail lands on are not failure_detail fields and
	// nothing downstream re-truncates (S08 AC #24, §Preflight; S04
	// AC #33). Neither bound applies to the Body returned on the
	// success path, which is the served fixture the caller compares.
	Body []byte
}

type SeedSpec struct {
	// Write issues every artifact this row seeds, in one call, against
	// the upstream. It reports the completion request per artifact,
	// surfaces the first artifact its format's verdict calls
	// not-stored, and must be idempotent per artifact and
	// content-deterministic: it checks existence before writing and
	// reports through SeedResult.Preexisting whether any artifact was
	// found rather than written.
	Write SeedCallback
	// ReadBack polls the upstream, not the repository under test, and
	// returns the served bytes on success. Establishing readability on
	// the upstream before the row reads through the proxy is the whole
	// point of the poll (S08 §Seeding and asynchronous upstreams).
	ReadBack SeedCallback
	// Fixture is this run's expected bytes, a pure function of (run ID,
	// slug) per S08 §Fixture seeding model. AC #37 compares a resumed
	// settle's read-back against it.
	Fixture []byte
	// WriteVerb is the format's write method, which the cause sort
	// compares SeedResult.Method against. No callback verdict can
	// supply it, and a verb is not a status, so it keeps the
	// no-format-status-literal rule intact.
	WriteVerb string
	// SettleTimeout is the resolved cfg.SettleTimeout, passed
	// explicitly because it is not derivable from ctx, whose deadline
	// is the root 2n x d + 5m rather than the per-settle cap. Zero
	// means exactly one read-back and no polling loop, which is
	// AC #14's carve-out; the read-back is never skipped.
	SettleTimeout time.Duration
}

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; set by the
	// runner, not by test authors (S04 AC #54).
	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 for
	// every skip but the seeding-refusal one, which carries the
	// refused write's own response for library consumers (S04
	// §TestDescriptor, TestCase, Status, Detail; S08 AC #15).
	// SkipWithDetail is the only constructor that populates it on a
	// non-failing case.
	Detail *Detail
	// SetupFailure is non-nil when the row could not establish the
	// run's fixture source, as opposed to failing an assertion about
	// the registry under test (S04 §TestDescriptor, TestCase, Status,
	// Detail). The runner reads it after runOne and stops the loop,
	// carrying it into Report.Interrupted and the returned error, so
	// S04 §Exit codes maps it to 2 rather than 1.
	//
	// It is a field and not a Status value because the enum is
	// switched exhaustively by renderers and by external consumers; a
	// new value would break them, an ignored field does not. Being
	// additive, it never replaces Status: a row that sets it still
	// reports a canonical Status, StatusSkip for a seeding failure,
	// because every Status consumer panics on a non-canonical value.
	//
	// Nothing populates this field yet. The only sanctioned producer is
	// the shared seed-and-settle helper landing as pkg/conformance/seed.go
	// (plan Step 5a), which MUST scrub the detail before it populates
	// this field, with redact.RedactURLUserinfo(redact.ScanContent(...)):
	// the surfaces it reaches are not failure_detail fields and so are
	// outside S04 AC #74's render-boundary scan, and ScanContent alone
	// would miss a body echoing scheme://user:pass@host. Naming the
	// helper and not "whoever populates it" is what makes the rule hold,
	// since this is a plain error on an exported struct.
	//
	// Until that helper lands, an Fn that sets this field must scrub it
	// itself, because no layer downstream will. The three surfaces the
	// value reaches all apply strictly less than the failure_detail path:
	// internal/report's stdout "Interrupted:" line and JUnit <error
	// message> apply RedactURLUserinfo alone (redactMessage), and the
	// exit-2 stderr write applies stripControl and no redaction at all
	// (S08 §Preflight). The keyword scan belongs to the producer, not to
	// those boundaries, because it corrupts curated prose.
	SetupFailure error
	// contains filtered or unexported fields
}

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
	// NeedsUpstream declares that the test cannot run without a
	// fixture upstream, per S04 §TestDescriptor, TestCase, Status,
	// Detail. False for every hosted row, so a descriptor literal
	// that omits it keeps its current meaning.
	//
	// The runner reads it to skip the row when the Env carries no
	// upstream (S08 §Upstream gate), and for AC #36's post-loop verdict,
	// which asks it three questions: whether the selection holds a
	// seeding row, whether the pre-narrowing catalog holds one, and
	// whether any selected seeding row got the run's fixture onto the
	// upstream. That verdict is the field's largest consequence, since it
	// turns a remote run that established nothing into exit 2. The third
	// question is about the seeding and not about the Status: a row that
	// seeds and then skips on a pluggable arm established its fixture and
	// must say so through SkipAfterSeeding, and a row that skips before
	// it writes anything must use Skip.
	//
	// A further read lives outside this package: internal/cli counts the
	// rows a run will settle against to size the derived --timeout (S08
	// §Seeding and asynchronous upstreams), off SelectDescriptors rather
	// than off the catalog; S08 §S04 amendments attributes it to
	// internal/cli. Declaring the field here rather than deciding it
	// inside Fn is what makes every one of them readable without
	// executing anything.
	NeedsUpstream bool
	// 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
}

type UpstreamEnv interface {
	// HasUpstream reports whether a writable fixture upstream is
	// available in this env.
	HasUpstream() bool
}