@definitelytyped/eslint-plugin 0.0.166-next.4

package/src/configs/all.ts

@@ -0,0 +1,151 @@
+import { rules } from "../rules/index.js";
+import { Linter } from "eslint";
+
+export const all: Linter.BaseConfig = {
+  plugins: ["@definitelytyped", "@typescript-eslint", "jsdoc"],
+  settings: {
+    jsdoc: {
+      tagNamePreference: {
+        argument: "argument",
+        exception: "exception",
+        function: "function",
+        method: "method",
+        param: "param",
+        return: "return",
+        returns: "returns",
+      },
+    },
+  },
+  rules: {
+    "jsdoc/check-tag-names": [
+      "error",
+      {
+        // TODO: Some (but not all) of these tags should likely be removed from this list.
+        // Additionally, some may need to be contributed to eslint-plugin-jsdoc.
+        definedTags: [
+          "addVersion",
+          "also",
+          "api",
+          "author",
+          "beta",
+          "brief",
+          "category",
+          "cfg",
+          "chainable",
+          "check",
+          "checkReturnValue",
+          "classDescription",
+          "condparamprivilege",
+          "constraint",
+          "credits",
+          "declaration",
+          "defApiFeature",
+          "defaultValue",
+          "detail",
+          "end",
+          "eventproperty",
+          "experimental",
+          "export",
+          "expose",
+          "extendscript",
+          "factory",
+          "field",
+          "final",
+          "fixme",
+          "fluent",
+          "for",
+          "governance",
+          "header",
+          "hidden-property",
+          "hidden",
+          "id",
+          "jsx",
+          "jsxImportSource",
+          "label",
+          "language",
+          "legacy",
+          "link",
+          "listen",
+          "locus",
+          "methodOf",
+          "minVersion",
+          "ngdoc",
+          "nonstandard",
+          "note",
+          "npm",
+          "observable",
+          "option",
+          "optionobject",
+          "options",
+          "packageDocumentation",
+          "param",
+          "parent",
+          "platform",
+          "plugin",
+          "preserve",
+          "privateRemarks",
+          "privilegeLevel",
+          "privilegeName",
+          "proposed",
+          "range",
+          "readOnly",
+          "related",
+          "remark",
+          "remarks",
+          "required",
+          "requires",
+          "restriction",
+          "returnType",
+          "section",
+          "see",
+          "since",
+          "const",
+          "singleton",
+          "source",
+          "struct",
+          "suppress",
+          "targetfolder",
+          "enum",
+          "title",
+          "record",
+          "title",
+          "TODO",
+          "trigger",
+          "triggers",
+          "typeparam",
+          "typeParam",
+          "unsupported",
+          "url",
+          "usage",
+          "warn",
+          "warning",
+          "version",
+        ],
+        typed: true,
+      },
+    ],
+  },
+
+  overrides: [
+    {
+      files: ["*.cts", "*.mts", "*.ts", "*.tsx"],
+      parser: "@typescript-eslint/parser",
+      parserOptions: {
+        project: true,
+        warnOnUnsupportedTypeScriptVersion: false,
+      },
+      rules: {
+        ...Object.fromEntries(Object.keys(rules).map((name) => [`@definitelytyped/${name}`, "error"])),
+        "@typescript-eslint/ban-ts-comment": [
+          "error",
+          {
+            "ts-expect-error": false, // Used in tests.
+            "ts-ignore": "allow-with-description",
+            "ts-nocheck": true,
+            "ts-check": false,
+          },
+        ],
+      },
+    },
+  ],
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+import { all } from "./configs/all.js";
+export { rules } from "./rules/index.js";
+
+export const configs = {
+  all,
+};

package/src/rules/dt-header.ts

@@ -0,0 +1,74 @@
+import { renderExpected, validate } from "@definitelytyped/header-parser";
+import { createRule, isMainFile } from "../util";
+
+type MessageId =
+  | "definitionsBy"
+  | "minimumTypeScriptVersion"
+  | "parseError"
+  | "typeDefinitionsFor"
+  | "typescriptVersion";
+
+const rule = createRule({
+  name: "dt-header",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Ensure consistency of DefinitelyTyped headers.",
+      recommended: "error",
+    },
+    messages: {
+      definitionsBy: "Author name should be your name, not the default.",
+      minimumTypeScriptVersion: "TypeScript version should be specified under header in `index.d.ts`.",
+      parseError: "Error parsing header. Expected: {{expected}}",
+      typeDefinitionsFor: "Header should only be in `index.d.ts` of the root.",
+      typescriptVersion: "Minimum TypeScript version should be specified under header in `index.d.ts`.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const sourceCode = context.getSourceCode();
+    const { lines, text } = sourceCode;
+
+    const lookFor = (search: string, messageId: MessageId) => {
+      for (let i = 0; i < lines.length; i += 1) {
+        if (lines[i].startsWith(search)) {
+          context.report({
+            loc: {
+              end: { line: i + 1, column: search.length },
+              start: { line: i + 1, column: 0 },
+            },
+            messageId,
+          });
+        }
+      }
+    };
+
+    if (!isMainFile(context.getFilename(), /*allowNested*/ true)) {
+      lookFor("// Type definitions for", "typeDefinitionsFor");
+      lookFor("// TypeScript Version", "typescriptVersion");
+      lookFor("// Minimum TypeScript Version", "minimumTypeScriptVersion");
+      return {};
+    }
+
+    lookFor("// Definitions by: My Self", "definitionsBy");
+
+    const error = validate(text);
+    if (error) {
+      context.report({
+        data: {
+          expected: renderExpected(error.expected),
+        },
+        loc: {
+          column: error.column,
+          line: error.line,
+        },
+        messageId: "parseError",
+      });
+    }
+
+    return {};
+  },
+});
+
+export = rule;

