KAN-73: document and validate MCP ticket description format

resources/js/lib/ticket-description.ts

@@ -2,30 +2,40 @@ import type { JSONContent } from '@tiptap/core';
 import { Markdown, MarkdownManager } from '@tiptap/markdown';
 import StarterKit from '@tiptap/starter-kit';
 import { h } from 'vue';
+import descriptionFormat from './ticket-description-format.json';
 import type { VNodeChild } from 'vue';
 
 export function safeDescriptionLink(value: unknown): string | null {
     if (
         typeof value !== 'string' ||
-        /[\s\\]/u.test(value) ||
-        [...value].some(
-            (character) =>
-                character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127,
-        )
+        new RegExp(descriptionFormat.unsafe_link_characters, 'u').test(value)
     ) {
         return null;
     }
+    try {
+        if (
+            new RegExp(descriptionFormat.unsafe_link_characters, 'u').test(
+                decodeURIComponent(value),
+            )
+        ) {
+            return null;
+        }
+    } catch {
+        return null;
+    }
     if (/^(https?:\/\/|mailto:)/i.test(value)) {
         try {
-            const url = new URL(value);
-            return ['http:', 'https:', 'mailto:'].includes(url.protocol)
+            new URL(value);
+            return new RegExp(descriptionFormat.link_prefix, 'i').test(value)
                 ? value
                 : null;
         } catch {
             return null;
         }
     }
-    return /^(\/(?!\/)|#)/.test(value) ? value : null;
+    return new RegExp(descriptionFormat.link_prefix, 'i').test(value)
+        ? value
+        : null;
 }
 
 export function descriptionExtensions() {
@@ -55,15 +65,21 @@ const markdown = new MarkdownManager({
 /** Unsupported Markdown stays editable verbatim instead of being silently discarded. */
 export function supportsVisualDescription(value: string): boolean {
     let supported = true;
-    markdown.instance.walkTokens(markdown.instance.lexer(value), (token) => {
-        if (
-            ['html', 'table', 'image'].includes(token.type) ||
-            (token.type === 'list_item' && token.task) ||
-            (token.type === 'link' && !safeDescriptionLink(token.href))
-        ) {
-            supported = false;
-        }
-    });
+    markdown.instance.walkTokens(
+        markdown.instance.lexer(value, { gfm: true, breaks: true }),
+        (token) => {
+            if (
+                Object.hasOwn(
+                    descriptionFormat.unsupported_tokens,
+                    token.type,
+                ) ||
+                (token.type === 'list_item' && token.task) ||
+                (token.type === 'link' && !safeDescriptionLink(token.href))
+            ) {
+                supported = false;
+            }
+        },
+    );
     return supported;
 }