@platformos/platformos-check-common 0.0.2

package/src/checks/valid-visible-if/index.ts

@@ -0,0 +1,184 @@
+import { type LiquidVariableLookup } from '@platformos/liquid-html-parser';
+import {
+  Severity,
+  SourceCodeType,
+  type LiquidCheckDefinition,
+  type JSONCheckDefinition,
+} from '../../types';
+import { getLocStart, nodeAtPath } from '../../json';
+import { getSchema, isBlockSchema, isSectionSchema } from '../../to-schema';
+import { reportWarning } from '../../utils';
+import {
+  getGlobalSettings,
+  getVariableLookupsInExpression,
+  validateLookup,
+  offsetAdjust,
+  type Vars,
+} from './visible-if-utils';
+
+// Note that unlike most other files in the `checks` directory, this exports two
+// checks: one for Liquid files and one for 'config/settings_schema.json'. They
+// perform the same check using the same logic (modulo differences extracting
+// the schema and determining warning start and end indices).
+
+const meta = {
+  code: 'ValidVisibleIf',
+  name: 'Validate visible_if expressions',
+  docs: {
+    description:
+      'Ensures visible_if expressions are well-formed and only reference settings keys that are defined',
+    recommended: true,
+    url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-visible-if',
+  },
+  severity: Severity.ERROR,
+  schema: {},
+  targets: [],
+};
+
+export const ValidVisibleIf: LiquidCheckDefinition = {
+  meta: { ...meta, type: SourceCodeType.LiquidHtml },
+
+  create(context) {
+    return {
+      async LiquidRawTag(node) {
+        if (node.name !== 'schema' || node.body.kind !== 'json') return;
+
+        const schema = await getSchema(context);
+
+        const { validSchema, ast } = schema ?? {};
+        if (
+          !validSchema ||
+          validSchema instanceof Error ||
+          !validSchema.settings?.some((setting) => 'visible_if' in setting) ||
+          !ast ||
+          ast instanceof Error
+        ) {
+          return;
+        }
+
+        const offset = node.blockStartPosition.end;
+        const settings = Object.fromEntries(
+          (await getGlobalSettings(context)).map((s) => [s, true] as const),
+        );
+        const currentFileSettings = Object.fromEntries(
+          validSchema.settings.map((setting) => [setting.id, true] as const),
+        );
+
+        const vars: Vars = { settings };
+        if (isSectionSchema(schema)) {
+          vars.section = { settings: currentFileSettings };
+        } else if (isBlockSchema(schema)) {
+          vars.block = { settings: currentFileSettings };
+        }
+
+        for (const [i, setting] of validSchema.settings.entries()) {
+          if (!('visible_if' in setting) || typeof setting.visible_if !== 'string') continue;
+
+          const visibleIfNode = nodeAtPath(ast, ['settings', i, 'visible_if'])!;
+
+          const varLookupsOrWarning = await getVariableLookupsInExpression(setting.visible_if);
+          if (varLookupsOrWarning === null) continue;
+
+          if ('warning' in varLookupsOrWarning) {
+            reportWarning(varLookupsOrWarning.warning, offset, visibleIfNode, context);
+            continue;
+          }
+
+          const report = (message: string | null, lookup: LiquidVariableLookup) => {
+            if (typeof message === 'string') {
+              context.report({
+                message,
+                // the JSONNode start location returned by `getLocStart`
+                // includes the opening quotation mark — whereas when we parse
+                // the inner expression, 0 is the location _inside_ the quotes.
+                // we add 1 to the offsets to compensate.
+                startIndex:
+                  offset + getLocStart(visibleIfNode) + lookup.position.start + offsetAdjust + 1,
+                endIndex:
+                  offset + getLocStart(visibleIfNode) + lookup.position.end + offsetAdjust + 1,
+              });
+            }
+          };
+
+          for (const lookup of varLookupsOrWarning) {
+            if (lookup.name === 'section' && isBlockSchema(schema)) {
+              //no-op, we don't know what section this block will be used in, so we can't validate that the setting exists
+            } else if (lookup.name === 'section' && !isSectionSchema(schema)) {
+              report(
+                `Invalid visible_if: can't refer to "section" when not in a section or block file.`,
+                lookup,
+              );
+            } else if (lookup.name === 'block' && !isBlockSchema(schema)) {
+              report(
+                `Invalid visible_if: can't refer to "block" when not in a block file.`,
+                lookup,
+              );
+            } else {
+              report(validateLookup(lookup, vars), lookup);
+            }
+          }
+        }
+      },
+    };
+  },
+};
+
+export const ValidVisibleIfSettingsSchema: JSONCheckDefinition = {
+  meta: { ...meta, type: SourceCodeType.JSON },
+
+  create(context) {
+    const relativePath = context.toRelativePath(context.file.uri);
+    if (relativePath !== 'config/settings_schema.json') return {};
+
+    return {
+      async Property(node) {
+        if (node.key.value !== 'visible_if' || node.value.type !== 'Literal') return;
+        const visibleIfExpression = node.value.value;
+        if (typeof visibleIfExpression !== 'string') return;
+        const offset = node.value.loc.start.offset;
+
+        const varLookupsOrWarning = await getVariableLookupsInExpression(visibleIfExpression);
+        if (varLookupsOrWarning === null) return;
+
+        if ('warning' in varLookupsOrWarning) {
+          context.report({
+            message: varLookupsOrWarning.warning,
+            startIndex: node.value.loc.start.offset,
+            endIndex: node.value.loc.end.offset,
+          });
+          return;
+        }
+
+        const settings = Object.fromEntries(
+          (await getGlobalSettings(context)).map((s) => [s, true] as const),
+        );
+
+        const vars: Vars = { settings };
+
+        const report = (message: string | null, lookup: LiquidVariableLookup) => {
+          if (typeof message === 'string') {
+            context.report({
+              message,
+              startIndex: offset + lookup.position.start + offsetAdjust + 1,
+              endIndex: offset + lookup.position.end + offsetAdjust + 1,
+            });
+          }
+        };
+
+        for (const lookup of varLookupsOrWarning) {
+          // settings_schema.json can't reference `section` or `block`.
+          if (lookup.name === 'section') {
+            report(
+              `Invalid visible_if: can't refer to "section" when not in a section file.`,
+              lookup,
+            );
+          } else if (lookup.name === 'block') {
+            report(`Invalid visible_if: can't refer to "block" when not in a block file.`, lookup);
+          } else {
+            report(validateLookup(lookup, vars), lookup);
+          }
+        }
+      },
+    };
+  },
+};