package/src/rules/export-just-namespace.ts

@@ -0,0 +1,83 @@
+import { AST_NODE_TYPES, TSESTree } from "@typescript-eslint/utils";
+import { createRule } from "../util";
+
+interface ExportAssignmentWithIdentifier extends TSESTree.TSExportAssignment {
+  expression: TSESTree.Identifier;
+}
+
+const rule = createRule({
+  name: "export-just-namespace",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Forbids `export = foo` where `foo` is a namespace and isn't merged with a function/class/type/interface.",
+      recommended: "error",
+    },
+    messages: {
+      useTheBody: "Instead of `export =`-ing a namespace, use the body of the namespace as the module body.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const ast = context.getSourceCode().ast;
+
+    const exportEqualsNode = ast.body.find(isExportEqualsWithIdentifier);
+    if (!exportEqualsNode) {
+      return {};
+    }
+
+    if (isJustNamespace(ast.body, exportEqualsNode.expression.name)) {
+      context.report({
+        messageId: "useTheBody",
+        node: exportEqualsNode,
+      });
+    }
+
+    return {};
+  },
+});
+
+/**
+ * @returns Where there is a namespace but there are no functions/classes/etc. with the same name.
+ */
+function isJustNamespace(statements: TSESTree.ProgramStatement[], exportEqualsName: string): boolean {
+  let anyNamespace = false;
+
+  for (const statement of statements) {
+    switch (statement.type) {
+      case AST_NODE_TYPES.TSModuleDeclaration:
+        anyNamespace ||= nameMatches(statement.id);
+        break;
+      case AST_NODE_TYPES.VariableDeclaration:
+        if (statement.declarations.some((d) => nameMatches(d.id))) {
+          // OK. It's merged with a variable.
+          return false;
+        }
+        break;
+      case AST_NODE_TYPES.ClassDeclaration:
+      case AST_NODE_TYPES.FunctionDeclaration:
+      case AST_NODE_TYPES.TSDeclareFunction:
+      case AST_NODE_TYPES.TSTypeAliasDeclaration:
+      case AST_NODE_TYPES.TSInterfaceDeclaration:
+        if (nameMatches(statement.id)) {
+          // OK. It's merged with a function/class/type/interface.
+          return false;
+        }
+        break;
+    }
+  }
+
+  return anyNamespace;
+
+  function nameMatches(nameNode: TSESTree.Node | undefined | null): boolean {
+    return !!nameNode && nameNode.type === AST_NODE_TYPES.Identifier && nameNode.name === exportEqualsName;
+  }
+}
+
+function isExportEqualsWithIdentifier(node: TSESTree.Node): node is ExportAssignmentWithIdentifier {
+  return node.type === AST_NODE_TYPES.TSExportAssignment && node.expression.type === AST_NODE_TYPES.Identifier;
+}
+
+export = rule;

