@discord/eslint-plugin-discord-intl 0.6.0 → 0.6.2

package/index.js

@@ -1,7 +1,8 @@
 module.exports = {
   rules: {
-    'trimmed-whitespace': require('./rules/trimmable-whitespace'),
+    'trimmed-whitespace': require('./rules/trimmed-whitespace'),
     'use-static-access': require('./rules/use-static-access'),
+    'no-opaque-messages-objects': require('./rules/no-opaque-messages-objects'),
   },
   configs: {
     recommended: {
@@ -9,6 +10,7 @@ module.exports = {
       rules: {
         '@discord/discord-intl/trimmed-whitespace': 'error',
         '@discord/discord-intl/use-static-access': 'error',
+        '@discord/discord-intl/no-opaque-messages-objects': 'error',
       },
     },
   },

package/lib/is-typescript.js

@@ -0,0 +1,11 @@
+/**
+ * Returns true if the current execution is using a TypeScript parser, using a best-effort guess
+ * based on the given context.
+ * @param {import('eslint').Rule.RuleContext} context
+ * @returns {boolean}
+ */
+function isTypeScript(context) {
+  return context.parserPath?.includes('@typescript-eslint') ?? false;
+}
+
+module.exports = { isTypeScript };

package/lib/traverse.js

@@ -1,18 +1,80 @@
 const { isMessageDefinitionsFile } = require('@discord/intl-loader-core');
 
+/** @typedef {import('eslint').Rule.NodeParentExtension} NodeParentExtension */
+/** @typedef {import('eslint').SourceCode} SourceCode */
+/** @typedef {import('eslint').Scope.ScopeManager} ScopeManager */
+/** @typedef {import('eslint').Scope.Reference} Reference */
 /** @typedef {import('eslint').Rule.RuleListener} RuleListener */
 /** @typedef {import('eslint').Rule.RuleContext} RuleContext */
+/** @typedef {import('estree').Node} Node */
 /** @typedef {import('estree').MemberExpression} MemberExpression */
+/** @typedef {import('estree').ImportDeclaration} ImportDeclaration */
+/** @typedef {import('estree').ImportSpecifier} ImportSpecifier */
+/** @typedef {import('estree').ImportDefaultSpecifier} ImportDefaultSpecifier */
+/** @typedef {import('estree').ImportNamespaceSpecifier} ImportNamespaceSpecifier */
 /** @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 {import('estree').Identifier} Identifier */
 
 /**
- * @typedef {(node: MemberExpression, importer: BaseModuleSpecifier) => void} MessageAccessCallback
+ * @typedef DiscordIntlPluginConfig
+ * @property {Record<string, string[]>} [extraImports]
+ */
+
+/**
+ * @param {DiscordIntlPluginConfig | undefined} config
+ * @param {ImportDeclaration} path
+ * @returns {Array<ImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier>}
+ */
+function getImportedMessagesObjectSpecifiers(config, 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 [];
+  }
+
+  return path.specifiers.filter(
+    (specifier) =>
+      (isDefinition && specifier.type === 'ImportDefaultSpecifier') ||
+      extraImportSpecifiers.includes(specifier.local.name),
+  );
+}
+
+/**
+ *
+ * @param {RuleContext} context
+ * @param {Node} node
+ * @returns {Reference[]}
+ */
+function getBindingReferences(context, node) {
+  return (
+    context.sourceCode
+      .getDeclaredVariables(node)
+      // 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) => /** @type {Reference[]} */ (variable.references))
+  );
+}
+
+/**
+ * @typedef {(
+ *  node: MemberExpression & NodeParentExtension,
+ *  importer: BaseModuleSpecifier & NodeParentExtension
+ * ) => void} MessageAccessCallback
+ * @typedef {(
+ *  reference: Identifier & NodeParentExtension,
+ *  importer: BaseModuleSpecifier & NodeParentExtension
+ * ) => void} MessagesReferenceCallback
  * @typedef {(
- *  property: Property,
+ *  property: Property & NodeParentExtension,
  *  value: SimpleLiteral | TemplateLiteral,
  *  definition: ObjectExpression | undefined,
  * ) => void} MessageDefinitionCallback
@@ -30,44 +92,26 @@ const { isMessageDefinitionsFile } = require('@discord/intl-loader-core');
  */
 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),
-      );
+      const specifiers = getImportedMessagesObjectSpecifiers(config, path);
+      if (specifiers.length === 0) return;
 
       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);
