@platformos/platformos-check-common 0.0.2

package/src/checks/unrecognized-render-partial-arguments/index.ts

@@ -0,0 +1,76 @@
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import { RenderMarkup } from '@platformos/liquid-html-parser';
+import { LiquidDocParameter } from '../../liquid-doc/liquidDoc';
+import {
+  getLiquidDocParams,
+  getPartialName,
+  reportUnknownArguments,
+} from '../../liquid-doc/arguments';
+
+export const UnrecognizedRenderPartialArguments: LiquidCheckDefinition = {
+  meta: {
+    code: 'UnrecognizedRenderPartialArguments',
+    name: 'Unrecognized Render Partial Arguments',
+    aliases: ['UnrecognizedRenderPartialParams'],
+    docs: {
+      description:
+        'This check ensures that no unknown arguments are used when rendering a partial.',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/unrecognized-render-partial-arguments',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    function reportUnknownAliases(
+      node: RenderMarkup,
+      liquidDocParameters: Map<string, LiquidDocParameter>,
+      partialName: string,
+    ) {
+      const alias = node.alias;
+      const variable = node.variable;
+
+      if (alias && !liquidDocParameters.has(alias.value) && variable) {
+        const startIndex = variable.position.start + 1;
+
+        context.report({
+          message: `Unknown argument '${alias.value}' in render tag for partial '${partialName}'.`,
+          startIndex: startIndex,
+          endIndex: alias.position.end,
+          suggest: [
+            {
+              message: `Remove '${alias.value}'`,
+              fix: (fixer: any) => {
+                if (variable) {
+                  return fixer.remove(variable.position.start, alias.position.end);
+                }
+              },
+            },
+          ],
+        });
+      }
+    }
+
+    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;
+
+        const unknownProvidedParams = node.args.filter((p) => !liquidDocParameters.has(p.name));
+        reportUnknownAliases(node, liquidDocParameters, partialName);
+        reportUnknownArguments(context, node, unknownProvidedParams, partialName);
+      },
+    };
+  },
+};

package/src/checks/unused-assign/index.spec.ts

