@platformos/platformos-check-common 0.0.2

package/src/checks/metadata-params/index.ts

@@ -0,0 +1,119 @@
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import yaml from 'js-yaml';
+import { DocumentsLocator, DocumentType } from '@platformos/platformos-common';
+import { URI } from 'vscode-uri';
+import { LiquidNamedArgument, Position } from '@platformos/liquid-html-parser';
+import { getLiquidDocParams } from '../../liquid-doc/arguments';
+import { relative } from '../../path';
+
+type Metadata = {
+  metadata: {
+    params: Record<string, unknown>;
+  };
+};
+
+function extractMetadataParams(source: string): string[] | null {
+  source = source.trim();
+  if (!source.startsWith('---')) return null;
+
+  const end = source.indexOf('---', 3);
+  if (end === -1) return null;
+
+  const yamlBlock = source.slice(3, end).trim();
+  try {
+    const result = yaml.load(yamlBlock) as Metadata;
+    return Object.keys(result.metadata.params);
+  } catch (e) {
+    return null;
+  }
+}
+
+export const MetadataParamsCheck: LiquidCheckDefinition = {
+  meta: {
+    code: 'MetadataParamsCheck',
+    name: 'Metadata Params Check',
+    docs: {
+      description:
+        'Ensures that parameters referenced in the document exist in metadata.params or in the doc tag.',
+      recommended: true,
+      url: undefined,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    const locator = new DocumentsLocator(context.fs);
+
+    const validate = async (
+      nodeType: DocumentType,
+      targetFile: string,
+      args: LiquidNamedArgument[],
+      position: Position,
+    ) => {
+      const locatedFile = await locator.locate(
+        URI.parse(context.config.rootUri),
+        nodeType,
+        targetFile,
+      );
+
+      if (!locatedFile) {
+        return;
+      }
+      let params = extractMetadataParams(await context.fs.readFile(locatedFile));
+      if (!params) {
+        const liquidDocParameters = await getLiquidDocParams(
+          context,
+          relative(locatedFile, context.config.rootUri),
+        );
+
+        if (!liquidDocParameters) return;
+
+        params = Array.from(liquidDocParameters.values())
+          .filter((p) => p.required)
+          .map((p) => p.name);
+      }
+
+      args
+        .filter((arg) => !params.includes(arg.name))
+        .forEach((arg) => {
+          context.report({
+            message: `Unknown parameter ${arg.name} passed to ${nodeType} call`,
+            startIndex: arg.position.start,
+            endIndex: arg.position.end,
+          });
+        });
+
+      params
+        .filter((param) => !args.find((arg) => arg.name === param))
+        .forEach((param) => {
+          context.report({
+            message: `Required parameter ${param} must be passed to ${nodeType} call`,
+            startIndex: position.start,
+            endIndex: position.end,
+          });
+        });
+    };
+
+    return {
+      async RenderMarkup(node) {
+        const targetFile = 'value' in node.snippet ? node.snippet.value : node.snippet.name;
+        if (!targetFile) {
+          return;
+        }
+
+        await validate('render', targetFile, node.args, node.position);
+      },
+      async FunctionMarkup(node) {
+        const targetFile = 'value' in node.partial ? node.partial.value : node.partial.name;
+        if (!targetFile) {
+          return;
+        }
+
+        await validate('function', targetFile, node.args, node.position);
+      },
+    };
+  },
+};

package/src/checks/missing-asset/index.spec.ts

@@ -0,0 +1,59 @@
+import { expect, describe, it } from 'vitest';
+import { MissingAsset } from '.';
+import { check } from '../../test';
+
+describe('Module: MissingAsset', () => {
+  it('should report the missing asset when assigned to a variable', async () => {
+    const file = `
+      {% assign logo_url = 'logo.png' | asset_url %}
+      <img src="{{ logo_url }}" alt="Logo" />
+    `;
+    const files = {
+      'app/views/partials/partial.liquid': file,
+      'app/views/partials/existing.liquid': '',
+    };
+
+    const offenses = await check(files, [MissingAsset]);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal("'logo.png' does not exist");
+  });
+
+  it('should report the missing asset when defined inline', async () => {
+    const file = `<link rel="stylesheet" href="{{ 'styles.css' | asset_url }}" />`;
+    const files = {
+      'app/views/partials/partial.liquid': file,
+      'app/views/partials/existing.liquid': '',
+    };
+
+    const offenses = await check(files, [MissingAsset]);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal("'styles.css' does not exist");
+  });
+
+  it('should report the missing asset when multiple filters applied', async () => {
+    const file = `<link rel="stylesheet" href="{{ 'styles.css' | asset_url | stylesheet_tag}}" />`;
+    const files = {
+      'app/views/partials/partial.liquid': file,
+      'app/views/partials/existing.liquid': '',
+    };
+
+    const offenses = await check(files, [MissingAsset]);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal("'styles.css' does not exist");
+  });
+
+  it('should report no offenses when an asset file exists', async () => {
+    const file = `<link rel="stylesheet" href="{{ 'styles.css' | asset_url }}" />`;
+    const files = {
+      'app/views/partials/partial.liquid': file,
+      'app/assets/styles.css': 'a',
+    };
+
+    const offenses = await check(files, [MissingAsset]);
+
+    expect(offenses).to.have.length(0);
+  });
+});

package/src/checks/missing-asset/index.ts

@@ -0,0 +1,48 @@
+import { DocumentsLocator } from '@platformos/platformos-common';
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import { doesFileExist } from '../../utils/file-utils';
+import { isLiquidString } from '../utils';
+import { URI } from 'vscode-uri';
+
+export const MissingAsset: LiquidCheckDefinition = {
+  meta: {
+    code: 'MissingAsset',
+    name: 'Avoid rendering missing asset files',
+    docs: {
+      description: 'Reports missing asset files',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/missing-asset',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    const documentsLocator = new DocumentsLocator(context.fs);
+    return {
+      async LiquidVariable(node) {
+        if (node.filters.length === 0 || node.filters[0].name !== 'asset_url') {
+          return;
+        }
+
+        if (!isLiquidString(node.expression)) return;
+
+        let expression = node.expression;
+        const result = await documentsLocator.locate(
+          URI.parse(context.config.rootUri),
+          'asset',
+          expression.value,
+        );
+        if (!result) {
+          context.report({
+            message: `'${expression.value}' does not exist`,
+            startIndex: expression.position.start,
+            endIndex: expression.position.end,
+          });
+        }
+      },
+    };
+  },
+};

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

@@ -0,0 +1,144 @@
+import { describe, it, expect } from 'vitest';
+import { applySuggestions, runLiquidCheck } from '../../test';
+import { MissingContentForArguments } from '.';
+
+function check(existingCode: string, source: string) {
+  return runLiquidCheck(
+    MissingContentForArguments,
+    source,
+    undefined,
+    {},
+    {
+      'blocks/card.liquid': existingCode,
+    },
+  );
+}
+
+const blockSourceCode = `
+  {% doc %}
+    @param {string} required_string - A required string
+    @param {number} required_number - A required number
+    @param {boolean} required_boolean - A required boolean
+    @param {object} required_object - A required object
+    @param {string} [optional_string] - An optional string
+    @param {number} [optional_number] - An optional number
+    @param {object} [optional_object] - An optional object
+    @param {boolean} [optional_boolean] - An optional boolean
+  {% enddoc %}
+`;
+
+describe('Module: MissingContentForArguments', () => {
+  describe('missing required arguments', () => {
+    it('should report missing required arguments', async () => {
+      const offenses = await check(blockSourceCode, `{% content_for 'block', type: 'card' %}`);
+
+      expect(offenses).toHaveLength(4);
+      expect(offenses[0].message).toBe(
+        "Missing required argument 'required_string' in content_for tag for static block 'card'.",
+      );
+      expect(offenses[1].message).toBe(
+        "Missing required argument 'required_number' in content_for tag for static block 'card'.",
+      );
+      expect(offenses[2].message).toBe(
+        "Missing required argument 'required_boolean' in content_for tag for static block 'card'.",
+      );
+      expect(offenses[3].message).toBe(
+        "Missing required argument 'required_object' in content_for tag for static block 'card'.",
+      );
+    });
+  });
+
+  describe('suggestions', () => {
+    it('should suggest adding missing required arguments when none already exist', async () => {
+      const sourceCode = `{% content_for 'block', type: 'card' %}`;
+      const offenses = await check(blockSourceCode, sourceCode);
+
+      expect(offenses).toHaveLength(4);
+      const x = applySuggestions(sourceCode, offenses[0]);
+      expect(x).toEqual([`{% content_for 'block', type: 'card', required_string: '' %}`]);
+    });
+  });
+
+  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(
+        MissingContentForArguments,
+        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 not report when block has no doc comment', async () => {
+      const sourceCode = `{% content_for 'block', type: 'card', title: 'My Card' %}`;
+      const offenses = await runLiquidCheck(
+        MissingContentForArguments,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': `<h1>This partial has no doc comment</h1>`,
+        },
+      );
+
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not report when LiquidDoc definition has no defined params', async () => {
+      const sourceCode = `{% content_for 'block', type: 'card', title: 'My Card' %}`;
+      const offenses = await runLiquidCheck(
+        MissingContentForArguments,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': `
+            {% doc %}
+              @description this is a description
+              @example this is an example
+            {% enddoc %}
+            <div>{{ title }}</div>
+            <div>{{ description }}</div>
+          `,
+        },
+      );
+
+      expect(offenses).toHaveLength(0);
+    });
+
+    it('should not report when block name is a VariableLookup', async () => {
+      const sourceCode = `{% assign block_name = 'card' %}{% content_for 'block', type: block_name, title: 'My Card' %}`;
+      const offenses = await runLiquidCheck(
+        MissingContentForArguments,
+        sourceCode,
+        undefined,
+        {},
+        {
+          'blocks/card.liquid': `
+            {% doc %}
+              @param {string} title - The title of the card
+              @param {string} description - The description of the card
+            {% enddoc %}
+            <div>{{ title }}</div>
+            <div>{{ description }}</div>
+          `,
+        },
+      );
+
+      expect(offenses).toHaveLength(0);
+    });
+  });
+});

package/src/checks/missing-content-for-arguments/index.ts

@@ -0,0 +1,46 @@
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import { ContentForMarkup } from '@platformos/liquid-html-parser';
+import {
+  getBlockName,
+  getLiquidDocParams,
+  reportMissingArguments,
+} from '../../liquid-doc/arguments';
+
+export const MissingContentForArguments: LiquidCheckDefinition = {
+  meta: {
+    code: 'MissingContentForArguments',
+    name: 'Missing ContentFor Arguments',
+    docs: {
+      description:
+        'This check ensures that all required arguments are provided when rendering a static block.',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/missing-content-for-arguments',
+    },
+    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 providedParams = new Map(node.args.map((arg) => [arg.name, arg]));
+
+        const missingRequiredParams = Array.from(liquidDocParameters.values()).filter(
+          (p) => p.required && !providedParams.has(p.name),
+        );
+
+        reportMissingArguments(context, node, missingRequiredParams, blockName);
+      },
+    };
+  },
+};

package/src/checks/missing-template/index.spec.ts

@@ -0,0 +1,61 @@
+import { expect, describe, it } from 'vitest';
+import { MissingTemplate } from '.';
+import { check } from '../../test';
+
+describe('Module: MissingTemplate', () => {
+  it('should report missing template errors', async () => {
+    const testCases = [
+      {
+        testCase: 'should report the missing partial to be rendered with "render"',
+        file: `
+        {% render 'missing' with foo as arg          %}
+        {% render myvariable %}
+      `,
+        expected: {
+          check: 'MissingTemplate',
+          end: {
+            character: 27,
+            index: 28,
+            line: 1,
+          },
+          fix: undefined,
+          message: "'missing' does not exist",
+          severity: 0,
+          start: {
+            character: 18,
+            index: 19,
+            line: 1,
+          },
+          suggest: undefined,
+          type: 'LiquidHtml',
+          uri: 'file:///app/views/partials/partial.liquid',
+        },
+        filesWith: (file: string) => ({
+          'app/views/partials/partial.liquid': file,
+        }),
+      },
+      {
+        testCase: 'should report the missing partial to be rendered with "include"',
+        file: "{% include 'missing' %}",
+        expected: {
+          message: "'missing' does not exist",
+          uri: 'file:///app/views/partials/partial.liquid',
+          start: { index: 11, line: 0, character: 11 },
+          end: { index: 20, line: 0, character: 20 },
+        },
+        filesWith: (file: string) => ({
+          'app/views/partials/partial.liquid': file,
+        }),
+      },
+    ];
+    for (const { testCase, file, expected, filesWith } of testCases) {
+      const offenses = await check(filesWith(file), [MissingTemplate]);
+
+      expect(offenses).to.have.length(1);
+      expect(offenses, testCase).to.containOffense({
+        check: MissingTemplate.meta.code,
+        ...expected,
+      });
+    }
+  });
+});

package/src/checks/missing-template/index.ts

@@ -0,0 +1,101 @@
+import {
+  LiquidTag,
+  LiquidTagNamed,
+  NamedTags,
+  NodeTypes,
+  Position,
+} from '@platformos/liquid-html-parser';
+import { minimatch } from 'minimatch';
+import {
+  LiquidCheckDefinition,
+  RelativePath,
+  SchemaProp,
+  Severity,
+  SourceCodeType,
+} from '../../types';
+import { doesFileExist } from '../../utils/file-utils';
+import { DocumentsLocator } from '@platformos/platformos-common';
+import { URI } from 'vscode-uri';
+
+const schema = {
+  ignoreMissing: SchemaProp.array(SchemaProp.string(), []),
+};
+
+export const MissingTemplate: LiquidCheckDefinition<typeof schema> = {
+  meta: {
+    code: 'MissingTemplate',
+    name: 'Avoid rendering missing templates',
+    docs: {
+      description: 'Reports missing partial liquid file',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/missing-template',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.ERROR,
+    schema,
+    targets: [],
+  },
+
+  create(context) {
+    const locator = new DocumentsLocator(context.fs);
+
+    return {
+      async RenderMarkup(node) {
+        if (node.snippet.type === NodeTypes.VariableLookup) return;
+
+        const snippet = node.snippet;
+        const location = await locator.locate(
+          URI.parse(context.config.rootUri),
+          'render',
+          snippet.value,
+        );
+
+        if (!location) {
+          context.report({
+            message: `'${snippet.value}' does not exist`,
+            startIndex: node.snippet.position.start,
+            endIndex: node.snippet.position.end,
+          });
+        }
+      },
+
+      async FunctionMarkup(node) {
+        if (node.partial.type === NodeTypes.VariableLookup) return;
+
+        const partial = node.partial;
+        const location = await locator.locate(
+          URI.parse(context.config.rootUri),
+          'function',
+          partial.value,
+        );
+
+        if (!location) {
+          context.report({
+            message: `'${partial.value}' does not exist`,
+            startIndex: node.partial.position.start,
+            endIndex: node.partial.position.end,
+          });
+        }
+      },
+
+      async GraphQLMarkup(node) {
+        if (node.graphql.type === NodeTypes.VariableLookup) return;
+
+        const graphql = node.graphql;
+        const location = await locator.locate(
+          URI.parse(context.config.rootUri),
+          'graphql',
+          graphql.value,
+        );
+
+        if (!location) {
+          context.report({
+            message: `'${graphql.value}' does not exist`,
+            startIndex: node.graphql.position.start,
+            endIndex: node.graphql.position.end,
+          });
+        }
+      },
+    };
+  },
+};

package/src/checks/orphaned-partial/index.spec.ts

@@ -0,0 +1,58 @@
+import { expect, describe, it } from 'vitest';
+import { OrphanedPartial } from './index';
+import { runLiquidCheck } from '../../test';
+
+describe('Module: OrphanedPartial', () => {
+  describe('when the partial is not referenced by any files', () => {
+    it('should report a warning', async () => {
+      const sourceCode = `<div>Orphaned content</div>`;
+
+      const offenses = await runLiquidCheck(
+        OrphanedPartial,
+        sourceCode,
+        'app/views/partials/orphaned.liquid',
+        {
+          getReferences: async (uri) => [],
+        },
+      );
+
+      expect(offenses).toHaveLength(1);
+      expect(offenses[0].message).toBe('This partial is not referenced by any other files');
+    });
+  });
+
+  describe('when the partial is referenced by other files', () => {
+    it('should not report a warning', async () => {
+      const sourceCode = `<div>Referenced partial</div>`;
+
+      const offenses = await runLiquidCheck(
+        OrphanedPartial,
+        sourceCode,
+        'app/views/partials/product-card.liquid',
+        {
+          getReferences: async (uri) => [
+            {
+              source: { uri: 'templates/product.liquid' },
+              target: { uri: 'app/views/partials/product-card.liquid' },
+              type: 'direct',
+            },
+          ],
+        },
+      );
+
+      expect(offenses).toHaveLength(0);
+    });
+  });
+
+  describe('when checking non-partial files', () => {
+    it('should not report warnings for templates', async () => {
+      const sourceCode = `{% section 'header' %}`;
+
+      const offenses = await runLiquidCheck(OrphanedPartial, sourceCode, 'templates/index.liquid', {
+        getReferences: async (uri) => [],
+      });
+
+      expect(offenses).toHaveLength(0);
+    });
+  });
+});

package/src/checks/orphaned-partial/index.ts

@@ -0,0 +1,43 @@
+import { isPartial } from '../../to-schema';
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+
+export const OrphanedPartial: LiquidCheckDefinition = {
+  meta: {
+    code: 'OrphanedPartial',
+    name: 'Prevent orphaned partials',
+    docs: {
+      description: 'This check exists to prevent orphaned partials in themes.',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/orphaned-partial',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    return {
+      async onCodePathEnd() {
+        const { getReferences } = context;
+
+        if (!getReferences) {
+          return;
+        }
+
+        const fileUri = context.file.uri;
+        if (isPartial(fileUri)) {
+          const references = await getReferences(fileUri);
+
+          if (references.length === 0) {
+            context.report({
+              message: `This partial is not referenced by any other files`,
+              startIndex: 0,
+              endIndex: 1,
+            });
+          }
+        }
+      },
+    };
+  },
+};