Merge pull request #2086 from NullVoxPopuli/nvp/fix-component-escaping-in-remark-land

Fix component escaping from markdown

Author: NullVoxPopuli

packages/repl-sdk/babel.config.cjs

@@ -0,0 +1,19 @@
+/**
+ * This babel.config is used for linting only
+ */
+module.exports = {
+  plugins: [
+    [
+      'module:decorator-transforms',
+      {
+        runtime: {
+          import: require.resolve('decorator-transforms/runtime-esm'),
+        },
+      },
+    ],
+  ],
+
+  generatorOpts: {
+    compact: false,
+  },
+};

packages/repl-sdk/package.json

@@ -22,13 +22,14 @@
     "type": "addon"
   },
   "scripts": {
-    "lint:fix": "pnpm -w exec lint fix",
+    "lint": "concurrently \"pnpm:lint:*(!fix)\" --names \"lint:\" --prefixColors auto",
+    "lint:fix": "concurrently \"pnpm:lint:*:fix\" --names \"fix:\" --prefixColors auto && pnpm run format",
     "example": "cd example && vite",
     "lint:package": "pnpm publint",
     "lint:js": "pnpm -w exec lint js",
     "lint:types": "tsc --noEmit",
     "lint:js:fix": "pnpm -w exec lint js:fix",
-    "lint:prettier:fix": "pnpm -w exec lint prettier:fix",
+    "format": "pnpm -w exec lint prettier:fix",
     "lint:prettier": "pnpm -w exec lint prettier",
     "test:node": "vitest"
   },
@@ -56,6 +57,7 @@
     "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.4",
     "common-tags": "^1.8.2",
+    "decorator-transforms": "2.3.1",
     "eslint": "^9.39.1",
     "prettier": "^3.7.4",
     "publint": "^0.3.16",

packages/repl-sdk/src/compilers/markdown/parse.js

@@ -12,6 +12,7 @@
  * @property {CodeBlock[]} codeBlocks
  */
 
+import remarkEscapeComponents, { REPL_LT } from '../../remark-escape-components.js';
 import { buildCompiler } from './build-compiler.js';
 
 export { buildCompiler } from './build-compiler.js';
