Evaluate the project, projectService, and root workspace configuration requirement for Angular

[TrevorKarjanis]

Describe the issue
Originally #173

I want to do a further evaluation of the necessity for the project configuration and the effect of only using the root tsconfig.json. I expect this mostly includes the configurations not accounted for in the other TS configuration files, e.g. the application, test specs, and library files.

We'll need to upstream identified issues and recommendations to angular/eslint, likely in the form of a bug report. There is some existing commentary about the projectService configuration (issues angular-eslint/angular-eslint#1872 (comment) and angular-eslint/angular-eslint#609 (comment)).

Additionally, Ravi informed me that a root workspace configuration is required even if the workspace is made up only of projects. This should be evaluated as well.

At least the following can be completed and information can be documented in this bug report.

1. Generate a new workspace with the latest version of Angular.
   • This workspace will have one root project.
2. Install and run the schematic for angular-eslint.
3. Document any notable characteristics of the default generated configuration.
4. Apply the rest of this style guide as documented in the README.
5. Document notable effects of using the projectService configuration with a root and child projects.
   • Consider evaluating the tool source to develop expectations for the identification of tsconfig files with projectService.
   • Which TS configurations are used for the root project?
   • Which TS configurations are used for the child projects?
   • Are the TS configurations for tests used?
6. Document notable effects of using the project configuration.
7. Attempt to configure the workspace without a root configuration and the document the results.

[TrevorKarjanis]

Research Results

The following results from research are provided to answer the questions outlined in the bug report. It has been determined from this research that no further work items are required. An upstream to angular-eslint, as originally suggested in #173, is not necessary, because angular-eslint does not require type checking by default. Therefore, the results below mostly pertain to typescript-eslint and Angular CLI. However, the summary outlines best practices to follow when configuring Angular and ESLint with type checking.

Summary

• A root ESLint configuration file is required in an Angular workspace for ng lint even if there are only projects with their own configuration file.
• The root tsconfig.json will include all of the application and test files by default.
• The VS Code TS server uses the project service which only uses one TS configuration file, the root tsconfig.json.
  • This can lead to discrepancies if there are differences between the root TS configuration and application and project configurations.
• VS Code ESLint and ng lint use the languageOptions.parserOptions ESLint configuration, not the VS Code TS server.
• languageOptions.parserOptions.projectService does not work in workspaces with projects.
• languageOptions.parserOptions.project has an order of precedence.
• The root tsconfig.json can be excluded from the ESLint project configuration if all TS files targeted by ESLint and not already included in tsconfig.app.json or tsconfig.spec.json are added, e.g. src/environments/environments.prod.ts.
• languageOptions.parserOptions.tsconfigRootDir is not required in the root configuration.
• A value of import.meta.dirname is required for tsconfigRootDir in projects.
• Upstream roadmap: "Our priority for the next year will be to improve the new Project Service API so that it works in all places the traditional Program API does. We won't remove the traditional project program behavior unless and until the new Project Service API is able to fully replace it."

Best Practices

• The root ESLint configuration can be empty when there are only projects but should always be included.
• Configure ESLint with languageOptions.parserOptions.project for consistency across VS Code, ng build, ng lint, and other workspaces.
• Configure languageOptions.parserOptions.tsconfigRootDir as import.meta.dirname for projects but do not define it for the root.

Default Generated Configuration

• The default ESLint configuration does not use rules that require type information, and thus neither projectService nor project are configured.
• The default configuration for lintFilePatterns in angular.json only includes TS and HTML files.
• The standalone eslint command will not function properly, because the flat configuration does not take the projects' configurations into account.
  • Fix this by adding an ignores statement to the root configuration, e.g. globalIgnores(['projects']).

NI Style Guide (requires type checking)

Root ESLint Configuration

• A root ESLint configuration file, e.g. eslint.config.mjs, is required for ng lint even if there are only projects with their own configuration file.

• VS Code ESlint functions properly in projects with or without a root ESLint configuration.

• ng lint functions properly in projects with a complete or empty ESLint configuration file at the root.

  • The file can literally be empty — no exports.

• ng lint fails with the following error for a project when there is no root ESLint configuration.

  An unhandled exception occurred: Cannot read config file: E:\Workspaces\angular-eslint-18\projects\angular-eslint-library\eslint.config.mjs
  Error: end of the stream or a document separator is expected (12:14)

TS Configuration

• The root tsconfig.json does not declare files nor include configurations.
  • By default, the root tsconfig.json includes **/* with supported extensions .ts, .tsx, .d.ts, and .js and .jsx if allowJs is true.
    • https://www.typescriptlang.org/tsconfig/#include
• The root tsconfig.json can be excluded from the ESLint languageOptions.parserOptions.project configuration if all TS files targeted by ESLint and not already included in tsconfig.app.json or tsconfig.spec.json are added, e.g. src/environments/environments.prod.ts.
• It is concluded from these tests that project has an order of precedence, the VS Code TS server uses the project service, and VS Code ESLint and ng lint use project, including the application and spec configurations when they take precedence.
  • This makes sense. The application and spec configurations are specific to Angular. VS Code would have to be explicitly configured to use these files. ESLint identifies eslint.config.ts by default and the TS configurations are configurable with project.
• languageOptions.parserOptions.projectService is recommended over project.
  • https://typescript-eslint.io/packages/parser/#project
• projectService not work in a workspace with projects, because project files are not included in the project service and allowDefaultProject does not allow ** glob patterns.
  • https://typescript-eslint.io/packages/parser/#allowdefaultproject
• projectService is supposed to be faster than project but is not necessarilly.
  • https://typescript-eslint.io/blog/project-service/#performance
• "Our priority for the next year will be to improve the new Project Service API so that it works in all places the traditional Program API does. We won't remove the traditional project program behavior unless and until the new Project Service API is able to fully replace it."
  • https://typescript-eslint.io/blog/project-service/#long-term-vision

tsconfigRootDir

• languageOptions.parserOptions.tsconfigRootDir is not required in the root configuration for VS Code ESLint, ng lint, nor eslint.
• tsconfigRootDir is required for ng lint in projects.
  • VS Code ESLint uses the correct TS configuration file for projects even when tsconfigRootDir is not set.
  • VS Code will report an error in the "Problems" tab if the TS configuration file can't be read.

Note: The results provided here are a summary of a larger set taken for all of the testing and research done. Contact me for further clarification.

@gokulprasanth-ni @jattasNI @rajsite