@docusaurus/eslint-plugin 2.4.1 → 3.0.0-beta.0

package/lib/index.d.ts

@@ -10,12 +10,18 @@ declare const _default: {
             ignoredStrings: string[];
         }], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
         'string-literal-i18n-messages': import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"translateChildren" | "translateArg", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+        'no-html-links': import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"link", [{
+            ignoreFullyResolved: boolean;
+        }], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+        'prefer-docusaurus-heading': import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"headings", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
     };
     configs: {
         recommended: {
             plugins: string[];
             rules: {
                 '@docusaurus/string-literal-i18n-messages': string;
+                '@docusaurus/no-html-links': string;
+                '@docusaurus/prefer-docusaurus-heading': string;
             };
         };
         all: {
@@ -23,6 +29,8 @@ declare const _default: {
             rules: {
                 '@docusaurus/string-literal-i18n-messages': string;
                 '@docusaurus/no-untranslated-text': string;
+                '@docusaurus/no-html-links': string;
+                '@docusaurus/prefer-docusaurus-heading': string;
             };
         };
     };

package/lib/index.js

@@ -14,6 +14,8 @@ module.exports = {
             plugins: ['@docusaurus'],
             rules: {
                 '@docusaurus/string-literal-i18n-messages': 'error',
+                '@docusaurus/no-html-links': 'warn',
+                '@docusaurus/prefer-docusaurus-heading': 'warn',
             },
         },
         all: {
@@ -21,6 +23,8 @@ module.exports = {
             rules: {
                 '@docusaurus/string-literal-i18n-messages': 'error',
                 '@docusaurus/no-untranslated-text': 'warn',
+                '@docusaurus/no-html-links': 'warn',
+                '@docusaurus/prefer-docusaurus-heading': 'warn',
             },
         },
     },

package/lib/rules/index.d.ts

@@ -9,5 +9,9 @@ declare const _default: {
         ignoredStrings: string[];
     }], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
     'string-literal-i18n-messages': import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"translateChildren" | "translateArg", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+    'no-html-links': import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"link", [{
+        ignoreFullyResolved: boolean;
+    }], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+    'prefer-docusaurus-heading': import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"headings", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
 };
 export default _default;

package/lib/rules/index.js

@@ -7,9 +7,13 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
+const no_html_links_1 = tslib_1.__importDefault(require("./no-html-links"));
+const prefer_docusaurus_heading_1 = tslib_1.__importDefault(require("./prefer-docusaurus-heading"));
 const no_untranslated_text_1 = tslib_1.__importDefault(require("./no-untranslated-text"));
 const string_literal_i18n_messages_1 = tslib_1.__importDefault(require("./string-literal-i18n-messages"));
 exports.default = {
     'no-untranslated-text': no_untranslated_text_1.default,
     'string-literal-i18n-messages': string_literal_i18n_messages_1.default,
+    'no-html-links': no_html_links_1.default,
+    'prefer-docusaurus-heading': prefer_docusaurus_heading_1.default,
 };

package/lib/rules/no-html-links.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+type Options = [
+    {
+        ignoreFullyResolved: boolean;
+    }
+];
+declare const _default: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"link", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export default _default;

package/lib/rules/no-html-links.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const util_1 = require("../util");
+const docsUrl = 'https://docusaurus.io/docs/docusaurus-core#link';
+function isFullyResolvedUrl(urlString) {
+    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;
+}
+exports.default = (0, util_1.createRule)({
+    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.name !== 'a') {
+                    return;
+                }
+                if (ignoreFullyResolved) {
+                    const hrefAttr = node.attributes.find((attr) => 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 = 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' });
+            },
+        };
+    },
+});

package/lib/rules/no-untranslated-text.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-declare type Options = [
+type Options = [
     {
         ignoredStrings: string[];
     }

package/lib/rules/prefer-docusaurus-heading.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+declare const _default: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"headings", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export default _default;

package/lib/rules/prefer-docusaurus-heading.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const util_1 = require("../util");
+exports.default = (0, util_1.createRule)({
+    name: 'prefer-docusaurus-heading',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'enforce using Docusaurus theme Heading component instead of any <hn> tag',
+            recommended: false,
+        },
+        schema: [],
+        messages: {
+            headings: 'Do not use any of the `<hn>` tags for headings. Use the `<Heading />` component from `@theme/Heading` instead.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const headingTypes = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
+        return {
+            JSXOpeningElement(node) {
+                const elementName = node.name.name;
+                if (!headingTypes.includes(elementName)) {
+                    return;
+                }
+                context.report({ node, messageId: 'headings' });
+            },
+        };
+    },
+});

package/lib/rules/string-literal-i18n-messages.d.ts

@@ -4,6 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-declare type MessageIds = 'translateChildren' | 'translateArg';
+type MessageIds = 'translateChildren' | 'translateArg';
 declare const _default: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<MessageIds, [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
 export default _default;

package/lib/util.d.ts

@@ -6,7 +6,7 @@
  */
 import { ESLintUtils } from '@typescript-eslint/utils';
 import type { TSESTree } from '@typescript-eslint/types/dist/ts-estree';
-declare type CheckTranslateChildOptions = {
+type CheckTranslateChildOptions = {
     ignoredStrings?: string[];
 };
 export declare function isStringWithoutExpressions(text: TSESTree.Node, options?: CheckTranslateChildOptions): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/eslint-plugin",
-  "version": "2.4.1",
+  "version": "3.0.0-beta.0",
   "description": "ESLint plugin to enforce best Docusaurus practices.",
   "main": "lib/index.js",
   "keywords": [
@@ -21,11 +21,11 @@
     "build": "tsc"
   },
   "dependencies": {
-    "@typescript-eslint/utils": "^5.30.5",
-    "tslib": "^2.4.0"
+    "@typescript-eslint/utils": "^5.62.0",
+    "tslib": "^2.6.0"
   },
   "devDependencies": {
-    "eslint-plugin-eslint-plugin": "^4.4.0"
+    "eslint-plugin-eslint-plugin": "^5.1.0"
   },
   "peerDependencies": {
     "eslint": ">=6"
@@ -33,5 +33,5 @@
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "60e657d8ae5a4a9ed1c2d777f9defd882cc12681"
+  "gitHead": "27a1e90d9fff88af90ecad35bea16d4d7230482a"
 }

package/src/index.ts

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

package/src/rules/index.ts

@@ -5,10 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import noHtmlLinks from './no-html-links';
+import preferDocusaurusHeading from './prefer-docusaurus-heading';
 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,
+  'prefer-docusaurus-heading': preferDocusaurusHeading,
 };

package/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'});
+      },
+    };
+  },
+});

package/src/rules/prefer-docusaurus-heading.ts

@@ -0,0 +1,46 @@
+/**
+ * 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';
+
+type Options = [];
+type MessageIds = 'headings';
+
+export default createRule<Options, MessageIds>({
+  name: 'prefer-docusaurus-heading',
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'enforce using Docusaurus theme Heading component instead of any <hn> tag',
+      recommended: false,
+    },
+    schema: [],
+    messages: {
+      headings:
+        'Do not use any of the `<hn>` tags for headings. Use the `<Heading />` component from `@theme/Heading` instead.',
+    },
+  },
+  defaultOptions: [],
+
+  create(context) {
+    const headingTypes = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
+
+    return {
+      JSXOpeningElement(node) {
+        const elementName = (node.name as TSESTree.JSXIdentifier).name;
+
+        if (!headingTypes.includes(elementName)) {
+          return;
+        }
+
+        context.report({node, messageId: 'headings'});
+      },
+    };
+  },
+});