@platformos/platformos-check-common 0.0.2

package/src/checks/pagination-size/index.spec.ts

@@ -0,0 +1,158 @@
+import { expect, describe, it } from 'vitest';
+import { highlightedOffenses, runLiquidCheck } from '../../test';
+import { PaginationSize } from './index';
+
+describe('Module: PaginationSize', () => {
+  it('should report an offense when paginate size is less than minSize', async () => {
+    const sourceCode = `
+      {% paginate collection.products by 0 %}
+      {% endpaginate %}
+    `;
+    const offenses = await runLiquidCheck(PaginationSize, sourceCode);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      'Pagination size must be a positive integer between 1 and 250.',
+    );
+
+    const highlights = highlightedOffenses({ 'file.liquid': sourceCode }, offenses);
+    expect(highlights).to.eql(['0']);
+  });
+
+  it('should report an offense when paginate size is greater than maxSize', async () => {
+    const sourceCode = `
+      {% paginate collection.products by 251 %}
+      {% endpaginate %}
+    `;
+
+    const offenses = await runLiquidCheck(PaginationSize, sourceCode);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      'Pagination size must be a positive integer between 1 and 250.',
+    );
+
+    const highlights = highlightedOffenses({ 'file.liquid': sourceCode }, offenses);
+    expect(highlights).to.eql(['251']);
+  });
+
+  it('should not report an offense when paginate size is within the minSize and maxSize range', async () => {
+    const sourceCode = `
+      {% paginate collection.products by 25 %}
+      {% endpaginate %}
+    `;
+
+    const offenses = await runLiquidCheck(PaginationSize, sourceCode);
+    expect(offenses).to.have.length(0);
+
+    const highlights = highlightedOffenses({ 'file.liquid': sourceCode }, offenses);
+    expect(highlights).to.be.empty;
+  });
+
+  it('should not report an offense when paginate size is a section setting with a valid default value', async () => {
+    const sourceCode = `
+      {% paginate collection.products by section.settings.products_per_page %}
+      {% endpaginate %}
+      {% schema %}
+        {
+          "name": "test",
+          "settings": [
+            {
+              "type": "number",
+              "id": "products_per_page",
+              "label": "Products per Page",
+              "default": 12
+            }
+          ]
+        }
+      {% endschema %}
+    `;
+
+    const offenses = await runLiquidCheck(PaginationSize, sourceCode);
+    expect(offenses).to.have.length(0);
+    const highlights = highlightedOffenses({ 'file.liquid': sourceCode }, offenses);
+    expect(highlights).to.be.empty;
+  });
+
+  it('should report an offense when paginate size is a section setting with an invalid default value', async () => {
+    const sourceCode = `
+      {% paginate collection.products by section.settings.products_per_page %}
+      {% endpaginate %}
+      {% schema %}
+        {
+          "name": "test",
+          "settings": [
+            {
+              "type": "number",
+              "id": "products_per_page",
+              "label": "Products per Page",
+              "default": 251
+            }
+          ]
+        }
+      {% endschema %}
+    `;
+
+    const offenses = await runLiquidCheck(PaginationSize, sourceCode);
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      `This setting's default value should be between 1 and 250 but is currently 251.`,
+    );
+    const highlights = highlightedOffenses({ 'file.liquid': sourceCode }, offenses);
+    expect(highlights).to.eql(['section.settings.products_per_page']);
+  });
+
+  it('should report an offense when paginate size is a section setting with a missing default value', async () => {
+    const sourceCode = `
+      {% paginate collection.products by section.settings.products_per_page %}
+      {% endpaginate %}
+      {% schema %}
+        {
+          "name": "test",
+          "settings": [
+            {
+              "type": "number",
+              "id": "products_per_page",
+              "label": "Products per Page"
+            }
+          ]
+        }
+      {% endschema %}
+    `;
+
+    const offenses = await runLiquidCheck(PaginationSize, sourceCode);
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      'Default pagination size should be defined in the section settings.',
+    );
+
+    const highlights = highlightedOffenses({ 'file.liquid': sourceCode }, offenses);
+    expect(highlights).to.eql(['section.settings.products_per_page']);
+  });
+
+  it('should not report an offense when settings is not an array', async () => {
+    const sourceCode = `
+      {% paginate collection.products by section.settings.products_per_page %}
+      {% endpaginate %}
+      {% schema %}
+        {
+          "name": "test",
+          "settings": {
+            "products_per_page": {
+              "type": "number",
+              "id": "products_per_page",
+              "label": "Products per Page",
+              "default": 51
+            }
+          }
+        }
+      {% endschema %}
+    `;
+
+    const offenses = await runLiquidCheck(PaginationSize, sourceCode);
+    expect(offenses).to.have.length(0);
+
+    const highlights = highlightedOffenses({ 'file.liquid': sourceCode }, offenses);
+    expect(highlights).to.be.empty;
+  });
+});