+        const bindingReferences = getBindingReferences(context, specifier);
 
         for (const reference of bindingReferences) {
-          // @ts-expect-error `identifier` is actually `Identifier & NodeParentExtension`.
-          const parent = reference.identifier.parent;
+          const parent = /** @type {MemberExpression & NodeParentExtension} */ (
+            // @ts-expect-error `identifier` is actually `Identifier & NodeParentExtension`.
+            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);
+          callback(parent, /** @type {BaseModuleSpecifier & NodeParentExtension} */ (specifier));
         }
       }
     },
@@ -113,13 +157,12 @@ function traverseMessageDefinitions(context, callback) {
           case 'Literal':
           case 'TemplateLiteral':
             callback(
-              property,
+              /** @type {Property & NodeParentExtension} */ (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';
             });
@@ -132,7 +175,7 @@ function traverseMessageDefinitions(context, callback) {
             }
 
             callback(
-              property,
+              /** @type {Property & NodeParentExtension} */ (property),
               /** @type {SimpleLiteral} */ (messageProperty.value),
               property.value,
             );
@@ -143,4 +186,37 @@ function traverseMessageDefinitions(context, callback) {
   });
 }
 
-module.exports = { traverseMessageAccesses, traverseMessageDefinitions };
+/**
+ * Visit all `Identifier`s that act as accesses to a complete intl messages object. This includes
+ * all references, including message accesses, object passing, and includes the original import
+ * for completeness.
+ *
+ * @param {RuleContext} context The rule context from ESLint
+ * @param {MessagesReferenceCallback} callback Function to call for each instance of a message access
+ * @returns {RuleListener} A visitor object for the Babel transform.
+ */
+function traverseMessageObjectReferences(context, callback) {
+  const config = context.settings['@discord/discord-intl'];
+
+  return /** @type {RuleListener} */ ({
+    ImportDeclaration(path) {
+      const specifiers = getImportedMessagesObjectSpecifiers(config, path);
+      for (const specifier of specifiers) {
+        const bindingReferences = getBindingReferences(context, specifier);
+
+        for (const reference of bindingReferences) {
+          callback(
+            /** @type {Identifier & NodeParentExtension} */ (reference.identifier),
+            /** @type {BaseModuleSpecifier & NodeParentExtension} */ (specifier),
+          );
+        }
+      }
+    },
+  });
+}
+
+module.exports = {
+  traverseMessageAccesses,
+  traverseMessageDefinitions,
+  traverseMessageObjectReferences,
+};

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@discord/eslint-plugin-discord-intl",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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.6.0"
+    "@typescript-eslint/scope-manager": "^8.8.1",
+    "@discord/intl-loader-core": "0.6.2"
   },
   "devDependencies": {
     "@types/eslint": "^8.56.12",
     "@types/estree": "^1.0.6",
+    "@typescript-eslint/parser": "^8.8.1",
     "eslint": "8.57.1"
   }
 }

package/rules/no-opaque-messages-objects.js

@@ -0,0 +1,48 @@
+const { traverseMessageObjectReferences } = require('../lib/traverse');
+const { isTypeScript } = require('../lib/is-typescript');
+
+module.exports = /** @type {import('eslint').Rule.RuleModule} */ ({
+  meta: {
+    docs: {
+      description:
+        'Disallow using whole messages objects as singular values, through passing as arguments to functions, taking the type of the object, and more.',
+      category: 'Best Practices',
+    },
+    messages: {
+      noObjectArgument:
+        'Avoid passing message objects around as parameters. Use messages individually',
+      noTypeof:
+        'Avoid requesting the type of an entire messages object. Use messages individually.',
+    },
+  },
+  create(context) {
+    return traverseMessageObjectReferences(context, (reference) => {
+      const parent = reference.parent;
+      if (parent.type === 'CallExpression') {
+        context.report({
+          node: reference,
+          messageId: 'noObjectArgument',
+        });
+        return;
+      }
+
+      if (parent.type === 'UnaryExpression' && parent.operator === 'typeof') {
+        context.report({
+          node: parent,
+          messageId: 'noTypeof',
+        });
+        return;
+      }
+
+      if (isTypeScript(context)) {
+        // @ts-expect-error TSNodes
+        if (parent.type === 'TSTypeQuery') {
+          context.report({
+            node: parent,
+            messageId: 'noTypeof',
+          });
+        }
+      }
+    });
+  },
+});

package/rules/no-opaque-messages-objects.test.js

