From 8acbb5da267a5496571d8381949f2f25d1637563 Mon Sep 17 00:00:00 2001
From: Jonathan de Jong <jonathan@automatia.nl>
Date: Fri, 30 Sep 2022 14:20:48 +0200
Subject: [PATCH 1/3] add ListMessageSplitter and apply to rules command

---
 src/ListMessageSplitter.ts       | 217 +++++++++++++++++++++++++++++++
 src/commands/DumpRulesCommand.ts |  66 ++++++----
 2 files changed, 261 insertions(+), 22 deletions(-)
 create mode 100644 src/ListMessageSplitter.ts

diff --git a/src/ListMessageSplitter.ts b/src/ListMessageSplitter.ts
new file mode 100644
index 00000000..4a6da6a1
--- /dev/null
+++ b/src/ListMessageSplitter.ts
@@ -0,0 +1,217 @@
+import {LogService} from "matrix-bot-sdk";
+
+export type MessageSnippet = { html: string, text: string };
+
+// The max size a message can be, with 24_000 picked at random to accommodate for overhead.
+const OVERHEAD = 24_000
+const MAX_SIZE = 65_536 - OVERHEAD;
+
+// The extra bits that a <ul> tag wrapping would add to a message
+const UL_TAG_WRAP_SIZE = "<ul></ul>".length;
+const HTML_LIST_ITEM_EXTRA_SIZE = "<li></li>".length;
+const TEXT_LIST_ITEM_EXTRA_SIZE = " * \n".length;
+
+export class MessageListItem {
+    public html: string;
+    public text: string;
+
+    constructor(
+        html: string,
+        text: string,
+    ) {
+        if (html.length > (MAX_SIZE / 2)) {
+            throw new Error("HTML string too long for one item")
+        } else if (text.length > (MAX_SIZE / 2)) {
+            throw new Error("text string too long for one item")
+        }
+        this.html = html;
+        this.text = text;
+    }
+
+    public size(): number {
+        return this.html.length + HTML_LIST_ITEM_EXTRA_SIZE
+            + this.text.length + TEXT_LIST_ITEM_EXTRA_SIZE
+    }
+}
+
+export class MessageListHeader extends MessageListItem {
+    public size(): number {
+        return this.html.length + this.text.length
+    }
+}
+
+class MessageListing {
+    public items: MessageListItem[] = [];
+
+    constructor(public header: MessageListHeader | null) {
+    }
+
+    public split_at_size(desired_size: number): {sized: MessageListing | null, rest: MessageListing | null} {
+        if (this.size() <= desired_size) {
+            return {sized: this, rest: null};
+        } else {
+            let sized = new MessageListing(this.header);
+            if (sized.size() > desired_size) {
+                // If the header alone is too much, just give up.
+                return {sized: null, rest: this}
+            }
+
+            let rest = new MessageListing(null);
+            rest.items = [...this.items];
+
+            let current_item = rest.items.shift();
+
+            while (current_item !== undefined) {
+                // Add the new item tentatively
+                sized.items.push(current_item);
+
+                if (sized.size() > desired_size) {
+                    // If we went over the limit, return the last item and return the results
+                    rest.items.unshift(sized.items.pop()!)
+
+                    if (sized.items.length > 0) {
+                        return {sized, rest};
+                    } else {
+                        return {sized: null, rest}
+                    }
+                }
+
+                current_item = rest.items.shift();
+            }
+
+            // ??? We somehow did not go over the size limit when testing it per item?
+            // This is a weird state, as we should have already caught this with the
+            // `this.size() <= desired_size` conditional.
+            LogService.warn("ListMessageSplitter", `encountered end of while loop, required max ${desired_size} size, current item is ${sized.size()}`)
+
+            return {sized, rest: null}
+        }
+    }
+
+    public size(): number {
+        let with_header = this.header !== null ? this.header.size() + "\n".length + "<br>".length : 0;
+
+        return with_header
+            + (this.items.length > 0 ? UL_TAG_WRAP_SIZE : 0)
+            + this.items.reduce((prev, curr, _idx, _arr) => prev + curr.size(), 0);
+    }
+
+    public render(): MessageSnippet {
+        let current: MessageSnippet = {
+            html: "",
+            text: ""
+        };
+
+        for (let item of this.items) {
+            current.html += `<li>${item.html}</li>`
+            current.text += ` * ${item.text}\n`
+        }
+
+        current.html = this.items.length > 0 ? `<ul>${current.html}</ul>` : "";
+
+        if (this.header !== null) {
+            current.html = this.header.html + "<br>".length + current.html;
+            current.text = this.header.text + "\n" + current.text;
+        }
+
+        return current;
+    }
+}
+
+/// A class that allows splitting items and headers into multiple messages.
+export class ListMessageSplitter {
+    private items: (MessageListItem | MessageListHeader)[] = [];
+
+    constructor() {
+    }
+
+    public add_header(html: string, text: string) {
+        this.add(new MessageListHeader(html, text))
+    }
+
+    public add_paragraph(html: string, text: string) {
+        this.add(new MessageListItem(html, text))
+    }
+
+    public add(paragraph: MessageListItem | MessageListHeader) {
+        this.items.push(paragraph)
+    }
+
+    // Convert this.items into listings.
+    private get_listings(): MessageListing[] {
+        let current_listings: MessageListing[] = [];
+        let current_listing = new MessageListing(null);
+
+        for (let item of this.items) {
+            if (item instanceof MessageListHeader) {
+                if (current_listing.header !== null) {
+                    current_listings.push(current_listing);
+
+                    current_listing = new MessageListing(item);
+                } else {
+                    current_listing.header = item;
+                }
+            } else {
+                current_listing.items.push(item);
+            }
+        }
+
+        current_listings.push(current_listing);
+
+        return current_listings;
+    }
+
+    // Split the listings until they do not hit MAX_SIZE anymore.
+    private split_listings(listings: MessageListing[]): MessageListing[][] {
+        let result: MessageListing[][] = [];
+
+        let current: MessageListing[] = [];
+        let current_size = 0;
+
+        let listing: MessageListing | null;
+        for (listing of listings) {
+            while (listing !== null) {
+                let { sized, rest } = listing.split_at_size(MAX_SIZE - current_size);
+
+                if (sized !== null) {
+                    current.push(sized);
+                    current_size += sized.size()
+                } else {
+                    result.push(current);
+                    current = [];
+                    current_size = 0;
+                }
+
+                listing = rest;
+            }
+        }
+
+        result.push(current);
+
+        return result;
+    }
+
+    public render(): { html: string, text: string }[] {
+        let rendered: { html: string, text: string }[] = [];
+
+        let listings = this.get_listings();
+        let chunks = this.split_listings(listings);
+
+        for (let chunk of chunks) {
+            let current = {
+                html: "",
+                text: "",
+            }
+
+            for (let listing of chunk) {
+                let {html, text} = listing.render();
+                current.html += html;
+                current.text += text;
+            }
+
+            rendered.push(current)
+        }
+
+        return rendered;
+    }
+}
diff --git a/src/commands/DumpRulesCommand.ts b/src/commands/DumpRulesCommand.ts
index ca92e791..37fa2b07 100644
--- a/src/commands/DumpRulesCommand.ts
+++ b/src/commands/DumpRulesCommand.ts
@@ -18,6 +18,7 @@ import { RichReply } from "matrix-bot-sdk";
 import { Mjolnir } from "../Mjolnir";
 import { EntityType } from "../models/ListRule";
 import { htmlEscape } from "../utils";
