[LiquidDoc] Parsing support for optional parameters and default values

----
- Added a parameter `required` to the LiquidDocParamNode
- By default, parameters are required unless they have `[]` around the name
- Parameters with incomplete delimiters `e.g. ([missingTail)` will map to a `TextNode`
- Default values are supported for optional parameters - `[param=default]`
- Default values will match anything between `=` and `]`. Leading and Trailing spaces are trimmed.

I originally tried accessing everything from the top level in the param node.
This is still the goal, but I think this should be done at stage 2 so that we can leverage the recursive nature of how to-AST works.
My original approach attempted to Write everything to the top level in stage 1, but we should be doing this in stage 2.

Author: jamesmengo

.changeset/chatty-scissors-relax.md

@@ -0,0 +1,6 @@
+---
+'@shopify/liquid-html-parser': minor
+'theme-check-vscode': minor
+---
+
+Add support for parsing optional parameters in LiquidDoc. Optional parameters are designated by wrapping the name in square brackets, and can accept a default value (e.g. `@param [parameter_name=default]`).

.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/grammar/liquid-html.ohm

@@ -398,14 +398,28 @@ LiquidDoc <: Helpers {
   strictSpace = " " | "\t"
   // We use this as an escape hatch to stop matching TextNode and try again when one of these characters is encountered 
   openControl:= "@" | end
+  // We use this to map text values into a textNodes via mappings in stage-1-cst.ts
+  textValue = identifierCharacter+
 
   fallbackNode = "@" anyExceptStar<endOfParam>
-  paramNode = "@param" strictSpace* paramType? strictSpace* paramName (strictSpace* "-")? strictSpace* paramDescription
+  paramNode = "@param" strictSpace* paramType? strictSpace* (paramName | optionalParamName) (strictSpace* "-")? strictSpace* paramDescription
+
   paramType = "{" strictSpace* paramTypeContent strictSpace* "}"
   paramTypeContent = anyExceptStar<("}"| strictSpace)>
-  paramName = identifierCharacter+
-  paramDescription = anyExceptStar<endOfParam>
+
+  paramDescription = (~"]" anyExceptStar<endOfParam>)
   endOfParam = strictSpace* (newline | end)
+
+  // Required parameter name - e.g. "paramName"
+  paramName = textValue
+  // Optional parameter name - e.g. "[paramName]"
+  optionalParamName = "[" strictSpace* optionalParamNameContent strictSpace* "]"
+  // Content of an optional parameter name - e.g. "paramName=defaultValue"
+  optionalParamNameContent = strictSpace* textValue strictSpace* optionalParamNameDefaultValue?
+  // Default value of an optional parameter name - e.g. "=defaultValue"
+  optionalParamNameDefaultValue = "=" strictSpace* optionalParamNameDefaultContent
+  optionalParamNameDefaultContent = anyExceptPlus<endOfOptionalParamNameDefaultValue>
+  endOfOptionalParamNameDefaultValue = strictSpace* "]"
 }
 
 LiquidHTML <: Liquid {

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

@@ -85,6 +85,7 @@ export enum ConcreteNodeTypes {
   ContentForNamedArgument = 'ContentForNamedArgument',
 
   LiquidDocParamNode = 'LiquidDocParamNode',
+  LiquidDocParamNameNode = 'LiquidDocParamNameNode',
 }
 
 export const LiquidLiteralValues = {
@@ -110,11 +111,18 @@ export interface ConcreteBasicNode<T> {
 export interface ConcreteLiquidDocParamNode
   extends ConcreteBasicNode<ConcreteNodeTypes.LiquidDocParamNode> {
   name: 'param';
-  paramName: ConcreteTextNode;
+  paramName: ConcreteLiquidDocParamNameNode;
   paramDescription: ConcreteTextNode | null;
   paramType: ConcreteTextNode | null;
 }
 
+export interface ConcreteLiquidDocParamNameNode
+  extends ConcreteBasicNode<ConcreteNodeTypes.LiquidDocParamNameNode> {
+  required: boolean;
+  defaultValue: ConcreteTextNode | null;
+  paramNameContent: ConcreteTextNode;
+}
+
 export interface ConcreteHtmlNodeBase<T> extends ConcreteBasicNode<T> {
   attrList?: ConcreteAttributeNode[];
 }
@@ -1344,7 +1352,28 @@ function toLiquidDocAST(source: string, matchingSource: string, offset: number)
     },
     paramType: 2,
     paramTypeContent: textNode,
-    paramName: textNode,
+    paramName: {
+      type: ConcreteNodeTypes.LiquidDocParamNameNode,
+      paramNameContent: 0,
+      locStart,
+      locEnd,
+      source,
+      required: true,
+      defaultValue: null,
+    },
+    optionalParamName: 2,
+    optionalParamNameContent: {
+      type: ConcreteNodeTypes.LiquidDocParamNameNode,
+      paramNameContent: 1,
+      required: false,
+      defaultValue: 3,
+      locStart,
+      locEnd,
+      source,
+    },
+    optionalParamNameDefaultValue: 2,
+    optionalParamNameDefaultContent: textNode,
+    textValue: textNode,
     paramDescription: textNode,
     fallbackNode: textNode,
   };

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

@@ -1220,56 +1220,72 @@ describe('Unit: Stage 2 (AST)', () => {
       expectPath(ast, 'children.0.markup.1.children.0.children.1.markup.name').to.eql('var3');
     });
 
-    it(`should parse doc tags`, () => {
-      ast = toLiquidAST(`{% doc %}{% enddoc %}`);
-      expectPath(ast, 'children.0.type').to.eql('LiquidRawTag');
-      expectPath(ast, 'children.0.name').to.eql('doc');
-      expectPath(ast, 'children.0.markup').toEqual('');
-      expectPath(ast, 'children.0.body.value').to.eql('');
-      expectPath(ast, 'children.0.body.type').toEqual('RawMarkup');
-      expectPath(ast, 'children.0.body.nodes').toEqual([]);
-
-      ast = toLiquidAST(`
+    describe('LiquidDoc', () => {
+      it(`should parse liquid doc tags`, () => {
+        ast = toLiquidAST(`{% doc %}{% enddoc %}`);
+        expectPath(ast, 'children.0.type').to.eql('LiquidRawTag');
+        expectPath(ast, 'children.0.name').to.eql('doc');
+        expectPath(ast, 'children.0.markup').toEqual('');
+        expectPath(ast, 'children.0.body.value').to.eql('');
+        expectPath(ast, 'children.0.body.type').toEqual('RawMarkup');
+        expectPath(ast, 'children.0.body.nodes').toEqual([]);
+
+        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
+        @param [optionalParameterWithDefault=defaultValue] - optional parameter description with default
+        @param {String} [optionalParameterWithDefaultAndType=defaultValue]
         {%- 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('LiquidDocParamNode');
-      expectPath(ast, 'children.0.body.nodes.0.name').to.eql('param');
-      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.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.paramName.type').to.eql('TextNode');
-      expectPath(ast, 'children.0.body.nodes.1.paramName.value').to.eql('paramWithDescription');
-      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.',
-      );
-      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('LiquidDocParamNode');
-      expectPath(ast, 'children.0.body.nodes.2.name').to.eql('param');
-      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.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.type').to.eql('LiquidRawTag');
+        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(
+          '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('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.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('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('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.spec.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=defaultValue]  - paramDescription` */
 export interface LiquidDocParamNode extends ASTNode<NodeTypes.LiquidDocParamNode> {
   name: 'param';
   /** The name of the parameter (e.g. "product") */
@@ -764,6 +764,10 @@ 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;
+  /** The default value of the parameter (e.g. "10") - null if the parameter is required or has no default value */
+  defaultValue: TextNode | null;
 }
 export interface ASTNode<T> {
   /**
@@ -1287,12 +1291,14 @@ function buildAst(
           source: node.source,
           paramName: {
             type: NodeTypes.TextNode,
-            value: node.paramName.value,
+            value: node.paramName.paramNameContent.value,
             position: position(node.paramName),
             source: node.paramName.source,
           },
           paramDescription: toNullableTextNode(node.paramDescription),
           paramType: toNullableTextNode(node.paramType),
+          required: node.paramName.required,
+          defaultValue: toNullableTextNode(node.paramName.defaultValue),
         });
         break;
       }