feat: add comments and improve decensor performance

Author: envico801

src/format.ts

@@ -134,13 +134,29 @@ export class FormatConverter {
 		return [note_text.replace(regexp, mask), matches]
 	}
 
-	decensor(note_text: string, mask: string, replacements: string[], escape: boolean): string {
-		let i = 0;
-		return note_text.replace(new RegExp(mask, 'g'), (): string => {
-			let replacement: string = replacements[i++];
-			return escape ? escapeHtml(replacement) : replacement;
-		});
-	}
+  decensor(note_text: string, mask: string, replacements: string[], escape: boolean): string {
+    let index = 0;
+
+    // note_text example: "The OBSTOANKICODEDISPLAY is worth OBSTOANKICODEDISPLAY today"
+    // maskGlobalReg example: /OBSTOANKICODEDISPLAY/g
+    const maskGlobalRegex = new RegExp(mask, 'g');
+
+    const matchCount = (note_text.match(maskGlobalRegex) || []).length;
+
+    // Validate that we have exactly enough replacements
+    if (matchCount !== replacements.length) {
+      throw new Error(`Mismatch between placeholders (${matchCount}) and replacements (${replacements.length})`);
+    }
+
+    // replacements example: ["10", "15"]
+    note_text = note_text.replace(maskGlobalRegex, () => {
+      const replacement = replacements[index++];
+      return escape ? escapeHtml(replacement) : replacement;
+    });
+
+    // note_text expected: "The 10 is worth 15 today"
+    return note_text;
+  }
 
 	format(note_text: string, cloze: boolean, highlights_to_cloze: boolean): string {
 		note_text = this.obsidian_to_anki_math(note_text)