Repository navigation
✨ governor: merge-hotspot advisor files modularize issues for the ci-maintainer - #15429
Conversation
…maintainer Detect files repeatedly touched by concurrent PRs from data the hive already has (merge-train file lists, rebase-conflict records), score them, apply a don't-splinter guard (size + distinct symbol groups), and file one deduped modularize issue per hotspot through the writeback gate for the ci-maintainer lane. Expose GET /api/hotspots, a hotspots block in /api/status, hivectl governor hotspots, a governor tile, docs and a Merge Hotspots section in the ci-maintainer prompts. Signed-off-by: Andrew Anderson <andy@clubanderson.com>
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
Open PR overlap checkBase branch: Conflicts are checked with every PR merged onto the current tip of
|
|
@clubanderson is auto-promoted for contributor-lane merging on this PR: the last 5 merged PRs by this author in this hive's repositories have no revert or sentinel-alert evidence. CI, reviewer verdict, diff fences, soak, holds and branch protection still apply. |
|
@clubanderson this PR is held at Failing checks:
Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path. |
|
stage 080-awaiting-merge-admission → 071-needs-author: optional-check-failing:test (dashboard shuffle 1/3) |
…n tile Signed-off-by: Andrew Anderson <andy@clubanderson.com>
|
stage 080-awaiting-merge-admission → 050-review-pending: required-check-pending:build-and-test |
There was a problem hiding this comment.
Reviewed (docs-currency) — advisory only, no blocker.
Docs match the code: operator-reference.md thresholds/size weights//data/hotspots.json/two-hour unseen window are backed by src/pkg/hotspot/hotspot.go (DefaultDocMinLines = 1500, size weight at 800/1500/4000), src/cmd/hive/hotspot_advisor.go (hotspotStatePath, hotspotUnseenAfter = 2 * time.Hour, Origin: config.OriginSourceGovernor), and the /api/status.hotspots row is backed by src/pkg/dashboard/server.go:3676 + statusWithWebhooks.Hotspots. dashboard-misc.md citation pkg/dashboard/api.go:531 resolves to the GET /api/hotspots registration at head.
- Advisory (in-scope, low): the new merge hotspots tile (
src/pkg/dashboard/static-src/js/governor-view.js:270-277) is not mentioned insrc/docs/dashboard-sections.md§ Governor (line 89 ff.), which enumerates the governor tiles for operators. That list already omits MTTR and Planning, so this is not a regression, but since #15428 item 5 names the tile explicitly, one bullet would keep the operator doc current:
- The **hold** list names every held item. Held means someone parked it with a hold label.
- The **merge hotspots** tile counts files that concurrent PRs keep colliding on (`/api/status.hotspots.count`); the label gains `· N filed` once modularize issues exist. It is hidden when the advisor is not wired. Details are on `GET /api/hotspots` — see [operator-reference.md § Merge-hotspot advisor](operator-reference.md#merge-hotspot-advisor-governorhotspot_).
(insert after the **hold** bullet in § Governor.)
— hive: agent=ci-maintainer backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
Correctness review (head 52fbde0)
1. Unreadable /data/hotspots.json silently disables persistence for the whole process and defeats issue dedupe — src/cmd/hive/hotspot_advisor.go:47-48
On any read/parse error hotspotStore() falls back to hotspot.NewStore(""), i.e. an in-memory store whose dirtySave is a no-op (src/pkg/hotspot/store.go:368-371). From then on nothing is persisted, and on every subsequent restart the same corrupt file reproduces the fallback. Because dedupe is purely local state (Filer.File only consults f.Store.Issue, src/pkg/hotspot/issue.go:238; the <!-- hive:hotspot file=… --> marker is written but never searched for), a lost/corrupt state file means a second refactor: … is a merge hotspot issue is filed for every actionable file on the next hourly pass, contrary to "One open issue per file" in the PR body and operator-reference.md. A single truncated write (pod killed between WriteFile and Rename is handled, but a bad JSON from any other cause is not) is enough to trigger this.
st, err := hotspot.NewStore(hotspotStatePath)
if err != nil {
bad := hotspotStatePath + ".corrupt"
slog.Warn("hotspot: state unreadable; moving it aside and starting empty", "path", hotspotStatePath, "moved_to", bad, "error", err)
_ = os.Rename(hotspotStatePath, bad)
if st, err = hotspot.NewStore(hotspotStatePath); err != nil {
st, _ = hotspot.NewStore("")
}
}
Optionally also have IssueCreator/Filer search open issues for Marker(file) before creating, so the marker actually dedupes as the body says.
2. GET /api/hotspots returns "hotspots": null once the advisor is wired but has no results — src/pkg/dashboard/api_hotspots.go:68
hotspotDashSource.HotspotsJSON returns d.store.Results(repo) (hotspot_advisor.go:69), which is a nil []Hotspot when nothing is cached or the repo is unknown (store.go:330). Wrapped in any that is a non-nil interface, so hs != nil is true and the nil slice marshals as null, not the [] the unwired branch and the API doc imply. api_hotspots_test.go only exercises a fake returning []any{}, so it cannot catch it. Fix in the adapter (keeps the dashboard free of pkg/hotspot):
func (d hotspotDashSource) HotspotsJSON(repo string) any {
hs := d.store.Results(repo)
if hs == nil {
return []hotspot.Hotspot{}
}
return hs
}
3. (advisory) The don't-splinter guard is weaker than #15428 / the PR body state. The issue and PR body say a split is recommended only when "the overlapping PRs touched ≥ 2 distinct top-level symbol groups"; recommend() checks len(h.SymbolGroups) which is the file's current top-level declarations (src/pkg/hotspot/hotspot.go:262-266, Groups(file, info.Source)), not what the PRs changed — the code comment at hotspot.go:181-184 admits hunk data is not retained. Practically every ≥800-line Go file has ≥2 top-level decls, so the guard reduces to the size bar. operator-reference.md describes it correctly; the PR body should be reworded to match, or the guard should use per-PR patch hunks.
— hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
Security review — no blocking findings. One low-severity hardening note.
Checkout reader follows symlinks out of the checkout (src/cmd/hive/hotspot_advisor.go:133-137). filepath.Clean("/" + path) correctly neutralises .., but os.ReadFile(filepath.Join(root, clean)) still follows a symlink committed in the repo (e.g. docs/x.md -> /etc/…). The path comes from merge-train PR file lists (automerge_merge_train.go, RecordPRFiles) and the resulting line count and ## heading / def / class names from the target (pkg/hotspot/kinds.go:69-85 Groups) end up in a public issue body (pkg/hotspot/issue.go Body, "Top-level units"). Exploitation needs a merged symlink plus ≥6 PRs / ≥3 overlaps on that path, so the risk is low, but the repo already uses os.OpenRoot (src/pkg/github/review_request_sandbox_spool.go) for exactly this:
if root := cfg.Project.CheckoutRootFor(repo); root != "" {
if r, err := os.OpenRoot(root); err == nil {
if data, err := r.ReadFile(path); err == nil {
src = data
}
_ = r.Close()
}
}
(os.Root.ReadFile rejects .. and any symlink that escapes root, so the manual filepath.Clean is no longer needed.) The GitHub-contents fallback is unaffected: GetContents returns the symlink target string, not the file it points at.
Checked and fine: GET /api/hotspots is read-only and registered on the same authenticated mux as its siblings (api.go:531); issue filing goes through WritebackAllowed(..., KindIssueFile, ...) with fixed labels (hotspot_advisor.go:87-104); state file holds only repo/PR numbers/paths (store.go:387-392); no new tokens, secrets, or workflow changes.
— hive: agent=adjudicator-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
Reviewed (intent-alignment, head 52fbde0) — the diff covers every item of #15428 (detect / score / classify / file / expose + lane prompt) with no scope creep; the api-reference/*.md churn is only server.go: citation shifts. Two advisory gaps between the stated contract and the code, neither blocking:
-
Dedupe is store-only; the marker is never consulted. #15428 §4 and the PR body say issues are "deduped with
<!-- hive:hotspot file=… -->", butFiler.File(src/pkg/hotspot/issue.go:255-278) looks upf.Store.Issue(repo, file)only;Markeris written into the body (issue.go:42) and otherwise read only by a test.hotspotStore()falls back to an empty store when/data/hotspots.jsonis unreadable (src/cmd/hive/hotspot_advisor.go:52-56), so after a lost/corrupt PVC file a second openrefactor: <path> …issue is filed while the first is still open. Same PVC-index pattern as upstream-watch, so acceptable as-is — but either make the marker load-bearing or soften the wording. Minimal code route: an optional finder the Filer consults when the store has no record:--- a/src/pkg/hotspot/issue.go +++ b/src/pkg/hotspot/issue.go @@ type IssueStater interface { +// MarkerFinder (optional) finds an open issue whose body carries Marker(file); +// consulted when the Store has no record so a lost state file cannot double-file. +type MarkerFinder interface { + FindOpenHotspotIssue(ctx context.Context, repo, marker string) (number int, url string, found bool, err error) +} @@ func (f *Filer) File( - if rec, ok := f.Store.Issue(repo, h.File); ok { + rec, ok := f.Store.Issue(repo, h.File) + if !ok && f.Finder != nil { + if n, u, found, err := f.Finder.FindOpenHotspotIssue(ctx, repo, Marker(h.File)); err == nil && found { + rec = IssueRecord{Repo: repo, File: h.File, Number: n, URL: u, FiledAt: now()} + f.Store.RecordIssue(rec) + ok = true + } + } + if ok {
Related:
hotspotGitHub.HotspotIssueStatealways returns a zeroclosedAt(hotspot_advisor.go:106-115;github.IssueSummaryhas no closed time,src/pkg/github/client.go:4073-4078), soFilersubstitutesnow()(issue.go:263-265). Thehotspot_refile_dayswait therefore starts when the advisor notices the close (only while the file is actionable), not at the close itself — conservative, but the docs say "after it closes". -
Evidence coverage is narrower than the issue's "merged + open PRs per repo".
RecordPRFilesfires only insideplanMergeTrainsfor PRs that pass the automerge lane prefilter and share a base with ≥1 other candidate (src/pkg/github/automerge/automerge_merge_train.go:349-370at head), and only whileauto_merge.merge_train.enabledis true (:347). PRs the lane never considers (held, draft, non-eligible, solo on their base) are invisible toprs/overlaps. That is the issue's own "no new polling" constraint and fine — but the operator-reference section (src/docs/operator-reference.md§ Merge-hotspot advisor) should say the advisor requires the merge train and counts only train candidates, and the PR-body dry run (full GraphQL export, 118 PRs → 17 hotspots) will overstate production hit rates for the same reason. One-line doc suggestion:- **Where to look.** `GET /api/hotspots` (or `hivectl governor hotspots [--repo owner/name]`) lists every hotspot with its recommendation and issue; `/api/status` carries `hotspots: {count, actionable, filed}`. State lives in `/data/hotspots.json`; the analysis runs at most hourly in the eval cycle, the intake on every merge-train sweep. A PR the train has not seen for two hours has its interval closed at its last sighting. The advisor depends on `auto_merge.merge_train.enabled` (default on) and only counts PRs the merge train admitted as candidates — PRs the automerge lane never considers do not contribute to `prs` or `overlaps`.
— hive: agent=adjudicator-3 backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
Reviewed (style/maintainability) — no blocker; four advisory items, worst first. Read at head 52fbde0.
-
IssueStaterpromisesclosedAt; the adapter never delivers it.src/cmd/hive/hotspot_advisor.go:110returnstime.Time{}for every closed issue becausegithub.IssueSummary(src/pkg/github/client.go:4073-4078) has no closed timestamp, soFiler.File(src/pkg/hotspot/issue.go, theif closedAt.IsZero() { closedAt = now() }branch) always stamps "closed = when the advisor next noticed", and it only looks while the file is actionable again. Contract-safe (never refiles sooner thanhotspot_refile_days) but a file that re-heats months after its issue closed waits another 30 d. Honour the interface instead of leaving it decorative:func (g hotspotGitHub) HotspotIssueState(ctx context.Context, repo string, number int) (bool, time.Time, error) { - sum, ok, err := g.c.IssueSummary(ctx, repo, number) - if err != nil { - return false, time.Time{}, err - } - if !ok { - return false, time.Time{}, nil - } - return strings.EqualFold(sum.State, "open"), time.Time{}, nil + owner, name, ok := strings.Cut(repo, "/") + gh := g.c.GoGitHub() + if !ok || gh == nil { + return false, time.Time{}, nil + } + iss, resp, err := gh.Issues.Get(ctx, owner, name, number) + if err != nil { + if resp != nil && resp.StatusCode == http.StatusNotFound { + return false, time.Time{}, nil + } + return false, time.Time{}, err + } + return strings.EqualFold(iss.GetState(), "open"), iss.GetClosedAt().Time, nil } -
Store.dirtySaveis neither dirty-tracked nor deferred (src/pkg/hotspot/store.go:373): every mutator does a synchronousMarshalIndent+ write + rename of the whole state (PRs, conflicts, issues and the cachedResults).ObservePRis called once per train candidate per sweep from the planner (src/pkg/github/automerge/automerge_merge_train.go:376), so one sweep over N candidates rewrites/data/hotspots.jsonN times inside the merge-train path. Either rename tosave()so the name matches, or keep adirty booland addFlush()called fromrunHotspotAdvisorafterSetResults. The rename alone is fine for now:// save writes the state; callers hold s.mu. Errors are swallowed: the // store is advisory and rebuilds from the next sweeps. func (s *Store) save() { -
Dead exported API in a new package.
Store.ClosePR(store.go:108) has no caller at all;Store.ReconcileOpen(store.go:128) is only called fromhotspot_test.go:379. Production liveness goes throughTouchOpen/ExpireUnseen. Drop both (and theReconcileOpentest) so the store surface reflects what the advisor actually does, or wireReconcileOpenin and dropTouchOpen+ExpireUnseen— not both designs. -
Defaults are duplicated with "mirrors" comments and no parity check:
config.DefaultHotspot{WindowDays,MinPRs,MinOverlaps,MinLines,RefileDays}(src/pkg/config/config.go:2214-2218) vshotspot.Default{Window,MinPRs,MinOverlaps,MinLines}(src/pkg/hotspot/hotspot.go:119-122) and a thirdhotspot.DefaultHotspotRefileDays(src/pkg/hotspot/issue.go:298).cmd/hiveimports both; pin them there:// src/cmd/hive/hotspot_advisor_test.go func TestHotspotDefaultsMirrorConfig(t *testing.T) { if hotspot.DefaultWindow != time.Duration(config.DefaultHotspotWindowDays)*24*time.Hour || hotspot.DefaultMinPRs != config.DefaultHotspotMinPRs || hotspot.DefaultMinOverlaps != config.DefaultHotspotMinOverlaps || hotspot.DefaultMinLines != config.DefaultHotspotMinLines || hotspot.DefaultHotspotRefileDays != config.DefaultHotspotRefileDays { t.Fatal("pkg/hotspot defaults drifted from pkg/config governor.hotspot_* defaults") } }
Minor doc note: the changelog (changelog.d/added-merge-hotspot-advisor.md:1) says issues are "deduped by <!-- hive:hotspot file=… -->", but the marker is only written, never searched — dedupe is the PVC store (issue.go f.Store.Issue), which starts empty when the state file is unreadable (hotspot_advisor.go:50-53). Same idiom as upstream-watch, so fine; just say "deduped per file by the advisor's state" to avoid implying a GitHub-side lookup.
— hive: agent=adjudicator-4 backend=copilot model=claude-fable-5.1 copilot=1.0.88
… edges (94.5%) Signed-off-by: Andrew Anderson <andy@clubanderson.com>
b2dadf3
ℹ️ Sentinel notice — informational; author is trusted (owner), merge is not blockedHive flagged this PR (author @clubanderson, head
Hive did not add the |
There was a problem hiding this comment.
Blocked on the coverage gate, not on the design I read.
coveragejob 123580190265 at52fbde0:COVERAGE GATE FAILED: hotspot: 82.3% (floor 90%). The newpkg/hotspotis under the default per-package floor inv2-ci.yml; it needs ~8 points more (or a recorded floor, which is an owner call) before tide will take it.
What I verified about the write path, since this is a new agent-initiated external side effect:
- Filing is gated:
Filer.FileconsultsGate.IssueFileAllowedbeforeCreateHotspotIssue(pkg/hotspot/issue.go:271-274), and the only production wiring setsGate: ghAdapter(cmd/hive/hotspot_advisor.go:198-199), whose adapter goes throughWritebackAllowed(..., KindIssueFile, ...)(hotspot_advisor.go:83-86). Paused repos are respected via that gate. - One issue per file with refile wait: open-issue state is re-checked via
Staterand a closed one waitsRefile(issue.go:248-270). - Default-on:
HotspotIssuesEnabled()returns true whenhotspot_enabledis unset (config.go:2222-2224), as the body states — so every hive on this build starts filingagent/ci-maintainerissues on its watched repos after merge. That is the declared scope; I am just making it visible for whoever merges.
I did not read the detector/scoring (hotspot.go, kinds.go, store.go) in depth — no claim either way on those.
— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88
|
Thank you for your contribution! Your PR has been merged. We'd love to hear how your experience was: share feedback |
Fixes #15428
What
A merge-hotspot advisor for the governor. The merge train already detects when concurrent PRs touch the same file; this turns that signal into a periodic recommendation: this file keeps being the collision point — here is how to split it — filed as an issue for the ci-maintainer lane. It is what we just did by hand for
static/index.html(#15300) anddocs/api-reference.md(#15304).Detector (
pkg/hotspot)HotspotRecorderhook inautomerge), rebase-conflict events from the rebase follow-through, and open-PR liveness from the actionable snapshot. No new GitHub polling.code,doc,generated,lock,data. Docs are reported but only recommended as "split by section" when large; generated files (// Code generated,.pb.go, dashboardstatic/→static-src/) point at their source.go/ast, methods grouped under receiver; JS/TS/py regex; md##headings).Issue writer
KindIssueFile, honours paused repos,// writeback:gatedfor the ratchet). Labelsagent/ci-maintainer+kind/cleanup(kind/refactordoesn't exist on this repo).refactor: <path> is a merge hotspot — split into <N> units; body = marker<!-- hive:hotspot file=… -->, ≤ 300-word summary, evidence table, colliding symbol groups, concrete bucket proposal, generated-file note, explicit don't-splinter rule (≤ 4 files, each ≥ 150 lines, no behaviour change, tests move with code). Golden intestdata/issue_body.golden.md.hotspot_refile_daysafter close (injected clock in tests).Surface
GET /api/hotspots(per repo: file, prs, overlaps, conflicts, lines, kind, recommendation, symbol groups, issue, last_updated),hotspots: {count, actionable, filed}in/api/status,hivectl governor hotspots, OpenAPI entry.merge hotspotstile in the governor view (static-src → regeneratedindex.html; it is a ~10-line change so I kept it rather than API-only).operator-reference.mdsection,api-reference/dashboard-misc.md,health-status-events.md,hivectl.md; changelog fragment.Config keys added (
governor.*)hotspot_enabledtruehotspot_window_days7hotspot_min_prs6hotspot_min_overlaps3hotspot_min_lines800hotspot_refile_days30agent_runtime_golden.jsonis unchanged (all keysomitemptywith defaults applied via accessors).Dry run — hivecommons/hive, last 7 days
One GraphQL fetch (100 most recent merged PRs since 2026-10-22 + 18 open, files first:30), run through
Analyzewith default thresholds against this checkout for sizes/symbols (HOTSPOT_SAMPLE=… go test -run TestSampleDryRun ./pkg/hotspot/). 118 PRs → 17 hotspots; top 10:src/pkg/dashboard/static/index.htmlstatic-src/src/pkg/dashboard/stage_tracker.gosrc/docs/dashboard-sections.mdsrc/pkg/dashboard/static-src/css/tracker.csssrc/pkg/dashboard/api_repo_item_decide_delegated.gosrc/docs/api-reference.mdsrc/docs/operator-reference.mdsrc/pkg/dashboard/static-src/js/tracker-row.jssrc/pkg/dashboard/stage_tracker_row_actions_test.gosrc/docs/labels-and-control-signals.mdMatches the expected hits (
stage_tracker*.go,tracker-*.js,index.html→ points atstatic-src). Conflicts are 0 in the sample because the GraphQL export has no rebase records; in production they come from the rebase follow-through.Testing
go build ./...,go veton touched packages.go test -race -count=1onpkg/hotspot,pkg/config,pkg/policies,pkg/hivectl/commands,pkg/writeback(ratchet),pkg/github/automerge(merge-train),pkg/dashboard(hotspots, OpenAPI, import ratchet, status, webstatic staleness).scripts/check-api-reference-citations.shclean.