@discord/eslint-plugin-discord-intl 0.4.2-canary.6e372bd

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Discord, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# eslint-plugin-discord-intl
+
+An ESLint (v8) plugin for linting intl messages in the `@discord/intl` system. Currently this linter only checks best
+practices for messages like whitespace and access notation in other source files, but will eventually be able to lint
+the content of messages themselves using the database's `validateMessages` API.
+
+## Install
+
+```shell
+pnpm add -D @discord/eslint-plugin-discord-intl
+```
+
+## Configure
+
+```javascript
+module.exports = {
+  // Extend the recommended plugin configuration
+  extends: ['plugin:@discord/eslint-plugin-discord-intl/recommended'],
+  // Optionally add configuration for all rules
+  settings: {
+    '@discord/discord-intl': {
+      extraImports: {
+        '@app/intl': ['t'],
+      },
+    },
+  },
+};
+```

package/index.js

@@ -0,0 +1,15 @@
+module.exports = {
+  rules: {
+    'trimmed-whitespace': require('./rules/trimmable-whitespace'),
+    'use-static-access': require('./rules/use-static-access'),
+  },
+  configs: {
+    recommended: {
+      plugins: ['@discord/discord-intl'],
+      rules: {
+        '@discord/discord-intl/trimmed-whitespace': 'error',
+        '@discord/discord-intl/use-static-access': 'error',
+      },
+    },
+  },
+};

package/lib/traverse.js