@@ -0,0 +1,160 @@
+import { expect, describe, it } from 'vitest';
+import { UnusedAssign } from './index';
+import { runLiquidCheck, applySuggestions } from '../../test';
+
+describe('Module: UnusedAssign', () => {
+  it('should report an error when a variable is assigned but not used', async () => {
+    const sourceCode = `
+      {% assign unusedVar = "value" %}
+      {% assign usedVar = "anotherValue" %}
+      {{ usedVar }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal("The variable 'unusedVar' is assigned but not used");
+  });
+
+  it('should not report an error when a variable is assigned and used', async () => {
+    const sourceCode = `
+      {% assign usedVar = "value" %}
+      {{ usedVar }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+
+    expect(offenses).to.be.empty;
+  });
+
+  it('should provide a suggestion to remove the unused variable', async () => {
+    const sourceCode = `
+      {% assign unusedVar = "value" %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].suggest).to.have.length(1);
+    expect(offenses[0]!.suggest![0].message).to.equal("Remove the unused variable 'unusedVar'");
+  });
+
+  it('should fix the code by removing the unused variable', async () => {
+    const sourceCode = `
+      {% assign unusedVar = "value" %}
+      {% assign usedVar = "anotherValue" %}
+      {{ usedVar }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    const suggestions = applySuggestions(sourceCode, offenses[0]);
+
+    // We're not deleting the line, that's prettier's job.
+    const expectedFixedCode = `
+      ${''}
+      {% assign usedVar = "anotherValue" %}
+      {{ usedVar }}
+    `;
+
+    expect(suggestions).to.include(expectedFixedCode);
+  });
+
+  it('should not report unused assigns for things used in a capture tag', async () => {
+    const sourceCode = `
+      {% assign usedVar = "anotherValue" %}
+      {% capture foo %}
+        {{ usedVar }}
+      {% endcapture %}
+      {{ foo }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.be.empty;
+  });
+
+  it('should report unused capture', async () => {
+    const sourceCode = `
+      {% assign usedVar = "anotherValue" %}
+      {% capture foo %}
+        {{ usedVar }}
+      {% endcapture %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).not.to.be.empty;
+  });
+
+  it('should not report unused assigns for things used in a raw-like tag', async () => {
+    const tags = ['style'];
+    for (const tag of tags) {
+      const sourceCode = `
+        {% assign usedVar = 1 %}
+        {% ${tag} %}
+          {{ usedVar }}
+        {% end${tag} %}
+      `;
+
+      const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+      expect(offenses).to.be.empty;
+    }
+  });
+
+  it('should report unused assigns for things used in raw code that gets stripped away (schema, etc)', async () => {
+    const tags = ['schema', 'javascript', 'stylesheet'];
+    for (const tag of tags) {
+      const sourceCode = `
+        {% assign usedVar = 1 %}
+        {% ${tag} %}
+          {{ usedVar }}
+        {% end${tag} %}
+      `;
+
+      const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+      expect(offenses).to.not.be.empty;
+    }
+  });
+
+  it('should not report unused assigns for things used in a HTML raw-like tag', async () => {
+    const tags = ['style', 'script'];
+    for (const tag of tags) {
+      const sourceCode = `
+        {% assign usedVar = 1 %}
+        <${tag}>
+          {{ usedVar }}
+        </${tag}>
+      `;
+
+      const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+      expect(offenses).to.be.empty;
+    }
+  });
+
+  it('should not report unused assigns for variables starting with an underscore', async () => {
+    const sourceCode = `
+      {% assign _ = 1 %}
+      {% assign _unusedVar = 1 %}
+      {% capture _ %}
+        {% form "cart", cart %}
+          {% assign some_var = cart.successfully_posted? %}
+        {% endform %}
+      {% endcapture %}
+      {{ some_var }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should report unused assign for things used in a {% raw %} tag', async () => {
+    const sourceCode = `
+      {% assign unusedVar = 1 %}
+      {% # It's a trap. It's not really used %}
+      {% raw %}
+        {{ unusedVar }}
+      {% endraw %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(1);
+  });
+});

package/src/checks/unused-assign/index.ts

@@ -0,0 +1,87 @@
+import {
+  LiquidHtmlNode,
+  LiquidTag,
+  LiquidTagAssign,
+  LiquidTagCapture,
+  NodeTypes,
+} from '@platformos/liquid-html-parser';
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import { isWithinRawTagThatDoesNotParseItsContents } from '../utils';
+
+export const UnusedAssign: LiquidCheckDefinition = {
+  meta: {
+    code: 'UnusedAssign',
+    name: 'Prevent unused assigns',
+    docs: {
+      description:
+        'This check exists to prevent bloat in themes by surfacing variable definitions that are not used.',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/unused-assign',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    const assignedVariables: Map<string, LiquidTagAssign | LiquidTagCapture> = new Map();
+    const usedVariables: Set<string> = new Set();
+
+    function checkVariableUsage(node: any) {
+      if (node.type === NodeTypes.VariableLookup) {
+        usedVariables.add(node.name);
+      }
+    }
+
+    return {
+      async LiquidTag(node, ancestors) {
+        if (isWithinRawTagThatDoesNotParseItsContents(ancestors)) return;
+        if (isLiquidTagAssign(node)) {
+          assignedVariables.set(node.markup.name, node);
+        } else if (isLiquidTagCapture(node) && node.markup.name) {
+          assignedVariables.set(node.markup.name, node);
+        }
+      },
+
+      async VariableLookup(node, ancestors) {
+        if (isWithinRawTagThatDoesNotParseItsContents(ancestors)) return;
+        const parentNode = ancestors.at(-1);
+        if (parentNode && isLiquidTagCapture(parentNode)) {
+          return;
+        }
+        checkVariableUsage(node);
+      },
+
+      async onCodePathEnd() {
+        for (const [variable, node] of assignedVariables.entries()) {
+          if (!usedVariables.has(variable) && !variable.startsWith('_')) {
+            context.report({
+              message: `The variable '${variable}' is assigned but not used`,
+              startIndex: isLiquidTagCapture(node)
+                ? node.blockStartPosition.start
+                : node.position.start,
+              endIndex: isLiquidTagCapture(node) ? node.blockStartPosition.end : node.position.end,
+              suggest: [
+                {
+                  message: `Remove the unused variable '${variable}'`,
+                  fix: (corrector) => corrector.remove(node.position.start, node.position.end),
+                },
+              ],
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+function isLiquidTagAssign(node: LiquidTag): node is LiquidTagAssign {
+  return node.name === 'assign' && typeof node.markup !== 'string';
+}
+
+function isLiquidTagCapture(node: LiquidHtmlNode): node is LiquidTagCapture {
+  return (
+    node.type == NodeTypes.LiquidTag && node.name === 'capture' && typeof node.markup !== 'string'
+  );
+}

package/src/checks/unused-doc-param/index.spec.ts

@@ -0,0 +1,89 @@
+import { expect, describe, it } from 'vitest';
+import { UnusedDocParam } from './index';
+import { runLiquidCheck, applySuggestions } from '../../test';
+import { LoopNamedTags } from '@platformos/liquid-html-parser';
+
+describe('Module: UnusedDocParam', () => {
+  it('should not report a warning when a variable is defined and used', async () => {
+    const sourceCode = `
+      {% doc %}
+        @param param1 - Example param
+      {% enddoc %}
+
+      {{ param1 }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedDocParam, sourceCode);
+
+    expect(offenses).to.be.empty;
+  });
+
+  it('should report a warning with suggestions when a variable is defined but not used', async () => {
+    const sourceCode = `
+      {% doc %}
+        @param param1 - Example param
+        @param param2 - Example param
+      {% enddoc %}
+
+      {{ param1 }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedDocParam, sourceCode);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      "The parameter 'param2' is defined but not used in this file.",
+    );
+    expect(offenses[0].suggest).to.have.length(1);
+    expect(offenses[0]!.suggest![0].message).to.equal("Remove unused parameter 'param2'");
+  });
+
+  it('should apply suggestion when a variable is defined but not used', async () => {
+    const sourceCode = `
+      {% doc %}
+        @param param1 - Example param
+        @param param2 - Example param
+      {% enddoc %}
+
+      {{ param1 }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedDocParam, sourceCode);
+    const suggestions = applySuggestions(sourceCode, offenses[0]);
+
+    expect(suggestions).to.include(`
+      {% doc %}
+        @param param1 - Example param
+        
+      {% enddoc %}
+
+      {{ param1 }}
+    `);
+  });
+
+  LoopNamedTags.forEach((tag) => {
+    it(`should report a warning when a variable is defined but not used outside '${tag}' loop context`, async () => {
+      const sourceCode = `
+        {% doc %}
+          @param param1 - Example param
+          @param param2 - Example param
+        {% enddoc %}
+  
+        {{ param1 }}
+        
+        {% ${tag} param2 in array %}
+          {{ param2 }}
+        {% end${tag} %}
+      `;
+
+      const offenses = await runLiquidCheck(UnusedDocParam, sourceCode);
+
+      expect(offenses).to.have.length(1);
+      expect(offenses[0].message).to.equal(
+        "The parameter 'param2' is defined but not used in this file.",
+      );
+      expect(offenses[0].suggest).to.have.length(1);
+      expect(offenses[0]!.suggest![0].message).to.equal("Remove unused parameter 'param2'");
+    });
+  });
+});

package/src/checks/unused-doc-param/index.ts

@@ -0,0 +1,59 @@
+import { LiquidDocParamNode, NodeTypes } from '@platformos/liquid-html-parser';
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+import { isLoopScopedVariable } from '../utils';
+
+export const UnusedDocParam: LiquidCheckDefinition = {
+  meta: {
+    code: 'UnusedDocParam',
+    name: 'Prevent unused doc parameters',
+    docs: {
+      description:
+        'This check exists to ensure any parameters defined in the `doc` tag are used within the partial.',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/unused-doc-param',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    const definedLiquidDocParams: Map<string, LiquidDocParamNode> = new Map();
+    const usedVariables: Set<string> = new Set();
+
+    return {
+      async LiquidDocParamNode(node) {
+        definedLiquidDocParams.set(node.paramName.value, node);
+      },
+
+      async VariableLookup(node, ancestors) {
+        if (
+          node.type === NodeTypes.VariableLookup &&
+          node.name &&
+          !isLoopScopedVariable(node.name, ancestors)
+        ) {
+          usedVariables.add(node.name);
+        }
+      },
+
+      async onCodePathEnd() {
+        for (const [variable, node] of definedLiquidDocParams.entries()) {
+          if (!usedVariables.has(variable)) {
+            context.report({
+              message: `The parameter '${variable}' is defined but not used in this file.`,
+              startIndex: node.position.start,
+              endIndex: node.position.end,
+              suggest: [
+                {
+                  message: `Remove unused parameter '${variable}'`,
+                  fix: (corrector) => corrector.remove(node.position.start, node.position.end),
+                },
+              ],
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/src/checks/utils.ts

@@ -0,0 +1,117 @@
+import {
+  Position,
+  NodeTypes,
+  HtmlElement,
+  TextNode,
+  AttrEmpty,
+  AttrSingleQuoted,
+  AttrDoubleQuoted,
+  AttrUnquoted,
+  LiquidHtmlNode,
+  LiquidBranch,
+  LiquidTagFor,
+  LiquidTagTablerow,
+  LiquidTag,
+  LoopNamedTags,
+} from '@platformos/liquid-html-parser';
+import { LiquidHtmlNodeOfType as NodeOfType } from '../types';
+
+type ElementType<T> = T extends (infer E)[] ? E : never;
+
+export type ValuedHtmlAttribute = AttrSingleQuoted | AttrDoubleQuoted | AttrUnquoted;
+
+export function isNodeOfType<T extends NodeTypes>(
+  type: T,
+  node?: LiquidHtmlNode,
+): node is NodeOfType<T> {
+  return node?.type === type;
+}
+
+export function isLiquidBranch(node: LiquidHtmlNode): node is LiquidBranch {
+  return isNodeOfType(NodeTypes.LiquidBranch, node);
+}
+
+export function isHtmlTag<T>(
+  node: HtmlElement,
+  name: T,
+): node is HtmlElement & { name: [{ name: T }]; blockEndPosition: Position } {
+  return (
+    node.name.length === 1 &&
+    node.name[0].type === NodeTypes.TextNode &&
+    node.name[0].value === name &&
+    !!node.blockEndPosition
+  );
+}
+
+export function isAttr(attr: ValuedHtmlAttribute | AttrEmpty, name: string) {
+  return (
+    attr.name.length === 1 &&
+    isNodeOfType(NodeTypes.TextNode, attr.name[0]) &&
+    attr.name[0].value === name
+  );
+}
+
+export function isHtmlAttribute(
+  attr: ElementType<HtmlElement['attributes']>,
+): attr is ValuedHtmlAttribute | AttrEmpty {
+  return [
+    NodeTypes.AttrUnquoted,
+    NodeTypes.AttrDoubleQuoted,
+    NodeTypes.AttrSingleQuoted,
+    NodeTypes.AttrEmpty,
+  ].some((type) => isNodeOfType(type, attr));
+}
+
+export function isValuedHtmlAttribute(
+  attr: ElementType<HtmlElement['attributes']>,
+): attr is ValuedHtmlAttribute {
+  return [NodeTypes.AttrUnquoted, NodeTypes.AttrDoubleQuoted, NodeTypes.AttrSingleQuoted].some(
+    (type) => isNodeOfType(type, attr),
+  );
+}
+
+export function valueIncludes(attr: ValuedHtmlAttribute, word: string) {
+  const regex = new RegExp(`(^|\\s)${word}(\\s|$)`, 'g');
+
+  return attr.value
+    .filter((node): node is TextNode => isNodeOfType(NodeTypes.TextNode, node))
+    .some((valueNode) => regex.test(valueNode.value));
+}
+
+export function hasAttributeValueOf(attr: ValuedHtmlAttribute, value: string) {
+  return (
+    attr.value.length === 1 &&
+    isNodeOfType(NodeTypes.TextNode, attr.value[0]) &&
+    attr.value[0].value === value
+  );
+}
+
+export function isLiquidString(node: LiquidHtmlNode): node is NodeOfType<NodeTypes.String> {
+  return node.type === NodeTypes.String;
+}
+
+export function isLoopScopedVariable(variableName: string, ancestors: LiquidHtmlNode[]) {
+  return ancestors.some(
+    (ancestor) =>
+      ancestor.type === NodeTypes.LiquidTag &&
+      isLoopLiquidTag(ancestor) &&
+      typeof ancestor.markup !== 'string' &&
+      ancestor.markup.variableName === variableName,
+  );
+}
+
+export function isLoopLiquidTag(tag: LiquidTag): tag is LiquidTagFor | LiquidTagTablerow {
+  return LoopNamedTags.includes(tag.name as any);
+}
+
+const RawTagsThatDoNotParseTheirContents = ['raw', 'stylesheet', 'javascript', 'schema'];
+
+function isRawTagThatDoesNotParseItsContent(node: LiquidHtmlNode) {
+  return (
+    node.type === NodeTypes.LiquidRawTag && RawTagsThatDoNotParseTheirContents.includes(node.name)
+  );
+}
+
+export function isWithinRawTagThatDoesNotParseItsContents(ancestors: LiquidHtmlNode[]) {
+  return ancestors.some(isRawTagThatDoesNotParseItsContent);
+}