@kirill.konshin/lint 0.3.0 → 0.3.2
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/README.md +147 -85
- package/configs/nx.js +11 -3
- package/configs/{next.js → react.js} +98 -15
- package/configs/storybook.js +17 -5
- package/configs/tailwind.js +75 -34
- package/configs/testing.js +27 -5
- package/configs/turbo.js +3 -3
- package/configs/typescriptTypeAware.js +3 -2
- package/index.d.ts +63 -23
- package/index.js +22 -15
- package/lib.js +273 -127
- package/package.json +5 -2
- package/rules/npm-yarn.md +11 -3
- package/rules/tailwind.md +7 -2
package/lib.js
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
-
import { execSync } from 'node:child_process';
|
|
2
1
|
import { existsSync } from 'node:fs';
|
|
3
2
|
import { dirname, isAbsolute, relative, resolve } from 'node:path';
|
|
4
3
|
import { includeIgnoreFile as includeIgnoreFileCompat } from '@eslint/compat';
|
|
4
|
+
import { findRootSync } from '@manypkg/find-root';
|
|
5
|
+
import { getPackagesSync } from '@manypkg/get-packages';
|
|
5
6
|
import { globSync } from 'glob';
|
|
7
|
+
import { isPackageExists } from 'local-pkg';
|
|
6
8
|
|
|
7
9
|
export const tsExtsRaw = 'js,jsx,ts,tsx,cjs,cts,mjs,mts'; // TODO mdx, needs loader
|
|
8
10
|
export const eslintExtsRaw = `${tsExtsRaw},md,mdx,htm,html,vue`;
|
|
@@ -23,89 +25,42 @@ export const GLOBAL_IGNORES = [
|
|
|
23
25
|
'**/.yarn',
|
|
24
26
|
];
|
|
25
27
|
|
|
28
|
+
const LINT_DEBUG = Boolean(process.env.LINT_DEBUG);
|
|
29
|
+
|
|
26
30
|
/**
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
* @param {string} specifier e.g. `'next/package.json'` - probe package.json, importing the real entry could have side effects
|
|
30
|
-
* @returns {boolean}
|
|
31
|
+
* Structured debug logging, gated by the `LINT_DEBUG` env var (any non-empty value). Traces the
|
|
32
|
+
* detection machinery: capability probes, workspace scans and per-tool gate verdicts.
|
|
31
33
|
*/
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
return true;
|
|
36
|
-
} catch {
|
|
37
|
-
return false;
|
|
38
|
-
}
|
|
34
|
+
function debug(message, ...args) {
|
|
35
|
+
if (!LINT_DEBUG) return;
|
|
36
|
+
console.log(`[@kirill.konshin/lint] ${message}`, ...args);
|
|
39
37
|
}
|
|
40
38
|
|
|
41
|
-
// lockfiles & workspace manifests only ever live at the workspace root
|
|
42
|
-
const ROOT_MARKERS = [
|
|
43
|
-
'yarn.lock',
|
|
44
|
-
'package-lock.json',
|
|
45
|
-
'pnpm-lock.yaml',
|
|
46
|
-
'pnpm-workspace.yaml',
|
|
47
|
-
'bun.lock',
|
|
48
|
-
'bun.lockb',
|
|
49
|
-
];
|
|
50
|
-
|
|
51
39
|
/**
|
|
52
|
-
*
|
|
40
|
+
* Capability gate: is a package resolvable from the workspace root - the scope the ESLint plugins
|
|
41
|
+
* themselves resolve from at lint time?
|
|
53
42
|
*
|
|
54
|
-
* @param {string}
|
|
55
|
-
* @
|
|
56
|
-
* @returns {string | null}
|
|
43
|
+
* @param {string} packageName e.g. `'next'`
|
|
44
|
+
* @returns {boolean}
|
|
57
45
|
*/
|
|
58
|
-
function
|
|
59
|
-
|
|
60
|
-
return (
|
|
61
|
-
execSync(command, {
|
|
62
|
-
cwd,
|
|
63
|
-
stdio: ['ignore', 'pipe', 'ignore'],
|
|
64
|
-
encoding: 'utf-8',
|
|
65
|
-
timeout: 15_000,
|
|
66
|
-
}).trim() || null
|
|
67
|
-
);
|
|
68
|
-
} catch {
|
|
69
|
-
return null;
|
|
70
|
-
}
|
|
46
|
+
export function isPackageResolvable(packageName) {
|
|
47
|
+
return isPackageExists(packageName, { paths: [findWorkspaceRoot()] });
|
|
71
48
|
}
|
|
72
49
|
|
|
73
50
|
/**
|
|
74
|
-
*
|
|
75
|
-
* contains (or is) `cwd` - guards against stale env
|
|
76
|
-
* directories AND against non-path CLI noise: Yarn 1 has no real `yarn node` command, its
|
|
77
|
-
* run-fallback executes it anyway and prints `yarn node v1.22.22\n...\nDone in 0.06s.` to stdout
|
|
78
|
-
* (verified) - a banner must never be mistaken for a root.
|
|
51
|
+
* An env-supplied root candidate is only plausible when it is an absolute existing directory that
|
|
52
|
+
* contains (or is) `cwd` - guards against stale env leaking in from an unrelated checkout.
|
|
79
53
|
*
|
|
80
54
|
* @param {string | undefined} root
|
|
81
55
|
* @param {string} cwd
|
|
82
56
|
* @returns {boolean}
|
|
83
57
|
*/
|
|
84
58
|
function isRootOf(root, cwd) {
|
|
85
|
-
if (!root ||
|
|
59
|
+
if (!root || !isAbsolute(root) || !existsSync(root)) return false;
|
|
86
60
|
const rel = relative(root, cwd);
|
|
87
61
|
return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
|
|
88
62
|
}
|
|
89
63
|
|
|
90
|
-
/**
|
|
91
|
-
* Last-resort walk: nearest ancestor with a lockfile / workspace manifest, bounded by `.git`
|
|
92
|
-
* (a marker above the repo boundary belongs to another project; `.git` is a directory in a normal
|
|
93
|
-
* clone but a FILE in worktrees and submodules - existsSync covers both).
|
|
94
|
-
*
|
|
95
|
-
* @param {string} cwd
|
|
96
|
-
* @returns {string}
|
|
97
|
-
*/
|
|
98
|
-
function walkToRootMarker(cwd) {
|
|
99
|
-
let dir = cwd;
|
|
100
|
-
for (;;) {
|
|
101
|
-
if (ROOT_MARKERS.some((marker) => existsSync(resolve(dir, marker)))) return dir;
|
|
102
|
-
if (existsSync(resolve(dir, '.git'))) return dir;
|
|
103
|
-
const parent = dirname(dir);
|
|
104
|
-
if (parent === dir) return cwd;
|
|
105
|
-
dir = parent;
|
|
106
|
-
}
|
|
107
|
-
}
|
|
108
|
-
|
|
109
64
|
const workspaceRoots = new Map();
|
|
110
65
|
|
|
111
66
|
/**
|
|
@@ -114,72 +69,103 @@ const workspaceRoots = new Map();
|
|
|
114
69
|
* because lint often runs from INSIDE a package (lint-staged, IDE, `yarn workspace x lint`) while
|
|
115
70
|
* the shared config must see the whole repo.
|
|
116
71
|
*
|
|
117
|
-
* Resolution order, cheapest first -
|
|
72
|
+
* Resolution order, cheapest first - an env candidate must contain `cwd` or it is rejected:
|
|
118
73
|
* 1. env the package manager sets for its child processes: `PROJECT_CWD` (Yarn Berry),
|
|
119
|
-
* `npm_config_local_prefix` (npm >= 7, workspace-aware)
|
|
120
|
-
* 2.
|
|
121
|
-
*
|
|
122
|
-
*
|
|
123
|
-
* no package.json around it echoes cwd back, so anything more specific must win first
|
|
124
|
-
* 3. walking up from `cwd` to the nearest lockfile / workspace manifest, bounded by `.git`
|
|
125
|
-
*
|
|
126
|
-
* TODO verify the whole package end-to-end per manager - Yarn Berry, Yarn Berry PnP, Yarn 1,
|
|
127
|
-
* pnpm, npm - see README "Issues"; so far only root detection was exercised outside this repo.
|
|
74
|
+
* `npm_config_local_prefix` (npm >= 7, workspace-aware) - free, no fs walk at all
|
|
75
|
+
* 2. `@manypkg/find-root`: walks up to the nearest workspace manifest (package.json `workspaces`,
|
|
76
|
+
* pnpm-workspace.yaml, lerna.json, rush.json, bun), falling back to the nearest `package.json`
|
|
77
|
+
* for single-package repos - covers every manager, incl. the env-less ones (pnpm, Yarn 1)
|
|
128
78
|
*
|
|
129
|
-
*
|
|
130
|
-
* - Yarn Berry: env when spawned by yarn, `yarn node` probe otherwise - both give the root
|
|
131
|
-
* - npm: env when spawned by npm/npx, `npm prefix` otherwise
|
|
132
|
-
* - pnpm: sets NO usable env at all (not even in scripts) - always the `pnpm root -w` probe
|
|
133
|
-
* - Yarn 1 (classic): sets NO root env (only `INIT_CWD` = invocation dir) and has no root
|
|
134
|
-
* command; its `yarn node` banner output is rejected by {@link isRootOf}; classic workspaces
|
|
135
|
-
* resolve via `npm prefix` (same package.json `workspaces` field) or the yarn.lock walk
|
|
136
|
-
*
|
|
137
|
-
* Cached per `cwd` - the CLI probes are expensive and the config is rebuilt on every lint run.
|
|
79
|
+
* Cached per `cwd` - the config is rebuilt on every lint run.
|
|
138
80
|
*
|
|
139
81
|
* @param {string} [cwd]
|
|
140
|
-
* @returns {string} absolute path; `cwd` itself when
|
|
82
|
+
* @returns {string} absolute path; `cwd` itself when there is no package.json anywhere above
|
|
141
83
|
*/
|
|
142
84
|
export function findWorkspaceRoot(cwd = process.cwd()) {
|
|
143
85
|
if (workspaceRoots.has(cwd)) return workspaceRoots.get(cwd);
|
|
144
86
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
()
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
}
|
|
152
|
-
|
|
153
|
-
() => tryExec('npm prefix', cwd),
|
|
154
|
-
];
|
|
155
|
-
|
|
156
|
-
let root = null;
|
|
157
|
-
for (const candidate of candidates) {
|
|
158
|
-
const value = candidate();
|
|
159
|
-
if (isRootOf(value, cwd)) {
|
|
160
|
-
root = resolve(value);
|
|
161
|
-
break;
|
|
87
|
+
let root = [process.env.PROJECT_CWD, process.env.npm_config_local_prefix].find((dir) => isRootOf(dir, cwd));
|
|
88
|
+
if (root) {
|
|
89
|
+
root = resolve(root);
|
|
90
|
+
} else {
|
|
91
|
+
try {
|
|
92
|
+
root = findRootSync(cwd).rootDir;
|
|
93
|
+
} catch {
|
|
94
|
+
root = cwd; // no package.json anywhere above - degenerate sandbox, scans just see less
|
|
162
95
|
}
|
|
163
96
|
}
|
|
164
|
-
root ??= walkToRootMarker(cwd);
|
|
165
97
|
|
|
166
98
|
workspaceRoots.set(cwd, root);
|
|
167
99
|
return root;
|
|
168
100
|
}
|
|
169
101
|
|
|
102
|
+
const workspacePackageDirs = new Map();
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Absolute directories of all workspace packages - the real `workspaces` / `pnpm-workspace.yaml`
|
|
106
|
+
* globs expanded by `@manypkg/get-packages`, NOT a scan heuristic. Single-package repos yield the
|
|
107
|
+
* root itself; no package.json at all yields an empty list (degenerate sandboxes, tests).
|
|
108
|
+
*
|
|
109
|
+
* @returns {string[]}
|
|
110
|
+
*/
|
|
111
|
+
function findWorkspacePackages() {
|
|
112
|
+
const root = findWorkspaceRoot();
|
|
113
|
+
if (workspacePackageDirs.has(root)) return workspacePackageDirs.get(root);
|
|
114
|
+
|
|
115
|
+
let dirs = [];
|
|
116
|
+
try {
|
|
117
|
+
dirs = getPackagesSync(root).packages.map((pkg) => pkg.dir);
|
|
118
|
+
} catch {
|
|
119
|
+
// no package.json at the root - only the root scan applies
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
workspacePackageDirs.set(root, dirs);
|
|
123
|
+
return dirs;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* The workspace package owning `file` (e.g. the Tailwind entry CSS) - matched against the real
|
|
128
|
+
* workspace package dirs (see {@link findWorkspacePackages}), NOT by walking to the nearest
|
|
129
|
+
* package.json: a directory that is not a declared workspace member belongs to the root. Returns
|
|
130
|
+
* the workspace root when no package contains `file`.
|
|
131
|
+
*
|
|
132
|
+
* @param {string} file absolute path
|
|
133
|
+
* @returns {string} absolute directory path
|
|
134
|
+
*/
|
|
135
|
+
export function packageDirOf(file) {
|
|
136
|
+
const root = findWorkspaceRoot();
|
|
137
|
+
return (
|
|
138
|
+
findWorkspacePackages()
|
|
139
|
+
.filter((dir) => dir !== root)
|
|
140
|
+
.sort((a, b) => b.length - a.length) // nested packages: the deepest match wins
|
|
141
|
+
.find((dir) => {
|
|
142
|
+
const rel = relative(dir, file);
|
|
143
|
+
return !rel.startsWith('..') && !isAbsolute(rel);
|
|
144
|
+
}) ?? root
|
|
145
|
+
);
|
|
146
|
+
}
|
|
147
|
+
|
|
170
148
|
/*
|
|
171
149
|
* Build outputs regularly contain COPIES of the scanned files (compiled css, a next.config.js in a
|
|
172
150
|
* published dist) and would poison the scans even in repos that don't gitignore them. Scan-only -
|
|
173
|
-
* GLOBAL_IGNORES stays the deliberate lint-wide list.
|
|
151
|
+
* GLOBAL_IGNORES stays the deliberate lint-wide list. `.git` matters for `dot: true` scans;
|
|
152
|
+
* `node_modules` because the scans are depth-unbounded within a package.
|
|
174
153
|
*/
|
|
175
|
-
const SCAN_IGNORES = [
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
154
|
+
const SCAN_IGNORES = [
|
|
155
|
+
'**/node_modules',
|
|
156
|
+
'**/dist',
|
|
157
|
+
'**/build',
|
|
158
|
+
'**/out',
|
|
159
|
+
'**/coverage',
|
|
160
|
+
'**/.next',
|
|
161
|
+
'**/.expo',
|
|
162
|
+
'**/storybook-static',
|
|
163
|
+
'**/.git',
|
|
164
|
+
];
|
|
180
165
|
|
|
181
166
|
/**
|
|
182
|
-
* Glob for config-file candidates
|
|
167
|
+
* Glob for config-file candidates across the workspace: the root directory plus every workspace
|
|
168
|
+
* package (the real `workspaces` globs via {@link findWorkspacePackages}, not a depth heuristic),
|
|
183
169
|
* skipping dot dirs, build outputs, the given ignore patterns and everything in the root
|
|
184
170
|
* `.gitignore`. Anchored to {@link findWorkspaceRoot}, NOT cwd.
|
|
185
171
|
*
|
|
@@ -187,10 +173,12 @@ const SCAN_DEPTH = 6;
|
|
|
187
173
|
*
|
|
188
174
|
* @param {string} fileGlob e.g. `'*.css'`, `'next.config.*'`
|
|
189
175
|
* @param {string[]} [ignores] extra glob patterns to skip
|
|
176
|
+
* @param {{ dot?: boolean }} [options] `dot` also scans dot directories (e.g. `.storybook`)
|
|
190
177
|
* @returns {string[]} absolute paths
|
|
191
178
|
*/
|
|
192
|
-
export function scanWorkspace(fileGlob, ignores = []) {
|
|
179
|
+
export function scanWorkspace(fileGlob, ignores = [], { dot = false } = {}) {
|
|
193
180
|
const root = findWorkspaceRoot();
|
|
181
|
+
const packages = findWorkspacePackages().filter((dir) => dir !== root);
|
|
194
182
|
|
|
195
183
|
let gitignored = [];
|
|
196
184
|
try {
|
|
@@ -209,28 +197,43 @@ export function scanWorkspace(fileGlob, ignores = []) {
|
|
|
209
197
|
pattern.endsWith('/') ? `${pattern}**` : `${pattern}/**`,
|
|
210
198
|
]);
|
|
211
199
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
200
|
+
// package dirs are scanned individually - keep the root scan from descending into them twice
|
|
201
|
+
const rootIgnore = [
|
|
202
|
+
...ignore,
|
|
203
|
+
...packages.flatMap((dir) => {
|
|
204
|
+
const rel = relative(root, dir).replaceAll('\\', '/');
|
|
205
|
+
return [rel, `${rel}/**`];
|
|
206
|
+
}),
|
|
207
|
+
];
|
|
208
|
+
|
|
209
|
+
const files = [
|
|
210
|
+
...globSync(`**/${fileGlob}`, { cwd: root, ignore: rootIgnore, absolute: true, dot }),
|
|
211
|
+
...packages.flatMap((dir) => globSync(`**/${fileGlob}`, { cwd: dir, ignore, absolute: true, dot })),
|
|
212
|
+
];
|
|
213
|
+
|
|
214
|
+
// debug('scanWorkspace', { fileGlob, root, packages, dot, ignores, files });
|
|
215
|
+
|
|
216
|
+
return files;
|
|
218
217
|
}
|
|
219
218
|
|
|
220
219
|
/*
|
|
221
|
-
* Capability detection, exported for debugging. Package probes resolve from
|
|
222
|
-
*
|
|
223
|
-
*
|
|
224
|
-
*
|
|
220
|
+
* Capability detection, exported for debugging. Package probes resolve from the WORKSPACE ROOT -
|
|
221
|
+
* the same scope the plugins' own resolution sees at lint time (eslint-plugin-tailwindcss's
|
|
222
|
+
* workers, eslint-config-next's internal `require`s, eslint-plugin-storybook's static import,
|
|
223
|
+
* eslint-plugin-jest's version sniffing). A tool hoisted to the root (default npm/yarn behavior)
|
|
224
|
+
* is visible; a leaf-only install is not - `toolGate` then fails with hoisting guidance instead of
|
|
225
|
+
* a cryptic plugin crash. `nx.json` is checked at the workspace root, not via cwd.
|
|
225
226
|
*/
|
|
226
|
-
export const hasNext = isPackageResolvable('next
|
|
227
|
-
export const hasStorybook = isPackageResolvable('storybook
|
|
228
|
-
export const hasVite = isPackageResolvable('vite
|
|
229
|
-
export const hasJest = isPackageResolvable('jest
|
|
230
|
-
export const hasVitest = isPackageResolvable('vitest
|
|
231
|
-
export const hasTurbo = isPackageResolvable('turbo
|
|
227
|
+
export const hasNext = isPackageResolvable('next');
|
|
228
|
+
export const hasStorybook = isPackageResolvable('storybook');
|
|
229
|
+
export const hasVite = isPackageResolvable('vite');
|
|
230
|
+
export const hasJest = isPackageResolvable('jest');
|
|
231
|
+
export const hasVitest = isPackageResolvable('vitest');
|
|
232
|
+
export const hasTurbo = isPackageResolvable('turbo');
|
|
232
233
|
export const hasNx = existsSync(resolve(findWorkspaceRoot(), 'nx.json'));
|
|
233
|
-
export const hasTailwind = isPackageResolvable('tailwindcss
|
|
234
|
+
export const hasTailwind = isPackageResolvable('tailwindcss');
|
|
235
|
+
|
|
236
|
+
debug('capability probes', { hasNext, hasStorybook, hasVite, hasJest, hasVitest, hasTurbo, hasNx, hasTailwind });
|
|
234
237
|
|
|
235
238
|
/**
|
|
236
239
|
* Normalize a defineLintConfig flag into its options object with a canonical `enabled`:
|
|
@@ -248,3 +251,146 @@ export function asOptions(option) {
|
|
|
248
251
|
if (typeof option === 'object' && option !== null) return { enabled: true, ...option };
|
|
249
252
|
return {};
|
|
250
253
|
}
|
|
254
|
+
|
|
255
|
+
/**
|
|
256
|
+
* Shared activation gate of the tool-scoped config blocks (next, storybook, turbo, nx, jest,
|
|
257
|
+
* vitest, tailwind) - the one decision every block repeats: is the tool ON, and can its plugin
|
|
258
|
+
* actually run. The `configs/*.js` functions keep only their tool-specific parts (which blocks to
|
|
259
|
+
* emit, how the evidence feeds settings) and differ solely in the spec they pass here.
|
|
260
|
+
*
|
|
261
|
+
* Decision flow:
|
|
262
|
+
* - `enabled: false` → off, always.
|
|
263
|
+
* - strict (defineLintConfig `detection.strict`): the same-scope probe gates (`strictHas`,
|
|
264
|
+
* defaulting to `has`); `scan` never runs, but `absolutizeOptions` evidence still counts. A tool
|
|
265
|
+
* that is ON while its package is unresolvable (`requirePackage`) or its mandatory evidence is
|
|
266
|
+
* missing (`needs`) throws instead of producing a config that crashes at lint time.
|
|
267
|
+
* - non-strict: evidence-based detection - `absolutizeOptions(options)` wins over the `scan()`
|
|
268
|
+
* auto-discovery; the tool is detected when the package probe hits or evidence exists (`needs`
|
|
269
|
+
* makes evidence mandatory even when the probe hits). A tool that is ON while `packageName` is
|
|
270
|
+
* unresolvable from the workspace root throws an actionable HOISTING error (no silent skip, no
|
|
271
|
+
* symlink bridging - the plugins resolve from the root scope, so only hoisting actually fixes
|
|
272
|
+
* them; the user or their AI agent picks it up from the error).
|
|
273
|
+
*
|
|
274
|
+
* @param {boolean | { enabled?: boolean } | undefined} option the tool's defineLintConfig flag
|
|
275
|
+
* @param {boolean} strict same-scope detection only (defineLintConfig `detection.strict`)
|
|
276
|
+
* @param {object} spec
|
|
277
|
+
* @param {string} spec.tool flag name, used in error messages
|
|
278
|
+
* @param {boolean} spec.has module-load package probe (chain resolvability, see the `has*` exports)
|
|
279
|
+
* @param {boolean} [spec.strictHas] strict-mode detection gate when it differs from `has` (nx: `nx.json` at cwd)
|
|
280
|
+
* @param {string} [spec.packageName] package the tool's plugin needs resolvable at lint time - ON + unresolvable from the workspace root is a hard error with hoisting guidance
|
|
281
|
+
* @param {boolean} [spec.requirePackage] fail loudly when the tool is ON but `packageName` is unresolvable; defaults to `packageName` being set - pass `false` when the plugin works without the tool installed (jest/vitest)
|
|
282
|
+
* @param {(options: object) => string[]} [spec.absolutizeOptions] evidence files derived from the options (absolute anchor paths for the package probes - the anchor itself need not exist, resolution walks up from its directory; allowed under strict)
|
|
283
|
+
* @param {() => string[]} [spec.scan] evidence auto-discovery below the workspace root (absolute paths; never runs under strict or when `absolutizeOptions` produced files)
|
|
284
|
+
* @param {boolean} [spec.allowMultiple] whether several evidence files are usable (default true - next supports several apps); when `false` several candidates are ALWAYS a hard error, even in auto mode - the right one cannot be guessed (tailwind's single entry CSS) and a silent skip of a tool that is evidently present would be hard to detect; zero candidates keeps the usual `needs` behavior
|
|
285
|
+
* @param {{ what: string, detail: string, hint: string }} [spec.needs] makes evidence MANDATORY (the plugin crashes without it - tailwind's entry CSS): detection without evidence stays inert even when `has` hits, forcing the tool on without it throws
|
|
286
|
+
* @returns {{ enabled: boolean, options: object, files: string[] }} the verdict, the normalized options (without `enabled`) and the evidence files
|
|
287
|
+
*/
|
|
288
|
+
export function toolGate(option, strict, spec) {
|
|
289
|
+
const { enabled, ...options } = asOptions(option);
|
|
290
|
+
let absolutized = [];
|
|
291
|
+
let scanned = [];
|
|
292
|
+
// every return path funnels through here so the effective verdict is always traceable
|
|
293
|
+
const trace = (result, reason) => {
|
|
294
|
+
debug(
|
|
295
|
+
`toolGate \`${spec.tool}\` %o`,
|
|
296
|
+
{
|
|
297
|
+
strict,
|
|
298
|
+
has: spec.has,
|
|
299
|
+
enabled: result.enabled,
|
|
300
|
+
reason,
|
|
301
|
+
},
|
|
302
|
+
{
|
|
303
|
+
supplied: option,
|
|
304
|
+
absolutized,
|
|
305
|
+
scanned,
|
|
306
|
+
},
|
|
307
|
+
);
|
|
308
|
+
return result;
|
|
309
|
+
};
|
|
310
|
+
const off = { enabled: false, options, files: [] };
|
|
311
|
+
if (enabled === false) return trace(off, 'disabled explicitly');
|
|
312
|
+
|
|
313
|
+
const {
|
|
314
|
+
tool,
|
|
315
|
+
has,
|
|
316
|
+
strictHas = has,
|
|
317
|
+
packageName,
|
|
318
|
+
requirePackage = Boolean(packageName),
|
|
319
|
+
absolutizeOptions,
|
|
320
|
+
scan,
|
|
321
|
+
allowMultiple = true,
|
|
322
|
+
needs,
|
|
323
|
+
} = spec;
|
|
324
|
+
const prefix = `[@kirill.konshin/lint] \`${tool}\``;
|
|
325
|
+
/*
|
|
326
|
+
* Several candidates with allowMultiple off are a hard error even in auto mode: the evidence
|
|
327
|
+
* proves the tool IS in use, the right candidate is unknowable, and silently skipping a tool
|
|
328
|
+
* that is evidently present would be hard to detect.
|
|
329
|
+
*/
|
|
330
|
+
const usable = (candidates) => {
|
|
331
|
+
if (!allowMultiple && candidates.length > 1) {
|
|
332
|
+
const fix = needs ? `pass ${needs.hint} to pick one, or set` : `set`;
|
|
333
|
+
throw new Error(
|
|
334
|
+
`${prefix} found several ${needs?.what ?? 'evidence'} candidates and cannot pick one - ` +
|
|
335
|
+
`${fix} \`${tool}: false\`:\n${candidates.map((file) => ` - ${file}`).join('\n')}`,
|
|
336
|
+
);
|
|
337
|
+
}
|
|
338
|
+
return candidates;
|
|
339
|
+
};
|
|
340
|
+
|
|
341
|
+
if (strict) {
|
|
342
|
+
if (!(enabled ?? strictHas)) return trace(off, 'strict probe negative');
|
|
343
|
+
if (requirePackage && !has) {
|
|
344
|
+
throw new Error(
|
|
345
|
+
`${prefix} is on under strict detection, but the \`${packageName}\` package is not ` +
|
|
346
|
+
`resolvable at this scope - install it here or set \`${tool}: false\`.`,
|
|
347
|
+
);
|
|
348
|
+
}
|
|
349
|
+
absolutized = absolutizeOptions?.(options) ?? [];
|
|
350
|
+
const files = usable(absolutized);
|
|
351
|
+
if (needs && files.length === 0) {
|
|
352
|
+
throw new Error(
|
|
353
|
+
`${prefix} is on under strict detection, which cannot scan for the ${needs.what} - ` +
|
|
354
|
+
`pass ${needs.hint} or set \`${tool}: false\`.`,
|
|
355
|
+
);
|
|
356
|
+
}
|
|
357
|
+
return trace({ enabled: true, options, files }, enabled ? 'strict, forced on' : 'strict probe positive');
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
absolutized = absolutizeOptions?.(options) ?? [];
|
|
361
|
+
scanned = absolutized.length > 0 ? [] : (scan?.() ?? []);
|
|
362
|
+
const files = usable(absolutized.length > 0 ? absolutized : scanned);
|
|
363
|
+
|
|
364
|
+
if (needs && files.length === 0) {
|
|
365
|
+
// `enabled` is only defined when the consumer explicitly turned the tool on - fail loudly
|
|
366
|
+
// then; detection-driven activation (enabled === undefined) stays inert instead.
|
|
367
|
+
if (enabled) {
|
|
368
|
+
throw new Error(
|
|
369
|
+
`${prefix} was enabled explicitly, but no ${needs.detail} was found - zero or several ` +
|
|
370
|
+
`candidates. Pass ${needs.hint} explicitly.`,
|
|
371
|
+
);
|
|
372
|
+
}
|
|
373
|
+
return trace(off, `no ${needs.what} found`);
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
if (!(enabled ?? (has || files.length > 0))) return trace(off, 'not detected');
|
|
377
|
+
|
|
378
|
+
/*
|
|
379
|
+
* The tool is ON but its package is invisible at the workspace root - the scope the plugins
|
|
380
|
+
* resolve from at lint time. No silent skip and no symlink bridging: fail with the fix
|
|
381
|
+
* (hoisting) and let the user or their AI agent pick it up from here.
|
|
382
|
+
*/
|
|
383
|
+
if (requirePackage && !has) {
|
|
384
|
+
const leaf = files.map((file) => dirname(file)).find((dir) => isPackageExists(packageName, { paths: [dir] }));
|
|
385
|
+
throw new Error(
|
|
386
|
+
`${prefix} is in use, but the \`${packageName}\` package is not resolvable from the workspace root` +
|
|
387
|
+
(leaf ? ` (it is installed near \`${leaf}\`)` : '') +
|
|
388
|
+
` - hoist it: keep the package manager's default hoisting (no \`installConfig.hoistingLimits\` / ` +
|
|
389
|
+
`\`nohoist\`), on pnpm add \`public-hoist-pattern[]=${packageName}\` to .npmrc, or add ` +
|
|
390
|
+
`\`${packageName}\` to the root devDependencies. Set \`${tool}: false\` to turn the tool off. ` +
|
|
391
|
+
`Run eslint with LINT_DEBUG=1 to trace detection.`,
|
|
392
|
+
);
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
return trace({ enabled: true, options, files }, enabled ? 'forced on' : 'detected');
|
|
396
|
+
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kirill.konshin/lint",
|
|
3
3
|
"description": "ESLint + Prettier + lint-staged config and AI agent rules/skills for monorepos",
|
|
4
|
-
"version": "0.3.
|
|
4
|
+
"version": "0.3.2",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"skipGenerate": true,
|
|
7
7
|
"bin": {
|
|
@@ -31,6 +31,8 @@
|
|
|
31
31
|
"dependencies": {
|
|
32
32
|
"@eslint/compat": "^2.0.3",
|
|
33
33
|
"@eslint/js": "^10.0.1",
|
|
34
|
+
"@manypkg/find-root": "^3.1.0",
|
|
35
|
+
"@manypkg/get-packages": "^3.1.0",
|
|
34
36
|
"@next/eslint-plugin-next": "^16.2.1",
|
|
35
37
|
"@nx/eslint-plugin": "^23.1.0",
|
|
36
38
|
"@typescript-eslint/eslint-plugin": "^8.57.2",
|
|
@@ -53,7 +55,8 @@
|
|
|
53
55
|
"eslint-plugin-unused-imports": "^4.4.1",
|
|
54
56
|
"glob": "^13.0.6",
|
|
55
57
|
"globals": "^16.4.0",
|
|
56
|
-
"jsonc-eslint-parser": "^2.4.2"
|
|
58
|
+
"jsonc-eslint-parser": "^2.4.2",
|
|
59
|
+
"local-pkg": "^1.2.1"
|
|
57
60
|
},
|
|
58
61
|
"devDependencies": {
|
|
59
62
|
"vitest": "*"
|
package/rules/npm-yarn.md
CHANGED
|
@@ -17,6 +17,17 @@ description: NPM & Yarn patterns
|
|
|
17
17
|
- Always try to use the latest version of a library.
|
|
18
18
|
- Always try to find if there is a suitable library for a given task before writing custom code, ask user if library is not very popular.
|
|
19
19
|
|
|
20
|
+
# Hoisting
|
|
21
|
+
|
|
22
|
+
- Hoist everything: keep the package manager's DEFAULT hoisting — do not set `installConfig.hoistingLimits`/`nmHoistingLimits` or Yarn 1 `nohoist`; the historical React Native/Expo/Electron reasons are obsolete (Metro follows symlinks since RN 0.72, Expo SDK 54+ supports monorepos with any strategy, hoisting limits break Electron Forge and duplicate React instances)
|
|
23
|
+
- Electron + pnpm needs MORE hoisting, not less: set `node-linker=hoisted` (or `shamefully-hoist=true`) in `.npmrc`, otherwise packaged apps miss dependencies (electron-builder/electron-vite guidance)
|
|
24
|
+
- Binary packagers don't need hoisting limits either: bundle to a single file first (esbuild), then package — node_modules layout becomes irrelevant; use Node's SEA (stable since Node 22, one-step `--build-sea` since 25.5) or `@yao-pkg/pkg` (maintained fork of the deprecated `vercel/pkg`)
|
|
25
|
+
- Shared root configs (e.g. `@kirill.konshin/lint`) must be able to resolve leaf tools (`next`, `tailwindcss`, `storybook`, `jest`) from the workspace root:
|
|
26
|
+
- npm / Yarn: default hoisting already exposes them
|
|
27
|
+
- pnpm: add to `.npmrc`: `public-hoist-pattern[]=next`, `public-hoist-pattern[]=tailwindcss`, `public-hoist-pattern[]=storybook`, `public-hoist-pattern[]=jest` (`*eslint*`/`*prettier*` are hoisted by default)
|
|
28
|
+
- Yarn PnP: declare the tools at the workspace root as well
|
|
29
|
+
- If lint fails with "not resolvable from the workspace root": apply the above or add the package to root `devDependencies`; run eslint with `LINT_DEBUG=1` to trace detection
|
|
30
|
+
|
|
20
31
|
# Consistent versions
|
|
21
32
|
|
|
22
33
|
In Monorepos pin versions of sub-packages to main.
|
|
@@ -28,9 +39,6 @@ Root `package.json`:
|
|
|
28
39
|
|
|
29
40
|
```json
|
|
30
41
|
{
|
|
31
|
-
"installConfig": {
|
|
32
|
-
"hoistingLimits": "dependencies"
|
|
33
|
-
},
|
|
34
42
|
"overrides": {
|
|
35
43
|
"next": "$next",
|
|
36
44
|
"eslint": "$eslint",
|
package/rules/tailwind.md
CHANGED
|
@@ -10,8 +10,13 @@ description: Set of rules for projects which use Tailwind
|
|
|
10
10
|
# ESLint (eslint-plugin-tailwindcss, bundled with @kirill.konshin/lint)
|
|
11
11
|
|
|
12
12
|
- The plugin MUST be able to resolve the Tailwind entry CSS or it hard-crashes lint (ENOENT)
|
|
13
|
-
- Zero-config happy path: when
|
|
14
|
-
-
|
|
13
|
+
- Zero-config happy path: when the workspace contains exactly ONE `*.css` with `@import "tailwindcss"` (scanned across the root + every workspace package, `.gitignore`-aware), rules auto-enable with that entry
|
|
14
|
+
- Rules auto-scope to the workspace package owning the entry CSS (block `basePath`); pass `tailwind: { scoped: false }` to lint the whole workspace
|
|
15
|
+
- `tailwindcss` must be resolvable from the workspace root — if lint fails with "not resolvable from the workspace root", hoist it (see npm-yarn.md "Hoisting") or add it to root `devDependencies`; run eslint with `LINT_DEBUG=1` to trace detection
|
|
16
|
+
- Several entry CSS candidates are ALWAYS a HARD ERROR (a silent skip is hard to notice)
|
|
17
|
+
- pass `cssConfigPath` to pick one (if others are not useful) OR
|
|
18
|
+
- create multiple leaf `eslint.config.ts` per app (if ALL need to be linted)
|
|
19
|
+
- When detection can't see `tailwindcss` (e.g. it lives only in leaf packages of a monorepo), force it with `tailwind: true` — then a missing entry CSS is a HARD ERROR instead of a silent skip
|
|
15
20
|
- ONLY when auto-find finds nothing (or several entries) pass the MANDATORY entry explicitly in `eslint.config.mjs`:
|
|
16
21
|
|
|
17
22
|
```js
|