@marcomigozzi/trailhead 0.15.0 → 0.16.1

package/plugins/trailhead/hooks/mod/map-pane-view.ts

@@ -1,13 +1,14 @@
 // Pure view logic of the map pane: parse what `gh` printed, group the rows, word a
 // failure and an age, decide when a refresh may run. No engine calls here, so it is easy to test.
 import { fit } from './work-state-view'
-import type { BurndownHistory, BurndownIssue, DashboardRef, MapCounts, MapInfo, MapsRead, MapSummary, PaneTicket, TicketState, TicketType, UatParent } from '../../types'
+import type { BurndownHistory, BurndownIssue, DashboardRef, MapCounts, MapInfo, MapsRead, MapSummary, OpenTotal, PaneTicket, TicketState, TicketType, UatParent } from '../../types'
 
 export const TICKET_TYPES: readonly TicketType[] = ['decision', 'research', 'prototype', 'build', 'bug', 'task']
 
 // `isCapped`: gh returned as many rows as it was asked for, so the list may be cut.
 export type ParsedTickets = { tickets: readonly PaneTicket[]; unverifiedCount: number; isCapped: boolean }
 export type TicketGroups = {
+  needsYou: readonly PaneTicket[]
   frontier: readonly PaneTicket[]
   inProgress: readonly PaneTicket[]
   uat: readonly PaneTicket[]
@@ -68,17 +69,10 @@ const stateOf = (names: readonly string[], assignees: readonly string[]): Ticket
 // Only an https link is kept; anything else would be drawn as plain text.
 const safeUrl = (raw: unknown): string => (typeof raw === 'string' && /^https:\/\//.test(raw) ? raw : '')
 
-// `gh issue list --json number,title,labels,assignees,url`. Unverified rows are
-// quarantined (counted, never listed); whiteboard rows do not belong to a map, and on the
-// whiteboard (`isWhiteboard`) only they are kept.
-export const parseTickets = (stdout: string, opts: { isWhiteboard?: boolean } = {}): ParsedTickets | null => {
-  let raw: unknown
-  try {
-    raw = JSON.parse(stdout)
-  } catch {
-    return null
-  }
-  if (!Array.isArray(raw)) return null
+// The rows of an open-ticket list (the `gh issue list --json number,title,labels,assignees,url` shape).
+// Unverified rows are quarantined (counted, never listed); whiteboard rows do not belong to a map, and on the
+// whiteboard (`isWhiteboard`) only they are kept. A list that reached LIST_LIMIT rows is capped.
+export const ticketsFromRows = (raw: readonly unknown[], opts: { isWhiteboard?: boolean } = {}): ParsedTickets => {
   const rows = raw.filter(isRecord).filter(r => isPosInt(r.number))
   const named = rows.map(r => ({ r, names: labelNames(r.labels) }))
   const unverifiedCount = named.filter(({ names }) => names.includes(`${LABEL_PREFIX}unverified`)).length
@@ -95,13 +89,61 @@ export const parseTickets = (stdout: string, opts: { isWhiteboard?: boolean } =
         assignees,
         url: safeUrl(r.url),
         isUat: names.includes(`${LABEL_PREFIX}uat`),
+        isNeedsYou: names.includes(`${LABEL_PREFIX}needs-you`),
         uatOf: null,
       }
     })
   return { tickets, unverifiedCount, isCapped: raw.length >= LIST_LIMIT }
 }
 
-// `gh issue list --label trailhead:uat ... --json number,body`: ticket number -> the parent its first
+// `gh issue list --json ...` output as a ticket list; not a list is unreadable (null).
+export const parseTickets = (stdout: string, opts: { isWhiteboard?: boolean } = {}): ParsedTickets | null => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(stdout)
+  } catch {
+    return null
+  }
+  return Array.isArray(raw) ? ticketsFromRows(raw, opts) : null
+}
+
+// The rows that carry `name`: a GraphQL `labels:` filter is any-of, so an AND of two labels is done here.
+export const withLabel = (rows: readonly unknown[], name: string): unknown[] =>
+  rows.filter(r => isRecord(r) && labelNames(r.labels).includes(name))
+
+export type IssuesPage = { rows: unknown[]; hasNextPage: boolean; endCursor: string | null }
+
+// One page of the GraphQL open-ticket read (`repository.issues(...){nodes{...}pageInfo{...}}`), its nodes
+// flattened to the rows `gh issue list --json` prints so one parser serves both (`body` rides along only when
+// the node has a string one, so the ticket rows keep their shape). Any `errors` (even beside
+// partial `data`), a missing page info or a next page without a cursor is unreadable: the caller decides (`readOpen` falls back to
+// `gh issue list`, `readUat` fails closed to null).
+export const parseIssuesPage = (stdout: string): IssuesPage | null => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(stdout)
+  } catch {
+    return null
+  }
+  if (!isRecord(raw) || 'errors' in raw || !isRecord(raw.data) || !isRecord(raw.data.repository)) return null
+  const issues = raw.data.repository.issues
+  if (!isRecord(issues) || !Array.isArray(issues.nodes) || !isRecord(issues.pageInfo)) return null
+  const { hasNextPage, endCursor } = issues.pageInfo
+  if (typeof hasNextPage !== 'boolean') return null
+  if (hasNextPage && (typeof endCursor !== 'string' || endCursor === '')) return null
+  const inner = (v: unknown) => (isRecord(v) && Array.isArray(v.nodes) ? v.nodes : [])
+  const rows = issues.nodes.filter(isRecord).map(n => ({
+    number: n.number,
+    title: n.title,
+    url: n.url,
+    labels: inner(n.labels),
+    assignees: inner(n.assignees),
+    ...(typeof n.body === 'string' ? { body: n.body } : {}),
+  }))
+  return { rows, hasNextPage, endCursor: hasNextPage ? (endCursor as string) : null }
+}
+
+// The open `trailhead:uat` rows of the GraphQL read, as JSON (`number` and `body`): ticket number -> the parent its first
 // `UAT of:` line names, `[<name>](<url>/issues/<n>)` (or a bare `#<n>`, with an empty title). A row with
 // no such line, or an unreadable one, is skipped; not a list is unreadable (null).
 export const parseUatParents = (stdout: string): ReadonlyMap<number, UatParent> | null => {
@@ -237,7 +279,55 @@ export const parseMapsRead = (stdout: string): MapsRead | null => {
       }),
     )
     .sort((a, b) => a.number - b.number)