package/src/checks/valid-visible-if/visible-if-utils.ts

@@ -0,0 +1,158 @@
+import {
+  type LiquidVariableLookup,
+  NodeTypes,
+  toLiquidHtmlAST,
+} from '@platformos/liquid-html-parser';
+import { Context, SourceCodeType } from '../..';
+import { parseJSON } from '../../json';
+import { visit } from '../../visitor';
+
+export type Vars = { [key: string]: Vars | true };
+
+export const variableExpressionMatcher = /{{(.+?)}}/;
+export const adjustedPrefix = '{% if ';
+export const adjustedSuffix = ' %}{% endif %}';
+export const offsetAdjust = '{{'.length - adjustedPrefix.length;
+
+export async function getVariableLookupsInExpression(
+  expression: string,
+): Promise<LiquidVariableLookup[] | { warning: string } | null> {
+  // As of February 2025, parsers other than LiquidJS don't yet support
+  // expressions in {{ variable }} tags. So we have to do something a little
+  // gnarly — before parsing it we extract the expression from within the tag
+  // and plunk it into an `{% if <expression> %}{% endif %}` statement instead.
+  // This requires us to adjust the reported character ranges and offer slightly
+  // less useful messages on syntax errors, but otherwise should behave
+  // similarly to a proper `{{ <expression> }}` syntax whenever it lands.
+  const match = variableExpressionMatcher.exec(expression);
+  if (match == null) {
+    return {
+      warning: `Invalid visible_if expression. It should take the form "{{ <expression> }}".`,
+    };
+  }
+  const unwrappedExpression = match[1];
+
+  const adjustedExpression = `${adjustedPrefix}${unwrappedExpression}${adjustedSuffix}`;
+
+  try {
+    const innerAst = toLiquidHtmlAST(adjustedExpression, {
+      mode: 'strict',
+      allowUnclosedDocumentNode: false,
+    });
+
+    if (innerAst.children.length !== 1) {
+      throw new Error('Unexpected child count for DocumentNode');
+    }
+
+    const ifTag = innerAst.children[0];
+
+    if (ifTag.type !== 'LiquidTag' || ifTag.name !== 'if') {
+      throw new Error("Expected DocumentNode to contain 'if' tag");
+    }
+
+    const expressionNode = ifTag.markup;
+    if (typeof expressionNode === 'string') {
+      return {
+        warning: `Invalid visible_if expression.`,
+      };
+    }
+
+    if (
+      expressionNode.type === NodeTypes.LiquidLiteral &&
+      ['true', 'false'].includes(expressionNode.keyword)
+    ) {
+      // Those are OK
+      return null;
+    }
+
+    const vars = await visit<SourceCodeType.LiquidHtml, LiquidVariableLookup>(ifTag, {
+      VariableLookup: async (node) => node,
+    });
+
+    if (vars.length === 0) {
+      return {
+        warning: `visible_if expression contains no references to any settings. This is likely an error.`,
+      };
+    }
+
+    return vars;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      // Because of our hackish approach, the underlying error is likely to
+      // include an incorrect character range and/or mention {% if %} tags.
+      // Squelch the details and just report it as a simple syntax error.
+      return { warning: 'Syntax error: cannot parse visible_if expression.' };
+    }
+
+    return { warning: String(error) };
+  }
+}
+
+export function validateLookup(lookup: LiquidVariableLookup, vars: Vars): string | null {
+  const normalized = getNormalizedLookups(lookup);
+
+  const poppedSegments = [];
+  let scope = vars;
+  while (normalized.length > 0) {
+    const segment = normalized.shift()!;
+    poppedSegments.push(segment);
+
+    // "noUncheckedIndexedAccess" is false in our tsconfig.json
+    const next = scope[segment] as true | Vars | undefined;
+
+    if (!next) {
+      return `Invalid variable: "${poppedSegments.join('.')}" was not found.`;
+    }
+
+    if (typeof next === 'boolean') {
+      if (normalized.length > 0) {
+        return `Invalid variable: "${poppedSegments.join(
+          '.',
+        )}" refers to a variable, but is being used here as a namespace.`;
+      }
+      return null;
+    }
+
+    scope = next;
+  }
+
+  // note this is the reverse of the above similar-looking case
+  return `Invalid variable: "${poppedSegments.join(
+    '.',
+  )}" refers to a namespace, but is being used here as a variable.`;
+}
+
+function getNormalizedLookups(lookup: LiquidVariableLookup) {
+  const nestedLookups = lookup.lookups.map((lookup) => {
+    if (lookup.type !== NodeTypes.String) {
+      throw new Error(`Expected lookups to be String nodes: ${JSON.stringify(lookup)}`);
+    }
+    return lookup.value;
+  });
+
+  return [lookup.name, ...nestedLookups];
+}
+
+export async function getGlobalSettings(context: Context<SourceCodeType>) {
+  const globalSettings: string[] = [];
+
+  try {
+    const uri = context.toUri('config/settings_schema.json');
+    const settingsFile = await context.fs.readFile(uri);
+    const settings = parseJSON(settingsFile);
+    if (Array.isArray(settings)) {
+      for (const group of settings) {
+        if ('settings' in group && Array.isArray(group.settings)) {
+          globalSettings.push(
+            ...group.settings.map((setting: any) => setting.id).filter((id: any) => id),
+          );
+        }
+      }
+    }
+  } catch (e) {
+    console.error('Error fetching global settings:', e);
+    // ignore absent or malformed settings schema
+  }
+
+  return globalSettings;
+}

