feat: add type declarations for configs (#347)

Since the flat configuration system has us doing native JavaScript
imports, TypeScript can now do proper type checking which means it's
useful to start shipping types.

Because
[TypeScript](typescript-eslint/typescript-eslint#955 (comment))
requires file names to be unique (of which the file extension is not
part of), I've introduced a single declaration file that holds the types
for each config, rather than having a `.d.ts` per config, and to ensure
maximum compatibility I've defined declarations for each configuration
both with and without the `.js` extension.

configs.d.ts

@@ -0,0 +1,71 @@
+declare module 'eslint-config-ackama' {
+  import type { Linter } from 'eslint';
+
+  const config: Linter.Config;
+
+  export = config;
+}
+
+declare module 'eslint-config-ackama/@typescript-eslint' {
+  import type { Linter } from 'eslint';
+
+  const config: Linter.Config;
+
+  export = config;
+}
+
+declare module 'eslint-config-ackama/@typescript-eslint.js' {
+  import type { Linter } from 'eslint';
+
+  const config: Linter.Config;
+
+  export = config;
+}
+
+declare module 'eslint-config-ackama/flowtype' {
+  import type { Linter } from 'eslint';
+
+  const config: Linter.Config;
+
+  export = config;
+}
+
+declare module 'eslint-config-ackama/flowtype.js' {
+  import type { Linter } from 'eslint';
+
+  const config: Linter.Config;
+
+  export = config;
+}
+
+declare module 'eslint-config-ackama/jest' {
+  import type { Linter } from 'eslint';
+
+  const config: Linter.Config;
+
+  export = config;
+}
+
+declare module 'eslint-config-ackama/jest.js' {
+  import type { Linter } from 'eslint';
+
+  const config: Linter.Config;
+
+  export = config;
+}
+
+declare module 'eslint-config-ackama/react' {
+  import type { Linter } from 'eslint';
+
+  const config: Linter.Config;
+
+  export = config;
+}
+
+declare module 'eslint-config-ackama/react.js' {
+  import type { Linter } from 'eslint';
+
+  const config: Linter.Config;
+
+  export = config;
+}

package.json

@@ -9,12 +9,14 @@
   },
   "license": "ISC",
   "author": "Gareth Jones",
+  "types": "configs.d.ts",
   "files": [
     "@typescript-eslint.js",
     "flowtype.js",
     "index.js",
     "jest.js",
-    "react.js"
+    "react.js",
+    "configs.d.ts"
   ],
   "scripts": {
     "lint": "eslint . --ext js,ts",

test/configs.spec.ts

@@ -13,6 +13,8 @@ const configFiles = fs
   )
   .map(value => value.name);
 
+const typeDeclarations = fs.readFileSync('configs.d.ts', 'utf8');
+
 /**
  * Determines the canonical package name for the given eslint `plugin`,
  * that can be used to install the plugin using a package manager.
@@ -64,6 +66,13 @@ describe('package.json', () => {
     );
   });
 
+  it('includes typescript types', () => {
+    expect.hasAssertions();
+
+    expect(packageJson.types).toBe('configs.d.ts');
+    expect(packageJson.files).toContain('configs.d.ts');
+  });
+
   describe('peer dependencies', () => {
     it('includes eslint and prettier as required peer dependencies', () => {
       expect.hasAssertions();
@@ -154,6 +163,23 @@ describe('for each config file', () => {
       ]);
     });
 
+    it('is defined as a module in the type declarations', () => {
+      expect.hasAssertions();
+
+      const moduleName =
+        // eslint-disable-next-line jest/no-conditional-in-test
+        configFile === 'index.js'
+          ? 'eslint-config-ackama'
+          : `eslint-config-ackama/${configFile}`;
+
+      // we expect the module declared with and without the `.js` extension
+      // to ensure support for importing in both CJS and ESM environments
+      expect(typeDeclarations).toContain(`declare module '${moduleName}' {`);
+      expect(typeDeclarations).toContain(
+        `declare module '${moduleName.replace(/\.js$/u, '')}' {`
+      );
+    });
+
     it('lists any plugins as peer dependencies', () => {
       expect.hasAssertions();
 

tools/generate-configs-list.ts

@@ -91,6 +91,7 @@ const determineConfigDependencies = (configName: string): string[] => {
 };
 
 const configs = files
+  .filter(config => config.endsWith('.js'))
   .sort((a, b) => (a === 'index.js' ? -1 : a.localeCompare(b)))
   .map(config => path.parse(config).name)
   .flatMap(name => [