@platformos/platformos-check-common 0.0.2

package/src/checks/matching-translations/index.spec.ts

@@ -0,0 +1,400 @@
+import { expect, describe, it } from 'vitest';
+import { autofix, check, highlightedOffenses } from '../../test';
+import { MatchingTranslations } from '../../checks/matching-translations/index';
+
+const prettyJSON = (json: any) => JSON.stringify(json, null, 2);
+
+describe('Module: MatchingTranslations', async () => {
+  it('should report offenses when the translation file is missing a key', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: 'Hello',
+          world: 'World',
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: 'Olá',
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+
+      expect(offenses).to.be.of.length(1);
+      expect(offenses).to.containOffense("The translation for 'world' is missing");
+    }
+  });
+
+  it('should report offenses when the default translation is missing a key', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: 'Hello',
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: 'Olá',
+          world: 'Mundo',
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+
+      expect(offenses).to.be.of.length(1);
+      expect(offenses).to.containOffense("A default translation for 'world' does not exist");
+      expect(offenses[0]!).to.suggest(
+        theme[`locales/pt-BR${prefix}.json`],
+        'Delete unneeded translation key',
+        {
+          startIndex: 0,
+          endIndex: theme[`locales/pt-BR${prefix}.json`].length,
+          insert: prettyJSON({
+            hello: 'Olá',
+          }),
+        },
+      );
+    }
+  });
+
+  it('should report offenses when nested translation keys do not exist', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: { world: 'Hello, world!' },
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: {},
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+
+      expect(offenses).to.be.of.length(1);
+      expect(offenses).to.containOffense({
+        message: "The translation for 'hello.world' is missing",
+        uri: `file:///locales/pt-BR${prefix}.json`,
+      });
+
+      const fixed = await autofix(theme, offenses);
+      expect(fixed[`locales/pt-BR${prefix}.json`]).to.eql(
+        prettyJSON({
+          hello: {
+            world: 'TODO',
+          },
+        }),
+      );
+    }
+  });
+
+  it('should report offenses when translation shapes do not match', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: { world: 'Hello, world!' },
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: 'Olá',
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+
+      expect(offenses).to.be.of.length(2);
+      expect(offenses).to.containOffense({
+        message: "A default translation for 'hello' does not exist",
+        uri: `file:///locales/pt-BR${prefix}.json`,
+      });
+      expect(offenses).to.containOffense({
+        message: "The translation for 'hello.world' is missing",
+        uri: `file:///locales/pt-BR${prefix}.json`,
+      });
+
+      const fixed = await autofix(theme, offenses);
+
+      expect(fixed[`locales/pt-BR${prefix}.json`]).to.eql(
+        prettyJSON({
+          hello: { world: 'TODO' },
+        }),
+      );
+    }
+  });
+
+  it('should report offenses when nested translation keys do not match', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: { world: 'Hello, world!' },
+        }),
+        [`locales/fr${prefix}.json`]: JSON.stringify({
+          hello: { monde: 'Bonjour, monde' },
+        }),
+        [`locales/es-ES${prefix}.json`]: JSON.stringify({
+          hello: { world: 'Hello, world!', mundo: { hola: '¡Hola, mundo!' } },
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+
+      expect(offenses).to.be.of.length(3);
+      expect(offenses).to.containOffense({
+        message: "A default translation for 'hello.monde' does not exist",
+        uri: `file:///locales/fr${prefix}.json`,
+      });
+      expect(offenses).to.containOffense({
+        message: "A default translation for 'hello.mundo.hola' does not exist",
+        uri: `file:///locales/es-ES${prefix}.json`,
+      });
+      expect(offenses).to.containOffense({
+        message: "The translation for 'hello.world' is missing",
+        uri: `file:///locales/fr${prefix}.json`,
+      });
+
+      const fixed = await autofix(theme, offenses);
+      expect(fixed[`locales/fr${prefix}.json`]).to.eql(
+        prettyJSON({
+          hello: { monde: 'Bonjour, monde', world: 'TODO' },
+        }),
+      );
+
+      // Default does not exist should be a suggestion and not autofixed.
+      expect(fixed[`locales/es-ES${prefix}.json`]).to.eql(theme[`locales/es-ES${prefix}.json`]);
+    }
+  });
+
+  it('should not report offenses when default translations do not exist', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en${prefix}.json`]: JSON.stringify({
+          hello: 'Hello',
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: 'Olá',
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+
+      expect(offenses).to.be.of.length(0);
+    }
+  });
+
+  it('should not report offenses when translations match', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: 'Hello',
+          world: 'World',
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: 'Olá',
+          world: 'Mundo',
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+
+      expect(offenses).to.be.of.length(0);
+    }
+  });
+
+  it('should not report offenses when nested translations match', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: { world: 'Hello, world!' },
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: { world: 'Olá, mundo!' },
+        }),
+        [`locales/fr${prefix}.json`]: JSON.stringify({
+          hello: { world: 'Bonjour, monde' },
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+
+      expect(offenses).to.be.of.length(0);
+    }
+  });
+
+  it('should not report offenses and ignore pluralization', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: {
+            one: 'Hello, you',
+            other: "Hello, y'all",
+          },
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: {
+            zero: 'Estou sozinho :(',
+            few: 'Olá, galerinha :)',
+          },
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+
+      expect(offenses).to.be.of.length(0);
+    }
+  });
+
+  it('should not report offenses and ignore keys provided by Shopify', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: 'Hello',
+          shopify: {
+            checkout: {
+              general: {
+                page_title: 'Checkout',
+              },
+            },
+          },
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: 'Olá',
+          shopify: {
+            sentence: {
+              words_connector: 'hello world',
+            },
+          },
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+
+      expect(offenses).to.be.of.length(0);
+    }
+  });
+
+  it('should not report offenses and ignore "*.schema.json" files', async () => {
+    const theme = {
+      'locales/en.default.json': JSON.stringify({ hello: 'Hello' }),
+      'locales/pt-BR.schema.json': JSON.stringify({}),
+    };
+
+    const offenses = await check(theme, [MatchingTranslations]);
+
+    expect(offenses).to.be.of.length(0);
+  });
+
+  it('should highlight the proper element when the translation file is missing a key', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: 'Hello',
+          world: 'World',
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: 'Olá',
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+      const elements = highlightedOffenses(theme, offenses);
+
+      expect(elements).to.deep.eq(['{"hello":"Olá"}']);
+    }
+  });
+
+  it('should highlight the proper element when the default translation is missing a key', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: 'Hello',
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: 'Olá',
+          world: 'Mundo',
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+      const elements = highlightedOffenses(theme, offenses);
+
+      expect(elements).to.deep.eq(['"world":"Mundo"']);
+    }
+  });
+
+  it('should highlight the proper element when nested translation keys do not exist', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: {
+            world: 'Hello, world!',
+          },
+          welcome: 'Welcome',
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: {},
+          welcome: 'Bem-vinda',
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+      const elements = highlightedOffenses(theme, offenses);
+
+      expect(elements).to.deep.eq(['"hello":{}']);
+    }
+  });
+
+  it('should highlight the proper element when nested translation keys do not exist and there is a sibling node', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: {
+            shopify: 'Shopify!',
+            world: 'Hello, world!',
+          },
+          welcome: 'Welcome',
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: {
+            shopify: 'Shopify!',
+          },
+          welcome: 'Bem-vinda',
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+      const elements = highlightedOffenses(theme, offenses);
+
+      expect(elements).to.deep.eq(['"hello":{"shopify":"Shopify!"}']);
+    }
+  });
+
+  it('should highlight the proper element when translation shapes do not match', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: { world: 'Hello, world!' },
+        }),
+        [`locales/pt-BR${prefix}.json`]: JSON.stringify({
+          hello: 'Olá',
+        }),
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+      const elements = highlightedOffenses(theme, offenses);
+
+      // We have two elements because we have two offenses:
+      // - A default translation for 'hello' does not exist"
+      // - The translation for 'hello.world' is missing"
+      expect(elements).to.deep.eq(['"hello":"Olá"', '"hello":"Olá"']);
+    }
+  });
+
+  it('should not highlight anything if the file is unparseable', async () => {
+    for (const prefix of ['', '.schema']) {
+      const theme = {
+        [`locales/en.default${prefix}.json`]: JSON.stringify({
+          hello: { world: 'Hello, world!' },
+        }),
+        [`locales/pt-BR${prefix}.json`]: `{"hello": }`,
+      };
+
+      const offenses = await check(theme, [MatchingTranslations]);
+      expect(offenses).to.have.length(0);
+    }
+  });
+});

package/src/checks/matching-translations/index.ts

@@ -0,0 +1,175 @@
+import {
+  JSONCheckDefinition,
+  JSONNode,
+  JSONSourceCode,
+  Severity,
+  SourceCodeType,
+  PropertyNode,
+} from '../../types';
+
+const PLURALIZATION_KEYS = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);
+
+export const MatchingTranslations: JSONCheckDefinition = {
+  meta: {
+    code: 'MatchingTranslations',
+    name: 'Translation files should have the same keys',
+    docs: {
+      description: 'TODO',
+      recommended: true,
+      url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/matching-translations',
+    },
+    type: SourceCodeType.JSON,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    // State
+    const defaultTranslations = new Set<string>();
+    const missingTranslations = new Set<string>();
+    const nodesByPath = new Map<string, PropertyNode>();
+    const file = context.file;
+    const fileUri = file.uri;
+    const relativePath = context.toRelativePath(fileUri);
+    const ast = file.ast;
+    const isLocaleFile = relativePath.startsWith('locales/');
+    const isDefaultTranslationsFile =
+      fileUri.endsWith('.default.json') || fileUri.endsWith('.default.schema.json');
+    const isSchemaTranslationFile = fileUri.endsWith('.schema.json');
+
+    if (!isLocaleFile || isDefaultTranslationsFile || ast instanceof Error) {
+      // No need to lint a file that isn't a translation file, we return an
+      // empty object as the check for those.
+      return {};
+    }
+
+    // Helpers
+    const hasDefaultTranslations = () => defaultTranslations.size > 0;
+    const isTerminalNode = ({ type }: JSONNode) => type === 'Literal';
+    const isPluralizationNode = (node: PropertyNode) => PLURALIZATION_KEYS.has(node.key.value);
+    const isShopifyPath = (path: string) => path.startsWith('shopify.');
+
+    const hasDefaultTranslation = (translationPath: string) =>
+      defaultTranslations.has(translationPath) ?? false;
+
+    const isPluralizationPath = (path: string) =>
+      [...PLURALIZATION_KEYS].some((key) => path.endsWith(key));
+
+    const jsonPaths = (json: any): string[] => {
+      const keys = Object.keys(json);
+
+      return keys.reduce((acc: string[], key: string) => {
+        if (typeof json[key] !== 'object') {
+          return acc.concat(key);
+        }
+
+        const childJson = json[key];
+        const childPaths = jsonPaths(childJson);
+
+        return acc.concat(childPaths.map((path) => `${key}.${path}`));
+      }, []);
+    };
+
+    const objectPath = (nodes: JSONNode[]) => {
+      return nodes
+        .filter((node): node is PropertyNode => node.type === 'Property')
+        .reduce((acc: string[], val) => acc.concat(val.key.value), [])
+        .join('.');
+    };
+
+    const countCommonParts = (arrayA: string[], arrayB: string[]): number => {
+      const minLength = Math.min(arrayA.length, arrayB.length);
+
+      for (let i = 0; i < minLength; i++) {
+        if (arrayA[i] !== arrayB[i]) {
+          return i;
+        }
+      }
+
+      return minLength;
+    };
+
+    const closestTranslationKey = (translationKey: string) => {
+      const translationKeyParts = translationKey.split('.');
+      let closestMatch = '';
+      let maxCommonParts = 0;
+
+      for (const path of nodesByPath.keys()) {
+        const pathParts = path.split('.');
+        const commonParts = countCommonParts(pathParts, translationKeyParts);
+
+        if (commonParts > maxCommonParts) {
+          maxCommonParts = commonParts;
+          closestMatch = path;
+        }
+      }
+
+      return nodesByPath.get(closestMatch) ?? ast;
+    };
+
+    return {
+      async onCodePathStart() {
+        const getDefaultTranslations = isSchemaTranslationFile
+          ? context.getDefaultSchemaTranslations
+          : context.getDefaultTranslations;
+        const defaultTranslationPaths = await getDefaultTranslations().then(jsonPaths);
+        defaultTranslationPaths.forEach(Set.prototype.add, defaultTranslations);
+
+        // At the `onCodePathStart`, we assume that all translations are missing,
+        // and remove translation paths while traversing through the file.
+        defaultTranslationPaths.forEach(Set.prototype.add, missingTranslations);
+      },
+
+      async Property(node, ancestors) {
+        const path = objectPath(ancestors.concat(node));
+
+        nodesByPath.set(path, node);
+
+        if (!hasDefaultTranslations()) return;
+        if (isPluralizationNode(node)) return;
+        if (!isTerminalNode(node.value)) return;
+        if (isShopifyPath(path)) return;
+
+        if (hasDefaultTranslation(path)) {
+          // As `path` is present, we remove it from the
+          // `missingTranslationsPerFile` bucket.
+          missingTranslations.delete(path);
+          return;
+        }
+
+        context.report({
+          message: `A default translation for '${path}' does not exist`,
+          startIndex: node.loc!.start.offset,
+          endIndex: node.loc!.end.offset,
+          suggest: [
+            {
+              message: 'Delete unneeded translation key',
+              fix(corrector) {
+                corrector.remove(path);
+              },
+            },
+          ],
+        });
+      },
+
+      async onCodePathEnd() {
+        missingTranslations.forEach((path) => {
+          const closest = closestTranslationKey(path);
+
+          if (isPluralizationPath(path)) return;
+          if (isShopifyPath(path)) return;
+
+          context.report({
+            message: `The translation for '${path}' is missing`,
+            startIndex: closest.loc!.start.offset,
+            endIndex: closest.loc!.end.offset,
+            fix(corrector) {
+              corrector.add(path, 'TODO');
+            },
+          });
+        });
+      },
+    };
+  },
+};

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

@@ -0,0 +1,103 @@
+import { expect, describe, it } from 'vitest';
+import { MetadataParamsCheck } from '.';
+import { check } from '../../test';
+
+describe('Module: MetadataParamsCheck', () => {
+  it('should report the missing variable when not defined but passed', async () => {
+    const file = `
+      ---
+      metadata:
+        params:
+          variable: {}
+          variable3: {}
+      ---
+      {% assign a = 5 | plus: variable | plus: variable2 %}
+      {{ a }}
+    `;
+    const file2 = `
+      {% function a = 'commands/call/fileToCall', variable: 2, variable2: 12 %}
+      {{ a }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [MetadataParamsCheck]);
+
+    expect(offenses).to.have.length(2);
+    expect(offenses).to.containOffense('Unknown parameter variable2 passed to function call');
+    expect(offenses).to.containOffense(
+      'Required parameter variable3 must be passed to function call',
+    );
+  });
+
+  it('should ignore if metadata not defined', async () => {
+    const file = `
+      ---
+      metadata:
+      ---
+      {% assign a = 5 | plus: variable | plus: variable2 %}
+      {{ a }}
+    `;
+    const file2 = `
+      {% function a = 'commands/call/fileToCall', variable: 2, variable2: 12 %}
+      {{ a }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [MetadataParamsCheck]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should accept doc tag if metadata not defined', async () => {
+    const file = `
+      {% doc %}
+        @param {Number} variable - param with description
+        @param {Number} variable2 - param with description
+      {% enddoc %}
+
+      {% assign a = 5 | plus: variable | plus: variable2 %}
+      {{ a }}
+    `;
+    const file2 = `
+      {% function a = 'commands/call/fileToCall', variable: 2, variable2: 12 %}
+      {{ a }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [MetadataParamsCheck]);
+
+    expect(offenses).to.have.length(0);
+  });
+
+  it('should reject if doc tag is missing params', async () => {
+    const file = `
+      {% doc %}
+        @param {Number} variable - param with description
+      {% enddoc %}
+
+      {% assign a = 5 | plus: variable | plus: variable2 %}
+      {{ a }}
+    `;
+    const file2 = `
+      {% function a = 'commands/call/fileToCall', variable: 2, variable2: 12 %}
+      {{ a }}
+    `;
+    const files = {
+      'app/lib/commands/call/fileToCall.liquid': file,
+      'app/lib/caller.liquid': file2,
+    };
+
+    const offenses = await check(files, [MetadataParamsCheck]);
+
+    expect(offenses).to.have.length(1);
+  });
+});