@definitelytyped/eslint-plugin 0.0.197 → 0.0.198

package/src/rules/npm-naming.ts

@@ -0,0 +1,211 @@
+import {
+  CheckOptions as CriticOptions,
+  dtsCritic as critic,
+  ErrorKind,
+  ExportErrorKind,
+  Mode,
+  parseExportErrorKind,
+  CriticError,
+} from "@definitelytyped/dts-critic";
+
+import { addSuggestion } from "../suggestions";
+import { createRule, isMainFile } from "../util";
+import { CodeRawOptionError, NpmNamingOptions } from "./npm-naming/types";
+
+function parseEnabledErrors(errors: CodeRawOptionError[]): [ExportErrorKind, boolean][] {
+  const enabledChecks: [ExportErrorKind, boolean][] = [];
+  for (const tuple of errors) {
+    const error = parseExportErrorKind(tuple[0]);
+    if (error) {
+      enabledChecks.push([error, tuple[1]]);
+    }
+  }
+  return enabledChecks;
+}
+
+function parseRawOptions(rawOptions: NpmNamingOptions): CriticOptions {
+  switch (rawOptions.mode) {
+    case Mode.Code:
+      return { ...rawOptions, errors: new Map(parseEnabledErrors(rawOptions.errors)) };
+    case Mode.NameOnly:
+      return rawOptions;
+  }
+}
+
+const enabledSuggestions: ExportErrorKind[] = [ErrorKind.JsPropertyNotInDts, ErrorKind.JsSignatureNotInDts];
+
+function toOptionsWithSuggestions(options: CriticOptions): CriticOptions {
+  if (options.mode === Mode.NameOnly) {
+    return options;
+  }
+
+  const optionsWithSuggestions = { mode: options.mode, errors: new Map(options.errors) };
+
+  for (const err of enabledSuggestions) {
+    optionsWithSuggestions.errors.set(err, true);
+  }
+
+  return optionsWithSuggestions;
+}
+
+function eslintDisableOption(error: ErrorKind): string {
+  switch (error) {
+    case ErrorKind.NoMatchingNpmPackage:
+    case ErrorKind.NoMatchingNpmVersion:
+    case ErrorKind.NonNpmHasMatchingPackage:
+      return `"off"`;
+    case ErrorKind.NoDefaultExport:
+    case ErrorKind.NeedsExportEquals:
+    case ErrorKind.JsSignatureNotInDts:
+    case ErrorKind.JsPropertyNotInDts:
+    case ErrorKind.DtsSignatureNotInJs:
+    case ErrorKind.DtsPropertyNotInJs:
+      return JSON.stringify(["error", { mode: Mode.Code, errors: [[error, false]] }]);
+  }
+}
+
+const rule = createRule<[NpmNamingOptions], "error">({
+  name: "npm-naming",
+  defaultOptions: [
+    {
+      mode: Mode.NameOnly,
+    },
+  ],
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Ensure that package name and DefinitelyTyped header match npm package info.",
+    },
+    messages: {
+      error: `{{ error }}
+If you won't fix this error now or you think this error is wrong,
+you can disable this check by adding the following options to your project's .eslintrc.json file under "rules":
+
+    "@definitelytyped/npm-naming": {{ option }}`,
+    },
+    schema: [
+      {
+        oneOf: [
+          {
+            additionalProperties: false,
+            properties: {
+              mode: {
+                type: "string",
+                enum: [Mode.NameOnly],
+              },
+            },
+            type: "object",
+          },
+          {
+            additionalProperties: false,
+            type: "object",
+            properties: {
+              mode: {
+                type: "string",
+                enum: [Mode.Code],
+              },
+              errors: {
+                type: "array",
+                items: {
+                  type: "array",
+                  items: [
+                    {
+                      description: "Name of the check.",
+                      type: "string",
+                      enum: [ErrorKind.NeedsExportEquals, ErrorKind.NoDefaultExport],
+                    },
+                    {
+                      description: "Whether the check is enabled or disabled.",
+                      type: "boolean",
+                    },
+                  ],
+                  minItems: 2,
+                  maxItems: 2,
+                },
+              },
+            },
+          },
+        ],
+      },
+    ],
+  },
+  create(context, [rawOptions]) {
+    if (!isMainFile(context.filename, /*allowNested*/ false)) {
+      return {};
+    }
+
+    const options = parseRawOptions(rawOptions);
+    const optionsWithSuggestions = toOptionsWithSuggestions(options);
+    const diagnostics = critic(context.filename, /* sourcePath */ undefined, optionsWithSuggestions);
+    const errors = filterErrors(diagnostics);
+
+    for (const error of errors) {
+      switch (error.kind) {
+        case ErrorKind.NoMatchingNpmPackage:
+        case ErrorKind.NoMatchingNpmVersion:
+        case ErrorKind.NonNpmHasMatchingPackage:
+        case ErrorKind.DtsPropertyNotInJs:
+        case ErrorKind.DtsSignatureNotInJs:
+        case ErrorKind.JsPropertyNotInDts:
+        case ErrorKind.JsSignatureNotInDts:
+        case ErrorKind.NeedsExportEquals:
+        case ErrorKind.NoDefaultExport:
+          context.report({
+            data: {
+              error: error.message,
+              option: eslintDisableOption(error.kind),
+            },
+            loc: error.position
+              ? {
+                  start: context.sourceCode.getLocFromIndex(error.position.start),
+                  end: context.sourceCode.getLocFromIndex(error.position.start + error.position.length),
+                }
+              : {
+                  end: {
+                    line: 2,
+                    column: 0,
+                  },
+                  start: {
+                    line: 1,
+                    column: 0,
+                  },
+                },
+            messageId: "error",
+          });
+          break;
+      }
+    }
+
+    return {};
+
+    function filterErrors(diagnostics: CriticError[]): CriticError[] {
+      const errors: CriticError[] = [];
+
+      diagnostics.forEach((diagnostic) => {
+        if (isSuggestion(diagnostic)) {
+          addSuggestion(
+            context.filename,
+            "npm-naming",
+            diagnostic.message,
+            diagnostic.position?.start,
+            diagnostic.position?.length,
+          );
+        } else {
+          errors.push(diagnostic);
+        }
+      });
+
+      return errors;
+    }
+
+    function isSuggestion(diagnostic: CriticError): boolean {
+      return (
+        options.mode === Mode.Code &&
+        enabledSuggestions.includes(diagnostic.kind as ExportErrorKind) &&
+        !(options.errors as Map<ErrorKind, boolean>).get(diagnostic.kind)
+      );
+    }
+  },
+});
+
+export = rule;