package/src/checks/variable-name/index.spec.ts

@@ -0,0 +1,62 @@
+import { expect, describe, it } from 'vitest';
+import { VariableName } from './index';
+import { applySuggestions, runLiquidCheck } from '../../test';
+
+describe('Module: VariableName', () => {
+  it('should report an error when a variable is using wrong naming format', async () => {
+    const sourceCode = `{% assign variableName = "value" %}`;
+
+    const offenses = await runLiquidCheck(VariableName, sourceCode);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal("The variable 'variableName' uses wrong naming format");
+  });
+
+  it('should not report an error when a variable is using correct format', async () => {
+    const sourceCode = `{% assign variable_name = "value" %}`;
+
+    const offenses = await runLiquidCheck(VariableName, sourceCode);
+
+    expect(offenses).to.be.empty;
+  });
+
+  it('should provide a suggestion to change the variable naming', async () => {
+    const sourceCode = `{% assign variableName = "value" %}`;
+
+    const offenses = await runLiquidCheck(VariableName, sourceCode);
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].suggest).to.have.length(1);
+    expect(offenses[0]!.suggest![0].message).to.equal(
+      "Change variable 'variableName' to 'variable_name'",
+    );
+  });
+
+  it('should fix the code by changing the wrongly formatted variable', async () => {
+    const sourceCode = `{% assign variableName = "value" %}`;
+
+    const offenses = await runLiquidCheck(VariableName, sourceCode);
+    const suggestions = applySuggestions(sourceCode, offenses[0]);
+
+    const expectedFixedCode = `{% assign variable_name = "value" %}`;
+
+    expect(suggestions).to.include(expectedFixedCode);
+  });
+
+  // It's impossible to make an idempotent rule that works for all cases. We
+  // have to accept whatever spacing the user has input as valid.
+  it('should not complain about numbers inside variable names', async () => {
+    const varNames = [
+      `first_b_2_b_model`,
+      `first_b2_b_model`,
+      `first_b2b_model`,
+      `first_3_d_model`,
+      `first3_d_model`,
+    ];
+    for (const varName of varNames) {
+      const sourceCode = `{% assign ${varName} = "value" %}`;
+      const offenses = await runLiquidCheck(VariableName, sourceCode);
+      expect(offenses).to.be.empty;
+    }
+  });
+});

