Merge pull request #801 from Shopify/add-hover-support-for-description-tag

Add hover support for the description tag

Author: EvilGenius13

.changeset/popular-geese-flow.md

@@ -0,0 +1,5 @@
+---
+'@shopify/theme-language-server-common': patch
+---
+
+Add hover support for the `@description` tag

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

@@ -1082,8 +1082,8 @@ describe('Unit: Stage 1 (CST)', () => {
         });
 
         it('should parse @param with malformed optional delimiters as Text Nodes', () => {
-          const testStr = `{% doc %} 
-            @param paramWithMissingHeadDelim] 
+          const testStr = `{% doc %}
+            @param paramWithMissingHeadDelim]
             @param [paramWithMissingTailDelim
             @param missingHeadWithDescription] - description value
             @param [missingTailWithDescription - description value
@@ -1330,10 +1330,10 @@ describe('Unit: Stage 1 (CST)', () => {
           {% enddoc %}`;
           cst = toCST(testStr);
           expectPath(cst, '0.children.0.type').to.equal('LiquidDocDescriptionNode');
-          expectPath(cst, '0.children.0.content.value').to.equal('This is a description\n');
+          expectPath(cst, '0.children.0.content.value').to.equal('This is a description');
 
           expectPath(cst, '0.children.1.type').to.equal('LiquidDocDescriptionNode');
-          expectPath(cst, '0.children.1.content.value').to.equal('This is a second description\n');
+          expectPath(cst, '0.children.1.content.value').to.equal('This is a second description');
         });
 
         it('should parse and strip whitespace from description tag with content that has leading whitespace', () => {
@@ -1362,7 +1362,7 @@ describe('Unit: Stage 1 (CST)', () => {
           expectPath(cst, '0.children.0.type').to.equal('LiquidDocDescriptionNode');
           expectPath(cst, '0.children.0.name').to.equal('description');
           expectPath(cst, '0.children.0.content.value').to.equal(
-            'hello      there        my    friend\n          This is a description\n          It supports multiple lines\n',
+            'hello      there        my    friend\n          This is a description\n          It supports multiple lines',
           );
         });
 
@@ -1373,9 +1373,9 @@ describe('Unit: Stage 1 (CST)', () => {
         {% enddoc %}`;
           cst = toCST(testStr);
           expectPath(cst, '0.children.0.type').to.equal('LiquidDocDescriptionNode');
-          expectPath(cst, '0.children.0.content.value').to.equal('hello there\n');
+          expectPath(cst, '0.children.0.content.value').to.equal('hello there');
           expectPath(cst, '0.children.1.type').to.equal('LiquidDocDescriptionNode');
-          expectPath(cst, '0.children.1.content.value').to.equal('second description\n');
+          expectPath(cst, '0.children.1.content.value').to.equal('second description');
         });
       }
     });

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

@@ -1400,7 +1400,15 @@ function toLiquidDocAST(source: string, matchingSource: string, offset: number)
       source,
       content: 2,
     },
