@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/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
- * Capability gate: is a package installed in the consumer's project?
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
- export function isPackageResolvable(specifier) {
33
- try {
34
- import.meta.resolve(specifier);
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
- * Run a shell command, returning trimmed stdout or null on any failure.
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} command
55
- * @param {string} cwd
56
- * @returns {string | null}
43
+ * @param {string} packageName e.g. `'next'`
44
+ * @returns {boolean}
57
45
  */
58
- function tryExec(command, cwd) {
59
- try {
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
- * A workspace-root candidate is only plausible when it is an absolute existing directory that
75
- * contains (or is) `cwd` - guards against stale env / CLI answers leaking into unrelated
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 || root.includes('\n') || !isAbsolute(root) || !existsSync(root)) return false;
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 - every candidate must contain `cwd` or it is rejected:
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. the package managers' own CLIs (subprocess, slow - hit when e.g. the IDE spawns eslint
121
- * directly): `pnpm root -w` (dirname of the printed node_modules), Yarn Berry via `yarn node`,
122
- * and `npm prefix` LAST - it walks up honoring package.json `workspaces` membership, but with
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
- * Per-manager reality (all verified empirically):
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 nothing better was found
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
- const candidates = [
146
- () => process.env.PROJECT_CWD,
147
- () => process.env.npm_config_local_prefix,
148
- () => {
149
- const nodeModules = tryExec('pnpm root -w', cwd);
150
- return nodeModules && dirname(nodeModules);
151
- },
152
- () => tryExec(`yarn node -p "process.env.PROJECT_CWD||''"`, cwd),
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 = ['**/dist', '**/build', '**/out', '**/coverage', '**/.next', '**/.expo', '**/storybook-static'];
176
-
177
- // glob's maxDepth counts path segments INCLUDING the filename (verified empirically): 6 → files up
178
- // to five directory levels below the root, covering packages/<x>/src/styles and apps/<group>/<app>
179
- const SCAN_DEPTH = 6;
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 below the workspace root (up to five directory levels deep),
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
- return globSync(`**/${fileGlob}`, {
213
- cwd: root,
214
- maxDepth: SCAN_DEPTH,
215
- ignore,
216
- absolute: true,
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 THIS package's install
222
- * location, so in a monorepo where a tool lives only in leaf packages (not in the root
223
- * package.json) detection can miss it - that's what the per-tool force-on flags of
224
- * defineLintConfig are for. `nx.json` is checked at the workspace root, not via cwd.
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/package.json');
227
- export const hasStorybook = isPackageResolvable('storybook/package.json');
228
- export const hasVite = isPackageResolvable('vite/package.json');
229
- export const hasJest = isPackageResolvable('jest/package.json');
230
- export const hasVitest = isPackageResolvable('vitest/package.json');
231
- export const hasTurbo = isPackageResolvable('turbo/package.json');
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/package.json');
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.0",
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 `tailwindcss` is installed and the workspace contains exactly ONE `*.css` with `@import "tailwindcss"` (scanned ≤3 dir levels, `.gitignore`-aware), rules auto-enable with that entry
14
- - 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/ambiguous entry CSS is a HARD ERROR instead of a silent skip
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