@platformos/platformos-check-common 0.0.2

package/src/checks/undefined-object/index.ts

@@ -0,0 +1,336 @@
+import {
+  LiquidDocParamNode,
+  LiquidHtmlNode,
+  LiquidTag,
+  LiquidTagAssign,
+  LiquidTagCapture,
+  LiquidTagDecrement,
+  LiquidTagFor,
+  LiquidTagIncrement,
+  LiquidTagTablerow,
+  LiquidVariableLookup,
+  LiquidTagFunction,
+  NamedTags,
+  NodeTypes,
+  Position,
+  FunctionMarkup,
+  LiquidTagHashAssign,
+  LiquidTagGraphQL,
+  LiquidTagBackground,
+  BackgroundInlineMarkup,
+} from '@platformos/liquid-html-parser';
+import { LiquidCheckDefinition, Severity, SourceCodeType, ThemeDocset } from '../../types';
+import { isError, last } from '../../utils';
+import { isWithinRawTagThatDoesNotParseItsContents } from '../utils';
+
+type Scope = { start?: number; end?: number };
+
+export const UndefinedObject: LiquidCheckDefinition = {
+  meta: {
+    code: 'UndefinedObject',
+    name: 'Undefined Object',
+    docs: {
+      description: 'This check exists to identify references to undefined Liquid objects.',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/undefined-object',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    const relativePath = context.toRelativePath(context.file.uri);
+    const ast = context.file.ast;
+
+    if (isError(ast)) return {};
+
+    /**
+     * Skip this check when definitions for global objects are unavailable.
+     */
+    if (!context.themeDocset) {
+      return {};
+    }
+
+    const themeDocset = context.themeDocset;
+    const scopedVariables: Map<string, Scope[]> = new Map();
+    const fileScopedVariables: Set<string> = new Set();
+    const variables: LiquidVariableLookup[] = [];
+
+    function indexVariableScope(variableName: string | null, scope: Scope) {
+      if (!variableName) return;
+
+      const indexedScope = scopedVariables.get(variableName) ?? [];
+      scopedVariables.set(variableName, indexedScope.concat(scope));
+    }
+
+    return {
+      async LiquidDocParamNode(node: LiquidDocParamNode) {
+        const paramName = node.paramName?.value;
+        if (paramName) {
+          fileScopedVariables.add(paramName);
+        }
+      },
+
+      async LiquidTag(node, ancestors) {
+        if (isWithinRawTagThatDoesNotParseItsContents(ancestors)) return;
+
+        if (isLiquidTagAssign(node) || isLiquidTagGraphQL(node)) {
+          indexVariableScope(node.markup.name, {
+            start: node.blockStartPosition.end,
+          });
+        }
+
+        if (isLiquidTagHashAssign(node) && node.markup.target.name) {
+          indexVariableScope(node.markup.target.name, {
+            start: node.blockStartPosition.end,
+          });
+        }
+
+        if (isLiquidTagCapture(node)) {
+          indexVariableScope(node.markup.name, {
+            start: node.blockEndPosition?.end,
+          });
+        }
+
+        /**
+         * {% form 'cart', cart %}
+         *   {{ form }}
+         * {% endform %}
+         */
+        if (['form', 'paginate'].includes(node.name)) {
+          indexVariableScope(node.name, {
+            start: node.blockStartPosition.end,
+            end: node.blockEndPosition?.start,
+          });
+        }
+
+        if (node.name === 'function') {
+          indexVariableScope((node.markup as FunctionMarkup).name, {
+            start: node.position.end,
+          });
+        }
+
+        if (node.name === 'layout') {
+          indexVariableScope('none', {
+            start: node.position.start,
+            end: node.position.end,
+          });
+        }
+
+        /* {% increment var %} */
+        if (
+          (isLiquidTagIncrement(node) || isLiquidTagDecrement(node)) &&
+          node.markup.name !== null
+        ) {
+          indexVariableScope(node.markup.name, {
+            start: node.position.start,
+          });
+        }
+
+        /**
+         * {% for x in y %}
+         *   {{ forloop }}
+         *   {{ x }}
+         * {% endfor %}
+         */
+        if (isLiquidForTag(node) || isLiquidTableRowTag(node)) {
+          indexVariableScope(node.markup.variableName, {
+            start: node.blockStartPosition.end,
+            end: node.blockEndPosition?.start,
+          });
+          indexVariableScope(node.name === 'for' ? 'forloop' : 'tablerowloop', {
+            start: node.blockStartPosition.end,
+            end: node.blockEndPosition?.start,
+          });
+        }
+
+        if (isLiquidTagBackground(node)) {
+          indexVariableScope(node.markup.jobId.name, {
+            start: node.blockEndPosition?.end,
+          });
+        }
+      },
+
+      async VariableLookup(node, ancestors) {
+        if (isWithinRawTagThatDoesNotParseItsContents(ancestors)) return;
+
+        const parent = last(ancestors);
+        if (isLiquidTag(parent) && isLiquidTagCapture(parent)) return;
+
+        // Skip the jobId variable in background tag markup - it's being defined, not used
+        if (isBackgroundInlineMarkup(parent) && parent.jobId === node) return;
+
+        variables.push(node);
+      },
+
+      async onCodePathEnd() {
+        const objects = await globalObjects(themeDocset, relativePath);
+
+        objects.forEach((obj) => fileScopedVariables.add(obj.name));
+
+        variables.forEach((variable) => {
+          if (!variable.name) return;
+
+          const isVariableDefined = isDefined(
+            variable.name,
+            variable.position,
+            fileScopedVariables,
+            scopedVariables,
+          );
+          if (isVariableDefined) return;
+
+          context.report({
+            message: `Unknown object '${variable.name}' used.`,
+            startIndex: variable.position.start,
+            endIndex: variable.position.end,
+          });
+        });
+      },
+    };
+  },
+};
+
+async function globalObjects(themeDocset: ThemeDocset, relativePath: string) {
+  const objects = await themeDocset.objects();
+  const contextualObjects = getContextualObjects(relativePath);
+
+  const globalObjects = objects.filter(({ access, name }) => {
+    return (
+      contextualObjects.includes(name) ||
+      !access ||
+      access.global === true ||
+      access.template.length > 0
+    );
+  });
+
+  return globalObjects;
+}
+
+function getContextualObjects(relativePath: string): string[] {
+  if (relativePath.startsWith('layout/checkout.liquid')) {
+    return [
+      'locale',
+      'direction',
+      'skip_to_content_link',
+      'checkout_html_classes',
+      'checkout_stylesheets',
+      'checkout_scripts',
+      'content_for_logo',
+      'breadcrumb',
+      'order_summary_toggle',
+      'content_for_order_summary',
+      'alternative_payment_methods',
+      'content_for_footer',
+      'tracking_code',
+    ];
+  }
+  if (relativePath.startsWith('sections/')) {
+    return ['section', 'predictive_search', 'recommendations', 'comment'];
+  }
+
+  if (relativePath.startsWith('blocks/')) {
+    return ['app', 'section', 'recommendations', 'block'];
+  }
+
+  if (relativePath.includes('views/partials/') || relativePath.includes('/lib/')) {
+    return ['app'];
+  }
+
+  return [];
+}
+
+function isDefined(
+  variableName: string,
+  variablePosition: Position,
+  fileScopedVariables: Set<string>,
+  scopedVariables: Map<string, Scope[]>,
+): boolean {
+  /**
+   * Check if the variable is defined in the file
+   */
+  if (fileScopedVariables.has(variableName)) {
+    return true;
+  }
+
+  /**
+   * Check if the variable is defined within a specific scope
+   */
+  const scopes = scopedVariables.get(variableName);
+
+  /**
+   * If no specific scopes exist (and it wasn't defined in the file), it's undefined
+   */
+  if (!scopes) {
+    return false;
+  }
+
+  /**
+   * Check if the variable's usage position falls within any of the defined scopes
+   */
+  return scopes.some((scope) => isDefinedInScope(variablePosition, scope));
+}
+
+function isDefinedInScope(variablePosition: Position, scope: Scope) {
+  const start = variablePosition.start;
+  const isVariableAfterScopeStart = !scope.start || start > scope.start;
+  const isVariableBeforeScopeEnd = !scope.end || start < scope.end;
+
+  return isVariableAfterScopeStart && isVariableBeforeScopeEnd;
+}
+
+function isLiquidTag(node?: LiquidHtmlNode): node is LiquidTag {
+  return node?.type === NodeTypes.LiquidTag;
+}
+
+function isLiquidTagCapture(node: LiquidTag): node is LiquidTagCapture {
+  return node.name === NamedTags.capture;
+}
+
+function isLiquidTagAssign(node: LiquidTag): node is LiquidTagAssign {
+  return node.name === NamedTags.assign && typeof node.markup !== 'string';
+}
+
+function isLiquidTagHashAssign(node: LiquidTag): node is LiquidTagHashAssign {
+  return node.name === NamedTags.hash_assign && typeof node.markup !== 'string';
+}
+
+function isLiquidTagGraphQL(node: LiquidTag): node is LiquidTagGraphQL {
+  return node.name === NamedTags.graphql && typeof node.markup !== 'string';
+}
+
+function isLiquidForTag(node: LiquidTag): node is LiquidTagFor {
+  return node.name === NamedTags.for && typeof node.markup !== 'string';
+}
+
+function isLiquidTableRowTag(node: LiquidTag): node is LiquidTagTablerow {
+  return node.name === NamedTags.tablerow && typeof node.markup !== 'string';
+}
+
+function isLiquidTagIncrement(node: LiquidTag): node is LiquidTagIncrement {
+  return node.name === NamedTags.increment && typeof node.markup !== 'string';
+}
+
+function isLiquidTagDecrement(node: LiquidTag): node is LiquidTagDecrement {
+  return node.name === NamedTags.decrement && typeof node.markup !== 'string';
+}
+
+function isLiquidTagBackground(
+  node: LiquidTag,
+): node is LiquidTagBackground & { markup: BackgroundInlineMarkup } {
+  return (
+    node.name === NamedTags.background &&
+    typeof node.markup !== 'string' &&
+    node.markup.type === NodeTypes.BackgroundInlineMarkup
+  );
+}
+
+function isBackgroundInlineMarkup(node: unknown): node is BackgroundInlineMarkup {
+  return (
+    typeof node === 'object' &&
+    node !== null &&
+    'type' in node &&
+    node.type === NodeTypes.BackgroundInlineMarkup
+  );
+}

package/src/checks/unique-doc-param-names/index.spec.ts

@@ -0,0 +1,35 @@
+import { expect, describe, it } from 'vitest';
+import { UniqueDocParamNames } from './index';
+import { runLiquidCheck } from '../../test';
+
+describe('Module: UniqueDocParamNames', () => {
+  it(`should not report an error when a all doc params have unique names`, async () => {
+    const sourceCode = `
+      {% doc %}
+        @param param1 - Example param
+        @param param2 - Example param
+        @param param3 - Example param
+      {% enddoc %}
+    `;
+
+    const offenses = await runLiquidCheck(UniqueDocParamNames, sourceCode);
+
+    expect(offenses).to.be.empty;
+  });
+
+  it('should report an error when a param name appears more than once', async () => {
+    const sourceCode = `
+      {% doc %}
+        @param param1 - Example param
+        @param param1 - Example param
+        @param param1 - Example param
+      {% enddoc %}
+    `;
+
+    const offenses = await runLiquidCheck(UniqueDocParamNames, sourceCode);
+
+    expect(offenses).to.have.length(2);
+    expect(offenses[0].message).to.equal("The parameter 'param1' is defined more than once.");
+    expect(offenses[1].message).to.equal("The parameter 'param1' is defined more than once.");
+  });
+});

package/src/checks/unique-doc-param-names/index.ts

@@ -0,0 +1,39 @@
+import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
+
+export const UniqueDocParamNames: LiquidCheckDefinition = {
+  meta: {
+    code: 'UniqueDocParamNames',
+    name: 'Unique doc parameter names',
+    docs: {
+      description:
+        'This check exists to ensure any parameter names defined in the `doc` tag are unique.',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/unique-doc-param-names',
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    const definedLiquidDocParamNames: Set<string> = new Set();
+
+    return {
+      async LiquidDocParamNode(node) {
+        const paramName = node.paramName.value;
+
+        if (!definedLiquidDocParamNames.has(paramName)) {
+          definedLiquidDocParamNames.add(paramName);
+          return;
+        }
+
+        context.report({
+          message: `The parameter '${paramName}' is defined more than once.`,
+          startIndex: node.paramName.position.start,
+          endIndex: node.paramName.position.end,
+        });
+      },
+    };
+  },
+};

package/src/checks/unique-settings-id/index.spec.ts

@@ -0,0 +1,24 @@
+import { expect, describe, it } from 'vitest';
+import { UniqueSettingIds } from './index';
+import { highlightedOffenses, runJSONCheck } from '../../test';
+import { invalidJson, validJson } from './test-data';
+
+describe('Module: UniqueSettingIds', () => {
+  it("Should report an error for duplicate id's in settings_schema (0)", async () => {
+    const offenses = await runJSONCheck(UniqueSettingIds, invalidJson, 'file.json');
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal('Duplicate setting id found: "nosto_account_id"');
+
+    const highlights = highlightedOffenses({ 'file.json': invalidJson }, offenses);
+
+    expect(highlights).to.have.length(1);
+    expect(highlights[0]).to.equal('"id": "nosto_account_id"');
+  });
+
+  it('should not report any errors for valid file', async () => {
+    const offenses = await runJSONCheck(UniqueSettingIds, validJson);
+
+    expect(offenses).to.be.empty;
+  });
+});

package/src/checks/unique-settings-id/index.ts

@@ -0,0 +1,84 @@
+import {
+  isArrayNode,
+  isLiteralNode,
+  isObjectNode,
+  isPropertyNode,
+  Severity,
+  SourceCodeType,
+} from '../../types';
+
+import type { ArrayNode, PropertyNode, JSONCheckDefinition } from '../../types';
+
+export const UniqueSettingIds: JSONCheckDefinition = {
+  meta: {
+    code: 'UniqueSettingId',
+    name: 'Prevent duplicate Ids in setting_schema',
+    docs: {
+      description: 'This check is aimed at eliminating duplicate Ids in settings_schema.json',
+      recommended: true,
+      // url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-schema',
+    },
+    type: SourceCodeType.JSON,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    return {
+      async onCodePathEnd(file) {
+        if (isArrayNode(file.ast)) {
+          const settingIds: PropertyNode[] = [];
+
+          /* Find and loop through all of our nodes that have an id value and find their key value */
+          for (const child of file.ast.children) {
+            if (isObjectNode(child) && child.children) {
+              const settingsNode = child.children.find((node) => node.key.value === 'settings');
+
+              if (settingsNode && settingsNode.value && isArrayNode(settingsNode.value)) {
+                for (const setting of settingsNode.value.children) {
+                  if (isObjectNode(setting) && setting.children) {
+                    const idNode = setting.children.find((node) => node.key.value === 'id');
+                    if (isPropertyNode(idNode)) {
+                      settingIds.push(idNode);
+                    }
+                  }
+                }
+              }
+            }
+          }
+
+          /* Check for dupes */
+          const idMap = new Map<string, PropertyNode[]>();
+          for (const node of settingIds) {
+            if (isLiteralNode(node.value)) {
+              const id = node.value.value;
+              if (typeof id === 'string') {
+                if (!idMap.has(id)) {
+                  idMap.set(id, []);
+                }
+                idMap.get(id)!.push(node);
+              }
+            }
+          }
+
+          const duplicates: [string, PropertyNode[]][] = Array.from(idMap.entries()).filter(
+            ([_, nodes]) => nodes.length > 1,
+          );
+
+          if (duplicates.length > 0) {
+            for (const [id, nodes] of duplicates) {
+              const lastNodeFound = nodes[nodes.length - 1];
+
+              context.report({
+                message: `Duplicate setting id found: "${id}"`,
+                startIndex: lastNodeFound.loc.start.offset,
+                endIndex: lastNodeFound.loc.end.offset,
+              });
+            }
+          }
+        }
+      },
+    };
+  },
+};