@platformos/platformos-check-common 0.0.2

package/src/checks/valid-block-target/index.ts

@@ -0,0 +1,142 @@
+import { nodeAtPath } from '../../json';
+import { getSchema } from '../../to-schema';
+import {
+  LiquidCheckDefinition,
+  LiteralNode,
+  Section,
+  Severity,
+  SourceCodeType,
+  ThemeBlock,
+} from '../../types';
+import {
+  getBlocks,
+  reportWarning,
+  validateBlockFileExistence,
+  validateNestedBlocks,
+  isInvalidPresetBlock,
+  isInvalidDefaultBlock,
+} from '../../utils';
+
+export const ValidBlockTarget: LiquidCheckDefinition = {
+  meta: {
+    code: 'ValidBlockTarget',
+    name: 'Validate block targeting in presets',
+    docs: {
+      description:
+        'Ensures block types only reference valid block types and respect parent-child relationships',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-block-target',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    return {
+      async LiquidRawTag(node) {
+        if (node.name !== 'schema' || node.body.kind !== 'json') return;
+
+        const offset = node.blockStartPosition.end;
+        const schema = await getSchema(context);
+        const { validSchema, ast } = schema ?? {};
+        if (!validSchema || validSchema instanceof Error) return;
+        if (!ast || ast instanceof Error) return;
+        if (!schema) return;
+        const { staticBlockDefs } = schema;
+
+        const {
+          rootLevelThemeBlocks,
+          rootLevelLocalBlocks,
+          presetLevelBlocks,
+          defaultLevelBlocks,
+        } = getBlocks(validSchema);
+
+        if (rootLevelLocalBlocks.length > 0) return;
+
+        let errorsInRootLevelBlocks = false;
+        await Promise.all(
+          rootLevelThemeBlocks.map(async ({ node, path }) => {
+            const typeNode = nodeAtPath(ast, path)! as LiteralNode;
+            const exists = await validateBlockFileExistence(node.type, context);
+            if (!exists) {
+              errorsInRootLevelBlocks = true;
+              reportWarning(blockDoesNotExistError(node.type), offset, typeNode, context);
+            }
+          }),
+        );
+
+        if (errorsInRootLevelBlocks) return;
+
+        for (const [depthStr, blocks] of Object.entries(presetLevelBlocks)) {
+          const depth = parseInt(depthStr, 10);
+
+          if (depth === 0) {
+            await Promise.all(
+              blocks.map(async ({ node, path }) => {
+                const typeNode = nodeAtPath(ast, path)! as LiteralNode;
+                const blockId = 'id' in node ? node.id! : path.at(-2)!;
+                const isStaticBlock = !!node.static;
+
+                if (isInvalidPresetBlock(blockId, node, rootLevelThemeBlocks, staticBlockDefs)) {
+                  const errorMessage = isStaticBlock
+                    ? `Could not find a static block of type "${node.type}" with id "${blockId}" in this file.`
+                    : reportMissingThemeBlockDefinitionError(node);
+                  reportWarning(errorMessage, offset, typeNode, context);
+                }
+
+                const exists = await validateBlockFileExistence(node.type, context);
+                if (exists) {
+                  if ('blocks' in node && node.blocks) {
+                    await validateNestedBlocks(
+                      context,
+                      node,
+                      node.blocks,
+                      path.slice(0, -1),
+                      offset,
+                      ast,
+                    );
+                  }
+                } else {
+                  reportWarning(blockDoesNotExistError(node.type), offset, typeNode, context);
+                }
+              }),
+            );
+          }
+        }
+
+        await Promise.all(
+          defaultLevelBlocks.map(async ({ node, path }) => {
+            const typeNode = nodeAtPath(ast, path)! as LiteralNode;
+
+            if (isInvalidDefaultBlock(node, rootLevelThemeBlocks)) {
+              reportWarning(
+                reportMissingThemeBlockDefinitionError(node),
+                offset,
+                typeNode,
+                context,
+              );
+            }
+
+            const exists = await validateBlockFileExistence(node.type, context);
+            if (!exists) {
+              reportWarning(blockDoesNotExistError(node.type), offset, typeNode, context);
+            }
+          }),
+        );
+      },
+    };
+  },
+};
+
+function reportMissingThemeBlockDefinitionError(node: Section.Block | ThemeBlock.Block) {
+  const isPrivateBlockType = node.type.startsWith('_');
+  return isPrivateBlockType
+    ? `Theme block type "${node.type}" is a private block so it must be explicitly allowed in "blocks" at the root of this schema.`
+    : `Theme block type "${node.type}" must be allowed in "blocks" at the root of this schema.`;
+}
+
+function blockDoesNotExistError(name: string) {
+  return `Theme block 'blocks/${name}.liquid' does not exist.`;
+}

