RFC: Use package.json exports to "hide" the dist folder for packages and control our exported surface-area

[bradzacher]

Currently we don't use package.json exports, so anyone can import any file in any package by directly referencing a path within the dist folder - i.e.

import * as TSESLint from '@typescript-eslint/utils/dist/ts-eslint';

This is obviously a sub-par experience for consumers due to the deep path, and is a sub-par experience for us because any file technically forms part of our "external API".

In ESLint v8 they began using exports to lock down their package, and I think we should follow their lead to some degree.

I propose that we follow one of the following options:

1) export all of dist, without the dist

{
  "exports": {
    "./*": "./dist/*"
  },
  "typesVersions": {
    "*": {
      "*": ["dist/*"]
    }
  }
}

This is the least restrictive thing we could do - it would simply mean consumers needn't include dist/ in their import path - which is nice as it hides an implementation detail.

2) export all, but ban specific things

{
  "exports": {
    "./*": "./dist/*"
    "./some-internal/file": null
  },
  "typesVersions": {
    "*": {
      "*": ["dist/*"]
    }
  }
}

This is slightly more restrictive, but still very permissive.
This would allow us to build APIs that are intended to be internal only and hide them, whilst still generally allowing all imports without the dist/.

3) export specific, allowed parts of our API

{
  "exports": {
    "./": "./dist/index",
    "./ts-eslint": "./dist/ts-eslint/index",
    "./ast-utils": "./dist/ast-utils/index",
    // ...
  },
  "typesVersions": {
    "*": {
      "./": "./dist/index",
      "./ts-eslint": "./dist/ts-eslint/index.d.ts",
      "./ast-utils": "./dist/ast-utils/index.d.ts",
      // ...
    }
  }
}

This is the most restrictive thing we could do as we would ban deep imports except those that we choose. It would also allow us to remove the dist/ from imports.

[JoshuaKGoldberg]

+1, once in a while TypeScript auto-imports something from dist/ and it's annoying.

I'm in favor of as much restriction as possible. Keeping the API as minimal as possible means we get the most control over what consumers are able to use. We don't want them to feel comfortable importing miscellaneous dist/-y exports not meant to be part of the public API.

[bradzacher]

I'm more than happy to go for option 3 - it was my preferred option!
I just thought I'd lay out all the options for discussion.

[JoshuaKGoldberg]

cc @JamesHenry @Josh-Cena - I think this RFC is ready to be ratified, unless you'd like to continue the discussion here?

[JamesHenry]

Option 3 is good with me!

[Josh-Cena]

I like 3, although I don't have strong opinions in general.

[JoshuaKGoldberg]

Cool, looks like we're in agreement on choice 3 here. Thanks all! Converting this back into an issue, and marking as accepting PRs.

Edit: #6050