@definitelytyped/dtslint 0.0.166 → 0.0.167-next.1

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;

package/src/rules/no-self-import.ts

@@ -0,0 +1,40 @@
+import { ESLintUtils } from "@typescript-eslint/utils";
+import { createRule, getCommonDirectoryName } from "../util";
+
+const rule = createRule({
+  name: "no-self-import",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Forbids declaration files to import the current package using a global import.",
+      recommended: "error",
+    },
+    messages: {
+      useRelativeImport: "Declaration file should not use a global import of itself. Use a relative import.",
+    },
+    schema: [],
+  },
+  create(context) {
+    if (!context.getFilename().endsWith(".d.ts")) {
+      return {};
+    }
+
+    const services = ESLintUtils.getParserServices(context);
+    const packageName = getCommonDirectoryName(services.program.getRootFileNames());
+
+    return {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      ImportDeclaration(node) {
+        if (node.source.value === packageName || node.source.value.startsWith(packageName + "/")) {
+          context.report({
+            messageId: "useRelativeImport",
+            node,
+          });
+        }
+      },
+    };
+  },
+});
+
+export = rule;

package/src/rules/no-single-element-tuple-type.ts

@@ -0,0 +1,31 @@
+import { createRule } from "../util";
+import { TSESTree } from "@typescript-eslint/utils";
+
+const rule = createRule({
+  name: "no-single-element-tuple-type",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Forbids `[T]`, which should be `T[]`.",
+      recommended: "error",
+    },
+    messages: {
+      singleElementTupleType: `Type [T] is a single-element tuple type. You probably meant T[].`,
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      "TSTupleType[elementTypes.length=1]"(node: TSESTree.TSTupleType) {
+        context.report({
+          messageId: "singleElementTupleType",
+          node,
+        });
+      },
+    };
+  },
+});
+
+export = rule;

package/src/rules/no-unnecessary-generics.ts

@@ -0,0 +1,126 @@
+import { ESLintUtils, TSESTree } from "@typescript-eslint/utils";
+import * as ts from "typescript";
+
+import { createRule } from "../util";
+
+type ESTreeFunctionLikeWithTypeParameters = TSESTree.FunctionLike & {
+  typeParameters: {};
+};
+
+type TSSignatureDeclarationWithTypeParameters = ts.SignatureDeclaration & {
+  typeParameters: {};
+};
+
+const rule = createRule({
+  defaultOptions: [],
+  meta: {
+    docs: {
+      description: "Forbids signatures using a generic parameter only once.",
+      recommended: "error",
+    },
+    messages: {
+      never: "Type parameter {{name}} is never used.",
+      sole: "Type parameter {{name}} is used only once.",
+    },
+    schema: [],
+    type: "problem",
+  },
+  name: "no-relative-import-in-test",
+  create(context) {
+    return {
+      [[
+        "ArrowFunctionExpression[typeParameters]",
+        "FunctionDeclaration[typeParameters]",
+        "FunctionExpression[typeParameters]",
+        "TSCallSignatureDeclaration[typeParameters]",
+        "TSConstructorType[typeParameters]",
+        "TSDeclareFunction[typeParameters]",
+        "TSFunctionType[typeParameters]",
+        "TSMethodSignature[typeParameters]",
+      ].join(", ")](esNode: ESTreeFunctionLikeWithTypeParameters) {
+        const parserServices = ESLintUtils.getParserServices(context);
+        const tsNode = parserServices.esTreeNodeToTSNodeMap.get(esNode) as TSSignatureDeclarationWithTypeParameters;
+        if (!tsNode.typeParameters) {
+          return;
+        }
+
+        const checker = parserServices.program.getTypeChecker();
+
+        for (const typeParameter of tsNode.typeParameters) {
+          const name = typeParameter.name.text;
+          const res = getSoleUse(tsNode, assertDefined(checker.getSymbolAtLocation(typeParameter.name)), checker);
+          switch (res.type) {
+            case "sole":
+              context.report({
+                data: { name },
+                messageId: "sole",
+                node: parserServices.tsNodeToESTreeNodeMap.get(res.soleUse),
+              });
+              break;
+            case "never":
+              context.report({
+                data: { name },
+                messageId: "never",
+                node: parserServices.tsNodeToESTreeNodeMap.get(typeParameter),
+              });
+              break;
+          }
+        }
+      },
+    };
+  },
+});
+
+type Result = { type: "ok" | "never" } | { type: "sole"; soleUse: ts.Identifier };
+function getSoleUse(sig: ts.SignatureDeclaration, typeParameterSymbol: ts.Symbol, checker: ts.TypeChecker): Result {
+  const exit = {};
+  let soleUse: ts.Identifier | undefined;
+
+  try {
+    if (sig.typeParameters) {
+      for (const tp of sig.typeParameters) {
+        if (tp.constraint) {
+          recur(tp.constraint);
+        }
+      }
+    }
+    for (const param of sig.parameters) {
+      if (param.type) {
+        recur(param.type);
+      }
+    }
+    if (sig.type) {
+      recur(sig.type);
+    }
+  } catch (err) {
+    if (err === exit) {
+      return { type: "ok" };
+    }
+    throw err;
+  }
+
+  return soleUse ? { type: "sole", soleUse } : { type: "never" };
+
+  function recur(node: ts.Node): void {
+    if (ts.isIdentifier(node)) {
+      if (checker.getSymbolAtLocation(node) === typeParameterSymbol) {
+        if (soleUse === undefined) {
+          soleUse = node;
+        } else {
+          throw exit;
+        }
+      }
+    } else {
+      node.forEachChild(recur);
+    }
+  }
+}
+
+export = rule;
+
+function assertDefined<T>(value: T | undefined): T {
+  if (value === undefined) {
+    throw new Error("unreachable");
+  }
+  return value;
+}