@@ -0,0 +1,146 @@
+const { isMessageDefinitionsFile } = require('@discord/intl-loader-core');
+
+/** @typedef {import('eslint').Rule.RuleListener} RuleListener */
+/** @typedef {import('eslint').Rule.RuleContext} RuleContext */
+/** @typedef {import('estree').MemberExpression} MemberExpression */
+/** @typedef {import('estree').BaseModuleSpecifier} BaseModuleSpecifier */
+/** @typedef {import('estree').ObjectExpression} ObjectExpression */
+/** @typedef {import('estree').SimpleLiteral} SimpleLiteral */
+/** @typedef {import('estree').TemplateLiteral} TemplateLiteral */
+/** @typedef {import('estree').Property} Property */
+
+/**
+ * @typedef {(node: MemberExpression, importer: BaseModuleSpecifier) => void} MessageAccessCallback
+ * @typedef {(
+ *  property: Property,
+ *  value: SimpleLiteral | TemplateLiteral,
+ *  definition: ObjectExpression | undefined,
+ * ) => void} MessageDefinitionCallback
+ */
+
+/**
+ * Visit all `MemberExpression`s that act as accesses to intl messages, even if they are not
+ * statically analyzable. All accesses on all imported message objects will be traversed in a
+ * single pass, invoking `callback` for each one with the MemberExpression node as the first
+ * argument, and the specifier that imported the messages object as the second.
+ *
+ * @param {RuleContext} context The rule context from ESLint
+ * @param {MessageAccessCallback} callback Function to call for each instance of a message access
+ * @returns {RuleListener} A visitor object for the Babel transform.
+ */
+function traverseMessageAccesses(context, callback) {
+  const config = context.settings['@discord/discord-intl'];
+  const source = context.sourceCode;
+
+  return /** @type {RuleListener} */ ({
+    ImportDeclaration(path) {
+      const importSource = /** @type {string} */ (path.source.value);
+      // TODO: Make `isMessageDefinitionsFile` understand this properly.
+      const isDefinition =
+        isMessageDefinitionsFile(importSource) || importSource.endsWith('.messages');
+      const extraImportSpecifiers = config.extraImports?.[importSource] ?? [];
+      // This transformer only handles usages of intl messages, so only
+      // imports of definitions files and configured extra specifiers need to
+      // be handled.
+      if (!isDefinition && extraImportSpecifiers.length === 0) {
+        return;
+      }
+
+      const specifiers = path.specifiers.filter(
+        (specifier) =>
+          (isDefinition && specifier.type === 'ImportDefaultSpecifier') ||
+          extraImportSpecifiers.includes(specifier.local.name),
+      );
+
+      for (const specifier of specifiers) {
+        const bindingReferences = source
+          .getDeclaredVariables(specifier)
+          // This should only ever yield 1 variable, so flatMap is unnecessary, but it is safer to
+          // use in case this changes in the future.
+          .flatMap((variable) => variable.references);
+
+        for (const reference of bindingReferences) {
+          // @ts-expect-error `identifier` is actually `Identifier & NodeParentExtension`.
+          const parent = reference.identifier.parent;
+
+          // We only care about member expressions, since a direct reference to the
+          // message source doesn't necessarily make it a message access.
+          if (parent.type !== 'MemberExpression') continue;
+
+          callback(/** @type {MemberExpression} */ parent, specifier);
+        }
+      }
+    },
+  });
+}
+
+/**
+ * Visit all Message definitions in the file, invoking `callback` for each one with the string
+ * value node as the first argument and, if present, the full definition object as the second
+ * argument.
+ *
+ * @param {RuleContext} context The rule context from ESLint
+ * @param {MessageDefinitionCallback} callback Function to call for each message definition.
+ * @returns {RuleListener} A visitor object for the Babel transform.
+ */
+function traverseMessageDefinitions(context, callback) {
+  const source = context.sourceCode;
+
+  return /** @type {RuleListener} */ ({
+    CallExpression(path) {
+      // Only look at direct `defineMessages` function calls.
+      if (path.callee.type !== 'Identifier' || path.callee.name !== 'defineMessages') return;
+
+      // This is a very roundabout way of determining that the current CallExpression is calling
+      // the `defineMessages` function that was directly imported from `@discord/intl`.
+      const importingDefinitionSource = source
+        .getScope(path)
+        .variables[0].defs.find((definition) => definition.type === 'ImportBinding')?.parent
+        .source.value;
+      if (importingDefinitionSource !== '@discord/intl') return;
+
+      const definitionsObject = path.arguments[0];
+      // This early return assumes something else can/will assert that the call expression is valid.
+      // In almost every case, that's TypeScript, so we don't need to report on it twice.
+      if (definitionsObject.type !== 'ObjectExpression') return;
+
+      for (const property of definitionsObject.properties) {
+        // Spreads aren't analyzable here, and probably shouldn't be allowed.
+        // TODO: Apply a lint when a Spread is encountered? Or follow it to the definition.
+        if (property.type === 'SpreadElement') continue;
+
+        switch (property.value.type) {
+          case 'Literal':
+          case 'TemplateLiteral':
+            callback(
+              property,
+              /** @type {SimpleLiteral | TemplateLiteral} */ (property.value),
+              undefined,
+            );
+            break;
+          case 'ObjectExpression': {
+            console.log('got expression');
+            const messageProperty = property.value.properties.find((prop) => {
+              return prop.type === 'Property' && 'name' in prop.key && prop.key.name === 'message';
+            });
+            if (
+              messageProperty == null ||
+              messageProperty.type === 'SpreadElement' ||
+              messageProperty.value.type !== 'Literal'
+            ) {
+              break;
+            }
+
+            callback(
+              property,
+              /** @type {SimpleLiteral} */ (messageProperty.value),
+              property.value,
+            );
+          }
+        }
+      }
+    },
+  });
+}
+
+module.exports = { traverseMessageAccesses, traverseMessageDefinitions };

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@discord/eslint-plugin-discord-intl",
+  "version": "0.4.2-canary.6e372bd",
+  "license": "MIT",
+  "type": "commonjs",
+  "description": "ESLint plugin for validating and linting messages and translations using @discord/intl",
+  "main": "index.js",
+  "dependencies": {
+    "@discord/intl-loader-core": "0.4.2"
+  },
+  "devDependencies": {
+    "@types/eslint": "^8.56.12",
+    "@types/estree": "^1.0.6",
+    "eslint": "8.57.1"
+  }
+}

package/rules/trimmable-whitespace.js