package/src/suggestions.ts

@@ -0,0 +1,75 @@
+import fs = require("fs");
+import os = require("os");
+import path = require("path");
+
+const suggestionsDir = path.join(os.homedir(), ".dts", "suggestions");
+
+interface Suggestion {
+  fileName: string;
+  ruleName: string;
+  message: string;
+  start?: number;
+  width?: number;
+}
+
+// Packages for which suggestions were already added in this run of dtslint.
+const existingPackages = new Set();
+
+/**
+ *  A rule should call this function to provide a suggestion instead of a lint failure.
+ */
+export function addSuggestion(fileName: string, ruleName: string, message: string, start?: number, width?: number) {
+  const suggestion: Suggestion = {
+    fileName,
+    ruleName,
+    message,
+    start,
+    width,
+  };
+
+  const packageName = dtPackageName(fileName);
+  if (!packageName) {
+    return;
+  }
+  let flag = "a";
+  if (!existingPackages.has(packageName)) {
+    flag = "w";
+    existingPackages.add(packageName);
+  }
+  try {
+    if (!fs.existsSync(suggestionsDir)) {
+      fs.mkdirSync(suggestionsDir, { recursive: true });
+    }
+    fs.writeFileSync(
+      path.join(suggestionsDir, packageName + ".txt"),
+      flag === "a" ? "\n" + formatSuggestion(suggestion) : formatSuggestion(suggestion),
+      { flag, encoding: "utf8" },
+    );
+  } catch (e) {
+    console.log(`Could not write suggestions for package ${packageName}. ${(e as Error).message || ""}`);
+  }
+}
+
+const dtPath = path.join("DefinitelyTyped", "types");
+
+function dtPackageName(filePath: string): string | undefined {
+  const dtIndex = filePath.indexOf(dtPath);
+  if (dtIndex === -1) {
+    return undefined;
+  }
+  const basePath = filePath.substr(dtIndex + dtPath.length);
+  const dirs = basePath.split(path.sep).filter((dir) => dir !== "");
+  if (dirs.length === 0) {
+    return undefined;
+  }
+  const packageName = dirs[0];
+  // Check if this is an old version of a package.
+  if (dirs.length > 1 && /^v\d+(\.\d+)?$/.test(dirs[1])) {
+    return packageName + dirs[1];
+  }
+  return packageName;
+}
+
+function formatSuggestion(suggestion: Suggestion): string {
+  return JSON.stringify(suggestion, /*replacer*/ undefined, 0);
+}

package/src/util.ts

@@ -116,3 +116,24 @@ export function getImportSource(
 
   return undefined;
 }
