@docusaurus/eslint-plugin 0.0.0-4925

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Facebook, Inc. and its affiliates.
+
+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,7 @@
+# `@docusaurus/eslint-plugin`
+
+ESLint plugin to enforce best Docusaurus practices.
+
+## Usage
+
+See [eslint-plugin documentation](https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin).

package/lib/index.js

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const requireIndex = require('requireindex');
+
+module.exports = {
+  rules: requireIndex(`${__dirname}/rules`),
+  configs: {
+    recommended: {
+      rules: {
+        '@docusaurus/string-literal-i18n-messages': 'error',
+      },
+    },
+    all: {
+      rules: {
+        '@docusaurus/string-literal-i18n-messages': 'error',
+        '@docusaurus/no-untranslated-text': 'warn',
+      },
+    },
+  },
+};

package/lib/rules/no-untranslated-text.js

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const {isTextLabelChild, report} = require('../util');
+
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'enforce text labels in JSX to be wrapped by translate calls',
+      category: 'Suggestions',
+      url: 'https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin/no-untranslated-text',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          ignoreStrings: {
+            type: 'array',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      translateChildren:
+        'All text labels in JSX should be wrapped by translate calls',
+    },
+  },
+
+  create(context) {
+    const stringsToIgnore = context.options[0]?.ignoreStrings ?? [];
+
+    const isParentTranslate = ({child, isParentFragment}) =>
+      !isParentFragment &&
+      child.parent.openingElement.name.name === 'Translate';
+
+    const isChildValid = ({child, isParentFragment}) => {
+      if (!isTextLabelChild({child, ignoreWhitespace: true, stringsToIgnore})) {
+        return true;
+      }
+      return isParentTranslate({child, isParentFragment});
+    };
+
+    const isNodeValid = ({node, isFragment = false} = {}) =>
+      node.children.every((child) =>
+        isChildValid({child, isParentFragment: isFragment}),
+      );
+
+    return {
+      'JSXElement[openingElement.selfClosing=false]': (node) => {
+        if (!isNodeValid({node})) {
+          report(context, node, 'translateChildren');
+        }
+      },
+      'JSXFragment[openingFragment]': (node) => {
+        if (!isNodeValid({node, isFragment: true})) {
+          report(context, node, 'translateChildren');
+        }
+      },
+    };
+  },
+};

package/lib/rules/string-literal-i18n-messages.js

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const {
+  isTextLabelChild,
+  report,
+  isStringWithoutExpressions,
+} = require('../util');
+
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'enforce translate APIs to be called on plain text labels',
+      category: 'Possible Problems',
+      url: 'https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin/string-literal-i18n-messages',
+    },
+    schema: [],
+    messages: {
+      translateChildren:
+        '<Translate> children must be hardcoded strings. You can have in-string dynamic placeholders using the values prop.',
+      translateArg:
+        'translation message must be a hardcoded string. You can have in-string dynamic placeholders using the values argument.',
+    },
+  },
+
+  create(context) {
+    const isNodeValid = (node) =>
+      node.children.every((child) => isTextLabelChild({child}));
+
+    return {
+      "JSXElement[openingElement.name.name='Translate']": (node) => {
+        if (!isNodeValid(node)) {
+          report(context, node, 'translateChildren');
+        }
+      },
+      "CallExpression > Identifier[name='translate']": (node) => {
+        const messageProperty = node.parent.arguments[0].properties.find(
+          (property) => property.key.name === 'message',
+        );
+        if (!messageProperty) {
+          return;
+        }
+
+        if (
+          !isStringWithoutExpressions({
+            text: messageProperty.value,
+          })
+        ) {
+          report(context, node, 'translateArg');
+        }
+      },
+    };
+  },
+};

package/lib/util.js