@@ -0,0 +1,51 @@
+const util = require('node:util');
+const { traverseMessageDefinitions } = require('../lib/traverse');
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function trimLeadingWhitespace(raw) {
+  return raw.replace(/^(\s|\\[rtn])+/, '');
+}
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function trimTrailingWhitespace(raw) {
+  return raw.replace(/(\s|\\[rtn])+$/, '');
+}
+
+module.exports = /** @type {import('eslint').Rule.RuleModule} */ ({
+  meta: {
+    fixable: 'code',
+    docs: {
+      description: 'Disallow whitespace at the beginning and end of intl messages',
+      category: 'Best Practices',
+    },
+    messages: {
+      noWhitespace:
+        'Do not add leading/trailing whitespace to messages. It can lead to inconsistency and ambiguity during translation',
+    },
+  },
+  create(context) {
+    return traverseMessageDefinitions(context, (_property, value, _definition) => {
+      const sourceText = context.sourceCode.getText(value);
+      const quote = sourceText[0];
+      const rawNoQuotes = sourceText.slice(1, -1);
+
+      const trimmed = trimLeadingWhitespace(trimTrailingWhitespace(rawNoQuotes));
+      util.inspect(rawNoQuotes);
+      util.inspect(trimmed);
+      if (trimmed === rawNoQuotes) return;
+
+      context.report({
+        node: value,
+        messageId: 'noWhitespace',
+        fix(fixer) {
+          return [fixer.replaceText(value, `${quote}${trimmed}${quote}`)];
+        },
+      });
+    });
+  },
+});

package/rules/trimmable-whitespace.test.js

@@ -0,0 +1,133 @@
+// enforce-foo-bar.test.js
+const { RuleTester } = require('eslint');
+const trimmableWhitespace = require('./trimmable-whitespace');
+
+const ruleTester = new RuleTester({
+  // Must use at least ecmaVersion 2015 because
+  // that's when `const` variables were introduced.
+  parserOptions: { ecmaVersion: 2015, sourceType: 'module' },
+});
+
+/**
+ * @param {string} messages
+ */
+function defineMessages(messages) {
+  return `
+    import {defineMessages} from '@discord/intl';
+
+    export default defineMessages(${messages});
+  `;
+}
+
+ruleTester.run('trimmable-whitespace', trimmableWhitespace, {
+  valid: [
+    {
+      name: 'normal strings',
+      code: defineMessages("{ A: 'no trimmable whitespace' }"),
+    },
+    {
+      name: 'templates',
+      code: defineMessages(
+        '{ A: `no trimmable whitespace`, QUASI: `${  space  }`, MULTILINE: `hi\n  yes` }',
+      ),
+    },
+    {
+      name: 'multi-line',
+      code: defineMessages(
+        `{ A: \`no trimmable
+        whitespace\`}`,
+      ),
+    },
+    {
+      name: 'object',
+      code: defineMessages(
+        '{ A: { message: "no whitespace", description: "  does not matter here  " }}',
+      ),
+    },
+  ],
+  invalid: [
+    {
+      code: defineMessages(`{
+        A: '  leading whitespace',
+        B: 'trailing whitespace  ',
+        C: '  surrounding whitespace  ',
+      }`),
+      output: defineMessages(`{
+        A: 'leading whitespace',
+        B: 'trailing whitespace',
+        C: 'surrounding whitespace',
+      }`),
+      errors: 3,
+    },
+    {
+      code: defineMessages(`{
+        TABS: '\tleading whitespace',
+        B: 'trailing whitespace\t',
+        C: '\tsurrounding whitespace\t',
+      }`),
+      output: defineMessages(`{
+        TABS: 'leading whitespace',
+        B: 'trailing whitespace',
+        C: 'surrounding whitespace',
+      }`),
+      errors: 3,
+    },
+    {
+      code: defineMessages(`{
+        NEWLINES: '\\nleading whitespace',
+        B: 'trailing whitespace\\n',
+        C: '\\nsurrounding whitespace\\n',
+      }`),
+      output: defineMessages(`{
+        NEWLINES: 'leading whitespace',
+        B: 'trailing whitespace',
+        C: 'surrounding whitespace',
+      }`),
+      errors: 3,
+    },
+    {
+      code: defineMessages(`{
+        MIXED: '\\n  \\t leading\\n  \\twhitespace  \\t\\n',
+      }`),
+      output: defineMessages(`{
+        MIXED: 'leading\\n  \\twhitespace',
+      }`),
+      errors: 1,
+    },
+    {
+      code: defineMessages(`{
+        ONLY_BROKEN: '\\n \\t leading\\n  \\twhitespace  \\t\\n',
+        VALID: 'valid string',
+      }`),
+      output: defineMessages(`{
+        ONLY_BROKEN: 'leading\\n  \\twhitespace',
+        VALID: 'valid string',
+      }`),
+      errors: 1,
+    },
+    {
+      name: 'template quasis',
+      code: defineMessages('{ A: `no trimmable whitespace`, QUASI: ` ${  space  } ` }'),
+      output: defineMessages('{ A: `no trimmable whitespace`, QUASI: `${  space  }` }'),
+      errors: 1,
+    },
+    {
+      name: 'multiline templates',
+      code: defineMessages('{ A: `no trimmable whitespace`, QUASI: `\n\t${  space  }\n  ` }'),
+      output: defineMessages('{ A: `no trimmable whitespace`, QUASI: `${  space  }` }'),
+      errors: 1,
+    },
+    {
+      name: 'object',
+      code: defineMessages(
+        '{ A: { message: " no whitespace", description: "  does not matter here  " }}',
+      ),
+      output: defineMessages(
+        '{ A: { message: "no whitespace", description: "  does not matter here  " }}',
+      ),
+      errors: 1,
+    },
+  ],
+});
+
+console.log('All tests passed!');