+
+export function isMainFile(fileName: string, allowNested: boolean) {
+  // Linter may be run with cwd of the package. We want `index.d.ts` but not `submodule/index.d.ts` to match.
+  if (fileName === "index.d.ts") {
+    return true;
+  }
+
+  if (path.basename(fileName) !== "index.d.ts") {
+    return false;
+  }
+
+  let parent = path.dirname(fileName);
+  // May be a directory for an older version, e.g. `v0`.
+  // Note a types redirect `foo/ts3.1` should not have its own header.
+  if (allowNested && /^v(0\.)?\d+$/.test(path.basename(parent))) {
+    parent = path.dirname(parent);
+  }
+
+  // Allow "types/foo/index.d.ts", not "types/foo/utils/index.d.ts"
+  return path.basename(path.dirname(parent)) === "types";
+}

package/test/__snapshots__/plugin.test.ts.snap

@@ -0,0 +1,262 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`plugin should have the expected exports 1`] = `
+{
+  "configs": {
+    "all": {
+      "overrides": [
+        {
+          "files": [
+            "*.cts",
+            "*.mts",
+            "*.ts",
+            "*.tsx",
+          ],
+          "parser": "@typescript-eslint/parser",
+          "parserOptions": {
+            "project": true,
+            "warnOnUnsupportedTypeScriptVersion": false,
+          },
+          "rules": {
+            "@definitelytyped/expect": "error",
+            "@definitelytyped/export-just-namespace": "error",
+            "@definitelytyped/no-any-union": "error",
+            "@definitelytyped/no-bad-reference": "error",
+            "@definitelytyped/no-const-enum": "error",
+            "@definitelytyped/no-dead-reference": "error",
+            "@definitelytyped/no-declare-current-package": "error",
+            "@definitelytyped/no-import-default-of-export-equals": "error",
+            "@definitelytyped/no-import-of-dev-dependencies": "error",
+            "@definitelytyped/no-old-dt-header": "error",
+            "@definitelytyped/no-relative-import-in-test": "error",
+            "@definitelytyped/no-self-import": "error",
+            "@definitelytyped/no-single-declare-module": "error",
+            "@definitelytyped/no-single-element-tuple-type": "error",
+            "@definitelytyped/no-unnecessary-generics": "error",
+            "@definitelytyped/no-useless-files": "error",
+            "@definitelytyped/prefer-declare-function": "error",
+            "@definitelytyped/redundant-undefined": "error",
+            "@definitelytyped/strict-export-declare-modifiers": "error",
+            "@typescript-eslint/adjacent-overload-signatures": "error",
+            "@typescript-eslint/array-type": [
+              "error",
+              {
+                "default": "array-simple",
+              },
+            ],
+            "@typescript-eslint/ban-ts-comment": [
+              "error",
+              {
+                "ts-check": false,
+                "ts-expect-error": false,
+                "ts-ignore": "allow-with-description",
+                "ts-nocheck": true,
+              },
+            ],
+            "@typescript-eslint/ban-types": [
+              "error",
+              {
+                "extendDefaults": true,
+                "types": {
+                  "{}": false,
+                },
+              },
+            ],
+            "@typescript-eslint/consistent-type-definitions": "error",
+            "@typescript-eslint/explicit-member-accessibility": [
+              "error",
+              {
+                "accessibility": "no-public",
+              },
+            ],
+            "@typescript-eslint/naming-convention": [
+              "error",
+              {
+                "custom": {
+                  "match": false,
+                  "regex": "^I[A-Z]",
+                },
+                "format": [],
+                "selector": "interface",
+              },
+            ],
+            "@typescript-eslint/no-empty-interface": "error",
+            "@typescript-eslint/no-invalid-void-type": [
+              "error",
+              {
+                "allowAsThisParameter": true,
+                "allowInGenericTypeArguments": true,
+              },
+            ],
+            "@typescript-eslint/no-misused-new": "error",
+            "@typescript-eslint/prefer-namespace-keyword": "error",
+            "@typescript-eslint/triple-slash-reference": [
+              "error",
+              {
+                "path": "always",
+                "types": "prefer-import",
+              },
+            ],
+            "no-duplicate-imports": "error",
+            "unicode-bom": [
+              "error",
+              "never",
+            ],
+          },
+        },
+      ],
+      "plugins": [
+        "@definitelytyped",
+        "@typescript-eslint",
+        "jsdoc",
+      ],
+      "rules": {
+        "jsdoc/check-tag-names": [
+          "error",
+          {
+            "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,
+          },
+        ],
+      },
+      "settings": {
+        "jsdoc": {
+          "tagNamePreference": {
+            "argument": "argument",
+            "exception": "exception",
+            "function": "function",
+            "method": "method",
+            "param": "param",
+            "return": "return",
+            "returns": "returns",
+          },
+        },
+      },
+    },
+  },
+  "meta": {
+    "name": "@definitelytyped/eslint-plugin",
+    "version": "version",
+  },
+  "rules": [
+    "export-just-namespace",
+    "no-any-union",
+    "no-bad-reference",
+    "no-const-enum",
+    "no-dead-reference",
+    "no-declare-current-package",
+    "no-import-default-of-export-equals",
+    "no-relative-import-in-test",
+    "no-self-import",
+    "no-single-element-tuple-type",
+    "no-unnecessary-generics",
+    "no-useless-files",
+    "prefer-declare-function",
+    "redundant-undefined",
+    "strict-export-declare-modifiers",
+    "no-single-declare-module",
+    "no-old-dt-header",
+    "no-import-of-dev-dependencies",
+    "npm-naming",
+    "expect",
+  ],
+}
+`;

