@platformos/platformos-check-common 0.0.2

package/src/checks/valid-render-partial-argument-types/index.spec.ts

@@ -0,0 +1,468 @@
+import { describe, it, expect } from 'vitest';
+import { runLiquidCheck, applySuggestions } from '../../test';
+import { ValidRenderPartialArgumentTypes } from '.';
+import { BasicParamTypes } from '../../liquid-doc/utils';
+
+describe('Module: ValidRenderPartialParamTypes', () => {
+  describe('type validation', () => {
+    const typeTests = [
+      {
+        type: 'string',
+        validValues: ["'hello'", "''", 'product'],
+        invalidValues: [
+          { value: '123', actualType: BasicParamTypes.Number },
+          { value: 'true', actualType: BasicParamTypes.Boolean },
+        ],
+      },
+      {
+        type: 'number',
+        validValues: ['0', '123', '-1', 'product'],
+        invalidValues: [
+          { value: "'hello'", actualType: BasicParamTypes.String },
+          { value: 'true', actualType: BasicParamTypes.Boolean },
+        ],
+      },
+      {
+        type: 'boolean',
+        validValues: ['true', 'false', 'nil', 'empty', 'product', '123', "'hello'"],
+        invalidValues: [],
+      },
+      {
+        type: 'object',
+        validValues: ['product', '(1..3)'],
+        invalidValues: [
+          { value: "'hello'", actualType: BasicParamTypes.String },
+          { value: '123', actualType: BasicParamTypes.Number },
+          { value: 'true', actualType: BasicParamTypes.Boolean },
+          { value: 'empty', actualType: BasicParamTypes.Boolean },
+        ],
+      },
+    ];
+
+    for (const test of typeTests) {
+      describe(`${test.type} validation`, () => {
+        const makeSnippet = (type: string) => `
+          {% doc %}
+            @param {${type}} param - Description
+          {% enddoc %}
+          <div>{{ param }}</div>
+        `;
+
+        test.validValues.forEach((value) => {
+          it(`should accept ${value} for ${test.type}`, async () => {
+            const sourceCode = `{% render 'card', param: ${value} %}`;
+            const offenses = await runLiquidCheck(
+              ValidRenderPartialArgumentTypes,
+              sourceCode,
+              undefined,
+              {},
+              {
+                'app/views/partials/card.liquid': makeSnippet(test.type),
+              },
+            );
+            expect(offenses).toHaveLength(0);
+          });
+        });
+
+        test.invalidValues.forEach(({ value, actualType: expectedType }) => {
+          it(`should reject ${value} for ${test.type}`, async () => {
+            const sourceCode = `{% render 'card', param: ${value} %}`;
+            const offenses = await runLiquidCheck(
+              ValidRenderPartialArgumentTypes,
+              sourceCode,
+              undefined,
+              {},
+              {
+                'app/views/partials/card.liquid': makeSnippet(test.type),
+              },
+            );
+            expect(offenses).toHaveLength(1);
+            expect(offenses[0].message).toBe(
+              `Type mismatch for argument 'param': expected ${test.type}, got ${expectedType}`,
+            );
+          });
+        });
+      });
+    }
+  });
+
+  describe('edge cases', () => {
+    it('should handle mixed case type annotations', async () => {
+      const sourceCode = `{% render 'card', text: "hello", count: 5, flag: true, data: product %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': `
+            {% doc %}
+              @param {String} text - The text
+              @param {NUMBER} count - The count
+              @param {BOOLEAN} flag - The flag
+              @param {Object} data - The data
+            {% enddoc %}
+            <div>{{ text }}{{ count }}{{ flag }}{{ data }}</div>
+          `,
+        },
+      );
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should ignore variable lookups', async () => {
+      const sourceCode = `{% render 'card', title: product_title %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': `
+            {% doc %}
+              @param {String} title - The title
+            {% enddoc %}
+            <div>{{ title }}</div>
+          `,
+        },
+      );
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not report when partial has no doc comment', async () => {
+      const sourceCode = `{% render 'card', title: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': `<h1>This partial has no doc comment</h1>`,
+        },
+      );
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not enforce unsupported types', async () => {
+      const sourceCode = `{% render 'card', title: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': `
+            {% doc %}
+              @param {Unsupported} title - The title
+            {% enddoc %}
+            <div>{{ title }}</div>
+          `,
+        },
+      );
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not report for unrecognized arguments', async () => {
+      const sourceCode = `{% render 'card', title: "hello", unrecognized: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': `
+            {% doc %}
+              @param {String} title - The title
+            {% enddoc %}
+            <div>{{ title }}</div>
+          `,
+        },
+      );
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should report when `with` alias is used', async () => {
+      const sourceCode = `{% render 'card' with 12 as title %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': `
+          {% doc %}
+            @param {String} title - The title
+          {% enddoc %}
+          <div>{{ title }}</div>
+        `,
+        },
+      );
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toBe(
+        "Type mismatch for argument 'title': expected string, got number",
+      );
+    });
+
+    it('should report when `for` alias is used', async () => {
+      const sourceCode = `{% render 'card' for 123 as title %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': `
+          {% doc %}
+            @param {String} title - The title
+          {% enddoc %}
+          <div>{{ title }}</div>
+        `,
+        },
+      );
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toBe(
+        "Type mismatch for argument 'title': expected string, got number",
+      );
+    });
+  });
+
+  describe('suggestions', () => {
+    const makeSnippet = (type: string) => `
+      {% doc %}
+        @param {${type}} param - Description
+      {% enddoc %}
+      <div>{{ param }}</div>
+    `;
+
+    it('should suggest replacing with default value for type or removing value', async () => {
+      const sourceCode = `{% render 'card', param: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': makeSnippet('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].suggest).toHaveLength(2);
+      expect(offenses[0].suggest?.[0]?.message).toBe("Replace with default value '''' for string");
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% render 'card', param: '' %}`);
+
+      const suggestions = applySuggestions(sourceCode, offenses[0]);
+      expect(suggestions?.[1]).toEqual(`{% render 'card', param:  %}`);
+    });
+
+    it('should allow users to fix a single argument when multiple are provided`', async () => {
+      const sourceCode = `{% render 'card', title: 123, count: 5 %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': `
+          {% doc %}
+            @param {string} title - The title
+            @param {number} count - The count
+          {% enddoc %}
+          <div>{{ title }} {{ count }}</div>
+        `,
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toBe(
+        "Type mismatch for argument 'title': expected string, got number",
+      );
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% render 'card', title: '', count: 5 %}`);
+    });
+
+    it('should handle arguments with trailing commas', async () => {
+      const sourceCode = `{% render 'card', param: 123, %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': makeSnippet('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% render 'card', param: '', %}`);
+    });
+
+    it('should handle arguments with complex spacing', async () => {
+      const sourceCode = `{% render 'card',
+        title: 123,
+        count: 5
+      %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': `
+          {% doc %}
+            @param {string} title - The title
+            @param {number} count - The count
+          {% enddoc %}
+        `,
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% render 'card',
+        title: '',
+        count: 5
+      %}`);
+    });
+
+    it('should handle argument with no space after colon', async () => {
+      const sourceCode = `{% render 'card', param:123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': makeSnippet('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% render 'card', param:'' %}`);
+    });
+
+    it('should handle argument with multiple spaces after colon', async () => {
+      const sourceCode = `{% render 'card', param:     123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': makeSnippet('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% render 'card', param:     '' %}`);
+    });
+
+    it('should handle argument with newlines', async () => {
+      const sourceCode = `{% render 'card', param: 
+        123 
+      %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': makeSnippet('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% render 'card', param: 
+        '' 
+      %}`);
+    });
+
+    it('should suggest removal and replacement if expected type has a default value', async () => {
+      const sourceCode = `{% render 'card', param: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': makeSnippet('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].suggest).toHaveLength(2);
+      expect(offenses[0].suggest?.[0]?.message).toBe("Replace with default value '''' for string");
+      expect(offenses[0].suggest?.[1]?.message).toBe('Remove value');
+    });
+
+    it("should only suggest removal if expected type default value is ''", async () => {
+      const sourceCode = `{% render 'card', param: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': makeSnippet('object'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].suggest).toHaveLength(1);
+      expect(offenses[0].suggest?.[0]?.message).toBe('Remove value');
+    });
+
+    it('should handle when aliases `with` syntax is used', async () => {
+      const sourceCode = `{% render 'card' with 123 as param %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': makeSnippet('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toBe(
+        "Type mismatch for argument 'param': expected string, got number",
+      );
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% render 'card' with '' as param %}`);
+    });
+
+    it('should handle when aliases `for` syntax is used', async () => {
+      const sourceCode = `{% render 'card' for 123 as param %}`;
+      const offenses = await runLiquidCheck(
+        ValidRenderPartialArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'app/views/partials/card.liquid': makeSnippet('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toBe(
+        "Type mismatch for argument 'param': expected string, got number",
+      );
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% render 'card' for '' as param %}`);
+    });
+  });
+});

package/src/checks/valid-render-partial-argument-types/index.ts

@@ -0,0 +1,89 @@
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import { NodeTypes, RenderMarkup } from '@platformos/liquid-html-parser';
+import { LiquidDocParameter } from '../../liquid-doc/liquidDoc';
+import { inferArgumentType, isTypeCompatible } from '../../liquid-doc/utils';
+import {
+  findTypeMismatchParams,
+  generateTypeMismatchSuggestions,
+  getLiquidDocParams,
+  getPartialName,
+  reportTypeMismatches,
+} from '../../liquid-doc/arguments';
+
+export const ValidRenderPartialArgumentTypes: LiquidCheckDefinition = {
+  meta: {
+    code: 'ValidRenderPartialArgumentTypes',
+    name: 'Valid Render Partial Argument Types',
+    aliases: ['ValidRenderPartialParamTypes'],
+    docs: {
+      description:
+        'This check ensures that arguments passed to partial match the expected types defined in the liquidDoc header if present.',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-render-partial-argument-types',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    /**
+     * Checks for type mismatches when alias is used with `for` or `with` syntax.
+     * This can be refactored at a later date to share more code with regular named arguments as they are both backed by LiquidExpression nodes.
+     *
+     * E.g. {% render 'card' with 123 as title %}
+     */
+    function findAndReportAliasType(
+      node: RenderMarkup,
+      liquidDocParameters: Map<string, LiquidDocParameter>,
+    ) {
+      if (
+        node.alias &&
+        node.variable?.name &&
+        node.variable.name.type !== NodeTypes.VariableLookup
+      ) {
+        const paramIsDefinedWithType = liquidDocParameters
+          .get(node.alias.value)
+          ?.type?.toLowerCase();
+        if (paramIsDefinedWithType) {
+          const providedParamType = inferArgumentType(node.variable.name);
+          if (!isTypeCompatible(paramIsDefinedWithType, providedParamType)) {
+            const suggestions = generateTypeMismatchSuggestions(
+              paramIsDefinedWithType,
+              node.variable.name.position.start,
+              node.variable.name.position.end,
+            );
+
+            context.report({
+              message: `Type mismatch for argument '${node.alias.value}': expected ${paramIsDefinedWithType}, got ${providedParamType}`,
+              startIndex: node.variable.name.position.start,
+              endIndex: node.variable.name.position.end,
+              suggest: suggestions,
+            });
+          }
+        }
+      }
+    }
+
+    return {
+      async RenderMarkup(node: RenderMarkup) {
+        const partialName = getPartialName(node);
+
+        if (!partialName) return;
+
+        const liquidDocParameters = await getLiquidDocParams(
+          context,
+          `app/views/partials/${partialName}.liquid`,
+        );
+
+        if (!liquidDocParameters) return;
+
+        findAndReportAliasType(node, liquidDocParameters);
+
+        const typeMismatchParams = findTypeMismatchParams(liquidDocParameters, node.args);
+        reportTypeMismatches(context, typeMismatchParams, liquidDocParameters);
+      },
+    };
+  },
+};