@definitelytyped/dtslint 0.0.166 → 0.0.167

package/docs/no-any-union.md

@@ -0,0 +1,27 @@
+# no-any-union
+
+Forbids to include `any` in a union. When `any` is used in a union type, the resulting type is still `any`.
+
+**Bad**:
+
+```ts
+function f(x: string | any): void;
+```
+
+**Good**:
+
+```ts
+function f(x: string): void;
+```
+
+Or:
+```ts
+function f(x: any): void;
+```
+
+Or:
+```ts
+function f(x: string | object): void;
+```
+
+While the `string` portion of this type annotation may _look_ useful, it in fact offers no additional typechecking over simply using `any`.

package/docs/no-bad-reference.md

@@ -0,0 +1,28 @@
+# no-bad-reference
+
+(This rule is specific to DefinitelyTyped.)
+Avoid using `<reference path>`.
+
+**Bad**:
+
+```ts
+/// <reference path="../node_modules/@types/foo/index.d.ts" />
+import * as foo from "foo";
+```
+
+**Good**:
+
+If "foo" is written in external module style (see `no-single-declare-module`), the import alone should work thanks to [module resolution](http://www.typescriptlang.org/docs/handbook/module-resolution.html):
+
+```ts
+// TypeScript will look for a definition for "foo" using module resolution
+import * as foo from "foo";
+```
+
+If not, use `<reference types>` instead:
+
+```ts
+/// <reference types="foo" />
+```
+
+The only time `<reference path>` should be necessary if for global (not module) libraries that are separated into multiple files; the index file must include references to the others to bring them into the compilation.

package/docs/no-const-enum.md

@@ -0,0 +1,16 @@
+# no-const-enum
+
+Avoid using `const enum`s. These can't be used by JavaScript users or by TypeScript users with [`--isolatedModules`](https://www.typescriptlang.org/docs/handbook/compiler-options.html) enabled.
+
+**Bad**:
+
+```ts
+const enum Bit { Off, On }
+export function f(b: Bit): void;
+```
+
+**Good**:
+
+```ts
+export function f(b: 0 | 1): void;
+```

package/docs/no-dead-reference.md

@@ -0,0 +1,17 @@
+# no-dead-reference
+
+A `<reference>` comment should go at the top of a file -- otherwise it is just a normal comment.
+
+**Bad**:
+
+```ts
+console.log("Hello world!");
+/// <reference types="jquery" />
+```
+
+**Good**:
+
+```ts
+/// <reference types="jquery" />
+console.log("Hello world!");
+```

package/docs/no-declare-current-package.md

@@ -0,0 +1,35 @@
+# no-declare-current-package
+
+Avoid using `declare module`, and prefer to declare module contents in a file.
+
+**Bad**:
+
+```ts
+// foo/index.d.ts
+declare module "foo" {
+    export const x = 0;
+}
+```
+
+**Good**:
+
+```ts
+// foo/index.d.ts
+export const x = 0;
+```
+
+**Bad**:
+
+```ts
+// foo/index.d.ts
+declare module "foo/bar" {
+    export const x = 0;
+}
+```
+
+**Good**:
+
+```ts
+// foo/bar.d.ts
+export const x = 0;
+```

package/docs/no-import-default-of-export-equals.md

@@ -0,0 +1,22 @@
+# no-import-default-of-export-equals
+
+Don't use a default import of a package that uses `export =`.
+Users who do not have `--allowSyntheticDefaultExports` or `--esModuleInterop` will get different behavior.
+This rule only applies to definition files -- for test files you can use a default import if you prefer.
+
+**Bad**:
+
+```ts
+// foo/index.d.ts
+declare interface I {}
+export = I;
+
+// bar/index.d.ts
+import I from "foo";
+```
+
+**Good**:
+
+```ts
+import I = require("foo");
+```

package/docs/no-outside-dependencies.md

@@ -0,0 +1,23 @@
+# no-outside-dependencies
+
+Don't import from `DefinitelyTyped/node_modules`.
+
+**Bad**:
+
+```ts
+import * as x from "x";
+// where 'x' is defined only in `DefinitelyTyped/node_modules`
+```
+
+**Good**:
+
+Add a `package.json`:
+
+```ts
+{
+    "private": true,
+    "dependencies": {
+        "x": "^1.2.3"
+    }
+}
+```

package/docs/no-self-import.md

@@ -0,0 +1,27 @@
+# no-self-import
+
+A package should not import components of itself using a globally-qualified name; it should use relative imports instead.
+
+**Bad**:
+
+```ts
+import foo from "this-package/foo.d.ts";
+```
+
+**Good**:
+
+```ts
+import foo from "./foo.d.ts";
+```
+
+**Bad**:
+
+```ts
+import myself from "this-package";
+```
+
+**Good**:
+
+```ts
+import myself from ".";
+```

package/docs/no-single-element-tuple-type.md

@@ -0,0 +1,15 @@
+# no-single-element-tuple-type
+
+Some users mistakenly write `[T]` when then intend to write an array type `T[]`.
+
+**Bad**:
+
+```ts
+export const x: [T];
+```
+
+**Good**:
+
+```ts
+export const x: T[];
+```

package/docs/no-unnecessary-generics.md

@@ -0,0 +1,69 @@
+# no-unnecessary-generics
+
+Forbids a function to use a generic type parameter only once.
+Generic type parameters allow you to relate the type of one thing to another;
+if they are used only once, they can be replaced with their type constraint.
+
+**Bad**:
+
+```ts
+function logAnything<T>(x: T): void;
+```
+
+**Good**:
+
+```ts
+function logAnything(x: any): void;
+```
+
+---
+
+**Bad**:
+
+```ts
+function useLogger<T extends Logger>(logger: T): void;
+```
+
+**Good**:
+
+```ts
+function useLogger(logger: Logger): void;
+```
+
+---
+
+**Bad**:
+
+```ts
+function clear<T>(array: T[]): void;
+```
+
+**Good**:
+
+```ts
+function clear(array: any[]): void;
+```
+
+---
+
+`getMeAT<T>(): T`:
+If a type parameter does not appear in the types of any parameters, you don't really have a generic function, you just have a disguised type assertion.
+Prefer to use a real type assertion, e.g. `getMeAT() as number`.
+Example where a type parameter is acceptable: `function id<T>(value: T): T;`.
+Example where it is not acceptable: `function parseJson<T>(json: string): T;`.
+Exception: `new Map<string, number>()` is OK.
+
+**Bad**:
+
+```ts
+function parse<T>(): T;
+const x = parse<number>();
+```
+
+**Good**:
+
+
+```ts
+function parse(): {};
+const x = parse() as number;
+```

package/docs/no-useless-files.md

@@ -0,0 +1,14 @@
+# no-useless-files
+
+Don't include empty files.
+
+**Bad**:
+
+```ts
+```
+
+**Good**:
+
+```ts
+export function something(): void;
+```

package/docs/prefer-declare-function.md

@@ -0,0 +1,15 @@
+# prefer-declare-function
+
+Prefer to declare a function using the `function` keyword instead of a variable of function type.
+
+**Bad**:
+
+```ts
+export const f: () => number;
+```
+
+**Good**:
+
+```ts
+export function f(): number;
+```

package/docs/redundant-undefined.md

@@ -0,0 +1,15 @@
+# redundant-undefined
+
+Avoid explicitly specifying `undefined` as a type for a parameter which is already optional.
+
+**Bad**:
+
+```ts
+function f(s?: string | undefined): void {}
+```
+
+**Good**:
+
+```ts
+function f(s?: string): void {}
+```

package/docs/trim-file.md

@@ -0,0 +1,17 @@
+# trim-file
+
+Don't include blank lines at the beginning or end of a file.
+
+**Bad**:
+
+```ts
+
+export function f(): number;
+
+```
+
+**Good**:
+
+```ts
+export function f(): number;
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@definitelytyped/dtslint",
-  "version": "0.0.166",
+  "version": "0.0.167",
   "description": "Runs tests on TypeScript definition files",
   "main": "./dist/index.js",
   "bin": "./dist/index.js",
@@ -22,10 +22,10 @@
     "test": "../../node_modules/.bin/jest --config ../../jest.config.js packages/dtslint"
   },
   "dependencies": {
-    "@definitelytyped/dts-critic": "^0.0.166",
-    "@definitelytyped/header-parser": "^0.0.166",
-    "@definitelytyped/typescript-versions": "^0.0.166",
-    "@definitelytyped/utils": "^0.0.166",
+    "@definitelytyped/dts-critic": "^0.0.167",
+    "@definitelytyped/header-parser": "^0.0.167",
+    "@definitelytyped/typescript-versions": "^0.0.167",
+    "@definitelytyped/utils": "^0.0.167",
     "@typescript-eslint/eslint-plugin": "^5.55.0",
     "@typescript-eslint/parser": "^5.55.0",
     "@typescript-eslint/types": "^5.56.0",
@@ -52,5 +52,5 @@
     "node": ">=10.0.0"
   },
   "license": "MIT",
-  "gitHead": "e350e85d1fafe538f7bbe2a700639aaaa4e90814"
+  "gitHead": "e12bf210f4a28f20a84052fc049baccc5673d49a"
 }

package/src/lint.ts

@@ -67,7 +67,9 @@ export async function lint(
   if (!expectOnly) {
     const cwd = process.cwd();
     process.chdir(dirPath);
-    const eslint = new ESLint();
+    const eslint = new ESLint({
+      rulePaths: [joinPaths(__dirname, "./rules/")],
+    });
     const formatter = await eslint.loadFormatter("stylish");
     const eresults = await eslint.lintFiles(esfiles);
     output += formatter.format(eresults);

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/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;