@sgfe/eslint-plugin-sg 1.0.3

package/lib/rules/require-meta-docs-description.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const { getStaticValue } = require('eslint-utils');
+const utils = require('../utils');
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+const DEFAULT_PATTERN = new RegExp('^(enforce|require|disallow)');
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'require rules to implement a `meta.docs.description` property with the correct format',
+      category: 'Rules',
+      recommended: false,
+      url: 'https://github.com/eslint-community/eslint-plugin-eslint-plugin/tree/HEAD/docs/rules/require-meta-docs-description.md',
+    },
+    fixable: null,
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          pattern: {
+            type: 'string',
+            description:
+              "A regular expression that the description must match. Use `'.+'` to allow anything.",
+            default: '^(enforce|require|disallow)',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      extraWhitespace:
+        '`meta.docs.description` must not have leading nor trailing whitespace.',
+      mismatch: '`meta.docs.description` must match the regexp {{pattern}}.',
+      missing: '`meta.docs.description` is required.',
+      wrongType: '`meta.docs.description` must be a non-empty string.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode || context.getSourceCode(); // TODO: just use context.sourceCode when dropping eslint < v9
+    const ruleInfo = utils.getRuleInfo(sourceCode);
+    if (!ruleInfo) {
+      return {};
+    }
+
+    return {
+      Program(ast) {
+        const scope = sourceCode.getScope?.(ast) || context.getScope(); // TODO: just use sourceCode.getScope() when we drop support for ESLint < v9.0.0
+        const { scopeManager } = sourceCode;
+
+        const pattern =
+          context.options[0] && context.options[0].pattern
+            ? new RegExp(context.options[0].pattern)
+            : DEFAULT_PATTERN;
+
+        const metaNode = ruleInfo.meta;
+        const docsNode = utils
+          .evaluateObjectProperties(metaNode, scopeManager)
+          .find((p) => p.type === 'Property' && utils.getKeyName(p) === 'docs');
+
+        const descriptionNode = utils
+          .evaluateObjectProperties(docsNode && docsNode.value, scopeManager)
+          .find(
+            (p) =>
+              p.type === 'Property' && utils.getKeyName(p) === 'description'
+          );
+
+        if (!descriptionNode) {
+          context.report({
+            node: docsNode || metaNode || ruleInfo.create,
+            messageId: 'missing',
+          });
+          return;
+        }
+
+        const staticValue = getStaticValue(descriptionNode.value, scope);
+        if (!staticValue) {
+          // Ignore non-static values since we can't determine what they look like.
+          return;
+        }
+
+        if (typeof staticValue.value !== 'string' || staticValue.value === '') {
+          context.report({
+            node: descriptionNode.value,
+            messageId: 'wrongType',
+          });
+        } else if (staticValue.value !== staticValue.value.trim()) {
+          context.report({
+            node: descriptionNode.value,
+            messageId: 'extraWhitespace',
+          });
+        } else if (!pattern.test(staticValue.value)) {
+          context.report({
+            node: descriptionNode.value,
+            messageId: 'mismatch',
+            data: { pattern },
+          });
+        }
+      },
+    };
+  },
+};

package/lib/rules/require-meta-docs-url.js

