@opndev/tennis-match-center 0.0.1

package/lib/knockout-planner.mjs

@@ -0,0 +1,573 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { MATCH_MINUTES, REST_MINUTES } from './match-time.mjs'
+import { SPLIT_SIZES } from './knockout-draw.mjs'
+import { activePhase, activeSession } from './sessions.mjs'
+
+
+/**
+ * Which of two court blocks to prefer: the one standing closest
+ * together, then the one under lights, then the lower one.
+ *
+ * Light breaks a tie rather than deciding it - a round takes the lit
+ * courts where that costs it nothing, so an overrunning match still
+ * has somewhere to finish, but it does not climb the row to find them.
+ *
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {boolean}
+ */
+function cheaperWindow(a, b) {
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return a[i] < b[i]
+    }
+  }
+
+  return false
+}
+
+/**
+ * The courts a round takes this slot, or nothing where it cannot have
+ * them.
+ *
+ * Identities are picked here rather than when the round was sized, so
+ * the lower courts go to the round closest to its Final. Feasibility
+ * was counted against the same pool, but a round needing several slots
+ * is fussier than one needing a single slot, so it can still come up
+ * short once a shallower round has taken its pick - in which case it
+ * waits rather than start somewhere it cannot finish.
+ *
+ * Of the court sets that would do, it takes the one standing closest
+ * together, and the lowest of those - a division's matches belong in
+ * one band of the row rather than scattered down it, and the rounds
+ * are handed their courts nearest-the-Final first, so the band order
+ * follows the draw's own order.
+ *
+ * @param {Object} item The draw and the cut it is taking.
+ * @param {Array} pool Courts still going in this slot.
+ * @param {PlanningDay} day
+ * @param {Object} where Its slots and where the run starts.
+ * @returns {Array} The courts held, or an empty list.
+ */
+function holdCourts(item, pool, day, where, row) {
+  if (item.held) {
+    const held = item.held.filter(court => pool.includes(court))
+
+    return held.length === 0 ? [] : held
+  }
+
+  const fitting = day.fitting(pool, where, item.parts)
+
+  if (fitting.length < item.count) {
+    return []
+  }
+
+  const at = court => row.indexOf(court)
+  const busy = new Set(row.filter(court => !pool.includes(court)).map(at))
+
+  let best = null
+
+  for (let start = 0; start + item.count <= fitting.length; start++) {
+    const window = fitting.slice(start, start + item.count)
+    const cost = [
+      holesWith(busy, window.map(at), row.length),
+      at(window[window.length - 1]) - at(window[0]),
+      at(window[0]),
+      window.filter(court => !court.lit).length,
+    ]
+
+    if (best === null || cheaperWindow(cost, best.cost)) {
+      best = { window, cost }
+    }
+  }
+
+  return best.window
+}
+
+/**
+ * How many holes the row would have with these courts taken as well.
+ *
+ * A hole is a run of unused courts with play on both sides of it -
+ * "not yes, yes, no, yes; it should be yes, yes, yes, no". Courts
+ * idle at either end of the row are not holes, however many there are:
+ * a knockout round is half the one before it, so the tail empties out
+ * by design.
+ *
+ * @param {Set<number>} busy Positions already in use this slot.
+ * @param {number[]} taking Positions this round would take.
+ * @param {number} width Courts in the row.
+ * @returns {number}
+ */
+export function holesWith(busy, taking, width) {
+  const used = new Set([...busy, ...taking])
+
+  if (used.size === 0) {
+    return 0
+  }
+
+  let holes = 0
+  let open = false
+  let seen = false
+
+  for (let position = 0; position < width; position++) {
+    if (used.has(position)) {
+      if (open) {
+        holes += 1
+        open = false
+      }
+
+      seen = true
+    } else if (seen) {
+      open = true
+    }
+  }
+
+  return holes
+}
+
+/**
+ * Books a round onto its courts, part by part, and says when the
+ * division is next free.
+ *
+ * The courts are recorded on the unit the first time, so whatever it
+ * starts on it finishes on - re-picking each slot is what had a round
+ * open on C10/C11 and close on C14/C15 an hour later. A round too wide
+ * for the day to finish (its spill) pins nothing, there being no set
+ * of courts it could finish on.
+ *
+ * A split is its own rest: the half that played first has sat out
+ * every band the second half took, so no rest slot is charged on top.
+ *
+ * @param {Object} item The draw and the cut it is taking.
+ * @param {Array} held The courts it plays on.
+ * @param {Object} day The competition, its slots and the rest it owes.
+ * @param {PlanningDay} day The day it is booked on.
+ * @param {Object} where The competition, its slots and the rest owed.
+ */
+function placeRound(item, held, day, where) {
+  const { draw, parts } = item
+  const { competition, own, slotIndex, restSlots } = where
+  const width = draw.width
+  const already = draw.placedInRound
+  const round = draw.round.round
+
+  if (!item.spill) {
+    draw.pin(held)
+  }
+
+  let placed = 0
+
+  for (let part = 0; part < parts && already + placed < width; part++) {
+    const partSlot = own[slotIndex + part]
+
+    for (const court of held) {
+      if (already + placed >= width) {
+        break
+      }
+
+      day.place({
+        competition_id: competition.id,
+        division_id: draw.divisionId,
+        division_name: draw.divisionName,
+        division_gender: draw.divisionGender,
+        group_id: null,
+        group_name: null,
+        phase: 'knockout',
+        round,
+        match_slot: already + placed,
+        court_id: court.id,
+        date: day.date,
+        slot: partSlot.key,
+      }, partSlot)
+
+      placed += 1
+    }
+  }
+
+  draw.book({ count: placed, parts, slotIndex, restSlots })
+}
+
+/**
+ * How many whole slots of rest a division is owed between two of its
+ * rounds, beyond the slot it is playing in.
+ *
+ * A slot already at least a match plus a rest long (Team Cup's
+ * 90-minute tie: 45 to play plus the 45 owed) owes nothing more, and
+ * the next round can use the very next slot. A 60-minute doubles slot
+ * covers the match only and still owes 30 of the 45, which a plain
+ * floor(45 / 60) would lose entirely - rolling the next round onto the
+ * same courts with no break at all.
+ *
+ * @param {number} slotLength Minutes the competition's slot runs.
+ * @returns {number}
+ */
+function restSlotsFor(slotLength) {
+  const owed = Math.max(0, MATCH_MINUTES + REST_MINUTES - slotLength)
+
+  return Math.ceil(owed / slotLength)
+}
+
+/**
+ * Which of exactly two divisions may take this slot.
+ *
+ * Two divisions (Masters Men and Women, most often) share their courts
+ * turn by turn rather than both grabbing their own the same slot - one
+ * match at a time reads as a single continuous draw rather than two
+ * competing for attention side by side. Three or more fill a slot with
+ * everyone ready, there being no sensible "whose turn" with that many.
+ *
+ * Resting or already finished hands the slot to the other rather than
+ * sitting idle waiting for a turn nobody can take.
+ *
+ * @param {Array} units Both divisions, in their fixed order.
+ * @param {Array} ready Those that could go on now.
+ * @param {number} turnIndex Whose turn it is.
+ * @returns {Array} The one draw that may go on, or nothing.
+ */
+function whoseTurn(units, ready, turnIndex) {
+  const turn = ready.includes(units[turnIndex])
+    ? units[turnIndex]
+    : units[(turnIndex + 1) % 2]
+
+  return ready.includes(turn) ? [turn] : []
+}
+
+/**
+ * Fills the knockout day slot by slot.
+ *
+ * Each division's rounds are a queue. A round becomes eligible once
+ * the division has had its rest, and the slot is then filled with
+ * whichever eligible rounds fit - widest round first, and within a
+ * round the weakest field first, so the beginners open the day and
+ * the finals close it.
+ *
+ * Laying the day out as strict round columns (every R32 before any
+ * R16) was too rigid: it left the whole grid idle while one division
+ * rested, when a division that had already rested could have played
+ * its next round alongside someone else's current one.
+ *
+ * A round goes on whole where the room is there, and is otherwise cut
+ * the way the bracket cuts - see SPLIT_SIZES above.
+ *
+ * @param {PlanningDay} day The date being filled - its courts, slots,
+ *   occupancy and the plan the cells go into.
+ * @param {Object} params
+ * @param {Array} params.competitions In priority order.
+ * @param {Array<KnockoutDraw>} params.draws Every draw in the event;
+ *   each competition takes its own.
+ * @param {Map<number, Array>} params.sessions Each competition's
+ *   sessions, in order.
+ * @param {boolean} params.split Whether a round may be cut at all.
+ */
+export function assignKnockout(day, { competitions, draws, sessions, split }) {
+  const { date } = day
+
+  for (const competition of competitions) {
+    const own = day.slotsFor(competition.id)
+    const ownSessions = sessions.get(competition.id) ?? []
+
+    const ownSession = activeSession(ownSessions, date)
+    const restSlots = restSlotsFor(ownSession?.playtime ?? MATCH_MINUTES)
+
+    const firstSlot = own.findIndex(slot =>
+      (slot.phase ?? activePhase(ownSessions, date, slot.key)) === 'knockout'
+    )
+
+    if (firstSlot === -1) {
+      continue
+    }
+
+    for (const pro of [true, false]) {
+    const lane = { pro, courts: day.courtsFor(pro) }
+    const units = draws.filter(draw =>
+      draw.competition.id === competition.id && draw.isPro === pro
+    )
+
+    if (units.length === 0) {
+      continue
+    }
+
+    let turnIndex = 0
+
+    for (let slotIndex = firstSlot; slotIndex < own.length; slotIndex++) {
+      const slot = own[slotIndex]
+
+      /** The lane's courts with nothing on them in this slot. */
+      function free() {
+        return day.free(lane.courts, slot)
+      }
+
+      if (free().length === 0) {
+        continue
+      }
+
+      let ready = units
+        .filter(draw => draw.readyAt(slotIndex))
+        .sort((a, b) => (b.width - a.width) || (b.level - a.level))
+
+      if (ready.length === 0) {
+        continue
+      }
+
+      if (units.length === 2) {
+        ready = whoseTurn(units, ready, turnIndex)
+      }
+
+      if (ready.length === 0) {
+        continue
+      }
+
+      const placedHere = []
+
+      const fittingCache = new Map()
+      const where = { slots: own, slotIndex }
+
+      /**
+       * The courts that could hold every part of a run this long,
+       * memoised for the slot.
+       *
+       * @param {number} parts Consecutive slots the run would take.
+       * @returns {Array} Courts free for all of them.
+       */
+      function fittingCourts(parts) {
+        if (!fittingCache.has(parts)) {
+          fittingCache.set(parts, day.fitting(free(), where, parts))
+        }
+
+        return fittingCache.get(parts)
+      }
+
+      /**
+       * Every way this round could go on in this slot, cheapest cut
+       * first. The band picks between them across divisions rather
+       * than each division taking the best it can see and leaving the
+       * next one the scraps.
+       *
+       * A round already under way keeps the courts it started on: they
+       * were decided when it started and it finishes on them, whatever
+       * of them is free now being all it may have.
+       *
+       * @param {KnockoutDraw} draw
+       * @param {Object} [options]
+       * @param {boolean} [options.forceSplit] Cut it even where the
+       *   caller would rather have whole rounds - the band would
+       *   otherwise stand empty.
+       * @returns {Array<{parts: number, count: number}>}
+       */
+      function optionsFor(draw, { forceSplit = false } = {}) {
+        const { width, remaining } = draw
+
+        if (remaining <= 0) {
+          return []
+        }
+
+        if (draw.roundCourts) {
+          const held = fittingCourts(1)
+            .filter(court => draw.roundCourts.includes(court.id))
+            .slice(0, remaining)
+
+          if (held.length === 0) {
+            return []
+          }
+
+          return [{ parts: 1, count: held.length, held }]
+        }
+
+        const cutting = split || forceSplit
+        const slotsLeft = own.length - slotIndex
+        const usable = day.usable(lane.courts, slot).length
+
+        const options = draw.cuts(cutting)
+          .filter(cut => fittingCourts(cut.parts).length >= cut.count)
+
+        if (options.length > 0 || !cutting) {
+          return options
+        }
+
+        if (width <= usable * slotsLeft) {
+          return []
+        }
+
+        const spill = Math.min(remaining, fittingCourts(1).length)
+
+        return spill > 0 ? [{ parts: 1, count: spill, spill: true }] : []
+      }
+
+      /**
+       * Whether the courts exist for a set of choices. A court free
+       * for four slots running is free for two, so the deeper cuts are
+       * checked first and everything shallower shares what is left.
+       */
+      function roomFor(choices) {
+        return SPLIT_SIZES.every(depth => {
+          const need = choices
+            .filter(choice => choice.parts >= depth)
+            .reduce((total, choice) => total + choice.count, 0)
+
+          return need <= fittingCourts(depth).length
+        })
+      }
+
+      /**
+       * Whether this band leaves the draw reading forwards. A later
+       * round never goes on while an earlier one is still waiting for
+       * the room to go on whole, or one division would be playing
+       * quarters while another has not had its sixteenths.
+       */
+      function inOrder(taken, waiting) {
+        const held = Math.max(
+          ...waiting.map(draw => draw.roundsRemaining), -Infinity
+        )
+
+        return taken.every(({ draw }) => draw.roundsRemaining >= held)
+      }
+
+      /**
+       * Whether this choice abandons a split the division is already
+       * in. Its second half is a round behind its first all the way
+       * down, and going back to whole rounds would put the two halves
+       * on court together. The Final ends it: a semi split 1/1 still
+       * leads to one Final.
+       */
+      function breaksStride({ draw, choice }) {
+        return draw.breaksStride(choice.parts)
+      }
+
+      /**
+       * What a band costs, compared term by term, lowest winning:
+       * divisions breaking stride, then courts left idle, then the
+       * deepest cut anyone takes, then the number of cuts.
+       *
+       * @returns {number[]}
+       */
+      function cost(taken) {
+        return [
+          taken.filter(breaksStride).length,
+          -taken.reduce((total, { choice }) => total + choice.count, 0),
+          Math.max(...taken.map(({ choice }) => choice.parts), 0),
+          taken.reduce((total, { choice }) => total + choice.parts, 0),
+        ]
+      }
+
+      function cheaper(a, b) {
+        const left = cost(a)
+        const right = cost(b)
+
+        for (let i = 0; i < left.length; i++) {
+          if (left[i] !== right[i]) {
+            return left[i] < right[i]
+          }
+        }
+
+        return false
+      }
+
+      /**
+       * The cheapest set of rounds this band can hold, over every
+       * combination of the ready divisions and their legal cuts.
+       *
+       * @returns {Array<{draw: Object, choice: Object}>} Empty where
+       *   nothing can go on at all.
+       */
+      function bandChoice({ forceSplit = false } = {}) {
+        const offered = ready
+          .map(draw => ({ draw, options: optionsFor(draw, { forceSplit }) }))
+
+        const candidates = offered.filter(one => one.options.length > 0)
+
+        // A round with no cut that fits anywhere is waiting for room
+        // just as surely as one that was passed over, and a later
+        // round must not go on ahead of it. Leaving these out of the
+        // reckoning is what let a QF open before another division's
+        // R16 had started at all.
+        const stuck = offered
+          .filter(one => one.options.length === 0)
+          .map(one => one.draw)
+
+        let best = null
+
+        function walk(index, taken) {
+          if (index === candidates.length) {
+            if (taken.length === 0) {
+              return
+            }
+
+            const waiting = candidates
+              .filter(candidate => !taken.some(
+                ({ draw }) => draw === candidate.draw
+              ))
+              .map(candidate => candidate.draw)
+              .concat(stuck)
+
+            const choices = taken.map(({ choice }) => choice)
+
+            if (!roomFor(choices) || !inOrder(taken, waiting)) {
+              return
+            }
+
+            if (best === null || cheaper(taken, best)) {
+              best = taken
+            }
+
+            return
+          }
+
+          const { draw, options } = candidates[index]
+
+          for (const choice of options) {
+            walk(index + 1, [...taken, { draw, choice }])
+          }
+
+          walk(index + 1, taken)
+        }
+
+        walk(0, [])
+
+        return best ?? []
+      }
+
+      for (const { draw, choice } of bandChoice()) {
+        placedHere.push({ draw, ...choice })
+      }
+
+      if (placedHere.length === 0) {
+        for (const { draw, choice } of bandChoice({ forceSplit: true })) {
+          placedHere.push({ draw, ...choice })
+        }
+      }
+
+      if (placedHere.length === 0) {
+        continue
+      }
+
+      placedHere.sort((a, b) =>
+        (a.draw.level - b.draw.level) ||
+        (a.draw.roundsRemaining - b.draw.roundsRemaining)
+      )
+
+      let pool = free()
+
+      for (const item of placedHere) {
+        const held = holdCourts(item, pool, day, where, lane.courts)
+
+        if (held.length === 0) {
+          continue
+        }
+
+        pool = pool.filter(court => !held.includes(court))
+
+        placeRound(item, held, day, {
+          competition, own, slotIndex, restSlots,
+        })
+      }
+
+      if (units.length === 2 && placedHere.length > 0) {
+        turnIndex = units.indexOf(placedHere[0].draw) === 0 ? 1 : 0
+      }
+    }
+    }
+  }
+}