From 44ff69c4d06c45201ce4e42435e899a2ea73b4e1 Mon Sep 17 00:00:00 2001
From: 1AhmedYasser <26207361+1AhmedYasser@users.noreply.github.com>
Date: Fri, 13 Feb 2026 15:19:53 +0200
Subject: [PATCH] chore(617): Maintain citations order

---
 lib/helpers.ts | 116 ++++++++++++++++++++++++++-----------------------
 1 file changed, 62 insertions(+), 54 deletions(-)

diff --git a/lib/helpers.ts b/lib/helpers.ts
index 94bae0b..9948566 100644
--- a/lib/helpers.ts
+++ b/lib/helpers.ts
@@ -510,6 +510,37 @@ function getUniqueCitationsAndMapping(citations: { url: string; title: string; f
   return { uniqueCitations, originalDocToUniqueDoc };
 }
 
+function toSuperscript(num: number, superscriptMap: string): string {
+  return String(num)
+    .split('')
+    .map((digit) => superscriptMap[Number(digit)])
+    .join('');
+}
+
+function buildLinkLine(
+  displayNum: number,
+  citation: { url: string; title: string; filepath: string },
+  superscriptMap: string,
+): string {
+  const linkLabel = toSuperscript(displayNum, superscriptMap);
+  try {
+    const parsedUrl = JSON.parse(citation.url).join('\\n');
+    return `  • ${linkLabel} [${citation.title}](${citation.filepath})\\n- ${parsedUrl}\\n\\n`;
+  } catch {
+    try {
+      new URL(citation.url);
+      return `  • ${linkLabel} [${citation.title}](${citation.filepath})\\n- ${citation.url}\\n\\n`;
+    } catch {
+      try {
+        new URL(citation.filepath);
+        return `  • ${linkLabel} [${citation.title}](${citation.filepath})`;
+      } catch {
+        return '';
+      }
+    }
+  }
+}
+
 export function replaceDocs(
   content: string,
   context: { citations?: { url: string; title: string; filepath: string }[] },
@@ -518,69 +549,46 @@ export function replaceDocs(
 
   const { uniqueCitations, originalDocToUniqueDoc } = getUniqueCitationsAndMapping(context.citations);
 
-  let replacedContent = content;
-
-  originalDocToUniqueDoc.forEach((uniqueDocIndex, originalDocNum) => {
-    const uniqueDocNum = uniqueDocIndex + 1;
-
-    if (uniqueDocNum !== originalDocNum) {
-      const originalKey = `[doc${originalDocNum}]`;
-      const uniqueKey = `[doc${uniqueDocNum}]`;
-
-      if (replacedContent.includes(originalKey)) {
-        replacedContent = replacedContent.replaceAll(originalKey, uniqueKey);
-      }
+  const appearanceOrder: number[] = [];
+  const seenUnique = new Set<number>();
+  const docRefRegex = /\[doc(\d+)\]/g;
+  let match: RegExpExecArray | null;
+  while ((match = docRefRegex.exec(content)) !== null) {
+    const originalDocNum = Number(match[1]);
+    const uniqueIndex = originalDocToUniqueDoc.get(originalDocNum);
+    if (uniqueIndex === undefined) continue;
+    if (!seenUnique.has(uniqueIndex)) {
+      seenUnique.add(uniqueIndex);
+      appearanceOrder.push(uniqueIndex);
     }
+  }
+
+  const uniqueIndexToDisplayNum = new Map<number, number>();
+  appearanceOrder.forEach((uniqueIndex, i) => {
+    uniqueIndexToDisplayNum.set(uniqueIndex, i + 1);
   });
 
-  const links: string[] = [];
   const superscriptMap = '⁰¹²³⁴⁵⁶⁷⁸⁹';
+  let replacedContent = content;
 
-  uniqueCitations.forEach((uniqueItem, uniqueIndex) => {
-    const uniqueDocNum = uniqueIndex + 1;
-    const docKey = `[doc${uniqueDocNum}]`;
-
+  originalDocToUniqueDoc.forEach((uniqueIndex, originalDocNum) => {
+    const displayNum = uniqueIndexToDisplayNum.get(uniqueIndex);
+    if (displayNum === undefined) return;
+    const docKey = `[doc${originalDocNum}]`;
+    const linkLabel = toSuperscript(displayNum, superscriptMap);
     if (replacedContent.includes(docKey)) {
-      try {
-        const parsedUrl = JSON.parse(uniqueItem.citation.url).join('\\n');
-        let linkLabel = String(uniqueDocNum)
-          .split('')
-          .map((digit) => superscriptMap[Number(digit)])
-          .join('');
-        replacedContent = replacedContent.replaceAll(docKey, `⁽${linkLabel}⁾`);
-        links.push(
-          `  • ${linkLabel} [${uniqueItem.citation.title}](${uniqueItem.citation.filepath})\\n- ${parsedUrl}\\n\\n`,
-        );
-      } catch (error) {
-        console.error('Error parsing URL as JSON array:', error);
-        try {
-          new URL(uniqueItem.citation.url);
-          let linkLabel = String(uniqueDocNum)
-            .split('')
-            .map((digit) => superscriptMap[Number(digit)])
-            .join('');
-          replacedContent = replacedContent.replaceAll(docKey, `⁽${linkLabel}⁾`);
-          links.push(
-            `  • ${linkLabel} [${uniqueItem.citation.title}](${uniqueItem.citation.filepath})\\n- ${uniqueItem.citation.url}\\n\\n`,
-          );
-        } catch (error) {
-          console.error('Error parsing URL as JSON array:', error);
-          try {
-            new URL(uniqueItem.citation.filepath);
-            let linkLabel = String(uniqueDocNum)
-              .split('')
-              .map((digit) => superscriptMap[Number(digit)])
-              .join('');
-            replacedContent = replacedContent.replaceAll(docKey, `⁽${linkLabel}⁾`);
-            links.push(`  • ${linkLabel} [${uniqueItem.citation.title}](${uniqueItem.citation.filepath})`);
-          } catch {
-            replacedContent = replacedContent.replaceAll(docKey, '');
-          }
-        }
-      }
+      replacedContent = replacedContent.replaceAll(docKey, `⁽${linkLabel}⁾`);
     }
   });
 
+  const links: string[] = [];
+  for (let i = 0; i < appearanceOrder.length; i++) {
+    const uniqueIndex = appearanceOrder[i];
+    const displayNum = i + 1;
+    const line = buildLinkLine(displayNum, uniqueCitations[uniqueIndex].citation, superscriptMap);
+    if (line) links.push(line);
+  }
+
   replacedContent = replacedContent
     .replaceAll('\n', '\\n')
     .replaceAll('"', '\"')