package/src/checks/pagination-size/index.ts

@@ -0,0 +1,104 @@
+import {
+  LiquidRawTag,
+  LiquidTag,
+  LiquidVariableLookup,
+  NodeTypes,
+} from '@platformos/liquid-html-parser';
+import { LiquidCheckDefinition, SchemaProp, Severity, SourceCodeType } from '../../types';
+import { isError, last } from '../../utils';
+import { isNodeOfType } from '../utils';
+import { parseJSON } from '../../json';
+
+const schema = {
+  minSize: SchemaProp.number(1),
+  maxSize: SchemaProp.number(250),
+};
+
+export const PaginationSize: LiquidCheckDefinition<typeof schema> = {
+  meta: {
+    code: 'PaginationSize',
+    name: 'Ensure paginate tags are used with performant sizes',
+    docs: {
+      description: 'This check is aimed at keeping response times low.',
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/pagination-size',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema,
+    targets: [],
+  },
+
+  create(context) {
+    const minSize = context.settings.minSize;
+    const maxSize = context.settings.maxSize;
+    let schemaSettings: any[] = [];
+    const pageSizeLookups: LiquidVariableLookup[] = [];
+
+    function checkPageSize(
+      pageSizeNode: any,
+      value: number,
+      message: string = `Pagination size must be a positive integer between ${minSize} and ${maxSize}.`,
+    ) {
+      if (minSize <= value && value <= maxSize) return;
+      context.report({
+        message,
+        startIndex: pageSizeNode.position.start,
+        endIndex: pageSizeNode.position.end,
+      });
+    }
+
+    return {
+      async LiquidTag(node: LiquidTag) {
+        if (typeof node.markup === 'string' || node.name !== 'paginate') return;
+
+        const pageSizeNode = node.markup.pageSize;
+
+        if (isNodeOfType(NodeTypes.VariableLookup, pageSizeNode)) {
+          pageSizeLookups.push(pageSizeNode);
+        } else if (isNodeOfType(NodeTypes.Number, pageSizeNode)) {
+          checkPageSize(pageSizeNode, Number(pageSizeNode.value));
+        }
+      },
+
+      async LiquidRawTag(node: LiquidRawTag) {
+        if (node.name === 'schema') {
+          const schema = parseJSON(node.body.value);
+          if (isError(schema)) return;
+          if (schema.settings && Array.isArray(schema.settings)) {
+            schemaSettings = schema.settings;
+          }
+        }
+      },
+
+      async onCodePathEnd() {
+        pageSizeLookups.forEach((pageSizeVariableLookup) => {
+          // Kind of assumes that you're using settings of some sort.
+          const lastLookup = last(pageSizeVariableLookup.lookups);
+          if (lastLookup === undefined) return;
+          if (lastLookup.type !== NodeTypes.String) return;
+
+          const settingId = lastLookup.value;
+          const setting = schemaSettings.find((setting) => setting.id === settingId);
+
+          if (setting === undefined) return;
+
+          if (setting.default === undefined) {
+            context.report({
+              message: `Default pagination size should be defined in the section settings.`,
+              startIndex: pageSizeVariableLookup.position.start,
+              endIndex: pageSizeVariableLookup.position.end,
+            });
+            return;
+          }
+
+          checkPageSize(
+            pageSizeVariableLookup,
+            setting.default,
+            `This setting's default value should be between ${minSize} and ${maxSize} but is currently ${setting.default}.`,
+          );
+        });
+      },
+    };
+  },
+};

package/src/checks/parser-blocking-script/index.spec.ts

@@ -0,0 +1,225 @@
+import { expect, describe, it } from 'vitest';
+import { ParserBlockingScript } from '.';
+import { applySuggestions, check as reportOffenses } from '../../test';
+
+describe('Module: ParserBlockingScript', () => {
+  it('should report the correct offense for the Liquid filter', async () => {
+    const file = "{{ 'asset' | script_tag }}";
+    const startIndex = file.indexOf('script_tag');
+    const endIndex = startIndex + 'script_tag'.length;
+
+    const offenses = await reportOffenses(
+      {
+        'code.liquid': file,
+      },
+      [ParserBlockingScript],
+    );
+
+    expect(offenses).to.have.length(1);
+    const { check, message, start, end } = offenses[0];
+    expect(check).to.equal(ParserBlockingScript.meta.code);
+    expect(message).to.contain('Use a <script> tag with async');
+    expect(start.index).to.equal(startIndex);
+    expect(end.index).to.equal(endIndex);
+  });
+
+  it('should report the correct offense when using the script tag', async () => {
+    const file = `
+        <script src="https://foo.bar/baz.js"></script>
+      `;
+    const startIndex = file.indexOf('<script');
+    const endIndex = file.indexOf('</script>') + '</script>'.length;
+
+    const offenses = await reportOffenses(
+      {
+        'code.liquid': file,
+      },
+      [ParserBlockingScript],
+    );
+
+    expect(offenses).to.have.length(1);
+    const { check, message, start, end } = offenses[0];
+    expect(check).to.equal(ParserBlockingScript.meta.code);
+    expect(message).to.contain('Avoid parser blocking scripts by adding `defer`');
+    expect(start.index).to.equal(startIndex);
+    expect(end.index).to.equal(endIndex);
+  });
+
+  describe('Case: LiquidFilter corrections', () => {
+    it('should suggest to replace a LiquidVariableOutput with a script tag that has the expression as URL', async () => {
+      const file = "{{ 'asset' | script_tag }}";
+      const offenses = await reportOffenses(
+        {
+          'code.liquid': file,
+        },
+        [ParserBlockingScript],
+      );
+
+      expect(offenses).to.have.length(1);
+      const offense = offenses[0]!;
+      expect(offense).to.suggest(file, `Use an HTML script tag with the defer attribute instead`, {
+        startIndex: 0,
+        endIndex: file.length,
+        insert: `<script src="{{ 'asset' }}" defer></script>`,
+      });
+      expect(offense).to.suggest(file, `Use an HTML script tag with the async attribute instead`, {
+        startIndex: 0,
+        endIndex: file.length,
+        insert: `<script src="{{ 'asset' }}" async></script>`,
+      });
+
+      const suggestions = applySuggestions(file, offense);
+      expect(suggestions).to.include(`<script src="{{ 'asset' }}" defer></script>`);
+      expect(suggestions).to.include(`<script src="{{ 'asset' }}" async></script>`);
+    });
+
+    it('should suggest to replace a LiquidVariableOutput with a script tag that has the expression and previous filters as URL', async () => {
+      const file = "{{ 'asset' | asset_url | script_tag }}";
+      const offenses = await reportOffenses(
+        {
+          'code.liquid': file,
+        },
+        [ParserBlockingScript],
+      );
+
+      expect(offenses).to.have.length(1);
+      const offense = offenses[0];
+      expect(offense).to.suggest(file, `Use an HTML script tag with the defer attribute instead`, {
+        startIndex: 0,
+        endIndex: file.length,
+        insert: `<script src="{{ 'asset' | asset_url }}" defer></script>`,
+      });
+      expect(offense).to.suggest(file, `Use an HTML script tag with the async attribute instead`, {
+        startIndex: 0,
+        endIndex: file.length,
+        insert: `<script src="{{ 'asset' | asset_url }}" async></script>`,
+      });
+
+      const suggestions = applySuggestions(file, offense);
+      expect(suggestions).to.include(`<script src="{{ 'asset' | asset_url }}" defer></script>`);
+      expect(suggestions).to.include(`<script src="{{ 'asset' | asset_url }}" async></script>`);
+    });
+
+    it('should not suggest anything if the script_tag appears in an echo tag', async () => {
+      const file = "{% echo 'asset' | asset_url | script_tag %}";
+      const offenses = await reportOffenses(
+        {
+          'code.liquid': file,
+        },
+        [ParserBlockingScript],
+      );
+
+      expect(offenses).to.have.length(1);
+      const { suggest } = offenses[0];
+      expect(suggest).not.to.exist;
+    });
+
+    it('should not suggest anything if the script_tag appears in an assign tag', async () => {
+      const file = "{% assign script = 'asset' | asset_url | script_tag %}";
+      const offenses = await reportOffenses(
+        {
+          'code.liquid': file,
+        },
+        [ParserBlockingScript],
+      );
+
+      expect(offenses).to.have.length(1);
+      const { suggest } = offenses[0];
+      expect(suggest).not.to.exist;
+    });
+
+    it('should not suggest anything if the script_tag appears in a liquid tag', async () => {
+      const file = "{% liquid\necho 'asset' | asset_url | script_tag %}";
+      const offenses = await reportOffenses(
+        {
+          'code.liquid': file,
+        },
+        [ParserBlockingScript],
+      );
+
+      expect(offenses).to.have.length(1);
+      const { suggest } = offenses[0];
+      expect(suggest).not.to.exist;
+    });
+  });
+
+  describe('Case: script tag suggestion', () => {
+    it('should suggest adding both attributes at the end', async () => {
+      const file = `<script src="a.js"></script>`;
+      const offenses = await reportOffenses({ 'code.liquid': file }, [ParserBlockingScript]);
+
+      expect(offenses).to.have.length(1);
+
+      const offense = offenses[0];
+      expect(offense).to.suggest(file, `Use an HTML script tag with the defer attribute instead`, {
+        startIndex: file.indexOf('>'),
+        endIndex: file.indexOf('>'),
+        insert: ` defer`,
+      });
+      expect(offense).to.suggest(file, `Use an HTML script tag with the async attribute instead`, {
+        startIndex: file.indexOf('>'),
+        endIndex: file.indexOf('>'),
+        insert: ` async`,
+      });
+
+      const suggestions = applySuggestions(file, offense);
+      expect(suggestions).to.include('<script src="a.js" defer></script>');
+      expect(suggestions).to.include('<script src="a.js" async></script>');
+    });
+  });
+
+  describe('No offenses', () => {
+    it('should not report any offense when async is set on a script tag', async () => {
+      const file = `
+        <script src="https://foo.bar/baz.js" async></script>
+      `;
+      const offenses = await reportOffenses(
+        {
+          'code.liquid': file,
+        },
+        [ParserBlockingScript],
+      );
+      expect(offenses).to.have.length(0);
+    });
+
+    it('should not report any offense when defer is set on a script tag', async () => {
+      const file = `
+        <script src="https://foo.bar/baz.js" defer="defer"></script>
+      `;
+      const offenses = await reportOffenses(
+        {
+          'code.liquid': file,
+        },
+        [ParserBlockingScript],
+      );
+      expect(offenses).to.have.length(0);
+    });
+
+    it('should not report any offense when async and defer are set on a script tag', async () => {
+      const file = `
+        <script src="https://foo.bar/baz.js" async defer></script>
+      `;
+      const offenses = await reportOffenses(
+        {
+          'code.liquid': file,
+        },
+        [ParserBlockingScript],
+      );
+      expect(offenses).to.have.length(0);
+    });
+
+    it('should not report any offense when using scripts of type module', async () => {
+      const file = `
+        <script src="https://foo.bar/baz.js" type="module"></script>
+        <script src="https://foo.bar/baz.js" type="importmap"></script>
+      `;
+      const offenses = await reportOffenses(
+        {
+          'code.liquid': file,
+        },
+        [ParserBlockingScript],
+      );
+      expect(offenses).to.have.length(0);
+    });
+  });
+});

package/src/checks/parser-blocking-script/index.ts

@@ -0,0 +1,91 @@
+import { NodeTypes } from '@platformos/liquid-html-parser';
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import { last } from '../../utils';
+import { hasAttributeValueOf, isAttr, isHtmlAttribute, isValuedHtmlAttribute } from '../utils';
+import { liquidFilterSuggestion, scriptTagSuggestion } from './suggestions';
+
+export const ParserBlockingScript: LiquidCheckDefinition = {
+  meta: {
+    code: 'ParserBlockingScript',
+    aliases: ['ParserBlockingScriptTag'],
+    name: 'Avoid parser blocking scripts',
+    docs: {
+      description: 'They are bad ok?',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/parser-blocking-javascript',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    return {
+      // {{ 'asset' | asset_url | script_tag }}
+      LiquidFilter: async (node, ancestors) => {
+        if (node.name !== 'script_tag') return;
+
+        const filterString = node.source.slice(node.position.start, node.position.end);
+        const offset = filterString.indexOf('script_tag');
+        const parentNode = last(ancestors);
+        const grandParentNode = last(ancestors, -1);
+
+        context.report({
+          message:
+            'The script_tag filter is parser-blocking. Use a <script> tag with async or defer for better performance',
+          startIndex: node.position.start + offset,
+          endIndex: node.position.end,
+          suggest:
+            grandParentNode &&
+            grandParentNode.type === NodeTypes.LiquidVariableOutput &&
+            parentNode &&
+            parentNode.type === NodeTypes.LiquidVariable &&
+            last(parentNode.filters) === node
+              ? [
+                  liquidFilterSuggestion('defer', node, parentNode, grandParentNode),
+                  liquidFilterSuggestion('async', node, parentNode, grandParentNode),
+                ]
+              : undefined,
+        });
+      },
+
+      // <script src="...">
+      HtmlRawNode: async (node) => {
+        if (node.name !== 'script') {
+          return;
+        }
+
+        const hasSrc = node.attributes
+          .filter(isValuedHtmlAttribute)
+          .some((attr) => isAttr(attr, 'src'));
+
+        if (!hasSrc) {
+          return;
+        }
+
+        const hasDeferOrAsync = node.attributes
+          .filter(isHtmlAttribute)
+          .some((attr) => isAttr(attr, 'async') || isAttr(attr, 'defer'));
+        const isTypeModule = node.attributes
+          .filter(isValuedHtmlAttribute)
+          .some(
+            (attr) =>
+              isAttr(attr, 'type') &&
+              (hasAttributeValueOf(attr, 'module') || hasAttributeValueOf(attr, 'importmap')),
+          );
+
+        if (hasDeferOrAsync || isTypeModule) {
+          return;
+        }
+
+        context.report({
+          message: 'Avoid parser blocking scripts by adding `defer` or `async` on this tag',
+          startIndex: node.position.start,
+          endIndex: node.position.end,
+          suggest: [scriptTagSuggestion('defer', node), scriptTagSuggestion('async', node)],
+        });
+      },
+    };
+  },
+};

package/src/checks/parser-blocking-script/suggestions.ts

@@ -0,0 +1,42 @@
+import {
+  HtmlRawNode,
+  LiquidFilter,
+  LiquidVariable,
+  LiquidVariableOutput,
+} from '@platformos/liquid-html-parser';
+import { LiquidHtmlSuggestion } from '../../types';
+import { last } from '../../utils';
+
+const suggestionMessage = (attr: 'defer' | 'async') =>
+  `Use an HTML script tag with the ${attr} attribute instead`;
+
+export const liquidFilterSuggestion = (
+  attr: 'defer' | 'async',
+  node: LiquidFilter,
+  parentNode: LiquidVariable,
+  grandParentNode: LiquidVariableOutput,
+): LiquidHtmlSuggestion => ({
+  message: suggestionMessage(attr),
+  fix(corrector) {
+    const expression = node.source.slice(
+      parentNode.expression.position.start,
+      last(parentNode.filters, -1)?.position.end ?? node.position.start,
+    );
+    const url = `{{ ${expression} }}`;
+    corrector.replace(
+      grandParentNode.position.start,
+      grandParentNode.position.end,
+      `<script src="${url}" ${attr}></script>`,
+    );
+  },
+});
+
+export const scriptTagSuggestion = (
+  attr: 'defer' | 'async',
+  node: HtmlRawNode,
+): LiquidHtmlSuggestion => ({
+  message: suggestionMessage(attr),
+  fix(corrector) {
+    corrector.insert(node.blockStartPosition.end - 1, ` ${attr}`);
+  },
+});