package/src/rules/no-useless-files.ts

@@ -0,0 +1,58 @@
+import { createRule } from "../util";
+
+const rule = createRule({
+  name: "no-useless-files",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Forbids files with no content.",
+      recommended: "error",
+    },
+    messages: {
+      noContent: "File has no content.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const {
+      ast: { tokens, comments },
+    } = context.getSourceCode();
+
+    if (tokens.length === 0) {
+      if (comments.length === 0) {
+        reportNoContent();
+      } else {
+        const referenceRegExp = /^\/\s*<reference\s*(types|path)\s*=\s*["|'](.*)["|']/;
+        let noReferenceFound = true;
+
+        for (const comment of comments) {
+          const referenceMatch = comment.value.match(referenceRegExp)?.[1];
+          if (!referenceMatch) {
+            continue;
+          }
+          noReferenceFound = false;
+          break;
+        }
+
+        if (noReferenceFound) {
+          reportNoContent();
+        }
+      }
+    }
+
+    return {};
+
+    function reportNoContent() {
+      context.report({
+        messageId: "noContent",
+        loc: {
+          start: { line: 1, column: 0 },
+          end: { line: 1, column: 0 },
+        },
+      });
+    }
+  },
+});
+
+export = rule;

package/src/rules/prefer-declare-function.ts

@@ -0,0 +1,37 @@
+import { AST_NODE_TYPES, TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../util";
+
+const rule = createRule({
+  defaultOptions: [],
+  meta: {
+    docs: {
+      description: "Forbids `const x: () => void`.",
+      recommended: "error",
+    },
+    messages: {
+      variableFunction: "Use a function declaration instead of a variable of function type.",
+    },
+    schema: [],
+    type: "problem",
+  },
+  name: "prefer-declare-function",
+  create(context) {
+    return {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      "VariableDeclaration > VariableDeclarator"(node: TSESTree.VariableDeclarator) {
+        if (
+          node.id.typeAnnotation?.typeAnnotation.type === AST_NODE_TYPES.TSFunctionType &&
+          context.getFilename().endsWith(".d.ts")
+        ) {
+          context.report({
+            messageId: "variableFunction",
+            node: node.id,
+          });
+        }
+      },
+    };
+  },
+});
+
+export = rule;

package/src/rules/redundant-undefined.ts

@@ -0,0 +1,62 @@
+import { createRule } from "../util";
+import { AST_NODE_TYPES } from "@typescript-eslint/utils";
+import { TSESTree } from "@typescript-eslint/types";
+
+const rule = createRule({
+  name: "redundant-undefined",
+  defaultOptions: [],
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Forbids optional parameters from including an explicit `undefined` in their type; requires it in optional properties.",
+      recommended: "error",
+    },
+    messages: {
+      redundantUndefined: `Parameter is optional, so no need to include \`undefined\` in the type.`,
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      TSUnionType(node) {
+        const hasUndefinedType = node.types.some((t) => t.type === AST_NODE_TYPES.TSUndefinedKeyword);
+        if (
+          node.parent!.type === AST_NODE_TYPES.TSTypeAnnotation &&
+          isParameter(node.parent!.parent!) &&
+          node.parent.parent.optional &&
+          isFunctionLike(node.parent!.parent!.parent!) &&
+          hasUndefinedType
+        ) {
+          context.report({
+            messageId: "redundantUndefined",
+            node,
+          });
+        }
+      },
+    };
+  },
+});
+
+function isFunctionLike(node: TSESTree.Node): node is TSESTree.FunctionLike {
+  return (
+    node.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+    node.type === AST_NODE_TYPES.FunctionDeclaration ||
+    node.type === AST_NODE_TYPES.FunctionExpression ||
+    node.type === AST_NODE_TYPES.TSDeclareFunction ||
+    node.type === AST_NODE_TYPES.TSEmptyBodyFunctionExpression
+  );
+}
+/** Note: Does not include parameter properties because those can't be optional */
+function isParameter(node: TSESTree.Node): node is Exclude<TSESTree.Parameter, TSESTree.TSParameterProperty> {
+  return (
+    node.type === AST_NODE_TYPES.ArrayPattern ||
+    node.type === AST_NODE_TYPES.AssignmentPattern ||
+    node.type === AST_NODE_TYPES.Identifier ||
+    node.type === AST_NODE_TYPES.ObjectPattern ||
+    node.type === AST_NODE_TYPES.RestElement
+  );
+}
+
+export = rule;