package/src/checks/valid-content-for-argument-types/index.spec.ts

@@ -0,0 +1,382 @@
+import { describe, it, expect } from 'vitest';
+import { runLiquidCheck, applySuggestions } from '../../test';
+import { ValidContentForArgumentTypes } from '.';
+import { BasicParamTypes } from '../../liquid-doc/utils';
+
+describe('Module: ValidContentForParamTypes', () => {
+  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 makeBlock = (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 = `{% content_for 'block', type: 'card', param: ${value} %}`;
+            const offenses = await runLiquidCheck(
+              ValidContentForArgumentTypes,
+              sourceCode,
+              undefined,
+              {},
+              {
+                'blocks/card.liquid': makeBlock(test.type),
+              },
+            );
+            expect(offenses).toHaveLength(0);
+          });
+        });
+
+        test.invalidValues.forEach(({ value, actualType: expectedType }) => {
+          it(`should reject ${value} for ${test.type}`, async () => {
+            const sourceCode = `{% content_for 'block', type: 'card', param: ${value} %}`;
+            const offenses = await runLiquidCheck(
+              ValidContentForArgumentTypes,
+              sourceCode,
+              undefined,
+              {},
+              {
+                'blocks/card.liquid': makeBlock(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 = `{% content_for 'block', type: 'card', text: "hello", count: 5, flag: true, data: product %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/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 = `{% content_for 'block', type: 'card', title: product_title %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/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 = `{% content_for 'block', type: 'card', title: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': `<h1>This partial has no doc comment</h1>`,
+        },
+      );
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not enforce unsupported types', async () => {
+      const sourceCode = `{% content_for 'block', type: 'card', title: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/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 = `{% content_for 'block', type: 'card', title: "hello", unrecognized: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': `
+            {% doc %}
+              @param {String} title - The title
+            {% enddoc %}
+            <div>{{ title }}</div>
+          `,
+        },
+      );
+      expect(offenses).toHaveLength(0);
+    });
+  });
+
+  describe('suggestions', () => {
+    const makeBlock = (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 = `{% content_for 'block', type: 'card', param: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': makeBlock('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(`{% content_for 'block', type: 'card', param: '' %}`);
+
+      const suggestions = applySuggestions(sourceCode, offenses[0]);
+      expect(suggestions?.[1]).toEqual(`{% content_for 'block', type: 'card', param:  %}`);
+    });
+
+    it('should allow users to fix a single argument when multiple are provided`', async () => {
+      const sourceCode = `{% content_for 'block', type: 'card', title: 123, count: 5 %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/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(`{% content_for 'block', type: 'card', title: '', count: 5 %}`);
+    });
+
+    it('should handle arguments with trailing commas', async () => {
+      const sourceCode = `{% content_for 'block', type: 'card', param: 123, %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': makeBlock('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% content_for 'block', type: 'card', param: '', %}`);
+    });
+
+    it('should handle arguments with complex spacing', async () => {
+      const sourceCode = `{% content_for 'block', type: 'card',
+        title: 123,
+        count: 5
+      %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/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(`{% content_for 'block', type: 'card',
+        title: '',
+        count: 5
+      %}`);
+    });
+
+    it('should handle argument with no space after colon', async () => {
+      const sourceCode = `{% content_for 'block', type: 'card', param:123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': makeBlock('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% content_for 'block', type: 'card', param:'' %}`);
+    });
+
+    it('should handle argument with multiple spaces after colon', async () => {
+      const sourceCode = `{% content_for 'block', type: 'card', param:     123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': makeBlock('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% content_for 'block', type: 'card', param:     '' %}`);
+    });
+
+    it('should handle argument with newlines', async () => {
+      const sourceCode = `{% content_for 'block', type: 'card', param: 
+        123 
+      %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': makeBlock('string'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+
+      const result = applySuggestions(sourceCode, offenses[0]);
+      expect(result?.[0]).toEqual(`{% content_for 'block', type: 'card', param: 
+        '' 
+      %}`);
+    });
+
+    it('should suggest removal and replacement if expected type has a default value', async () => {
+      const sourceCode = `{% content_for 'block', type: 'card', param: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': makeBlock('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 = `{% content_for 'block', type: 'card', param: 123 %}`;
+      const offenses = await runLiquidCheck(
+        ValidContentForArgumentTypes,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': makeBlock('object'),
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].suggest).toHaveLength(1);
+      expect(offenses[0].suggest?.[0]?.message).toBe('Remove value');
+    });
+  });
+});

package/src/checks/valid-content-for-argument-types/index.ts

@@ -0,0 +1,42 @@
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import { ContentForMarkup } from '@platformos/liquid-html-parser';
+import {
+  findTypeMismatchParams,
+  getBlockName,
+  getLiquidDocParams,
+  reportTypeMismatches,
+} from '../../liquid-doc/arguments';
+
+export const ValidContentForArgumentTypes: LiquidCheckDefinition = {
+  meta: {
+    code: 'ValidContentForArgumentTypes',
+    name: 'Valid ContentFor Argument Types',
+    docs: {
+      description:
+        'This check ensures that arguments passed to static blocks 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-content-for-argument-types',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    return {
+      async ContentForMarkup(node: ContentForMarkup) {
+        const blockName = getBlockName(node);
+
+        if (!blockName) return;
+
+        const liquidDocParameters = await getLiquidDocParams(context, `blocks/${blockName}.liquid`);
+
+        if (!liquidDocParameters) return;
+
+        const typeMismatchParams = findTypeMismatchParams(liquidDocParameters, node.args);
+        reportTypeMismatches(context, typeMismatchParams, liquidDocParameters);
+      },
+    };
+  },
+};

package/src/checks/valid-content-for-arguments/index.spec.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import { ValidContentForArguments } from '.';
+import { runLiquidCheck } from '../../test';
+
+describe('Module: ValidContentForArguments', () => {
+  describe('{% content_for "unknown" %}', () => {
+    it('should not report offenses for strategies we do not know or support yet', async () => {
+      const offenses = await runLiquidCheck(
+        ValidContentForArguments,
+        '{% content_for "snippet", closest.product: product %}',
+      );
+      expect(offenses).toHaveLength(0);
+    });
+  });
+
+  describe('{% content_for "blocks" %}', () => {
+    it('should accept `closest.*` kwargs', async () => {
+      const offenses = await runLiquidCheck(
+        ValidContentForArguments,
+        '{% content_for "blocks", closest.product: product %}',
+      );
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not accept `context.*` kwargs', async () => {
+      const offenses = await runLiquidCheck(
+        ValidContentForArguments,
+        '{% content_for "blocks", context.product: product %}',
+      );
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0]!.message).to.equal(
+        `{% content_for "blocks" %} only accepts 'closest.*' arguments`,
+      );
+    });
+
+    it('should report offenses for non-`closest.*` kwargs', async () => {
+      const offenses = await runLiquidCheck(
+        ValidContentForArguments,
+        '{% content_for "blocks", product: product %}',
+      );
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0]!.message).to.equal(
+        `{% content_for "blocks" %} only accepts 'closest.*' arguments`,
+      );
+    });
+  });
+
+  describe('{% content_for "block", type: "", id: "" %}', () => {
+    it('should accept valid arguments', async () => {
+      const offenses = await runLiquidCheck(
+        ValidContentForArguments,
+        '{% content_for "block", type: "text", id: "static-block" %}',
+      );
+      expect(offenses).toHaveLength(0);
+    });
+
+    it(`should report an offense if 'type' is not a string`, async () => {
+      const offenses = await runLiquidCheck(
+        ValidContentForArguments,
+        '{% content_for "block", type: 10, id: "static-block" %}',
+      );
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).to.equal(`The 'type' argument should be a string`);
+    });
+
+    it(`should report an offense if 'id' is not a string`, async () => {
+      const offenses = await runLiquidCheck(
+        ValidContentForArguments,
+        '{% content_for "block", type: "foo", id: (0..10) %}',
+      );
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).to.equal(`The 'id' argument should be a string`);
+    });
+
+    it(`should accept static arguments`, async () => {
+      const offenses = await runLiquidCheck(
+        ValidContentForArguments,
+        '{% content_for "block", type: "foo", id: "id", product: product %}',
+      );
+      expect(offenses).toHaveLength(0);
+    });
+
+    it(`should report an offense for reserved arguments`, async () => {
+      const offenses = await runLiquidCheck(
+        ValidContentForArguments,
+        '{% content_for "block", type: "foo", id: "id", settings: settings %}',
+      );
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).to.equal(
+        `{% content_for "block" %} doesn't support 'settings' because it's a reserved argument.`,
+      );
+    });
+
+    it(`should report offenses for multiple reserved arguments`, async () => {
+      const offenses = await runLiquidCheck(
+        ValidContentForArguments,
+        '{% content_for "block", type: "foo", id: "id", settings: settings, section: section %}',
+      );
+      const messages = offenses.map((o) => o.message);
+
+      expect(messages).to.deep.equal([
+        `{% content_for "block" %} doesn't support 'settings' because it's a reserved argument.`,
+        `{% content_for "block" %} doesn't support 'section' because it's a reserved argument.`,
+      ]);
+    });
+  });
+});