run

type InflightJob struct {
	Repo      string
	Connector string
}

type InterruptSummaryInput struct {
	Phase    string        // "clone", "extract", "postprocess"
	Inflight []InflightJob // populated only for the "extract" phase
	TempDir  string        // absolute path; "" if no temp dir was created
	Cleaned  bool          // true when the temp dir was removed (false with --keep-clones)
	ExitCode int           // 130 for graceful SIGINT
}

type Options struct {
	Out         string
	Workers     int
	KeepClones  bool
	Connectors  []connector.Connector
	Logger      *slog.Logger
	ToolVersion string
	// Progress is the sink for run-time phase events. Nil resolves to a
	// no-op; the CLI selects a TTY grid / line log / NDJSON / no-op sink
	// based on the --output mode resolved in cmd/xray/output.go.
	Progress progress.Sink
	// OnTempDir, if non-nil, is invoked exactly once with the absolute
	// path of the per-run temp directory immediately after creation. The
	// CLI uses it so the signal handler can name the leaked path in the
	// double-Ctrl-C force-exit log line.
	OnTempDir func(string)
}

type PartialFailure struct {
	Repo      string
	Connector string
	Reason    string
}

type Result struct {
	ArtifactPath string
	SHA256       string
	Size         int64
	Duration     time.Duration
	Manifest     manifest.Manifest

	// RateLimitWaits and RateLimitWaitSeconds are the cumulative wait
	// count and total wait time across every connector's ratelimit
	// transport, drained from the progress.RateLimitCounter that the CLI
	// tees alongside the user-facing sink. Populated by the cmd layer
	// after Run returns (Run itself does not aggregate the counter).
	RateLimitWaits       int
	RateLimitWaitSeconds int

	// Interrupted is true iff Run returned because ctx was canceled.
	Interrupted      bool
	InterruptedPhase string        // "clone", "extract", "postprocess"
	InflightJobs     []InflightJob // populated only during "extract" cancel
	TempDir          string        // absolute path; non-empty whenever cleanup ran (or was skipped via KeepClones)
}

type RunSummary struct {
	Kind       string            `json:"kind"`
	OK         bool              `json:"ok"`
	DurationS  int               `json:"duration_s"`
	Artifact   SummaryArtifact   `json:"artifact"`
	Rows       map[string]any    `json:"rows"`
	Provenance SummaryProvenance `json:"provenance"`
	Partial    []PartialFailure  `json:"partial"`
}

type SummaryArtifact struct {
	Path          string `json:"path"`
	SizeBytes     int64  `json:"size_bytes"`
	SHA256        string `json:"sha256"`
	SchemaVersion int    `json:"schema_version"`
	LogPath       string `json:"log_path,omitempty"`
}

type SummaryInput struct {
	Manifest             manifest.Manifest
	ArtifactPath         string
	SHA256               string
	Size                 int64
	Duration             time.Duration
	LogPath              string
	PartialFails         []PartialFailure
	RateLimitWaits       int
	RateLimitWaitSeconds int
}

type SummaryProvenance struct {
	EndpointsAccessible   int `json:"endpoints_accessible"`
	EndpointsTotal        int `json:"endpoints_total"`
	EndpointsInaccessible int `json:"endpoints_inaccessible"`
	PerRowErrors          int `json:"per_row_errors"`
	RateLimitTruncated    int `json:"rate_limit_truncated"`
	RateLimitWaits        int `json:"rate_limit_waits"`
	RateLimitWaitSeconds  int `json:"rate_limit_wait_seconds"`
	PartialPaginations    int `json:"partial_paginations"`
}