Improve tsconfig handling (#818)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

Author: spence-s

cli.ts

@@ -25,7 +25,7 @@ const cli = meow(
     --config          Path to a XO configuration file
     --semicolon       Use semicolons [Default: true]
     --react           Include React specific parsing and xo-react linting rules [Default: false]
-    --prettier        Format with prettier or turn off prettier conflicted rules when set to 'compat' [Default: false]
+    --prettier        Format with prettier or turn off Prettier-conflicted rules when set to 'compat' [Default: false]
     --print-config    Print the effective ESLint config for the given file
     --version         Print XO version
     --open            Open files with issues in your editor

lib/handle-ts-files.ts

@@ -33,10 +33,6 @@ export async function handleTsconfig({cwd, files}: {cwd: string; files: string[]
 
 	const fallbackTsConfigPath = path.join(cwd, 'node_modules', '.cache', cacheDirName, 'tsconfig.xo.json');
 
-	delete tsConfig.include;
-	delete tsConfig.exclude;
-	delete tsConfig.files;
-
 	tsConfig.files = unincludedFiles;
 
 	if (unincludedFiles.length > 0) {

lib/utils.ts

@@ -1,8 +1,15 @@
-import arrify from 'arrify';
-import {type SetRequired} from 'type-fest';
+import path from 'node:path';
+import micromatch from 'micromatch';
 import {type Linter} from 'eslint';
-import {allFilesGlob} from './constants.js';
+import {type SetRequired} from 'type-fest';
+import arrify from 'arrify';
+import configXoTypescript from 'eslint-config-xo-typescript';
 import {type XoConfigItem} from './types.js';
+import {
+	allFilesGlob,
+	jsExtensions,
+	jsFilesGlob,
+} from './constants.js';
 
 /**
 Convert a `xo` config item to an ESLint config item.
@@ -36,3 +43,117 @@ export const xoToEslintConfigItem = (xoConfig: XoConfigItem): SetRequired<Linter
 
 	return eslintConfig;
 };
+
+/**
+Function used to match files which should be included in the `tsconfig.json` files.
+
+@param cwd - The current working directory to resolve relative filepaths.
+@param files - The _absolute_ file paths to match against the globs.
+@param globs - The globs to match the files against.
+@param ignores - The globs to ignore when matching the files.
+@returns An array of file paths that match the globs and do not match the ignores.
+*/
+export const matchFilesForTsConfig = (cwd: string, files: string[], globs: string[], ignores: string[]) => micromatch(
+	files.map(file => path.normalize(path.relative(cwd, file))),
+	// https://github.com/micromatch/micromatch/issues/217
+	globs.map(glob => path.normalize(glob)),
+	{
+		dot: true,
+		ignore: ignores.map(file => path.normalize(file)),
+		cwd,
+	},
+).map(file => path.resolve(cwd, file));
+
+/**
+Once a config is resolved, it is pre-processed to ensure that all properties are set correctly.
+
+This includes ensuring that user-defined properties can override XO defaults, and that files are parsed correctly and performantly based on the users XO config.
+
+@param xoConfig - The flat XO config to pre-process.
+@returns The pre-processed flat XO config.
+*/
+export const preProcessXoConfig = (xoConfig: XoConfigItem[]): // eslint-disable-line complexity
+{config: XoConfigItem[]; tsFilesGlob: string[]; tsFilesIgnoresGlob: string[]} => {
+	const tsFilesGlob: string[] = [];
+	const tsFilesIgnoresGlob: string[] = [];
+
+	const processedConfig: XoConfigItem[] = [];
+
+	for (const [idx, {...config}] of xoConfig.entries()) {
+		// We can skip the first config  item, as it is the base config item.
+		if (idx === 0) {
+			processedConfig.push(config);
+			continue;
+		}
+
+		// Use TS parser/plugin for JS files if the config contains TypeScript rules which are applied to JS files.
+		// typescript-eslint rules set to "off" are ignored and not applied to JS files.
+		if (
+			config.rules
+			&& !config.languageOptions?.parser
+			&& !config.languageOptions?.parserOptions?.['project']
+			&& !config.plugins?.['@typescript-eslint']
+		) {
+			const hasTsRules = Object.entries(config.rules).some(rulePair => {
+				// If its not a @typescript-eslint rule, we don't care
+				if (!rulePair[0].startsWith('@typescript-eslint/')) {
+					return false;
+				}
+
+				if (Array.isArray(rulePair[1])) {
+					return rulePair[1]?.[0] !== 'off' && rulePair[1]?.[0] !== 0;
+				}
+
+				return rulePair[1] !== 'off'
+					&& rulePair[1] !== 0;
+			});
+
+			if (hasTsRules) {
+				let isAppliedToJsFiles = false;
+
+				if (config.files) {
+					const normalizedFiles = arrify(config.files).map(file => path.normalize(file));
+					// Strip the basename off any globs
+					const globs = normalizedFiles.map(file => micromatch.scan(file, {dot: true}).glob).filter(Boolean);
+					// Check if the files globs match a test file with a js extension
+					// If not, check that the file paths match a js extension
+					isAppliedToJsFiles = micromatch.some(jsExtensions.map(ext => `test.${ext}`), globs, {dot: true})
+						|| micromatch.some(normalizedFiles, jsFilesGlob, {dot: true});
+				} else if (config.files === undefined) {
+					isAppliedToJsFiles = true;
+				}
+
+				if (isAppliedToJsFiles) {
+					config.languageOptions ??= {};
+					config.plugins ??= {};
+					config.plugins = {
+						...config.plugins,
+						...configXoTypescript[1]?.plugins,
+					};
+					config.languageOptions.parser = configXoTypescript[1]?.languageOptions?.parser;
+					tsFilesGlob.push(...arrify(config.files ?? allFilesGlob));
+					tsFilesIgnoresGlob.push(...arrify(config.ignores));
+				}
+			}
+		}
+
+		// If a user sets the `parserOptions.project` or `projectService` or `tsconfigRootDir`, we need to ensure that the tsFilesGlob is set to exclude those files,
+		// as this indicates the user has opted out of the default TypeScript handling for those files.
+		if (
+			config.languageOptions?.parserOptions?.['project'] !== undefined
+			|| config.languageOptions?.parserOptions?.['projectService'] !== undefined
+			|| config.languageOptions?.parserOptions?.['tsconfigRootDir'] !== undefined
+		) {
+			// The glob itself should NOT be negated
+			tsFilesIgnoresGlob.push(...arrify(config.files ?? allFilesGlob));
+		}
+
+		processedConfig.push(config);
+	}
+
+	return {
+		config: processedConfig,
+		tsFilesGlob,
+		tsFilesIgnoresGlob,
+	};
+};

lib/xo.ts

@@ -6,7 +6,6 @@ import findCacheDirectory from 'find-cache-directory';
 import {globby} from 'globby';
 import arrify from 'arrify';
 import defineLazyProperty from 'define-lazy-prop';
-import micromatch from 'micromatch';
 import prettier from 'prettier';
 import {
 	type XoLintResult,
@@ -20,12 +19,11 @@ import {
 	cacheDirName,
 	allExtensions,
 	tsFilesGlob,
-	allFilesGlob,
 } from './constants.js';
 import {xoToEslintConfig} from './xo-to-eslint.js';
 import resolveXoConfig from './resolve-config.js';
 import {handleTsconfig} from './handle-ts-files.js';
-// Import {handleTsconfig} from './handle-ts-files-typescript.js';
+import {matchFilesForTsConfig, preProcessXoConfig} from './utils.js';
 
 export class Xo {
 	/**
@@ -127,7 +125,7 @@ export class Xo {
 	flatConfigPath?: string | undefined;
 
 	/**
-	If any user configs container Prettier, we will need to fetch the Prettier config.
+	If any user configs contains Prettier, we will need to fetch the Prettier config.
 	*/
 	prettier?: boolean;
 
@@ -136,6 +134,18 @@ export class Xo {
 	*/
 	prettierConfig?: prettier.Options;
 
+	/**
+	The glob pattern for TypeScript files, for which we will handle TS files and tsconfig.
+
+	We expand this based on the XO config and the files glob patterns.
+	*/
+	tsFilesGlob: string[] = [tsFilesGlob];
+
+	/**
+	We use this to also add negative glob patterns in case a user overrides the parserOptions in their XO config.
+	*/
+	tsFilesIgnoresGlob: string[] = [];
+
 	constructor(_linterOptions: LinterOptions, _baseXoConfig: XoConfigOptions = {}) {
 		this.linterOptions = _linterOptions;
 		this.baseXoConfig = _baseXoConfig;
@@ -164,63 +174,14 @@ export class Xo {
 			...this.linterOptions,
 		});
 
-		this.xoConfig = [
+		const {config, tsFilesGlob, tsFilesIgnoresGlob} = preProcessXoConfig([
 			this.baseXoConfig,
 			...flatOptions,
-		];
-
-		// Split off the TS rules in a special case, so that you won't get errors
-		// for JS files when the TS rules are not in the config.
-		this.xoConfig = this.xoConfig.flatMap(config => {
-			// If the user does not specify files, then we can assume they want everything to work correctly and
-			// for rules to apply to all files. However, TS rules will error with JS files, so we need to split them off.
-			// if the user supplies files, then we cannot make the same assumption, so we will not split them off.
-			if (config.files) {
-				return config;
-			}
-
-			const ruleEntries = Object.entries(config.rules ?? {});
-			const otherRules: Array<[string, Linter.RuleEntry]> = [];
-			const tsRules: Array<[string, Linter.RuleEntry]> = [];
-
-			for (const [rule, ruleValue] of ruleEntries) {
-				if (!rule || !ruleValue) {
-					continue;
-				}
-
-				if (rule.startsWith('@typescript-eslint')) {
-					tsRules.push([rule, ruleValue]);
-				} else {
-					otherRules.push([rule, ruleValue]);
-				}
-			}
-
-			// If no TS rules, return the config as is
-			if (tsRules.length === 0) {
-				return config;
-			}
-
-			// If there are TS rules, we need to split them off into a new config
-			const tsConfig: XoConfigItem = {
-				...config,
-				rules: Object.fromEntries(tsRules),
-			};
-
-			// Apply TS rules to all files
-			tsConfig.files = [tsFilesGlob];
-
-			const otherConfig: XoConfigItem = {
-				...config,
-				// Set the other rules to the original config
-				rules: Object.fromEntries(otherRules),
-			};
-
-			// These rules should still apply to all files
-			otherConfig.files = [allFilesGlob];
-
-			return [tsConfig, otherConfig];
-		});
+		]);
 
+		this.xoConfig = config;
+		this.tsFilesGlob.push(...tsFilesGlob);
+		this.tsFilesIgnoresGlob.push(...tsFilesIgnoresGlob);
 		this.prettier = this.xoConfig.some(config => config.prettier);
 		this.prettierConfig = await prettier.resolveConfig(flatConfigPath, {editorconfig: true}) ?? {};
 		this.flatConfigPath = flatConfigPath;
@@ -278,7 +239,7 @@ export class Xo {
 			return;
 		}
 
-		const tsFiles = files.filter(file => micromatch.isMatch(file, tsFilesGlob, {dot: true}));
+		const tsFiles = matchFilesForTsConfig(this.linterOptions.cwd, files, this.tsFilesGlob, this.tsFilesIgnoresGlob);
 
 		if (tsFiles.length === 0) {
 			return;

readme.md

@@ -34,7 +34,7 @@ It uses [ESLint](https://eslint.org) underneath, so issues regarding built-in ru
 - Open all files with errors at the correct line in your editor with `$ xo --open`.
 - Specify [indent](#space) and [semicolon](#semicolon) preferences easily without messing with the rule config.
 - Optionally use the [Prettier](https://github.com/prettier/prettier) code style or turn off all Prettier rules with the `compat` option.
-- Optionally use `eslint-config-xo-react` for easy jsx and react linting with zero config.
+- Optionally use `eslint-config-xo-react` for easy JSX and React linting with zero config.
 - Optionally use with ESLint [directly](#usage-as-an-eslint-configuration)
 - Great [editor plugins](#editor-plugins).
 
@@ -63,7 +63,7 @@ $ xo --help
 		--config          Path to a XO configuration file
 		--semicolon       Use semicolons [Default: true]
 		--react           Include React specific parsing and xo-react linting rules [Default: false]
-		--prettier        Format with prettier or turn off prettier conflicted rules when set to 'compat' [Default: false]
+		--prettier        Format with prettier or turn off prettier-conflicted rules when set to 'compat' [Default: false]
 		--print-config    Print the effective ESLint config for the given file
 		--version         Print XO version
 		--open            Open files with issues in your editor
@@ -108,7 +108,7 @@ Simply run `$ npm init xo` (with any options) to add XO to create an `xo.config.
 
 ## Config
 
-You can configure XO options by creating an `xo.config.js` or an `xo.config.ts` file in the root directory of your project. XO supports all js/ts file extensions (js,cjs,mjs,ts,cts,mts) automatically. A XO config is an extension of ESLint's Flat Config. Like ESLint, an XO config exports an array of XO config objects. XO config objects extend [ESLint Configuration Objects](https://eslint.org/docs/latest/use/configure/configuration-files#configuration-objects). This means all the available configuration params for ESLint also work for `XO`. However, `XO` enhances and adds extra params to the configuration objects to make them easier to work with.
+You can configure XO options by creating an `xo.config.js` or an `xo.config.ts` file in the root directory of your project, or you can add an `xo` field to your `package.json`. XO supports all js/ts file extensions (js,cjs,mjs,ts,cts,mts) automatically. A XO config is an extension of ESLint's Flat Config. Like ESLint, an XO config exports an array of XO config objects. XO config objects extend [ESLint Configuration Objects](https://eslint.org/docs/latest/use/configure/configuration-files#configuration-objects). This means all the available configuration params for ESLint also work for `XO`. However, `XO` enhances and adds extra params to the configuration objects to make them easier to work with.
 
 ### Config types
 
@@ -124,24 +124,32 @@ const xoConfig = [...]
 
 `xo.config.ts`
 
-```js
+```ts
 import {type FlatXoConfig} from 'xo';
 
 const xoConfig: FlatXoConfig = [...]
 ```
 
+```ts
+export default [...] satisfies import('xo').FlatXoConfig
+```
+
 ### files
 
 Type: `string | string[] | undefined`\
 Default: `**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx}`
 
 A glob or array of glob strings which the config object will apply. By default `XO` will apply the configuration to [all files](lib/constants.ts).
 
+> Tip: If you are adding additional `@typescript-eslint` rules to your config, these rules will apply to JS files as well unless you separate them appropriately with the `files` option. `@typescript-eslint` rules set to `'off'` or `0`, however, will have no effect on JS linting.
+
 ### ignores
 
 Type: `string[]`
 
-Some [paths](lib/constants.ts) are ignored by default, including paths in `.gitignore`. Additional ignores can be added here. For global ignores, keep `ignores` as the only key in the config item.
+Some [paths](lib/constants.ts) are ignored by default, including paths in `.gitignore`. Additional ignores can be added here.
+
+> Tip: For *global* ignores, keep `ignores` as the only key in the config item. You can optionally set a `name` property. Adding more properties will cause ignores to be scoped down to your files selection, which may have unexpected effects.
 
 ### space
 
@@ -202,15 +210,17 @@ XO will automatically lint TypeScript files (`.ts`, `.mts`, `.cts`, and `.tsx`)
 
 XO will handle the [@typescript-eslint/parser `project` option](https://typescript-eslint.io/packages/parser/#project) automatically even if you don't have a `tsconfig.json` in your project.
 
+You can opt out of XO's automatic tsconfig handling by specifying your own `languageOptions.parserOptions.project`, `languageOptions.parserOptions.projectService`, or `languageOptions.parserOptions.tsconfigRootDir`. Files in a config with these properties will be excluded from automatic tsconfig handling.
+
 ## Usage as an ESLint Configuration
 
 With the introduction of the ESLint flat config, many of the original goals of `xo` were brought into the ESLint core, and shareable configs with plugins became possible. Although we highly recommend the use of the `xo` cli, we understand that some teams need to rely on ESLint directly.
 
 For these purposes, you can still get most of the features of `xo` by using our ESLint configuration helpers.
 
-### `xoToEslintConfig`
+### xoToEslintConfig
 
-The `xoToEslintConfig` function is designed for use in an `eslint.config.js` file. It is NOT for use in an `xo.config.js` file. This function takes a `FlatXoConfig` and outputs an ESLint config object. This function will neither be able to automatically handle TS integration for you nor automatic Prettier integration. You are responsible for configuring your other tools appropriately. The `xo` cli, will however, handle all of these details for you.
+The `xoToEslintConfig` function is designed for use in an `eslint.config.js` file. It is NOT for use in an `xo.config.js` file. This function takes a `FlatXoConfig` and outputs an ESLint config object. This function will neither be able to automatically handle TS integration for you nor automatic Prettier integration. You are responsible for configuring your other tools appropriately. The `xo` cli, will, however, handle all of these details for you.
 
 `eslint.config.js`