feat: capacity estimate — mean cost and demand profile (spec 032)

[lukas-frystak-sonarsource]

What this implements

Amends the spec 031 capacity estimator per spec 032. The analyze bgtasks --estimate-workers flag remains the CLI surface; this PR changes the numbers it produces and replaces the ±20% band with an operationally meaningful demand profile.

Key changes

File	Change
internal/analyzer/bgtasks/estimate.go	Switch representative cost from mode → mean; remove rounding/margin constants; add DemandProfile struct and computeDemandProfile; add VerdictFor; remove JobsLow/High, TotalLow/High, MarginPct
internal/analyzer/bgtasks.go	Update logCapacityEstimate: add demand-profile logging (step 2b), always show all 8 size categories (empty ones as "no tasks"), add per-worker verdict line; extract logDemandProfile and logWorkerEstimate helpers to stay within complexity limits
internal/analyzer/bgtasks/estimate_test.go	Remove mode/tie-break/rounding tests; add: MeanCost, MeanIdentity, CostFloor, DemandProfile, InsufficientSpan, VerdictFor_Branches, AllEightCategories
specs/032-IMP-capacity-estimate-mean-and-demand.md	impl-status: in-progress

Notable decisions

• Mean not mode: the mean makes totalJobs(n) = reportCapacitySec(n) / avgReportCost an algebraic identity (holds exactly when no category hits the cost floor), eliminating the systematic throughput over-estimate from 031.
• p95 peak: single-hour outliers (bulk re-analyses) don't distort the headline peak; busiestHourCount is still logged at DEBUG.
• Demand profile on zero-filled hours: the average reflects real calendar time including quiet nights/weekends, not just active hours.
• Cognitive Complexity: logCapacityEstimate was refactored into logDemandProfile + logWorkerEstimate to satisfy the ≤15 limit flagged by Sonar.

Testing

• All existing tests pass; no golden-master files changed (report output is byte-for-byte identical when --estimate-workers is omitted).
• New unit tests cover: mean cost correctness, the mean-identity invariant, cost-floor clamping, demand profile p95 computation, insufficient-span guard, all three verdict branches, and always-8-categories output.
• Smoke test requires a live SonarQube instance (sonar-insights -v analyze bgtasks --estimate-workers 4,8,16) — not available in CI; output shape was verified via TestAnalyzeBgTasks_WithEstimateWorkers.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues
0 New dependency risks

Measures
0 Security Hotspots
94.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[gitar-bot]

💡 Edge Case: Demand profile vulnerable to zero/extreme SubmittedAt values

In computeDemandProfile (internal/analyzer/bgtasks/estimate.go:129-167), observedHours is derived from latestHour.Sub(earliestHour).Hours() and then used both to size counts := make([]int, 0, observedHours) and to iterate for h := earliestHour; !h.After(latestHour); h = h.Add(time.Hour).

This is safe for normal data, but if any REPORT task has a missing/zero SubmittedAt (Go zero time = year 1) — or a corrupt far-future timestamp — earliest becomes year 1 while latest is ~2026. The span (~2025 years) exceeds time.Duration's max (~292 years), so Sub(...) overflows and .Hours() yields a wrong (possibly negative) value. A negative observedHours makes make([]int, 0, negative) panic; a huge positive value triggers a multi-million-iteration loop. Either degrades or crashes the (otherwise best-effort, never-fatal) capacity estimate.

Unlike the rest of the estimator, there is no guard here. Consider skipping tasks with a zero SubmittedAt, or clamping observedHours to a sane bound, so malformed timestamps cannot overflow the duration math or drive a giant allocation/loop.

Skip tasks with a zero SubmittedAt so they cannot drag earliest to year 1 and overflow the duration span. (Adjust avgPerHour to use the counted total if zero-timestamp tasks are excluded.):

for i, t := range reportTasks {
	if t.SubmittedAt.IsZero() {
		continue // ignore tasks with no arrival timestamp
	}
	hour := t.SubmittedAt.UTC().Truncate(time.Hour)
	hourCounts[hour]++
	if earliest.IsZero() || t.SubmittedAt.Before(earliest) {
		earliest = t.SubmittedAt
	}
	if latest.IsZero() || t.SubmittedAt.After(latest) {
		latest = t.SubmittedAt
	}
}

• Apply fix

_{Check the box to apply the fix or reply for a change | Was this helpful? React with 👍 / 👎}

[gitar-bot]