+import { ListMessageSplitter } from "../ListMessageSplitter";
 
 /**
  * List all of the rules that match a given entity.
@@ -77,52 +78,73 @@ export async function execRulesMatchingCommand(roomId: string, event: any, mjoln
 
 // !mjolnir rules
 export async function execDumpRulesCommand(roomId: string, event: any, mjolnir: Mjolnir) {
-    let html = "<b>Rules currently in use:</b><br/>";
-    let text = "Rules currently in use:\n";
+    let splitter = new ListMessageSplitter();
+
+    splitter.add_header("<b>Rules currently in use:</b>", "Rules currently in use:");
 
-    let hasLists = false;
     for (const list of mjolnir.lists) {
-        hasLists = true;
         let hasRules = false;
 
         const shortcodeInfo = list.listShortcode ? ` (shortcode: ${list.listShortcode})` : '';
 
-        html += `<a href="${list.roomRef}">${list.roomId}</a>${shortcodeInfo}:<br/><ul>`;
-        text += `${list.roomRef}${shortcodeInfo}:\n`;
+        splitter.add_header(`<a href="${list.roomRef}">${list.roomId}</a>${shortcodeInfo}:`, `${list.roomRef}${shortcodeInfo}:`);
 
         for (const rule of list.serverRules) {
             hasRules = true;
-            html += `<li>server (<code>${rule.recommendation}</code>): <code>${htmlEscape(rule.entity)}</code> (${htmlEscape(rule.reason)})</li>`;
-            text += `* server (${rule.recommendation}): ${rule.entity} (${rule.reason})\n`;
+
+            splitter.add_paragraph(
+                `server (<code>${rule.recommendation}</code>): <code>${htmlEscape(rule.entity)}</code> (${htmlEscape(rule.reason)})`,
+                `server (${rule.recommendation}): ${rule.entity} (${rule.reason})`
+            )
         }
 
         for (const rule of list.userRules) {
             hasRules = true;
-            html += `<li>user (<code>${rule.recommendation}</code>): <code>${htmlEscape(rule.entity)}</code> (${htmlEscape(rule.reason)})</li>`;
-            text += `* user (${rule.recommendation}): ${rule.entity} (${rule.reason})\n`;
+
+            splitter.add_paragraph(
+                `user (<code>${rule.recommendation}</code>): <code>${htmlEscape(rule.entity)}</code> (${htmlEscape(rule.reason)})`,
+                `user (${rule.recommendation}): ${rule.entity} (${rule.reason})`
+            )
         }
 
         for (const rule of list.roomRules) {
             hasRules = true;
-            html += `<li>room (<code>${rule.recommendation}</code>): <code>${htmlEscape(rule.entity)}</code> (${htmlEscape(rule.reason)})</li>`;
-            text += `* room (${rule.recommendation}): ${rule.entity} (${rule.reason})\n`;
+
+            splitter.add_paragraph(
+                `room (<code>${rule.recommendation}</code>): <code>${htmlEscape(rule.entity)}</code> (${htmlEscape(rule.reason)})`,
+                `room (${rule.recommendation}): ${rule.entity} (${rule.reason})`
+            )
         }
 
         if (!hasRules) {
-            html += "<li><i>No rules</i>";
-            text += "* No rules\n";
+            splitter.add_paragraph(
+                "<i>No rules</i>",
+                "No rules"
+            )
         }
-
-        html += "</ul>";
-        text += "\n";
     }
 
-    if (!hasLists) {
-        html = "No ban lists configured";
-        text = "No ban lists configured";
+    if (mjolnir.lists.length === 0) {
+        splitter.add_paragraph(
+            "No ban lists configured",
+            "No ban lists configured"
+        )
     }
 
-    const reply = RichReply.createFor(roomId, event, text, html);
+    let rendered = splitter.render();
+    let first = rendered.shift()!;
+
+    const reply = RichReply.createFor(roomId, event, first.text, first.html);
     reply["msgtype"] = "m.notice";
-    return mjolnir.client.sendMessage(roomId, reply);
+
+    await mjolnir.client.sendMessage(roomId, reply);
+
+    for (const message of rendered) {
+        await mjolnir.client.sendMessage(roomId, {
+            msgtype: "m.notice",
+            body: message.text,
+            format: "org.matrix.custom.html",
+            formatted_body: message.html,
+        });
+    }
 }

From 59a720d4c1a34b2bb91ac6191cac6176967735a8 Mon Sep 17 00:00:00 2001
From: Jonathan de Jong <jonathan@automatia.nl>
Date: Sat, 8 Oct 2022 10:51:04 +0200
Subject: [PATCH 2/3] Adress review feedback

- added documentation
- moved sending to splitter function
---
 src/ListMessageSplitter.ts       | 118 ++++++++++++++++++++++++++++---
 src/commands/DumpRulesCommand.ts |  17 +----
 2 files changed, 111 insertions(+), 24 deletions(-)

diff --git a/src/ListMessageSplitter.ts b/src/ListMessageSplitter.ts
index 4a6da6a1..aebccbb7 100644
--- a/src/ListMessageSplitter.ts
+++ b/src/ListMessageSplitter.ts
@@ -1,19 +1,78 @@
-import {LogService} from "matrix-bot-sdk";
+/*
+    The list splitter is meant to help with large itemized messages (such as a ban list),
+    which each have "headers" (bits of text that introduce the list).
 
+    The behaviour is such that one pumps items and headers one-by-one into ListMessageSplitter,
+    which then splits them internally to accomodate maximum matrix event sizes, and renders them simultaniously.
+
+    As such, a workflow with ListMessageSplitter would look something like this;
+
+    ```js
+    let splitter = new ListMessageSplitter();
+
+    // Start a new list, input both html and text versions of the header.
+    splitter.add_header("<b>Rules currently in use:</b>", "Rules currently in use:");
+
+    for (rule of this.rules) {
+      // Add a new "paragraph", an item, se string templates here for each item.
+      splitter.add_paragraph(
+        `rule <code>#${rule.number}</code>: ${rule.text()}`,
+        `rule #${rule.number}: ${rule.text()}`
+      )
+    }
+
+    if (this.rules.length === 0) {
+        splitter.add_paragraph(
+            "No rules configured",
+            "No rules configured"
+        )
+    }
+
+    // Add another header, start a new list in the same message.
+    splitter.add_header("<b>Servers currently observed:</b>", "Servers currently observed:");
+
+    for (server of this.servers) {
+      splitter.add_paragraph(
+        `server ${server.name()}`,
+        `server ${server.name()}`
+      )
+    }
+
+    if (this.servers.length === 0) {
+        splitter.add_paragraph(
+            "No servers observed",
+            "No servers observed"
+        )
+    }
+
+    // Reply to an event with the whole deal, splitting into multiple messages as needed.
+    splitter.reply(mjolnir.client, roomId, event, true)
+    ```
+*/
+
+import {LogService, MatrixClient, RichReply} from "matrix-bot-sdk";
+
+// Helper type for html + text tuples.
 export type MessageSnippet = { html: string, text: string };
 
 // The max size a message can be, with 24_000 picked at random to accommodate for overhead.
