feat: Add types to package (#179)

* chore: Upgrade ESLint

* Add back eslintignore

* Skip tests relying on project files

* feat: Add type definitions

fixes #177

* Replace deprecated type

* Add missing JSDoc comments

* Fix linting error

* Remove ExpectType and update types test

* Remove lib from tsconfig.json

* Update package.json

Co-authored-by: Francesco Trotta <[email protected]>

---------

Co-authored-by: Francesco Trotta <[email protected]>

Author: nzakas

.github/workflows/ci.yml

@@ -40,3 +40,16 @@ jobs:
       run: npm install
     - name: Test
       run: npm test
+
+  test_types:
+    name: Test Types
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: lts/*
+    - name: Install Packages
+      run: npm install
+    - name: Test
+      run: npm run test:types

lib/config-array/ignore-pattern.js

@@ -118,7 +118,7 @@ const DotPatterns = Object.freeze([".*", "!.eslintrc.*", "!../"]);
 //------------------------------------------------------------------------------
 
 /**
- *
+ * Represents a set of glob patterns to ignore against a base path.
  */
 class IgnorePattern {
 

lib/shared/config-validator.js

@@ -52,7 +52,7 @@ const noOptionsSchema = Object.freeze({
 //-----------------------------------------------------------------------------
 
 /**
- *
+ * Validator for configuration objects.
  */
 export default class ConfigValidator {
     constructor({ builtInRules = new Map() } = {}) {

lib/types/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview This file contains the core types for ESLint. It was initially extracted
+ * from the `@types/eslint__eslintrc` package.
+ */
+
+/*
+ * MIT License
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE
+ */
+
+import type { Linter } from "eslint";
+
+/**
+ * A compatibility class for working with configs.
+ */
+export class FlatCompat {
+    constructor({
+        baseDirectory,
+        resolvePluginsRelativeTo,
+        recommendedConfig,
+        allConfig,
+    }?: {
+        /**
+         * default: process.cwd()
+         */
+        baseDirectory?: string;
+        resolvePluginsRelativeTo?: string;
+        recommendedConfig?: Linter.LegacyConfig;
+        allConfig?: Linter.LegacyConfig;
+    });
+
+    /**
+     * Translates an ESLintRC-style config into a flag-config-style config.
+     * @param eslintrcConfig The ESLintRC-style config object.
+     * @returns A flag-config-style config object.
+     */
+    config(eslintrcConfig: Linter.LegacyConfig): Linter.Config[];
+
+    /**
+     * Translates the `env` section of an ESLintRC-style config.
+     * @param envConfig The `env` section of an ESLintRC config.
+     * @returns An array of flag-config objects representing the environments.
+     */
+    env(envConfig: { [name: string]: boolean }): Linter.Config[];
+
+    /**
+     * Translates the `extends` section of an ESLintRC-style config.
+     * @param configsToExtend The names of the configs to load.
+     * @returns An array of flag-config objects representing the config.
+     */
+    extends(...configsToExtend: string[]): Linter.Config[];
+
+    /**
+     * Translates the `plugins` section of an ESLintRC-style config.
+     * @param plugins The names of the plugins to load.
+     * @returns An array of flag-config objects representing the plugins.
+     */
+    plugins(...plugins: string[]): Linter.Config[];
+}

package.json

@@ -4,10 +4,12 @@
   "description": "The legacy ESLintRC config file format for ESLint",
   "type": "module",
   "main": "./dist/eslintrc.cjs",
+  "types": "./dist/eslintrc.d.ts",
   "exports": {
     ".": {
       "import": "./lib/index.js",
-      "require": "./dist/eslintrc.cjs"
+      "require": "./dist/eslintrc.cjs",
+      "types": "./lib/types/index.d.ts"
     },
     "./package.json": "./package.json",
     "./universal": {
@@ -26,7 +28,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rollup -c",
+    "build": "rollup -c && node -e \"fs.copyFileSync('./lib/types/index.d.ts', './dist/eslintrc.d.cts')\"",
     "lint": "eslint . --report-unused-disable-directives",
     "lint:fix": "npm run lint -- --fix",
     "prepare": "npm run build",
@@ -35,7 +37,8 @@
     "release:generate:beta": "eslint-generate-prerelease beta",
     "release:generate:rc": "eslint-generate-prerelease rc",
     "release:publish": "eslint-publish-release",
-    "test": "mocha -R progress -c 'tests/lib/*.cjs' && c8 mocha -R progress -c 'tests/lib/**/*.js'"
+    "test": "mocha -R progress -c 'tests/lib/*.cjs' && c8 mocha -R progress -c 'tests/lib/**/*.js'",
+    "test:types": "tsc -p tests/lib/types/tsconfig.json"
   },
   "repository": "eslint/eslintrc",
   "funding": "https://opencollective.com/eslint",

tests/lib/types/tsconfig.json

@@ -0,0 +1,17 @@
+{
+    "compilerOptions": {
+        "module": "node16",
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true,
+        "exactOptionalPropertyTypes": true
+    },
+    "files": [
+        "../../../lib/types/index.d.ts",
+        "types.test.mts"
+    ]
+}

tests/lib/types/types.test.mts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview This file contains tests for types. It was initially extracted
+ * from the `@types/eslint__eslintrc` package.
+ */
+
+/*
+ * MIT License
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE
+ */
+
+
+import { FlatCompat } from "../../../lib/types/index.js";
+import { Linter } from "eslint";
+
+const __dirname = "/path/to/project";
+
+const compat = new FlatCompat({
+    baseDirectory: __dirname,
+    resolvePluginsRelativeTo: __dirname,
+});
+
+const config: Linter.Config[] = [
+    ...compat.extends("standard", "example"),
+
+    ...compat.env({
+        es2020: true,
+        node: true,
+    }),
+
+    ...compat.plugins("airbnb", "react"),
+
+    ...compat.config({
+        plugins: ["airbnb", "react"],
+        extends: "standard",
+        env: {
+            es2020: true,
+            node: true,
+        },
+        rules: {
+            semi: "error",
+        },
+    }),
+];
+
+export default config;