Ranggefuege: Rollen, die aufeinander aufbauen

Bisher trug jede Rolle ihre Rechte vollstaendig selbst. Bei achtzehn Rollen
und zweiundzwanzig Rechten heisst das, dass eine hoehere Rangrolle die ganze
Liste der darunterliegenden noch einmal abhaken muss - beim Anlegen
fehleranfaellig und bei jeder spaeteren Aenderung doppelt zu pflegen.

Ein Gefuege ist eine benannte, geordnete Folge von Rollen. Jede Sprosse
erbt alles von jeder Sprosse unter ihr, verwaltet wird nur noch das, was
oben dazukommt. Geerbt wird nicht nur die Rechteliste, sondern auch
Freigabestufe und Anmeldung: sonst waere eine Befoerderung unter Umstaenden
eine Herabstufung, naemlich immer dann, wenn Discord beim Befoerdern die
alte Rangrolle abnimmt.

Die Ordnung ist bewusst eine Reihenfolge und kein Zeiger je Rolle - ueber
ganzen Zahlen gibt es keinen Zyklus, den man abfangen muesste. Aufloesen
eines Gefueges laesst die Rollen stehen und nimmt nur das Geerbte weg.

Die Rechnung steht als reine Funktion in lib/auth/ladders.ts und wird an
drei Stellen benutzt: bei der Rechteaufloesung, in der Verwaltung und in
der Vorschau des Editors, die im Browser mitrechnet. Eine Vorschau, die den
Stand vor dem Verschieben zeigt, waere schlimmer als keine.

Die Rollenseite zeigt Geerbtes kursiv und gesperrt an, damit dort niemand
blind Kaestchen setzt, die laengst gesetzt sind.

Nebenbei: Aenderungen an der Rollenzuordnung landen jetzt im Protokoll, mit
Vorher und Nachher. Wer Rollen aendert, aendert die Rechte anderer - genau
dafuer ist es da.

web/lib/auth/ladders.ts

@@ -0,0 +1,123 @@
+import { isPermission, type Permission } from '@/lib/auth/permissions'
+
+/**
+ * Ranggefüge: Rollen, die aufeinander aufbauen.
+ *
+ * Eine Leiter ist eine benannte, geordnete Folge von Rollen, in der jede
+ * Sprosse alles kann, was jede Sprosse unter ihr kann. Der Grund ist die
+ * Pflege: ohne das trägt jede höhere Rangrolle die Rechte aller niedrigeren
+ * noch einmal als Kopie, und jede spätere Änderung ist an mehreren Stellen
+ * nachzuziehen - oder eben nicht, und dann laufen sie auseinander.
+ *
+ * Geerbt wird **alles**, was eine Rolle gewährt, nicht nur die Kästchen:
+ * Rechte, Freigabestufe und der Türsteher. Eine höhere Sprosse darf nie
+ * weniger wert sein als eine niedrigere, sonst wäre eine Beförderung unter
+ * Umständen eine Herabstufung - und genau das passiert, wenn beim Befördern in
+ * Discord die alte Rangrolle abgenommen wird, was dort üblich ist.
+ *
+ * Die Vererbung ist bewusst eine **Ordnung** und kein Zeiger je Rolle: über
+ * ganzen Zahlen gibt es keinen Zyklus, den man abfangen müsste.
+ */
+
+/** Das, was eine Rolle gewährt - so viel, wie für die Rechnung nötig ist. */
+export type LadderRung = {
+  discordRoleId: string
+  clearanceLevel: number
+  permissions: readonly string[]
+  grantsMembership: boolean
+  ladderId: string | null
+  ladderRank: number | null
+}
+
+/** Dasselbe, nachdem die Sprossen darunter eingerechnet sind. */
+export type ResolvedRung = {
+  clearanceLevel: number
+  permissions: Set<Permission>
+  grantsMembership: boolean
+  /** Nur das Geerbte, für die Anzeige im Adminbereich. */
+  inherited: Set<Permission>
+  /** Die Stufe der eigenen Zeile, falls die geerbte höher liegt. */
+  ownClearanceLevel: number
+}
+
+function leer(): ResolvedRung {
+  return {
+    clearanceLevel: 0,
+    permissions: new Set<Permission>(),
+    grantsMembership: false,
+    inherited: new Set<Permission>(),
+    ownClearanceLevel: 0,
+  }
+}
+
+/**
+ * Was eine einzelne Rolle gewährt, einschliesslich aller Sprossen unter ihr.
+ *
+ * `alle` muss nur die Rollen enthalten, die für diese Rechnung infrage kommen -
+ * die Leiter selbst genügt. Rollen ohne Leiter erben nichts und werden von
+ * keiner Leiter berührt.
+ */
+export function withInherited(rolle: LadderRung, alle: readonly LadderRung[]): ResolvedRung {
+  const ergebnis = leer()
+
+  ergebnis.clearanceLevel = rolle.clearanceLevel
+  ergebnis.ownClearanceLevel = rolle.clearanceLevel
+  ergebnis.grantsMembership = rolle.grantsMembership
+  for (const wert of rolle.permissions) {
+    if (isPermission(wert)) ergebnis.permissions.add(wert)
+  }
+
+  if (rolle.ladderId === null || rolle.ladderRank === null) return ergebnis
+
+  for (const andere of alle) {
+    if (andere.ladderId !== rolle.ladderId) continue
+    if (andere.ladderRank === null || andere.ladderRank > rolle.ladderRank) continue
+    if (andere.discordRoleId === rolle.discordRoleId) continue
+
+    if (andere.clearanceLevel > ergebnis.clearanceLevel) {
+      ergebnis.clearanceLevel = andere.clearanceLevel
+    }
+    if (andere.grantsMembership) ergebnis.grantsMembership = true
+    for (const wert of andere.permissions) {
+      if (!isPermission(wert)) continue
+      if (!ergebnis.permissions.has(wert)) ergebnis.inherited.add(wert)
+      ergebnis.permissions.add(wert)
+    }
+  }
+
+  return ergebnis
+}
+
+/**
+ * Dasselbe für einen ganzen Satz Rollen auf einmal, als Tabelle nach
+ * Rollen-ID. Für die Adminansicht, die jede Rolle mit ihrem tatsächlichen
+ * Ergebnis zeigen muss - sonst steht in der Vorschau etwas anderes, als der
+ * Nutzer später bekommt.
+ */
+export function resolveAll(alle: readonly LadderRung[]): Map<string, ResolvedRung> {
+  const tabelle = new Map<string, ResolvedRung>()
+  for (const rolle of alle) {
+    tabelle.set(rolle.discordRoleId, withInherited(rolle, alle))
+  }
+  return tabelle
+}
+
+/**
+ * Die höchste Sprosse je Leiter, die jemand mit diesen Rollen trägt.
+ *
+ * Damit lässt sich das Geerbte in **einer** weiteren Abfrage nachladen, statt
+ * die ganze Zuordnungstabelle zu holen und in JavaScript zu filtern.
+ */
+export function highestRungPerLadder(
+  rollen: readonly Pick<LadderRung, 'ladderId' | 'ladderRank'>[],
+): Map<string, number> {
+  const hoechste = new Map<string, number>()
+  for (const rolle of rollen) {
+    if (rolle.ladderId === null || rolle.ladderRank === null) continue
+    const bisher = hoechste.get(rolle.ladderId)
+    if (bisher === undefined || rolle.ladderRank > bisher) {
+      hoechste.set(rolle.ladderId, rolle.ladderRank)
+    }
+  }
+  return hoechste
+}