package/src/rules/index.ts

@@ -0,0 +1,35 @@
+import * as dtHeader from "./dt-header";
+import * as exportJustNamespace from "./export-just-namespace";
+import * as noAnyUnion from "./no-any-union";
+import * as noBadReference from "./no-bad-reference";
+import * as noConstEnum from "./no-const-enum";
+import * as noDeadReference from "./no-dead-reference";
+import * as noDeclareCurrentPackage from "./no-declare-current-package";
+import * as noImportDefaultOfExportEquals from "./no-import-default-of-export-equals";
+import * as noOutsideDependencies from "./no-outside-dependencies";
+import * as noSelfImport from "./no-self-import";
+import * as noSingleElementTupleType from "./no-single-element-tuple-type";
+import * as noUnnecessaryGenerics from "./no-unnecessary-generics";
+import * as noUselessFiles from "./no-useless-files";
+import * as preferDeclareFunction from "./prefer-declare-function";
+import * as redundantUndefined from "./redundant-undefined";
+import * as trimFile from "./trim-file";
+
+export const rules = {
+  "dt-header": dtHeader,
+  "export-just-namespace": exportJustNamespace,
+  "no-any-union": noAnyUnion,
+  "no-bad-reference": noBadReference,
+  "no-const-enum": noConstEnum,
+  "no-dead-reference": noDeadReference,
+  "no-declare-current-package": noDeclareCurrentPackage,
+  "no-import-default-of-export-equals": noImportDefaultOfExportEquals,
+  "no-outside-dependencies": noOutsideDependencies,
+  "no-self-import": noSelfImport,
+  "no-single-element-tuple-type": noSingleElementTupleType,
+  "no-unnecessary-generics": noUnnecessaryGenerics,
+  "no-useless-files": noUselessFiles,
+  "prefer-declare-function": preferDeclareFunction,
+  "redundant-undefined": redundantUndefined,
+  "trim-file": trimFile,
+};

package/src/rules/no-any-union.ts

@@ -0,0 +1,34 @@
+import { createRule } from "../util";
+import { AST_NODE_TYPES } from "@typescript-eslint/utils";
+
+const rule = createRule({
+  name: "no-any-union",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Forbid a union to contain `any`",
+      recommended: "error",
+    },
+    messages: {
+      anyUnion: "Including `any` in a union will override all other members of the union.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      TSUnionType(node) {
+        const hasAnyType = node.types.some((t) => t.type === AST_NODE_TYPES.TSAnyKeyword);
+        if (hasAnyType) {
+          context.report({
+            messageId: "anyUnion",
+            node,
+          });
+        }
+      },
+    };
+  },
+});
+
+export = rule;

package/src/rules/no-bad-reference.ts