package/rules/use-static-access.js

@@ -0,0 +1,100 @@
+const { traverseMessageAccesses } = require('../lib/traverse');
+
+/**
+ * Output from import('identifier-regex').then((regex) => regex()). Used
+ * directly because ESLint 8 doesn't support ESM plugins nicely, so we
+ * have to stick in common JS.
+ */
+const IDENTIFIER_REGEX =
+  /^(?!await|break|case|catch|class|const|continue|debugger|default|delete|do|else|enum|export|extends|false|finally|for|function|if|import|in|instanceof|new|null|return|super|switch|this|throw|true|try|typeof|var|void|while|with|yield|implements|interface|package|private|protected|public|arguments|eval|globalThis|Infinity|NaN|undefined)[$_\p{ID_Start}][$_\u200C\u200D\p{ID_Continue}]*$/u;
+
+/**
+ * Returns true if the given value is able to be written as an identifier rather than requiring a
+ * string container.
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isValidIdentifier(value) {
+  return IDENTIFIER_REGEX.test(value);
+}
+
+module.exports = /** @type {import('eslint').Rule.RuleModule} */ ({
+  meta: {
+    fixable: 'code',
+    docs: {
+      description:
+        'Ensure Intl Message accesses are statically analyzable by requiring dot notation, rather than computed accesses with `[]` brackets, using variables for message names, or interpolated template strings.',
+      category: 'Best Practices',
+    },
+    messages: {
+      computedAccess:
+        'Messages should only be accessed with dot notation to be properly transformed during bundling',
+      nonStringKey:
+        'Message objects only contain names as keys. Any other type will always be incorrect',
+      invalidName: 'Message names must be valid identifiers for use with dot access notation',
+      interpolatedTemplate:
+        'Template strings should not be used to access messages. Use a static name with dot access instead',
+      staticTemplate:
+        'Avoid template strings for message accesses to ensure they are always static',
+    },
+  },
+
+  create(context) {
+    return traverseMessageAccesses(context, (node) => {
+      // If it's already using dot access, then every condition must already be met.
+      if (!node.computed) return;
+
+      const receiver = context.sourceCode.getText(node.object);
+      const property = node.property;
+
+      if (property.type === 'TemplateLiteral') {
+        if (property.quasis.length === 1) {
+          const messageName = property.quasis[0].value.raw;
+          if (!isValidIdentifier(messageName)) {
+            context.report({ node: property, messageId: 'invalidName' });
+            return;
+          }
+          context.report({
+            node,
+            messageId: 'computedAccess',
+            fix(fixer) {
+              return fixer.replaceText(node, `${receiver}.${messageName}`);
+            },
+          });
+        } else {
+          context.report({
+            node,
+            messageId: 'interpolatedTemplate',
+            // Not fixable because the interpolation isn't knowable at compile time.
+          });
+        }
+        return;
+      }
+
+      if (property.type === 'Literal') {
+        if (typeof property.value !== 'string') {
+          context.report({ node: property, messageId: 'nonStringKey' });
+          return;
+        }
+        const messageName = property.value;
+        if (!isValidIdentifier(messageName)) {
+          context.report({ node: property, messageId: 'invalidName' });
+          return;
+        }
+        context.report({
+          node,
+          messageId: 'computedAccess',
+          fix(fixer) {
+            return fixer.replaceText(node, `${receiver}.${messageName}`);
+          },
+        });
+        return;
+      }
+
+      context.report({
+        node,
+        messageId: 'nonStringKey',
+      });
+    });
+  },
+});