@@ -0,0 +1,175 @@
+/**
+ * @author Toru Nagashima <https://github.com/mysticatea>
+ */
+
+'use strict';
+
+// -----------------------------------------------------------------------------
+// Requirements
+// -----------------------------------------------------------------------------
+
+const path = require('path');
+const util = require('../utils');
+const { getStaticValue } = require('eslint-utils');
+
+// -----------------------------------------------------------------------------
+// Rule Definition
+// -----------------------------------------------------------------------------
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'require rules to implement a `meta.docs.url` property',
+      category: 'Rules',
+      recommended: false,
+      url: 'https://github.com/eslint-community/eslint-plugin-eslint-plugin/tree/HEAD/docs/rules/require-meta-docs-url.md',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          pattern: {
+            type: 'string',
+            description:
+              "A pattern to enforce rule's document URL. It replaces `{{name}}` placeholder by each rule name. The rule name is the basename of each rule file. Omitting this allows any URL.",
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      mismatch: '`meta.docs.url` property must be `{{expectedUrl}}`.',
+      missing: '`meta.docs.url` property is missing.',
+      wrongType: '`meta.docs.url` property must be a string.',
+    },
+  },
+
+  /**
+   * Creates AST event handlers for require-meta-docs-url.
+   * @param {RuleContext} context - The rule context.
+   * @returns {Object} AST event handlers.
+   */
+  create(context) {
+    const options = context.options[0] || {};
+    const filename = context.filename || context.getFilename(); // TODO: just use context.filename when dropping eslint < v9
+    const ruleName =
+      filename === '<input>'
+        ? undefined
+        : path.basename(filename, path.extname(filename));
+    const expectedUrl =
+      !options.pattern || !ruleName
+        ? undefined
+        : options.pattern.replaceAll(/{{\s*name\s*}}/g, ruleName);
+
+    /**
+     * Check whether a given URL is the expected URL.
+     * @param {string} url The URL to check.
+     * @returns {boolean} `true` if the node is the expected URL.
+     */
+    function isExpectedUrl(url) {
+      return Boolean(
+        typeof url === 'string' &&
+          (expectedUrl === undefined || url === expectedUrl)
+      );
+    }
+
+    const sourceCode = context.sourceCode || context.getSourceCode(); // TODO: just use context.sourceCode when dropping eslint < v9
+    const ruleInfo = util.getRuleInfo(sourceCode);
+    if (!ruleInfo) {
+      return {};
+    }
+
+    return {
+      Program(ast) {
+        const scope = sourceCode.getScope?.(ast) || context.getScope(); // TODO: just use sourceCode.getScope() when we drop support for ESLint < v9.0.0
+        const { scopeManager } = sourceCode;
+
+        const metaNode = ruleInfo.meta;
+        const docsPropNode = util
+          .evaluateObjectProperties(metaNode, scopeManager)
+          .find((p) => p.type === 'Property' && util.getKeyName(p) === 'docs');
+        const urlPropNode = util
+          .evaluateObjectProperties(
+            docsPropNode && docsPropNode.value,
+            scopeManager
+          )
+          .find((p) => p.type === 'Property' && util.getKeyName(p) === 'url');
+
+        const staticValue = urlPropNode
+          ? getStaticValue(urlPropNode.value, scope)
+          : undefined;
+        if (urlPropNode && !staticValue) {
+          // Ignore non-static values since we can't determine what they look like.
+          return;
+        }
+
+        if (isExpectedUrl(staticValue && staticValue.value)) {
+          return;
+        }
+
+        context.report({
+          node:
+            (urlPropNode && urlPropNode.value) ||
+            (docsPropNode && docsPropNode.value) ||
+            metaNode ||
+            ruleInfo.create,
+
+          // eslint-disable-next-line unicorn/no-negated-condition -- actually more clear like this
+          messageId: !urlPropNode
+            ? 'missing'
+            : // eslint-disable-next-line unicorn/no-nested-ternary,unicorn/no-negated-condition -- this is fine for now
+            !expectedUrl
+            ? 'wrongType'
+            : /* otherwise */ 'mismatch',
+
+          data: {
+            expectedUrl,
+          },
+
+          fix(fixer) {
+            if (!expectedUrl) {
+              return null;
+            }
+
+            const urlString = JSON.stringify(expectedUrl);
+            if (urlPropNode) {
+              if (
+                urlPropNode.value.type === 'Literal' ||
+                (urlPropNode.value.type === 'Identifier' &&
+                  urlPropNode.value.name === 'undefined')
+              ) {
+                return fixer.replaceText(urlPropNode.value, urlString);
+              }
+            } else if (
+              docsPropNode &&
+              docsPropNode.value.type === 'ObjectExpression'
+            ) {
+              return util.insertProperty(
+                fixer,
+                docsPropNode.value,
+                `url: ${urlString}`,
+                sourceCode
+              );
+            } else if (
+              !docsPropNode &&
+              metaNode &&
+              metaNode.type === 'ObjectExpression'
+            ) {
+              return util.insertProperty(
+                fixer,
+                metaNode,
+                `docs: {\nurl: ${urlString}\n}`,
+                sourceCode
+              );
+            }
+
+            return null;
+          },
+        });
+      },
+    };
+  },
+};

