diff --git a/changelog.d/added-preparation-queue-visual-order.md b/changelog.d/added-preparation-queue-visual-order.md new file mode 100644 index 0000000000..0b9b2ebae3 --- /dev/null +++ b/changelog.d/added-preparation-queue-visual-order.md @@ -0,0 +1 @@ +- Show preparation owners and FIFO waiting positions in a visible train-style Activity Monitor rail, removing redundant preparation pills and the zero-train header summary while preserving real ready trains, PR stages, row sorting, pagination, and issue trees. diff --git a/src/docs/dashboard.md b/src/docs/dashboard.md index 974c2cbafe..297cba3452 100644 --- a/src/docs/dashboard.md +++ b/src/docs/dashboard.md @@ -2,6 +2,37 @@ ## Base preparation visibility +A directly visible **Preparation queue** overview above the pipeline reuses the +train's rail, marker and header styling without seating preparation work in a +ready merge train. A confirmed owner reads **Preparing** and confirmed waiters +are numbered in durable FIFO order of first qualifying admission, not PR +creation time or number. This is preparation order, not guaranteed merge order: +independently ready PRs may merge, invalid tickets can leave, and changed work +may qualify again at the end of the FIFO. + +The overview contains references to the actual PR rows, not copied or reparented +pipeline rows. Existing custom sorts, filters, pages, collapsed repo groups and +multiple-PR issue trees remain unchanged. Only PRs actually drawn on the current +page receive a rail entry; missing members are explicitly identified as on +another page/collapsed repo or hidden by the current filters. A member can keep +its true waiting ordinal when earlier confirmed members are not on the page. +Redundant preparation/behind-owner pills are suppressed only on PRs visibly +represented by that rail. Outside it the existing pills remain useful fallbacks; +unverified warnings and real CI / Review / held signals are never suppressed. +The gold header chip/popover no longer repeats preparation counts or tickets +when the rail is present, and is hidden when no genuine ready train exists. +Distinct ready-train information remains available in its existing train view +and ready-only queue popover; preparation is never promoted into those seats. + +Unverified recorded owners or tickets have a separate, unnumbered note. An +unverified waiting ticket prevents confirming the ordinal of later tickets; +their relative FIFO order remains visible but their position reads unverified. +No old admission-head proof is transferred to a refreshed head. Tooltips explain +the distinction from review approval, readiness and native queue membership. +The rail uses a labelled region/list, ordinary links, existing theme tokens, +and static markers with no animation (including reduced-motion mode). It reads +the existing cached tracker payload and adds no polling or store reads. + The Activity Monitor's existing **Merge queue** chip also shows durable base preparation tickets for repositories using the current-base gate, even when no ready merge train exists. Its popover distinguishes the recorded owner from FIFO diff --git a/src/pkg/dashboard/stage_tracker_preparation_visual.test.js b/src/pkg/dashboard/stage_tracker_preparation_visual.test.js new file mode 100644 index 0000000000..a9e693385d --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_preparation_visual.test.js @@ -0,0 +1,310 @@ +// Execute the shipped preparation projection/rendering helpers in CI. The +// pipeline owns filtering/sorting/paging; the rail only references its result. +const test = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); +const vm = require('node:vm'); +const source = name => fs.readFileSync(path.join(__dirname, 'static-src/js', name + '.js'), 'utf8'); +const fn = (file, name) => { + const found = source(file).match(new RegExp('function ' + name + '\\([^\\n]*\\) \\{[\\s\\S]*?\\n \\}')); + assert.ok(found, name); + return found[0]; +}; +const NOW = Date.parse('2026-10-31T01:00:00Z'); +const REPO = 'hivecommons/hive'; +const esc = value => String(value).replace(/[&<>"']/g, ch => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[ch])); +const plain = value => JSON.parse(JSON.stringify(value)); + +function load() { + const region = { hidden: true, innerHTML: '' }; + const elements = new Map(); + let present = true; + const ctx = vm.createContext({ console, Date, esc, + document: { getElementById: id => id === 'activity-monitor-preparation' ? present ? region : null : elements.get(id) || null }, + stageTrackerAnchor: stage => Number(stage) || 0, + stageTrackerAttentionTier: () => 1, + stageTrackerNormalizeFilter: f => f, + STAGE_TRACKER_TERMINAL: 100, + }); + const core = source('tracker-words-core'); + for (const name of ['STAGE_TRACKER_TRAIN_ICON_PATH', 'STAGE_TRACKER_TRAIN_ICON_TITLE', 'STAGE_TRACKER_TRAIN_ACCENTS']) { + const found = core.match(new RegExp('const ' + name + ' = [^\\n]+')); + assert.ok(found, name); + vm.runInContext(found[0], ctx); + } + for (const name of ['stageTrackerTrainIconHtml', 'stageTrackerTrainAccentClass', 'stageTrackerOrdinal']) vm.runInContext(fn('tracker-words-core', name), ctx); + for (const name of ['stageTrackerLinkedSuperseder', 'stageTrackerLinkedSupersededGone']) vm.runInContext(fn('tracker-words-gate', name), ctx); + for (const name of ['stageTrackerLinkedPRItem', 'stageTrackerLinkedPROpen', 'stageTrackerLinkedDrawnHere', 'stageTrackerLinkedSorted', 'stageTrackerAdoptOrphanPRs']) vm.runInContext(fn('tracker-row-layout', name), ctx); + for (const name of ['stageTrackerPreparationWord', 'stageTrackerPreparationAge', 'stageTrackerPreparationChipHtml']) vm.runInContext(fn('tracker-queue', name), ctx); + for (const name of ['stageTrackerSort', 'stageTrackerPage']) vm.runInContext(fn('tracker-filter', name), ctx); + vm.runInContext(source('tracker-preparation'), ctx); + return { ctx, region, elements, removeRegion() { present = false; } }; +} +function fixture() { + const pr = (number, stage, caption) => ({ kind: 'pr', repo: REPO, number, stage, caption, state: 'open', + head: 'head-' + number, base_ref: 'v5', title: 'PR ' + number, url: 'https://github.com/' + REPO + '/pull/' + number, + created_at: '2026-10-30T00:00:00Z' }); + const owner = pr(45, 70, 'Review · no free reviewer'); + const first = pr(9, 50, 'CI · checks pending'); + const second = pr(2, 70, 'Review · exact-head bundle pending'); + const ticket = (it, role) => ({ role, number: it.number, state: 'current', head_sha: it.head, + current_head: it.head, since: '2026-10-31T00:30:00Z', pipeline: it.caption, + detail: 'Ticket matches the current open PR snapshot', ...(role === 'waiting' ? { behind: owner.number } : {}) }); + const q = { repo: REPO, base_ref: 'v5', state: 'observed', owner: ticket(owner, 'owner'), waiting: [ticket(first, 'waiting'), ticket(second, 'waiting')] }; + owner.preparation = q.owner; + first.preparation = q.waiting[0]; + second.preparation = q.waiting[1]; + return { owner, first, second, q, data: { items: [second, first, owner], base_preparation: [q] } }; +} +function model(ctx, f, listed = f.data.items, page = listed) { + return ctx.stageTrackerPreparationVisualModel(f.data, listed, page, []); +} + +test('owner first and persisted FIFO, not PR number/age, with original stages and train facts unchanged', () => { + const { ctx } = load(), f = fixture(); + f.owner.merge_train = { id: 'real-ready-train', position: 2 }; + f.first.created_at = '2020-01-01T00:00:00Z'; + const before = plain(f.data); + const groups = model(ctx, f), html = ctx.stageTrackerPreparationVisualHtml(groups, NOW); + assert.equal(groups[0].owner.ticket.number, 45); + assert.deepEqual(plain(groups[0].waiting.map(e => [e.ticket.number, e.position])), [[9, 1], [2, 2]]); + assert.ok(html.indexOf('Preparing') < html.indexOf('Waiting 1st for preparation')); + assert.ok(html.indexOf('Waiting 1st for preparation') < html.indexOf('Waiting 2nd for preparation')); + assert.match(html, /Review · no free reviewer/); + assert.match(html, /CI · checks pending/); + assert.match(html, /ticket age 30m/); + assert.match(html, /not guaranteed merge order/); + assert.deepEqual(plain(f.data), before); + assert.doesNotMatch(html, /data-ham-train=|data-ham-key=|ham-row|aria-label="Merge queue"|Ready for merge|Merged!/); +}); + +test('release/handoff clears former owner and recomputes waiting positions from new snapshot', () => { + const { ctx, region } = load(), f = fixture(); + ctx.stageTrackerPreparationVisualSync(f.data, f.data.items, f.data.items, [], NOW); + assert.equal(ctx.stageTrackerPreparationChipHtml(f.first), ''); + f.q.owner = { ...f.first.preparation, role: 'owner' }; + f.first.preparation = f.q.owner; + f.q.waiting = [f.second.preparation]; + f.second.preparation.behind = f.first.number; + f.data.items = [f.first, f.second, f.owner]; + ctx.stageTrackerPreparationVisualSync(f.data, f.data.items, f.data.items, [], NOW); + assert.match(region.innerHTML, />#9 PR 9<\/a>/); + assert.doesNotMatch(region.innerHTML, /Owner #45|Waiting 2nd/); + assert.equal(ctx.stageTrackerPreparationRepresented(f.owner), false); + assert.match(ctx.stageTrackerPreparationChipHtml(f.owner), /Preparing base/); + assert.equal(f.first.stage, 50); + assert.equal(f.second.stage, 70); +}); + +test('inactive merged/held/expired tickets are excluded and readmission uses new FIFO order', () => { + const { ctx } = load(), f = fixture(); + f.q.waiting.unshift(...['merged', 'held', 'expired'].map((detail, i) => ({ number: 100 + i, role: 'waiting', state: 'inactive', detail }))); + let groups = model(ctx, f); + assert.equal(groups[0].inactive, 3); + assert.deepEqual(plain(groups[0].waiting.map(e => e.position)), [1, 2]); + const html = ctx.stageTrackerPreparationVisualHtml(groups, NOW); + assert.match(html, /3 inactive tickets excluded/); + assert.doesNotMatch(html, /#100|#101|#102/); + f.q.waiting = [f.second.preparation, f.first.preparation]; + groups = model(ctx, f); + assert.deepEqual(plain(groups[0].waiting.map(e => [e.ticket.number, e.position])), [[2, 1], [9, 2]]); +}); + +test('unverified refreshed owner stays ahead as a warning without old-head pipeline proof', () => { + const { ctx } = load(), f = fixture(); + f.owner.head = 'own-refreshed-head'; + f.q.owner.state = 'unverified'; + f.q.owner.current_head = f.owner.head; + f.q.owner.detail = 'Head changed; current preparation unverified'; + f.q.owner.pipeline = 'old-head APPROVED proof'; + const groups = model(ctx, f), html = ctx.stageTrackerPreparationVisualHtml(groups, NOW); + assert.equal(groups[0].owner, null); + assert.equal(groups[0].unverified[0].ticket.number, 45); + assert.ok(html.indexOf('Unverified recorded owner #45') < html.indexOf('Waiting 1st')); + assert.doesNotMatch(html, /old-head APPROVED proof/); + assert.match(ctx.stageTrackerPreparationChipHtml(f.owner), /unverified/); +}); + +test('unknown predecessor prevents fabricated exact ranks for subsequent confirmed tickets', () => { + const { ctx } = load(), f = fixture(); + f.q.waiting.unshift({ number: 77, role: 'waiting', state: 'unverified', head_sha: 'missing', detail: 'Not in current tracker snapshot' }); + const groups = model(ctx, f), html = ctx.stageTrackerPreparationVisualHtml(groups, NOW); + assert.deepEqual(plain(groups[0].waiting.map(e => e.position)), [0, 0]); + assert.match(html, /position unverified/); + assert.match(html, /Unverified recorded ticket #77/); + assert.doesNotMatch(html, /Waiting 1st|Waiting 2nd/); +}); + +test('exact repo/base/head join rejects stale or missing identities instead of borrowing proofs', () => { + for (const change of [ + f => { f.first.head = 'new-head'; }, + f => { f.first.base_ref = 'different-base'; }, + f => { f.first.repo = 'someone/else'; }, + f => { f.first.preparation.current_head = 'different-current-head'; }, + f => { f.data.items = [f.owner, f.second]; }, + ]) { + const { ctx } = load(), f = fixture(); + change(f); + const groups = model(ctx, f), html = ctx.stageTrackerPreparationVisualHtml(groups, NOW); + assert.ok(groups[0].unverified.some(e => e.ticket.number === f.first.number)); + assert.equal(groups[0].waiting[0].position, 0); + assert.doesNotMatch(html, /CI · checks pending/); + } +}); + +test('filters and pagination preserve FIFO ordinals but never draw absent members as visible seats', () => { + const { ctx } = load(), f = fixture(); + const groups = model(ctx, f, [f.owner, f.second], [f.second]); + const html = ctx.stageTrackerPreparationVisualHtml(groups, NOW); + assert.equal(groups[0].owner.location, 'offpage'); + assert.deepEqual(plain(groups[0].waiting.map(e => [e.location, e.position])), [['filtered', 1], ['page', 2]]); + assert.match(html, /1 of 3 confirmed tickets shown/); + assert.match(html, /On another page or in a collapsed repo: Preparing #45/); + assert.match(html, /Not shown by the current filters: Waiting 1st for preparation #9/); + assert.equal((html.match(/
  • /); + assert.match(html, /Owner #45/); +}); + +test('actual number/custom sorting and page slice remain unchanged by the rail', () => { + const { ctx } = load(), f = fixture(); + const ordered = ctx.stageTrackerSort(f.data.items, [], { sort: 'number', dir: 'desc' }); + const page = ctx.stageTrackerPage(ordered, { size: 25, page: 1 }); + const before = plain(page); + const groups = model(ctx, f, ordered, page.rows); + ctx.stageTrackerPreparationVisualHtml(groups, NOW); + assert.deepEqual(plain(page), before); + assert.deepEqual(plain(page.rows.map(it => it.number)), [45, 9, 2]); + assert.deepEqual(plain(groups[0].waiting.map(e => e.ticket.number)), [9, 2]); + assert.deepEqual(plain(f.data.items.map(it => it.stage)), [70, 50, 70]); +}); + +test('linked multiple PRs and shared issue trees are referenced once without reparenting rows', () => { + const { ctx } = load(), f = fixture(); + const issue = { kind: 'issue', repo: REPO, number: 500, stage: 40, + linked_prs: [{ ...f.first, drawn_under: 500 }, { ...f.second, drawn_under: 500 }] }; + const other = { ...issue, number: 501, linked_prs: issue.linked_prs.map(lp => ({ ...lp })) }; + f.data.items = [issue, other, f.owner]; + const before = plain(f.data); + const groups = model(ctx, f), html = ctx.stageTrackerPreparationVisualHtml(groups, NOW); + assert.equal(groups[0].waiting.length, 2); + assert.deepEqual(plain(groups[0].waiting.map(e => e.row.host.number)), [500, 500]); + assert.equal((html.match(/
  • { + const { ctx } = load(), f = fixture(); + const stale = { kind: 'issue', repo: REPO, number: 500, linked_prs: [{ ...f.first, head: 'old-linked-head' }] }; + f.data.items.push(stale); + const groups = model(ctx, f, [stale], [stale]); + assert.ok(groups[0].unverified.some(e => e.ticket.number === f.first.number)); + assert.equal(groups[0].waiting.some(e => e.ticket.number === f.first.number), false); +}); + +test('only represented exact current members lose redundant pills; ungrouped/unknown fallback stays', () => { + const { ctx, region, removeRegion } = load(), f = fixture(); + assert.match(ctx.stageTrackerPreparationChipHtml(f.first), /Waiting for preparation behind #45/); + ctx.stageTrackerPreparationVisualSync(f.data, [f.first], [f.first], [], NOW); + assert.equal(ctx.stageTrackerPreparationChipHtml(f.first), ''); + assert.match(ctx.stageTrackerPreparationChipHtml(f.second), /Waiting for preparation behind #45/); + assert.match(ctx.stageTrackerPreparationChipHtml(f.owner), /Preparing base/); + assert.equal(f.first.stage, 50); + assert.match(region.innerHTML, /Waiting 1st for preparation/); + f.first.preparation.state = 'unverified'; + assert.match(ctx.stageTrackerPreparationChipHtml(f.first), /unverified/); + f.first.preparation.state = 'current'; + f.first.head = 'changed-after-render'; + assert.match(ctx.stageTrackerPreparationChipHtml(f.first), /Waiting for preparation/); + f.first.head = f.first.preparation.head_sha; + removeRegion(); + ctx.stageTrackerPreparationVisualSync(f.data, f.data.items, f.data.items, [], NOW); + assert.match(ctx.stageTrackerPreparationChipHtml(f.first), /Waiting for preparation behind #45/); +}); + +test('single covering PR suppresses only redundant preparation annotation, not its real stage or signals', () => { + const { ctx } = load(), f = fixture(); + const issue = { kind: 'issue', repo: REPO, number: 500, linked_prs: [{ ...f.first }] }; + f.data.items = [issue, f.owner, f.second]; + ctx.stageTrackerPreparationVisualSync(f.data, f.data.items, f.data.items, [], NOW); + const shown = { ...issue, via_pr: true, preparation: f.first.preparation, head: f.first.head, stage: f.first.stage, hold: { reason: 'needs human' }, caption: f.first.caption }; + assert.equal(ctx.stageTrackerPreparationChipHtml(shown), ''); + assert.equal(shown.stage, 50); + assert.deepEqual(shown.hold, { reason: 'needs human' }); + assert.equal(shown.caption, 'CI · checks pending'); + shown.preparation = { ...shown.preparation, state: 'unverified' }; + assert.match(ctx.stageTrackerPreparationChipHtml(shown), /unverified/); +}); + +test('inactive policy hides the rail; unavailable/loading state is explicit and clears pill suppression', () => { + const { ctx, region } = load(), f = fixture(); + ctx.stageTrackerPreparationVisualSync(f.data, f.data.items, f.data.items, [], NOW); + f.data.base_preparation = []; + ctx.stageTrackerPreparationVisualSync(f.data, f.data.items, f.data.items, [], NOW); + assert.equal(region.hidden, true); + assert.match(ctx.stageTrackerPreparationChipHtml(f.first), /Waiting for preparation/); + delete f.data.base_preparation; + assert.deepEqual(plain(model(ctx, f)), []); + f.data.base_preparation = [{ repo: REPO, base_ref: 'v5', state: 'unavailable', message: 'durable snapshot read failed' }]; + ctx.stageTrackerPreparationVisualSync(f.data, f.data.items, [], [], NOW); + assert.equal(region.hidden, false); + assert.match(region.innerHTML, /durable snapshot read failed/); + ctx.stageTrackerPreparationVisualSync(null, [], [], [], NOW); + assert.match(region.innerHTML, /Preparation queue unavailable/); + assert.doesNotMatch(region.innerHTML, /0 confirmed|
  • { + const { ctx } = load(), f = fixture(); + f.first.title = ' & title'; + f.q.waiting[0].pipeline = ''; + const html = ctx.stageTrackerPreparationVisualHtml(model(ctx, f), NOW); + assert.match(html, /aria-label="Preparation queue"/); + assert.match(html, /aria-label="Confirmed preparation order on this page"/); + assert.match(html, /<img onerror="bad">/); + assert.doesNotMatch(html, /