package/src/checks/variable-name/index.ts

@@ -0,0 +1,115 @@
+import {
+  LiquidHtmlNode,
+  LiquidTag,
+  LiquidTagAssign,
+  LiquidTagCapture,
+  NodeTypes,
+} from '@platformos/liquid-html-parser';
+import { LiquidCheckDefinition, SchemaProp, Severity, SourceCodeType } from '../../types';
+import { camelCase, kebabCase, snakeCase } from 'lodash';
+
+const pascalCase = (string: string) => {
+  const camelCased = camelCase(string);
+  return camelCased.charAt(0).toUpperCase() + camelCased.slice(1);
+};
+
+const isLiquidTagAssign = (node: LiquidTag): node is LiquidTagAssign => {
+  return node.name === 'assign' && typeof node.markup !== 'string';
+};
+
+const isLiquidTagCapture = (node: LiquidHtmlNode): node is LiquidTagCapture => {
+  return (
+    node.type == NodeTypes.LiquidTag && node.name === 'capture' && typeof node.markup !== 'string'
+  );
+};
+
+const formatTypes = {
+  camelCase: camelCase,
+  PascalCase: pascalCase,
+  snake_case: snakeCase,
+  'kebab-case': kebabCase,
+};
+
+type FormatTypes = keyof typeof formatTypes;
+
+const schema = {
+  format: SchemaProp.string('snake_case'),
+};
+
+// It's impossible to make an idempotent rule that works for all cases. We
+// have to accept whatever spacing the user has input as valid.
+// This function strips dash/underscores around digits so that we can at least
+// make sure that the variable name is in the "correct" format. (e.g. snake case)
+const collapseNumberSpacing = (varName: string) => varName.replace(/[-_]?\d[-_]?/g, '');
+
+export const VariableName: LiquidCheckDefinition<typeof schema> = {
+  meta: {
+    code: 'VariableName',
+    name: 'Invalid variable naming format',
+    docs: {
+      description: 'This check is aimed at using certain variable naming conventions',
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/variable-name',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema,
+    targets: [],
+  },
+
+  create(context) {
+    const formatter = (node: LiquidTagAssign | LiquidTagCapture) => {
+      if (!node.markup.name) {
+        return {
+          valid: false,
+        };
+      }
+
+      const formatter = formatTypes[context.settings.format as FormatTypes];
+      const suggestion = formatter(node.markup.name);
+
+      return {
+        valid: collapseNumberSpacing(node.markup.name) === collapseNumberSpacing(suggestion),
+        suggestion,
+      };
+    };
+
+    const reportHandler = (node: LiquidTagAssign | LiquidTagCapture) => {
+      return context.report({
+        message: `The variable '${node.markup.name}' uses wrong naming format`,
+        startIndex: node.markup.position.start,
+        endIndex: node.markup.position.end,
+        suggest: [
+          {
+            message: `Change variable '${node.markup.name}' to '${formatter(node).suggestion}'`,
+            fix: (corrector) => {
+              const { position, name, source } = node.markup;
+
+              return corrector.replace(
+                position.start,
+                position.end,
+                source
+                  .slice(position.start, position.end)
+                  .replace(name!, formatter(node).suggestion!),
+              );
+            },
+          },
+        ],
+      });
+    };
+
+    return {
+      async LiquidTag(node) {
+        if (isLiquidTagAssign(node)) {
+          if (!formatter(node).valid) {
+            reportHandler(node);
+          }
+        } else if (isLiquidTagCapture(node) && node.markup.name) {
+          if (!formatter(node).valid) {
+            reportHandler(node);
+          }
+        }
+      },
+    };
+  },
+};

package/src/context-utils.spec.ts

@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+  makeGetDefaultLocale,
+  makeGetDefaultTranslations,
+  makeGetMetafieldDefinitions,
+} from './context-utils';
+import { MockFileSystem } from './test';
+import { AbstractFileSystem } from '@platformos/platformos-common';
+
+describe('Unit: getDefaultLocale', () => {
+  let fs: AbstractFileSystem;
+  beforeEach(() => {
+    fs = new MockFileSystem(
+      {
+        'gitRootTheme/locales/en.default.json': JSON.stringify({ beverage: 'coffee' }),
+        'gitRootTheme/locales/fr.json': JSON.stringify({ beverage: 'coffee' }),
+        'gitRootTheme/snippet/foo.liquid': JSON.stringify({ beverage: 'coffee' }),
+        'frenchDefault/locales/fr.default.json': JSON.stringify({ beverage: 'café' }),
+        'frenchDefault/snippet/foo.liquid': JSON.stringify({ beverage: 'coffee' }),
+        '.shopify/metafields.json': JSON.stringify({
+          product: [
+            {
+              key: 'color',
+              name: 'color',
+              namespace: 'custom',
+              description: 'the color of the product',
+              type: {
+                category: 'COLOR',
+                name: 'color',
+              },
+            },
+          ],
+        }),
+      },
+      'shopify-vfs:/',
+    );
+  });
+
+  it('should return the correct translations depending on the root', async () => {
+    let getDefaultLocale = makeGetDefaultLocale(fs, 'shopify-vfs:/gitRootTheme');
+    expect(await getDefaultLocale()).to.eql('en');
+
+    getDefaultLocale = makeGetDefaultLocale(fs, 'shopify-vfs:/frenchDefault');
+    expect(await getDefaultLocale()).to.eql('fr');
+  });
+
+  describe('Unit: makeGetMetafieldDefinitions', () => {
+    it('should return metafield definitions in correct format', async () => {
+      const getMetafieldDefinitions = makeGetMetafieldDefinitions(fs);
+
+      let definitions = await getMetafieldDefinitions('shopify-vfs:/');
+
+      expect(definitions.product).toHaveLength(1);
+      expect(definitions.product[0]).deep.equals({
+        key: 'color',
+        name: 'color',
+        namespace: 'custom',
+        description: 'the color of the product',
+        type: {
+          category: 'COLOR',
+          name: 'color',
+        },
+      });
+    });
+
+    it("should return no metafield definitions if file isn't in correct format", async () => {
+      fs = new MockFileSystem(
+        {
+          '.shopify/metafields.json': JSON.stringify('uhoh'),
+        },
+        'shopify-vfs:/',
+      );
+      const getMetafieldDefinitions = makeGetMetafieldDefinitions(fs);
+
+      let definitions = await getMetafieldDefinitions('shopify-vfs:/');
+
+      expect(definitions).deep.equals({
+        article: [],
+        blog: [],
+        collection: [],
+        company: [],
+        company_location: [],
+        location: [],
+        market: [],
+        order: [],
+        page: [],
+        product: [],
+        variant: [],
+        shop: [],
+      });
+    });
+  });
+
+  describe('Unit: getDefaultTranslationsFactory', () => {
+    it('should return the correct translations depending on the root', async () => {
+      let getDefaultTranslations = makeGetDefaultTranslations(fs, [], 'shopify-vfs:/gitRootTheme');
+      expect(await getDefaultTranslations()).to.eql({ beverage: 'coffee' });
+
+      getDefaultTranslations = makeGetDefaultTranslations(fs, [], 'shopify-vfs:/frenchDefault');
+      expect(await getDefaultTranslations()).to.eql({ beverage: 'café' });
+    });
+  });
+});