@@ -0,0 +1,92 @@
+// enforce-foo-bar.test.js
+const { RuleTester } = require('eslint');
+const noOpaqueMessagesObjects = require('./no-opaque-messages-objects');
+
+const typescriptParser = require.resolve('@typescript-eslint/parser');
+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('no-opaque-messages-objects', noOpaqueMessagesObjects, {
+  valid: [
+    {
+      name: 'normal message formatting',
+      code: `
+      import messages from 'Feature.messages';
+      intl.format(messages.SOME_MESSAGE);
+      otherFunction(messages.OTHER_MESSAGE);
+      `,
+    },
+    {
+      name: 'intermediate object passing',
+      code: `
+      import messages from 'Feature.messages';
+      otherFunction({
+        FIRST: messages.FIRST,
+        OTHER_MESSAGE: messages.OTHER_MESSAGE,
+      });
+      `,
+    },
+    {
+      name: 'typeof individual message',
+      parser: typescriptParser,
+      code: `
+      import messages from 'Feature.messages';
+      typeof messages.FOO;
+      function foo(message: typeof messages.FOO) {}
+      `,
+    },
+  ],
+  invalid: [
+    {
+      name: 'passing whole object',
+      code: `
+      import messages from 'Feature.messages';
+      otherFunction(messages);
+      `,
+      errors: 1,
+    },
+    {
+      name: 'passing whole object',
+      settings: {
+        '@discord/discord-intl': {
+          extraImports: { '@app/intl': ['t'] },
+        },
+      },
+      code: `
+      import {t} from '@app/intl';
+      otherFunction(t);
+      `,
+      errors: 1,
+    },
+    {
+      name: 'passing whole object',
+      code: `
+      import messages from 'Feature.messages';
+      otherFunction(messages);
+      `,
+      errors: 1,
+    },
+    {
+      name: 'typeof messages value',
+      code: `
+      import messages from 'Feature.messages';
+      typeof messages;
+      `,
+      errors: 1,
+    },
+    {
+      name: 'typeof messages as parameter',
+      parser: typescriptParser,
+      code: `
+      import messages from 'Feature.messages';
+      function foo(strings: typeof messages) {}
+      `,
+      errors: 1,
+    },
+  ],
+});
+
+console.log('All tests passed!');

package/rules/{trimmable-whitespace.js → trimmed-whitespace.js}

@@ -1,4 +1,3 @@
-const util = require('node:util');
 const { traverseMessageDefinitions } = require('../lib/traverse');
 
 /**
@@ -35,8 +34,6 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ({
       const rawNoQuotes = sourceText.slice(1, -1);
 
       const trimmed = trimLeadingWhitespace(trimTrailingWhitespace(rawNoQuotes));
-      util.inspect(rawNoQuotes);
-      util.inspect(trimmed);
       if (trimmed === rawNoQuotes) return;
 
       context.report({

package/rules/{trimmable-whitespace.test.js → trimmed-whitespace.test.js}

@@ -1,6 +1,6 @@
 // enforce-foo-bar.test.js
 const { RuleTester } = require('eslint');
-const trimmableWhitespace = require('./trimmable-whitespace');
+const trimmedWhitespace = require('./trimmed-whitespace');
 
 const ruleTester = new RuleTester({
   // Must use at least ecmaVersion 2015 because
@@ -19,22 +19,22 @@ function defineMessages(messages) {
   `;
 }
 
-ruleTester.run('trimmable-whitespace', trimmableWhitespace, {
+ruleTester.run('trimmed-whitespace', trimmedWhitespace, {
   valid: [
     {
       name: 'normal strings',
-      code: defineMessages("{ A: 'no trimmable whitespace' }"),
+      code: defineMessages("{ A: 'no trimmed whitespace' }"),
     },
     {
       name: 'templates',
       code: defineMessages(
-        '{ A: `no trimmable whitespace`, QUASI: `${  space  }`, MULTILINE: `hi\n  yes` }',
+        '{ A: `no trimmed whitespace`, QUASI: `${  space  }`, MULTILINE: `hi\n  yes` }',
       ),
     },
     {
       name: 'multi-line',
       code: defineMessages(
-        `{ A: \`no trimmable
+        `{ A: \`no trimmed
         whitespace\`}`,
       ),
     },
@@ -107,14 +107,14 @@ ruleTester.run('trimmable-whitespace', trimmableWhitespace, {
     },
     {
       name: 'template quasis',
-      code: defineMessages('{ A: `no trimmable whitespace`, QUASI: ` ${  space  } ` }'),
-      output: defineMessages('{ A: `no trimmable whitespace`, QUASI: `${  space  }` }'),
+      code: defineMessages('{ A: `no trimmed whitespace`, QUASI: ` ${  space  } ` }'),
+      output: defineMessages('{ A: `no trimmed 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  }` }'),
+      code: defineMessages('{ A: `no trimmed whitespace`, QUASI: `\n\t${  space  }\n  ` }'),
+      output: defineMessages('{ A: `no trimmed whitespace`, QUASI: `${  space  }` }'),
       errors: 1,
     },
     {