Parser + Prettier - Add dash-seperator for liquidDoc Param Descriptions

Shopify · Dec 11, 2024 · 434b276 · 434b276
1 parent e4fb275
commit 434b276
Show file tree

Hide file tree

Showing 5 changed files with 34 additions and 7 deletions.
diff --git a/packages/liquid-html-parser/grammar/liquid-html.ohm b/packages/liquid-html-parser/grammar/liquid-html.ohm
@@ -395,7 +395,7 @@ LiquidDoc <: Helpers {
     | fallbackNode
 
   fallbackNode = "@" anyExceptStar<newline>
-  paramNode = "@param" space* (paramType)? space* (paramName)? paramDescription?
+  paramNode = "@param" space* (paramType)? space* (paramName)? space* "-"? paramDescription?
   paramType = "{" anyExceptStar<"}"> "}"
   paramName = identifierCharacter+
   paramDescription = (~newline identifierCharacter | space)+

diff --git a/packages/liquid-html-parser/src/stage-1-cst.spec.ts b/packages/liquid-html-parser/src/stage-1-cst.spec.ts
@@ -1058,6 +1058,19 @@ describe('Unit: Stage 1 (CST)', () => {
           );
         });
 
+        it('should parse @param with description seperated by a dash', () => {
+          const testStr = `{% doc %}
+            @param dashWithSpace - param with description
+            @param dashWithNoSpace -param with description
+            @param notDashSeparated param with description
+          {% enddoc %}`;
+          cst = toCST(testStr);
+
+          expectPath(cst, '0.children.0.paramDescription.dashSeparated').to.equal(true);
+          expectPath(cst, '0.children.1.paramDescription.dashSeparated').to.equal(true);
+          expectPath(cst, '0.children.2.paramDescription.dashSeparated').to.equal(false);
+        });
+
         it('should parse unsupported doc tags as text nodes', () => {
           const testStr = `{% doc %} @unsupported this tag is not supported {% enddoc %}`;
           cst = toCST(testStr);

diff --git a/packages/liquid-html-parser/src/stage-1-cst.ts b/packages/liquid-html-parser/src/stage-1-cst.ts
@@ -113,10 +113,16 @@ export interface ConcreteLiquidDocParamNode
   name: string;
   value: string;
   paramName: ConcreteTextNode;
-  paramDescription: ConcreteTextNode;
+  paramDescription: ConcreteLiquidDocParamDescription;
   paramType: ConcreteTextNode;
 }
 
+export interface ConcreteLiquidDocParamDescription
+  extends ConcreteBasicNode<ConcreteNodeTypes.TextNode> {
+  dashSeparated: boolean;
+  value: string;
+}
+
 export interface ConcreteHtmlNodeBase<T> extends ConcreteBasicNode<T> {
   attrList?: ConcreteAttributeNode[];
 }
@@ -1358,13 +1364,15 @@ function toLiquidDocAST(source: string, matchingSource: string, offset: number)
         };
       },
       paramDescription: function (nodes: Node[]) {
-        const descriptionNode = nodes[5];
+        const dashNode = nodes[6];
+        const descriptionNode = nodes[7];
         return {
           type: ConcreteNodeTypes.TextNode,
           value: descriptionNode.sourceString.trim(),
           source,
           locStart: offset + descriptionNode.source.startIdx,
           locEnd: offset + descriptionNode.source.endIdx,
+          dashSeparated: dashNode.sourceString.trim() === '-',
         };
       },
     },

diff --git a/packages/liquid-html-parser/src/stage-2-ast.spec.ts b/packages/liquid-html-parser/src/stage-2-ast.spec.ts
@@ -1232,7 +1232,7 @@ describe('Unit: Stage 2 (AST)', () => {
       ast = toLiquidAST(`
         {% doc -%}
         @param asdf
-        @param {String} paramWithDescription param with description
+        @param {String} paramWithDescription - param with description
         @unsupported this node falls back to a text node
         {%- enddoc %}
       `);
@@ -1244,18 +1244,18 @@ describe('Unit: Stage 2 (AST)', () => {
       expectPath(ast, 'children.0.body.nodes.0.paramName.value').to.eql('asdf');
       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.0.paramDescription.dashSeparated').to.eql(false);
       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.dashSeparated').to.eql(true);
       expectPath(ast, 'children.0.body.nodes.1.paramDescription.value').to.eql(
         'param with 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(
         '@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
@@ -758,11 +758,16 @@ export interface TextNode extends ASTNode<NodeTypes.TextNode> {
 export interface LiquidDocParamNode extends ASTNode<NodeTypes.LiquidDocParamNode> {
   name: string;
   value: string;
-  paramDescription: TextNode;
+  paramDescription: LiquidDocParamDescription;
   paramName: TextNode;
   paramType: TextNode;
 }
 
+export interface LiquidDocParamDescription extends ASTNode<NodeTypes.TextNode> {
+  dashSeparated: boolean;
+  value: string;
+}
+
 export interface ASTNode<T> {
   /**
    * The type of the node, as a string.
@@ -1295,6 +1300,7 @@ function buildAst(
             value: node.paramDescription.value,
             position: position(node.paramDescription),
             source: node.paramDescription.source,
+            dashSeparated: node.paramDescription.dashSeparated,
           },
           paramType: {
             type: NodeTypes.TextNode,