package/rules/use-static-access.test.js

@@ -0,0 +1,108 @@
+// enforce-foo-bar.test.js
+const { RuleTester } = require('eslint');
+const useStaticAccess = require('./use-static-access');
+
+const ruleTester = new RuleTester({
+  // Must use at least ecmaVersion 2015 because
+  // that's when `const` variables were introduced.
+  parserOptions: { ecmaVersion: 2015, sourceType: 'module' },
+});
+
+ruleTester.run('use-static-access', useStaticAccess, {
+  valid: [
+    {
+      name: 'non-messages expressions',
+      code: `
+        // All valid because they aren't message identifiers
+        something['WHATEVER'];
+        foo['bar'];
+        t['correct'];
+      `,
+    },
+    {
+      name: 'dot-access message accesses',
+      code: `
+        import messages from 'Feature.messages';
+        messages.SOME_MESSAGE;
+        messages.SOME_MESSAGE['afterward'];
+        parent[messages.SOME_MESSAGE];
+        parent.call(messages.SOME_MESSAGE);
+      `,
+    },
+    {
+      name: 'extra imports',
+      settings: {
+        extraImports: {
+          '@app/intl': ['t'],
+        },
+      },
+      code: `
+        import {t} from '@app/intl';
+        t.SOME_MESSAGE;
+        t.SOME_MESSAGE['afterward'];
+        parent[t.SOME_MESSAGE];
+        parent.call(t.SOME_MESSAGE);
+      `,
+    },
+  ],
+  invalid: [
+    {
+      name: 'computed literal access',
+      code: `
+        import messages from 'Feature.messages';
+        messages['SOME_MESSAGE'];
+      `,
+      output: `
+        import messages from 'Feature.messages';
+        messages.SOME_MESSAGE;
+      `,
+      errors: 1,
+    },
+    {
+      name: 'static template literal access',
+      code: `
+        import messages from 'Feature.messages';
+        messages[\`SOME_MESSAGE\`];
+      `,
+      output: `
+        import messages from 'Feature.messages';
+        messages.SOME_MESSAGE;
+      `,
+      errors: 1,
+    },
+    {
+      name: 'dynamic template literal access',
+      code: `
+        import messages from 'Feature.messages';
+        messages[\`SCOPE_\${name}\`];
+      `,
+      errors: 1,
+    },
+    {
+      name: 'variable access',
+      code: `
+        import messages from 'Feature.messages';
+        messages[someVariable];
+      `,
+      errors: 1,
+    },
+    {
+      name: 'invalid identifier access',
+      code: `
+        import messages from 'Feature.messages';
+        messages['not an identifier'];
+      `,
+      errors: 1,
+    },
+    {
+      name: 'keyword access',
+      code: `
+        import messages from 'Feature.messages';
+        messages['return'];
+      `,
+      errors: 1,
+    },
+  ],
+});
+
+console.log('All tests passed!');