exadev-eslint-config 2.16.1 → 2.17.0

package/README.md

@@ -160,6 +160,18 @@ export default tseslint.config(
 
 Trailing arguments are arbitrary flat-config objects, appended in order after everything else -- `exadevConfig({}, { rules: { 'no-console': 'warn' } })` is equivalent to spreading the default export plus one more config object.
 
+## Gitignore-derived ignores
+
+`exadevConfig()`'s default output includes an `ignores` block derived directly from your project's own `.gitignore` (via [`@eslint/config-helpers`](https://www.npmjs.com/package/@eslint/config-helpers)'s `includeIgnoreFile`), so a generated directory your `.gitignore` already knows about (`dist/`, `coverage/`, a tool's own report output) is never linted, without hand-duplicating that list in `eslint.config.ts` too. This closes a real gap: a `.gitignore`d directory that nothing previously linted broadly enough to reach could still get linted the moment a wide-reaching rule (this package's own bundled RFC 8785 JSON canonicalization, say) started matching every file its glob covers.
+
+| Value | `options.gitignore` |
+| --- | --- |
+| `true` | Force on -- throws if no `.gitignore` exists |
+| `false` | Force off -- always `[]`, no resolution attempted |
+| `undefined` / omitted | Auto-detect (the default): on if the project has a `.gitignore`, silently off if it doesn't (nothing to read from a project with no version control set up yet) |
+
+Needs no peer to install -- `@eslint/config-helpers` is bundled into this package's own build.
+
 ## RFC 8785 canonical JSON formatting
 
 Every JSON file is linted against [`eslint-plugin-json-canonical`](https://github.com/ExaDev/eslint-plugin-json-canonical) v2 -- plain UTF-16 code-unit key ordering, canonical number formatting, canonical string escaping, and (as of that plugin's own v2) pretty-printed layout (2-space indentation, one member/element per line, a trailing newline), per [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785). This is bundled unconditionally, the same way jsdoc/tsdoc support is: `eslint-plugin-json-canonical` is a plain dependency of this package, so every consumer already has it. There is no option to turn it off.

package/dist/index.cjs

@@ -24,6 +24,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
+let node_fs = require("node:fs");
+node_fs = __toESM(node_fs, 1);
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
 let eslint_plugin_jsdoc = require("eslint-plugin-jsdoc");
 eslint_plugin_jsdoc = __toESM(eslint_plugin_jsdoc, 1);
 let eslint_plugin_tsdoc = require("eslint-plugin-tsdoc");
@@ -31,8 +35,6 @@ eslint_plugin_tsdoc = __toESM(eslint_plugin_tsdoc, 1);
 let eslint_plugin_json_canonical = require("eslint-plugin-json-canonical");
 eslint_plugin_json_canonical = __toESM(eslint_plugin_json_canonical, 1);
 let node_module = require("node:module");
-let node_fs = require("node:fs");
-let node_path = require("node:path");
 let _typescript_eslint_utils = require("@typescript-eslint/utils");
 let typescript = require("typescript");
 typescript = __toESM(typescript, 1);
@@ -41,6 +43,143 @@ let _eslint_js = require("@eslint/js");
 _eslint_js = __toESM(_eslint_js, 1);
 let typescript_eslint = require("typescript-eslint");
 typescript_eslint = __toESM(typescript_eslint, 1);
+//#region node_modules/.pnpm/@eslint+config-helpers@0.7.0/node_modules/@eslint/config-helpers/dist/esm/index.js
+/**
+* @fileoverview Ignore file utilities for the config-helpers package.
+* This file was forked from the source code for the compat package.
+*
+* @author Nicholas C. Zakas
+* @author Kirk Waiblinger
+*/
+/**
+* @typedef {object} IncludeIgnoreFileOptionsObject
+* @property {boolean} [gitignoreResolution] Whether to interpret the contents of an ignore file relative to the config file or the ignore file.
+* - gitignoreResolution: false (default): Interprets ignore patterns relative to the config file
+* - gitignoreResolution: true: Interprets the ignore patterns in a file relative to the ignore file
+* @property {string} [name] The name to give the output config object(s).
+*/
+/**
+* Options for `includeIgnoreFile()`. May be provided as an object or, for
+* legacy compatibility with `@eslint/compat`, as a string which is treated as
+* the `name` option.
+* @typedef {IncludeIgnoreFileOptionsObject | string} IncludeIgnoreFileOptions
+*/
+/**
+* Converts an ESLint ignore pattern to a minimatch pattern.
+* @param {string} pattern The .eslintignore or .gitignore pattern to convert.
+* @returns {string} The converted pattern.
+*/
+function convertIgnorePatternToMinimatch(pattern) {
+	const isNegated = pattern.startsWith("!");
+	const negatedPrefix = isNegated ? "!" : "";
+	const patternToTest = (isNegated ? pattern.slice(1) : pattern).trimEnd();
+	if ([
+		"",
+		"**",
+		"/**",
+		"**/"
+	].includes(patternToTest)) return `${negatedPrefix}${patternToTest}`;
+	const firstIndexOfSlash = patternToTest.indexOf("/");
+	return `${negatedPrefix}${firstIndexOfSlash < 0 || firstIndexOfSlash === patternToTest.length - 1 ? "**/" : ""}${(firstIndexOfSlash === 0 ? patternToTest.slice(1) : patternToTest).replaceAll(/(?=((?:\\.|[^{(])*))\1([{(])/guy, "$1\\$2")}${patternToTest.endsWith("/**") ? "/*" : ""}`;
+}
+/**
+* @param {string} ignoreFilePath
+* @returns {string[]}
+*/
+function ignoreFilePathToPatterns(ignoreFilePath) {
+	return node_fs.default.readFileSync(ignoreFilePath, "utf8").split(/\r?\n/u).map((line) => line.trim()).filter((line) => line && !line.startsWith("#")).map(convertIgnorePatternToMinimatch);
+}
+/**
+* Helper to parse and validate the options to `includeIgnoreFile()`
+*
+* @param {string | { gitignoreResolution?: unknown, name?: unknown } | undefined} options
+* @returns {{ gitignoreResolution: boolean, name: string }}
+*/
+function parseOptions(options) {
+	if (typeof options === "string") return {
+		gitignoreResolution: false,
+		name: options
+	};
+	const optionsObject = options ?? {};
+	if (typeof optionsObject !== "object" || Array.isArray(optionsObject)) throw new TypeError("The options argument to `includeIgnoreFile()` should be an object or a string.");
+	const gitignoreResolution = optionsObject.gitignoreResolution ?? false;
+	if (typeof gitignoreResolution !== "boolean") throw new TypeError("The `gitignoreResolution` option must be specified a boolean or omitted");
+	const name = optionsObject.name ?? `Imported .gitignore patterns`;
+	if (typeof name !== "string") throw new TypeError("The `name` option must be specified as a string or omitted.");
+	return {
+		gitignoreResolution,
+		name
+	};
+}
+/**
+* @overload
+*
+* Reads ignore files and returns objects with the ignore patterns.
+*
+* @param {string[]} ignoreFilePathArg The paths of ignore files to include.
+* @param {IncludeIgnoreFileOptions} [options]
+* @returns {ConfigObject[]}
+*/
+/**
+* @overload
+*
+* Reads an ignore file and returns an object with the ignore patterns.
+*
+* @param {string} ignoreFilePathArg The path of the ignore file to include.
+* @param {IncludeIgnoreFileOptions} [options]
+* @returns {ConfigObject}
+*/
+/**
+* @overload
+*
+* Reads an ignore file(s) and returns an object(s) with the ignore patterns.
+*
+* @param {string[] | string} ignoreFilePathArg The path(s) of the ignore file(s) to include.
+* @param {IncludeIgnoreFileOptions} [options]
+* @returns {ConfigObject[] | ConfigObject}
+*/
+/**
+* Reads an ignore file(s) and returns an object(s) with the ignore patterns.
+*
+* @param {string[] | string} ignoreFilePathArg The path(s) of the ignore file(s) to include.
+* @param {IncludeIgnoreFileOptions} [options]
+* @returns {ConfigObject[] | ConfigObject}
+*/
+function includeIgnoreFile(ignoreFilePathArg, options) {
+	const returnSingleObject = !Array.isArray(ignoreFilePathArg);
+	const ignoreFilePaths = Array.isArray(ignoreFilePathArg) ? ignoreFilePathArg : [ignoreFilePathArg];
+	for (const ignorePath of ignoreFilePaths) {
+		if (typeof ignorePath !== "string") throw new TypeError("The first argument to `includeIgnoreFile()` should be a string or array of strings");
+		if (!node_path.default.isAbsolute(ignorePath)) throw new Error(`The ignore file location must be an absolute path. Received ${ignorePath}`);
+	}
+	const { gitignoreResolution, name } = parseOptions(options);
+	if (returnSingleObject) return {
+		name,
+		ignores: ignoreFilePathToPatterns(ignoreFilePathArg),
+		...gitignoreResolution ? { basePath: node_path.default.dirname(ignoreFilePathArg) } : {}
+	};
+	return ignoreFilePaths.map((ignoreFilePath, i) => ({
+		name: `${name} (${i})`,
+		ignores: ignoreFilePathToPatterns(ignoreFilePath),
+		...gitignoreResolution ? { basePath: node_path.default.dirname(ignoreFilePath) } : {}
+	}));
+}
+//#endregion
+//#region src/gitignore.ts
+/**
+* A generated directory that's `.gitignore`d but not in this array's own `ignores` block was, until this feature existed, a real, confirmed gap: harmless while nothing linted broadly enough to reach it, then a real problem the moment a wide-reaching rule (this package's own bundled RFC 8785 JSON canonicalization, say) started matching every file its own glob covers, including a leftover build/report artifact nobody meant to lint at all. Deriving `ignores` from `.gitignore` itself, rather than a hand-maintained list every consumer would otherwise have to keep in sync by hand, means a project's own existing single source of truth for "what isn't source" is the one ESLint uses too.
+*/
+function buildGitignoreConfig(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	if (options.enabled === false) return [];
+	const gitignorePath = (0, node_path.join)(cwd, ".gitignore");
+	if (!(0, node_fs.existsSync)(gitignorePath)) {
+		if (options.enabled === true) throw new Error(`@exadev/eslint-config: gitignore-based ignores were explicitly requested but no .gitignore was found at ${gitignorePath}`);
+		return [];
+	}
+	return [includeIgnoreFile(gitignorePath)];
+}
+//#endregion
 //#region src/jsdoc.ts
 const JS_TS_FILE_PATTERNS$1 = "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
 const jsdocConfig = eslint_plugin_jsdoc.default.configs["flat/recommended-tsdoc-error"];
@@ -160,7 +299,7 @@ function buildNextjsConfig(options = {}) {
 }
 //#endregion
 //#region package.json
-var version = "2.16.1";
+var version = "2.17.0";
 //#endregion
 //#region src/react.ts
 const JSX_FILE_PATTERNS = ["**/*.jsx", "**/*.tsx"];
@@ -1872,6 +2011,7 @@ function toPublicConfigArray(built) {
 //#region src/create-config.ts
 function exadevConfig(options = {}, ...userConfigs) {
 	return toPublicConfigArray([
+		...buildGitignoreConfig({ enabled: options.gitignore }),
 		...recommendedTypeChecked,
 		...jsdocAndTsdoc,
 		...jsonCanonicalConfig,

package/dist/index.d.cts

@@ -8,6 +8,7 @@ interface ExadevConfigOptions {
   readonly react?: boolean;
   readonly nextjs?: boolean;
   readonly packageJsonKeyOrder?: boolean;
+  readonly gitignore?: boolean;
 }
 declare function exadevConfig(options?: ExadevConfigOptions, ...userConfigs: readonly TSESLint.FlatConfig.Config[]): PublicConfigArray;
 declare const defaultConfig: PublicConfigArray;

package/dist/index.d.ts

@@ -8,6 +8,7 @@ interface ExadevConfigOptions {
   readonly react?: boolean;
   readonly nextjs?: boolean;
   readonly packageJsonKeyOrder?: boolean;
+  readonly gitignore?: boolean;
 }
 declare function exadevConfig(options?: ExadevConfigOptions, ...userConfigs: readonly TSESLint.FlatConfig.Config[]): PublicConfigArray;
 declare const defaultConfig: PublicConfigArray;

package/dist/index.js

@@ -1,14 +1,151 @@
+import fs, { existsSync, readFileSync } from "node:fs";
+import path, { join, posix } from "node:path";
 import jsdoc from "eslint-plugin-jsdoc";
 import tsdoc from "eslint-plugin-tsdoc";
 import jsonCanonical from "eslint-plugin-json-canonical";
 import { createRequire } from "node:module";
-import { existsSync, readFileSync } from "node:fs";
-import { join, posix } from "node:path";
 import { AST_NODE_TYPES, ESLintUtils, TSESLint } from "@typescript-eslint/utils";
 import * as ts from "typescript";
 import { isPropertyReadonlyInType, isTypeReference } from "ts-api-utils";
 import js from "@eslint/js";
 import tseslint from "typescript-eslint";
+//#region node_modules/.pnpm/@eslint+config-helpers@0.7.0/node_modules/@eslint/config-helpers/dist/esm/index.js
+/**
+* @fileoverview Ignore file utilities for the config-helpers package.
+* This file was forked from the source code for the compat package.
+*
+* @author Nicholas C. Zakas
+* @author Kirk Waiblinger
+*/
+/**
+* @typedef {object} IncludeIgnoreFileOptionsObject
+* @property {boolean} [gitignoreResolution] Whether to interpret the contents of an ignore file relative to the config file or the ignore file.
+* - gitignoreResolution: false (default): Interprets ignore patterns relative to the config file
+* - gitignoreResolution: true: Interprets the ignore patterns in a file relative to the ignore file
+* @property {string} [name] The name to give the output config object(s).
+*/
+/**
+* Options for `includeIgnoreFile()`. May be provided as an object or, for
+* legacy compatibility with `@eslint/compat`, as a string which is treated as
+* the `name` option.
+* @typedef {IncludeIgnoreFileOptionsObject | string} IncludeIgnoreFileOptions
+*/
+/**
+* Converts an ESLint ignore pattern to a minimatch pattern.
+* @param {string} pattern The .eslintignore or .gitignore pattern to convert.
+* @returns {string} The converted pattern.
+*/
+function convertIgnorePatternToMinimatch(pattern) {
+	const isNegated = pattern.startsWith("!");
+	const negatedPrefix = isNegated ? "!" : "";
+	const patternToTest = (isNegated ? pattern.slice(1) : pattern).trimEnd();
+	if ([
+		"",
+		"**",
+		"/**",
+		"**/"
+	].includes(patternToTest)) return `${negatedPrefix}${patternToTest}`;
+	const firstIndexOfSlash = patternToTest.indexOf("/");
+	return `${negatedPrefix}${firstIndexOfSlash < 0 || firstIndexOfSlash === patternToTest.length - 1 ? "**/" : ""}${(firstIndexOfSlash === 0 ? patternToTest.slice(1) : patternToTest).replaceAll(/(?=((?:\\.|[^{(])*))\1([{(])/guy, "$1\\$2")}${patternToTest.endsWith("/**") ? "/*" : ""}`;
+}
+/**
+* @param {string} ignoreFilePath
+* @returns {string[]}
+*/
+function ignoreFilePathToPatterns(ignoreFilePath) {
+	return fs.readFileSync(ignoreFilePath, "utf8").split(/\r?\n/u).map((line) => line.trim()).filter((line) => line && !line.startsWith("#")).map(convertIgnorePatternToMinimatch);
+}
+/**
+* Helper to parse and validate the options to `includeIgnoreFile()`
+*
+* @param {string | { gitignoreResolution?: unknown, name?: unknown } | undefined} options
+* @returns {{ gitignoreResolution: boolean, name: string }}
+*/
+function parseOptions(options) {
+	if (typeof options === "string") return {
+		gitignoreResolution: false,
+		name: options
+	};
+	const optionsObject = options ?? {};
+	if (typeof optionsObject !== "object" || Array.isArray(optionsObject)) throw new TypeError("The options argument to `includeIgnoreFile()` should be an object or a string.");
+	const gitignoreResolution = optionsObject.gitignoreResolution ?? false;
+	if (typeof gitignoreResolution !== "boolean") throw new TypeError("The `gitignoreResolution` option must be specified a boolean or omitted");
+	const name = optionsObject.name ?? `Imported .gitignore patterns`;
+	if (typeof name !== "string") throw new TypeError("The `name` option must be specified as a string or omitted.");
+	return {
+		gitignoreResolution,
+		name
+	};
+}
+/**
+* @overload
+*
+* Reads ignore files and returns objects with the ignore patterns.
+*
+* @param {string[]} ignoreFilePathArg The paths of ignore files to include.
+* @param {IncludeIgnoreFileOptions} [options]
+* @returns {ConfigObject[]}
+*/
+/**
+* @overload
+*
+* Reads an ignore file and returns an object with the ignore patterns.
+*
+* @param {string} ignoreFilePathArg The path of the ignore file to include.
+* @param {IncludeIgnoreFileOptions} [options]
+* @returns {ConfigObject}
+*/
+/**
+* @overload
+*
+* Reads an ignore file(s) and returns an object(s) with the ignore patterns.
+*
+* @param {string[] | string} ignoreFilePathArg The path(s) of the ignore file(s) to include.
+* @param {IncludeIgnoreFileOptions} [options]
+* @returns {ConfigObject[] | ConfigObject}
+*/
+/**
+* Reads an ignore file(s) and returns an object(s) with the ignore patterns.
+*
+* @param {string[] | string} ignoreFilePathArg The path(s) of the ignore file(s) to include.
+* @param {IncludeIgnoreFileOptions} [options]
+* @returns {ConfigObject[] | ConfigObject}
+*/
+function includeIgnoreFile(ignoreFilePathArg, options) {
+	const returnSingleObject = !Array.isArray(ignoreFilePathArg);
+	const ignoreFilePaths = Array.isArray(ignoreFilePathArg) ? ignoreFilePathArg : [ignoreFilePathArg];
+	for (const ignorePath of ignoreFilePaths) {
+		if (typeof ignorePath !== "string") throw new TypeError("The first argument to `includeIgnoreFile()` should be a string or array of strings");
+		if (!path.isAbsolute(ignorePath)) throw new Error(`The ignore file location must be an absolute path. Received ${ignorePath}`);
+	}
+	const { gitignoreResolution, name } = parseOptions(options);
+	if (returnSingleObject) return {
+		name,
+		ignores: ignoreFilePathToPatterns(ignoreFilePathArg),
+		...gitignoreResolution ? { basePath: path.dirname(ignoreFilePathArg) } : {}
+	};
+	return ignoreFilePaths.map((ignoreFilePath, i) => ({
+		name: `${name} (${i})`,
+		ignores: ignoreFilePathToPatterns(ignoreFilePath),
+		...gitignoreResolution ? { basePath: path.dirname(ignoreFilePath) } : {}
+	}));
+}
+//#endregion
+//#region src/gitignore.ts
+/**
+* A generated directory that's `.gitignore`d but not in this array's own `ignores` block was, until this feature existed, a real, confirmed gap: harmless while nothing linted broadly enough to reach it, then a real problem the moment a wide-reaching rule (this package's own bundled RFC 8785 JSON canonicalization, say) started matching every file its own glob covers, including a leftover build/report artifact nobody meant to lint at all. Deriving `ignores` from `.gitignore` itself, rather than a hand-maintained list every consumer would otherwise have to keep in sync by hand, means a project's own existing single source of truth for "what isn't source" is the one ESLint uses too.
+*/
+function buildGitignoreConfig(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	if (options.enabled === false) return [];
+	const gitignorePath = join(cwd, ".gitignore");
+	if (!existsSync(gitignorePath)) {
+		if (options.enabled === true) throw new Error(`@exadev/eslint-config: gitignore-based ignores were explicitly requested but no .gitignore was found at ${gitignorePath}`);
+		return [];
+	}
+	return [includeIgnoreFile(gitignorePath)];
+}
+//#endregion
 //#region src/jsdoc.ts
 const JS_TS_FILE_PATTERNS$1 = "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
 const jsdocConfig = jsdoc.configs["flat/recommended-tsdoc-error"];
@@ -128,7 +265,7 @@ function buildNextjsConfig(options = {}) {
 }
 //#endregion
 //#region package.json
-var version = "2.16.1";
+var version = "2.17.0";
 //#endregion
 //#region src/react.ts
 const JSX_FILE_PATTERNS = ["**/*.jsx", "**/*.tsx"];
@@ -1840,6 +1977,7 @@ function toPublicConfigArray(built) {
 //#region src/create-config.ts
 function exadevConfig(options = {}, ...userConfigs) {
 	return toPublicConfigArray([
+		...buildGitignoreConfig({ enabled: options.gitignore }),
 		...recommendedTypeChecked,
 		...jsdocAndTsdoc,
 		...jsonCanonicalConfig,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "exadev-eslint-config",
   "description": "Shared custom ESLint rules and plugin for ExaDev projects",
-  "version": "2.16.1",
+  "version": "2.17.0",
   "dependencies": {
     "@eslint/js": "^10.0.1",
     "@typescript-eslint/utils": "8.67.0",
@@ -14,6 +14,7 @@
     "@arethetypeswrong/cli": "^0.18.5",
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
+    "@eslint/config-helpers": "0.7.0",
     "@eslint/json": "2.1.0",
     "@humanwhocodes/momoa": "^3.3.13",
     "@next/eslint-plugin-next": "^16.3.2",