Documentation
¶
Overview ¶
Package preflight builds a cost-preview Plan for an xray run without performing the run. It is consumed by `xray check` to surface the expected wall-clock, disk, and API budget before the customer commits to an extraction.
All probing is read-only: GraphQL count aggregates and metadata fields (diskUsage, pullRequests.totalCount) that mutate nothing.
Index ¶
Constants ¶
const ( // APICallsPerRepoBase is the cheap-overhead per repo: branch list, // branch_protection, languages, releases, codeowners, harness probe, // file_metrics summary. Roughly one paged call per endpoint. APICallsPerRepoBase = 40 // APICallsPerPR is the average GraphQL+enrich load per PR: list page // share, reviews + comments + review_threads pagination, defects // enrich, merge-method fetch. Empirical median across the seed // engagements ~ 2. APICallsPerPR = 2 // APICallsPerCommit is the per-commit enrich cost (batched, so this // is fractional in practice). APICallsPerCommit = 1 // CloneBytesPerKBDiskUsage converts GitHub's diskUsage (KB) to a // clone-size estimate in bytes. diskUsage is the on-disk size of the // bare repository on GitHub's storage, which is typically a tight // upper bound for the bare clone xray performs (`git clone --bare`). CloneBytesPerKBDiskUsage = 1024 // SecondsPerAPICall is the connector-side wall-clock budget per API // call, averaged across the GraphQL primary-rate ceiling, retry // jitter, and parallelism. Calibrated against the v0.1 baseline // (~3.5k calls / 7 min wall-clock on 5 workers). SecondsPerAPICall = 0.04 // SecondsPerGBClone covers the clone phase: network bandwidth + // local disk write. Assumes a 200 Mbit/s effective downstream. SecondsPerGBClone = 40 // SecondsPerGBFileWalk covers the local filesystem walk performed by // extractWorkingTree after cloning. The walk itself makes zero GitHub // API calls but is significant wall-clock for large repos. Calibrated // from a 13-repo 7-day run: ~780s of walk time for ~1 GiB total disk. // 600 s/GiB is slightly below the empirical ~780 to leave headroom // while still capturing the dominant cost that the old formula missed. SecondsPerGBFileWalk = 600 // SecondsPerGBComplexityHistory covers the extractComplexityHistoryBatch // phase: git cat-file decompression of (commit × file) blob pairs. // Calibrated from the issue-#149 profile: 11.4s on 478 MiB clone (75k // pairs) → ~3s after 4× parallelisation ≈ 6 s/GiB. Scaled ×10 for // production hardware (SecondsPerGBFileWalk calibration implies 5-10× // slower per-GiB on non-NVMe). Set above empirical to preserve the // cost-preview's over-estimate posture. SecondsPerGBComplexityHistory = 60 // MinimumWallClockSeconds is the floor — a "trivial" plan (one tiny // repo, one connector) still has fixed overhead. MinimumWallClockSeconds = 30 )
Calibration constants for the cost preview. These are deliberate over-estimates so the preview never under-promises wall-clock to a nervous customer. Refined empirically as the connectors stabilise.
Variables ¶
This section is empty.
Functions ¶
func FormatBytes ¶
FormatBytes renders a byte count using 1024-based units with the matching binary unit labels (KiB / MiB / GiB) so the cost-preview's number and the post-run summary's artifact-size both compute and label the same way. Customers see one consistent format across both commands instead of "500 MB" in check and "476.8 MiB" in summary.
Types ¶
type InaccessibleEndpoint ¶
InaccessibleEndpoint records a permission-gated endpoint discovered to be inaccessible during preflight. Surfaced upfront so the customer can fix scope before starting the full run.
type Plan ¶
type Plan struct {
Repos int
Teams int
WindowStart time.Time
WindowEnd time.Time
WindowDays int
Connectors []string
CloneBytes int64
APICalls int
WallClockSecs int
}
Plan is the cost-preview output for a configured run.
type RepoStat ¶
type RepoStat struct {
Slug string
DiskUsageKB int64 // GraphQL repository.diskUsage; 0 if unavailable.
PullRequests int // estimated PRs updated in window (all-time count scaled by window/repo-age ratio; unscaled if window not set).
Commits int // estimated commits in window; 0 if unknown.
}
RepoStat is a per-repo cheap-aggregate snapshot used to feed the cost estimate. The connector-specific probe implementation populates these fields via read-only GraphQL aggregates.