Code Review 👍 Approved with suggestions 0 resolved / 1 findings

Implements the mean-based capacity estimate and demand profile per spec 032 with refactored logging helpers. Ensure computeDemandProfile is hardened against zero or extreme SubmittedAt values to prevent calculation errors.

💡 Edge Case: Demand profile vulnerable to zero/extreme SubmittedAt values

📄 internal/analyzer/bgtasks/estimate.go:129-143

In computeDemandProfile (internal/analyzer/bgtasks/estimate.go:129-167), observedHours is derived from latestHour.Sub(earliestHour).Hours() and then used both to size counts := make([]int, 0, observedHours) and to iterate for h := earliestHour; !h.After(latestHour); h = h.Add(time.Hour).

This is safe for normal data, but if any REPORT task has a missing/zero SubmittedAt (Go zero time = year 1) — or a corrupt far-future timestamp — earliest becomes year 1 while latest is ~2026. The span (~2025 years) exceeds time.Duration's max (~292 years), so Sub(...) overflows and .Hours() yields a wrong (possibly negative) value. A negative observedHours makes make([]int, 0, negative) panic; a huge positive value triggers a multi-million-iteration loop. Either degrades or crashes the (otherwise best-effort, never-fatal) capacity estimate.

Unlike the rest of the estimator, there is no guard here. Consider skipping tasks with a zero SubmittedAt, or clamping observedHours to a sane bound, so malformed timestamps cannot overflow the duration math or drive a giant allocation/loop.

Skip tasks with a zero SubmittedAt so they cannot drag `earliest` to year 1 and overflow the duration span. (Adjust avgPerHour to use the counted total if zero-timestamp tasks are excluded.)

for i, t := range reportTasks {
	if t.SubmittedAt.IsZero() {
		continue // ignore tasks with no arrival timestamp
	}
	hour := t.SubmittedAt.UTC().Truncate(time.Hour)
	hourCounts[hour]++
	if earliest.IsZero() || t.SubmittedAt.Before(earliest) {
		earliest = t.SubmittedAt
	}
	if latest.IsZero() || t.SubmittedAt.After(latest) {
		latest = t.SubmittedAt
	}
}

🤖 Prompt for agents

Code Review: Implements the mean-based capacity estimate and demand profile per spec 032 with refactored logging helpers. Ensure `computeDemandProfile` is hardened against zero or extreme `SubmittedAt` values to prevent calculation errors.

1. 💡 Edge Case: Demand profile vulnerable to zero/extreme SubmittedAt values
   Files: internal/analyzer/bgtasks/estimate.go:129-143

   In `computeDemandProfile` (internal/analyzer/bgtasks/estimate.go:129-167), `observedHours` is derived from `latestHour.Sub(earliestHour).Hours()` and then used both to size `counts := make([]int, 0, observedHours)` and to iterate `for h := earliestHour; !h.After(latestHour); h = h.Add(time.Hour)`.
   
   This is safe for normal data, but if any REPORT task has a missing/zero `SubmittedAt` (Go zero time = year 1) — or a corrupt far-future timestamp — `earliest` becomes year 1 while `latest` is ~2026. The span (~2025 years) exceeds `time.Duration`'s max (~292 years), so `Sub(...)` overflows and `.Hours()` yields a wrong (possibly negative) value. A negative `observedHours` makes `make([]int, 0, negative)` panic; a huge positive value triggers a multi-million-iteration loop. Either degrades or crashes the (otherwise best-effort, never-fatal) capacity estimate.
   
   Unlike the rest of the estimator, there is no guard here. Consider skipping tasks with a zero `SubmittedAt`, or clamping `observedHours` to a sane bound, so malformed timestamps cannot overflow the duration math or drive a giant allocation/loop.

   Fix (Skip tasks with a zero SubmittedAt so they cannot drag `earliest` to year 1 and overflow the duration span. (Adjust avgPerHour to use the counted total if zero-timestamp tasks are excluded.)):
   for i, t := range reportTasks {
   	if t.SubmittedAt.IsZero() {
   		continue // ignore tasks with no arrival timestamp
   	}
   	hour := t.SubmittedAt.UTC().Truncate(time.Hour)
   	hourCounts[hour]++
   	if earliest.IsZero() || t.SubmittedAt.Before(earliest) {
   		earliest = t.SubmittedAt
   	}
   	if latest.IsZero() || t.SubmittedAt.After(latest) {
   		latest = t.SubmittedAt
   	}
   }

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}