feat: add eslint plugin no-html-links (#8156)

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: Viktor Malmedal <viktor.malmedal@eniro.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>

packages/eslint-plugin/src/index.ts

@@ -14,6 +14,7 @@ export = {
       plugins: ['@docusaurus'],
       rules: {
         '@docusaurus/string-literal-i18n-messages': 'error',
+        '@docusaurus/no-html-links': 'warn',
       },
     },
     all: {
@@ -21,6 +22,7 @@ export = {
       rules: {
         '@docusaurus/string-literal-i18n-messages': 'error',
         '@docusaurus/no-untranslated-text': 'warn',
+        '@docusaurus/no-html-links': 'warn',
       },
     },
   },

packages/eslint-plugin/src/rules/__tests__/no-html-links.test.ts

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ */
+
+import rule from '../no-html-links';
+import {RuleTester} from './testUtils';
+
+const errorsJSX = [{messageId: 'link'}] as const;
+
+const ruleTester = new RuleTester({
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+});
+
+ruleTester.run('prefer-docusaurus-link', rule, {
+  valid: [
+    {
+      code: '<Link to="/test">test</Link>',
+    },
+    {
+      code: '<Link to="https://twitter.com/docusaurus">Twitter</Link>',
+    },
+    {
+      code: '<a href="https://twitter.com/docusaurus">Twitter</a>',
+      options: [{ignoreFullyResolved: true}],
+    },
+    {
+      code: '<a href={`https://twitter.com/docusaurus`}>Twitter</a>',
+      options: [{ignoreFullyResolved: true}],
+    },
+    {
+      code: '<a href="mailto:viktor@malmedal.dev">Contact</a>  ',
+      options: [{ignoreFullyResolved: true}],
+    },
+    {
+      code: '<a href="tel:123456789">Call</a>',
+      options: [{ignoreFullyResolved: true}],
+    },
+  ],
+  invalid: [
+    {
+      code: '<a href="/test">test</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href="https://twitter.com/docusaurus" target="_blank">test</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href="https://twitter.com/docusaurus" target="_blank" rel="noopener noreferrer">test</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href="mailto:viktor@malmedal.dev">Contact</a>  ',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href="tel:123456789">Call</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href={``}>Twitter</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href={`https://www.twitter.com/docusaurus`}>Twitter</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href="www.twitter.com/docusaurus">Twitter</a>',
+      options: [{ignoreFullyResolved: true}],
+      errors: errorsJSX,
+    },
+    {
+      // TODO we might want to make this test pass
+      // Can template literals be statically pre-evaluated? (Babel can do it)
+      // eslint-disable-next-line no-template-curly-in-string
+      code: '<a href={`https://twitter.com/${"docu" + "saurus"} ${"rex"}`}>Twitter</a>',
+      options: [{ignoreFullyResolved: true}],
+      errors: errorsJSX,
+    },
+  ],
+});

packages/eslint-plugin/src/rules/index.ts

@@ -5,10 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import noHtmlLinks from './no-html-links';
 import noUntranslatedText from './no-untranslated-text';
 import stringLiteralI18nMessages from './string-literal-i18n-messages';
 
 export default {
   'no-untranslated-text': noUntranslatedText,
   'string-literal-i18n-messages': stringLiteralI18nMessages,
+  'no-html-links': noHtmlLinks,
 };

packages/eslint-plugin/src/rules/no-html-links.ts

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ */
+
+import {createRule} from '../util';
+import type {TSESTree} from '@typescript-eslint/types/dist/ts-estree';
+
+const docsUrl = 'https://docusaurus.io/docs/docusaurus-core#link';
+
+type Options = [
+  {
+    ignoreFullyResolved: boolean;
+  },
+];
+
+type MessageIds = 'link';
+
+function isFullyResolvedUrl(urlString: string): boolean {
+  try {
+    // href gets coerced to a string when it gets rendered anyway
+    const url = new URL(String(urlString));
+    if (url.protocol) {
+      return true;
+    }
+  } catch (e) {}
+  return false;
+}
+
+export default createRule<Options, MessageIds>({
+  name: 'no-html-links',
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'enforce using Docusaurus Link component instead of <a> tag',
+      recommended: false,
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          ignoreFullyResolved: {
+            type: 'boolean',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      link: `Do not use an \`<a>\` element to navigate. Use the \`<Link />\` component from \`@docusaurus/Link\` instead. See: ${docsUrl}`,
+    },
+  },
+  defaultOptions: [
+    {
+      ignoreFullyResolved: false,
+    },
+  ],
+
+  create(context, [options]) {
+    const {ignoreFullyResolved} = options;
+
+    return {
+      JSXOpeningElement(node) {
+        if ((node.name as TSESTree.JSXIdentifier).name !== 'a') {
+          return;
+        }
+
+        if (ignoreFullyResolved) {
+          const hrefAttr = node.attributes.find(
+            (attr): attr is TSESTree.JSXAttribute =>
+              attr.type === 'JSXAttribute' && attr.name.name === 'href',
+          );
+
+          if (hrefAttr?.value?.type === 'Literal') {
+            if (isFullyResolvedUrl(String(hrefAttr.value.value))) {
+              return;
+            }
+          }
+          if (hrefAttr?.value?.type === 'JSXExpressionContainer') {
+            const container: TSESTree.JSXExpressionContainer = hrefAttr.value;
+            const {expression} = container;
+            if (expression.type === 'TemplateLiteral') {
+              // Simple static string template literals
+              if (
+                expression.expressions.length === 0 &&
+                expression.quasis.length === 1 &&
+                expression.quasis[0]?.type === 'TemplateElement' &&
+                isFullyResolvedUrl(String(expression.quasis[0].value.raw))
+              ) {
+                return;
+              }
+              // TODO add more complex TemplateLiteral cases here
+            }
+          }
+        }
+
+        context.report({node, messageId: 'link'});
+      },
+    };
+  },
+});