package/lib/rules/require-meta-fixable.js

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview require rules to implement a `meta.fixable` property
+ * @author Teddy Katz
+ */
+
+'use strict';
+
+const { getStaticValue } = require('eslint-utils');
+const utils = require('../utils');
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'require rules to implement a `meta.fixable` property',
+      category: 'Rules',
+      recommended: true,
+      url: 'https://github.com/eslint-community/eslint-plugin-eslint-plugin/tree/HEAD/docs/rules/require-meta-fixable.md',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          catchNoFixerButFixableProperty: {
+            type: 'boolean',
+            default: false,
+            description:
+              "Whether the rule should attempt to detect rules that do not have a fixer but enable the `meta.fixable` property. This option is off by default because it increases the chance of false positives since fixers can't always be detected when helper functions are used.",
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      invalid: '`meta.fixable` must be either `code`, `whitespace`, or `null`.',
+      missing:
+        '`meta.fixable` must be either `code` or `whitespace` for fixable rules.',
+      noFixerButFixableValue:
+        '`meta.fixable` is enabled but no fixer detected.',
+    },
+  },
+
+  create(context) {
+    const catchNoFixerButFixableProperty =
+      context.options[0] && context.options[0].catchNoFixerButFixableProperty;
+
+    const sourceCode = context.sourceCode || context.getSourceCode(); // TODO: just use context.sourceCode when dropping eslint < v9
+    const { scopeManager } = sourceCode;
+    const ruleInfo = utils.getRuleInfo(sourceCode);
+    let contextIdentifiers;
+    let usesFixFunctions;
+
+    if (!ruleInfo) {
+      return {};
+    }
+
+    return {
+      Program(ast) {
+        contextIdentifiers = utils.getContextIdentifiers(scopeManager, ast);
+      },
+      CallExpression(node) {
+        if (
+          node.callee.type === 'MemberExpression' &&
+          contextIdentifiers.has(node.callee.object) &&
+          node.callee.property.type === 'Identifier' &&
+          node.callee.property.name === 'report' &&
+          (node.arguments.length > 4 ||
+            (node.arguments.length === 1 &&
+              utils
+                .evaluateObjectProperties(node.arguments[0], scopeManager)
+                .some((prop) => utils.getKeyName(prop) === 'fix')))
+        ) {
+          usesFixFunctions = true;
+        }
+      },
+      'Program:exit'(ast) {
+        const scope = sourceCode.getScope?.(ast) || context.getScope(); // TODO: just use sourceCode.getScope() when we drop support for ESLint < v9.0.0
+        const metaFixableProp =
+          ruleInfo &&
+          utils
+            .evaluateObjectProperties(ruleInfo.meta, scopeManager)
+            .find((prop) => utils.getKeyName(prop) === 'fixable');
+
+        if (metaFixableProp) {
+          const staticValue = getStaticValue(metaFixableProp.value, scope);
+          if (!staticValue) {
+            // Ignore non-static values since we can't determine what they look like.
+            return;
+          }
+
+          if (
+            !['code', 'whitespace', null, undefined].includes(staticValue.value)
+          ) {
+            // `fixable` property has an invalid value.
+            context.report({
+              node: metaFixableProp.value,
+              messageId: 'invalid',
+            });
+            return;
+          }
+
+          if (
+            usesFixFunctions &&
+            !['code', 'whitespace'].includes(staticValue.value)
+          ) {
+            // Rule is fixable but `fixable` property does not have a fixable value.
+            context.report({
+              node: metaFixableProp.value,
+              messageId: 'missing',
+            });
+          } else if (
+            catchNoFixerButFixableProperty &&
+            !usesFixFunctions &&
+            ['code', 'whitespace'].includes(staticValue.value)
+          ) {
+            // Rule is NOT fixable but `fixable` property has a fixable value.
+            context.report({
+              node: metaFixableProp.value,
+              messageId: 'noFixerButFixableValue',
+            });
+          }
+        } else if (!metaFixableProp && usesFixFunctions) {
+          // Rule is fixable but is missing the `fixable` property.
+          context.report({
+            node: ruleInfo.meta || ruleInfo.create,
+            messageId: 'missing',
+          });
+        }
+      },
+    };
+  },
+};