package/src/rules/trim-file.ts

@@ -0,0 +1,45 @@
+import { createRule } from "../util";
+
+const rule = createRule({
+  name: "trim-file",
+  defaultOptions: [],
+  meta: {
+    type: "layout",
+    docs: {
+      description: "Forbids leading/trailing blank lines in a file. Allows file to end in '\n'",
+      recommended: "error",
+    },
+    messages: {
+      leadingBlankLine: "File should not begin with a blank line.",
+      trailingBlankLine:
+        "File should not end with a blank line. (Ending in one newline OK, ending in two newlines not OK.)",
+    },
+    schema: [],
+  },
+  create(context) {
+    const { lines, text } = context.getSourceCode();
+    if (text.startsWith("\r") || text.startsWith("\n")) {
+      context.report({
+        messageId: "leadingBlankLine",
+        loc: {
+          start: { line: 1, column: 0 },
+          end: { line: 1, column: 0 },
+        },
+      });
+    }
+    if (text.endsWith("\n\n") || text.endsWith("\r\n\r\n")) {
+      const line = lines.length;
+      context.report({
+        messageId: "trailingBlankLine",
+        loc: {
+          start: { line, column: 0 },
+          end: { line, column: 0 },
+        },
+      });
+    }
+
+    return {};
+  },
+});
+
+export = rule;

package/src/util.ts

@@ -1,9 +1,14 @@
+import { ESLintUtils } from "@typescript-eslint/utils";
 import assert = require("assert");
 import { pathExists, readFile } from "fs-extra";
 import { basename, dirname, join } from "path";
 import stripJsonComments = require("strip-json-comments");
 import * as ts from "typescript";
 
+export const createRule = ESLintUtils.RuleCreator(
+  (name) => `https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/dtslint/src/rules/${name}.ts`
+);
+
 export async function readJson(path: string) {
   const text = await readFile(path, "utf-8");
   return JSON.parse(stripJsonComments(text));
@@ -13,6 +18,19 @@ export function failure(ruleName: string, s: string): string {
   return `${s} See: https://github.com/microsoft/DefinitelyTyped-tools/blob/master/packages/dtslint/docs/${ruleName}.md`;
 }
 
+export function getCommonDirectoryName(files: readonly string[]): string {
+  let minLen = 999;
+  let minDir = "";
+  for (const file of files) {
+    const dir = dirname(file);
+    if (dir.length < minLen) {
+      minDir = dir;
+      minLen = dir.length;
+    }
+  }
+  return basename(minDir);
+}
+
 export async function getCompilerOptions(dirPath: string): Promise<ts.CompilerOptions> {
   const tsconfigPath = join(dirPath, "tsconfig.json");
   if (!(await pathExists(tsconfigPath))) {
@@ -30,6 +48,13 @@ export function last<T>(a: readonly T[]): T {
   return a[a.length - 1];
 }
 
+export function assertDefined<T>(a: T | undefined): T {
+  if (a === undefined) {
+    throw new Error();
+  }
+  return a;
+}
+
 export async function mapDefinedAsync<T, U>(arr: Iterable<T>, mapper: (t: T) => Promise<U | undefined>): Promise<U[]> {
   const out = [];
   for (const a of arr) {