package/test/npm-naming.test.ts

@@ -0,0 +1,57 @@
+import { RuleTester } from "@typescript-eslint/rule-tester";
+
+import * as npmNaming from "../src/rules/npm-naming";
+import { ErrorKind, Mode } from "@definitelytyped/dts-critic";
+
+const ruleTester = new RuleTester({
+  parser: "@typescript-eslint/parser",
+});
+
+ruleTester.run("npm-naming", npmNaming, {
+  invalid: [
+    {
+      code: `export default dtsCritic();`,
+      errors: [
+        {
+          data: {
+            error: `The declaration doesn't match the JavaScript module 'dts-critic'. Reason:
+The declaration should use 'export =' syntax because the JavaScript source uses 'module.exports =' syntax and 'module.exports' can be called or constructed.
+
+To learn more about 'export =' syntax, see https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require.`,
+            option: `["error",{"mode":"code","errors":[["NeedsExportEquals",false]]}]`,
+          },
+          column: 1,
+          endColumn: 1,
+          line: 1,
+          endLine: 2,
+          messageId: "error",
+        },
+      ],
+      filename: "packages/eslint-plugin/test/types/dts-critic/index.d.ts",
+      options: [{ mode: Mode.Code, errors: [[ErrorKind.NeedsExportEquals, true]] }],
+    },
+    {
+      code: `// test content`,
+      errors: [
+        {
+          data: {
+            error: `Declaration file must have a matching npm package.
+To resolve this error, either:
+1. Change the name to match an npm package.
+2. Add \`\"nonNpm\": true\` to the package.json to indicate that this is not an npm package.
+   Ensure the package name is descriptive enough to avoid conflicts with future npm packages.`,
+            option: `"off"`,
+          },
+          column: 1,
+          endColumn: 1,
+          line: 1,
+          endLine: 2,
+          messageId: "error",
+        },
+      ],
+      filename: "packages/eslint-plugin/test/types/wenceslas/index.d.ts",
+      options: [{ mode: Mode.NameOnly }],
+    },
+  ],
+  valid: [],
+});

package/test/plugin.test.ts

@@ -0,0 +1,14 @@
+import plugin = require("../src/index");
+
+describe("plugin", () => {
+  it("should have the expected exports", () => {
+    expect({
+      ...plugin,
+      meta: {
+        ...plugin.meta,
+        version: "version",
+      },
+      rules: Object.keys(plugin.rules),
+    }).toMatchSnapshot();
+  });
+});

package/test/types/dts-critic/index.d.ts

@@ -0,0 +1,9 @@
+declare function _default(): void;
+
+declare namespace _default {
+  export function findDtsName(dtsPath: string): string;
+  export function checkNames(names: string[]): unknown;
+  export function checkSource(text: string): unknown;
+  export function findNames(): string[];
+  export function retrieveNpmHomepageOrFail(): string[];
+}

package/test/types/dts-critic/package.json

@@ -0,0 +1,17 @@
+{
+    "devDependencies": {
+        "@types/dts-critic": "workspace:."
+    },
+    "private": true,
+    "projects": [
+        "https://typescriptlang.org"
+    ],
+    "version": "1.0.9999",
+    "name": "@types/dts-critic",
+    "owners": [
+        {
+            "githubUsername": "ghost",
+            "name": "Not Default"
+        }
+    ]
+}

package/test/types/wenceslas/package.json

@@ -0,0 +1,17 @@
+{
+    "devDependencies": {
+        "@types/wenceslas": "workspace:."
+    },
+    "private": true,
+    "projects": [
+        "https://typescriptlang.org"
+    ],
+    "version": "0.9.9999",
+    "name": "@types/wenceslas",
+    "owners": [
+        {
+            "githubUsername": "ghost",
+            "name": "Not Default"
+        }
+    ]
+}