diff --git a/.github/DISCUSSION_TEMPLATE/rfcs.yml b/.github/DISCUSSION_TEMPLATE/rfcs.yml index 0e0b99abf05e..e9467392b44d 100644 --- a/.github/DISCUSSION_TEMPLATE/rfcs.yml +++ b/.github/DISCUSSION_TEMPLATE/rfcs.yml @@ -16,7 +16,7 @@ body: options: - label: I have [searched for related discussions](https://github.com/typescript-eslint/typescript-eslint/discussions) and [searched for related issues](https://github.com/typescript-eslint/typescript-eslint/issues) and found none that match my proposal. required: true - - label: I have [read the FAQ](https://typescript-eslint.io/docs/linting/troubleshooting) and my problem is not listed. + - label: I have [read the FAQ](https://typescript-eslint.io/linting/troubleshooting) and my problem is not listed. required: true id: required-checks type: checkboxes diff --git a/.github/ISSUE_TEMPLATE/01-bug-report-plugin.yaml b/.github/ISSUE_TEMPLATE/01-bug-report-plugin.yaml index af01af154c20..e35d0340a328 100644 --- a/.github/ISSUE_TEMPLATE/01-bug-report-plugin.yaml +++ b/.github/ISSUE_TEMPLATE/01-bug-report-plugin.yaml @@ -18,7 +18,7 @@ body: required: true - label: I have [searched for related issues](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+label%3Abug+label%3A%22package%3A+eslint-plugin%22) and found none that matched my issue. required: true - - label: I have [read the FAQ](https://typescript-eslint.io/docs/linting/troubleshooting) and my problem is not listed. + - label: I have [read the FAQ](https://typescript-eslint.io/linting/troubleshooting) and my problem is not listed. required: true - type: input id: playground-link diff --git a/.github/ISSUE_TEMPLATE/02-enhancement-rule-option.yaml b/.github/ISSUE_TEMPLATE/02-enhancement-rule-option.yaml index 8b857b50548f..ac65fbca8c1f 100644 --- a/.github/ISSUE_TEMPLATE/02-enhancement-rule-option.yaml +++ b/.github/ISSUE_TEMPLATE/02-enhancement-rule-option.yaml @@ -16,7 +16,7 @@ body: required: true - label: I have searched the [current rule list](https://typescript-eslint.io/rules/#supported-rules) and found no rules that match my proposal. required: true - - label: I have [read the FAQ](https://typescript-eslint.io/docs/linting/troubleshooting) and my problem is not listed. + - label: I have [read the FAQ](https://typescript-eslint.io/linting/troubleshooting) and my problem is not listed. required: true - type: checkboxes id: rule-fits-the-brief diff --git a/.github/ISSUE_TEMPLATE/03-enhancement-new-rule.yaml b/.github/ISSUE_TEMPLATE/03-enhancement-new-rule.yaml index 2e01a8d2c586..6bd61005bd6a 100644 --- a/.github/ISSUE_TEMPLATE/03-enhancement-new-rule.yaml +++ b/.github/ISSUE_TEMPLATE/03-enhancement-new-rule.yaml @@ -16,7 +16,7 @@ body: required: true - label: I have searched the [current rule list](https://typescript-eslint.io/rules/#supported-rules) and found no rules that match my proposal. required: true - - label: I have [read the FAQ](https://typescript-eslint.io/docs/linting/troubleshooting) and my problem is not listed. + - label: I have [read the FAQ](https://typescript-eslint.io/linting/troubleshooting) and my problem is not listed. required: true - type: checkboxes id: rule-fits-the-brief diff --git a/.github/ISSUE_TEMPLATE/04-enhancement-new-base-rule-extension.yaml b/.github/ISSUE_TEMPLATE/04-enhancement-new-base-rule-extension.yaml index 1c02ebe658a4..8c0ca8d8694c 100644 --- a/.github/ISSUE_TEMPLATE/04-enhancement-new-base-rule-extension.yaml +++ b/.github/ISSUE_TEMPLATE/04-enhancement-new-base-rule-extension.yaml @@ -23,7 +23,7 @@ body: required: true - label: I have searched the [current extension rule list](https://typescript-eslint.io/rules/#extension-rules) and found no rules that match my proposal. required: true - - label: I have [read the FAQ](https://typescript-eslint.io/docs/linting/troubleshooting) and my problem is not listed. + - label: I have [read the FAQ](https://typescript-eslint.io/linting/troubleshooting) and my problem is not listed. required: true - type: checkboxes id: rule-fits-the-brief diff --git a/.github/ISSUE_TEMPLATE/05-documentation-request.yml b/.github/ISSUE_TEMPLATE/05-documentation-request.yml index f21358bf8ed6..c140dc478d15 100644 --- a/.github/ISSUE_TEMPLATE/05-documentation-request.yml +++ b/.github/ISSUE_TEMPLATE/05-documentation-request.yml @@ -12,7 +12,7 @@ body: options: - label: I have looked for existing [open or closed documentation requests](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+label%3Adocumentation) that match my proposal. required: true - - label: I have [read the FAQ](https://typescript-eslint.io/docs/linting/troubleshooting) and my problem is not listed. + - label: I have [read the FAQ](https://typescript-eslint.io/linting/troubleshooting) and my problem is not listed. required: true - type: markdown attributes: diff --git a/.github/ISSUE_TEMPLATE/06-bug-report-other.yaml b/.github/ISSUE_TEMPLATE/06-bug-report-other.yaml index 6340c525b375..91f2cf35fd37 100644 --- a/.github/ISSUE_TEMPLATE/06-bug-report-other.yaml +++ b/.github/ISSUE_TEMPLATE/06-bug-report-other.yaml @@ -17,7 +17,7 @@ body: required: true - label: I have [searched for related issues](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+label%3Abug) and found none that matched my issue. required: true - - label: I have [read the FAQ](https://typescript-eslint.io/docs/linting/troubleshooting) and my problem is not listed. + - label: I have [read the FAQ](https://typescript-eslint.io/linting/troubleshooting) and my problem is not listed. required: true - type: markdown id: complexity-note diff --git a/.github/ISSUE_TEMPLATE/07-enhancement-other.yaml b/.github/ISSUE_TEMPLATE/07-enhancement-other.yaml index 686ee970a679..5f0ee6146c59 100644 --- a/.github/ISSUE_TEMPLATE/07-enhancement-other.yaml +++ b/.github/ISSUE_TEMPLATE/07-enhancement-other.yaml @@ -15,7 +15,7 @@ body: required: true - label: I have searched the [current rule list](https://typescript-eslint.io/rules/#supported-rules) and found no rules that match my proposal. required: true - - label: I have [read the FAQ](https://typescript-eslint.io/docs/linting/troubleshooting) and my problem is not listed. + - label: I have [read the FAQ](https://typescript-eslint.io/linting/troubleshooting) and my problem is not listed. required: true - type: dropdown id: package diff --git a/.github/ISSUE_TEMPLATE/08-bug-report-complex.yaml b/.github/ISSUE_TEMPLATE/08-bug-report-complex.yaml index 1292c539f27f..c0da8397fa8e 100644 --- a/.github/ISSUE_TEMPLATE/08-bug-report-complex.yaml +++ b/.github/ISSUE_TEMPLATE/08-bug-report-complex.yaml @@ -22,7 +22,7 @@ body: required: true - label: I have [searched for related issues](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+label%3Abug) and found none that matched my issue. required: true - - label: I have [read the FAQ](https://typescript-eslint.io/docs/linting/troubleshooting) and my problem is not listed. + - label: I have [read the FAQ](https://typescript-eslint.io/linting/troubleshooting) and my problem is not listed. required: true - type: textarea id: description diff --git a/.github/ISSUE_TEMPLATE/09-config-change.yaml b/.github/ISSUE_TEMPLATE/09-config-change.yaml index 6f31c3f96b0e..c5323335a93a 100644 --- a/.github/ISSUE_TEMPLATE/09-config-change.yaml +++ b/.github/ISSUE_TEMPLATE/09-config-change.yaml @@ -14,7 +14,7 @@ body: options: - label: I have [searched for related issues](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+label%3A%22preset+config+change%22+) and found none that match my proposal. required: true - - label: I have [read the FAQ](https://typescript-eslint.io/docs/linting/troubleshooting) and my problem is not listed. + - label: I have [read the FAQ](https://typescript-eslint.io/linting/troubleshooting) and my problem is not listed. required: true - type: textarea id: description diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 42e6c62d54c0..566c2f4fc8a6 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -2,7 +2,7 @@ blank_issues_enabled: false contact_links: - name: FAQ about: Please check out our FAQ before filing new issues - url: https://typescript-eslint.io/docs/linting/troubleshooting + url: https://typescript-eslint.io/linting/troubleshooting - name: Getting Started Guide about: If you're looking for help setting up check out our getting started guide - url: https://typescript-eslint.io/docs/ + url: https://typescript-eslint.io diff --git a/.github/replies.yml b/.github/replies.yml index 3edf22c3ca14..a10137241409 100644 --- a/.github/replies.yml +++ b/.github/replies.yml @@ -73,5 +73,5 @@ replies: The configurability also leads to huge fanout [making tests huge, and awful to maintain](https://github.com/typescript-eslint/typescript-eslint/blob/b814e635c1f34139c89e0176727480935dd45cac/packages/eslint-plugin/tests/rules/type-annotation-spacing.test.ts). \ It's for these reasons that [eslint has frozen all stylistic lint rule options, and will not accept any new ones](https://eslint.org/blog/2020/05/changes-to-rules-policies). - See also our [What About Formatting?](https://typescript-eslint.io/docs/linting/troubleshooting/formatting) docs. + See also our [What About Formatting?](https://typescript-eslint.io/linting/troubleshooting/formatting) docs. name: Use Prettier diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c08116cdc9c..7144d2f3bc38 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,110 +1,4 @@ # Contributing -Thank you for your interest in contributing to TypeScript ESLint! 💜 - -> Make sure you read our [Code of Conduct](./CODE_OF_CONDUCT.md) before contributing. - -## Raising Issues - -So you've got a bug report, documentation request, or feature suggestion? -Great! - -Do: - -- Make sure you're using the [latest version of our packages](https://github.com/typescript-eslint/typescript-eslint/releases) -- Search [all opened and closed issues](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+) to make sure your issue wouldn't be a duplicate -- Fill out the [appropriate issue template](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose) completely -- Provide as much information as you can - -### Questions and Support Requests - -We do not have the bandwidth to handle questions or support requests in the issue tracker. -You can instead: - -- Ask a question on [StackOverflow](https://stackoverflow.com/questions/tagged/typescript-eslint 'StackOverflow questions tagged with typescript-eslint') using the `typescript-eslint` tag -- Publicly tweet [@tseslint on Twitter](https://twitter.com/tseslint) - -> Note that requests to add documentation _are_ allowed, even encouraged! 📝 - -## Commenting - -Please do comment on any open issue if you have more information that would be useful. - -Don't: - -- Leave useless comments such as _"+1"_ or _"when's this getting fixed?"_ that only act as spam - - If you have nothing to add but enthusiasm and joy, add a reaction such as 👍 -- Bring up unrelated topics in existing issues: instead, file a new issue -- Comment on closed PRs: instead, [file a new issue](#raising-issues) -- Comment on commits directly, as those comments are not searchable: instead, file a new issue - -## Pull Requests - -> See [DEVELOPMENT.md](./DEVELOPMENT.md) for details on how to get started developing locally. - -Do: - -- Only send pull requests that resolve [open issues marked as `accepting prs`](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+is%3Aopen+label%3A%22accepting+prs%22) - - One exception: extremely minor documentation typos -- Fill out the pull request template in full -- Validate your changes per [Development > Validating Changes](./DEVELOPMENT.md#validating-changes) before un-[drafting your PR](https://github.blog/2019-02-14-introducing-draft-pull-requests) - -Don't: - -- Force push after opening a PR - - Reasoning: GitHub is not able to track changes across force pushes, which makes it take longer for us to perform incremental reviews -- Comment asking for updates - - Reasoning: Your PR hasn't been forgotten! The volunteer maintainers have limited time to work on the project, and they will get to it as soon as they are able. - -### Raising a PR - -Once your changes are ready, you can raise a PR! 🙌 -The title of your PR should match the following format: - -```text -(): -``` - -You can find more samples of good past PR titles in [recent commits to `main`](https://github.com/typescript-eslint/typescript-eslint/commits/main). - -```text -fix(scope-manager): correct handling for class static blocks -``` - -```text -docs: Fix links to getting started in README.md -``` - -Within the body of your PR, make sure you reference the issue that you have worked on, as well as pointing out anything of note you wish us to look at during our review. - -> We do not care about the number, or style of commits in your history, because we squash merge every PR into `main`. -> Feel free to commit in whatever style you feel comfortable with. - -#### type - -Must be one of the following: - -- `docs` - if you only change documentation, and not shipped code -- `feat` - for any new functionality additions -- `fix` - for any bug fixes that don't add new functionality -- `test` - if you only change tests, and not shipped code -- `chore` - anything else - -#### package - -The name of the package you have made changes within, (e.g. `eslint-plugin`, `parser`, `typescript-estree`). -If you make significant changes across multiple packages, you can omit this (e.g. -`feat: foo bar`). - -#### short description - -A succinct title for the PR. - -### Addressing Feedback and Beyond - -With your PR raised and the CI passing, your PR will [wait in the queue to be reviewed](https://github.com/typescript-eslint/typescript-eslint/pulls?q=is%3Apr+is%3Aopen+sort%3Acreated-asc+-label%3A%22breaking+change%22+-label%3A%22awaiting+response%22+-label%3A%221+approval%22+-label%3A%22DO+NOT+MERGE%22+status%3Asuccess). -We generally review PRs oldest to newest, unless we consider a newer PR higher priority (e.g. if it's a bug fix). - -Once we have reviewed your PR, we will provide any feedback that needs addressing. -If you feel a requested change is wrong, don't be afraid to discuss with us in the comments. -Once the feedback is addressed, and the PR is reviewed, we'll ensure the branch is up to date with `main`, and merge it for you. +See **https://typescript-eslint.io/contributing** for our contributing guidelines. +Thanks! 💖 diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index fd5c04937988..b86c2c91a998 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,69 +1,4 @@ # Development -Thank you for your interest in developing on TypeScript ESLint! ❤️‍🔥 - -> See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on our general contribution flows. - -## Setup - -After [forking the repo from GitHub](https://help.github.com/articles/fork-a-repo): - -```shell -git clone https://github.com//typescript-eslint -cd typescript-eslint -yarn -``` - -Postinstall scripts will then fully build your repository locally with (`yarn build`). -At this point, you're ready to develop! 🚀 - -## Builds - -You can run `yarn build` in any package or in the root to build the package(s). - -Keep in mind that packages generally depend on each other's built outputs, and you'll need to `yarn build` dependents for their consumers to receive any new local changes. -For example, if you make a change within `scope-manager` and want to use it in `eslint-plugin`, you'll need to `yarn build` either from the root or within `packages/scope-manager`. - -## Validating Changes - -The following checks are all run on pull requests automatically. -You can also perform them locally. - -### Formatting - -We use [Prettier](https://prettier.io) to auto-format code. -A Git pre-commit hook should apply it to all committed changes. -ALternately, you can run `yarn format` in any package or in the root. - -### Linting - -All code changes must pass ESLint. -You can run `yarn lint` in any package or in the root. - -### Proofreading - -Changes must pass two linters for documentation and naming, the commands for which may be run from the root: - -- `yarn check-spelling`: [CSpell](https://cspell.org), for all code -- `yarn lint-markdown`: [Markdownlint](https://github.com/DavidAnson/markdownlint), for Markdown documentation - -### Tests - -All code changes should ideally be unit tested if possible. -You can run `yarn test` in any package to run its tests. - -> [VS Code launch tasks](https://code.visualstudio.com/docs/editor/tasks) tasks are provided that allow [visual debugging](https://code.visualstudio.com/docs/editor/debugging) tests - -#### Code Coverage - -We aim for 100% code coverage in all PRs when possible, except in the `website/` package. -Coverage reports are be generated locally whenever `yarn test` is run. - -The `codecov` bot should also comment on your PR with the percentage, as well as links to the line-by-line coverage of each file touched by your PR. - -### Type Checking - -All code should pass TypeScript type checking. -You can run `yarn typecheck` in any package or in the root to run `tsc`. - -> Run `yarn typecheck -w` to start `tsc` in watch mode. +See **https://typescript-eslint.io/contributing/development** for our development instructions. +Thanks! 💖 diff --git a/README.md b/README.md index 93bee2f66dc4..1354292a6be7 100644 --- a/README.md +++ b/README.md @@ -20,88 +20,9 @@ 👆

-## Packages included in this project - -See https://typescript-eslint.io/docs/development/architecture/packages for more details. - -- [`@typescript-eslint/eslint-plugin`](./packages/eslint-plugin) -- [`@typescript-eslint/parser`](./packages/parser) -- [`@typescript-eslint/eslint-plugin-tslint`](./packages/eslint-plugin-tslint) -- [`@typescript-eslint/utils`](./packages/utils) -- [`@typescript-eslint/typescript-estree`](./packages/typescript-estree) -- [`@typescript-eslint/scope-manager`](./packages/scope-manager) - -## Versioning - -All of the packages are published with the same version number to make it easier to coordinate both releases and installations. - -We publish a canary release on every successful merge to `main`, so **you never need to wait for a new stable version to make use of any updates**. - -Additionally, we promote to the `latest` tag on NPM once per week, **on Mondays at 1 pm Eastern**. - -The latest version under the `latest` tag is: - -NPM Version - -The latest version under the `canary` tag **(latest commit to `main`)** is: - -NPM Version - -(Note: The only exception to the automated publishes described above is when we are in the final phases of creating the next major version of the libraries - e.g. going from `1.x.x` to `2.x.x`. During these periods, we manually publish `canary` releases until we are happy with the release and promote it to `latest`.) - -### Supported TypeScript Version - -**The version range of TypeScript currently supported by this parser is `>=3.3.1 <5.0.0`.** - -These versions are what we test against. - -We will always endeavor to support the latest stable version of TypeScript. -Sometimes, but not always, changes in TypeScript will not require breaking changes in this project, and so we are able to support more than one version of TypeScript. -In some cases, we may even be able to support additional pre-releases (i.e. betas and release candidates) of TypeScript, but only if doing so does not require us to compromise on support for the latest stable version. - -Note that our packages have an open `peerDependency` requirement in order to allow for experimentation on newer/beta versions of TypeScript. - -If you use a non-supported version of TypeScript, the parser will log a warning to the console. -If you want to disable this warning, you can configure this in your `parserOptions`. See: [`@typescript-eslint/parser`](./packages/parser/) and [`@typescript-eslint/typescript-estree`](./packages/typescript-estree/). - -**Please ensure that you are using a supported version before submitting any issues/bug reports.** - -### Supported ESLint Version - -See the value of `eslint` declared in `@typescript-eslint/eslint-plugin`'s [package.json](./packages/eslint-plugin/package.json). - -### Supported Node Version - -This project makes an effort to support Active LTS and Maintenance LTS release statuses of Node according to [Node's release document](https://nodejs.org/en/about/releases). -Support for specific Current status releases are considered periodically. - -## License - -TypeScript ESLint inherits from the original TypeScript ESLint Parser license, as the majority of the work began there. It is licensed under a permissive BSD 2-clause license. - -## How can I help? - -I'm so glad you asked! - -Although typescript-eslint's packages are already downloaded millions of times per month and power high profile projects across our industry, this is a 100% community-driven project. -From the second you install one of the packages from this monorepo, you are a part of that community. - -**See an issue?** -Report it in as much detail as possible, ideally with a clear and minimal reproduction. - -If you have the time and the inclination, you can even take it a step further and submit a PR to improve the project. - -There are also financial ways to contribute, please see [Financial Contributors](#Financial-Contributors) for more details. - -All positive contributions are welcome here! - -> **[See the contributing guide here](./CONTRIBUTING.md)**. - -Please be respectful and mindful of how many hours of unpaid work go into typescript-eslint. - ## Code Contributors -This project exists thanks to every one of the awesome people who contribute code and documentation: +This project exists thanks to the awesome people who contribute code and documentation: Gallery of all contributors' profile photos @@ -114,3 +35,7 @@ In addition to submitting code and documentation updates, you can help us sustai Deploys by Netlify + +## License + +TypeScript ESLint inherits from the original TypeScript ESLint Parser license, as the majority of the work began there. It is licensed under a permissive BSD 2-clause license. diff --git a/docs/Architecture.md b/docs/Architecture.md new file mode 100644 index 000000000000..ee224c1e90ae --- /dev/null +++ b/docs/Architecture.md @@ -0,0 +1,17 @@ +--- +id: architecture +title: Architecture +--- + +The `@typescript-eslint/*` packages are built from a monorepo located at https://github.com/typescript-eslint/typescript-eslint. +The monorepo is built with [Lerna](https://lerna.js.org) and [Nx](https://nx.dev). + +Each page in this section corresponds to a package we intentionally expose to users. +They are: + +- [`@typescript-eslint/eslint-plugin`](./architecture/ESLint_Plugin.mdx): An ESLint plugin which provides lint rules for TypeScript codebases. +- [`@typescript-eslint/eslint-plugin-tslint`](./architecture/ESLint_Plugin_TSLint.mdx): ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint. +- [`@typescript-eslint/parser`](./architecture/Parser.mdx): An ESLint parser which allows for ESLint to lint TypeScript source code. +- [`@typescript-eslint/scope-manager`](./architecture/Scope_Manager.mdx): A fork of [`eslint-scope`](https://github.com/eslint/eslint-scope), enhanced to support TypeScript functionality. +- [`@typescript-eslint/typescript-estree`](./architecture/TypeScript-ESTree.mdx): The underlying code used by [`@typescript-eslint/parser`](./architecture/Parser.mdx) that converts TypeScript source code into an ESTree-compatible form. +- [`@typescript-eslint/utils`](./architecture/Utils.mdx): Utilities for working with TypeScript + ESLint together. diff --git a/docs/Contributing.mdx b/docs/Contributing.mdx new file mode 100644 index 000000000000..35846cdaaae0 --- /dev/null +++ b/docs/Contributing.mdx @@ -0,0 +1,15 @@ +--- +id: contributing +title: Contributing +--- + +Thank you for your interest in contributing to TypeScript ESLint! 💜 + +Although typescript-eslint's packages are already downloaded millions of times per month and power high profile projects across our industry, this is a 100% community-driven project. +From the second you install one of the packages from this monorepo, you are a part of that community. +So, from the bottom of our hearts, _thank you_ 💕. + +## Getting Started + +Please read our [Code of Conduct](https://github.com/typescript-eslint/typescript-eslint/blob/main/CODE_OF_CONDUCT.md) first. +If you're new to open source, you may also find the [How to Contribute to Open Source](https://opensource.guide/how-to-contribute) guide from https://opensource.guide useful. diff --git a/docs/development/CUSTOM_RULES.md b/docs/Custom_Rules.md similarity index 97% rename from docs/development/CUSTOM_RULES.md rename to docs/Custom_Rules.md index 183573b81093..0590398b8188 100644 --- a/docs/development/CUSTOM_RULES.md +++ b/docs/Custom_Rules.md @@ -5,6 +5,7 @@ title: Custom Rules --- :::important +This page describes how to write your own custom ESLint rules using typescript-eslint. You should be familiar with [ESLint's developer guide](https://eslint.org/docs/developer-guide) and [ASTs](https://typescript-eslint.io/blog/asts-and-typescript-eslint) before writing custom rules. ::: @@ -17,7 +18,7 @@ The main three changes to custom rules writing are: ## Utils Package -The `@typescript-eslint/utils` package acts as a replacement package for `eslint` that exports all the same objects and types, but with typescript-eslint support. +The [`@typescript-eslint/utils`](./architecture/Utils.mdx) package acts as a replacement package for `eslint` that exports all the same objects and types, but with typescript-eslint support. It also exports common utility functions and constants most custom typescript-eslint rules tend to use. :::caution diff --git a/docs/README.md b/docs/Getting_Started.md similarity index 82% rename from docs/README.md rename to docs/Getting_Started.md index 0cc743de8d8a..91c978322f48 100644 --- a/docs/README.md +++ b/docs/Getting_Started.md @@ -1,7 +1,6 @@ --- id: getting-started title: Getting Started -slug: / --- ## Quickstart @@ -64,16 +63,16 @@ ESLint will lint all TypeScript compatible files within the current folder, and ### Configuration Values -- `parser: '@typescript-eslint/parser'` tells ESLint to use the [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser) package you installed to parse your source files. +- `parser: '@typescript-eslint/parser'` tells ESLint to use the [`@typescript-eslint/parser`](./architecture/Parser.mdx) package you installed to parse your source files. - This is required, or else ESLint will throw errors as it tries to parse TypeScript code as if it were regular JavaScript. -- `plugins: ['@typescript-eslint']` tells ESLint to load the [`@typescript-eslint/eslint-plugin`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin) package as a plugin. +- `plugins: ['@typescript-eslint']` tells ESLint to load the [`@typescript-eslint/eslint-plugin`](./architecture/ESLint_Plugin.mdx) package as a plugin. - This allows you to use typescript-eslint's rules within your codebase. - `extends: [ ... ]` tells ESLint that your config extends the given configurations. - `eslint:recommended` is ESLint's inbuilt "recommended" config - it turns on a small, sensible set of rules which lint for well-known best-practices. - - `plugin:@typescript-eslint/recommended` is our "recommended" config - it's just like `eslint:recommended`, except it only turns on rules from our TypeScript-specific plugin. + - `plugin:@typescript-eslint/recommended` is our "recommended" config - it's similar to `eslint:recommended`, except it turns on TypeScript-specific rules from our plugin. ## Next Steps -We provide a plethora of powerful rules that utilize the power of TypeScript's type information. [Visit the next page for a setup guide](./linting/TYPED_LINTING.md 'Visit the next page for a typed rules setup guide'). +We provide a plethora of powerful rules that utilize the power of TypeScript's type information. [Visit the next page for a setup guide](./linting/Typed_Linting.md 'Visit the next page for a typed rules setup guide'). -If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](./linting/TROUBLESHOOTING.md). +If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](./linting/Troubleshooting.md). diff --git a/docs/architecture/ESLint_Plugin.mdx b/docs/architecture/ESLint_Plugin.mdx new file mode 100644 index 000000000000..eca601415550 --- /dev/null +++ b/docs/architecture/ESLint_Plugin.mdx @@ -0,0 +1,22 @@ +--- +id: eslint-plugin +sidebar_label: eslint-plugin +--- + +# `@typescript-eslint/eslint-plugin` + +> The TypeScript plugin for ESLint. ✨ + +:::info +See [Getting Started](../Getting_Started.md) for documentation on how to lint your TypeScript code with ESLint. +::: + +`@typescript-eslint/eslint-plugin` is an ESLint plugin used to load in custom rules and rule configurations lists from typescript-eslint. +Those rules rely on [`@typescript-eslint/parser`](./Parser.mdx) to parse TypeScript code into ESLint-compatible nodes, as well as provide backing TypeScript programs. + +## Exports + +| Name | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `configs` | Object mapping string names of configs to extendable [ESLint config settings](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#extending-configuration-files). | +| `rules` | Object mapping string names of rules to the [rule objects](https://eslint.org/docs/latest/developer-guide/working-with-rules). | diff --git a/docs/architecture/ESLint_Plugin_TSLint.mdx b/docs/architecture/ESLint_Plugin_TSLint.mdx new file mode 100644 index 000000000000..582d93aab8ef --- /dev/null +++ b/docs/architecture/ESLint_Plugin_TSLint.mdx @@ -0,0 +1,51 @@ +--- +id: eslint-plugin-tslint +sidebar_label: eslint-plugin-tslint +--- + +# `@typescript-eslint/eslint-plugin-tslint` + +> ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint. ✨ + +:::caution +Per [What About TSLint?](../linting/troubleshooting/TSLint.md), we highly recommend migrating off TSLint. +See [Getting Started](../Getting_Started.md) for documentation on how to lint your TypeScript code with ESLint. +::: + +## Installation + +```sh +yarn add -D @typescript-eslint/eslint-plugin-tslint +``` + +## Usage + +Configure in your ESLint config file: + +```js +{ + "plugins": [ + "@typescript-eslint/tslint" + ], + "parserOptions": { + "project": "tsconfig.json", + }, + "rules": { + "@typescript-eslint/tslint/config": ["warn", { + "lintFile": "", // path to tslint.json of your project + "rules": { + // tslint rules (will be used if `lintFile` is not specified) + }, + "rulesDirectory": [ + // array of paths to directories with rules, e.g. 'node_modules/tslint/lib/rules' (will be used if `lintFile` is not specified) + ] + }], + } +} +``` + +**Note:** The ability to automatically fix problems with `--fix` is unavailable for TSLint rules loaded with this plugin. + +## Rules + +This plugin contains only a single rule: `@typescript-eslint/tslint/config`. diff --git a/docs/architecture/Parser.mdx b/docs/architecture/Parser.mdx new file mode 100644 index 000000000000..185d67d35808 --- /dev/null +++ b/docs/architecture/Parser.mdx @@ -0,0 +1,260 @@ +--- +id: parser +sidebar_label: parser +--- + +# `@typescript-eslint/parser` + +> An [ESLint parser](https://eslint.org/docs/user-guide/configuring/plugins#specifying-parser) used to parse TypeScript code into ESLint-compatible nodes, as well as provide backing TypeScript programs. ✨ + +This is necessary because TypeScript produces a different, incompatible AST format to the one that ESLint requires to work. +For example, this is not valid JavaScript code because it contains the `: number` type annotation: + +```ts +let x: number = 1; +``` + +ESLint's native Espree parser would raise an error attempting to parse it. + +Additionally, because TypeScript is developed separately and with different goals from ESLint, ESTree, and Espree, its AST also represents nodes differently in many cases. +TS's AST is optimized for its use case of parsing incomplete code and typechecking. +ESTree is unoptimized and intended for "general purpose" use-cases of traversing the AST. + +:::tip +You can select `@typescript-eslint/parser` on the [TypeScript ESLint playground](https://typescript-eslint.io/play#showAST=es)'s left sidebar under _Options_ > _AST Explorer_ by selecting _ESTree_. +::: + +## Configuration + +The following additional configuration options are available by specifying them in [`parserOptions`](https://eslint.org/docs/user-guide/configuring/language-options#specifying-parser-options) in your ESLint configuration file. + +```ts +interface ParserOptions { + ecmaFeatures?: { + jsx?: boolean; + globalReturn?: boolean; + }; + ecmaVersion?: number | 'latest'; + emitDecoratorMetadata?: boolean; + extraFileExtensions?: string[]; + jsxFragmentName?: string | null; + jsxPragma?: string | null; + lib?: string[]; + moduleResolver?: string; + program?: import('typescript').Program; + project?: string | string[]; + projectFolderIgnoreList?: string[]; + tsconfigRootDir?: string; + warnOnUnsupportedTypeScriptVersion?: boolean; +} +``` + +### `ecmaFeatures` + +Optional additional options to describe how to parse the raw syntax. + +#### `jsx` + +> Default `false`. + +Enable parsing JSX when `true`. +More details can be found in the [TypeScript handbook's JSX docs](https://www.typescriptlang.org/docs/handbook/jsx.html). + +**NOTE:** this setting does not affect known file types (`.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`, `.json`) because the TypeScript compiler has its own internal handling for known file extensions. + + + +The exact behavior is as follows: + +- `.js`, `.mjs`, `.cjs`, `.jsx`, `.tsx` files are always parsed as if this is `true`. +- `.ts`, `.mts`, `.cts` files are always parsed as if this is `false`. +- For "unknown" extensions (`.md`, `.vue`): + - If `parserOptions.project` is _not_ provided: + - The setting will be respected. + - If `parserOptions.project` is provided (i.e. you are using rules with type information): + - **always parsed as if this is `false`** + +#### `globalReturn` + +> Default `false`. + +This options allows you to tell the parser if you want to allow global `return` statements in your codebase. + +### `ecmaVersion` + +> Default `2018`. + +Accepts any valid ECMAScript version number or `'latest'`: + +- A version: es3, es5, es6, es7, es8, es9, es10, es11, es12, es13, ..., or +- A year: es2015, es2016, es2017, es2018, es2019, es2020, es2021, es2022, ..., or +- `'latest'` + +When it's a version or a year, the value **must** be a number - so do not include the `es` prefix. + +Specifies the version of ECMAScript syntax you want to use. This is used by the parser to determine how to perform scope analysis, and it affects the default + +### `emitDecoratorMetadata` + +> Default `undefined`. + +This option allow you to tell parser to act as if `emitDecoratorMetadata: true` is set in `tsconfig.json`, but without [type-aware linting](https://typescript-eslint.io/linting/typed-linting). In other words, you don't have to specify `parserOptions.project` in this case, making the linting process faster. + +### `extraFileExtensions` + +> Default `undefined`. + +This option allows you to provide one or more additional file extensions which should be considered in the TypeScript Program compilation. +The default extensions are `['.js', '.mjs', '.cjs', '.jsx', '.ts', '.mts', '.cts', '.tsx']`. +Add extensions starting with `.`, followed by the file extension. E.g. for a `.vue` file use `"extraFileExtensions": [".vue"]`. + +### `jsxFragmentName` + +> Default `null` + +The identifier that's used for JSX fragment elements (after transpilation). +If `null`, assumes transpilation will always use a member of the configured `jsxPragma`. +This should not be a member expression - just the root identifier (i.e. use `"h"` instead of `"h.Fragment"`). + +If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler. + +### `jsxPragma` + +> Default `'React'` + +The identifier that's used for JSX Elements creation (after transpilation). +If you're using a library other than React (like `preact`), then you should change this value. If you are using the [new JSX transform](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) you can set this to `null`. + +This should not be a member expression - just the root identifier (i.e. use `"React"` instead of `"React.createElement"`). + +If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler. + +### `lib` + +> Default `['es2018']` + +For valid options, see the [TypeScript compiler options](https://www.typescriptlang.org/tsconfig#lib). + +Specifies the TypeScript `lib`s that are available. This is used by the scope analyser to ensure there are global variables declared for the types exposed by TypeScript. + +If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler. + +### `moduleResolver` + +> Default `undefined`. + +This option allows you to provide a custom module resolution. The value should point to a JS file that default exports (`export default`, or `module.exports =`, or `export =`) a file with the following interface: + +```ts +interface ModuleResolver { + version: 1; + resolveModuleNames( + moduleNames: string[], + containingFile: string, + reusedNames: string[] | undefined, + redirectedReference: ts.ResolvedProjectReference | undefined, + options: ts.CompilerOptions, + ): (ts.ResolvedModule | undefined)[]; +} +``` + +### `program` + +> Default `undefined`. + +This option allows you to programmatically provide an instance of a TypeScript Program object that will provide type information to rules. +This will override any programs that would have been computed from `parserOptions.project` or `parserOptions.createDefaultProgram`. +All linted files must be part of the provided program(s). + +[Refer to the TypeScript Wiki for an example on how to write the `resolveModuleNames` function](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API#customizing-module-resolution). + +### `project` + +> Default `undefined`. + +This option allows you to provide a path to your project's `tsconfig.json`. **This setting is required if you want to use rules which require type information**. Relative paths are interpreted relative to the current working directory if `tsconfigRootDir` is not set. If you intend on running ESLint from directories other than the project root, you should consider using `tsconfigRootDir`. + +- Accepted values: + + ```js + // path + project: './tsconfig.json'; + + // glob pattern + project: './packages/**/tsconfig.json'; + + // array of paths and/or glob patterns + project: ['./packages/**/tsconfig.json', './separate-package/tsconfig.json']; + ``` + +- If you use project references, TypeScript will not automatically use project references to resolve files. This means that you will have to add each referenced tsconfig to the `project` field either separately, or via a glob. + +- Note that using wide globs `**` in your `parserOptions.project` may cause performance implications. Instead of globs that use `**` to recursively check all folders, prefer paths that use a single `*` at a time. For more info see [#2611](https://github.com/typescript-eslint/typescript-eslint/issues/2611). + +- TypeScript will ignore files with duplicate filenames in the same folder (for example, `src/file.ts` and `src/file.js`). TypeScript purposely ignore all but one of the files, only keeping the one file with the highest priority extension (the extension priority order (from highest to lowest) is `.ts`, `.tsx`, `.d.ts`, `.js`, `.jsx`). For more info see #955. + +- Note that if this setting is specified and `createDefaultProgram` is not, you must only lint files that are included in the projects as defined by the provided `tsconfig.json` files. If your existing configuration does not include all of the files you would like to lint, you can create a separate `tsconfig.eslint.json` as follows: + + ```jsonc + { + // extend your base config so you don't have to redefine your compilerOptions + "extends": "./tsconfig.json", + "include": [ + "src/**/*.ts", + "test/**/*.ts", + "typings/**/*.ts", + // etc + + // if you have a mixed JS/TS codebase, don't forget to include your JS files + "src/**/*.js" + ] + } + ``` + +### `projectFolderIgnoreList` + +> Default `["**/node_modules/**"]`. + +This option allows you to ignore folders from being included in your provided list of `project`s. +This is useful if you have configured glob patterns, but want to make sure you ignore certain folders. + +It accepts an array of globs to exclude from the `project` globs. + +For example, by default it will ensure that a glob like `./**/tsconfig.json` will not match any `tsconfig`s within your `node_modules` folder (some npm packages do not exclude their source files from their published packages). + +### `tsconfigRootDir` + +> Default `undefined`. + +This option allows you to provide the root directory for relative tsconfig paths specified in the `project` option above. + +### `warnOnUnsupportedTypeScriptVersion` + +> Default `true`. + +This option allows you to toggle the warning that the parser will give you if you use a version of TypeScript which is not explicitly supported + +## Utilities + +### `createProgram(configFile, projectDirectory)` + +This serves as a utility method for users of the `parserOptions.programs` feature to create a TypeScript program instance from a config file. + +```ts +declare function createProgram( + configFile: string, + projectDirectory?: string, +): import('typescript').Program; +``` + +Example usage: + +```js title=".eslintrc.js" +const parser = require('@typescript-eslint/parser'); + +module.exports = { + parserOptions: { + programs: [parser.createProgram('tsconfig.json')], + }, +}; +``` diff --git a/docs/architecture/Scope_Manager.mdx b/docs/architecture/Scope_Manager.mdx new file mode 100644 index 000000000000..af7bd6e27c5c --- /dev/null +++ b/docs/architecture/Scope_Manager.mdx @@ -0,0 +1,104 @@ +--- +id: scope-manager +sidebar_label: scope-manager +--- + +# `@typescript-eslint/scope-manager` + +> A fork of [`eslint-scope`](https://github.com/eslint/eslint-scope), enhanced to support TypeScript functionality. ✨ + +A "scope analyser" traverses an AST and builds a model of how variables (and in our case, types) are defined and consumed by the source code. +This form of static analysis allows you to understand and trace variables throughout the program, allowing you to access powerful information about a program without needing to drop into the much, much heavier type information. + +## API + +### `analyze(tree, options)` + +Analyses a given AST and returns the resulting `ScopeManager`. + +```ts +interface AnalyzeOptions { + /** + * Known visitor keys. + */ + childVisitorKeys?: Record | null; + + /** + * Which ECMAScript version is considered. + * Defaults to `2018`. + * `'latest'` is converted to 1e8 at parser. + */ + ecmaVersion?: EcmaVersion | 1e8; + + /** + * Whether the whole script is executed under node.js environment. + * When enabled, the scope manager adds a function scope immediately following the global scope. + * Defaults to `false`. + */ + globalReturn?: boolean; + + /** + * Implied strict mode (if ecmaVersion >= 5). + * Defaults to `false`. + */ + impliedStrict?: boolean; + + /** + * The identifier that's used for JSX Element creation (after transpilation). + * This should not be a member expression - just the root identifier (i.e. use "React" instead of "React.createElement"). + * Defaults to `"React"`. + */ + jsxPragma?: string; + + /** + * The identifier that's used for JSX fragment elements (after transpilation). + * If `null`, assumes transpilation will always use a member on `jsxFactory` (i.e. React.Fragment). + * This should not be a member expression - just the root identifier (i.e. use "h" instead of "h.Fragment"). + * Defaults to `null`. + */ + jsxFragmentName?: string | null; + + /** + * The lib used by the project. + * This automatically defines a type variable for any types provided by the configured TS libs. + * For more information, see https://www.typescriptlang.org/tsconfig#lib + * + * Defaults to the lib for the provided `ecmaVersion`. + */ + lib?: Lib[]; + + /** + * The source type of the script. + */ + sourceType?: 'script' | 'module'; + + /** + * Emit design-type metadata for decorated declarations in source. + * Defaults to `false`. + */ + emitDecoratorMetadata?: boolean; +} +``` + +Example usage: + +```ts +import { analyze } from '@typescript-eslint/scope-manager'; +import { parse } from '@typescript-eslint/typescript-estree'; + +const code = `const hello: string = 'world';`; +const ast = parse(code, { + // note that scope-manager requires ranges on the AST + range: true, +}); +const scope = analyze(ast, { + ecmaVersion: 2020, + sourceType: 'module', +}); +``` + +## References + +- [You can view the original BSD 2 license for the code here](https://github.com/eslint/eslint-scope/blob/dbddf14d5771b21b5da704213e4508c660ca1c64/LICENSE) +- https://eslint.org/docs/developer-guide/scope-manager-interface +- https://github.com/eslint/eslint-scope diff --git a/docs/architecture/TypeScript-ESTree.mdx b/docs/architecture/TypeScript-ESTree.mdx new file mode 100644 index 000000000000..2ef3b91e20d8 --- /dev/null +++ b/docs/architecture/TypeScript-ESTree.mdx @@ -0,0 +1,352 @@ +--- +id: typescript-estree +sidebar_label: typescript-estree +--- + +# `@typescript-eslint/typescript-estree` + +> The underlying code used by [`@typescript-eslint/parser`](./Parser.mdx) that converts TypeScript source code into an ESTree-compatible form. ✨ + +This parser is designed to be generic and robust. +It can be used to power any use-case which requires taking TypeScript source code and producing an ESTree-compatible AST. + +It is most known for use within these hyper-popular open-source projects to power their TypeScript support: + +- [ESLint](https://eslint.org), the pluggable linting utility for JavaScript and JSX +- [Prettier](https://prettier.io), an opinionated code formatter + +It works by: + +1. Invoking the TypeScript compiler on the given source code in order to + produce a TypeScript AST +2. Converting that TypeScript AST into an ESTree AST + +## Installation + +TODO: standardize installation docs + +## API + +### Parsing + +#### `parse(code, options)` + +Parses the given string of code with the options provided and returns an ESTree-compatible AST. + +```ts +interface ParseOptions { + /** + * create a top-level comments array containing all comments + */ + comment?: boolean; + + /** + * An array of modules to turn explicit debugging on for. + * - 'typescript-eslint' is the same as setting the env var `DEBUG=typescript-eslint:*` + * - 'eslint' is the same as setting the env var `DEBUG=eslint:*` + * - 'typescript' is the same as setting `extendedDiagnostics: true` in your tsconfig compilerOptions + * + * For convenience, also supports a boolean: + * - true === ['typescript-eslint'] + * - false === [] + */ + debugLevel?: boolean | ('typescript-eslint' | 'eslint' | 'typescript')[]; + + /** + * Cause the parser to error if it encounters an unknown AST node type (useful for testing). + * This case only usually occurs when TypeScript releases new features. + */ + errorOnUnknownASTType?: boolean; + + /** + * Absolute (or relative to `cwd`) path to the file being parsed. + */ + filePath?: string; + + /** + * Enable parsing of JSX. + * For more details, see https://www.typescriptlang.org/docs/handbook/jsx.html + * + * NOTE: this setting does not effect known file types (.js, .cjs, .mjs, .jsx, .ts, .mts, .cts, .tsx, .json) because the + * TypeScript compiler has its own internal handling for known file extensions. + * + * For the exact behavior, see https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser#parseroptionsecmafeaturesjsx + */ + jsx?: boolean; + + /** + * Controls whether the `loc` information to each node. + * The `loc` property is an object which contains the exact line/column the node starts/ends on. + * This is similar to the `range` property, except it is line/column relative. + */ + loc?: boolean; + + /* + * Allows overriding of function used for logging. + * When value is `false`, no logging will occur. + * When value is not provided, `console.log()` will be used. + */ + loggerFn?: Function | false; + + /** + * Controls whether the `range` property is included on AST nodes. + * The `range` property is a [number, number] which indicates the start/end index of the node in the file contents. + * This is similar to the `loc` property, except this is the absolute index. + */ + range?: boolean; + + /** + * Set to true to create a top-level array containing all tokens from the file. + */ + tokens?: boolean; +} + +const PARSE_DEFAULT_OPTIONS: ParseOptions = { + comment: false, + errorOnUnknownASTType: false, + filePath: 'estree.ts', // or 'estree.tsx', if you pass jsx: true + jsx: false, + loc: false, + loggerFn: undefined, + range: false, + tokens: false, +}; + +declare function parse( + code: string, + options: ParseOptions = PARSE_DEFAULT_OPTIONS, +): TSESTree.Program; +``` + +Example usage: + +```js +import { parse } from '@typescript-eslint/typescript-estree'; + +const code = `const hello: string = 'world';`; +const ast = parse(code, { + loc: true, + range: true, +}); +``` + +#### `parseAndGenerateServices(code, options)` + +Parses the given string of code with the options provided and returns an ESTree-compatible AST. Accepts additional options which can be used to generate type information along with the AST. + +```ts +interface ParseAndGenerateServicesOptions extends ParseOptions { + /** + * Causes the parser to error if the TypeScript compiler returns any unexpected syntax/semantic errors. + */ + errorOnTypeScriptSyntacticAndSemanticIssues?: boolean; + + /** + * ***EXPERIMENTAL FLAG*** - Use this at your own risk. + * + * Causes TS to use the source files for referenced projects instead of the compiled .d.ts files. + * This feature is not yet optimized, and is likely to cause OOMs for medium to large projects. + * + * This flag REQUIRES at least TS v3.9, otherwise it does nothing. + * + * See: https://github.com/typescript-eslint/typescript-eslint/issues/2094 + */ + EXPERIMENTAL_useSourceOfProjectReferenceRedirect?: boolean; + + /** + * When `project` is provided, this controls the non-standard file extensions which will be parsed. + * It accepts an array of file extensions, each preceded by a `.`. + */ + extraFileExtensions?: string[]; + + /** + * Absolute (or relative to `tsconfigRootDir`) path to the file being parsed. + * When `project` is provided, this is required, as it is used to fetch the file from the TypeScript compiler's cache. + */ + filePath?: string; + + /** + * Allows the user to control whether or not two-way AST node maps are preserved + * during the AST conversion process. + * + * By default: the AST node maps are NOT preserved, unless `project` has been specified, + * in which case the maps are made available on the returned `parserServices`. + * + * NOTE: If `preserveNodeMaps` is explicitly set by the user, it will be respected, + * regardless of whether or not `project` is in use. + */ + preserveNodeMaps?: boolean; + + /** + * Absolute (or relative to `tsconfigRootDir`) paths to the tsconfig(s). + * If this is provided, type information will be returned. + */ + project?: string | string[]; + + /** + * If you provide a glob (or globs) to the project option, you can use this option to ignore certain folders from + * being matched by the globs. + * This accepts an array of globs to ignore. + * + * By default, this is set to ["/node_modules/"] + */ + projectFolderIgnoreList?: string[]; + + /** + * The absolute path to the root directory for all provided `project`s. + */ + tsconfigRootDir?: string; + + /** + * An array of one or more instances of TypeScript Program objects to be used for type information. + * This overrides any program or programs that would have been computed from the `project` option. + * All linted files must be part of the provided program(s). + */ + programs?: Program[]; + + /** + *************************************************************************************** + * IT IS RECOMMENDED THAT YOU DO NOT USE THIS OPTION, AS IT CAUSES PERFORMANCE ISSUES. * + *************************************************************************************** + * + * When passed with `project`, this allows the parser to create a catch-all, default program. + * This means that if the parser encounters a file not included in any of the provided `project`s, + * it will not error, but will instead parse the file and its dependencies in a new program. + */ + createDefaultProgram?: boolean; + + /** + * ESLint (and therefore typescript-eslint) is used in both "single run"/one-time contexts, + * such as an ESLint CLI invocation, and long-running sessions (such as continuous feedback + * on a file in an IDE). + * + * When typescript-eslint handles TypeScript Program management behind the scenes, this distinction + * is important because there is significant overhead to managing the so called Watch Programs + * needed for the long-running use-case. + * + * When allowAutomaticSingleRunInference is enabled, we will use common heuristics to infer + * whether or not ESLint is being used as part of a single run. + */ + allowAutomaticSingleRunInference?: boolean; + + /** + * Path to a file exporting a custom ModuleResolver. + */ + moduleResolver?: string; +} + +interface ParserServices { + program: ts.Program; + esTreeNodeToTSNodeMap: WeakMap; + tsNodeToESTreeNodeMap: WeakMap; + hasFullTypeInformation: boolean; +} + +interface ParseAndGenerateServicesResult { + ast: TSESTree.Program; + services: ParserServices; +} + +const PARSE_AND_GENERATE_SERVICES_DEFAULT_OPTIONS: ParseOptions = { + ...PARSE_DEFAULT_OPTIONS, + errorOnTypeScriptSyntacticAndSemanticIssues: false, + extraFileExtensions: [], + preserveNodeMaps: false, // or true, if you do not set this, but pass `project` + project: undefined, + projectFolderIgnoreList: ['/node_modules/'], + tsconfigRootDir: process.cwd(), +}; + +declare function parseAndGenerateServices( + code: string, + options: ParseOptions = PARSE_DEFAULT_OPTIONS, +): ParseAndGenerateServicesResult; +``` + +Example usage: + +```js +import { parseAndGenerateServices } from '@typescript-eslint/typescript-estree'; + +const code = `const hello: string = 'world';`; +const { ast, services } = parseAndGenerateServices(code, { + filePath: '/some/path/to/file/foo.ts', + loc: true, + project: './tsconfig.json', + range: true, +}); +``` + +#### `parseWithNodeMaps(code, options)` + +Parses the given string of code with the options provided and returns both the ESTree-compatible AST as well as the node maps. +This allows you to work with both ASTs without the overhead of types that may come with `parseAndGenerateServices`. + +```ts +interface ParseWithNodeMapsResult { + ast: TSESTree.Program; + esTreeNodeToTSNodeMap: ParserServices['esTreeNodeToTSNodeMap']; + tsNodeToESTreeNodeMap: ParserServices['tsNodeToESTreeNodeMap']; +} + +declare function parseWithNodeMaps( + code: string, + options: ParseOptions = PARSE_DEFAULT_OPTIONS, +): ParseWithNodeMapsResult; +``` + +Example usage: + +```js +import { parseWithNodeMaps } from '@typescript-eslint/typescript-estree'; + +const code = `const hello: string = 'world';`; +const { ast, esTreeNodeToTSNodeMap, tsNodeToESTreeNodeMap } = parseWithNodeMaps( + code, + { + loc: true, + range: true, + }, +); +``` + +### `TSESTree`, `AST_NODE_TYPES` and `AST_TOKEN_TYPES` + +Types for the AST produced by the parse functions. + +- `TSESTree` is a namespace which contains object types representing all of the AST Nodes produced by the parser. +- `AST_NODE_TYPES` is an enum which provides the values for every single AST node's `type` property. +- `AST_TOKEN_TYPES` is an enum which provides the values for every single AST token's `type` property. + +### Utilities + +#### `createProgram(configFile, projectDirectory)` + +This serves as a utility method for users of the `ParseOptions.programs` feature to create a TypeScript program instance from a config file. + +```ts +declare function createProgram( + configFile: string, + projectDirectory: string = process.cwd(), +): import('typescript').Program; +``` + +Example usage: + +```js +const tsESTree = require('@typescript-eslint/typescript-estree'); + +const program = tsESTree.createProgram('tsconfig.json'); +const code = `const hello: string = 'world';`; +const { ast, services } = parseAndGenerateServices(code, { + filePath: '/some/path/to/file/foo.ts', + loc: true, + program, + range: true, +}); +``` + +## Debugging + +If you encounter a bug with the parser that you want to investigate, you can turn on the debug logging via setting the environment variable: `DEBUG=typescript-eslint:*`. +I.e. in this repo you can run: `DEBUG=typescript-eslint:* yarn lint`. diff --git a/docs/architecture/Utils.mdx b/docs/architecture/Utils.mdx new file mode 100644 index 000000000000..9270f2ed8e55 --- /dev/null +++ b/docs/architecture/Utils.mdx @@ -0,0 +1,28 @@ +--- +id: utils +sidebar_label: utils +--- + +# `@typescript-eslint/utils` + +> Utilities for working with TypeScript + ESLint together. ✨ + +This package contains public utilities for writing custom rules and plugins in TypeScript. +Rules declared in [`@typescript-eslint/eslint-plugin`](https://typescript-eslint.io/architecture/eslint-plugin) are created using these utility functions. +Any custom rules you write generally will be as well. + +> See [Custom Rules](https://typescript-eslint.io/custom-rules) for documentation on creating your own custom ESLint rules for TypeScript code. + +## Exports + +| Name | Description | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AST_NODE_TYPES` | An enum with the names of every single _node_ found in `TSESTree`. | +| `AST_TOKEN_TYPES` | An enum with the names of every single _token_ found in `TSESTree`. | +| `ASTUtils` | Tools for operating on the ESTree AST. Also includes the [`eslint-utils`](https://www.npmjs.com/package/eslint-utils) package, correctly typed to work with the types found in `TSESTree` | +| `ESLintUtils` | Tools for creating ESLint rules with TypeScript. | +| `JSONSchema` | Types from the [`@types/json-schema`](https://www.npmjs.com/package/@types/json-schema) package, re-exported to save you having to manually import them. Also ensures you're using the same version of the types as this package. | +| `ParserServices` | Typing for the parser services provided when parsing a file using `@typescript-eslint/typescript-estree`. | +| `TSESLint` | Types for ESLint, correctly typed to work with the types found in `TSESTree`. | +| `TSESLintScope` | The [`eslint-scope`](https://www.npmjs.com/package/eslint-scope) package, correctly typed to work with the types found in both `TSESTree` and `TSESLint` | +| `TSESTree` | Types for the TypeScript flavor of ESTree created by `@typescript-eslint/typescript-estree`. | diff --git a/docs/contributing/Issues.mdx b/docs/contributing/Issues.mdx new file mode 100644 index 000000000000..ae61dd0e3123 --- /dev/null +++ b/docs/contributing/Issues.mdx @@ -0,0 +1,36 @@ +--- +id: issues +title: Issues +--- + +So you've got a bug report, documentation request, or feature suggestion? +Great! + +Please do: + +- Make sure you're using the [latest version of our packages](https://github.com/typescript-eslint/typescript-eslint/releases) +- Search [all opened and closed issues](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+) to make sure your issue wouldn't be a duplicate +- Fill out the [appropriate issue template](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose) completely +- Provide as much information as you can + +## Commenting + +Please do comment on any open issue if you have more information that would be useful. + +Please don't: + +- Leave useless comments such as _"+1"_ or _"when's this getting fixed?"_ that only act as spam + - If you have nothing to add but enthusiasm and joy, add a reaction such as 👍 +- Bring up unrelated topics in existing issues: instead, file a new issue +- Comment on closed PRs: instead, [file a new issue](#raising-issues) +- Comment on commits directly, as those comments are not searchable: instead, file a new issue + +## Questions and Support Requests + +We do not have the bandwidth to handle questions or support requests in the issue tracker. +You can instead: + +- Ask a question on [StackOverflow](https://stackoverflow.com/questions/tagged/typescript-eslint 'StackOverflow questions tagged with typescript-eslint') using the `typescript-eslint` tag +- Publicly tweet [@tseslint on Twitter](https://twitter.com/tseslint) + +> Note that requests to add documentation _are_ allowed, even encouraged! 📝 diff --git a/docs/contributing/Local_Development.mdx b/docs/contributing/Local_Development.mdx new file mode 100644 index 000000000000..294435616b70 --- /dev/null +++ b/docs/contributing/Local_Development.mdx @@ -0,0 +1,82 @@ +--- +id: local-development +title: Local Development +--- + +Thank you for your interest in developing on TypeScript ESLint! ❤️‍🔥 + +> See [Contributing](../Contributing.mdx) and [Issues](./Issues.mdx) for details on our general contribution flows. + +## Setup + +After [forking the repo from GitHub](https://help.github.com/articles/fork-a-repo) and [installing Yarn classic](https://classic.yarnpkg.com): + +```shell +git clone https://github.com//typescript-eslint +cd typescript-eslint +yarn +``` + +Postinstall scripts will then fully build your repository locally with (`yarn build`). +At this point, you're ready to develop! 🚀 + +## Builds + +You can run `yarn build` in the root to build all packages, or in any package to build just that package. + +Keep in mind that packages generally depend on each other's built outputs, and you'll need to `yarn build` dependents for their consumers to receive any new local changes. +For example, if you make a change within `scope-manager` and want to use it in `eslint-plugin`, you'll need to `yarn build` either from the root or within `packages/scope-manager`. + +## Validating Changes + +The following checks are all run on pull requests automatically. +You can also perform them locally. + +> See [Contributing > Pull Requests](../Contributing.mdx#raising-a-pr) for more information on pull requests. + +### Formatting + +We use [Prettier](https://prettier.io) to auto-format code. +A Git pre-commit hook should apply it to all committed changes. +ALternately, you can run `yarn format` in any package or in the root. + +### Linting + +All code changes must pass ESLint. +You can run `yarn lint` in any package or in the root. + +### Proofreading + +Changes must pass two linters for documentation and naming, the commands for which may be run from the root: + +- `yarn check-spelling`: [CSpell](https://cspell.org), for all code +- `yarn lint-markdown`: [Markdownlint](https://github.com/DavidAnson/markdownlint), for Markdown documentation + +### Tests + +All code changes should ideally be unit tested if possible. +You can run `yarn test` in any package to run its tests. + +> [VS Code launch tasks](https://code.visualstudio.com/docs/editor/tasks) tasks are provided that allow [visual debugging](https://code.visualstudio.com/docs/editor/debugging) tests. + +#### Code Coverage + +We aim for 100% code coverage in all PRs when possible, except in the `website/` package. +Coverage reports are be generated locally whenever `yarn test` is run. + +The `codecov` bot should also comment on your PR with the percentage, as well as links to the line-by-line coverage of each file touched by your PR. + +### Type Checking + +All code should pass TypeScript type checking. +You can run `yarn typecheck` in any package or in the root to run `tsc`. + +> Run `yarn typecheck -w` to start `tsc` in watch mode. + +## Website Development + +Our interactive documentation website is built with [Docusaurus](https://docusaurus.io). +Running `yarn start` from either the root or `packages/website` will start a local dev server on `localhost:3000`. + +> The `website` package relies on other packages being built. +> We recommend running `yarn build` from the root before `yarn start`. diff --git a/docs/contributing/Pull_Requests.mdx b/docs/contributing/Pull_Requests.mdx new file mode 100644 index 000000000000..6d1c1063fb11 --- /dev/null +++ b/docs/contributing/Pull_Requests.mdx @@ -0,0 +1,74 @@ +--- +id: pull-requests +title: Pull Requests +--- + +> See [Local Development](./Local_Development.mdx) for details on how to get started developing locally. + +So you've got changes locally that address an issue? +Fantastic! + +Please do: + +- Only send pull requests that resolve [open issues marked as `accepting prs`](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+is%3Aopen+label%3A%22accepting+prs%22) + - One exception: extremely minor documentation typos +- Fill out the pull request template in full +- Validate your changes per [Development > Validating Changes](./Local_Development.mdx#validating-changes) before un-[drafting your PR](https://github.blog/2019-02-14-introducing-draft-pull-requests) + +Please don't: + +- Force push after opening a PR + - Reasoning: GitHub is not able to track changes across force pushes, which makes it take longer for us to perform incremental reviews +- Comment asking for updates + - Reasoning: Your PR hasn't been forgotten! The volunteer maintainers have limited time to work on the project, and they will get to it as soon as they are able. + +### Raising a PR + +Once your changes are ready, you can raise a PR! 🙌 +The title of your PR should match the following format: + +```text +(): +``` + +You can find more samples of good past PR titles in [recent commits to `main`](https://github.com/typescript-eslint/typescript-eslint/commits/main): + +- `fix(scope-manager): correct handling for class static blocks` +- `docs: Fix links to getting started in README.md` + +Within the body of your PR, make sure you reference the issue that you have worked on, as well as pointing out anything of note you wish us to look at during our review. + +> We do not care about the number, or style of commits in your history, because we squash merge every PR into `main`. +> Feel free to commit in whatever style you feel comfortable with. + +> Tip: Send the PR from a branch other than `main`. +> See GitHub's [Proposing Changes docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests) for more information. + +#### type + +Must be one of the following: + +- `docs` - if you only change documentation, and not shipped code +- `feat` - for any new functionality additions +- `fix` - for any bug fixes that don't add new functionality +- `test` - if you only change tests, and not shipped code +- `chore` - anything else + +#### package + +The name of the package you have made changes within, (e.g. `eslint-plugin`, `parser`, `typescript-estree`). +If you make significant changes across multiple packages, you can omit this (e.g. +`feat: foo bar`). + +#### short description + +A succinct title for the PR. + +### Addressing Feedback and Beyond + +With your PR raised and the CI passing, your PR will [wait in the queue to be reviewed](https://github.com/typescript-eslint/typescript-eslint/pulls?q=is%3Apr+is%3Aopen+sort%3Acreated-asc+-label%3A%22breaking+change%22+-label%3A%22awaiting+response%22+-label%3A%221+approval%22+-label%3A%22DO+NOT+MERGE%22+status%3Asuccess). +We generally review PRs oldest to newest, unless we consider a newer PR higher priority (e.g. if it's a bug fix). + +Once we have reviewed your PR, we will provide any feedback that needs addressing. +If you feel a requested change is wrong, don't be afraid to discuss with us in the comments. +Once the feedback is addressed, and the PR is reviewed, we'll ensure the branch is up to date with `main`, and merge it for you. diff --git a/docs/development/architecture/PACKAGES.md b/docs/development/architecture/PACKAGES.md deleted file mode 100644 index f798e35b2e47..000000000000 --- a/docs/development/architecture/PACKAGES.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -id: packages -title: Packages -sidebar_label: Packages ---- - -This page describes the top-level packages exported by the [typescript-eslint monorepo](https://github.com/typescript-eslint/typescript-eslint). -Each of these are published as npm packages under the `@typescript-eslint` organization. - -## `@typescript-eslint/eslint-plugin` - -[`@typescript-eslint/eslint-plugin`] is the core [ESLint plugin](https://eslint.org/docs/user-guide/configuring/plugins) used by consumers to load in custom rules and rule configurations lists from typescript-eslint. -Those rules rely on ESLint using the `@typescript-eslint/parser` package described below, and are generally built using the other packages on this page. - -## `@typescript-eslint/parser` - -[`@typescript-eslint/parser`] takes in ESLint configuration settings, reads in TypeScript source text, and produces an ESTree AST. -This is necessary because TypeScript produces a different, incompatible AST format to the one that ESLint requires to work. - -For example, this is not valid JavaScript code because it contains the `: number` type annotation: - -```ts -let x: number = 1; -``` - -ESLint's native Espree parser would raise an error attempting to parse it. - -Additionally, because TypeScript is developed separately and with different goals from ESLint, ESTree, and Espree, its AST also represents nodes differently in many cases. -TS's AST is optimized for its use case of parsing incomplete code and typechecking. -ESTree is unoptimized and intended for "general purpose" use-cases of traversing the AST. - -See more on configuring custom parsers with ESLint on [ESLint's User Guide > Configuring > Plugins](https://eslint.org/docs/user-guide/configuring/plugins#specifying-parser). - -:::tip -You can select `@typescript-eslint/parser` on the [TypeScript ESLint playground](https://typescript-eslint.io/play#showAST=es)'s left sidebar under _Options_ > _AST Explorer_ by selecting _ESTree_. -::: - -## `@typescript-eslint/typescript-estree` - -[`@typescript-eslint/typescript-estree`] is used by `@typescript-eslint/parser` to take TypeScript source code and produce the equivalent ESTree AST. -It works by: - -1. Invoking the TypeScript compiler on the given source code in order to - produce a TypeScript AST -2. Converting that TypeScript AST into an ESTree AST - -> Because [`@typescript-eslint/typescript-estree`] has a very specific purpose, it is reusable for tools with similar -> requirements to ESLint. -> It is therefore also used to power the amazing opinionated code formatter [Prettier](https://prettier.io)'s TypeScript support. - -## `@typescript-eslint/scope-manager` - -[`@typescript-eslint/scope-manager`] is a fork of [`eslint-scope`](https://github.com/eslint/eslint-scope), enhanced to support TypeScript functionality. - -A "scope analyser" traverses an AST and builds a model of how variables (and in our case, types) are defined and consumed by the source code. -This form of static analysis allows you to understand and trace variables throughout the program, allowing you to access powerful information about a program without needing to drop into the much, much heavier type information. - -## `@typescript-eslint/utils` - -[`@typescript-eslint/utils`] contains public utilities for writing custom rules and plugins in TypeScript. -Rules declared in `@typescript-eslint/eslint-plugin` are created using its utility functions. -Any custom rules you write generally will be as well. - -## `@typescript-eslint/eslint-plugin-tslint` - -[`@typescript-eslint/eslint-plugin-tslint`] is a separate ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint. - -:::caution -**TSLint is deprecated.** It is in your best interest to migrate off it. See [Linting > Troubleshooting & FAQs > What About TSLint?](../../linting/troubleshooting/TSLINT.md). -::: - -[`@typescript-eslint/eslint-plugin-tslint`]: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin-tslint -[`@typescript-eslint/eslint-plugin`]: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin -[`@typescript-eslint/utils`]: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/utils -[`@typescript-eslint/parser`]: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser -[`@typescript-eslint/scope-manager`]: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/scope-manager -[`@typescript-eslint/typescript-estree`]: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/typescript-estree -[`@typescript-eslint/typescript-estree`]: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/typescript-estree diff --git a/docs/linting/CONFIGURATIONS.md b/docs/linting/Configurations.md similarity index 97% rename from docs/linting/CONFIGURATIONS.md rename to docs/linting/Configurations.md index de05a216ff87..11172d9aa60a 100644 --- a/docs/linting/CONFIGURATIONS.md +++ b/docs/linting/Configurations.md @@ -13,7 +13,7 @@ With the exception of `strict`, all configurations are considered "stable". Rule additions and removals are treated as breaking changes and will only be done in major version bumps. :::note -We recommend most packages extend from [`recommended-requiring-type-checking`](#recommended-requiring-type-checking) (which requires [typed linting](./TYPED_LINTING.md)). +We recommend most packages extend from [`recommended-requiring-type-checking`](#recommended-requiring-type-checking) (which requires [typed linting](./Typed_Linting.md)). ::: ### `eslint-recommended` @@ -65,7 +65,7 @@ Rules in this configuration are similarly useful to those in `recommended`. :::tip We recommend all TypeScript projects extend from this configuration, with the caveat that rules using type information take longer to run. -See [Linting with Type Information](/docs/linting/typed-linting) for more details. +See [Linting with Type Information](/linting/typed-linting) for more details. ::: ### `strict` diff --git a/docs/linting/TROUBLESHOOTING.md b/docs/linting/Troubleshooting.md similarity index 98% rename from docs/linting/TROUBLESHOOTING.md rename to docs/linting/Troubleshooting.md index 5001a0a16fa4..38d3bf38e710 100644 --- a/docs/linting/TROUBLESHOOTING.md +++ b/docs/linting/Troubleshooting.md @@ -35,11 +35,11 @@ If you don't find an existing extension rule, or the extension rule doesn't work - If you **do not** want to lint the file: - Use [one of the options ESLint offers](https://eslint.org/docs/latest/user-guide/configuring/ignoring-code) to ignore files, namely a `.eslintignore` file, or `ignorePatterns` config. - If you **do** want to lint the file: - - If you **do not** want to lint the file with [type-aware linting](./TYPED_LINTING.md): + - If you **do not** want to lint the file with [type-aware linting](./Typed_Linting.md): - Use [ESLint's `overrides` configuration](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#configuration-based-on-glob-patterns) to configure the file to not be parsed with type information. - A popular setup is to omit the above additions from top-level configuration and only apply them to TypeScript files via an override. - Alternatively, you can add `parserOptions: { project: null }` to an override for the files you wish to exclude. Note that `{ project: undefined }` will not work. - - If you **do** want to lint the file with [type-aware linting](./TYPED_LINTING.md): + - If you **do** want to lint the file with [type-aware linting](./Typed_Linting.md): - Check the `include` option of each of the tsconfigs that you provide to `parserOptions.project` - you must ensure that all files match an `include` glob, or else our tooling will not be able to find it. - If your file shouldn't be a part of one of your existing tsconfigs (for example, it is a script/tool local to the repo), then consider creating a new tsconfig (we advise calling it `tsconfig.eslint.json`) in your project root which lists this file in its `include`. For an example of this, you can check out the configuration we use in this repo: - [`tsconfig.eslint.json`](https://github.com/typescript-eslint/typescript-eslint/blob/main/tsconfig.eslint.json) @@ -64,12 +64,12 @@ For example, many projects have files like: In that case, viewing the `.eslintrc.cjs` in an IDE with the ESLint extension will show the error notice that the file couldn't be linted because it isn't included in `tsconfig.json`. -See our docs on [type aware linting](./TYPED_LINTING.md) for more information. +See our docs on [type aware linting](./Typed_Linting.md) for more information. ## I get errors telling me "The file must be included in at least one of the projects provided" You're using an outdated version of `@typescript-eslint/parser`. -Update to the latest version to see a more informative version of this error message, explained [above](#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). +Update to the latest version to see a more informative version of this error message, explained [above](#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file 'backlink to I get errors telling me ESLint was configured to run ...'). ## I use a framework (like Vue) that requires custom file extensions, and I get errors like "You should add `parserOptions.extraFileExtensions` to your config" @@ -241,7 +241,7 @@ Rules such as [`no-unsafe-argument`](https://typescript-eslint.io/rules/no-unsaf ## My linting feels really slow -As mentioned in the [type-aware linting doc](./TYPED_LINTING.md), if you're using type-aware linting, your lint times should be roughly the same as your build times. +As mentioned in the [type-aware linting doc](./Typed_Linting.md), if you're using type-aware linting, your lint times should be roughly the same as your build times. If you're experiencing times much slower than that, then there are a few common culprits. diff --git a/docs/linting/TYPED_LINTING.md b/docs/linting/Typed_Linting.md similarity index 88% rename from docs/linting/TYPED_LINTING.md rename to docs/linting/Typed_Linting.md index 8ffb708d0e3e..3e1beb396a8a 100644 --- a/docs/linting/TYPED_LINTING.md +++ b/docs/linting/Typed_Linting.md @@ -30,7 +30,7 @@ In more detail: - `parserOptions.tsconfigRootDir` tells our parser the absolute path of your project's root directory. - `parserOptions.project` tells our parser the relative path where your project's `tsconfig.json` is. - - If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/MONOREPOS.md). + - If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.md). - `plugin:@typescript-eslint/recommended-requiring-type-checking` is another recommended configuration we provide. This one contains rules that specifically require type information. With that done, run the same lint command you ran before. @@ -53,8 +53,8 @@ This means that generally they usually only run a complete lint before a push, o ### I get errors telling me "The file must be included in at least one of the projects provided" You're using an outdated version of `@typescript-eslint/parser`. -Update to the latest version to see a more informative version of this error message, explained [Troubleshooting and FAQs](./TROUBLESHOOTING.md##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). +Update to the latest version to see a more informative version of this error message, explained in our [Troubleshooting and FAQs page](./Troubleshooting.md#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file). ## Troubleshooting -If you're having problems getting this working, please have a look at our [Troubleshooting FAQ](./TROUBLESHOOTING.md). +If you're having problems getting this working, please have a look at our [Troubleshooting and FAQs page](./Troubleshooting.md). diff --git a/docs/linting/troubleshooting/TSLINT.md b/docs/linting/troubleshooting/TSLint.md similarity index 94% rename from docs/linting/troubleshooting/TSLINT.md rename to docs/linting/troubleshooting/TSLint.md index a145f9fca61e..8eb61e85713f 100644 --- a/docs/linting/troubleshooting/TSLINT.md +++ b/docs/linting/troubleshooting/TSLint.md @@ -17,7 +17,7 @@ You can look at [the alternatives list](https://github.com/typescript-eslint/typ There is also the ultimate fallback option of using both linters together for a while during your transition if you absolutely have to by using TSLint _within_ ESLint. -For this option, check out [`@typescript-eslint/eslint-plugin-tslint`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin-tslint). +For this option, check out [`@typescript-eslint/eslint-plugin-tslint`](../../architecture/ESLint_Plugin_TSLint.mdx). ## Why Deprecate TSLint? diff --git a/docs/linting/typed-linting/MONOREPOS.md b/docs/linting/typed-linting/Monorepos.md similarity index 97% rename from docs/linting/typed-linting/MONOREPOS.md rename to docs/linting/typed-linting/Monorepos.md index 5163e997ec84..e55d20647796 100644 --- a/docs/linting/typed-linting/MONOREPOS.md +++ b/docs/linting/typed-linting/Monorepos.md @@ -38,7 +38,7 @@ Be sure to update your `.eslintrc.js` to point at this new config file. ## One `tsconfig.json` per package (and an optional one in the root) -The `parserOptions.project` option introduced in [Linting with Type Information](../TYPED_LINTING.md) accepts an array of relative paths. +The `parserOptions.project` option introduced in [Linting with Type Information](../Typed_Linting.md) accepts an array of relative paths. Paths may be provided as [Node globs](https://github.com/isaacs/node-glob/blob/f5a57d3d6e19b324522a3fa5bdd5075fd1aa79d1/README.md#glob-primer). For each file being linted, the first matching project path will be used as its backing TSConfig. @@ -104,4 +104,4 @@ As an interim workaround, consider one of the following: ## Troubleshooting -If you're having problems getting this working, please have a look at our [Troubleshooting FAQ](../TROUBLESHOOTING.md). +If you're having problems getting this working, please have a look at our [Troubleshooting FAQ](../Troubleshooting.md). diff --git a/docs/maintenance/VERSIONING.md b/docs/maintenance/VERSIONING.md index 514215d1136c..0dd31ae90c1b 100644 --- a/docs/maintenance/VERSIONING.md +++ b/docs/maintenance/VERSIONING.md @@ -9,15 +9,59 @@ This page exists to help set guidelines around when what we consider to fall wit All of the packages in this project are published with the same version number to make it easier to coordinate both releases and installations. -When considering whether a change should be counted as "breaking" we first need to consider what package(s) it impacts. For example breaking changes for the parser packages have a different standard to those for the ESLint plugins. This is because not only do they have _very_ different API surfaces, they also are consumed in very different ways. +We publish a canary release on every successful merge to `main`, so **you never need to wait for a new stable version to make use of any updates**. -Please note that the lists provided below are non-exhaustive and are intended to serve as examples to help guide maintainers when planning and reviewing changes. +Additionally, we promote to the `latest` tag on NPM once per week, **on Mondays at 1 pm Eastern**. -## Internal packages +The latest version under the `latest` tag is: -Any packages in this project that are not part of our public API surface (such as `eslint-plugin-internal` or `website`) shall not be considered when calculating new package versions. +NPM Version + +The latest version under the `canary` tag **(latest commit to `main`)** is: + +NPM Version + +:::note +The only exception to the automated publishes described above is when we are in the final phases of creating the next major version of the libraries - e.g. going from `1.x.x` to `2.x.x`. +During these periods, we manually publish `canary` releases until we are happy with the release and promote it to `latest`. +::: + +## Dependant Versions + +### TypeScript + +> The version range of TypeScript currently supported is `>=3.3.1 <4.9.0`. + +These versions are what we test against. + +We will always endeavor to support the latest stable version of TypeScript. +Sometimes, but not always, changes in TypeScript will not require breaking changes in this project, and so we are able to support more than one version of TypeScript. +In some cases, we may even be able to support additional pre-releases (i.e. betas and release candidates) of TypeScript, but only if doing so does not require us to compromise on support for the latest stable version. + +Note that our packages have an open `peerDependency` requirement in order to allow for experimentation on newer/beta versions of TypeScript. + +If you use a non-supported version of TypeScript, the parser will log a warning to the console. +If you want to disable this warning, you can configure this in your `parserOptions`. +See: [`@typescript-eslint/parser`](./packages/parser/ TODO JOSH) and [`@typescript-eslint/typescript-estree`](./packages/typescript-estree/ TODO JOSH). -## `ast-spec` and `visitor-keys` +### ESLint + +> The version range of ESLint currently supported is `^6.0.0 || ^7.0.0 || ^8.0.0`. + +We generally support at least the latest two major versions of ESLint. + +### Node + +This project makes an effort to support Active LTS and Maintenance LTS release statuses of Node according to [Node's release document](https://nodejs.org/en/about/releases). +Support for specific Current status releases are considered periodically. + +## Breaking Changes + +When considering whether a change should be counted as "breaking" we first need to consider what package(s) it impacts. For example breaking changes for the parser packages have a different standard to those for the ESLint plugins. This is because not only do they have _very_ different API surfaces, they also are consumed in very different ways. + +Please note that the lists provided below are non-exhaustive and are intended to serve as examples to help guide maintainers when planning and reviewing changes. + +### `ast-spec` and `visitor-keys` A change to the AST **_shall_** be considered breaking if it: @@ -33,7 +77,7 @@ A change to the AST **_shall not_** be considered breaking if it: - Refines a type to be more specific (i.e. `string` to `'literal' | 'union'`). - Removes a type from a union that was erroneously added and did not match the runtime AST. -## `eslint-plugin` and `eslint-plugin-tslint` +### `eslint-plugin` and `eslint-plugin-tslint` A change to the plugins **_shall_** be considered breaking if it will require the user to change their config. More specifically: @@ -57,7 +101,7 @@ A change to the plugins **_shall not_** be considered breaking if it: - Removes a fixer or suggestion fixer. - Fixes incorrect behavior in a rule that may or may not introduce additional reports. -### `parser`, `typescript-estree`, `scope-manager`, `types`, `type-utils`, `utils` +#### `parser`, `typescript-estree`, `scope-manager`, `types`, `type-utils`, `utils` A change to these packages **_shall_** be considered breaking if it: @@ -70,3 +114,7 @@ A change to these packages **_shall not_** be considered breaking if it: - Adds **_optional_** arguments to functions or properties to input types. - Adds additional properties to output types. - Adds documentation in the form of JSDoc comments. + +### Internal packages + +Any packages in this project that are not part of our public API surface (such as `eslint-plugin-internal` or `website`) shall not be considered when calculating new package versions. diff --git a/netlify.toml b/netlify.toml index 8a38c2fa7772..0962e8c6a979 100644 --- a/netlify.toml +++ b/netlify.toml @@ -8,22 +8,37 @@ YARN_FLAGS = "--ignore-scripts" # https://docs.netlify.com/configure-builds/file-based-configuration/#redirects + +[[redirects]] + from = "/docs" + to = "/getting-started" + +[[redirects]] + from = "/docs/development/architecture/asts" + to = "/blog/asts-and-typescript-eslint" + [[redirects]] - from = "/docs/linting" - to = "/docs" + from = "/docs/development/architecture/packages" + to = "/architecture" + +[[redirects]] + from = "/docs/development/custom-rules" + to = "/custom-rules" [[redirects]] from = "/docs/linting/type-linting" - to = "/docs/linting/typed-linting" + to = "/linting/typed-linting" [[redirects]] from = "/docs/linting/monorepo" - to = "/docs/linting/typed-linting/monorepos" + to = "/linting/typed-linting/monorepos" [[redirects]] from = "/docs/linting/tslint" - to = "/docs/linting/troubleshooting/tslint" + to = "/linting/troubleshooting/tslint" [[redirects]] - from = "/docs/development/architecture/asts" - to = "/blog/asts-and-typescript-eslint" + from = "/docs/*" + to = "/" + to = "/docs/linting/troubleshooting/tslint" + diff --git a/packages/ast-spec/README.md b/packages/ast-spec/README.md index 388241c0061d..43536bb821b3 100644 --- a/packages/ast-spec/README.md +++ b/packages/ast-spec/README.md @@ -1,24 +1,16 @@ -

TypeScript-ESTree AST Specification

+# `@typescript-eslint/ast-spec` -

- CI - NPM Version - NPM Downloads -

+> Complete specification for the TypeScript-ESTree AST -This is the complete specification for the TypeScript-ESTree AST. - -It includes: +This package includes: - Node definitions as TypeScript types (the specification) - Logic for converting from the TypeScript AST to the TypeScript-ESTree AST. - Tests/Fixtures/Examples for each Node -**You probably don't want to use it directly.** - -If you're building an ESLint plugin, consider using [`@typescript-eslint/utils`](../utils) and [`@typescript-eslint/type-utils`](../type-utils). -If you're parsing TypeScript code, consider using [`@typescript-eslint/typescript-estree`](../typescript-estree). +## ✋ Internal Package -## Contributing +This is an _internal package_ to the [typescript-eslint monorepo](https://github.com/typescript-eslint/typescript-eslint). +You likely don't want to use it directly. -[See the contributing guide here](../../CONTRIBUTING.md) +👉 See **https://typescript-eslint.io** for docs on typescript-eslint. diff --git a/packages/ast-spec/package.json b/packages/ast-spec/package.json index 19a595262da8..9a8f346b9558 100644 --- a/packages/ast-spec/package.json +++ b/packages/ast-spec/package.json @@ -1,7 +1,7 @@ { "name": "@typescript-eslint/ast-spec", "version": "5.43.0", - "description": "TypeScript-ESTree AST spec", + "description": "Complete specification for the TypeScript-ESTree AST", "private": true, "keywords": [ "eslint", diff --git a/packages/eslint-plugin-internal/README.md b/packages/eslint-plugin-internal/README.md index adf369999286..7d081266c542 100644 --- a/packages/eslint-plugin-internal/README.md +++ b/packages/eslint-plugin-internal/README.md @@ -1,9 +1,10 @@ -

Internal ESLint Plugin

+# `@typescript-eslint/eslint-plugin-internal` -

An ESLint plugin used internally in this project to ensure consistency.

+> An ESLint plugin used internally in this project to ensure consistency. -

- CI -

+## ✋ Internal Package -This plugin is not intended to be used externally. +This is an _internal package_ to the [typescript-eslint monorepo](https://github.com/typescript-eslint/typescript-eslint). +You likely don't want to use it directly. + +👉 See **https://typescript-eslint.io** for docs on typescript-eslint. diff --git a/packages/eslint-plugin-tslint/README.md b/packages/eslint-plugin-tslint/README.md index 021b8780bfbd..57c414230ec8 100644 --- a/packages/eslint-plugin-tslint/README.md +++ b/packages/eslint-plugin-tslint/README.md @@ -1,62 +1,10 @@ -

ESLint Plugin TSLint

+# `@typescript-eslint/eslint-plugin-tslint` -

ESLint plugin wraps a TSLint configuration and lints the whole source using TSLint.

+> ESLint plugin that wraps a TSLint configuration and lints the whole source using TSLint. -

- CI - NPM Version - NPM Downloads -

+[![NPM Version](https://img.shields.io/npm/v/@typescript-eslint/eslint-plugin-tslint.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/eslint-plugin-tslint) +[![NPM Downloads](https://img.shields.io/npm/dm/@typescript-eslint/eslint-plugin-tslint.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/eslint-plugin-tslint) -## Installation +👉 See **https://typescript-eslint.io/architecture/eslint-plugin-tslint** for documentation on this package. -```sh -yarn add -D @typescript-eslint/eslint-plugin-tslint -``` - -## Usage - -Configure in your ESLint config file: - -```js -{ - "plugins": [ - "@typescript-eslint/tslint" - ], - "parserOptions": { - "project": "tsconfig.json", - }, - "rules": { - "@typescript-eslint/tslint/config": ["warn", { - "lintFile": "", // path to tslint.json of your project - "rules": { - // tslint rules (will be used if `lintFile` is not specified) - }, - "rulesDirectory": [ - // array of paths to directories with rules, e.g. 'node_modules/tslint/lib/rules' (will be used if `lintFile` is not specified) - ] - }], - } -} -``` - -**Note:** The ability to automatically fix problems with `--fix` is unavailable for TSLint rules loaded with this plugin. - -## Rules - -Plugin contains only single rule `@typescript-eslint/tslint/config`. - -## Examples - -- [`unlight/node-package-starter/.eslintrc.js`](https://github.com/unlight/node-package-starter/blob/master/.eslintrc.js) - -### TSLint Plugins - -- https://github.com/Glavin001/tslint-clean-code -- https://github.com/Microsoft/tslint-microsoft-contrib -- https://github.com/SonarSource/SonarTS -- https://github.com/ajafff/tslint-consistent-codestyle - -## Contributing - -[See the contributing guide here](../../CONTRIBUTING.md) +> See https://typescript-eslint.io for general documentation on typescript-eslint, the tooling that allows you to run ESLint and Prettier on TypeScript code. diff --git a/packages/eslint-plugin-tslint/package.json b/packages/eslint-plugin-tslint/package.json index d69678024c80..6a5a1d522b8f 100644 --- a/packages/eslint-plugin-tslint/package.json +++ b/packages/eslint-plugin-tslint/package.json @@ -3,7 +3,7 @@ "version": "5.43.0", "main": "dist/index.js", "typings": "src/index.ts", - "description": "TSLint wrapper plugin for ESLint", + "description": "ESLint plugin that wraps a TSLint configuration and lints the whole source using TSLint", "keywords": [ "eslint", "eslintplugin", diff --git a/packages/eslint-plugin/README.md b/packages/eslint-plugin/README.md index c7c0ea80e4f9..b9dd0cecd032 100644 --- a/packages/eslint-plugin/README.md +++ b/packages/eslint-plugin/README.md @@ -1,96 +1,10 @@ -

ESLint Plugin TypeScript

+# `@typescript-eslint/eslint-plugin` -

An ESLint plugin which provides lint rules for TypeScript codebases.

+An ESLint plugin which provides lint rules for TypeScript codebases. -

- CI - NPM Version - NPM Downloads -

+[![NPM Version](https://img.shields.io/npm/v/@typescript-eslint/eslint-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/eslint-plugin) +[![NPM Downloads](https://img.shields.io/npm/dm/@typescript-eslint/eslint-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/eslint-plugin) -## Getting Started +👉 See **https://typescript-eslint.io/architecture/utils** for our Getting Started docs. -- **[You can find our Getting Started docs here](https://typescript-eslint.io/docs)** -- **[You can find our FAQ / Troubleshooting docs here](https://typescript-eslint.io/docs/linting/troubleshooting)** - -These docs walk you through setting up ESLint, this plugin, and our parser. If you know what you're doing and just want to quick start, read on... - -## Quick-start - -### Installation - -Make sure you have TypeScript and [`@typescript-eslint/parser`](../parser) installed: - -```bash -$ yarn add -D typescript @typescript-eslint/parser -$ npm i --save-dev typescript @typescript-eslint/parser -``` - -Then install the plugin: - -```bash -$ yarn add -D @typescript-eslint/eslint-plugin -$ npm i --save-dev @typescript-eslint/eslint-plugin -``` - -It is important that you use the same version number for `@typescript-eslint/parser` and `@typescript-eslint/eslint-plugin`. - -**Note:** If you installed ESLint globally (using the `-g` flag) then you must also install `@typescript-eslint/eslint-plugin` globally. - -### Usage - -Add `@typescript-eslint/parser` to the `parser` field and `@typescript-eslint` to the plugins section of your `.eslintrc` configuration file, then configure the rules you want to use under the rules section. - -```json -{ - "parser": "@typescript-eslint/parser", - "plugins": ["@typescript-eslint"], - "rules": { - "@typescript-eslint/rule-name": "error" - } -} -``` - -You can also enable all the recommended rules for our plugin. Add `plugin:@typescript-eslint/recommended` in extends: - -```json -{ - "extends": ["plugin:@typescript-eslint/recommended"] -} -``` - -### Recommended Configs - -You can also use [`eslint:recommended`](https://eslint.org/docs/rules/) (the set of rules which are recommended for all projects by the ESLint Team) with this plugin: - -```json -{ - "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"] -} -``` - -As of version 2 of this plugin, _by design_, none of the rules in the main `recommended` config require type-checking in order to run. This means that they are more lightweight and faster to run. - -Some highly valuable rules require type-checking in order to be implemented correctly, however, so we provide an additional config you can extend from called `recommended-requiring-type-checking`. You would apply this _in addition_ to the recommended configs previously mentioned, e.g.: - -```json -{ - "extends": [ - "eslint:recommended", - "plugin:@typescript-eslint/recommended", - "plugin:@typescript-eslint/recommended-requiring-type-checking" - ] -} -``` - -Pro Tip: For larger codebases you may want to consider splitting our linting into two separate stages: 1. fast feedback rules which operate purely based on syntax (no type-checking), 2. rules which are based on semantics (type-checking). - -**[You can read more about linting with type information here](https://typescript-eslint.io/docs/linting/typed-linting)** - -## Supported Rules - -For the exhaustive list of supported rules, [please see our website](https://typescript-eslint.io/rules/). - -## Contributing - -[See the contributing guide here](../../CONTRIBUTING.md). +> See https://typescript-eslint.io for general documentation on typescript-eslint, the tooling that allows you to run ESLint and Prettier on TypeScript code. diff --git a/packages/eslint-plugin/docs/rules/README.md b/packages/eslint-plugin/docs/rules/README.md index 7c6bd00d36df..04e2d9870563 100644 --- a/packages/eslint-plugin/docs/rules/README.md +++ b/packages/eslint-plugin/docs/rules/README.md @@ -7,7 +7,7 @@ slug: / --- `@typescript-eslint/eslint-plugin` includes over 100 rules that detect best practice violations, bugs, and/or stylistic issues specifically for TypeScript code. -See [Configs](/docs/linting/configs) for how to enable recommended rules using configs. +See [Configs](/linting/configs) for how to enable recommended rules using configs. ## Supported Rules diff --git a/packages/eslint-plugin/docs/rules/consistent-type-imports.md b/packages/eslint-plugin/docs/rules/consistent-type-imports.md index 4ea1f7559943..045b7c2fa7da 100644 --- a/packages/eslint-plugin/docs/rules/consistent-type-imports.md +++ b/packages/eslint-plugin/docs/rules/consistent-type-imports.md @@ -90,7 +90,7 @@ const x: import('Bar') = 1; The `emitDecoratorMetadata` compiler option changes the code the TypeScript emits. In short - it causes TypeScript to create references to value imports when they are used in a type-only location. If you are using `emitDecoratorMetadata` then our tooling will require additional information in order for the rule to work correctly. -If you are using [type-aware linting](https://typescript-eslint.io/docs/linting/typed-linting), then you just need to ensure that the `tsconfig.json` you've configured for `parserOptions.project` has `emitDecoratorMetadata` turned on. Otherwise you can explicitly tell our tooling to analyze your code as if the compiler option was turned on [by setting `parserOptions.emitDecoratorMetadata` to `true`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/parser/README.md#parseroptionsemitdecoratormetadata). +If you are using [type-aware linting](https://typescript-eslint.io/linting/typed-linting), then you just need to ensure that the `tsconfig.json` you've configured for `parserOptions.project` has `emitDecoratorMetadata` turned on. Otherwise you can explicitly tell our tooling to analyze your code as if the compiler option was turned on [by setting `parserOptions.emitDecoratorMetadata` to `true`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/parser/README.md#parseroptionsemitdecoratormetadata). ## When Not To Use It diff --git a/packages/experimental-utils/README.md b/packages/experimental-utils/README.md index 3073308c16bb..d1468f928b15 100644 --- a/packages/experimental-utils/README.md +++ b/packages/experimental-utils/README.md @@ -1,12 +1,9 @@ -

Utils for ESLint Plugins

+# `@typescript-eslint/experimental-utils` -

Utilities for working with TypeScript + ESLint together.

+Utilities for working with TypeScript + ESLint together. -

- CI - NPM Version - NPM Downloads -

+[![NPM Version](https://img.shields.io/npm/v/@typescript-eslint/experimental-utils.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/experimental-utils) +[![NPM Downloads](https://img.shields.io/npm/dm/@typescript-eslint/experimental-utils.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/experimental-utils) ## Note diff --git a/packages/parser/README.md b/packages/parser/README.md index b32ed30beab4..f057b97f8680 100644 --- a/packages/parser/README.md +++ b/packages/parser/README.md @@ -1,304 +1,10 @@ -

TypeScript ESLint Parser

+# `@typescript-eslint/parser` -

An ESLint parser which leverages TypeScript ESTree to allow for ESLint to lint TypeScript source code.

+> An ESLint parser which leverages TypeScript ESTree to allow for ESLint to lint TypeScript source code. -

- CI - NPM Version - NPM Downloads -

+[![NPM Version](https://img.shields.io/npm/v/@typescript-eslint/parser.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/parser) +[![NPM Downloads](https://img.shields.io/npm/dm/@typescript-eslint/parser.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/parser) -## Getting Started +👉 See **https://typescript-eslint.io/architecture/parser** for documentation on this package. -**[You can find our Getting Started docs here](https://typescript-eslint.io/docs)** - -These docs walk you through setting up ESLint, this parser, and our plugin. If you know what you're doing and just want to quick start, read on... - -## Quick-start - -### Installation - -```bash -$ yarn add -D typescript @typescript-eslint/parser -$ npm i --save-dev typescript @typescript-eslint/parser -``` - -### Usage - -In your ESLint configuration file, set the `parser` property: - -```json -{ - "parser": "@typescript-eslint/parser" -} -``` - -There is sometimes an incorrect assumption that the parser itself is what does everything necessary to facilitate the use of ESLint with TypeScript. In actuality, it is the combination of the parser _and_ one or more plugins which allow you to maximize your usage of ESLint with TypeScript. - -For example, once this parser successfully produces an AST for the TypeScript source code, it might well contain some information which simply does not exist in a standard JavaScript context, such as the data for a TypeScript-specific construct, like an `interface`. - -The core rules built into ESLint, such as `indent` have no knowledge of such constructs, so it is impossible to expect them to work out of the box with them. - -Instead, you also need to make use of one more plugins which will add or extend rules with TypeScript-specific features. - -By far the most common case will be installing the [`@typescript-eslint/eslint-plugin`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin) plugin, but there are also other relevant options available such a [`@typescript-eslint/eslint-plugin-tslint`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin-tslint). - -## Configuration - -The following additional configuration options are available by specifying them in [`parserOptions`](https://eslint.org/docs/user-guide/configuring/language-options#specifying-parser-options) in your ESLint configuration file. - -```ts -interface ParserOptions { - ecmaFeatures?: { - jsx?: boolean; - globalReturn?: boolean; - }; - ecmaVersion?: number | 'latest'; - - jsxPragma?: string | null; - jsxFragmentName?: string | null; - lib?: string[]; - - project?: string | string[]; - projectFolderIgnoreList?: string[]; - tsconfigRootDir?: string; - extraFileExtensions?: string[]; - warnOnUnsupportedTypeScriptVersion?: boolean; - - program?: import('typescript').Program; - moduleResolver?: string; - - emitDecoratorMetadata?: boolean; -} -``` - -### `parserOptions.ecmaFeatures.jsx` - -Default `false`. - -Enable parsing JSX when `true`. More details can be found [here](https://www.typescriptlang.org/docs/handbook/jsx.html). - -**NOTE:** this setting does not affect known file types (`.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`, `.json`) because the TypeScript compiler has its own internal handling for known file extensions. - - - -The exact behavior is as follows: - -- `.js`, `.mjs`, `.cjs`, `.jsx`, `.tsx` files are always parsed as if this is `true`. -- `.ts`, `.mts`, `.cts` files are always parsed as if this is `false`. -- For "unknown" extensions (`.md`, `.vue`): - - If `parserOptions.project` is _not_ provided: - - The setting will be respected. - - If `parserOptions.project` is provided (i.e. you are using rules with type information): - - **always parsed as if this is `false`** - -### `parserOptions.ecmaFeatures.globalReturn` - -Default `false`. - -This options allows you to tell the parser if you want to allow global `return` statements in your codebase. - -### `parserOptions.ecmaVersion` - -Default `2018`. - -Accepts any valid ECMAScript version number or `'latest'`: - -- A version: es3, es5, es6, es7, es8, es9, es10, es11, es12, es13, ..., or -- A year: es2015, es2016, es2017, es2018, es2019, es2020, es2021, es2022, ..., or -- `'latest'` - -When it's a version or a year, the value **must** be a number - so do not include the `es` prefix. - -Specifies the version of ECMAScript syntax you want to use. This is used by the parser to determine how to perform scope analysis, and it affects the default - -### `parserOptions.jsxPragma` - -Default `'React'` - -The identifier that's used for JSX Elements creation (after transpilation). -If you're using a library other than React (like `preact`), then you should change this value. If you are using the [new JSX transform](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) you can set this to `null`. - -This should not be a member expression - just the root identifier (i.e. use `"React"` instead of `"React.createElement"`). - -If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler. - -### `parserOptions.jsxFragmentName` - -Default `null` - -The identifier that's used for JSX fragment elements (after transpilation). -If `null`, assumes transpilation will always use a member of the configured `jsxPragma`. -This should not be a member expression - just the root identifier (i.e. use `"h"` instead of `"h.Fragment"`). - -If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler. - -### `parserOptions.lib` - -Default `['es2018']` - -For valid options, see the [TypeScript compiler options](https://www.typescriptlang.org/tsconfig#lib). - -Specifies the TypeScript `lib`s that are available. This is used by the scope analyser to ensure there are global variables declared for the types exposed by TypeScript. - -If you provide `parserOptions.project`, you do not need to set this, as it will automatically detected from the compiler. - -### `parserOptions.project` - -Default `undefined`. - -This option allows you to provide a path to your project's `tsconfig.json`. **This setting is required if you want to use rules which require type information**. Relative paths are interpreted relative to the current working directory if `tsconfigRootDir` is not set. If you intend on running ESLint from directories other than the project root, you should consider using `tsconfigRootDir`. - -- Accepted values: - - ```js - // path - project: './tsconfig.json'; - - // glob pattern - project: './packages/**/tsconfig.json'; - - // array of paths and/or glob patterns - project: ['./packages/**/tsconfig.json', './separate-package/tsconfig.json']; - ``` - -- If you use project references, TypeScript will not automatically use project references to resolve files. This means that you will have to add each referenced tsconfig to the `project` field either separately, or via a glob. - -- Note that using wide globs `**` in your `parserOptions.project` may cause performance implications. Instead of globs that use `**` to recursively check all folders, prefer paths that use a single `*` at a time. For more info see [#2611](https://github.com/typescript-eslint/typescript-eslint/issues/2611). - -- TypeScript will ignore files with duplicate filenames in the same folder (for example, `src/file.ts` and `src/file.js`). TypeScript purposely ignore all but one of the files, only keeping the one file with the highest priority extension (the extension priority order (from highest to lowest) is `.ts`, `.tsx`, `.d.ts`, `.js`, `.jsx`). For more info see #955. - -- Note that if this setting is specified and `createDefaultProgram` is not, you must only lint files that are included in the projects as defined by the provided `tsconfig.json` files. If your existing configuration does not include all of the files you would like to lint, you can create a separate `tsconfig.eslint.json` as follows: - - ```jsonc - { - // extend your base config so you don't have to redefine your compilerOptions - "extends": "./tsconfig.json", - "include": [ - "src/**/*.ts", - "test/**/*.ts", - "typings/**/*.ts", - // etc - - // if you have a mixed JS/TS codebase, don't forget to include your JS files - "src/**/*.js" - ] - } - ``` - -### `parserOptions.tsconfigRootDir` - -Default `undefined`. - -This option allows you to provide the root directory for relative tsconfig paths specified in the `project` option above. - -### `parserOptions.projectFolderIgnoreList` - -Default `["**/node_modules/**"]`. - -This option allows you to ignore folders from being included in your provided list of `project`s. -This is useful if you have configured glob patterns, but want to make sure you ignore certain folders. - -It accepts an array of globs to exclude from the `project` globs. - -For example, by default it will ensure that a glob like `./**/tsconfig.json` will not match any `tsconfig`s within your `node_modules` folder (some npm packages do not exclude their source files from their published packages). - -### `parserOptions.extraFileExtensions` - -Default `undefined`. - -This option allows you to provide one or more additional file extensions which should be considered in the TypeScript Program compilation. -The default extensions are `['.js', '.mjs', '.cjs', '.jsx', '.ts', '.mts', '.cts', '.tsx']`. -Add extensions starting with `.`, followed by the file extension. E.g. for a `.vue` file use `"extraFileExtensions": [".vue"]`. - -### `parserOptions.warnOnUnsupportedTypeScriptVersion` - -Default `true`. - -This option allows you to toggle the warning that the parser will give you if you use a version of TypeScript which is not explicitly supported - -### `parserOptions.createDefaultProgram` - -Default `false`. - -This option allows you to request that when the `project` setting is specified, files will be allowed when not included in the projects defined by the provided `tsconfig.json` files. **Using this option will incur significant performance costs. This option is primarily included for backwards-compatibility.** See the **`project`** section above for more information. - -### `parserOptions.programs` - -Default `undefined`. - -This option allows you to programmatically provide an array of one or more instances of a TypeScript Program object that will provide type information to rules. -This will override any programs that would have been computed from `parserOptions.project` or `parserOptions.createDefaultProgram`. -All linted files must be part of the provided program(s). - -### `parserOptions.moduleResolver` - -Default `undefined`. - -This option allows you to provide a custom module resolution. The value should point to a JS file that default exports (`export default`, or `module.exports =`, or `export =`) a file with the following interface: - -```ts -interface ModuleResolver { - version: 1; - resolveModuleNames( - moduleNames: string[], - containingFile: string, - reusedNames: string[] | undefined, - redirectedReference: ts.ResolvedProjectReference | undefined, - options: ts.CompilerOptions, - ): (ts.ResolvedModule | undefined)[]; -} -``` - -[Refer to the TypeScript Wiki for an example on how to write the `resolveModuleNames` function](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API#customizing-module-resolution). - -Note that if you pass custom programs via `options.programs` this option will not have any effect over them (you can simply add the custom resolution on them directly). - -### `parserOptions.emitDecoratorMetadata` - -Default `undefined`. - -This option allow you to tell parser to act as if `emitDecoratorMetadata: true` is set in `tsconfig.json`, but without [type-aware linting](https://typescript-eslint.io/docs/linting/typed-linting). In other words, you don't have to specify `parserOptions.project` in this case, making the linting process faster. - -## Utilities - -### `createProgram(configFile, projectDirectory)` - -This serves as a utility method for users of the `parserOptions.programs` feature to create a TypeScript program instance from a config file. - -```ts -declare function createProgram( - configFile: string, - projectDirectory?: string, -): import('typescript').Program; -``` - -Example usage in .eslintrc.js: - -```js -const parser = require('@typescript-eslint/parser'); -const programs = [parser.createProgram('tsconfig.json')]; -module.exports = { - parserOptions: { - programs, - }, -}; -``` - -## Supported TypeScript Version - -Please see [`typescript-eslint`](https://github.com/typescript-eslint/typescript-eslint) for the supported TypeScript version. - -**Please ensure that you are using a supported version before submitting any issues/bug reports.** - -## Reporting Issues - -Please use the `@typescript-eslint/parser` issue template when creating your issue and fill out the information requested as best you can. This will really help us when looking into your issue. - -## License - -TypeScript ESLint Parser is licensed under a permissive BSD 2-clause license. - -## Contributing - -[See the contributing guide here](../../CONTRIBUTING.md) +> See https://typescript-eslint.io for general documentation on typescript-eslint, the tooling that allows you to run ESLint and Prettier on TypeScript code. diff --git a/packages/scope-manager/README.md b/packages/scope-manager/README.md index b0a745f3fa53..0258932e390a 100644 --- a/packages/scope-manager/README.md +++ b/packages/scope-manager/README.md @@ -1,120 +1,8 @@ -

TypeScript Scope Manager

+# `@typescript-eslint/scope-manager` -

- CI - NPM Version - NPM Downloads -

+[![NPM Version](https://img.shields.io/npm/v/@typescript-eslint/scope-manager.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/scope-manager) +[![NPM Downloads](https://img.shields.io/npm/dm/@typescript-eslint/scope-manager.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/scope-manager) -This is a fork of [`eslint-scope`](https://github.com/eslint/eslint-scope), enhanced to support TypeScript functionality. -[You can view the original license for the code here](https://github.com/eslint/eslint-scope/blob/dbddf14d5771b21b5da704213e4508c660ca1c64/LICENSE). +👉 See **https://typescript-eslint.io/architecture/scope-manager** for documentation on this package. -This package is consumed automatically by [`@typescript-eslint/parser`](../parser). -You probably don't want to use it directly. - -## Getting Started - -**[You can find our Getting Started docs here](https://typescript-eslint.io/docs)** - -## Installation - -```bash -$ yarn add -D typescript @typescript-eslint/scope-manager -$ npm i --save-dev typescript @typescript-eslint/scope-manager -``` - -## API - -### `analyze(tree, options)` - -Analyses a given AST and returns the resulting `ScopeManager`. - -```ts -interface AnalyzeOptions { - /** - * Known visitor keys. - */ - childVisitorKeys?: Record | null; - - /** - * Which ECMAScript version is considered. - * Defaults to `2018`. - * `'latest'` is converted to 1e8 at parser. - */ - ecmaVersion?: EcmaVersion | 1e8; - - /** - * Whether the whole script is executed under node.js environment. - * When enabled, the scope manager adds a function scope immediately following the global scope. - * Defaults to `false`. - */ - globalReturn?: boolean; - - /** - * Implied strict mode (if ecmaVersion >= 5). - * Defaults to `false`. - */ - impliedStrict?: boolean; - - /** - * The identifier that's used for JSX Element creation (after transpilation). - * This should not be a member expression - just the root identifier (i.e. use "React" instead of "React.createElement"). - * Defaults to `"React"`. - */ - jsxPragma?: string; - - /** - * The identifier that's used for JSX fragment elements (after transpilation). - * If `null`, assumes transpilation will always use a member on `jsxFactory` (i.e. React.Fragment). - * This should not be a member expression - just the root identifier (i.e. use "h" instead of "h.Fragment"). - * Defaults to `null`. - */ - jsxFragmentName?: string | null; - - /** - * The lib used by the project. - * This automatically defines a type variable for any types provided by the configured TS libs. - * For more information, see https://www.typescriptlang.org/tsconfig#lib - * - * Defaults to the lib for the provided `ecmaVersion`. - */ - lib?: Lib[]; - - /** - * The source type of the script. - */ - sourceType?: 'script' | 'module'; - - /** - * Emit design-type metadata for decorated declarations in source. - * Defaults to `false`. - */ - emitDecoratorMetadata?: boolean; -} -``` - -Example usage: - -```ts -import { analyze } from '@typescript-eslint/scope-manager'; -import { parse } from '@typescript-eslint/typescript-estree'; - -const code = `const hello: string = 'world';`; -const ast = parse(code, { - // note that scope-manager requires ranges on the AST - range: true, -}); -const scope = analyze(ast, { - ecmaVersion: 2020, - sourceType: 'module', -}); -``` - -## References - -- https://eslint.org/docs/developer-guide/scope-manager-interface -- https://github.com/eslint/eslint-scope - -## Contributing - -[See the contributing guide here](../../CONTRIBUTING.md) +> See https://typescript-eslint.io for general documentation on typescript-eslint, the tooling that allows you to run ESLint and Prettier on TypeScript code. diff --git a/packages/scope-manager/src/analyze.ts b/packages/scope-manager/src/analyze.ts index e227d1e45ad3..8e8e0d83406f 100644 --- a/packages/scope-manager/src/analyze.ts +++ b/packages/scope-manager/src/analyze.ts @@ -6,9 +6,9 @@ import type { ReferencerOptions } from './referencer'; import { Referencer } from './referencer'; import { ScopeManager } from './ScopeManager'; -//////////////////////////////////////////////////// -// MAKE SURE THIS IS KEPT IN SYNC WITH THE README // -//////////////////////////////////////////////////// +////////////////////////////////////////////////////////// +// MAKE SURE THIS IS KEPT IN SYNC WITH THE WEBSITE DOCS // +////////////////////////////////////////////////////////// interface AnalyzeOptions { /** diff --git a/packages/shared-fixtures/README.md b/packages/shared-fixtures/README.md index 866a6e866149..eb3bceabc7f8 100644 --- a/packages/shared-fixtures/README.md +++ b/packages/shared-fixtures/README.md @@ -1,7 +1,10 @@ -

Fixtures for Testing typescript-eslint

+# `@typescript-eslint/shared-fixtures` -

Code fixtures used to test the parser. This is not intended for external use.

+> Code fixtures used to test the `typescript-estree` parser. -

- CI -

+## ✋ Internal Package + +This is an _internal package_ to the [typescript-eslint monorepo](https://github.com/typescript-eslint/typescript-eslint). +You likely don't want to use it directly. + +👉 See **https://typescript-eslint.io** for docs on typescript-eslint. diff --git a/packages/shared-fixtures/package.json b/packages/shared-fixtures/package.json index cec6cebc6483..8a1ce8995d39 100644 --- a/packages/shared-fixtures/package.json +++ b/packages/shared-fixtures/package.json @@ -1,4 +1,5 @@ { + "description": "Code fixtures used to test the typescript-estree parser.", "name": "@typescript-eslint/shared-fixtures", "version": "5.43.0", "private": true diff --git a/packages/type-utils/README.md b/packages/type-utils/README.md index 19a4bf7e964d..2f842e803cc5 100644 --- a/packages/type-utils/README.md +++ b/packages/type-utils/README.md @@ -1,15 +1,12 @@ -

Type utils for ESLint Plugins

+# `@typescript-eslint/type-utils` -

Type utilities for working with TypeScript within ESLint rules.

+> Type utilities for working with TypeScript within ESLint rules. -

- CI - NPM Version - NPM Downloads -

+The utilities in this package are separated from `@typescript-eslint/utils` so that that package does not require a dependency on `typescript`. -This utilities in this package are separated from `@typescript-eslint/utils` so that that package does not require a dependency on `typescript`. +## ✋ Internal Package -## Contributing +This is an _internal package_ to the [typescript-eslint monorepo](https://github.com/typescript-eslint/typescript-eslint). +You likely don't want to use it directly. -[See the contributing guide here](../../CONTRIBUTING.md) +👉 See **https://typescript-eslint.io** for docs on typescript-eslint. diff --git a/packages/types/README.md b/packages/types/README.md index 273ac71a9368..7a3008bb982a 100644 --- a/packages/types/README.md +++ b/packages/types/README.md @@ -1,17 +1,12 @@ -

TypeScript-ESTree Types

+# `@typescript-eslint/types` -

- CI - NPM Version - NPM Downloads -

+> Types for the TypeScript-ESTree AST spec This package exists to help us reduce cycles and provide lighter-weight packages at runtime. -You probably don't want to use it directly. -If you're building an ESLint plugin, consider using [`@typescript-eslint/utils`](../utils). -If you're parsing TypeScript code, consider using [`@typescript-eslint/typescript-estree`](../typescript-estree). +## ✋ Internal Package -## Contributing +This is an _internal package_ to the [typescript-eslint monorepo](https://github.com/typescript-eslint/typescript-eslint). +You likely don't want to use it directly. -[See the contributing guide here](../../CONTRIBUTING.md) +👉 See **https://typescript-eslint.io** for docs on typescript-eslint. diff --git a/packages/typescript-estree/README.md b/packages/typescript-estree/README.md index cb1d0d0312c7..4ce7f1e7cf4e 100644 --- a/packages/typescript-estree/README.md +++ b/packages/typescript-estree/README.md @@ -1,383 +1,10 @@ -

TypeScript ESTree

+# `@typescript-eslint/typescript-estree` -

A parser that converts TypeScript source code into an ESTree-compatible form

- -

- CI - NPM Version - NPM Downloads -

- -## Getting Started - -**[You can find our Getting Started docs here](https://typescript-eslint.io/docs)** - -## About - -This parser is somewhat generic and robust, and could be used to power any use-case which requires taking TypeScript source code and producing an ESTree-compatible AST. - -In fact, it is already used within these hyper-popular open-source projects to power their TypeScript support: - -- [ESLint](https://eslint.org), the pluggable linting utility for JavaScript and JSX -- [Prettier](https://prettier.io), an opinionated code formatter - -## Installation - -```sh -yarn add -D @typescript-eslint/typescript-estree -``` - -## API - -### Parsing - -#### `parse(code, options)` - -Parses the given string of code with the options provided and returns an ESTree-compatible AST. - -```ts -interface ParseOptions { - /** - * create a top-level comments array containing all comments - */ - comment?: boolean; - - /** - * An array of modules to turn explicit debugging on for. - * - 'typescript-eslint' is the same as setting the env var `DEBUG=typescript-eslint:*` - * - 'eslint' is the same as setting the env var `DEBUG=eslint:*` - * - 'typescript' is the same as setting `extendedDiagnostics: true` in your tsconfig compilerOptions - * - * For convenience, also supports a boolean: - * - true === ['typescript-eslint'] - * - false === [] - */ - debugLevel?: boolean | ('typescript-eslint' | 'eslint' | 'typescript')[]; - - /** - * Cause the parser to error if it encounters an unknown AST node type (useful for testing). - * This case only usually occurs when TypeScript releases new features. - */ - errorOnUnknownASTType?: boolean; - - /** - * Absolute (or relative to `cwd`) path to the file being parsed. - */ - filePath?: string; - - /** - * Enable parsing of JSX. - * For more details, see https://www.typescriptlang.org/docs/handbook/jsx.html - * - * NOTE: this setting does not effect known file types (.js, .cjs, .mjs, .jsx, .ts, .mts, .cts, .tsx, .json) because the - * TypeScript compiler has its own internal handling for known file extensions. - * - * For the exact behavior, see https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser#parseroptionsecmafeaturesjsx - */ - jsx?: boolean; - - /** - * Controls whether the `loc` information to each node. - * The `loc` property is an object which contains the exact line/column the node starts/ends on. - * This is similar to the `range` property, except it is line/column relative. - */ - loc?: boolean; - - /* - * Allows overriding of function used for logging. - * When value is `false`, no logging will occur. - * When value is not provided, `console.log()` will be used. - */ - loggerFn?: Function | false; - - /** - * Controls whether the `range` property is included on AST nodes. - * The `range` property is a [number, number] which indicates the start/end index of the node in the file contents. - * This is similar to the `loc` property, except this is the absolute index. - */ - range?: boolean; - - /** - * Set to true to create a top-level array containing all tokens from the file. - */ - tokens?: boolean; -} - -const PARSE_DEFAULT_OPTIONS: ParseOptions = { - comment: false, - errorOnUnknownASTType: false, - filePath: 'estree.ts', // or 'estree.tsx', if you pass jsx: true - jsx: false, - loc: false, - loggerFn: undefined, - range: false, - tokens: false, -}; - -declare function parse( - code: string, - options: ParseOptions = PARSE_DEFAULT_OPTIONS, -): TSESTree.Program; -``` - -Example usage: - -```js -import { parse } from '@typescript-eslint/typescript-estree'; - -const code = `const hello: string = 'world';`; -const ast = parse(code, { - loc: true, - range: true, -}); -``` - -#### `parseAndGenerateServices(code, options)` - -Parses the given string of code with the options provided and returns an ESTree-compatible AST. Accepts additional options which can be used to generate type information along with the AST. - -```ts -interface ParseAndGenerateServicesOptions extends ParseOptions { - /** - * Causes the parser to error if the TypeScript compiler returns any unexpected syntax/semantic errors. - */ - errorOnTypeScriptSyntacticAndSemanticIssues?: boolean; - - /** - * ***EXPERIMENTAL FLAG*** - Use this at your own risk. - * - * Causes TS to use the source files for referenced projects instead of the compiled .d.ts files. - * This feature is not yet optimized, and is likely to cause OOMs for medium to large projects. - * - * This flag REQUIRES at least TS v3.9, otherwise it does nothing. - * - * See: https://github.com/typescript-eslint/typescript-eslint/issues/2094 - */ - EXPERIMENTAL_useSourceOfProjectReferenceRedirect?: boolean; - - /** - * When `project` is provided, this controls the non-standard file extensions which will be parsed. - * It accepts an array of file extensions, each preceded by a `.`. - */ - extraFileExtensions?: string[]; - - /** - * Absolute (or relative to `tsconfigRootDir`) path to the file being parsed. - * When `project` is provided, this is required, as it is used to fetch the file from the TypeScript compiler's cache. - */ - filePath?: string; - - /** - * Allows the user to control whether or not two-way AST node maps are preserved - * during the AST conversion process. - * - * By default: the AST node maps are NOT preserved, unless `project` has been specified, - * in which case the maps are made available on the returned `parserServices`. - * - * NOTE: If `preserveNodeMaps` is explicitly set by the user, it will be respected, - * regardless of whether or not `project` is in use. - */ - preserveNodeMaps?: boolean; - - /** - * Absolute (or relative to `tsconfigRootDir`) paths to the tsconfig(s). - * If this is provided, type information will be returned. - */ - project?: string | string[]; - - /** - * If you provide a glob (or globs) to the project option, you can use this option to ignore certain folders from - * being matched by the globs. - * This accepts an array of globs to ignore. - * - * By default, this is set to ["/node_modules/"] - */ - projectFolderIgnoreList?: string[]; - - /** - * The absolute path to the root directory for all provided `project`s. - */ - tsconfigRootDir?: string; - - /** - * An array of one or more instances of TypeScript Program objects to be used for type information. - * This overrides any program or programs that would have been computed from the `project` option. - * All linted files must be part of the provided program(s). - */ - programs?: Program[]; - - /** - *************************************************************************************** - * IT IS RECOMMENDED THAT YOU DO NOT USE THIS OPTION, AS IT CAUSES PERFORMANCE ISSUES. * - *************************************************************************************** - * - * When passed with `project`, this allows the parser to create a catch-all, default program. - * This means that if the parser encounters a file not included in any of the provided `project`s, - * it will not error, but will instead parse the file and its dependencies in a new program. - */ - createDefaultProgram?: boolean; - - /** - * ESLint (and therefore typescript-eslint) is used in both "single run"/one-time contexts, - * such as an ESLint CLI invocation, and long-running sessions (such as continuous feedback - * on a file in an IDE). - * - * When typescript-eslint handles TypeScript Program management behind the scenes, this distinction - * is important because there is significant overhead to managing the so called Watch Programs - * needed for the long-running use-case. - * - * When allowAutomaticSingleRunInference is enabled, we will use common heuristics to infer - * whether or not ESLint is being used as part of a single run. - */ - allowAutomaticSingleRunInference?: boolean; - - /** - * Path to a file exporting a custom ModuleResolver. - */ - moduleResolver?: string; -} - -interface ParserServices { - program: ts.Program; - esTreeNodeToTSNodeMap: WeakMap; - tsNodeToESTreeNodeMap: WeakMap; - hasFullTypeInformation: boolean; -} - -interface ParseAndGenerateServicesResult { - ast: TSESTree.Program; - services: ParserServices; -} - -const PARSE_AND_GENERATE_SERVICES_DEFAULT_OPTIONS: ParseOptions = { - ...PARSE_DEFAULT_OPTIONS, - errorOnTypeScriptSyntacticAndSemanticIssues: false, - extraFileExtensions: [], - preserveNodeMaps: false, // or true, if you do not set this, but pass `project` - project: undefined, - projectFolderIgnoreList: ['/node_modules/'], - tsconfigRootDir: process.cwd(), -}; - -declare function parseAndGenerateServices( - code: string, - options: ParseOptions = PARSE_DEFAULT_OPTIONS, -): ParseAndGenerateServicesResult; -``` - -Example usage: - -```js -import { parseAndGenerateServices } from '@typescript-eslint/typescript-estree'; - -const code = `const hello: string = 'world';`; -const { ast, services } = parseAndGenerateServices(code, { - filePath: '/some/path/to/file/foo.ts', - loc: true, - project: './tsconfig.json', - range: true, -}); -``` - -#### `parseWithNodeMaps(code, options)` - -Parses the given string of code with the options provided and returns both the ESTree-compatible AST as well as the node maps. -This allows you to work with both ASTs without the overhead of types that may come with `parseAndGenerateServices`. - -```ts -interface ParseWithNodeMapsResult { - ast: TSESTree.Program; - esTreeNodeToTSNodeMap: ParserServices['esTreeNodeToTSNodeMap']; - tsNodeToESTreeNodeMap: ParserServices['tsNodeToESTreeNodeMap']; -} - -declare function parseWithNodeMaps( - code: string, - options: ParseOptions = PARSE_DEFAULT_OPTIONS, -): ParseWithNodeMapsResult; -``` - -Example usage: - -```js -import { parseWithNodeMaps } from '@typescript-eslint/typescript-estree'; - -const code = `const hello: string = 'world';`; -const { ast, esTreeNodeToTSNodeMap, tsNodeToESTreeNodeMap } = parseWithNodeMaps( - code, - { - loc: true, - range: true, - }, -); -``` - -### `TSESTree`, `AST_NODE_TYPES` and `AST_TOKEN_TYPES` - -Types for the AST produced by the parse functions. - -- `TSESTree` is a namespace which contains object types representing all of the AST Nodes produced by the parser. -- `AST_NODE_TYPES` is an enum which provides the values for every single AST node's `type` property. -- `AST_TOKEN_TYPES` is an enum which provides the values for every single AST token's `type` property. - -### Utilities - -#### `createProgram(configFile, projectDirectory)` - -This serves as a utility method for users of the `ParseOptions.programs` feature to create a TypeScript program instance from a config file. - -```ts -declare function createProgram( - configFile: string, - projectDirectory: string = process.cwd(), -): import('typescript').Program; -``` - -Example usage: - -```js -const tsESTree = require('@typescript-eslint/typescript-estree'); - -const program = tsESTree.createProgram('tsconfig.json'); -const code = `const hello: string = 'world';`; -const { ast, services } = parseAndGenerateServices(code, { - filePath: '/some/path/to/file/foo.ts', - loc: true, - program, - range: true, -}); -``` - -## Supported TypeScript Version - -See the [Supported TypeScript Version](../../README.md#supported-typescript-version) section in the project root. - -If you use a non-supported version of TypeScript, the parser will log a warning to the console. - -**Please ensure that you are using a supported version before submitting any issues/bug reports.** - -## Reporting Issues - -Please check the current list of open and known issues and ensure the issue has not been reported before. When creating a new issue provide as much information about your environment as possible. This includes: - -- TypeScript version -- The `typescript-estree` version - -## AST Alignment Tests - -A couple of years after work on this parser began, the TypeScript Team at Microsoft began [officially supporting TypeScript parsing via Babel](https://blogs.msdn.microsoft.com/typescript/2018/08/27/typescript-and-babel-7/). - -I work closely with the TypeScript Team and we are gradually aligning the AST of this project with the one produced by Babel's parser. To that end, I have created a full test harness to compare the ASTs of the two projects which runs on every PR, please see [the code](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/typescript-estree/tests/ast-alignment) for more details. - -## Debugging - -If you encounter a bug with the parser that you want to investigate, you can turn on the debug logging via setting the environment variable: `DEBUG=typescript-eslint:*`. -I.e. in this repo you can run: `DEBUG=typescript-eslint:* yarn lint`. - -## License - -TypeScript ESTree inherits from the the original TypeScript ESLint Parser license, as the majority of the work began there. It is licensed under a permissive BSD 2-clause license. +[![NPM Version](https://img.shields.io/npm/v/@typescript-eslint/typescript-estree.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/utils) +[![NPM Downloads](https://img.shields.io/npm/dm/@typescript-eslint/typescript-estree.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/utils) ## Contributing -[See the contributing guide here](../../CONTRIBUTING.md) +👉 See **https://typescript-eslint.io/architecture/typescript-estree** for documentation on this package. + +> See https://typescript-eslint.io for general documentation on typescript-eslint, the tooling that allows you to run ESLint and Prettier on TypeScript code. diff --git a/packages/typescript-estree/src/create-program/createProjectProgram.ts b/packages/typescript-estree/src/create-program/createProjectProgram.ts index 326100d35784..7313573b6ab6 100644 --- a/packages/typescript-estree/src/create-program/createProjectProgram.ts +++ b/packages/typescript-estree/src/create-program/createProjectProgram.ts @@ -105,7 +105,7 @@ function createProjectProgram( `- Change ESLint's list of included files to not include this file`, `- Change ${describedSpecifiers} to include this file`, `- Create a new TSConfig that includes this file and include it in your parserOptions.project`, - `See the TypeScript ESLint docs for more info: https://typescript-eslint.io/docs/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file`, + `See the TypeScript ESLint docs for more info: https://typescript-eslint.io/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file`, ); } diff --git a/packages/typescript-estree/src/parseSettings/warnAboutTSVersion.ts b/packages/typescript-estree/src/parseSettings/warnAboutTSVersion.ts index ad9a74157d6c..191ac029325a 100644 --- a/packages/typescript-estree/src/parseSettings/warnAboutTSVersion.ts +++ b/packages/typescript-estree/src/parseSettings/warnAboutTSVersion.ts @@ -3,8 +3,8 @@ import * as ts from 'typescript'; import type { ParseSettings } from './index'; /** - * This needs to be kept in sync with the top-level README.md in the - * typescript-eslint monorepo + * This needs to be kept in sync with /docs/maintenance/VERSIONING.md + * in the typescript-eslint monorepo */ const SUPPORTED_TYPESCRIPT_VERSIONS = '>=3.3.1 <5.0.0'; diff --git a/packages/typescript-estree/src/parser-options.ts b/packages/typescript-estree/src/parser-options.ts index cec95c3b413d..632d9e6ae883 100644 --- a/packages/typescript-estree/src/parser-options.ts +++ b/packages/typescript-estree/src/parser-options.ts @@ -3,9 +3,9 @@ import type * as ts from 'typescript'; import type { TSESTree, TSESTreeToTSNode, TSNode, TSToken } from './ts-estree'; -//////////////////////////////////////////////////// -// MAKE SURE THIS IS KEPT IN SYNC WITH THE README // -//////////////////////////////////////////////////// +////////////////////////////////////////////////////////// +// MAKE SURE THIS IS KEPT IN SYNC WITH THE WEBSITE DOCS // +////////////////////////////////////////////////////////// interface ParseOptions { /** diff --git a/packages/typescript-estree/tests/lib/__snapshots__/parse.test.ts.snap b/packages/typescript-estree/tests/lib/__snapshots__/parse.test.ts.snap index 81341b5e35f2..108fdad11a14 100644 --- a/packages/typescript-estree/tests/lib/__snapshots__/parse.test.ts.snap +++ b/packages/typescript-estree/tests/lib/__snapshots__/parse.test.ts.snap @@ -23,7 +23,7 @@ However, that TSConfig does not include this file. Either: - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project -See the TypeScript ESLint docs for more info: https://typescript-eslint.io/docs/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" +See the TypeScript ESLint docs for more info: https://typescript-eslint.io/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `; exports[`parseAndGenerateServices invalid file error messages "parserOptions.extraFileExtensions" is non-empty the extension matches the file isn't included 1`] = ` @@ -32,7 +32,7 @@ However, that TSConfig does not include this file. Either: - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project -See the TypeScript ESLint docs for more info: https://typescript-eslint.io/docs/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" +See the TypeScript ESLint docs for more info: https://typescript-eslint.io/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `; exports[`parseAndGenerateServices invalid file error messages project includes errors for not included files 1`] = ` @@ -41,7 +41,7 @@ However, that TSConfig does not include this file. Either: - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project -See the TypeScript ESLint docs for more info: https://typescript-eslint.io/docs/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" +See the TypeScript ESLint docs for more info: https://typescript-eslint.io/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `; exports[`parseAndGenerateServices invalid file error messages project includes errors for not included files 2`] = ` @@ -50,7 +50,7 @@ However, that TSConfig does not include this file. Either: - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project -See the TypeScript ESLint docs for more info: https://typescript-eslint.io/docs/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" +See the TypeScript ESLint docs for more info: https://typescript-eslint.io/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `; exports[`parseAndGenerateServices invalid file error messages project includes errors for not included files 3`] = ` @@ -59,7 +59,7 @@ However, that TSConfig does not include this file. Either: - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project -See the TypeScript ESLint docs for more info: https://typescript-eslint.io/docs/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" +See the TypeScript ESLint docs for more info: https://typescript-eslint.io/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `; exports[`parseAndGenerateServices invalid file error messages project includes errors for not included files 4`] = ` @@ -68,7 +68,7 @@ However, that TSConfig does not include this file. Either: - Change ESLint's list of included files to not include this file - Change that TSConfig to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project -See the TypeScript ESLint docs for more info: https://typescript-eslint.io/docs/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" +See the TypeScript ESLint docs for more info: https://typescript-eslint.io/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `; exports[`parseAndGenerateServices invalid project error messages throws when non of multiple projects include the file 1`] = ` @@ -79,7 +79,7 @@ However, none of those TSConfigs include this file. Either: - Change ESLint's list of included files to not include this file - Change one of those TSConfigs to include this file - Create a new TSConfig that includes this file and include it in your parserOptions.project -See the TypeScript ESLint docs for more info: https://typescript-eslint.io/docs/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" +See the TypeScript ESLint docs for more info: https://typescript-eslint.io/linting/troubleshooting##i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file" `; exports[`parseAndGenerateServices isolated parsing should parse .js file - with JSX content - parserOptions.jsx = false 1`] = ` diff --git a/packages/utils/README.md b/packages/utils/README.md index d517cc457a53..8013675d9625 100644 --- a/packages/utils/README.md +++ b/packages/utils/README.md @@ -1,27 +1,10 @@ -

Utils for ESLint Plugins

+# `@typescript-eslint/utils` -

Utilities for working with TypeScript + ESLint together.

+> Utilities for working with TypeScript + ESLint together. -

- CI - NPM Version - NPM Downloads -

+[![NPM Version](https://img.shields.io/npm/v/@typescript-eslint/utils.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/utils) +[![NPM Downloads](https://img.shields.io/npm/dm/@typescript-eslint/utils.svg?style=flat-square)](https://www.npmjs.com/package/@typescript-eslint/utils) -## Exports +👉 See **https://typescript-eslint.io/architecture/utils** for documentation on this package. -| Name | Description | -| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`ASTUtils`](./src/ast-utils) | Tools for operating on the ESTree AST. Also includes the [`eslint-utils`](https://www.npmjs.com/package/eslint-utils) package, correctly typed to work with the types found in `TSESTree` | -| [`ESLintUtils`](./src/eslint-utils) | Tools for creating ESLint rules with TypeScript. | -| `JSONSchema` | Types from the [`@types/json-schema`](https://www.npmjs.com/package/@types/json-schema) package, re-exported to save you having to manually import them. Also ensures you're using the same version of the types as this package. | -| [`TSESLint`](./src/ts-eslint) | Types for ESLint, correctly typed to work with the types found in `TSESTree`. | -| [`TSESLintScope`](./src/ts-eslint-scope) | The [`eslint-scope`](https://www.npmjs.com/package/eslint-scope) package, correctly typed to work with the types found in both `TSESTree` and `TSESLint` | -| [`TSESTree`](../types/src/ts-estree.ts) | Types for the TypeScript flavor of ESTree created by `@typescript-eslint/typescript-estree`. | -| [`AST_NODE_TYPES`](../types/src/ast-node-types.ts) | An enum with the names of every single _node_ found in `TSESTree`. | -| [`AST_TOKEN_TYPES`](../types/src/ast-token-types.ts) | An enum with the names of every single _token_ found in `TSESTree`. | -| [`ParserServices`](../typescript-estree/src/parser-options.ts) | Typing for the parser services provided when parsing a file using `@typescript-eslint/typescript-estree`. | - -## Contributing - -[See the contributing guide here](../../CONTRIBUTING.md) +> See https://typescript-eslint.io for general documentation on typescript-eslint, the tooling that allows you to run ESLint and Prettier on TypeScript code. diff --git a/packages/visitor-keys/README.md b/packages/visitor-keys/README.md index 839c20c4954d..1745172a6f20 100644 --- a/packages/visitor-keys/README.md +++ b/packages/visitor-keys/README.md @@ -1,13 +1,10 @@ -

TypeScript-ESTree Visitor Keys

+# `@typescript-eslint/visitor-keys` -

Visitor keys used to help traverse the TypeScript-ESTree AST

+> Visitor keys used to help traverse the TypeScript-ESTree AST. -

- CI - NPM Version - NPM Downloads -

+## ✋ Internal Package -## Contributing +This is an _internal package_ to the [typescript-eslint monorepo](https://github.com/typescript-eslint/typescript-eslint). +You likely don't want to use it directly. -[See the contributing guide here](../../CONTRIBUTING.md) +👉 See **https://typescript-eslint.io** for docs on typescript-eslint. diff --git a/packages/website/docusaurusConfig.ts b/packages/website/docusaurusConfig.ts index 0ef589b005a2..9e8c5e3bcf3a 100644 --- a/packages/website/docusaurusConfig.ts +++ b/packages/website/docusaurusConfig.ts @@ -44,7 +44,7 @@ const presetClassicOptions: PresetClassicOptions = { const pluginContentDocsOptions: PluginContentDocsOptions = { id: 'base-docs', path: '../../docs', - routeBasePath: 'docs', + routeBasePath: '/', sidebarPath: require.resolve('./sidebars/sidebar.base.js'), editUrl: `${githubUrl}/edit/main/packages/website/`, beforeDefaultRemarkPlugins, @@ -74,20 +74,17 @@ const themeConfig: ThemeCommonConfig & AlgoliaThemeConfig = { }, items: [ { - to: 'docs/', - activeBasePath: 'docs', + to: 'getting-started/', label: 'Getting started', position: 'left', }, { to: 'rules/', - activeBasePath: 'rules', label: 'Rules', position: 'left', }, { to: 'blog/', - activeBasePath: 'blog', label: 'Blog', position: 'left', }, diff --git a/packages/website/plugins/generated-rule-docs.ts b/packages/website/plugins/generated-rule-docs.ts index 04f35189f5cf..37bd4e02cc40 100644 --- a/packages/website/plugins/generated-rule-docs.ts +++ b/packages/website/plugins/generated-rule-docs.ts @@ -80,7 +80,7 @@ export const generatedRuleDocs: Plugin = () => { We strongly recommend you do not use this rule or any other formatting linter rules. Use a separate dedicated formatter instead. - See What About Formatting? for more information. + See What About Formatting? for more information. `, type: 'jsx', diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js index fbad9c43b0a5..89fa0e543f36 100644 --- a/packages/website/sidebars/sidebar.base.js +++ b/packages/website/sidebars/sidebar.base.js @@ -35,22 +35,37 @@ module.exports = { label: 'Getting Started', type: 'category', }, + 'custom-rules', { + items: [ + 'contributing/issues', + 'contributing/local-development', + 'contributing/pull-requests', + ], + label: 'Contributing', + link: { + id: 'contributing', + type: 'doc', + }, type: 'category', - label: 'Development', - collapsible: false, + }, + { items: [ - { - label: 'Architecture', - type: 'category', - collapsible: false, - items: ['development/architecture/packages'], - }, - 'development/custom-rules', + 'architecture/eslint-plugin', + 'architecture/eslint-plugin-tslint', + 'architecture/parser', + 'architecture/scope-manager', + 'architecture/typescript-estree', + 'architecture/utils', ], + label: 'Architecture', + link: { + id: 'architecture', + type: 'doc', + }, + type: 'category', }, { - collapsible: false, items: [ 'maintenance/issues', 'maintenance/pull-requests', diff --git a/packages/website/src/pages/index.tsx b/packages/website/src/pages/index.tsx index 8dc318973cdc..c66571392d4e 100644 --- a/packages/website/src/pages/index.tsx +++ b/packages/website/src/pages/index.tsx @@ -119,7 +119,10 @@ function Feature({ title, description }: FeatureItem): JSX.Element {

{description}

- + Get Started
@@ -138,7 +141,7 @@ function Home(): JSX.Element {
Get Started diff --git a/packages/website/src/theme/MDXComponents/RuleAttributes.tsx b/packages/website/src/theme/MDXComponents/RuleAttributes.tsx index e0351d743c7b..075d0a6af8e1 100644 --- a/packages/website/src/theme/MDXComponents/RuleAttributes.tsx +++ b/packages/website/src/theme/MDXComponents/RuleAttributes.tsx @@ -89,7 +89,7 @@ export function RuleAttributes({ name }: { name: string }): React.ReactNode { children: ( <> This rule requires{' '} - + type information {' '} to run.