-  return { maps, whiteboard: whiteboardOf(repo) }
+  return { maps, whiteboard: whiteboardOf(repo), isMapsCapped: isCappedBy(issues, nodes.length) }
+}
+
+// More open maps exist than the read returned (`totalCount` above the nodes read); without a usable
+// `totalCount` a read that filled MAPS_READ_LIMIT is taken as cut.
+const isCappedBy = (issues: Record<string, unknown>, read: number): boolean => {
+  const count = totalOf(issues)
+  return count === null ? read >= MAPS_READ_LIMIT : count > read
+}
+
+// The most open maps one maps read asks for.
+export const MAPS_READ_LIMIT = 100
+
+// One query counting the open tickets of every open map and of the whiteboard: the dashboard's own scopes
+// (a ticket carries one map label or the whiteboard label, never both, so nothing counts twice).
+export const openTotalQuery = (maps: readonly number[]): string => {
+  const scope = (alias: string, label: string) => `${alias}:issues(states:OPEN,labels:["${label}"]){totalCount}`
+  const fields = [...maps.map(n => scope(`m${n}`, `${LABEL_PREFIX}map-${n}`)), scope('wb', `${LABEL_PREFIX}whiteboard`)]
+  return `query($owner:String!,$repo:String!){repository(owner:$owner,name:$repo){${fields.join('')}}}`
+}
+
+// The sum of every alias of `openTotalQuery`; any `errors`, a missing alias or an unusable count is
+// unreadable (null), never a partial sum shown as exact.
+export const parseOpenTotal = (stdout: string, maps: readonly number[]): number | null => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(stdout)
+  } catch {
+    return null
+  }
+  if (!isRecord(raw) || 'errors' in raw || !isRecord(raw.data) || !isRecord(raw.data.repository)) return null
+  const repo = raw.data.repository
+  const counts = [...maps.map(n => totalOf(repo[`m${n}`])), totalOf(repo.wb)]
+  return counts.some(c => c === null) ? null : counts.reduce((sum: number, c) => sum + (c as number), 0)
+}
+
+// The last good total, kept through a failed count read only while it was computed over exactly these open
+// maps (and the same cut of the maps read); a changed map set hides it rather than show it stale.
+export const keepOpenTotal = (kept: OpenTotal | null, maps: readonly number[], isMapsCapped: boolean): OpenTotal | null =>
+  kept !== null && kept.isMapsCapped === isMapsCapped && kept.maps.length === maps.length && kept.maps.every((n, i) => n === maps[i]) ? kept : null
+
+// The line of the total, long form first, the short one when that does not fit, null when unknown or when
+// not even the short one fits. A truncated maps read is a lower bound, worded as one.
+export const openTotalLabel = (total: number | null, isCapped: boolean, columns: number): string | null => {
+  if (total === null) return null
+  const long = `${isCapped ? 'at least ' : ''}${total} open across all maps + whiteboard`
+  if (long.length <= columns) return long
+  const short = `${isCapped ? '≥' : ''}${total} open in total`
+  return short.length <= columns ? short : null
 }
 
 // `gh issue list --label trailhead:dashboard --json number,url`: the pinned index, the lowest number
