stage 1/2 & prettier refactor along with extra test additions

Author: EvilGenius13

.changeset/many-seahorses-smoke.md

@@ -0,0 +1,14 @@
+---
+'@shopify/prettier-plugin-liquid': minor
+'@shopify/liquid-html-parser': minor
+---
+
+Add parsing and prettier support for example node in liquiddoc
+Example:
+
+```liquid
+{% doc %}
+  @example
+  Here is my content
+{% enddoc %}
+```

packages/liquid-html-parser/src/stage-1-cst.spec.ts

@@ -1126,6 +1126,12 @@ describe('Unit: Stage 1 (CST)', () => {
           expectPath(cst, '0.children.0.type').to.equal('LiquidDocExampleNode');
           expectPath(cst, '0.children.0.name').to.equal('example');
           expectPath(cst, '0.children.0.exampleContent.value').to.equal('hello there');
+          expectPath(cst, '0.children.0.exampleContent.locStart').to.equal(
+            testStr.indexOf('hello there'),
+          );
+          expectPath(cst, '0.children.0.exampleContent.locEnd').to.equal(
+            testStr.indexOf('hello there') + 'hello there'.length,
+          );
         });
 
         it('should parse an example tag with a value', () => {
@@ -1176,6 +1182,18 @@ describe('Unit: Stage 1 (CST)', () => {
             'hello      there        my    friend\n          This is an example\n          It supports multiple lines\n',
           );
         });
+
+        it('should parse multiple example nodes', () => {
+          const testStr = `{% doc %}
+          @example hello there
+          @example second example
+        {% enddoc %}`;
+          cst = toCST(testStr);
+          expectPath(cst, '0.children.0.type').to.equal('LiquidDocExampleNode');
+          expectPath(cst, '0.children.0.exampleContent.value').to.equal('hello there\n');
+          expectPath(cst, '0.children.1.type').to.equal('LiquidDocExampleNode');
+          expectPath(cst, '0.children.1.exampleContent.value').to.equal('second example\n');
+        });
       }
     });
   });

packages/liquid-html-parser/src/stage-2-ast.spec.ts