@@ -0,0 +1,62 @@
+import { TSESTree } from "@typescript-eslint/utils";
+import { createRule } from "../util";
+
+type MessageId = "referencePathPackage" | "referencePathTest";
+
+const rule = createRule({
+  name: "no-bad-reference",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description: `Forbids <reference path="../etc"/> in any file, and forbid <reference path> in test files.`,
+      recommended: "error",
+    },
+    messages: {
+      referencePathPackage:
+        "Don't use <reference path> to reference another package. Use an import or <reference types> instead.",
+      referencePathTest:
+        "Don't use <reference path> in test files. Use <reference types> or include the file in 'tsconfig.json'.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const { comments } = context.getSourceCode().ast;
+    const isDeclarationFile = context.getFilename().endsWith(".d.ts");
+
+    for (const comment of comments) {
+      const referenceMatch = comment.value.match(/<reference\s+path\s*=\s*"(.+)"\s*\/>/)?.[1];
+      if (!referenceMatch) {
+        continue;
+      }
+
+      if (isDeclarationFile) {
+        if (referenceMatch.startsWith("..")) {
+          report(comment, "referencePathPackage");
+        }
+      } else {
+        report(comment, "referencePathTest");
+      }
+    }
+
+    return {};
+
+    function report(comment: TSESTree.Comment, messageId: MessageId) {
+      context.report({
+        loc: {
+          end: {
+            column: comment.value.lastIndexOf(`"`),
+            line: comment.loc.end.line,
+          },
+          start: {
+            column: comment.value.indexOf(`"`) + 1,
+            line: comment.loc.start.line,
+          },
+        },
+        messageId,
+      });
+    }
+  },
+});
+
+export = rule;

package/src/rules/no-const-enum.ts

@@ -0,0 +1,30 @@
+import { createRule } from "../util";
+
+const rule = createRule({
+  name: "no-const-enum",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Forbid `const enum`",
+      recommended: "error",
+    },
+    messages: {
+      constEnum: "Use of `const enum` is forbidden.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      "TSEnumDeclaration[const]"(node) {
+        context.report({
+          messageId: "constEnum",
+          node,
+        });
+      },
+    };
+  },
+});
+
+export = rule;

package/src/rules/no-dead-reference.ts

@@ -0,0 +1,46 @@
+import { createRule } from "../util";
+
+const rule = createRule({
+  name: "no-dead-reference",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Ensures that all `/// <reference>` comments go at the top of the file.",
+      recommended: "error",
+    },
+    messages: {
+      referenceAtTop: "`/// <reference>` directive must be at top of file to take effect.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const source = context.getSourceCode();
+    if (source.ast.body.length) {
+      // 'm' flag makes it multiline, so `^` matches the beginning of any line.
+      // 'g' flag lets us set rgx.lastIndex
+      const rgx = /^\s*(\/\/\/ <reference)/gm;
+
+      // Start search at the first statement. (`/// <reference>` before that is OK.)
+      rgx.lastIndex = source.ast.body[0].range?.[0] ?? 0;
+
+      // eslint-disable-next-line no-constant-condition
+      while (true) {
+        const match = rgx.exec(source.text);
+        if (match === null) {
+          break;
+        }
+
+        const length = match[1].length;
+        const start = match.index + match[0].length - length;
+        context.report({
+          messageId: "referenceAtTop",
+          loc: source.getLocFromIndex(start),
+        });
+      }
+    }
+    return {};
+  },
+});
+
+export = rule;

package/src/rules/no-declare-current-package.ts

@@ -0,0 +1,45 @@
+import { getCommonDirectoryName, createRule } from "../util";
+import { ESLintUtils, AST_NODE_TYPES } from "@typescript-eslint/utils";
+const rule = createRule({
+  name: "no-declare-current-package",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Don't use an ambient module declaration of the current package; use a normal module.",
+      recommended: "error",
+    },
+    messages: {
+      noDeclareCurrentPackage:
+        `Instead of declaring a module with \`declare module "{{ text }}"\`, ` +
+        `write its contents in directly in {{ preferred }}.`,
+    },
+    schema: [],
+  },
+  create(context) {
+    if (!context.getFilename().endsWith(".d.ts")) {
+      return {};
+    }
+    const parserServices = ESLintUtils.getParserServices(context);
+    const packageName = getCommonDirectoryName(parserServices.program.getRootFileNames());
+    return {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      TSModuleDeclaration(node) {
+        if (
+          node.id.type === AST_NODE_TYPES.Literal &&
+          (node.id.value === packageName || node.id.value.startsWith(packageName + "/"))
+        ) {
+          const text = node.id.value;
+          const preferred = text === packageName ? '"index.d.ts"' : `"${text}.d.ts" or "${text}/index.d.ts`;
+          context.report({
+            messageId: "noDeclareCurrentPackage",
+            data: { text, preferred },
+            node,
+          });
+        }
+      },
+    };
+  },
+});
+
+export = rule;