@@ -0,0 +1,145 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const isMadeOfIgnoredStrings = ({text, stringsToIgnore}) =>
+  text
+    .trim()
+    .split(/\s+/)
+    .every((string) => stringsToIgnore.includes(string));
+
+const isWhitespace = (text) => !text || !text.trim();
+
+const isTextValid = ({text, ignoreWhitespace, stringsToIgnore}) =>
+  !!text &&
+  !(ignoreWhitespace && isWhitespace(text)) &&
+  !isMadeOfIgnoredStrings({
+    text,
+    stringsToIgnore,
+  });
+
+const isStringWithoutExpressions = ({
+  text,
+  ignoreWhitespace = false,
+  stringsToIgnore = [],
+} = {}) => {
+  switch (text.type) {
+    case 'Literal':
+      return isTextValid({text: text.value, ignoreWhitespace, stringsToIgnore});
+    case 'TemplateLiteral':
+      return (
+        !text.expressions.length &&
+        isTextValid({
+          text: text.quasis[0].value.raw,
+          ignoreWhitespace,
+          stringsToIgnore,
+        })
+      );
+    default:
+      return false;
+  }
+};
+
+const isTextLabelChild = ({
+  child,
+  ignoreWhitespace = false,
+  stringsToIgnore = [],
+} = {}) => {
+  switch (child.type) {
+    case 'JSXText':
+      return isTextValid({
+        text: child.value,
+        ignoreWhitespace,
+        stringsToIgnore,
+      });
+    case 'JSXExpressionContainer':
+      return isStringWithoutExpressions({
+        text: child.expression,
+        ignoreWhitespace,
+        stringsToIgnore,
+      });
+    default:
+      return false;
+  }
+};
+
+const report = (context, node, messageId) => {
+  context.report({
+    node,
+    messageId,
+  });
+};
+
+const getCommonValidTests = () => [
+  {
+    code: '<Translate>text</Translate>',
+  },
+  {
+    code: '<Translate> text </Translate>',
+  },
+  {
+    code: '<Translate>"text"</Translate>',
+  },
+  {
+    code: "<Translate>'text'</Translate>",
+  },
+  {
+    code: '<Translate>`text`</Translate>',
+  },
+  {
+    code: '<Translate>{"text"}</Translate>',
+  },
+  {
+    code: "<Translate>{'text'}</Translate>",
+  },
+  {
+    code: '<Translate>{`text`}</Translate>',
+  },
+  {
+    code: '<Component>{text}</Component>',
+  },
+  {
+    code: '<Component> {text} </Component>',
+  },
+  {
+    code: 'translate({message: `My page meta title`})',
+  },
+  {
+    code: `<Translate
+              id="homepage.title"
+              description="The homepage welcome message">
+                Welcome to my website
+            </Translate>`,
+  },
+  {
+    code: `<Translate
+              values={{firstName: 'Sébastien'}}>
+                {'Welcome, {firstName}! How are you?'}
+            </Translate>`,
+  },
+  {
+    code: `<Translate>{'This'} is {\`valid\`}</Translate>`,
+  },
+  {
+    code: "translate({message: 'My page meta title'})",
+  },
+  {
+    code: "translate({message: 'The logo of site {siteName}'}, {siteName: 'Docusaurus'})",
+  },
+  {
+    code: 'translate({otherProp: metaTitle})',
+  },
+  {
+    code: 'translate({otherProp: `My page meta title`})',
+  },
+];
+
+module.exports = {
+  isTextLabelChild,
+  report,
+  getCommonValidTests,
+  isStringWithoutExpressions,
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@docusaurus/eslint-plugin",
+  "version": "0.0.0-4925",
+  "description": "ESLint plugin to enforce best Docusaurus practices.",
+  "main": "lib/index.js",
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/docusaurus.git",
+    "directory": "packages/eslint-plugin"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "requireindex": "^1.2.0"
+  },
+  "devDependencies": {
+    "eslint-plugin-eslint-plugin": "^4.1.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=6"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "gitHead": "bfcd4b0c2f1149c0a9809cd37b45ee8cccb2c4c2"
+}