Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Markdown): pair link text brackets as CommonMark does (#7082)

Cindy Zhang6288ff65076d
diff --git a/.changeset/markdown-link-text-brackets.md b/.changeset/markdown-link-text-brackets.md
new file mode 100644
index 0000000000..522524f0d9
--- /dev/null
+++ b/.changeset/markdown-link-text-brackets.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Markdown: pair link text brackets as CommonMark does
+@cixzhang
+
+`Markdown` now pairs the brackets of link text as CommonMark specifies: link text may hold balanced brackets, so `[a [b] c](u)` is one link; the innermost bracket makes the link, so `[a [b](u)` links only `b`; and a link inside link text wins, so `[a [b](u) c](v)` shows the outer brackets as text instead of nesting links.
diff --git a/packages/core/src/Markdown/linkBrackets.test.tsx b/packages/core/src/Markdown/linkBrackets.test.tsx
new file mode 100644
index 0000000000..501e474977
--- /dev/null
+++ b/packages/core/src/Markdown/linkBrackets.test.tsx
@@ -0,0 +1,116 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {parseInlineAst, parseMarkdownAst} from './parser';
+
+type Json = {
+ type: string;
+ url?: string;
+ alt?: string;
+ value?: string;
+ children?: Json[];
+};
+
+/** Inline nodes as compact markup: links as `<a url>…</a>`. */
+function show(nodes: ReadonlyArray<Json>): string {
+ return nodes
+ .map(node => {
+ switch (node.type) {
+ case 'text':
+ return node.value;
+ case 'inlineCode':
+ return `\`${node.value}\``;
+ case 'link':
+ return `<a ${node.url}>${show(node.children ?? [])}</a>`;
+ case 'image':
+ return `<img ${node.url}>`;
+ default:
+ return `<${node.type}>${show(node.children ?? [])}</${node.type}>`;
+ }
+ })
+ .join('');
+}
+
+const inline = (markdown: string): string =>
+ show(parseInlineAst(markdown) as unknown as Json[]);
+
+/** The first paragraph of a document, as compact markup. */
+const paragraph = (markdown: string): string =>
+ show(
+ (parseMarkdownAst(markdown).children as unknown as Json[])[0].children ??
+ [],
+ );
+
+describe('link text brackets (CommonMark 0.31 §6.3)', () => {
+ it.each([
+ [
+ 'link text may hold balanced brackets',
+ '[a [b] c](u)',
+ '<a u>a [b] c</a>',
+ ],
+ ['a bracket pair can be the whole text', '[[b]](u)', '<a u>[b]</a>'],
+ ['the innermost opener makes the link', '[a [b](u)', '[a <a u>b</a>'],
+ [
+ 'a link inside link text wins; the outer brackets stay text',
+ '[a [b](u) c](v)',
+ '[a <a u>b</a> c](v)',
+ ],
+ ['an image may sit in link text', '[![i](img)](u)', '<a u><img img></a>'],
+ ['an image may hold a link', '![a [b](u) c](v) d', '<img v> d'],
+ [
+ 'a refused inner link still keeps the outer brackets text',
+ '[a [b](javascript:x) c](v)',
+ '[a [b](javascript:x) c](v)',
+ ],
+ [
+ 'emphasis may cross brackets that stay text',
+ '*[a [b](u) c*](v)',
+ '<emphasis>[a <a u>b</a> c</emphasis>](v)',
+ ],
+ ['an unmatched closer is text', '[a]b](u)', '[a]b](u)'],
+ [
+ 'brackets in a destination pair with nothing',
+ '[a](b]c) [d](e)',
+ '<a b]c>a</a> <a e>d</a>',
+ ],
+ ['an escaped bracket is text', '[a\\]b](u)', '<a u>a]b</a>'],
+ ['a code span hides its brackets', '[`]`](u)', '<a u>`]`</a>'],
+ ])('%s: %j', (_, markdown, expected) => {
+ expect(inline(markdown)).toBe(expected);
+ });
+
+ it('pairs reference links the same way', () => {
+ const definitions = '\n\n[bar]: /bar\n[y]: /y';
+ expect(paragraph(`[foo [bar]]${definitions}`)).toBe(
+ '[foo <a /bar>bar</a>]',
+ );
+ expect(paragraph(`[x][y]${definitions}`)).toBe('<a /y>x</a>');
+ expect(paragraph(`[a [bar] c](u)${definitions}`)).toBe(
+ '[a <a /bar>bar</a> c](u)',
+ );
+ });
+
+ it.each([
+ [
+ 'many openers around one link',
+ `${'['.repeat(20_000)}[a](u)${'](v)'.repeat(20_000)}`,
+ ],
+ ['many links inside link text', '[a [b](u) '.repeat(10_000)],
+ [
+ 'deeply balanced brackets',
+ `${'['.repeat(20_000)}a${']'.repeat(20_000)}(u)`,
+ ],
+ ['nested images', `${'!['.repeat(20_000)}a${'](u)'.repeat(20_000)}`],
+ ])('pairs %s in linear time', (_, markdown) => {
+ parseInlineAst(markdown);
+ let fastest = Number.POSITIVE_INFINITY;
+ for (let round = 0; round < 3; round++) {
+ const started = performance.now();
+ parseInlineAst(markdown);
+ fastest = Math.min(fastest, performance.now() - started);
+ }
+ // Alone, each takes 10–140 ms; the budget leaves room for a loaded
+ // test machine.
+ expect(fastest).toBeLessThan(2000);
+ });
+});
diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.ts
index df6e8afad0..e7ffe94a26 100644
--- a/packages/core/src/Markdown/parser.ts
+++ b/packages/core/src/Markdown/parser.ts
@@ -999,7 +999,7 @@ function matchReferenceLink(
node: MarkdownAstPhrasingContent<RuntimeExtensionNode>;
end: number;
} | null {
- const textClose = inlineIndex.closingBracket(start + 1);
+ const textClose = inlineIndex.openerClose(start);
if (textClose === -1) {
return null;
}
@@ -1064,7 +1064,7 @@ function matchReferenceImage(
node: MarkdownAstPhrasingContent<RuntimeExtensionNode>;
end: number;
} | null {
- const altClose = inlineIndex.closingBracket(start + 2);
+ const altClose = inlineIndex.openerClose(start + 1);
if (altClose === -1) {
return null;
}
@@ -1238,9 +1238,24 @@ interface InlineIndex {
* destination ends.
*/
closingParen(open: number): number;
+ /**
+ * The index of the `]` that closes the link or image opened by the `[` at
+ * `open`, or -1 when no link or image forms there. Brackets pair as
+ * CommonMark 0.31 §6.3 pairs them: each `]` closes the nearest open `[`,
+ * so link text may hold balanced brackets and `[a [b](u)` links only `b`;
+ * and a link inside link text wins, so the outer brackets stay text —
+ * links never nest. Images may hold links.
+ */
+ openerClose(open: number): number;
}
-function inlineIndexOf(text: string): InlineIndex {
+/** The most characters a link label may hold (CommonMark 0.31 §4.7). */
+const MAX_LINK_LABEL_LENGTH = 999;
+
+function inlineIndexOf(
+ text: string,
+ linkDefs?: ReadonlyMap<string, string>,
+): InlineIndex {
let backtickStarts: Map<number, number[]> | null = null;
const backtickCloser = (from: number, length: number): number => {
if (backtickStarts == null) {
@@ -1327,7 +1342,94 @@ function inlineIndexOf(text: string): InlineIndex {
}
return text[open] === '(' ? parenPartners[open] : -1;
};
- return {backtickCloser, closingBracket, closingParen};
+ /**
+ * Where the link or image whose text closes at `close` ends — past its
+ * destination or label — or -1 when nothing after the `]` makes one. The
+ * same checks the inline scan makes when it builds the node.
+ */
+ const linkEnd = (open: number, close: number): number => {
+ if (text[close + 1] === '(') {
+ const angleClose = angleDestinationClose(text, close + 1);
+ const urlClose =
+ angleClose === 'refused' ? -1 : (angleClose ?? closingParen(close + 1));
+ if (urlClose !== -1) {
+ return urlClose + 1;
+ }
+ }
+ if (linkDefs == null || close - open - 1 > MAX_LINK_LABEL_LENGTH) {
+ return -1;
+ }
+ const linkText = text.slice(open + 1, close);
+ const defines = (label: string): boolean => {
+ const href = linkDefs.get(normalizeLinkLabel(label));
+ return href != null && isSafeMarkdownParserUrl(href);
+ };
+ if (text[close + 1] === '[') {
+ const labelClose = closingBracket(close + 2);
+ if (
+ labelClose !== -1 &&
+ labelClose - close - 2 <= MAX_LINK_LABEL_LENGTH &&
+ defines(
+ labelClose === close + 2
+ ? linkText
+ : text.slice(close + 2, labelClose),
+ )
+ ) {
+ return labelClose + 1;
+ }
+ }
+ return linkText.trim() !== '' && defines(linkText) ? close + 1 : -1;
+ };
+ let openerCloses: Map<number, number> | null = null;
+ const openerClose = (open: number): number => {
+ if (openerCloses == null) {
+ // One pass in text order, as CommonMark's bracket stack runs: a `]`
+ // closes the nearest open `[`; when that makes a link, every `[`
+ // still open before it can no longer make one.
+ openerCloses = new Map();
+ const openers: {index: number; image: boolean}[] = [];
+ let inactiveBelow = 0;
+ for (let index = 0; index < text.length; index++) {
+ const character = text[index];
+ if (character === '\\') {
+ index++;
+ } else if (character === '`') {
+ let runEnd = index;
+ while (text[runEnd] === '`') {
+ runEnd++;
+ }
+ const closer = backtickCloser(runEnd, runEnd - index);
+ index = (closer === -1 ? runEnd : closer + (runEnd - index)) - 1;
+ } else if (character === '!' && text[index + 1] === '[') {
+ openers.push({index: index + 1, image: true});
+ index++;
+ } else if (character === '[') {
+ openers.push({index, image: false});
+ } else if (character === ']' && openers.length > 0) {
+ const position = openers.length - 1;
+ const opener = openers[position];
+ openers.pop();
+ const active = opener.image || position >= inactiveBelow;
+ inactiveBelow = Math.min(inactiveBelow, position);
+ if (!active) {
+ continue;
+ }
+ const end = linkEnd(opener.index, index);
+ if (end === -1) {
+ continue;
+ }
+ openerCloses.set(opener.index, index);
+ if (!opener.image) {
+ inactiveBelow = openers.length;
+ }
+ // The destination or label is no part of any bracket pairing.
+ index = end - 1;
+ }
+ }
+ }
+ return openerCloses.get(open) ?? -1;
+ };
+ return {backtickCloser, closingBracket, closingParen, openerClose};
}
// ---------------------------------------------------------------------------
@@ -2071,7 +2173,7 @@ function parseInlineImpl(
let delimiterNodes: Set<object> | null = null;
// Code-span closers and link-text closers, each indexed when first asked,
// so neither code spans nor link text rescan the text.
- const inlineIndex = inlineIndexOf(text);
+ const inlineIndex = inlineIndexOf(text, opts.linkDefs);
// Only a plugin that actually contributes INLINE syntax may cost anything
// per source position. A transform-only list contributes none, so it takes
// the same path as an omitted or empty one: no candidate probe per
@@ -2151,7 +2253,7 @@ function parseInlineImpl(
// --- Image ![alt](src) ---
if (text[i] === '!' && text[i + 1] === '[') {
- const altClose = inlineIndex.closingBracket(i + 2);
+ const altClose = inlineIndex.openerClose(i + 1);
if (altClose !== -1 && text[altClose + 1] === '(') {
const angleClose = angleDestinationClose(text, altClose + 1);
const srcClose =
@@ -2200,7 +2302,7 @@ function parseInlineImpl(
// --- Link [text](url) ---
if (text[i] === '[') {
- const textClose = inlineIndex.closingBracket(i + 1);
+ const textClose = inlineIndex.openerClose(i);
if (textClose !== -1 && text[textClose + 1] === '(') {
const angleClose = angleDestinationClose(text, textClose + 1);
const urlClose =