feat(ui): add Markdown processing functions and corresponding tests for node card descriptions

gemmadlou · gemmadlou · commit 6d9b393588ba · 2026-03-29T14:45:53.000+02:00
diff --git a/ui-graph/src/domain.test.ts b/ui-graph/src/domain.test.ts
@@ -1,7 +1,63 @@
 import { describe, expect, test } from 'bun:test';
-import { createNodeDomain, DEFAULT_PRIORITY, DONE_STATUS_ID } from './domain.js';
+import {
+    createNodeDomain,
+    DEFAULT_PRIORITY,
+    DONE_STATUS_ID,
+    lineBreaksToFullStops,
+    markdownSyntaxToPlainText,
+    truncatePlainDescriptionForNodeCard
+} from './domain.js';
 import type { CyNodeData } from './graphDataTypes.js';
 
+describe('markdownSyntaxToPlainText', () => {
+    test('bare bracket label becomes plain text', () => {
+        expect(markdownSyntaxToPlainText('[thing abc]')).toBe('thing abc');
+    });
+
+    test('inline link leaves text and following words', () => {
+        expect(markdownSyntaxToPlainText('[t](https://ex) rest')).toBe('t rest');
+    });
+
+    test('strips emphasis, inline code, and strikethrough', () => {
+        expect(markdownSyntaxToPlainText('**bold** and *italic*')).toBe('bold and italic');
+        expect(markdownSyntaxToPlainText('`code` here')).toBe('code here');
+        expect(markdownSyntaxToPlainText('~~gone~~ kept')).toBe('gone kept');
+    });
+
+    test('unwraps angle autolink', () => {
+        expect(markdownSyntaxToPlainText('see <https://a.com/b>')).toBe('see https://a.com/b');
+    });
+});
+
+describe('lineBreaksToFullStops', () => {
+    test('joins lines with a full stop when previous line has no ending punctuation', () => {
+        expect(lineBreaksToFullStops('First line\nSecond line')).toBe('First line. Second line');
+    });
+
+    test('joins with a single space when previous line already ends a sentence', () => {
+        expect(lineBreaksToFullStops('Done.\nNext')).toBe('Done. Next');
+    });
+
+    test('joins with space after trailing comma, colon, or semicolon', () => {
+        expect(lineBreaksToFullStops('However,\nnext')).toBe('However, next');
+        expect(lineBreaksToFullStops('Note:\nbody')).toBe('Note: body');
+    });
+});
+
+describe('truncatePlainDescriptionForNodeCard', () => {
+    test('empty or whitespace-only after strip yields empty', () => {
+        expect(truncatePlainDescriptionForNodeCard('   **  **   ')).toBe('');
+        expect(truncatePlainDescriptionForNodeCard('   \n\t  ')).toBe('');
+    });
+
+    test('truncates after strip with ellipsis when over limit', () => {
+        const long = 'word '.repeat(30) + 'end';
+        const out = truncatePlainDescriptionForNodeCard(long, 20);
+        expect(out.length).toBe(20);
+        expect(out.endsWith('\u2026')).toBe(true);
+    });
+});
+
 function baseNode(overrides: Partial<CyNodeData> = {}): CyNodeData {
     return {
         id: 'n1',
diff --git a/ui-graph/src/domain.ts b/ui-graph/src/domain.ts
@@ -231,16 +231,100 @@ export function getInitials(name: JsonValue): string {
     return parts[0].substring(0, 2).toUpperCase();
 }
 
+/**
+ * Best-effort removal of common Markdown syntax for short UI excerpts (not a full parser).
+ * Ordered passes: fenced code, inline code, images/links/reference links, bare bracket labels,
+ * strikethrough, emphasis, line-leading heading/blockquote/list/hr patterns, angle autolinks.
+ */
+export function markdownSyntaxToPlainText(raw: string): string {
+    let s = String(raw);
+
+    // Fenced blocks &rarr; inner text with whitespace collapsed (keep readable snippet).
+    s = s.replace(/```[\w-]*\n?([\s\S]*?)```/g, (_, inner: string) => {
+        const t = inner.replace(/\s+/g, ' ').trim();
+        return t ? ` ${t} ` : ' ';
+    });
+
+    // Inline code `...`
+    s = s.replace(/`([^`]+)`/g, '$1');
+
+    // Images ![alt](url)
+    s = s.replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1');
+
+    // Links [text](url)
+    s = s.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1');
+
+    // Reference-style [text][ref] or [text][]
+    s = s.replace(/\[([^\]]+)\]\[[^\]]*\]/g, '$1');
+
+    // Remaining [label] (shortcut reference / bare brackets)
+    s = s.replace(/\[([^\]]+)\]/g, '$1');
+
+    // Strikethrough ~~...~~
+    s = s.replace(/~~([^~]+)~~/g, '$1');
+
+    // Bold / italic (repeat to unwrap nested markers)
+    for (let i = 0; i < 12; i += 1) {
+        const next = s
+            .replace(/\*\*([^*]+)\*\*/g, '$1')
+            .replace(/__([^_]+)__/g, '$1')
+            .replace(/\*([^*]+)\*/g, '$1')
+            .replace(/_([^_]+)_/g, '$1');
+        if (next === s) break;
+        s = next;
+    }
+
+    s = s
+        .split('\n')
+        .map((line) => {
+            let L = line.replace(/^\s*#{1,6}\s+/, '');
+            L = L.replace(/^\s*>\s+/, '');
+            L = L.replace(/^\s*[-*+]\s+/, '');
+            L = L.replace(/^\s*\d+\.\s+/, '');
+            if (/^\s*(\*{3,}|-{3,}|_{3,})\s*$/.test(L)) return '';
+            return L;
+        })
+        .join('\n');
+
+    // Autolinks <https://...> and <http://...>
+    s = s.replace(/<https?:\/\/[^>\s]+>/gi, (m) => m.slice(1, -1));
+
+    return s;
+}
+
+/**
+ * Join non-empty lines with ". " so card excerpts read like sentences; if a line already ends with
+ * sentence punctuation (or trailing comma/semicolon/colon), join with a single space only.
+ */
+export function lineBreaksToFullStops(s: string): string {
+    const lines = s.split(/\r?\n+/).map((l) => l.trim()).filter(Boolean);
+    if (lines.length === 0) return '';
+    if (lines.length === 1) return lines[0];
+    const weakEnd = (t: string) => {
+        const u = t.trimEnd();
+        return /[.!?&hellip;]["')\]]?\s*$/.test(u) || /[,;:]\s*$/.test(u);
+    };
+    let out = lines[0];
+    for (let i = 1; i < lines.length; i += 1) {
+        const next = lines[i];
+        out = out.trimEnd() + (weakEnd(out) ? ' ' : '. ') + next;
+    }
+    return out;
+}
+
 /**
  * Plain-text description snippet for graph node cards (no HTML).
- * Normalizes whitespace; truncates to `maxChars` with an ellipsis when longer.
+ * Strips common Markdown syntax, turns line breaks into sentence breaks where helpful, then normalizes
+ * whitespace and truncates to `maxChars` with an ellipsis when longer.
  */
 export function truncatePlainDescriptionForNodeCard(
     raw: string | null | undefined,
     maxChars = 100
 ): string {
     if (raw == null || raw === '') return '';
-    const s = String(raw).replace(/\s+/g, ' ').trim();
+    const stripped = markdownSyntaxToPlainText(String(raw));
+    const joined = lineBreaksToFullStops(stripped);
+    const s = joined.replace(/\s+/g, ' ').trim();
     if (!s) return '';
     if (s.length <= maxChars) return s;
     return s.slice(0, maxChars - 1).trimEnd() + '\u2026';