-    descriptionContent: textNode(),
+    descriptionContent: {
+      type: ConcreteNodeTypes.TextNode,
+      value: function (this: Node) {
+        return this.sourceString.trim();
+      },
+      locStart,
+      locEnd,
+      source,
+    },
     paramType: 2,
     paramTypeContent: textNode(),
     paramName: {

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

@@ -1385,10 +1385,10 @@ describe('Unit: Stage 2 (AST)', () => {
         {% enddoc %}
       `);
       expectPath(ast, 'children.0.body.nodes.0.type').to.eql('LiquidDocDescriptionNode');
-      expectPath(ast, 'children.0.body.nodes.0.content.value').to.eql('This is a description\n');
+      expectPath(ast, 'children.0.body.nodes.0.content.value').to.eql('This is a description');
       expectPath(ast, 'children.0.body.nodes.1.type').to.eql('LiquidDocDescriptionNode');
       expectPath(ast, 'children.0.body.nodes.1.content.value').to.eql(
-        'This is another description\n        it can have multiple lines\n',
+        'This is another description\n        it can have multiple lines',
       );
 
       ast = toLiquidAST(`
@@ -1399,7 +1399,7 @@ describe('Unit: Stage 2 (AST)', () => {
         {% enddoc %}
       `);
       expectPath(ast, 'children.0.body.nodes.0.type').to.eql('LiquidDocDescriptionNode');
-      expectPath(ast, 'children.0.body.nodes.0.content.value').to.eql('This is a description\n');
+      expectPath(ast, 'children.0.body.nodes.0.content.value').to.eql('This is a description');
 
       expectPath(ast, 'children.0.body.nodes.1.type').to.eql('LiquidDocExampleNode');
       expectPath(ast, 'children.0.body.nodes.1.name').to.eql('example');
@@ -1572,7 +1572,7 @@ describe('Unit: Stage 2 (AST)', () => {
         @p█
       `);
       expectPath(ast, 'children.0.body.nodes.0.type').to.eql('LiquidDocDescriptionNode');
-      expectPath(ast, 'children.0.body.nodes.0.content.value').to.eql('This is a description\n');
+      expectPath(ast, 'children.0.body.nodes.0.content.value').to.eql('This is a description');
 
       expectPath(ast, 'children.0.body.nodes.1.type').to.eql('LiquidDocExampleNode');
       expectPath(ast, 'children.0.body.nodes.1.name').to.eql('example');

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

@@ -584,7 +584,7 @@ export function printLiquidDocDescription(
   const parts: Doc[] = ['@description'];
 
   if (node.content?.value) {
-    parts.push(' ', node.content.value.trim());
+    parts.push(' ', node.content.value);
   }
 
   return parts;

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

@@ -102,12 +102,12 @@ It should add a space between a description tag and content
 
 It should handle param, example, and description nodes
 {% doc %}
+  @description This is a description
+
   @param {String} paramName - param with description
 
   @example
   This is a valid example
-
-  @description This is a description
 {% enddoc %}
 
 It should add padding between dissimilar nodes

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

@@ -101,10 +101,10 @@ It should add a space between a description tag and content
 
 It should handle param, example, and description nodes
 {% doc %}
+  @description This is a description
   @param {String} paramName - param with description
   @example
   This is a valid example
-  @description This is a description
 {% enddoc %}
 
 It should add padding between dissimilar nodes

packages/theme-check-common/src/liquid-doc/liquidDoc.spec.ts

@@ -192,6 +192,45 @@ describe('Unit: getSnippetDefinition', () => {
     });
   });
 
+  it('should extract description from @description annotations', async () => {
+    const ast = toAST(`
+        {% doc %}
+          @description This is a description
+        {% enddoc %}
+      `);
+
+    const result = getSnippetDefinition(ast, 'product-card');
+    expect(result).to.deep.equal({
+      name: 'product-card',
+      liquidDoc: {
+        description: {
+          content: 'This is a description',
+          nodeType: 'description',
+        },
+      },
+    });
+  });
+
+  it('should extract only the first @description annotation', async () => {
+    const ast = toAST(`
+        {% doc %}
+          @description This is a description
+          @description This is another description
+        {% enddoc %}
+      `);
+
+    const result = getSnippetDefinition(ast, 'product-card');
+    expect(result).to.deep.equal({
+      name: 'product-card',
+      liquidDoc: {
+        description: {
+          content: 'This is a description',
+          nodeType: 'description',
+        },
+      },
+    });
+  });
+
   it('should return snippetDefinition without liquidDoc property if doc header is not present', async () => {
     const ast = toAST(`
       <div>No doc header here</div>

packages/theme-check-common/src/liquid-doc/liquidDoc.ts

@@ -1,7 +1,11 @@
 import { SourceCodeType } from '../types';
 import { visit } from '../visitor';
 import { LiquidHtmlNode } from '../types';
-import { LiquidDocExampleNode, LiquidDocParamNode } from '@shopify/liquid-html-parser';
+import {
+  LiquidDocExampleNode,
+  LiquidDocParamNode,
+  LiquidDocDescriptionNode,
+} from '@shopify/liquid-html-parser';
 
 export type GetSnippetDefinitionForURI = (
   uri: string,
@@ -16,10 +20,11 @@ export type SnippetDefinition = {
 type LiquidDocDefinition = {
   parameters?: LiquidDocParameter[];
   examples?: LiquidDocExample[];
+  description?: LiquidDocDescription;
 };
 
 interface LiquidDocNode {
-  nodeType: 'param' | 'example';
+  nodeType: 'param' | 'example' | 'description';
 }
 
 export interface LiquidDocParameter extends LiquidDocNode {
@@ -34,14 +39,19 @@ export interface LiquidDocExample extends LiquidDocNode {
   nodeType: 'example';
 }
 
+export interface LiquidDocDescription extends LiquidDocNode {
+  content: string;
+  nodeType: 'description';
+}
+
 export function getSnippetDefinition(
   snippet: LiquidHtmlNode,
   snippetName: string,
 ): SnippetDefinition {
   let hasDocTag = false;
-  const nodes: (LiquidDocParameter | LiquidDocExample)[] = visit<
+  const nodes: (LiquidDocParameter | LiquidDocExample | LiquidDocDescription)[] = visit<
     SourceCodeType.LiquidHtml,
-    LiquidDocParameter | LiquidDocExample
+    LiquidDocParameter | LiquidDocExample | LiquidDocDescription
   >(snippet, {
     LiquidRawTag(node) {
       if (node.name === 'doc') hasDocTag = true;
@@ -62,17 +72,29 @@ export function getSnippetDefinition(
         nodeType: 'example',
       };
     },
+    LiquidDocDescriptionNode(node: LiquidDocDescriptionNode) {
+      return {
+        content: node.content.value,
+        nodeType: 'description',
+      };
+    },
   });
-  const { parameters, examples } = nodes.reduce(
+  const { parameters, examples, description } = nodes.reduce(
     (acc, node) => {
       if (node.nodeType === 'param') {
         acc.parameters.push(node as LiquidDocParameter);
       } else if (node.nodeType === 'example') {
         acc.examples.push(node as LiquidDocExample);
+      } else if (node.nodeType === 'description' && !acc.description) {
+        acc.description = node as LiquidDocDescription;
       }
       return acc;
     },
-    { parameters: [] as LiquidDocParameter[], examples: [] as LiquidDocExample[] },
+    {
+      parameters: [] as LiquidDocParameter[],
+      examples: [] as LiquidDocExample[],
+      description: undefined as LiquidDocDescription | undefined,
+    },
   );
 
   if (!hasDocTag) return { name: snippetName };
@@ -82,6 +104,7 @@ export function getSnippetDefinition(
     liquidDoc: {
       ...(parameters.length && { parameters }),
       ...(examples.length && { examples }),
+      ...(description && { description }),
     },
   };
 }

packages/theme-language-server-common/src/hover/providers/RenderSnippetHoverProvider.spec.ts

@@ -48,6 +48,10 @@ describe('Module: RenderSnippetHoverProvider', async () => {
           nodeType: 'param',
         },
       ],
+      description: {
+        content: 'This is a description',
+        nodeType: 'description',
+      },
       examples: [
         {
           content: '{{ product }}',
@@ -66,7 +70,7 @@ describe('Module: RenderSnippetHoverProvider', async () => {
       provider = createProvider(async () => mockSnippetDefinition);
       await expect(provider).to.hover(
         `{% render 'product-car█d' %}`,
-        '### product-card\n\n**Parameters:**\n- `title`: string - The title of the product\n- `border-radius` (Optional): number - The border radius in px\n- `no-type` - This parameter has no type\n- `no-description`: string\n- `no-type-or-description`\n\n**Examples:**\n```liquid{{ product }}```\n```liquid{{ product.title }}```',
+        '### product-card\n\n**Description:**\n\n\nThis is a description\n\n**Parameters:**\n- `title`: string - The title of the product\n- `border-radius` (Optional): number - The border radius in px\n- `no-type` - This parameter has no type\n- `no-description`: string\n- `no-type-or-description`\n\n**Examples:**\n```liquid{{ product }}```\n```liquid{{ product.title }}```',
       );
     });
 

packages/theme-language-server-common/src/hover/providers/RenderSnippetHoverProvider.ts

@@ -49,6 +49,11 @@ export class RenderSnippetHoverProvider implements BaseHoverProvider {
 
     const parts = [`### ${snippetDefinition.name}`];
 
+    if (liquidDoc.description) {
+      const description = liquidDoc.description.content;
+      parts.push('', '**Description:**', '\n', description);
+    }
+
     if (liquidDoc.parameters?.length) {
       const parameters = this.buildParameters(liquidDoc.parameters);
       parts.push('', '**Parameters:**', parameters);