@lwojcik/eslint-config 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Łukasz Wójcik
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,69 @@
1
- # Temporary Holding Version
1
+ # @lwojcik/eslint-config
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/@lwojcik/eslint-config)](https://www.npmjs.com/package/@lwojcik/eslint-config)
4
+ [![codecov](https://codecov.io/gh/lwojcik/eslint-config/graph/badge.svg)](https://codecov.io/gh/lwojcik/eslint-config)
5
+ [![Build status](https://ci.appveyor.com/api/projects/status/9tc4d79iibn1rmeq/branch/main?svg=true)](https://ci.appveyor.com/project/lwojcik/lwojcik-eslint-config/branch/main)
6
+
7
+ A heavily opinionated ESLint config factory for TypeScript projects, focused on enforcing functional style and security.
8
+
9
+ ## Install
10
+
11
+ ```sh
12
+ npm install --save-dev --save-exact @lwojcik/eslint-config eslint typescript typescript-eslint
13
+ ```
14
+
15
+ Pin an exact version: a major bump of a bundled plugin (unicorn, sonarjs, ...) can add failures to your whole codebase, so it should reach you as a version change you choose.
16
+
17
+ ## Use
18
+
19
+ ```js
20
+ // eslint.config.js
21
+ import { createConfig } from '@lwojcik/eslint-config';
22
+
23
+ export default createConfig({
24
+ tsconfigRootDir: import.meta.dirname,
25
+ importAliases: ['@app'],
26
+ ignores: ['**/generated/'],
27
+ });
28
+ ```
29
+
30
+ `createConfig` returns an array of flat-config objects. Your `overrides` are appended last, so they win.
31
+
32
+ ## Options
33
+
34
+ | Option | Type | Default | Meaning |
35
+ | ----------------- | ---------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
36
+ | `tsconfigRootDir` | `string` | required | Directory of your `tsconfig.json`, for type-aware linting. Pass `import.meta.dirname`. |
37
+ | `importAliases` | `string[]` | `[]` | Path aliases such as `@app`, each sorted into its own import group after the packages and before relative imports. |
38
+ | `ignores` | `string[]` | `[]` | Globs to ignore, besides `**/coverage/` and `**/dist/`. |
39
+ | `untypedFiles` | `string[]` | `[]` | TypeScript files outside your tsconfig; type-aware rules are switched off for them. |
40
+ | `nodeVersion` | `string` | `'>=24.0.0'` | The Node range `eslint-plugin-n` checks against. |
41
+ | `processEnv` | `{ message, allowedIn: string[] }` | off | Bans `process.env` in `src/` with your message, except in the `allowedIn` globs (for example where you inject the environment). |
42
+ | `overrides` | `Linter.Config[]` | `[]` | Extra flat-config objects, appended last. |
43
+
44
+ ## What it enforces
45
+
46
+ Rules apply to `**/src/**/*.ts` unless noted.
47
+
48
+ - **Base:** `@eslint/js` recommended and typescript-eslint's type-checked recommended set, with unused disable directives reported as errors.
49
+ - **Functional style:** loops and `let` are banned (use `map`, `filter`, `reduce`, `const`), and `functional/immutable-data` forbids mutating existing values. A variable named `draft…` is exempt, for immer drafts.
50
+ - **Size limits:** at most 2 parameters per function, 20 statements, 50 lines per function, 250 lines per file, nesting depth 4, complexity 10, one class per file, no magic numbers (except in `src/config.ts`), identifiers of at least 2 characters.
51
+ - **No comments:** every comment is an error except `eslint` and `global` directives (all files, including tests).
52
+ - **Imports:** sorted with `simple-import-sort`, in the groups: side effects, `node:`, packages, your aliases in the order given, relative.
53
+ - **Style:** 80-column lines, padding lines around returns, declarations and blocks, `eqeqeq`, `prefer-const`, `object-shorthand`.
54
+ - **Plugins:** `unicorn` and `sonarjs` recommended sets (a few noisy rules are off), `security`, `security-node`, `no-secrets`, `no-unsanitized`, `xss`, `optimize-regex` and `n` for Node.
55
+ - **Tests and scripts** (`**/test/**`, `**/scripts/**`): the `no-unsafe-*` and `no-explicit-any` rules are off, and in tests also the promise and throw rules.
56
+ - **JSON** files are linted with `eslint-plugin-json`, comments allowed.
57
+
58
+ Type-aware linting needs a `tsconfig.json` that includes your files.
59
+
60
+ ## Development
61
+
62
+ ```sh
63
+ npm ci
64
+ npm test # lints fixture files with the config and asserts the rules reported
65
+ npm run typecheck # checks index.d.ts against the tests
66
+ npm run format:check
67
+ ```
68
+
69
+ Commits follow [Conventional Commits](https://www.conventionalcommits.org/); `npm run commit` opens a prompt.
package/index.d.ts ADDED
@@ -0,0 +1,18 @@
1
+ import type { Linter } from 'eslint';
2
+
3
+ export interface ProcessEnvRule {
4
+ message: string;
5
+ allowedIn: string[];
6
+ }
7
+
8
+ export interface ConfigOptions {
9
+ tsconfigRootDir: string;
10
+ importAliases?: string[];
11
+ ignores?: string[];
12
+ untypedFiles?: string[];
13
+ nodeVersion?: string;
14
+ processEnv?: ProcessEnvRule;
15
+ overrides?: Linter.Config[];
16
+ }
17
+
18
+ export function createConfig(options: ConfigOptions): Linter.Config[];
package/index.js ADDED
@@ -0,0 +1,280 @@
1
+ import eslint from '@eslint/js';
2
+ import stylistic from '@stylistic/eslint-plugin';
3
+ import { defineConfig } from 'eslint/config';
4
+ import functional from 'eslint-plugin-functional';
5
+ import json from 'eslint-plugin-json';
6
+ import nodePlugin from 'eslint-plugin-n';
7
+ import noComments from 'eslint-plugin-no-comments';
8
+ import noSecrets from 'eslint-plugin-no-secrets';
9
+ import noUnsanitized from 'eslint-plugin-no-unsanitized';
10
+ import optimizeRegex from 'eslint-plugin-optimize-regex';
11
+ import security from 'eslint-plugin-security';
12
+ import securityNode from 'eslint-plugin-security-node';
13
+ import simpleImportSort from 'eslint-plugin-simple-import-sort';
14
+ import { configs as sonarjs } from 'eslint-plugin-sonarjs';
15
+ import unicorn from 'eslint-plugin-unicorn';
16
+ import xss from 'eslint-plugin-xss';
17
+ import tseslint from 'typescript-eslint';
18
+
19
+ const SOURCE_FILES = ['**/src/**/*.ts'];
20
+ const LOOP_SELECTORS = [
21
+ 'ForStatement',
22
+ 'ForInStatement',
23
+ 'ForOfStatement',
24
+ 'WhileStatement',
25
+ 'DoWhileStatement',
26
+ ];
27
+ const DRAFT_PATTERNS = ['draft.**', 'draft*.**', '**.draft.**', '**.draft*.**'];
28
+
29
+ const importGroups = (aliases) => [
30
+ ['^\\u0000'],
31
+ ['^node:'],
32
+ [`^(?!${aliases.join('|')})@?\\w`],
33
+ ...aliases.map((alias) => [`^${alias}/`]),
34
+ ['^\\.'],
35
+ ];
36
+
37
+ const processEnvRules = ({ message, allowedIn }) => [
38
+ {
39
+ files: SOURCE_FILES,
40
+ rules: {
41
+ 'no-restricted-properties': [
42
+ 'error',
43
+ { object: 'process', property: 'env', message },
44
+ ],
45
+ },
46
+ },
47
+ { files: allowedIn, rules: { 'no-restricted-properties': 'off' } },
48
+ ];
49
+
50
+ export const createConfig = ({
51
+ tsconfigRootDir,
52
+ importAliases = [],
53
+ ignores = [],
54
+ untypedFiles = [],
55
+ nodeVersion = '>=24.0.0',
56
+ processEnv,
57
+ overrides = [],
58
+ }) =>
59
+ defineConfig(
60
+ {
61
+ ignores: ['**/coverage/', '**/dist/', ...ignores],
62
+ },
63
+ eslint.configs.recommended,
64
+ tseslint.configs.recommendedTypeChecked,
65
+ {
66
+ files: ['**/*.js', ...untypedFiles],
67
+ extends: [tseslint.configs.disableTypeChecked],
68
+ },
69
+ {
70
+ linterOptions: { reportUnusedDisableDirectives: 'error' },
71
+ plugins: {
72
+ '@stylistic': stylistic,
73
+ 'simple-import-sort': simpleImportSort,
74
+ },
75
+ rules: {
76
+ 'simple-import-sort/imports': [
77
+ 'error',
78
+ { groups: importGroups(importAliases) },
79
+ ],
80
+ 'simple-import-sort/exports': 'error',
81
+ 'no-var': 'error',
82
+ 'prefer-const': 'error',
83
+ 'object-shorthand': ['error', 'always'],
84
+ 'no-useless-rename': 'error',
85
+ 'no-param-reassign': ['error', { props: false }],
86
+ eqeqeq: ['error', 'always'],
87
+ 'max-len': [
88
+ 'error',
89
+ {
90
+ code: 80,
91
+ ignoreUrls: true,
92
+ ignoreStrings: true,
93
+ ignoreTemplateLiterals: true,
94
+ ignoreRegExpLiterals: true,
95
+ ignorePattern: '^\\s*(//|/\\*) eslint-',
96
+ },
97
+ ],
98
+ 'no-restricted-syntax': [
99
+ 'error',
100
+ ...LOOP_SELECTORS.map((selector) => ({
101
+ selector,
102
+ message:
103
+ 'Use map, filter, flatMap, find, some or reduce. A loop that must run in order may stay, with a disable comment that says why.',
104
+ })),
105
+ {
106
+ selector: "VariableDeclaration[kind='let']",
107
+ message:
108
+ 'Use const: a value built with map, filter, reduce, find or a ternary. A let that must stay (assigned in a try, kept across an await) may have a disable comment that says why.',
109
+ },
110
+ ],
111
+ '@stylistic/padding-line-between-statements': [
112
+ 'error',
113
+ { blankLine: 'always', prev: '*', next: 'return' },
114
+ { blankLine: 'always', prev: ['const', 'let', 'var'], next: '*' },
115
+ {
116
+ blankLine: 'any',
117
+ prev: ['const', 'let', 'var'],
118
+ next: ['const', 'let', 'var'],
119
+ },
120
+ { blankLine: 'always', prev: '*', next: 'multiline-block-like' },
121
+ { blankLine: 'always', prev: 'multiline-block-like', next: '*' },
122
+ ],
123
+ '@typescript-eslint/no-unused-vars': [
124
+ 'error',
125
+ { ignoreRestSiblings: true },
126
+ ],
127
+ },
128
+ },
129
+ {
130
+ files: ['**/*.ts'],
131
+ ignores: untypedFiles,
132
+ languageOptions: {
133
+ parserOptions: { projectService: true, tsconfigRootDir },
134
+ },
135
+ rules: {
136
+ '@typescript-eslint/prefer-includes': 'error',
137
+ '@typescript-eslint/prefer-find': 'error',
138
+ '@typescript-eslint/dot-notation': 'error',
139
+ },
140
+ },
141
+ {
142
+ files: SOURCE_FILES,
143
+ plugins: { functional },
144
+ rules: {
145
+ 'functional/immutable-data': [
146
+ 'error',
147
+ {
148
+ ignoreClasses: true,
149
+ ignoreNonConstDeclarations: { treatParametersAsConst: false },
150
+ ignoreAccessorPattern: DRAFT_PATTERNS,
151
+ },
152
+ ],
153
+ 'no-console': 'error',
154
+ 'max-classes-per-file': ['error', 1],
155
+ 'max-depth': ['error', 4],
156
+ 'no-magic-numbers': [
157
+ 'error',
158
+ {
159
+ detectObjects: false,
160
+ enforceConst: true,
161
+ ignore: [0, 1, -1, 2],
162
+ ignoreArrayIndexes: true,
163
+ },
164
+ ],
165
+ 'id-length': ['error', { min: 2, exceptions: ['_'] }],
166
+ complexity: ['error', 10],
167
+ 'max-params': ['error', 2],
168
+ 'max-statements': ['error', 20],
169
+ 'max-lines-per-function': [
170
+ 'error',
171
+ { max: 50, skipBlankLines: true, skipComments: true },
172
+ ],
173
+ 'max-lines': [
174
+ 'error',
175
+ { max: 250, skipBlankLines: true, skipComments: true },
176
+ ],
177
+ },
178
+ },
179
+ ...(processEnv ? processEnvRules(processEnv) : []),
180
+ {
181
+ ...unicorn.configs.recommended,
182
+ files: SOURCE_FILES,
183
+ },
184
+ { ...sonarjs.recommended, files: SOURCE_FILES },
185
+ { ...security.configs.recommended, files: SOURCE_FILES },
186
+ {
187
+ files: SOURCE_FILES,
188
+ rules: { 'security/detect-object-injection': 'off' },
189
+ },
190
+ {
191
+ files: SOURCE_FILES,
192
+ plugins: {
193
+ 'no-secrets': noSecrets,
194
+ 'security-node': securityNode,
195
+ xss,
196
+ 'optimize-regex': optimizeRegex,
197
+ 'no-unsanitized': noUnsanitized,
198
+ },
199
+ rules: {
200
+ ...securityNode.configs.recommended.rules,
201
+ ...noUnsanitized.configs.recommended.rules,
202
+ 'security-node/non-literal-reg-expr': 'off',
203
+ 'security-node/detect-insecure-randomness': 'off',
204
+ 'security-node/detect-non-literal-require-calls': 'off',
205
+ 'no-secrets/no-secrets': ['error', { tolerance: 4.7 }],
206
+ 'xss/no-location-href-assign': 'error',
207
+ 'optimize-regex/optimize-regex': 'error',
208
+ },
209
+ },
210
+ {
211
+ ...nodePlugin.configs['flat/recommended-module'],
212
+ files: SOURCE_FILES,
213
+ settings: { n: { version: nodeVersion } },
214
+ },
215
+ {
216
+ files: SOURCE_FILES,
217
+ rules: { 'n/no-missing-import': 'off' },
218
+ },
219
+ {
220
+ files: ['**/*.json'],
221
+ ignores: ['**/package-lock.json'],
222
+ extends: [tseslint.configs.disableTypeChecked],
223
+ ...json.configs['recommended-with-comments'],
224
+ },
225
+ {
226
+ files: ['**/src/config.ts'],
227
+ rules: { 'no-magic-numbers': 'off' },
228
+ },
229
+ {
230
+ files: SOURCE_FILES,
231
+ rules: {
232
+ 'unicorn/filename-case': [
233
+ 'error',
234
+ { cases: { kebabCase: true, pascalCase: true } },
235
+ ],
236
+ 'unicorn/name-replacements': [
237
+ 'error',
238
+ { replacements: { dir: { direction: false } } },
239
+ ],
240
+ 'sonarjs/new-operator-misuse': 'off',
241
+ 'unicorn/no-null': 'off',
242
+ 'unicorn/text-encoding-identifier-case': 'off',
243
+ 'unicorn/no-for-each': 'off',
244
+ 'unicorn/class-reference-in-static-methods': 'off',
245
+ 'unicorn/consistent-class-member-order': 'off',
246
+ 'unicorn/explicit-length-check': 'off',
247
+ 'unicorn/no-negated-condition': 'off',
248
+ 'unicorn/prefer-ternary': 'off',
249
+ 'unicorn/prefer-early-return': 'off',
250
+ 'unicorn/max-nested-calls': 'off',
251
+ 'unicorn/prefer-simple-condition-first': 'off',
252
+ 'unicorn/no-array-callback-reference': 'off',
253
+ },
254
+ },
255
+ {
256
+ files: ['**/*.{ts,js}'],
257
+ plugins: { 'no-comments': noComments },
258
+ rules: { 'no-comments/disallowComments': 'error' },
259
+ },
260
+ {
261
+ files: ['**/test/**/*.ts', '**/scripts/**/*.ts'],
262
+ rules: {
263
+ '@typescript-eslint/no-explicit-any': 'off',
264
+ '@typescript-eslint/no-unsafe-argument': 'off',
265
+ '@typescript-eslint/no-unsafe-assignment': 'off',
266
+ '@typescript-eslint/no-unsafe-call': 'off',
267
+ '@typescript-eslint/no-unsafe-member-access': 'off',
268
+ '@typescript-eslint/no-unsafe-return': 'off',
269
+ },
270
+ },
271
+ {
272
+ files: ['**/test/**/*.ts'],
273
+ rules: {
274
+ '@typescript-eslint/require-await': 'off',
275
+ '@typescript-eslint/only-throw-error': 'off',
276
+ '@typescript-eslint/prefer-promise-reject-errors': 'off',
277
+ },
278
+ },
279
+ ...overrides,
280
+ );
package/package.json CHANGED
@@ -1,6 +1,70 @@
1
1
  {
2
2
  "name": "@lwojcik/eslint-config",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "A strict, functional-style ESLint flat config factory for TypeScript projects.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "index.js",
8
+ "types": "index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./index.d.ts",
12
+ "default": "./index.js"
13
+ }
14
+ },
15
+ "files": [
16
+ "index.js",
17
+ "index.d.ts"
18
+ ],
19
+ "publishConfig": {
20
+ "access": "public"
21
+ },
22
+ "scripts": {
23
+ "prepare": "husky",
24
+ "commit": "cz",
25
+ "format": "prettier --write .",
26
+ "format:check": "prettier --check .",
27
+ "test": "vitest run",
28
+ "typecheck": "tsc",
29
+ "test:coverage": "vitest run --coverage"
30
+ },
31
+ "config": {
32
+ "commitizen": {
33
+ "path": "cz-conventional-changelog"
34
+ }
35
+ },
36
+ "dependencies": {
37
+ "@eslint/js": "^10.0.1",
38
+ "@stylistic/eslint-plugin": "^5.10.0",
39
+ "eslint-plugin-functional": "10.0.1",
40
+ "eslint-plugin-json": "^5.0.0",
41
+ "eslint-plugin-n": "^18.5.0",
42
+ "eslint-plugin-no-comments": "^1.2.1",
43
+ "eslint-plugin-no-secrets": "^2.3.3",
44
+ "eslint-plugin-no-unsanitized": "^4.1.5",
45
+ "eslint-plugin-optimize-regex": "^1.2.1",
46
+ "eslint-plugin-security": "^4.2.1",
47
+ "eslint-plugin-security-node": "^1.1.4",
48
+ "eslint-plugin-simple-import-sort": "^14.0.0",
49
+ "eslint-plugin-sonarjs": "^4.2.2",
50
+ "eslint-plugin-unicorn": "^79.0.0",
51
+ "eslint-plugin-xss": "^0.1.12"
52
+ },
53
+ "devDependencies": {
54
+ "@commitlint/cli": "21.2.4",
55
+ "@commitlint/config-conventional": "21.2.4",
56
+ "@types/node": "26.6.6",
57
+ "@vitest/coverage-v8": "5.1.0",
58
+ "commitizen": "4.3.2",
59
+ "cz-conventional-changelog": "3.3.0",
60
+ "husky": "9.1.7",
61
+ "prettier": "3.10.1",
62
+ "typescript": "6.0.3",
63
+ "vitest": "5.1.0"
64
+ },
65
+ "peerDependencies": {
66
+ "eslint": "^10.0.0",
67
+ "typescript": ">=5.0.0",
68
+ "typescript-eslint": "^8.0.0"
69
+ }
70
+ }