+//
+// Note: This amount was checked through trial and error, a conservative estimate would be
+// 65_536 / 2, though this author does not know overhead estimates of matrix E2EE.
 const OVERHEAD = 24_000
 const MAX_SIZE = 65_536 - OVERHEAD;
 
 // The extra bits that a <ul> tag wrapping would add to a message
 const UL_TAG_WRAP_SIZE = "<ul></ul>".length;
+// The extra bits that a <il> list tag wrapping would add to a message
 const HTML_LIST_ITEM_EXTRA_SIZE = "<li></li>".length;
+// The extra bits that listification of plaintext items would add to a message.
 const TEXT_LIST_ITEM_EXTRA_SIZE = " * \n".length;
 
+// An "Item" object to push into the list splitter.
 export class MessageListItem {
-    public html: string;
-    public text: string;
+    public readonly html: string;
+    public readonly text: string;
 
     constructor(
         html: string,
@@ -34,35 +93,56 @@ export class MessageListItem {
     }
 }
 
+// A "header" object to push into the list splitter.
 export class MessageListHeader extends MessageListItem {
     public size(): number {
         return this.html.length + this.text.length
     }
 }
 
+// An internal helper class to hold a series of items, together with an optional header.
+//
+// Mainly provides a coherent split_at_size function that would allow for on-demand-sized splitting of
+// listings with headers.
 class MessageListing {
     public items: MessageListItem[] = [];
 
     constructor(public header: MessageListHeader | null) {
     }
 
+    // Attempts to split this listing into a `sized` and `rest` listing.
+    //
+    // Returns:
+    // `sized` != null, if sized was adequate, or had to be split
+    // `rest` != null, if sized was not adequate (and had to be split),
+    //   or the first item is too big to be split at the desired size.
     public split_at_size(desired_size: number): {sized: MessageListing | null, rest: MessageListing | null} {
         if (this.size() <= desired_size) {
+            // If the current listing is under the desired size, just return it, rest = null.
             return {sized: this, rest: null};
         } else {
+            // Else, split it.
+
+            // Create a new listing with just the current header,
+            // as a candidate for the new sized listing.
             let sized = new MessageListing(this.header);
             if (sized.size() > desired_size) {
                 // If the header alone is too much, just give up.
                 return {sized: null, rest: this}
             }
 
+            // Create another listing, and dump the rest of all items in there.
             let rest = new MessageListing(null);
+            // Be sure to shallow copy, to not disturb the `this` listing.
             rest.items = [...this.items];
 
+            // Perform initial shift of item into a variable.
             let current_item = rest.items.shift();
 
+            // Keep looping while there are still items left.
+            // (Replaced at the end of the loop)
             while (current_item !== undefined) {
-                // Add the new item tentatively
+                // Add the new item to `sized` tentatively.
                 sized.items.push(current_item);
 
                 if (sized.size() > desired_size) {
@@ -72,6 +152,7 @@ class MessageListing {
                     if (sized.items.length > 0) {
                         return {sized, rest};
                     } else {
+                        // If this was the first item, `sized` is empty, return null.
                         return {sized: null, rest}
                     }
                 }
@@ -96,6 +177,7 @@ class MessageListing {
             + this.items.reduce((prev, curr, _idx, _arr) => prev + curr.size(), 0);
     }
 
+    // Render this listing into a messagesnippet.
     public render(): MessageSnippet {
         let current: MessageSnippet = {
             html: "",
@@ -118,7 +200,7 @@ class MessageListing {
     }
 }
 
-/// A class that allows splitting items and headers into multiple messages.
+// A class that allows splitting items and headers into multiple messages.
 export class ListMessageSplitter {
     private items: (MessageListItem | MessageListHeader)[] = [];
 
@@ -191,14 +273,14 @@ export class ListMessageSplitter {
         return result;
     }
 
-    public render(): { html: string, text: string }[] {
-        let rendered: { html: string, text: string }[] = [];
+    public render(): MessageSnippet[] {
+        let rendered: MessageSnippet[] = [];
 
         let listings = this.get_listings();
         let chunks = this.split_listings(listings);
 
         for (let chunk of chunks) {
-            let current = {
+            let current: MessageSnippet = {
                 html: "",
                 text: "",
             }
@@ -214,4 +296,24 @@ export class ListMessageSplitter {
 
         return rendered;
     }
+
+    public async reply(client: MatrixClient, roomId: string, toEvent: any, m_notice: boolean) {
+        let rendered = this.render();
+        let first = rendered.shift()!;
+
+        const reply = RichReply.createFor(roomId, toEvent, first.text, first.html);
+        if (m_notice)
+            reply["msgtype"] = "m.notice";
+
+        await client.sendMessage(roomId, reply);
+
+        for (const message of rendered) {
+            await client.sendMessage(roomId, {
+                msgtype: m_notice ? "m.notice" : "m.text",
+                body: message.text,
+                format: "org.matrix.custom.html",
+                formatted_body: message.html,
+            });
+        }
+    }
 }
diff --git a/src/commands/DumpRulesCommand.ts b/src/commands/DumpRulesCommand.ts
index 37fa2b07..031713fd 100644
--- a/src/commands/DumpRulesCommand.ts
+++ b/src/commands/DumpRulesCommand.ts
@@ -131,20 +131,5 @@ export async function execDumpRulesCommand(roomId: string, event: any, mjolnir:
         )
     }
 
-    let rendered = splitter.render();
-    let first = rendered.shift()!;
-
-    const reply = RichReply.createFor(roomId, event, first.text, first.html);
-    reply["msgtype"] = "m.notice";
-
-    await mjolnir.client.sendMessage(roomId, reply);
-
-    for (const message of rendered) {
-        await mjolnir.client.sendMessage(roomId, {
-            msgtype: "m.notice",
-            body: message.text,
-            format: "org.matrix.custom.html",
-            formatted_body: message.html,
-        });
-    }
+    await splitter.reply(mjolnir.client, roomId, event, true);
 }

From c56eb420d688984d4e2f5718c0a75a5d6a71ec0d Mon Sep 17 00:00:00 2001
From: Jonathan de Jong <jonathan@automatia.nl>
Date: Sat, 15 Oct 2022 20:08:37 +0200
Subject: [PATCH 3/3] Adress review feedback

---
 src/ListMessageSplitter.ts       | 220 ++++++++++++++++++-------------
 src/commands/DumpRulesCommand.ts |  14 +-
 2 files changed, 139 insertions(+), 95 deletions(-)

diff --git a/src/ListMessageSplitter.ts b/src/ListMessageSplitter.ts
index aebccbb7..a0bf207f 100644
--- a/src/ListMessageSplitter.ts
+++ b/src/ListMessageSplitter.ts
@@ -1,4 +1,4 @@
-/*
+/**
     The list splitter is meant to help with large itemized messages (such as a ban list),
     which each have "headers" (bits of text that introduce the list).
 
@@ -8,7 +8,7 @@
     As such, a workflow with ListMessageSplitter would look something like this;
 
     ```js
-    let splitter = new ListMessageSplitter();
+    const splitter = new ListMessageSplitter();
 
     // Start a new list, input both html and text versions of the header.
     splitter.add_header("<b>Rules currently in use:</b>", "Rules currently in use:");
@@ -50,17 +50,20 @@
     ```
 */
 
-import {LogService, MatrixClient, RichReply} from "matrix-bot-sdk";
+import {MatrixClient, RichReply} from "matrix-bot-sdk";
 
 // Helper type for html + text tuples.
 export type MessageSnippet = { html: string, text: string };
 
 // The max size a message can be, with 24_000 picked at random to accommodate for overhead.
-//
+
 // Note: This amount was checked through trial and error, a conservative estimate would be
 // 65_536 / 2, though this author does not know overhead estimates of matrix E2EE.
-const OVERHEAD = 24_000
-const MAX_SIZE = 65_536 - OVERHEAD;
+
+// The overhead from E2EE.
+export const OVERHEAD = 24_000
+// The max size a message can be.
+export const MAX_SIZE = 65_536 - OVERHEAD;
 
 // The extra bits that a <ul> tag wrapping would add to a message
 const UL_TAG_WRAP_SIZE = "<ul></ul>".length;
@@ -69,7 +72,11 @@ const HTML_LIST_ITEM_EXTRA_SIZE = "<li></li>".length;
 // The extra bits that listification of plaintext items would add to a message.
 const TEXT_LIST_ITEM_EXTRA_SIZE = " * \n".length;
 
-// An "Item" object to push into the list splitter.
+/**
+ * An "Item" object to push into the list splitter.
+ *
+ * Note: `html` and `text` must collectively not exceed MAX_SIZE.
+ */
 export class MessageListItem {
     public readonly html: string;
     public readonly text: string;
@@ -78,46 +85,56 @@ export class MessageListItem {
         html: string,
         text: string,
     ) {
-        if (html.length > (MAX_SIZE / 2)) {
-            throw new Error("HTML string too long for one item")
-        } else if (text.length > (MAX_SIZE / 2)) {
-            throw new Error("text string too long for one item")
-        }
+        if ((html.length + text.length) > MAX_SIZE)
+            throw new Error("HTML + text string size too large for one item")
         this.html = html;
         this.text = text;
     }
 
+    /**
+     * The total size of this list item, were it to be rendered.
+     */
     public size(): number {
         return this.html.length + HTML_LIST_ITEM_EXTRA_SIZE
             + this.text.length + TEXT_LIST_ITEM_EXTRA_SIZE
     }
 }
 
-// A "header" object to push into the list splitter.
+/**
+ * A "header" object to push into the list splitter.
+ */
 export class MessageListHeader extends MessageListItem {
     public size(): number {
         return this.html.length + this.text.length
     }
 }
 
-// An internal helper class to hold a series of items, together with an optional header.
-//
-// Mainly provides a coherent split_at_size function that would allow for on-demand-sized splitting of
-// listings with headers.
+/**
+ * An internal helper class to hold a series of items, together with an optional header.
+ *
+ * Mainly provides a coherent split_at_size function that would allow for on-demand-sized splitting of
+ * listings with headers.
+ */
 class MessageListing {
     public items: MessageListItem[] = [];
 
-    constructor(public header: MessageListHeader | null) {
+    constructor(public readonly header: MessageListHeader | null) {
     }
 
-    // Attempts to split this listing into a `sized` and `rest` listing.
-    //
-    // Returns:
-    // `sized` != null, if sized was adequate, or had to be split
-    // `rest` != null, if sized was not adequate (and had to be split),
-    //   or the first item is too big to be split at the desired size.
-    public split_at_size(desired_size: number): {sized: MessageListing | null, rest: MessageListing | null} {
-        if (this.size() <= desired_size) {
+    /**
+     * Attempts to split this listing into a `sized` and `rest` listing.
+     *
+     * @param desiredSize The desired max size to try to fit this listing in.
+     * @returns "sized" and "rest".
+     *
+     *  "sized" will be non-null either if the current listing fits entirely within the desired size,
+     *  or if it could be split to a desired size. Non-null "sized" is always within the desired size.
+     *
+     *  "rest" will be non-null with either the "rest" of the listing (after sized has been split),
+     *  or a copy of the current listing (if sized couldn't be made fit to the desired size).
+     */
+    public splitAtSize(desiredSize: number): {sized: MessageListing | null, rest: MessageListing | null} {
+        if (this.size() <= desiredSize) {
             // If the current listing is under the desired size, just return it, rest = null.
             return {sized: this, rest: null};
         } else {
@@ -125,27 +142,27 @@ class MessageListing {
 
             // Create a new listing with just the current header,
             // as a candidate for the new sized listing.
-            let sized = new MessageListing(this.header);
-            if (sized.size() > desired_size) {
+            const sized = new MessageListing(this.header);
+            if (sized.size() > desiredSize) {
                 // If the header alone is too much, just give up.
                 return {sized: null, rest: this}
             }
 
             // Create another listing, and dump the rest of all items in there.
-            let rest = new MessageListing(null);
+            const rest = new MessageListing(null);
             // Be sure to shallow copy, to not disturb the `this` listing.
             rest.items = [...this.items];
 
             // Perform initial shift of item into a variable.
-            let current_item = rest.items.shift();
+            let currentItem = rest.items.shift();
 
             // Keep looping while there are still items left.
             // (Replaced at the end of the loop)
-            while (current_item !== undefined) {
+            while (currentItem !== undefined) {
                 // Add the new item to `sized` tentatively.
-                sized.items.push(current_item);
+                sized.items.push(currentItem);
 
-                if (sized.size() > desired_size) {
+                if (sized.size() > desiredSize) {
                     // If we went over the limit, return the last item and return the results
                     rest.items.unshift(sized.items.pop()!)
 
@@ -157,34 +174,42 @@ class MessageListing {
                     }
                 }
 
-                current_item = rest.items.shift();
+                currentItem = rest.items.shift();
             }
 
             // ??? We somehow did not go over the size limit when testing it per item?
             // This is a weird state, as we should have already caught this with the
-            // `this.size() <= desired_size` conditional.
-            LogService.warn("ListMessageSplitter", `encountered end of while loop, required max ${desired_size} size, current item is ${sized.size()}`)
+            // `this.size() <= desiredSize` conditional.
 
-            return {sized, rest: null}
+            // There is one situation where this can happen, and that is if this.items is empty.
+            if (this.items.length !== 0)
+                throw new Error(`Undefined state: encountered end of while loop while this.items is non-empty`)
+            else
+                return {sized, rest: null}
         }
     }
 
+    /**
+     * The complete size of this listing. (if it were to be rendered)
+     */
     public size(): number {
-        let with_header = this.header !== null ? this.header.size() + "\n".length + "<br>".length : 0;
+        const withHeader = this.header !== null ? this.header.size() + "\n".length + "<br>".length : 0;
 
-        return with_header
+        return withHeader
             + (this.items.length > 0 ? UL_TAG_WRAP_SIZE : 0)
-            + this.items.reduce((prev, curr, _idx, _arr) => prev + curr.size(), 0);
+            + this.items.reduce((prev, curr) => prev + curr.size(), 0);
     }
 
-    // Render this listing into a messagesnippet.
+    /**
+     * Render this listing into a MessageSnippet.
+     */
     public render(): MessageSnippet {
-        let current: MessageSnippet = {
+        const current: MessageSnippet = {
             html: "",
             text: ""
         };
 
-        for (let item of this.items) {
+        for (const item of this.items) {
             current.html += `<li>${item.html}</li>`
             current.text += ` * ${item.text}\n`
         }
@@ -200,68 +225,75 @@ class MessageListing {
     }
 }
 
-// A class that allows splitting items and headers into multiple messages.
+/**
+ * A class that allows splitting items and headers into multiple messages.
+ */
 export class ListMessageSplitter {
-    private items: (MessageListItem | MessageListHeader)[] = [];
+    private listings: MessageListing[] = [];
 
     constructor() {
     }
 
-    public add_header(html: string, text: string) {
+    /**
+     * Add a header to start a listing with, to be followed up with paragraphs/items of text.
+     *
+     * @param html The HTML that the header consists of.
+     * @param text The "fallback" text that the header consists of.
+     */
+    public addHeader(html: string, text: string) {
         this.add(new MessageListHeader(html, text))
     }
 
-    public add_paragraph(html: string, text: string) {
+    /**
+     * Add a paragraph of text to the current latest listing, this will be itemized.
+     *
+     * @param html The HTML that the paragraph consists of.
+     * @param text The "fallback" text that the paragraph consists of.
+     */
+    public addParagraph(html: string, text: string) {
         this.add(new MessageListItem(html, text))
     }
 
-    public add(paragraph: MessageListItem | MessageListHeader) {
-        this.items.push(paragraph)
-    }
-
-    // Convert this.items into listings.
-    private get_listings(): MessageListing[] {
-        let current_listings: MessageListing[] = [];
-        let current_listing = new MessageListing(null);
-
-        for (let item of this.items) {
-            if (item instanceof MessageListHeader) {
-                if (current_listing.header !== null) {
-                    current_listings.push(current_listing);
-
-                    current_listing = new MessageListing(item);
-                } else {
-                    current_listing.header = item;
-                }
+    /**
+     * Add a single "item" to the current listings.
+     *
+     * This method is not recommended for easy use, use addHeader or addParagraph instead.
+     *
+     * @param item The listing item to add, either a header or a list item.
+     */
+    public add(item: MessageListItem | MessageListHeader) {
+        if (item instanceof MessageListHeader) {
+            this.listings.push(new MessageListing(item))
+        } else {
+            if (this.listings.length === 0) {
+                const listing = new MessageListing(null);
+                listing.items.push(item);
+                this.listings.push(listing);
             } else {
-                current_listing.items.push(item);
+                this.listings[-1].items.push(item)
             }
         }
-
-        current_listings.push(current_listing);
-
-        return current_listings;
     }
 
     // Split the listings until they do not hit MAX_SIZE anymore.
-    private split_listings(listings: MessageListing[]): MessageListing[][] {
-        let result: MessageListing[][] = [];
+    private splitListings(listings: MessageListing[]): MessageListing[][] {
+        const result: MessageListing[][] = [];
 
         let current: MessageListing[] = [];
-        let current_size = 0;
+        let currentSize = 0;
 
         let listing: MessageListing | null;
         for (listing of listings) {
             while (listing !== null) {
-                let { sized, rest } = listing.split_at_size(MAX_SIZE - current_size);
+                let { sized, rest } = listing.splitAtSize(MAX_SIZE - currentSize);
 
                 if (sized !== null) {
                     current.push(sized);
-                    current_size += sized.size()
+                    currentSize += sized.size()
                 } else {
                     result.push(current);
                     current = [];
-                    current_size = 0;
+                    currentSize = 0;
                 }
 
                 listing = rest;
@@ -273,20 +305,23 @@ export class ListMessageSplitter {
         return result;
     }
 
+    /**
+     * Render the current listings inside the splitter into a series of message (html and text)
+     * snippets to be posted to the room.
+     */
     public render(): MessageSnippet[] {
-        let rendered: MessageSnippet[] = [];
+        const rendered: MessageSnippet[] = [];
 
-        let listings = this.get_listings();
-        let chunks = this.split_listings(listings);
+        const chunks = this.splitListings(this.listings);
 
-        for (let chunk of chunks) {
-            let current: MessageSnippet = {
+        for (const chunk of chunks) {
+            const current: MessageSnippet = {
                 html: "",
                 text: "",
             }
 
-            for (let listing of chunk) {
-                let {html, text} = listing.render();
+            for (const listing of chunk) {
+                const {html, text} = listing.render();
                 current.html += html;
                 current.text += text;
             }
@@ -297,19 +332,28 @@ export class ListMessageSplitter {
         return rendered;
     }
 
-    public async reply(client: MatrixClient, roomId: string, toEvent: any, m_notice: boolean) {
-        let rendered = this.render();
-        let first = rendered.shift()!;
+    /**
+     * Render the current listings, and reply to a message with the first message,
+     * posting the following messages in the room as-is.
+     *
+     * @param client The matrix client with which to send these messages.
+     * @param roomId The room to respond into.
+     * @param toEvent The event to reply to.
+     * @param mNotice Whether or not these messages should be m.notice or not.
+     */
+    public async reply(client: MatrixClient, roomId: string, toEvent: any, mNotice: boolean) {
+        const rendered = this.render();
+        const first = rendered.shift()!;
 
         const reply = RichReply.createFor(roomId, toEvent, first.text, first.html);
-        if (m_notice)
+        if (mNotice)
             reply["msgtype"] = "m.notice";
 
         await client.sendMessage(roomId, reply);
 
         for (const message of rendered) {
             await client.sendMessage(roomId, {
-                msgtype: m_notice ? "m.notice" : "m.text",
+                msgtype: mNotice ? "m.notice" : "m.text",
                 body: message.text,
                 format: "org.matrix.custom.html",
                 formatted_body: message.html,
diff --git a/src/commands/DumpRulesCommand.ts b/src/commands/DumpRulesCommand.ts
index 031713fd..1f7aded7 100644
--- a/src/commands/DumpRulesCommand.ts
+++ b/src/commands/DumpRulesCommand.ts
@@ -80,19 +80,19 @@ export async function execRulesMatchingCommand(roomId: string, event: any, mjoln
 export async function execDumpRulesCommand(roomId: string, event: any, mjolnir: Mjolnir) {
     let splitter = new ListMessageSplitter();
 
-    splitter.add_header("<b>Rules currently in use:</b>", "Rules currently in use:");
+    splitter.addHeader("<b>Rules currently in use:</b>", "Rules currently in use:");
 
     for (const list of mjolnir.lists) {
         let hasRules = false;
 
         const shortcodeInfo = list.listShortcode ? ` (shortcode: ${list.listShortcode})` : '';
 
-        splitter.add_header(`<a href="${list.roomRef}">${list.roomId}</a>${shortcodeInfo}:`, `${list.roomRef}${shortcodeInfo}:`);
+        splitter.addHeader(`<a href="${list.roomRef}">${list.roomId}</a>${shortcodeInfo}:`, `${list.roomRef}${shortcodeInfo}:`);
 
         for (const rule of list.serverRules) {
             hasRules = true;
 
-            splitter.add_paragraph(
+            splitter.addParagraph(
                 `server (<code>${rule.recommendation}</code>): <code>${htmlEscape(rule.entity)}</code> (${htmlEscape(rule.reason)})`,
                 `server (${rule.recommendation}): ${rule.entity} (${rule.reason})`
             )
@@ -101,7 +101,7 @@ export async function execDumpRulesCommand(roomId: string, event: any, mjolnir:
         for (const rule of list.userRules) {
             hasRules = true;
 
-            splitter.add_paragraph(
+            splitter.addParagraph(
                 `user (<code>${rule.recommendation}</code>): <code>${htmlEscape(rule.entity)}</code> (${htmlEscape(rule.reason)})`,
                 `user (${rule.recommendation}): ${rule.entity} (${rule.reason})`
             )
@@ -110,14 +110,14 @@ export async function execDumpRulesCommand(roomId: string, event: any, mjolnir:
         for (const rule of list.roomRules) {
             hasRules = true;
 
-            splitter.add_paragraph(
+            splitter.addParagraph(
                 `room (<code>${rule.recommendation}</code>): <code>${htmlEscape(rule.entity)}</code> (${htmlEscape(rule.reason)})`,
                 `room (${rule.recommendation}): ${rule.entity} (${rule.reason})`
             )
         }
 
         if (!hasRules) {
-            splitter.add_paragraph(
+            splitter.addParagraph(
                 "<i>No rules</i>",
                 "No rules"
             )
@@ -125,7 +125,7 @@ export async function execDumpRulesCommand(roomId: string, event: any, mjolnir:
     }
 
     if (mjolnir.lists.length === 0) {
-        splitter.add_paragraph(
+        splitter.addParagraph(
             "No ban lists configured",
             "No ban lists configured"
         )