@@ -1298,6 +1298,27 @@ describe('Unit: Stage 2 (AST)', () => {
         'including inline code\n        This is a valid example\n        It can have multiple lines\n',
       );
 
+      ast = toLiquidAST(`
+        {% doc -%}
+        @example
+        First Example
+        @example
+        Second Example
+        {% enddoc %}
+      `);
+      expectPath(ast, 'children.0.type').to.eql('LiquidRawTag');
+      expectPath(ast, 'children.0.name').to.eql('doc');
+      expectPath(ast, 'children.0.body.nodes.0.type').to.eql('LiquidDocExampleNode');
+      expectPath(ast, 'children.0.body.nodes.0.name').to.eql('example');
+      expectPath(ast, 'children.0.body.nodes.0.exampleContent.value').to.eql(
+        '\n        First Example\n',
+      );
+      expectPath(ast, 'children.0.body.nodes.1.type').to.eql('LiquidDocExampleNode');
+      expectPath(ast, 'children.0.body.nodes.1.name').to.eql('example');
+      expectPath(ast, 'children.0.body.nodes.1.exampleContent.value').to.eql(
+        '\n        Second Example\n',
+      );
+
       ast = toLiquidAST(`
         {% doc -%}
         @example

packages/liquid-html-parser/src/stage-2-ast.ts

@@ -767,7 +767,7 @@ export interface LiquidDocParamNode extends ASTNode<NodeTypes.LiquidDocParamNode
   paramType: TextNode | null;
 }
 
-/** Represents a `@example` node in a LiquidDoc comment - `@example @exampleContent` */
+/** Represents a `@example` node in a LiquidDoc comment - `@example exampleContent` */
 export interface LiquidDocExampleNode extends ASTNode<NodeTypes.LiquidDocExampleNode> {
   name: 'example';
   /** The contents of the example (e.g. "{{ product }}"). Can be multiline. */
@@ -1312,12 +1312,7 @@ function buildAst(
           name: node.name,
           position: position(node),
           source: node.source,
-          exampleContent: {
-            type: NodeTypes.TextNode,
-            value: node.exampleContent.value,
-            position: position(node.exampleContent),
-            source: node.exampleContent.source,
-          },
+          exampleContent: toTextNode(node.exampleContent),
         });
         break;
       }

packages/prettier-plugin-liquid/src/printer/print/liquid.ts

@@ -546,48 +546,46 @@ export function printLiquidDocExample(
   const node = path.getValue();
   const parts: Doc[] = ['@example'];
 
-  if (node.exampleContent?.value) {
-    const content = node.exampleContent.value;
-    if (content) {
-      // Count leading newlines before content (\n\nmy content)
-      const leadingNewlines = content.match(/^\n*/)?.[0]?.length ?? 0;
-      const trimmedContent = content.trim();
-
-      // Push inline content to new line
+  const content = node.exampleContent.value;
+  if (content) {
+    // Count leading newlines before content (\n\nmy content)
+    const leadingNewlines = content.match(/^\n*/)?.[0]?.length ?? 0;
+    const trimmedContent = content.trim();
+
+    // Push inline content to new line
+    parts.push(hardline);
+
+    // If there were two or more leading newlines, push another new line
+    if (leadingNewlines > 1) {
       parts.push(hardline);
+    }
 
-      // If there were two or more leading newlines, push another new line
-      if (leadingNewlines > 1) {
-        parts.push(hardline);
-      }
+    // If content doesn't have newlines in it, make sure it's on a new line (not inline)
+    if (!trimmedContent.includes('\n')) {
+      parts.push(trimmedContent);
+      return parts;
+    }
 
-      // If content doesn't have newlines in it, make sure it's on a new line (not inline)
-      if (!trimmedContent.includes('\n')) {
-        parts.push(trimmedContent);
-        return parts;
-      }
+    // For multi-line content
+    const lines = trimmedContent.split('\n');
+    const processedLines: string[] = [];
+    let emptyLineCount = 0;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
 
-      // For multi-line content
-      const lines = trimmedContent.split('\n');
-      const processedLines: string[] = [];
-      let emptyLineCount = 0;
-
-      for (let i = 0; i < lines.length; i++) {
-        const line = lines[i].trim();
-
-        if (line === '') {
-          emptyLineCount++;
-          if (emptyLineCount <= 2) {
-            processedLines.push('');
-          }
-        } else {
-          emptyLineCount = 0;
-          processedLines.push(line);
+      if (line === '') {
+        emptyLineCount++;
+        if (emptyLineCount <= 2) {
+          processedLines.push('');
         }
+      } else {
+        emptyLineCount = 0;
+        processedLines.push(line);
       }
-
-      parts.push(join(hardline, processedLines));
     }
+
+    parts.push(join(hardline, processedLines));
   }
 
   return parts;

packages/prettier-plugin-liquid/src/test/liquid-doc/fixed.liquid

@@ -56,7 +56,7 @@ It should allow multiple empty lines between content
   with a single empty line
 {% enddoc %}
 
-It should remove empty lines at the end of the content
+It should remove empty lines at the end of the example content
 {% doc %}
   @example
 
@@ -70,3 +70,21 @@ It should respect example content with param and description
 
   This is a valid example
 {% enddoc %}
+
+It should allow multiple example nodes
+{% doc %}
+  @example
+  First Example
+  @example
+  Second Example
+{% enddoc %}
+
+It should default to two lines between example content when there are three or more new lines
+{% doc %}
+  @example
+
+  There are three lines between me and the next line
+
+
+  It will format down to two lines
+{% enddoc %}

packages/prettier-plugin-liquid/src/test/liquid-doc/index.liquid

@@ -43,7 +43,7 @@ It should allow single empty lines between content
   See?
 {% enddoc %}
 
-It should allow multiple empty lines between content
+It should allow multiple empty lines between example content
 {% doc %}
   @example
 
@@ -55,7 +55,7 @@ It should allow multiple empty lines between content
   with a single empty line
 {% enddoc %}
 
-It should remove empty lines at the end of the content
+It should remove empty lines at the end of the example content
 {% doc %}
   @example
 
@@ -70,3 +70,22 @@ It should respect example content with param and description
 
 This is a valid example
 {% enddoc %}
+
+It should allow multiple example nodes
+{% doc %}
+  @example
+  First Example
+  @example
+  Second Example
+{% enddoc %}
+
+It should default to two lines between example content when there are three or more new lines
+{% doc %}
+  @example
+
+  There are three lines between me and the next line
+
+
+
+  It will format down to two lines
+{% enddoc %}