package/src/rules/no-import-default-of-export-equals.ts

@@ -0,0 +1,68 @@
+import { createRule } from "../util";
+import { ESLintUtils } from "@typescript-eslint/utils";
+import * as ts from "typescript";
+
+const rule = createRule({
+  name: "no-import-default-of-export-equals",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Forbid a default import to reference an `export =` module.",
+      recommended: "error",
+    },
+    messages: {
+      noImportDefaultOfExportEquals: `The module {{moduleName}} uses \`export = \`. Import with \`import {{importName}} = require({{moduleName}})\`.`,
+    },
+    schema: [],
+  },
+  create(context) {
+    const parserServices = ESLintUtils.getParserServices(context);
+    const checker = parserServices.program.getTypeChecker();
+    if (context.getFilename().endsWith(".d.ts")) {
+      return {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        ImportDeclaration(node) {
+          const defaultName = node.specifiers.find((spec) => spec.type === "ImportDefaultSpecifier")?.local;
+          if (!defaultName) {
+            return;
+          }
+          const importName = defaultName.name;
+          const source = parserServices.esTreeNodeToTSNodeMap.get(node.source);
+          const sym = checker.getSymbolAtLocation(source);
+          if (
+            sym?.declarations?.some((d) =>
+              getStatements(d)?.some((s) => ts.isExportAssignment(s) && !!s.isExportEquals)
+            )
+          ) {
+            context.report({
+              messageId: "noImportDefaultOfExportEquals",
+              data: { moduleName: node.source.value, importName },
+              node: defaultName,
+            });
+          }
+        },
+      };
+    } else {
+      return {};
+    }
+  },
+});
+
+function getStatements(decl: ts.Declaration): readonly ts.Statement[] | undefined {
+  return ts.isSourceFile(decl)
+    ? decl.statements
+    : ts.isModuleDeclaration(decl)
+    ? getModuleDeclarationStatements(decl)
+    : undefined;
+}
+
+function getModuleDeclarationStatements(node: ts.ModuleDeclaration): readonly ts.Statement[] | undefined {
+  let { body } = node;
+  while (body && body.kind === ts.SyntaxKind.ModuleDeclaration) {
+    body = body.body;
+  }
+  return body && ts.isModuleBlock(body) ? body.statements : undefined;
+}
+
+export = rule;

package/src/rules/no-outside-dependencies.ts

@@ -0,0 +1,42 @@
+import { createRule, isMainFile } from "../util";
+import { ESLintUtils } from "@typescript-eslint/utils";
+const rule = createRule({
+  name: "no-outside-dependencies",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Don't import things in `DefinitelyTyped/node_modules`.",
+      recommended: "error",
+    },
+    messages: {
+      noOutsideDependencies: `File {{fileName}} comes from a \`node_modules\` but is not declared in this type's \`package.json\`. `,
+    },
+    schema: [],
+  },
+  create(context) {
+    if (isMainFile(context.getFilename(), /*allowNested*/ true)) {
+      const parserServices = ESLintUtils.getParserServices(context);
+      const hasNodeReference = parserServices.program
+        .getSourceFiles()
+        .some((f) => f.typeReferenceDirectives.some((dir) => dir.fileName === "node"));
+      for (const sourceFile of parserServices.program.getSourceFiles()) {
+        const fileName = sourceFile.fileName;
+        if (
+          fileName.includes("/DefinitelyTyped/node_modules/") &&
+          !parserServices.program.isSourceFileDefaultLibrary(sourceFile) &&
+          !(hasNodeReference && fileName.includes("buffer"))
+        ) {
+          context.report({
+            messageId: "noOutsideDependencies",
+            data: { fileName },
+            loc: { column: 0, line: 1 },
+          });
+        }
+      }
+    }
+    return {};
+  },
+});
+
+export = rule;