prevent prettier from moving // [!code ++] to different lines

Author: phryneas

config/prettier/format-mdx3.js

@@ -1,5 +1,6 @@
 /** @import { Plugin } from 'prettier' */
 
+import * as prettier from "prettier";
 import markdown from "prettier/plugins/markdown.js";
 
 /** @type {Plugin["languages"]} */
@@ -17,12 +18,77 @@ export const parsers = {
     astFormat: "mdx3",
   },
 };
+
+/**
+ * Applied to code blocks to preserve special comments like `// [!code ...]` on the same line.
+ */
+function handleCodeBlockWithSpecialComments(node, path, options) {
+  // Check if this code block has special comments
+  const specialCommentPattern = /\/\/\s*\[!code\s+[^\]]*\]/g;
+  const commentMatches = [...node.value.matchAll(specialCommentPattern)];
+
+  // Nothing to do.
+  if (commentMatches.length == 0) return null;
+
+  // Analyze comment positions - only track if comment should be inline
+  const commentPositions = commentMatches.map((commentMatch) => {
+    const beforeComment = node.value.substring(0, commentMatch.index);
+    const lineStart = beforeComment.lastIndexOf("\n") + 1;
+    const codeOnLine = node.value.substring(lineStart, commentMatch.index);
+
+    return {
+      comment: commentMatch[0],
+      shouldBeInline: codeOnLine.trim() !== "",
+    };
+  });
+
+  // Use default formatting first
+  const defaultEmbed = markdown.printers.mdast.embed(path, options);
+  return async (textToDoc) => {
+    let stringResult = prettier.doc.printer.printDocToString(
+      await defaultEmbed(textToDoc),
+      options
+    ).formatted;
+
+    const specialCommentPattern = /\/\/\s*\[!code\s+[^\]]*\]/g;
+    const formattedCommentMatches = [
+      ...stringResult.matchAll(specialCommentPattern),
+    ];
+
+    // Process each comment in reverse order to avoid index shifting
+    for (let i = formattedCommentMatches.length - 1; i >= 0; i--) {
+      const commentMatch = formattedCommentMatches[i];
+      const pos = commentPositions[i];
+      if (!pos || !pos.shouldBeInline) continue;
+
+      // Find the preceding non-whitespace character, starting from the comment position
+      let insertPos = commentMatch.index - 1;
+      while (insertPos >= 0 && /\s/.test(stringResult[insertPos])) {
+        insertPos--;
+      }
+
+      stringResult =
+        stringResult.substring(0, insertPos + 1) +
+        " " +
+        stringResult.substring(commentMatch.index);
+    }
+
+    return stringResult;
+  };
+}
+
 /** @type {Plugin["printers"]} */
 export const printers = {
   mdx3: {
     ...markdown.printers.mdast,
     embed(path, options) {
       const node = path.node;
+
+      if (node.type === "code" && node.lang !== null) {
+        const result = handleCodeBlockWithSpecialComments(node, path, options);
+        if (result) return result;
+      }
+
       if (node.type === "jsx") {
         // If the node was parsed incorrectly because it followed the MDX3 format (no spacing around JSX tags),
         // we will not try to format it as MDX, but instead return the original value.

config/prettier/test.ts

@@ -1,22 +1,12 @@
 import * as prettier from "prettier";
 const code = `
-Notice that the \`Trail\` component isn't receiving the entire \`trail\` object via props, only the \`id\` which is used along with the fragment document to create a live binding for each trail item in the cache. This allows each \`Trail\` component to react to the cache updates for a single trail independently. Updates to a trail's \`status\` will not cause the parent \`App\` component to rerender since the \`@nonreactive\` directive is applied to the \`TrailFragment\` spread, a fragment that includes the \`status\` field.
-
-<MinVersion version="3.12.0">
-## \`@unmask\`
-</MinVersion>
-
-The \`@unmask\` directive is used to make fragment data available when using [data masking](./fragments#data-masking). It is primarily used to [incrementally adopt data masking in an existing application](./fragments#incremental-adoption-in-an-existing-application). It is considered an escape hatch for all other cases where working with masked data would otherwise be difficult.
-
-\`\`\`graphql
-query GetPosts {
-  posts {
-    id
-    ...PostDetails @unmask
-  }
-}
+\`\`\`ts
+const client = new ApolloClient({
+  link: new HttpLink({ // [!code ++]
+    uri: "https://example.com/graphql",
+  }),
+});
 \`\`\`
-
 `;
 
 const result = await prettier.format(code, {

docs/source/migrating/apollo-client-4-migration.mdx

@@ -420,7 +420,7 @@ import {
 const client = new ApolloClient({
   // ...
   uri: "https://example.com/graphql",
-  link: new HttpLink({ <!--[!code --]-->
+  link: new HttpLink({ // [!code ++]
     uri: "https://example.com/graphql",
   }), // [!code ++]
   // ...