Update stage-2 to include required field on liquid doc params

Shopify · Jan 25, 2025 · 720b222 · 720b222
1 parent d7639ef
commit 720b222
Show file tree

Hide file tree

Showing 4 changed files with 36 additions and 8 deletions.
diff --git a/.changeset/smart-onions-pump.md b/.changeset/smart-onions-pump.md
@@ -0,0 +1,5 @@
+---
+'@shopify/liquid-html-parser': minor
+---
+
+Add parser support for optional liquiddoc parameters
diff --git a/packages/liquid-html-parser/src/stage-1-cst.spec.ts b/packages/liquid-html-parser/src/stage-1-cst.spec.ts
@@ -1033,6 +1033,7 @@ describe('Unit: Stage 1 (CST)', () => {
           const testStr = `{% doc %}
           @param [paramWithNoDescription]
           @param [    paramWithWhitespace       ]
+          @param {String} [optionalParam] - The optional param
           {% enddoc %}`;
           cst = toCST(testStr);
 
@@ -1059,6 +1060,10 @@ describe('Unit: Stage 1 (CST)', () => {
           expectPath(cst, '0.children.1.paramName.locEnd').to.equal(
             testStr.indexOf('paramWithWhitespace') + 'paramWithWhitespace'.length,
           );
+
+          expectPath(cst, '0.children.2.type').to.equal('LiquidDocParamNode');
+          expectPath(cst, '0.children.2.required').to.equal(false);
+          expectPath(cst, '0.children.2.paramType.value').to.equal('String');
         });
 
         it('should parse @param with missing optional delimiters as required', () => {

diff --git a/packages/liquid-html-parser/src/stage-2-ast.spec.ts b/packages/liquid-html-parser/src/stage-2-ast.spec.ts
@@ -1231,7 +1231,8 @@ describe('Unit: Stage 2 (AST)', () => {
 
       ast = toLiquidAST(`
         {% doc -%}
-        @param asdf
+        @param requiredParameter
+        @param [optionalParameter] - optional parameter description
         @param {String} paramWithDescription - param with description and \`punctation\`. This is still a valid param description.
         @unsupported this node falls back to a text node
         {%- enddoc %}
@@ -1240,22 +1241,36 @@ describe('Unit: Stage 2 (AST)', () => {
       expectPath(ast, 'children.0.name').to.eql('doc');
       expectPath(ast, 'children.0.body.nodes.0.type').to.eql('LiquidDocParamNode');
       expectPath(ast, 'children.0.body.nodes.0.name').to.eql('param');
+      expectPath(ast, 'children.0.body.nodes.0.required').to.eql(true);
       expectPath(ast, 'children.0.body.nodes.0.paramName.type').to.eql('TextNode');
-      expectPath(ast, 'children.0.body.nodes.0.paramName.value').to.eql('asdf');
+      expectPath(ast, 'children.0.body.nodes.0.paramName.value').to.eql('requiredParameter');
       expectPath(ast, 'children.0.body.nodes.0.paramDescription.type').to.eql('TextNode');
       expectPath(ast, 'children.0.body.nodes.0.paramDescription.value').to.eql('');
+
       expectPath(ast, 'children.0.body.nodes.1.type').to.eql('LiquidDocParamNode');
       expectPath(ast, 'children.0.body.nodes.1.name').to.eql('param');
+      expectPath(ast, 'children.0.body.nodes.1.required').to.eql(false);
       expectPath(ast, 'children.0.body.nodes.1.paramName.type').to.eql('TextNode');
-      expectPath(ast, 'children.0.body.nodes.1.paramName.value').to.eql('paramWithDescription');
+      expectPath(ast, 'children.0.body.nodes.1.paramName.value').to.eql('optionalParameter');
       expectPath(ast, 'children.0.body.nodes.1.paramDescription.type').to.eql('TextNode');
       expectPath(ast, 'children.0.body.nodes.1.paramDescription.value').to.eql(
+        'optional parameter description',
+      );
+
+      expectPath(ast, 'children.0.body.nodes.2.type').to.eql('LiquidDocParamNode');
+      expectPath(ast, 'children.0.body.nodes.2.name').to.eql('param');
+      expectPath(ast, 'children.0.body.nodes.2.required').to.eql(true);
+      expectPath(ast, 'children.0.body.nodes.2.paramName.type').to.eql('TextNode');
+      expectPath(ast, 'children.0.body.nodes.2.paramName.value').to.eql('paramWithDescription');
+      expectPath(ast, 'children.0.body.nodes.2.paramDescription.type').to.eql('TextNode');
+      expectPath(ast, 'children.0.body.nodes.2.paramDescription.value').to.eql(
         'param with description and `punctation`. This is still a valid param description.',
       );
-      expectPath(ast, 'children.0.body.nodes.1.paramType.type').to.eql('TextNode');
-      expectPath(ast, 'children.0.body.nodes.1.paramType.value').to.eql('String');
-      expectPath(ast, 'children.0.body.nodes.2.type').to.eql('TextNode');
-      expectPath(ast, 'children.0.body.nodes.2.value').to.eql(
+      expectPath(ast, 'children.0.body.nodes.2.paramType.type').to.eql('TextNode');
+      expectPath(ast, 'children.0.body.nodes.2.paramType.value').to.eql('String');
+
+      expectPath(ast, 'children.0.body.nodes.3.type').to.eql('TextNode');
+      expectPath(ast, 'children.0.body.nodes.3.value').to.eql(
         '@unsupported this node falls back to a text node',
       );
     });

diff --git a/packages/liquid-html-parser/src/stage-2-ast.ts b/packages/liquid-html-parser/src/stage-2-ast.ts
@@ -755,7 +755,7 @@ export interface TextNode extends ASTNode<NodeTypes.TextNode> {
   value: string;
 }
 
-/** Represents a `@param` node in a LiquidDoc comment - `@param paramName {paramType} - paramDescription` */
+/** Represents a `@param` node in a LiquidDoc comment - `@param {paramType} [paramName]  - paramDescription` */
 export interface LiquidDocParamNode extends ASTNode<NodeTypes.LiquidDocParamNode> {
   name: 'param';
   /** The name of the parameter (e.g. "product") */
@@ -764,6 +764,8 @@ export interface LiquidDocParamNode extends ASTNode<NodeTypes.LiquidDocParamNode
   paramDescription: TextNode | null;
   /** Optional type annotation for the parameter (e.g. "{string}", "{number}") */
   paramType: TextNode | null;
+  /** Whether this parameter must be passed when using the snippet */
+  required: boolean;
 }
 export interface ASTNode<T> {
   /**
@@ -1293,6 +1295,7 @@ function buildAst(
           },
           paramDescription: toNullableTextNode(node.paramDescription),
           paramType: toNullableTextNode(node.paramType),
+          required: node.required,
         });
         break;
       }