@@ -322,13 +412,13 @@ export const whiteboardHeading = (tickets: readonly PaneTicket[] | null, isCappe
 
 const byNumber = (a: PaneTicket, b: PaneTicket) => a.number - b.number
 
-// Paused wins, then a UAT ticket (whatever its state), then the state: each ticket shows once.
-type Place = TicketState | 'uat'
-const placeOf = (t: PaneTicket): Place => (t.state === 'paused' ? 'paused' : t.isUat ? 'uat' : t.state)
+// Needs-you wins, then paused, then a UAT ticket (whatever its state), then the state: each ticket shows once.
+type Place = TicketState | 'uat' | 'needs-you'
+const placeOf = (t: PaneTicket): Place => (t.isNeedsYou ? 'needs-you' : t.state === 'paused' ? 'paused' : t.isUat ? 'uat' : t.state)
 
 export const groupTickets = (tickets: readonly PaneTicket[]): TicketGroups => {
   const of = (place: Place) => tickets.filter(t => placeOf(t) === place).sort(byNumber)
-  return { frontier: of('frontier'), inProgress: of('in-progress'), uat: of('uat'), paused: of('paused'), blocked: of('blocked') }
+  return { needsYou: of('needs-you'), frontier: of('frontier'), inProgress: of('in-progress'), uat: of('uat'), paused: of('paused'), blocked: of('blocked') }
 }
 
 const errorText = (err: unknown): string => {
@@ -358,6 +448,10 @@ export const refreshDecision = (now: number, lastStartedAt: number | null, minMs
   return waitMs <= 0 ? { run: true } : { run: false, waitMs }
 }
 
+// A host timer dies silently (a refused `clock.after` never fires, a refused `every` period ends the
+// interval): one whose due time is past by more than the grace is held dead and started again.
+export const isTimerLate = (now: number, dueAt: number, graceMs: number): boolean => now - dueAt > graceMs
+
 export const ageLabel = (ms: number): string => {
   if (ms < 5_000) return 'just now'
   if (ms < 60_000) return `${Math.floor(ms / 1_000)}s ago`
@@ -365,7 +459,7 @@ export const ageLabel = (ms: number): string => {
   return `${Math.floor(ms / 3_600_000)}h ago`
 }
 
-export type RowAside = { kind: 'work' | 'queued' | 'holder' | 'self'; text: string }
+export type RowAside = { kind: 'work' | 'resume' | 'queued' | 'starting' | 'holder' | 'self'; text: string }
 export type RowLayout = {
   mark: string | null
   label: string
@@ -379,6 +473,8 @@ export type RowContext = {
   // True when the group holds the ticket in play: its rows share a two-cell mark column.
   hasMarkColumn: boolean
   pendingWork: number | null
+  // Whether the pending press waits for the turn to end (`queued`) or has been sent (`starting`).
+  pendingPhase: 'queued' | 'starting' | null
   columns: number
 }
 
@@ -408,20 +504,49 @@ export const footerStatus = (status: string, columns: number): FooterStatus => {
 
 const SELF_ASIDE: RowAside = { kind: 'self', text: 'this session' }
 
-// The ticket in play says `this session`; otherwise a frontier row has its button and the rest their holder.
-const asideOf = (t: PaneTicket, pendingWork: number | null, isInPlay: boolean): RowAside | null => {
+type Pending = { number: number | null; phase: 'queued' | 'starting' | null }
+// Only a press known to wait for the turn to end is offered a cancel; one sent, or not yet classed, is not.
+const pendingAside = (phase: Pending['phase']): RowAside =>
+  phase === 'queued' ? { kind: 'queued', text: 'queued' } : { kind: 'starting', text: 'starting' }
+
+const holderOf = (t: PaneTicket): RowAside => ({ kind: 'holder', text: t.assignees.map(a => `@${a}`).join(' ') })
+
+// A needs-you row: any holder first (a `work` press would steal the claim), then nothing when blocked,
+// else `work` (never `resume`: the claim clears the mark, resume would not).
+const needsYouAside = (t: PaneTicket, pending: Pending): RowAside | null => {
+  if (t.assignees.length > 0) return holderOf(t)
+  if (t.state === 'blocked') return null
+  return pending.number === t.number ? pendingAside(pending.phase) : { kind: 'work', text: 'work' }
+}
+
+// The ticket in play says `this session`; a needs-you row follows its own rule; otherwise a frontier row has
+// a `work` button, a paused one a `resume` button (the verb checks the claim), and the rest their holder.
+const asideOf = (t: PaneTicket, pending: Pending, isInPlay: boolean): RowAside | null => {
   if (isInPlay) return SELF_ASIDE
-  if (t.state === 'frontier') return pendingWork === t.number ? { kind: 'queued', text: 'queued' } : { kind: 'work', text: 'work' }
-  return t.assignees.length === 0 ? null : { kind: 'holder', text: t.assignees.map(a => `@${a}`).join(' ') }
+  if (t.isNeedsYou) return needsYouAside(t, pending)
+  if (t.state === 'frontier' || t.state === 'paused') {
+    if (pending.number === t.number) return pendingAside(pending.phase)
+    return t.state === 'frontier' ? { kind: 'work', text: 'work' } : { kind: 'resume', text: 'resume' }
+  }
+  return t.assignees.length === 0 ? null : holderOf(t)
 }
 
+// The button that takes a queued ticket back out of the queue.
+export const CANCEL_LABEL = 'cancel'
+const CANCEL_WIDTH = CANCEL_LABEL.length + BUTTON_CHROME + 1
+
 const asideWidth = (a: RowAside | null): number =>
-  a === null ? 0 : a.text.length + (a.kind === 'work' ? BUTTON_CHROME : 0) + 1
+  a === null
+    ? 0
+    : a.text.length + (a.kind === 'work' || a.kind === 'resume' ? BUTTON_CHROME : 0) + 1 + (a.kind === 'queued' ? CANCEL_WIDTH : 0)
+
+// The press the panel holds back while a turn runs, and releases when it ends.
+export type HeldPress = { id: number; verb: 'work' | 'resume'; number: number }
 
 // What one row draws, cut to the pane width: mark column, `#n title`, type, right-hand part.
 export const rowLayout = (t: PaneTicket, ctx: RowContext): RowLayout => {
   const mark = ctx.isInPlay ? MARK : ctx.hasMarkColumn ? MARK_PAD : null
-  const aside = asideOf(t, ctx.pendingWork, ctx.isInPlay)
+  const aside = asideOf(t, { number: ctx.pendingWork, phase: ctx.pendingPhase }, ctx.isInPlay)
   const type = t.type === null ? null : ` ${t.type}`
   const prefix = `#${t.number}`
   const room = ctx.columns - (mark?.length ?? 0) - asideWidth(aside) - (type?.length ?? 0) - prefix.length - 1