package/lib/rules/require-meta-has-suggestions.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const utils = require('../utils');
+const { getStaticValue } = require('eslint-utils');
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'require suggestable rules to implement a `meta.hasSuggestions` property',
+      category: 'Rules',
+      recommended: true,
+      url: 'https://github.com/eslint-community/eslint-plugin-eslint-plugin/tree/HEAD/docs/rules/require-meta-has-suggestions.md',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      shouldBeSuggestable:
+        '`meta.hasSuggestions` must be `true` for suggestable rules.',
+      shouldNotBeSuggestable:
+        '`meta.hasSuggestions` cannot be `true` for non-suggestable rules.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode || context.getSourceCode(); // TODO: just use context.sourceCode when dropping eslint < v9
+    const { scopeManager } = sourceCode;
+    const ruleInfo = utils.getRuleInfo(sourceCode);
+    if (!ruleInfo) {
+      return {};
+    }
+    let contextIdentifiers;
+    let ruleReportsSuggestions;
+
+    /**
+     * Check if a "suggest" object property from a rule violation report should be considered to contain suggestions.
+     * @param {Node} node - the "suggest" object property to check
+     * @returns {boolean} whether this property should be considered to contain suggestions
+     */
+    function doesPropertyContainSuggestions(node) {
+      const scope = sourceCode.getScope?.(node) || context.getScope(); // TODO: just use sourceCode.getScope() when we drop support for ESLint < v9.0.0
+      const staticValue = getStaticValue(node.value, scope);
+      if (
+        !staticValue ||
+        (Array.isArray(staticValue.value) && staticValue.value.length > 0) ||
+        (Array.isArray(staticValue.value) &&
+          staticValue.value.length === 0 &&
+          node.value.type === 'Identifier') // Array variable can have suggestions pushed to it.
+      ) {
+        // These are all considered reporting suggestions:
+        //   suggest: [{...}]
+        //   suggest: getSuggestions()
+        //   suggest: MY_SUGGESTIONS
+        return true;
+      }
+      return false;
+    }
+
+    return {
+      Program(ast) {
+        contextIdentifiers = utils.getContextIdentifiers(scopeManager, ast);
+      },
+      CallExpression(node) {
+        if (
+          node.callee.type === 'MemberExpression' &&
+          contextIdentifiers.has(node.callee.object) &&
+          node.callee.property.type === 'Identifier' &&
+          node.callee.property.name === 'report' &&
+          (node.arguments.length > 4 ||
+            (node.arguments.length === 1 &&
+              node.arguments[0].type === 'ObjectExpression'))
+        ) {
+          const suggestProp = utils
+            .evaluateObjectProperties(node.arguments[0], scopeManager)
+            .find((prop) => utils.getKeyName(prop) === 'suggest');
+          if (suggestProp && doesPropertyContainSuggestions(suggestProp)) {
+            ruleReportsSuggestions = true;
+          }
+        }
+      },
+      Property(node) {
+        // In order to reduce false positives, we will also check for a `suggest` property anywhere in the file.
+        // This is helpful especially in the event that helper functions are used for reporting violations.
+        if (
+          node.key.type === 'Identifier' &&
+          node.key.name === 'suggest' &&
+          doesPropertyContainSuggestions(node)
+        ) {
+          ruleReportsSuggestions = true;
+        }
+      },
+      'Program:exit'(node) {
+        const scope = sourceCode.getScope?.(node) || context.getScope(); // TODO: just use sourceCode.getScope() when we drop support for ESLint < v9.0.0
+        const metaNode = ruleInfo && ruleInfo.meta;
+        const hasSuggestionsProperty = utils
+          .evaluateObjectProperties(metaNode, scopeManager)
+          .find((prop) => utils.getKeyName(prop) === 'hasSuggestions');
+        const hasSuggestionsStaticValue =
+          hasSuggestionsProperty &&
+          getStaticValue(hasSuggestionsProperty.value, scope);
+
+        if (ruleReportsSuggestions) {
+          if (!hasSuggestionsProperty) {
+            // Rule reports suggestions but is missing the `meta.hasSuggestions` property altogether.
+            context.report({
+              node: metaNode || ruleInfo.create,
+              messageId: 'shouldBeSuggestable',
+              fix(fixer) {
+                if (metaNode && metaNode.type === 'ObjectExpression') {
+                  if (metaNode.properties.length === 0) {
+                    // If object is empty, just replace entire object.
+                    return fixer.replaceText(
+                      metaNode,
+                      '{ hasSuggestions: true }'
+                    );
+                  }
+                  // Add new property to start of property list.
+                  return fixer.insertTextBefore(
+                    metaNode.properties[0],
+                    'hasSuggestions: true, '
+                  );
+                }
+              },
+            });
+          } else if (
+            hasSuggestionsStaticValue &&
+            hasSuggestionsStaticValue.value !== true
+          ) {
+            // Rule reports suggestions but does not have `meta.hasSuggestions` property enabled.
+            context.report({
+              node: hasSuggestionsProperty.value,
+              messageId: 'shouldBeSuggestable',
+              fix(fixer) {
+                if (
+                  hasSuggestionsProperty.value.type === 'Literal' ||
+                  (hasSuggestionsProperty.value.type === 'Identifier' &&
+                    hasSuggestionsProperty.value.name === 'undefined')
+                ) {
+                  return fixer.replaceText(
+                    hasSuggestionsProperty.value,
+                    'true'
+                  );
+                }
+              },
+            });
+          }
+        } else if (
+          !ruleReportsSuggestions &&
+          hasSuggestionsProperty &&
+          hasSuggestionsStaticValue &&
+          hasSuggestionsStaticValue.value === true
+        ) {
+          // Rule does not report suggestions but has the `meta.hasSuggestions` property enabled.
+          context.report({
+            node: hasSuggestionsProperty.value,
+            messageId: 'shouldNotBeSuggestable',
+          });
+        }
+      },
+    };
+  },
+};