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

Author: jamesmengo

.changeset/smart-onions-pump.md

@@ -0,0 +1,5 @@
+---
+'@shopify/liquid-html-parser': minor
+---
+
+Add parser support for optional liquiddoc parameters

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', () => {

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

@@ -1231,7 +1231,8 @@ describe('Unit: Stage 2 (AST)', () => {
 
       ast = toLiquidAST(`
         {% doc -%}
-        @param paramWithNoType
+        @param requiredParamWithNoType
+        @param [optionalParameter] - optional parameter description
         @param {String} paramWithDescription - param with description and \`punctation\`. This is still a valid param description.
         @param {String} paramWithNoDescription
         @unsupported this node falls back to a text node
@@ -1242,34 +1243,43 @@ describe('Unit: Stage 2 (AST)', () => {
 
       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('paramWithNoType');
+      expectPath(ast, 'children.0.body.nodes.0.paramName.value').to.eql('requiredParamWithNoType');
       expectPath(ast, 'children.0.body.nodes.0.paramType').to.be.null;
       expectPath(ast, 'children.0.body.nodes.0.paramDescription').to.be.null;
 
       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(
-        'param with description and `punctation`. This is still a valid param description.',
+        'optional parameter 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.1.paramType').to.be.null;
+      expectPath(ast, 'children.0.body.nodes.1.paramType').to.be.null;
 
       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('paramWithNoDescription');
-      expectPath(ast, 'children.0.body.nodes.2.paramDescription').to.be.null;
+      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.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',
-      );
+      expectPath(ast, 'children.0.body.nodes.3.type').to.eql('LiquidDocParamNode');
+      expectPath(ast, 'children.0.body.nodes.3.name').to.eql('param');
+      expectPath(ast, 'children.0.body.nodes.2.paramName.type').to.eql('TextNode');
+      expectPath(ast, 'children.0.body.nodes.3.paramName.value').to.eql('paramWithNoDescription');
+      expectPath(ast, 'children.0.body.nodes.3.paramDescription').to.be.null;
+      expectPath(ast, 'children.0.body.nodes.3.paramType.type').to.eql('TextNode');
+      expectPath(ast, 'children.0.body.nodes.3.paramType.value').to.eql('String');
     });
 
     it('should parse unclosed tables with assignments', () => {

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;
       }