@@ -22,36 +23,67 @@ export { buildCompiler } from './build-compiler.js';
  * @returns {Promise<ParseResult>}
  */
 export async function parseMarkdown(input, options) {
-  const markdownCompiler = options?.compiler ?? buildCompiler(options);
+  const markdownCompiler =
+    options?.compiler ??
+    buildCompiler({
+      ...options,
+      remarkPlugins: [...(options?.remarkPlugins || []), remarkEscapeComponents],
+    });
   const processed = await markdownCompiler.process(input);
   const liveCode = /** @type {CodeBlock[]} */ (processed.data.liveCode || []);
   // @ts-ignore - processed is typed as unknown due to unified processor complexity
   let templateOnly = processed.toString();
 
-  // Unescape PascalCase components that had only the opening < HTML-entity escaped
-  // BUT only outside of <pre><code> blocks where escaping should be preserved
-  // (inline <code> tags should have components unescaped)
-  // Split by <pre><code>...</code></pre> to exclude only code blocks
-  const parts = templateOnly.split(/(<pre[^>]*>.*?<\/pre>)/is);
+  // 1. Convert the placeholder written by the remark plugin to &#x3C;
+  //    This placeholder survives the entire unified pipeline without being
+  //    entity-encoded, so no double-escaping can occur.
+  if (REPL_LT) {
+    templateOnly = templateOnly.replaceAll(REPL_LT, '&#x3C;');
+  }
+
+  // 2. The pipeline may HTML-escape `<` for PascalCase component invocations
+  //    that appear in regular markdown (outside code/backticks). Undo that so
+  //    Glimmer can still invoke them.  We only unescape outside <code> elements
+  //    (and outside <pre> blocks) to preserve escaping in code.
+  templateOnly = unescapeComponentsOutsideCode(templateOnly);
+
+  return { text: templateOnly, codeBlocks: liveCode };
+}
+
+/**
+ * Undo HTML-escaping of PascalCase component tags that appear outside
+ * `<code>` and `<pre>` blocks so Glimmer can invoke them.
+ *
+ * @param {string} html
+ * @returns {string}
+ */
+function unescapeComponentsOutsideCode(html) {
+  // Split by <pre>…</pre> blocks first – never touch code fences.
+  const parts = html.split(/(<pre[\s\S]*?<\/pre>)/gi);
 
   for (let i = 0; i < parts.length; i++) {
-    const part = parts[i];
-
-    // Only process parts that are NOT pre blocks (odd indices are pre blocks)
-    if (i % 2 === 0 && part) {
-      // Pattern: &#x3C;ComponentName ... / > (only < is escaped as &#x3C;)
-      parts[i] = part.replace(/&#x3C;([A-Z][a-zA-Z0-9]*\s[^<]*?)>/g, (match, content) => {
-        // Only unescape if it contains @ (attribute) indicating a component
-        if (content.includes('@')) {
-          return `<${content}>`;
+    // Only touch content outside <pre>
+    if (i % 2 === 0) {
+      // Split by <code>…</code> so we skip inline code too
+      const part = parts[i] ?? '';
+      const codeParts = part.split(/(<code[^>]*>[\s\S]*?<\/code>)/gi);
+
+      for (let j = 0; j < codeParts.length; j++) {
+        const segment = codeParts[j];
+
+        // Even indices are outside <code> – unescape PascalCase there
+        if (j % 2 === 0 && segment) {
+          codeParts[j] = segment
+            .replace(/&#x3C;([A-Z][a-zA-Z0-9]*\s[^<]*?)>/g, (_m, content) =>
+              content.includes('@') ? `<${content}>` : _m
+            )
+            .replace(/&#x3C;\/([A-Z][a-zA-Z0-9]*)>/g, '</$1>');
         }
+      }
 
-        return match;
-      });
+      parts[i] = codeParts.join('');
     }
   }
 
-  templateOnly = parts.join('');
-
-  return { text: templateOnly, codeBlocks: liveCode };
+  return parts.join('');
 }

packages/repl-sdk/src/compilers/markdown/parse.test.ts

@@ -230,7 +230,7 @@ describe('default features', () => {
       expect(result).toMatchInlineSnapshot(`
         {
           "codeBlocks": [],
-          "text": "<h2 id="hello-foo-two"><code><Hello @foo="two" /></code></h2>",
+          "text": "<h2 id="hello-foo-two"><code>&#x3C;Hello @foo="two" /></code></h2>",
         }
       `);
     });

packages/repl-sdk/src/remark-escape-components.js

@@ -0,0 +1,39 @@
+import { visit } from 'unist-util-visit';
+
+/**
+ * A unique placeholder that replaces `<` in PascalCase component tags
+ * inside inline code and non-live code fences. It survives the unified
+ * pipeline without being entity-encoded, and is converted to `&#x3C;`
+ * in the final post-processing step inside `parseMarkdown()`.
+ */
+export const REPL_LT = '__REPL_LT__';
+
+/**
+ * Remark plugin: escape PascalCase component tags in `inlineCode` and
+ * non-live `code` (code fence) nodes by replacing `<` with a placeholder.
+ */
+function remarkEscapeComponents() {
+  /** @param {import('mdast').Root} tree */
+  return (tree) => {
+    visit(tree, (node) => {
+      // Inline code (backticks)
+      if (node.type === 'inlineCode') {
+        node.value = node.value
+          .replace(/<([A-Z][a-zA-Z0-9]*(?:\s[^<]*)?)>/g, REPL_LT + '$1>')
+          .replace(/<\/([A-Z][a-zA-Z0-9]*)>/g, REPL_LT + '/$1>');
+      }
+
+      // Code fences (``` blocks)
+      if (node.type === 'code') {
+        // Only escape if not live
+        if (!/\blive\b/.test(node.meta || '')) {
+          node.value = node.value
+            .replace(/<([A-Z][a-zA-Z0-9]*(?:\s[^<]*)?)>/g, REPL_LT + '$1>')
+            .replace(/<\/([A-Z][a-zA-Z0-9]*)>/g, REPL_LT + '/$1>');
+        }
+      }
+    });
+  };
+}
+
+export default remarkEscapeComponents;

packages/repl-sdk/tests-node/markdown-parse.test.ts

@@ -8,4 +8,47 @@ describe('markdown/parse', () => {
     expect(result.text).toMatchInlineSnapshot(`"<h1 id="hello">hello</h1>"`);
     expect(result.codeBlocks).toMatchInlineSnapshot(`[]`);
   });
+
+  test('it escapes component invocations in code blocks', async () => {
+    const result = await parseMarkdown(
+      `# Comp in tag
+
+comp: \`<Portal @to="popover">\` 
+
+tag: \`<div>\`
+
+## Install
+
+\`\`\`hbs live
+<SetupInstructions @src="components/portal-targets.gts" />
+\`\`\`
+`,
+      {
+        isLive: (meta) => meta.includes('live'),
+        ALLOWED_FORMATS: ['hbs'],
+        getFlavorFromMeta: () => undefined,
+        isPreview: () => false,
+        isBelow: () => false,
+      }
+    );
+
+    expect(result.text).toMatchInlineSnapshot(`
+      "<h1 id="comp-in-tag">Comp in tag</h1>
+      <p>comp: <code>&#x3C;Portal @to="popover"></code></p>
+      <p>tag: <code>&#x3C;div></code></p>
+      <h2 id="install">Install</h2>
+      <div id="repl_1" class="repl-sdk__demo"></div>"
+    `);
+    expect(result.codeBlocks).toMatchInlineSnapshot(`
+      [
+        {
+          "code": "<SetupInstructions @src="components/portal-targets.gts" />",
+          "flavor": undefined,
+          "format": "hbs",
+          "meta": "live",
+          "placeholderId": "repl_1",
+        },
+      ]
+    `);
+  });
 });