[LiquidDoc] Add snippet hover support inside of {% render %} tag (#703)

## What are you adding in this PR?

Shopify/developer-tools-team#496

**1) Hover support for Liquid snippets inside of a `{% render %}` tag. Users will now see:**
- The snippet name as a header
- A list of parameters with their types and descriptions (if 
documented)

If there is no `{% doc %}` present in the snippet, we will just render the snippet name

**2) Caching for fetching LiquidDoc definitions**

##### Example snippet documentation:
```liquid
{% doc %}
  @param {String} title - The title of the product
  @param {Number} border-radius - The border radius in px
{% enddoc %}
```

##### When hovering over `product-card` in `{% render 'product-card' %}`, users will see:
```markdown
### product-card

**Parameters:**
- `title`: String - The title of the product
- `border-radius`: Number - The border radius in px
```

Uploading Cursor - liquidDoc.ts — theme-tools.mp4…

#### Hovering a snippet with docs
![image.png](https://graphite-user-uploaded-assets-prod.s3.amazonaws.com/JdHLnhebSbtZTZO01I1e/84bb1493-2812-4eba-9943-65b2d4071f9a.png)

#### Hovering a snippet without liquiddoc
![image.png](https://graphite-user-uploaded-assets-prod.s3.amazonaws.com/JdHLnhebSbtZTZO01I1e/ad09bea5-5e73-454a-9269-0ce8a187900e.png)


## What's next? Any followup issues?

- Consider adding validation for param types
- Add support for return value documentation
- Add support for example usage documentation

## What did you learn?

This is my first time working with the hover API in VS code. Pretty cool to read up on!

## Before you deploy

- [x] I included a minor bump `changeset`
- [x] My feature is backward compatible

Author: jamesmengo

.changeset/dry-donkeys-behave.md

@@ -0,0 +1,6 @@
+---
+'@shopify/theme-language-server-common': minor
+'@shopify/theme-check-common': minor
+---
+
+Cache liquidDoc fetch results

.changeset/little-flowers-swim.md

@@ -0,0 +1,6 @@
+---
+'@shopify/theme-language-server-common': minor
+'@shopify/theme-check-common': minor
+---
+
+Add hover support for Liquid snippets using {% doc %} annotations

packages/theme-language-server-common/src/documents/DocumentManager.ts

@@ -12,12 +12,14 @@ import {
   IsValidSchema,
   memo,
   Mode,
+  isError,
 } from '@shopify/theme-check-common';
 import { Connection } from 'vscode-languageserver';
 import { TextDocument } from 'vscode-languageserver-textdocument';
 import { ClientCapabilities } from '../ClientCapabilities';
 import { percent, Progress } from '../progress';
 import { AugmentedSourceCode } from './types';
+import { getSnippetDefinition } from '../liquidDoc';
 
 export class DocumentManager {
   /**
@@ -171,6 +173,12 @@ export class DocumentManager {
             const mode = await this.getModeForUri!(uri);
             return toSchema(mode, uri, sourceCode, this.isValidSchema);
           }),
+          /** Lazy and only computed once per file version */
+          getLiquidDoc: memo(async (snippetName: string) => {
+            if (isError(sourceCode.ast)) return { name: snippetName };
+
+            return getSnippetDefinition(sourceCode.ast, snippetName);
+          }),
         };
       default:
         return assertNever(sourceCode);

packages/theme-language-server-common/src/documents/types.ts

@@ -6,6 +6,7 @@ import {
   AppBlockSchema,
 } from '@shopify/theme-check-common';
 import { TextDocument } from 'vscode-languageserver-textdocument';
+import { SnippetDefinition } from '../liquidDoc';
 
 /** Util type to add the common `textDocument` property to the SourceCode. */
 type _AugmentedSourceCode<SCT extends SourceCodeType = SourceCodeType> = SourceCode<SCT> & {
@@ -23,6 +24,7 @@ export type AugmentedJsonSourceCode = _AugmentedSourceCode<SourceCodeType.JSON>;
  */
 export type AugmentedLiquidSourceCode = _AugmentedSourceCode<SourceCodeType.LiquidHtml> & {
   getSchema: () => Promise<SectionSchema | ThemeBlockSchema | AppBlockSchema | undefined>;
+  getLiquidDoc: (snippetName: string) => Promise<SnippetDefinition>;
 };
 
 /**

packages/theme-language-server-common/src/hover/HoverProvider.ts

@@ -12,10 +12,12 @@ import {
   LiquidObjectHoverProvider,
   LiquidTagHoverProvider,
   TranslationHoverProvider,
+  RenderSnippetHoverProvider,
 } from './providers';
 import { HtmlAttributeValueHoverProvider } from './providers/HtmlAttributeValueHoverProvider';
 import { findCurrentNode } from '@shopify/theme-check-common';
 import { GetThemeSettingsSchemaForURI } from '../settings';
+import { GetSnippetDefinitionForURI } from '../liquidDoc';
 
 export class HoverProvider {
   private providers: BaseHoverProvider[] = [];
@@ -26,6 +28,12 @@ export class HoverProvider {
     readonly getMetafieldDefinitions: (rootUri: string) => Promise<MetafieldDefinitionMap>,
     readonly getTranslationsForURI: GetTranslationsForURI = async () => ({}),
     readonly getSettingsSchemaForURI: GetThemeSettingsSchemaForURI = async () => [],
+    readonly getSnippetDefinitionForURI: GetSnippetDefinitionForURI = async (
+      _uri,
+      snippetName,
+    ) => ({
+      name: snippetName,
+    }),
   ) {
     const typeSystem = new TypeSystem(
       themeDocset,
@@ -41,6 +49,7 @@ export class HoverProvider {
       new HtmlAttributeHoverProvider(),
       new HtmlAttributeValueHoverProvider(),
       new TranslationHoverProvider(getTranslationsForURI, documentManager),
+      new RenderSnippetHoverProvider(getSnippetDefinitionForURI),
     ];
   }
 

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

@@ -0,0 +1,68 @@
+import { describe, beforeEach, it, expect } from 'vitest';
+import { DocumentManager } from '../../documents';
+import { HoverProvider } from '../HoverProvider';
+import { MetafieldDefinitionMap } from '@shopify/theme-check-common';
+import { GetSnippetDefinitionForURI, SnippetDefinition } from '../../liquidDoc';
+
+describe('Module: RenderSnippetHoverProvider', async () => {
+  let provider: HoverProvider;
+  let getSnippetDefinition: GetSnippetDefinitionForURI;
+  const mockSnippetDefinition: SnippetDefinition = {
+    name: 'product-card',
+    liquidDoc: {
+      parameters: [
+        {
+          name: 'title',
+          description: 'The title of the product',
+          type: 'string',
+        },
+        {
+          name: 'border-radius',
+          description: 'The border radius in px',
+          type: 'number',
+        },
+      ],
+    },
+  };
+
+  const createProvider = (getSnippetDefinition: GetSnippetDefinitionForURI) => {
+    return new HoverProvider(
+      new DocumentManager(),
+      {
+        filters: async () => [],
+        objects: async () => [],
+        tags: async () => [],
+        systemTranslations: async () => ({}),
+      },
+      async (_rootUri: string) => ({} as MetafieldDefinitionMap),
+      async () => ({}),
+      async () => [],
+      getSnippetDefinition,
+    );
+  };
+
+  beforeEach(async () => {
+    getSnippetDefinition = async () => mockSnippetDefinition;
+    provider = createProvider(getSnippetDefinition);
+  });
+
+  describe('hover', () => {
+    it('should return snippet definition with all parameters', async () => {
+      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`: number - The border radius in px',
+      );
+    });
+
+    it('should return an H3 with snippet name if no LiquidDocDefinition found', async () => {
+      getSnippetDefinition = async () => ({ name: 'unknown-snippet' });
+      provider = createProvider(getSnippetDefinition);
+      await expect(provider).to.hover(`{% render 'unknown-sni█ppet' %}`, '### unknown-snippet');
+    });
+
+    it('should return nothing if not in render tag', async () => {
+      await expect(provider).to.hover(`{% assign asdf = 'snip█pet' %}`, null);
+      await expect(provider).to.hover(`{{ 'snip█pet' }}`, null);
+    });
+  });
+});

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

@@ -0,0 +1,66 @@
+import { NodeTypes } from '@shopify/liquid-html-parser';
+import { LiquidHtmlNode } from '@shopify/theme-check-common';
+import { Hover, HoverParams } from 'vscode-languageserver';
+import { BaseHoverProvider } from '../BaseHoverProvider';
+import { SnippetDefinition, LiquidDocParameter } from '../../liquidDoc';
+
+export class RenderSnippetHoverProvider implements BaseHoverProvider {
+  constructor(
+    private getSnippetDefinitionForURI: (
+      uri: string,
+      snippetName: string,
+    ) => Promise<SnippetDefinition>,
+  ) {}
+
+  async hover(
+    currentNode: LiquidHtmlNode,
+    ancestors: LiquidHtmlNode[],
+    params: HoverParams,
+  ): Promise<Hover | null> {
+    const parentNode = ancestors.at(-1);
+    if (
+      currentNode.type !== NodeTypes.String ||
+      !parentNode ||
+      parentNode.type !== NodeTypes.RenderMarkup
+    ) {
+      return null;
+    }
+
+    const snippetName = currentNode.value;
+    const snippetDefinition = await this.getSnippetDefinitionForURI(
+      params.textDocument.uri,
+      snippetName,
+    );
+
+    const liquidDoc = snippetDefinition.liquidDoc;
+
+    if (!liquidDoc) {
+      return {
+        contents: {
+          kind: 'markdown',
+          value: `### ${snippetDefinition.name}`,
+        },
+      };
+    }
+
+    const parts = [`### ${snippetDefinition.name}`];
+
+    if (liquidDoc.parameters?.length) {
+      const parameters = liquidDoc.parameters
+        ?.map(
+          ({ name, type, description }: LiquidDocParameter) =>
+            `- \`${name}\`${type ? `: ${type}` : ''} ${description ? `- ${description}` : ''}`,
+        )
+        .join('\n');
+
+      parts.push('', '**Parameters:**', parameters);
+    }
+
+    return {
+      contents: {
+        kind: 'markdown',
+        value: parts.join('\n'),
+      },
+    };
+  }
+}

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

@@ -6,3 +6,4 @@ export { HtmlTagHoverProvider } from './HtmlTagHoverProvider';
 export { HtmlAttributeHoverProvider } from './HtmlAttributeHoverProvider';
 export { HtmlAttributeValueHoverProvider } from './HtmlAttributeValueHoverProvider';
 export { TranslationHoverProvider } from './TranslationHoverProvider';
+export { RenderSnippetHoverProvider } from './RenderSnippetHoverProvider';

packages/theme-language-server-common/src/liquidDoc.spec.ts

@@ -0,0 +1,68 @@
+import { expect, it } from 'vitest';
+import { LiquidHtmlNode } from '@shopify/theme-check-common';
+import { toSourceCode } from '@shopify/theme-check-common';
+import { describe } from 'vitest';
+import { getSnippetDefinition } from './liquidDoc';
+
+describe('Unit: makeGetLiquidDocDefinitions', () => {
+  function toAST(code: string) {
+    return toSourceCode('/tmp/foo.liquid', code).ast as LiquidHtmlNode;
+  }
+
+  it('should return name if no valid annotations are present in definition', async () => {
+    const ast = toAST(`
+        {% doc %}
+          just a description
+          @undefined asdf
+        {% enddoc %}
+      `);
+
+    const result = getSnippetDefinition(ast, 'product-card');
+    expect(result).to.deep.equal({
+      name: 'product-card',
+      liquidDoc: {
+        parameters: [],
+      },
+    });
+  });
+
+  it('should extract name, description and type from param annotations', async () => {
+    const ast = toAST(`
+        {% doc %}
+          @param {String} firstParam - The first param
+          @param {Number} secondParam - The second param
+          @param paramWithNoType - param with no type
+          @param paramWithOnlyName
+        {% enddoc %}
+      `);
+
+    const result = getSnippetDefinition(ast, 'product-card');
+    expect(result).to.deep.equal({
+      name: 'product-card',
+      liquidDoc: {
+        parameters: [
+          {
+            name: 'firstParam',
+            description: 'The first param',
+            type: 'String',
+          },
+          {
+            name: 'secondParam',
+            description: 'The second param',
+            type: 'Number',
+          },
+          {
+            name: 'paramWithNoType',
+            description: 'param with no type',
+            type: null,
+          },
+          {
+            name: 'paramWithOnlyName',
+            description: '',
+            type: null,
+          },
+        ],
+      },
+    });
+  });
+});

packages/theme-language-server-common/src/liquidDoc.ts

@@ -0,0 +1,50 @@
+import { SourceCodeType, visit } from '@shopify/theme-check-common';
+
+import { LiquidHtmlNode } from '@shopify/theme-check-common';
+
+import { LiquidDocParamNode } from '@shopify/liquid-html-parser';
+
+export type GetSnippetDefinitionForURI = (
+  uri: string,
+  snippetName: string,
+) => Promise<SnippetDefinition>;
+
+export type LiquidDocParameter = {
+  name: string;
+  description: string | null;
+  type: string | null;
+};
+
+export type SnippetDefinition = {
+  name: string;
+  liquidDoc?: LiquidDocDefinition;
+};
+
+type LiquidDocDefinition = {
+  parameters?: LiquidDocParameter[];
+};
+
+export function getSnippetDefinition(
+  snippet: LiquidHtmlNode,
+  snippetName: string,
+): SnippetDefinition {
+  const liquidDocParameters: LiquidDocParameter[] = visit<
+    SourceCodeType.LiquidHtml,
+    LiquidDocParameter
+  >(snippet, {
+    LiquidDocParamNode(node: LiquidDocParamNode) {
+      return {
+        name: node.paramName.value,
+        description: node.paramDescription?.value ?? null,
+        type: node.paramType?.value ?? null,
+      };
+    },
+  });
+
+  return {
+    name: snippetName,
+    liquidDoc: {
+      parameters: liquidDocParameters,
+    },
+  };
+}

packages/theme-language-server-common/src/server/startServer.ts

@@ -43,6 +43,8 @@ import { snippetName } from '../utils/uri';
 import { VERSION } from '../version';
 import { CachedFileSystem } from './CachedFileSystem';
 import { Configuration } from './Configuration';
+import { LiquidHtmlNode } from '@shopify/liquid-html-parser';
+import { getSnippetDefinition, SnippetDefinition } from '../liquidDoc';
 
 const defaultLogger = () => {};
 
@@ -171,6 +173,21 @@ export function startServer(
     return getDefaultSchemaTranslations();
   };
 
+  const getSnippetDefinitionForURI = async (
+    uri: string,
+    snippetName: string,
+  ): Promise<SnippetDefinition> => {
+    const rootUri = await findThemeRootURI(uri);
+    const snippetURI = path.join(rootUri, 'snippets', `${snippetName}.liquid`);
+    const snippet = documentManager.get(snippetURI);
+
+    if (!snippet || snippet.type !== SourceCodeType.LiquidHtml || isError(snippet.ast)) {
+      return { name: snippetName };
+    }
+
+    return snippet.getLiquidDoc(snippetName);
+  };
+
   const snippetFilter = ([uri]: FileTuple) => /\.liquid$/.test(uri) && /snippets/.test(uri);
   const getSnippetNamesForURI: GetSnippetNamesForURI = async (uri: string) => {
     const rootUri = await findThemeRootURI(uri);
@@ -252,6 +269,7 @@ export function startServer(
     getMetafieldDefinitions,
     getTranslationsForURI,
     getThemeSettingsSchemaForURI,
+    getSnippetDefinitionForURI,
   );
 
   const executeCommandProvider = new ExecuteCommandProvider(