@kirill.konshin/lint 0.3.1 → 0.3.3

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 CHANGED
@@ -64,7 +64,7 @@ import { defineLintConfig, scanWorkspace } from '@kirill.konshin/lint';
64
64
  // function form shown
65
65
  export default defineLintConfig(() => ({
66
66
  // enabled (default true) = tools are ON unless said otherwise;
67
- // strict (default false) = same-scope package probes only, no workspace scans and no symlink bridges
67
+ // strict (default false) = same-scope package probes only, no workspace evidence scans
68
68
  // `{ enabled: false, strict: true }` is ideal for per-package configs
69
69
  detection: { enabled: true, strict: false }, // default
70
70
 
@@ -124,6 +124,8 @@ export default defineLintConfig({
124
124
 
125
125
  [Detection](#detection) runs against the **workspace root** even from a nested config, so per-app tool settings (`cssConfigPath`) should be explicit absolute paths — relative ones depend on the lint cwd.
126
126
 
127
+ The Tailwind block auto-scopes to the **workspace package** owning the entry CSS (emitted as the block's `basePath`), so a single root config doesn't flag class-like strings in non-Tailwind packages; pass `tailwind: { scoped: false }` to apply it workspace-wide (no-op when the entry is owned by the workspace root itself).
128
+
127
129
  ## Prettier `.prettierrc.mjs`:
128
130
 
129
131
  ```js
@@ -153,6 +155,7 @@ end_of_line = lf
153
155
  charset = utf-8
154
156
  trim_trailing_whitespace = true
155
157
  insert_final_newline = false
158
+ max_line_length = 120
156
159
 
157
160
  [*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}]
158
161
  indent_size = 4
@@ -213,10 +216,11 @@ By default, always use the `prepare` script, as [Husky recommends](https://typic
213
216
 
214
217
  ```bash
215
218
  #!/bin/zsh
216
- source ~/.zshrc # for VSCode terminal
217
219
  yarn lint:staged
218
220
  ```
219
221
 
222
+ Note `source ~/.zshrc # for VSCode terminal` may be added for VSCode terminal that is not aware of ZSH. Do not add unless specifically asked, and remove if present.
223
+
220
224
  ## AI Agent Rules
221
225
 
222
226
  The package also ships a standardized set of coding conventions (`rules/*.md`) and skills for AI coding assistants, wired into a repo by the `lint-prepare` CLI.
@@ -295,6 +299,9 @@ export default [
295
299
  - **New:** every block is a composable exported `*Config()` function; gated ones accept `true` / `false` / an options object with optional `enabled` (defaults to `true` in the object form); `typeAware: true` enables the (slow) type-aware rules
296
300
  - **`prettier` is now a declared (required) peer dependency** — it was always required by the setup, so no action needed in practice
297
301
  - **TypeScript consumers get real types** — `index.d.ts` ships with the package (`LintOptions` and friends)
302
+ - **Hoisting** if tools can't find packages, fix it once in the package manager config: keep default hoisting (drop `installConfig.hoistingLimits`/`nohoist`), on pnpm add `public-hoist-pattern[]=<pkg>` to `.npmrc`, or add the tool to root `devDependencies`. Run eslint with `LINT_DEBUG=1` to trace detection.
303
+ - **Scans follow the declared workspace.** `scanWorkspace` (also used by all evidence scans) now covers the root directory plus the real `workspaces`/`pnpm-workspace.yaml` packages via `@manypkg/get-packages` instead of a blind ≤5-level glob — config files in directories that are not declared workspace members are only found via the root scan, and the depth limit is gone.
304
+ - `has*` probes are anchored at the **workspace root** (via `local-pkg`) instead of this package's install location — identical for standard root installs.
298
305
 
299
306
  Everything else — `prettier`, `listStaged`, extension lists (`tsExts`, …), `has*` detection exports, plugin re-exports (`nxPlugin`, …) — is unchanged.
300
307
 
@@ -316,10 +323,10 @@ Tool-gated functions take the same value as their `defineLintConfig` flag and ga
316
323
 
317
324
  Due to limitations package visibility between leaf and root this package has to be creative to support config-free detection.
318
325
 
319
- 1. **Package probe** — `import.meta.resolve('<pkg>/package.json')` from this package's install location (`has<Pkg>` exported for debugging).
320
- 2. **Evidence scan** — tool config files below the **workspace root** (≤5 directory levels, skipping dot dirs, build outputs, and `.gitignore`d files; exported as `scanWorkspace`). Catches tools installed only in **leaf** packages, invisible to the probe (1). The workspace root itself comes from the package manager (env `PROJECT_CWD`/`npm_config_local_prefix` → CLIs `pnpm root -w`, Berry `yarn node`, `npm prefix` → lockfile walk bounded by `.git`; exported as `findWorkspaceRoot`), so linting from inside a package still sees the whole repo.
321
- 3. **Leaf bridge** — when a plugin needs the tool's package itself but it's only installed in a leaf, a symlink `<workspace root>/node_modules/<pkg>` → leaf install is created automatically (the next install prunes it, the next lint recreates it). Forcing a tool whose package resolves nowhere fails with an actionable error instead of a cryptic plugin crash.
322
- 4. **Yarn Berry PnP quirk** — leaf resolutions point inside the zip cache (virtual paths), so the bridge is skipped and leaf-only tools degrade gracefully (auto → off, forced → actionable error). Under PnP install the tools at the workspace root as well, keeping versions in sync with the leaves (e.g. the `"vitest": "$vitest"` version-alias hack); `next` documents its own monorepo ESLint setup.
326
+ 1. **Package probe** — `local-pkg`'s `isPackageExists` anchored at the **workspace root**, the same scope the plugins resolve from at lint time (`has<Pkg>` exported for debugging).
327
+ 2. **Evidence scan** — tool config files across the workspace: the root directory plus every **workspace package** (the real `workspaces`/`pnpm-workspace.yaml` globs via `@manypkg/get-packages`, not a depth heuristic), skipping dot dirs, build outputs, and `.gitignore`d files; exported as `scanWorkspace`. Catches tools installed only in **leaf** packages, invisible to the probe (1). The workspace root itself comes from env (`PROJECT_CWD`/`npm_config_local_prefix`) with `@manypkg/find-root` as the fallback (workspace manifest walk, nearest `package.json` for single-package repos; exported as `findWorkspaceRoot`), so linting from inside a package still sees the whole repo.
328
+ 3. **Hoisting, not bridging** — the plugins need the tool's package resolvable from the workspace root; a tool that is evidently in use (2) but not resolvable there (1) is a **hard error** with hoisting guidance (keep default hoisting, pnpm `public-hoist-pattern`, or a root devDependency — see the error text) instead of a silent skip or a cryptic plugin crash. Fix it once in the package manager config; nothing is symlinked at lint time.
329
+ 4. **Yarn Berry PnP** — there is no hoisting to configure; declare the tools at the workspace root as well, keeping versions in sync with the leaves (e.g. the `"vitest": "$vitest"` version-alias hack); `next` documents its own monorepo ESLint setup.
323
330
 
324
331
  | Option | Package | Evidence glob | When zero / many found |
325
332
  | ----------- | ---------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
@@ -331,14 +338,16 @@ Due to limitations package visibility between leaf and root this package has to
331
338
  | `nx` | (plugin bundled) | `nx.json` at the workspace root | — |
332
339
  | `turbo` | `turbo` | package probe only | — |
333
340
 
334
- ¹ the plugins need the tool's package resolvable at lint time (`tailwindcss` for the theme-loading workers, `next` for `eslint-config-next`'s internal `require`s, `storybook` for its plugin's static import, `jest` for version sniffing) — covered by the leaf bridge above.
341
+ ¹ the plugins need the tool's package resolvable at lint time (`tailwindcss` for the theme-loading workers, `next` for `eslint-config-next`'s internal `require`s, `storybook` for its plugin's static import, `jest` for version sniffing) — resolvable from the workspace root, or the hard error of step 3 fires.
335
342
 
336
343
  The machinery is controlled by the `detection` option (same toggle notation as the tools):
337
344
 
338
- - `detection: false` — tools are OFF unless explicitly enabled; enabled tools still auto-detect their settings (steps 2–3)
339
- - `detection: { strict: true }` — only step 1 runs: the `has*` package probes **are** the strict detection (same-scope `import.meta.resolve`, no walking) — no workspace scans (2), no symlink bridges (3). Mandatory settings (`cssConfigPath`) must then be explicit, and `nx.json` is checked at **cwd** instead of the workspace root (`hasNx` is the only non-strict `has*`)
345
+ - `detection: false` — tools are OFF unless explicitly enabled; enabled tools still auto-detect their settings (step 2)
346
+ - `detection: { strict: true }` — only step 1 runs: the `has*` package probes **are** the strict detection — no workspace evidence scans (2). Mandatory settings (`cssConfigPath`) must then be explicit, and `nx.json` is checked at **cwd** instead of the workspace root (`hasNx` is the only non-package `has*`)
340
347
  - `detection: { enabled: false, strict: true }` — fully explicit: tools on only when set, probes only
341
348
 
349
+ Set `LINT_DEBUG=1` to trace the machinery: `has*` probe results, every workspace scan (glob, root, files found) and each tool's gate verdict (supplied options, absolutized & scanned evidence files, effective enabled status + reason).
350
+
342
351
  > `basePath: 'packages/xxx'` (ESLint ≥ 9.30) can scope a config object to a directory within a single root config, but it won't help with detection — `defineLintConfig` detects once, workspace-wide (e.g. Tailwind still demands exactly one entry CSS), so per-app settings would still have to be spelled out block by block; nested configs are the cleaner tool for this.
343
352
 
344
353
  ### Type-aware rules (optional, disabled by default for performance)
@@ -361,10 +370,10 @@ paths:
361
370
  - Package managers
362
371
  - [ ] TODO verify the package end-to-end (workspace-root detection, Tailwind / `next.config.*` scans, `has*` capability probes, plugin resolution, `defineLintConfig` under a real lint run) with each manager:
363
372
  - [x] Yarn Berry, node-modules linker — this repo, fully covered
364
- - [ ] Yarn Berry **PnP** — partially verified (scratch workspace): Tailwind leaf resolution is PnP-aware but points into the zip cache, so the node_modules symlink bridge is skipped by design (see "Tailwind CSS rules"); root-declared `tailwindcss` verified working; full config run (plugin loading, capability probes) still unverified
365
- - [ ] Yarn 1 (classic) — workspace-root detection verified in a scratch workspace (no root env, `npm prefix`/lockfile-walk path); full config unverified
366
- - [ ] pnpm — workspace-root detection verified in a scratch workspace (`pnpm root -w`, no usable env); full config unverified
367
- - [ ] npm — root probes verified (`npm_config_local_prefix`, workspace-aware `npm prefix`); full config unverified
373
+ - [ ] Yarn Berry **PnP** — root-declared `tailwindcss` verified working (see "Detection" step 4); full config run (plugin loading, capability probes) unverified since the switch to `@manypkg/find-root`/`local-pkg`
374
+ - [ ] Yarn 1 (classic) — root detection now delegates to `@manypkg/find-root` (workspace-manifest walk); unverified since the switch
375
+ - [ ] pnpm — root detection via `@manypkg/find-root` (`pnpm-workspace.yaml`); `public-hoist-pattern` guidance unverified in a real pnpm workspace
376
+ - [ ] npm — env fast-path (`npm_config_local_prefix`) verified previously; `@manypkg/find-root` fallback unverified since the switch
368
377
  - ESLint 9
369
378
  - [x] https://github.com/microsoft/rushstack/issues/4635 Failed to patch ESLint because the calling module was not recognized
370
379
  - [x] https://github.com/microsoft/rushstack/issues/4965 Failed to patch ESLint because the calling module was not recognized
package/configs/react.js CHANGED
@@ -106,11 +106,11 @@ export function reactBaseConfig() {
106
106
  * evidence (see {@link findNextRoots} - `next.config.*`, a `package.json` depending on `next`, a
107
107
  * `src/app`/`src/pages` tree) marks a Next repo even when the `next` package is installed only in
108
108
  * a leaf app (invisible to `hasNext`) - and because `eslint-config-next` `require`s files INSIDE
109
- * the `next` package, leaf-only installs are bridged from each app's own `package.json` (see
110
- * `ensurePackageResolvable` in lib.js for the mechanism and PnP behavior).
109
+ * the `next` package, `next` must be resolvable from the workspace root (hoisted); a leaf-only
110
+ * install is a hard error with hoisting guidance (see `toolGate` in lib.js).
111
111
  *
112
112
  * @param {boolean | NextOptions} [option] the defineLintConfig `next` flag
113
- * @param {boolean} [strict] same-scope detection only - no `next.config.*` scan, no bridge (defineLintConfig `detection.strict`)
113
+ * @param {boolean} [strict] same-scope detection only - no `next.config.*` scan (defineLintConfig `detection.strict`)
114
114
  * @returns {Promise<import('eslint').Linter.Config[]>}
115
115
  */
116
116
  export async function nextConfig(option, strict = false) {
@@ -120,11 +120,11 @@ export async function nextConfig(option, strict = false) {
120
120
  packageName: 'next',
121
121
  /*
122
122
  * rootDir entries may be relative or absolute paths OR globs (`apps/*` - the plugin
123
- * expands them itself for its settings), so for the bridge probes each entry is expanded
124
- * against the workspace root into real app dirs; a plain path that exists simply matches
125
- * itself. An entry matching nothing falls back to the literal path as the probe anchor
126
- * (harmless - resolution just walks up from there). The probes resolve from each app's
127
- * package.json.
123
+ * expands them itself for its settings), so for the evidence probes each entry is
124
+ * expanded against the workspace root into real app dirs; a plain path that exists simply
125
+ * matches itself. An entry matching nothing falls back to the literal path as the probe
126
+ * anchor (harmless - resolution just walks up from there). The probes resolve from each
127
+ * app's package.json.
128
128
  */
129
129
  absolutizeOptions: ({ rootDir }) =>
130
130
  (Array.isArray(rootDir) ? rootDir : [rootDir]).filter(Boolean).flatMap((dir) => {
@@ -4,12 +4,13 @@ import { GLOBAL_IGNORES, hasStorybook, scanWorkspace, toolGate } from '../lib.js
4
4
  * Storybook recommended rules. Full evidence-based gate (see `toolGate` in lib.js), mirroring
5
5
  * Tailwind: a `.storybook/main.*` marks a Storybook repo even when the `storybook` package is
6
6
  * installed only in a leaf package (invisible to `hasStorybook`) - and because
7
- * `eslint-plugin-storybook` statically imports the `storybook` package itself, leaf-only installs
8
- * are bridged (see `ensurePackageResolvable` in lib.js for the mechanism and PnP behavior); the
9
- * plugin stays lazily imported so consumers without Storybook never pay for it.
7
+ * `eslint-plugin-storybook` statically imports the `storybook` package itself, `storybook` must
8
+ * be resolvable from the workspace root (hoisted); a leaf-only install is a hard error with
9
+ * hoisting guidance (see `toolGate` in lib.js). The plugin stays lazily imported so consumers
10
+ * without Storybook never pay for it.
10
11
  *
11
12
  * @param {boolean | import('../index.js').ToggleOptions} [option] the defineLintConfig `storybook` flag; auto-detected when omitted
12
- * @param {boolean} [strict] same-scope detection only - no `.storybook` scan, no bridge (defineLintConfig `detection.strict`)
13
+ * @param {boolean} [strict] same-scope detection only - no `.storybook` scan (defineLintConfig `detection.strict`)
13
14
  * @returns {Promise<import('eslint').Linter.Config[]>}
14
15
  */
15
16
  export async function storybookConfig(option, strict = false) {
@@ -1,12 +1,12 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
  import { isAbsolute, resolve } from 'node:path';
3
3
 
4
- import { findWorkspaceRoot, GLOBAL_IGNORES, hasTailwind, scanWorkspace, toolGate } from '../lib.js';
4
+ import { findWorkspaceRoot, GLOBAL_IGNORES, hasTailwind, packageDirOf, scanWorkspace, toolGate } from '../lib.js';
5
5
 
6
6
  /**
7
- * All Tailwind v4 entry CSS candidates: every `*.css` below the workspace root (see
8
- * `scanWorkspace` - up to five directory levels, `.gitignore`- and build-output-aware) containing
9
- * the Tailwind v4 marker `@import "tailwindcss"`.
7
+ * All Tailwind v4 entry CSS candidates: every `*.css` across the workspace (see `scanWorkspace` -
8
+ * the root plus every workspace package, `.gitignore`- and build-output-aware) containing the
9
+ * Tailwind v4 marker `@import "tailwindcss"`.
10
10
  *
11
11
  * @param {string[]} ignores glob patterns to skip
12
12
  * @returns {string[]} absolute paths
@@ -47,11 +47,11 @@ export function findTailwindEntry(ignores) {
47
47
  * Auto-detection is driven by the entry CSS (see {@link findTailwindEntries}), not by the package
48
48
  * probe: explicit `cssConfigPath` wins, otherwise auto-find. Zero entries stays inert in auto mode
49
49
  * (nothing marks the repo as Tailwind) but fails loudly when Tailwind was FORCED on (`true` /
50
- * options object) - and so does an entry whose `tailwindcss` package cannot be resolved at all.
51
- * SEVERAL entries fail loudly even in auto mode: they prove the repo uses Tailwind, the right one
52
- * cannot be guessed, and a silent skip would be hard to detect - pass `cssConfigPath` to pick one. Leaf-only installs (tailwindcss next to the entry but invisible from the
53
- * workspace root, where the plugin's theme-loading workers resolve it) are bridged via
54
- * `ensurePackageResolvable` in lib.js - see its doc for the full mechanism and PnP behavior.
50
+ * options object). SEVERAL entries fail loudly even in auto mode: they prove the repo uses
51
+ * Tailwind, the right one cannot be guessed, and a silent skip would be hard to detect - pass
52
+ * `cssConfigPath` to pick one. `tailwindcss` must be resolvable from the workspace root (where
53
+ * the plugin's theme-loading workers resolve it); a leaf-only install is a hard error with
54
+ * hoisting guidance (see `toolGate` in lib.js).
55
55
  *
56
56
  * @param {boolean | TailwindOptions} [option] the defineLintConfig `tailwind` flag; auto-detected when omitted
57
57
  * @param {boolean} [strict] same-scope detection only - no entry scan, no bridge (defineLintConfig `detection.strict`)
@@ -71,8 +71,8 @@ export async function tailwindConfig(option, strict = false) {
71
71
  needs: {
72
72
  what: 'entry CSS',
73
73
  detail:
74
- 'single Tailwind v4 entry CSS (a *.css containing `@import "tailwindcss"`, scanned up to ' +
75
- '5 directory levels below the workspace root)',
74
+ 'single Tailwind v4 entry CSS (a *.css containing `@import "tailwindcss"`, scanned across ' +
75
+ 'the workspace root and every workspace package)',
76
76
  hint: '`tailwind: { cssConfigPath }`',
77
77
  },
78
78
  // the plugin takes exactly ONE entry - several scan candidates are a hard error
@@ -90,10 +90,23 @@ export async function tailwindConfig(option, strict = false) {
90
90
  // served the probes); an auto-found entry is the absolute evidence file
91
91
  const cssConfigPath = options.cssConfigPath ?? files[0];
92
92
 
93
+ /*
94
+ * The entry CSS pins down the ONE package that uses Tailwind, so by default the block is
95
+ * scoped to it via `basePath` (ESLint >= 9.30, absolute paths supported) instead of flagging
96
+ * class-like strings across the whole workspace. `files[0]` is the absolutized evidence path
97
+ * even when `cssConfigPath` was supplied relative. Owning package == workspace root (single-
98
+ * package repo, or the entry is not inside a declared workspace package) makes scoping a
99
+ * no-op - the block stays untouched.
100
+ */
101
+ const { scoped = true } = options;
102
+ const packageDir = scoped ? packageDirOf(files[0]) : null;
103
+ const basePath = packageDir && packageDir !== findWorkspaceRoot() ? { basePath: packageDir } : {};
104
+
93
105
  const tailwindPlugin = (await import('eslint-plugin-tailwindcss')).default;
94
106
  return [
95
107
  {
96
108
  ...tailwindPlugin.configs.recommended,
109
+ ...basePath,
97
110
  settings: { tailwindcss: { cssConfigPath } },
98
111
  },
99
112
  ];
package/index.d.ts CHANGED
@@ -32,12 +32,12 @@ export type ToggleOptions = {
32
32
  * - `false` / `{ enabled: false }` - tools default OFF; explicitly enabled tools still
33
33
  * auto-detect their settings
34
34
  * - `strict: true` - same-scope package probes only (exactly what the `has*` checks are): no
35
- * workspace walks, no evidence scans, no symlink bridges; mandatory settings like
36
- * `cssConfigPath` must be explicit, and `nx.json` is checked at cwd instead of the workspace
37
- * root. `{ enabled: false, strict: true }` is ideal for per-package monorepo configs.
35
+ * evidence scans; mandatory settings like `cssConfigPath` must be explicit, and `nx.json` is
36
+ * checked at cwd instead of the workspace root. `{ enabled: false, strict: true }` is ideal for
37
+ * per-package monorepo configs.
38
38
  */
39
39
  export type DetectionOptions = ToggleOptions & {
40
- /** same-scope package probes only - no workspace walks/scans/bridges */
40
+ /** same-scope package probes only - no workspace evidence scans */
41
41
  strict?: boolean;
42
42
  };
43
43
 
@@ -64,6 +64,15 @@ export type TailwindOptions = ToggleOptions & {
64
64
  * {@link findTailwindEntry}.
65
65
  */
66
66
  cssConfigPath?: TailwindPluginSettings['cssConfigPath'];
67
+ /**
68
+ * Scope the Tailwind rules to the workspace package that owns the entry CSS (emitted as the
69
+ * block's `basePath`, ESLint >= 9.30) instead of the whole workspace. No-op when the entry is
70
+ * owned by the workspace root itself (single-package repo, or not inside a declared
71
+ * workspace package).
72
+ *
73
+ * @default true
74
+ */
75
+ scoped?: boolean;
67
76
  };
68
77
 
69
78
  /**
@@ -238,15 +247,15 @@ export const vitestPlugin: typeof import('@vitest/eslint-plugin').default;
238
247
  // ----- Helpers & companion configs -----
239
248
 
240
249
  /**
241
- * Auto-find the Tailwind v4 entry CSS: the single `*.css` (scanned up to 5 directory levels below
242
- * the workspace root, skipping `.gitignore`d files and build outputs) containing
250
+ * Auto-find the Tailwind v4 entry CSS: the single `*.css` (scanned across the workspace root and
251
+ * every workspace package, skipping `.gitignore`d files and build outputs) containing
243
252
  * `@import "tailwindcss"`; null when zero or several match.
244
253
  */
245
254
  export function findTailwindEntry(ignores: string[]): string | null;
246
255
 
247
256
  /**
248
- * Auto-find Next.js app roots below the workspace root (scanned up to 5 levels, skipping
249
- * `.gitignore`d files and build outputs). `next.config.*` is optional in Next.js, so any of three
257
+ * Auto-find Next.js app roots (scanned across the workspace root and every workspace package,
258
+ * skipping `.gitignore`d files and build outputs). `next.config.*` is optional in Next.js, so any of three
250
259
  * signals marks an app root: a `next.config.*`, a `package.json` depending on `next`
251
260
  * (dependencies/devDependencies - peer declarations mark libraries, not apps), or a
252
261
  * `src/app`/`src/pages` directory (the reported root is the directory containing `src`);
@@ -255,8 +264,9 @@ export function findTailwindEntry(ignores: string[]): string | null;
255
264
  export function findNextRoots(ignores: string[]): string[];
256
265
 
257
266
  /**
258
- * Glob for config-file candidates below the workspace root (up to 5 directory levels, skipping
259
- * dot dirs unless `dot`, build outputs, extra `ignores` and everything in the root `.gitignore`).
267
+ * Glob for config-file candidates across the workspace - the root directory plus every workspace
268
+ * package (the real `workspaces` globs, not a depth heuristic) - skipping dot dirs unless `dot`,
269
+ * build outputs, extra `ignores` and everything in the root `.gitignore`.
260
270
  * Returns absolute paths - useful for building file lists like `typeAware.allowDefaultProject`.
261
271
  */
262
272
  export function scanWorkspace(fileGlob: string, ignores?: string[], options?: { dot?: boolean }): string[];
package/index.js CHANGED
@@ -85,8 +85,8 @@ export async function defineLintConfig(options = {}) {
85
85
  /*
86
86
  * `detection` uses the same toggle notation as the tool flags (true <> { enabled: true } <>
87
87
  * false <> { enabled: false }): `enabled` = are tools ON unless said otherwise (default true),
88
- * `strict` = same-scope package probes only, no workspace scans / symlink bridges (default
89
- * false; ideal for per-package monorepo configs).
88
+ * `strict` = same-scope package probes only, no workspace evidence scans (default false;
89
+ * ideal for per-package monorepo configs).
90
90
  */
91
91
  const { enabled: defaultOn = true, strict = false } = asOptions(options.detection);
92
92
  // with detection off, tools not mentioned explicitly are OFF instead of auto-detected
package/lib.js CHANGED
@@ -1,9 +1,10 @@
1
- import { execSync } from 'node:child_process';
2
- import { existsSync, lstatSync, mkdirSync, symlinkSync, unlinkSync } from 'node:fs';
3
- import { createRequire } from 'node:module';
4
- import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
1
+ import { existsSync } from 'node:fs';
2
+ import { dirname, isAbsolute, relative, resolve } from 'node:path';
5
3
  import { includeIgnoreFile as includeIgnoreFileCompat } from '@eslint/compat';
4
+ import { findRootSync } from '@manypkg/find-root';
5
+ import { getPackagesSync } from '@manypkg/get-packages';
6
6
  import { globSync } from 'glob';
7
+ import { isPackageExists } from 'local-pkg';
7
8
 
8
9
  export const tsExtsRaw = 'js,jsx,ts,tsx,cjs,cts,mjs,mts'; // TODO mdx, needs loader
9
10
  export const eslintExtsRaw = `${tsExtsRaw},md,mdx,htm,html,vue`;
@@ -24,89 +25,42 @@ export const GLOBAL_IGNORES = [
24
25
  '**/.yarn',
25
26
  ];
26
27
 
28
+ const LINT_DEBUG = Boolean(process.env.LINT_DEBUG);
29
+
27
30
  /**
28
- * Capability gate: is a package installed in the consumer's project?
29
- *
30
- * @param {string} specifier e.g. `'next/package.json'` - probe package.json, importing the real entry could have side effects
31
- * @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.
32
33
  */
33
- export function isPackageResolvable(specifier) {
34
- try {
35
- import.meta.resolve(specifier);
36
- return true;
37
- } catch {
38
- return false;
39
- }
34
+ function debug(message, ...args) {
35
+ if (!LINT_DEBUG) return;
36
+ console.log(`[@kirill.konshin/lint] ${message}`, ...args);
40
37
  }
41
38
 
42
- // lockfiles & workspace manifests only ever live at the workspace root
43
- const ROOT_MARKERS = [
44
- 'yarn.lock',
45
- 'package-lock.json',
46
- 'pnpm-lock.yaml',
47
- 'pnpm-workspace.yaml',
48
- 'bun.lock',
49
- 'bun.lockb',
50
- ];
51
-
52
39
  /**
53
- * 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?
54
42
  *
55
- * @param {string} command
56
- * @param {string} cwd
57
- * @returns {string | null}
43
+ * @param {string} packageName e.g. `'next'`
44
+ * @returns {boolean}
58
45
  */
59
- function tryExec(command, cwd) {
60
- try {
61
- return (
62
- execSync(command, {
63
- cwd,
64
- stdio: ['ignore', 'pipe', 'ignore'],
65
- encoding: 'utf-8',
66
- timeout: 15_000,
67
- }).trim() || null
68
- );
69
- } catch {
70
- return null;
71
- }
46
+ export function isPackageResolvable(packageName) {
47
+ return isPackageExists(packageName, { paths: [findWorkspaceRoot()] });
72
48
  }
73
49
 
74
50
  /**
75
- * A workspace-root candidate is only plausible when it is an absolute existing directory that
76
- * contains (or is) `cwd` - guards against stale env / CLI answers leaking into unrelated
77
- * directories AND against non-path CLI noise: Yarn 1 has no real `yarn node` command, its
78
- * run-fallback executes it anyway and prints `yarn node v1.22.22\n...\nDone in 0.06s.` to stdout
79
- * (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.
80
53
  *
81
54
  * @param {string | undefined} root
82
55
  * @param {string} cwd
83
56
  * @returns {boolean}
84
57
  */
85
58
  function isRootOf(root, cwd) {
86
- if (!root || root.includes('\n') || !isAbsolute(root) || !existsSync(root)) return false;
59
+ if (!root || !isAbsolute(root) || !existsSync(root)) return false;
87
60
  const rel = relative(root, cwd);
88
61
  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
89
62
  }
90
63
 
91
- /**
92
- * Last-resort walk: nearest ancestor with a lockfile / workspace manifest, bounded by `.git`
93
- * (a marker above the repo boundary belongs to another project; `.git` is a directory in a normal
94
- * clone but a FILE in worktrees and submodules - existsSync covers both).
95
- *
96
- * @param {string} cwd
97
- * @returns {string}
98
- */
99
- function walkToRootMarker(cwd) {
100
- let dir = cwd;
101
- for (;;) {
102
- if (ROOT_MARKERS.some((marker) => existsSync(resolve(dir, marker)))) return dir;
103
- if (existsSync(resolve(dir, '.git'))) return dir;
104
- const parent = dirname(dir);
105
- if (parent === dir) return cwd;
106
- dir = parent;
107
- }
108
- }
109
-
110
64
  const workspaceRoots = new Map();
111
65
 
112
66
  /**
@@ -115,65 +69,90 @@ const workspaceRoots = new Map();
115
69
  * because lint often runs from INSIDE a package (lint-staged, IDE, `yarn workspace x lint`) while
116
70
  * the shared config must see the whole repo.
117
71
  *
118
- * 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:
119
73
  * 1. env the package manager sets for its child processes: `PROJECT_CWD` (Yarn Berry),
120
- * `npm_config_local_prefix` (npm >= 7, workspace-aware)
121
- * 2. the package managers' own CLIs (subprocess, slow - hit when e.g. the IDE spawns eslint
122
- * directly): `pnpm root -w` (dirname of the printed node_modules), Yarn Berry via `yarn node`,
123
- * and `npm prefix` LAST - it walks up honoring package.json `workspaces` membership, but with
124
- * no package.json around it echoes cwd back, so anything more specific must win first
125
- * 3. walking up from `cwd` to the nearest lockfile / workspace manifest, bounded by `.git`
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)
126
78
  *
127
- * TODO verify the whole package end-to-end per manager - Yarn Berry, Yarn Berry PnP, Yarn 1,
128
- * pnpm, npm - see README "Issues"; so far only root detection was exercised outside this repo.
129
- *
130
- * Per-manager reality (all verified empirically):
131
- * - Yarn Berry: env when spawned by yarn, `yarn node` probe otherwise - both give the root
132
- * - npm: env when spawned by npm/npx, `npm prefix` otherwise
133
- * - pnpm: sets NO usable env at all (not even in scripts) - always the `pnpm root -w` probe
134
- * - Yarn 1 (classic): sets NO root env (only `INIT_CWD` = invocation dir) and has no root
135
- * command; its `yarn node` banner output is rejected by {@link isRootOf}; classic workspaces
136
- * resolve via `npm prefix` (same package.json `workspaces` field) or the yarn.lock walk
137
- *
138
- * 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.
139
80
  *
140
81
  * @param {string} [cwd]
141
- * @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
142
83
  */
143
84
  export function findWorkspaceRoot(cwd = process.cwd()) {
144
85
  if (workspaceRoots.has(cwd)) return workspaceRoots.get(cwd);
145
86
 
146
- const candidates = [
147
- () => process.env.PROJECT_CWD,
148
- () => process.env.npm_config_local_prefix,
149
- () => {
150
- const nodeModules = tryExec('pnpm root -w', cwd);
151
- return nodeModules && dirname(nodeModules);
152
- },
153
- () => tryExec(`yarn node -p "process.env.PROJECT_CWD||''"`, cwd),
154
- () => tryExec('npm prefix', cwd),
155
- ];
156
-
157
- let root = null;
158
- for (const candidate of candidates) {
159
- const value = candidate();
160
- if (isRootOf(value, cwd)) {
161
- root = resolve(value);
162
- 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
163
95
  }
164
96
  }
165
- root ??= walkToRootMarker(cwd);
166
97
 
167
98
  workspaceRoots.set(cwd, root);
168
99
  return root;
169
100
  }
170
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
+
171
148
  /*
172
149
  * Build outputs regularly contain COPIES of the scanned files (compiled css, a next.config.js in a
173
150
  * published dist) and would poison the scans even in repos that don't gitignore them. Scan-only -
174
- * GLOBAL_IGNORES stays the deliberate lint-wide list. `.git` matters for `dot: true` scans.
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.
175
153
  */
176
154
  const SCAN_IGNORES = [
155
+ '**/node_modules',
177
156
  '**/dist',
178
157
  '**/build',
179
158
  '**/out',
@@ -184,12 +163,9 @@ const SCAN_IGNORES = [
184
163
  '**/.git',
185
164
  ];
186
165
 
187
- // glob's maxDepth counts path segments INCLUDING the filename (verified empirically): 6 → files up
188
- // to five directory levels below the root, covering packages/<x>/src/styles and apps/<group>/<app>
189
- const SCAN_DEPTH = 6;
190
-
191
166
  /**
192
- * 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),
193
169
  * skipping dot dirs, build outputs, the given ignore patterns and everything in the root
194
170
  * `.gitignore`. Anchored to {@link findWorkspaceRoot}, NOT cwd.
195
171
  *
@@ -202,6 +178,7 @@ const SCAN_DEPTH = 6;
202
178
  */
203
179
  export function scanWorkspace(fileGlob, ignores = [], { dot = false } = {}) {
204
180
  const root = findWorkspaceRoot();
181
+ const packages = findWorkspacePackages().filter((dir) => dir !== root);
205
182
 
206
183
  let gitignored = [];
207
184
  try {
@@ -220,100 +197,43 @@ export function scanWorkspace(fileGlob, ignores = [], { dot = false } = {}) {
220
197
  pattern.endsWith('/') ? `${pattern}**` : `${pattern}/**`,
221
198
  ]);
222
199
 
223
- return globSync(`**/${fileGlob}`, {
224
- cwd: root,
225
- maxDepth: SCAN_DEPTH,
226
- ignore,
227
- absolute: true,
228
- dot,
229
- });
230
- }
231
-
232
- /**
233
- * Make sure `packageName` will be resolvable for the ESLint plugins that need it at lint time.
234
- *
235
- * In a monorepo a tool is often installed only in the LEAF package that uses it - invisible both
236
- * to the `has*` probes and to the plugins' own resolution: eslint-plugin-tailwindcss's workers
237
- * call local-pkg's `getPackageInfoSync('tailwindcss')`, whose resolver is anchored at
238
- * process.cwd() (verified empirically: NOT the module location, and NODE_PATH is ignored);
239
- * `eslint-config-next` `require`s files INSIDE the `next` package; `eslint-plugin-storybook`
240
- * statically imports `storybook`; `eslint-plugin-jest` sniffs the installed `jest` version.
241
- * Bridge: resolve the package from `fromFile`'s own package context (createRequire follows the
242
- * leaf's dependencies and is PnP-aware) and symlink
243
- * `<workspace root>/node_modules/<packageName>` to it - every resolution walk inside the repo
244
- * passes the root node_modules, so one link fixes all cwds. The package manager prunes the link
245
- * on the next install; it is simply recreated on the next lint. Nothing is touched when the
246
- * package is already resolvable via the normal chain.
247
- *
248
- * Yarn Berry PnP (verified in a scratch PnP workspace): the leaf resolution succeeds but points
249
- * INSIDE the zip cache - a virtual path a symlink cannot reach - so the bridge is skipped (the
250
- * target-exists guard) and the function reports `false`; under PnP the tools must be declared at
251
- * the workspace root instead (verified working - see README).
252
- *
253
- * @param {string} packageName e.g. `'tailwindcss'`, `'next'`, `'storybook'`
254
- * @param {string} fromFile absolute path of a file owned by the leaf package (entry CSS, `next.config.*`, ...)
255
- * @param {boolean} chainResolvable whether the package already resolves via the normal chain (the `has*` probe)
256
- * @returns {boolean} the package is resolvable for the plugins (possibly after bridging)
257
- */
258
- export function ensurePackageResolvable(packageName, fromFile, chainResolvable) {
259
- let leafPackageJson = null;
260
- try {
261
- leafPackageJson = createRequire(fromFile).resolve(`${packageName}/package.json`);
262
- } catch {
263
- // not a dependency of the leaf either
264
- }
265
- if (!leafPackageJson) return chainResolvable;
266
- if (chainResolvable) return true;
267
-
268
- const leafPackageDir = dirname(leafPackageJson);
269
- if (!existsSync(leafPackageDir)) return false; // PnP zip cache - virtual path, nothing to symlink to
270
-
271
- const bridge = join(findWorkspaceRoot(), 'node_modules', ...packageName.split('/'));
272
-
273
- let existing;
274
- try {
275
- existing = lstatSync(bridge);
276
- } catch {
277
- // nothing at the bridge path
278
- }
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
+ ];
279
208
 
280
- // heal a stale bridge left over from a previous layout (symlink whose target is gone)
281
- if (existing?.isSymbolicLink() && !existsSync(bridge)) {
282
- try {
283
- unlinkSync(bridge);
284
- existing = undefined;
285
- } catch {
286
- // fall through - the existsSync() verdict below stays authoritative
287
- }
288
- }
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
+ ];
289
213
 
290
- if (!existing) {
291
- try {
292
- mkdirSync(dirname(bridge), { recursive: true }); // scoped packages need the @scope dir
293
- // 'junction' for Windows (no admin rights needed); ignored on POSIX
294
- symlinkSync(leafPackageDir, bridge, 'junction');
295
- } catch {
296
- // best effort - verdict below
297
- }
298
- }
214
+ // debug('scanWorkspace', { fileGlob, root, packages, dot, ignores, files });
299
215
 
300
- return existsSync(bridge);
216
+ return files;
301
217
  }
302
218
 
303
219
  /*
304
- * Capability detection, exported for debugging. Package probes resolve from THIS package's install
305
- * location, so in a monorepo where a tool lives only in leaf packages (not in the root
306
- * package.json) detection can miss it - that's what the per-tool force-on flags of
307
- * 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.
308
226
  */
309
- export const hasNext = isPackageResolvable('next/package.json');
310
- export const hasStorybook = isPackageResolvable('storybook/package.json');
311
- export const hasVite = isPackageResolvable('vite/package.json');
312
- export const hasJest = isPackageResolvable('jest/package.json');
313
- export const hasVitest = isPackageResolvable('vitest/package.json');
314
- 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');
315
233
  export const hasNx = existsSync(resolve(findWorkspaceRoot(), 'nx.json'));
316
- 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 });
317
237
 
318
238
  /**
319
239
  * Normalize a defineLintConfig flag into its options object with a canonical `enabled`:
@@ -341,15 +261,15 @@ export function asOptions(option) {
341
261
  * Decision flow:
342
262
  * - `enabled: false` → off, always.
343
263
  * - strict (defineLintConfig `detection.strict`): the same-scope probe gates (`strictHas`,
344
- * defaulting to `has`); `scan` never runs and nothing is bridged, but `absolutizeOptions` evidence
345
- * still counts. A tool that is ON while its package is unresolvable (`requirePackage`) or its
346
- * mandatory evidence is missing (`needs`) throws instead of producing a config that crashes at
347
- * lint time.
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.
348
267
  * - non-strict: evidence-based detection - `absolutizeOptions(options)` wins over the `scan()`
349
268
  * auto-discovery; the tool is detected when the package probe hits or evidence exists (`needs`
350
- * makes evidence mandatory even when the probe hits). Leaf-only installs are bridged from the
351
- * evidence files via {@link ensurePackageResolvable}; an unresolvable package turns detection
352
- * off silently but fails loudly when the tool was forced on (and `requirePackage` holds).
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).
353
273
  *
354
274
  * @param {boolean | { enabled?: boolean } | undefined} option the tool's defineLintConfig flag
355
275
  * @param {boolean} strict same-scope detection only (defineLintConfig `detection.strict`)
@@ -357,7 +277,7 @@ export function asOptions(option) {
357
277
  * @param {string} spec.tool flag name, used in error messages
358
278
  * @param {boolean} spec.has module-load package probe (chain resolvability, see the `has*` exports)
359
279
  * @param {boolean} [spec.strictHas] strict-mode detection gate when it differs from `has` (nx: `nx.json` at cwd)
360
- * @param {string} [spec.packageName] package the tool's plugin needs resolvable at lint time - enables the leaf bridge from the evidence files
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
361
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)
362
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)
363
283
  * @param {() => string[]} [spec.scan] evidence auto-discovery below the workspace root (absolute paths; never runs under strict or when `absolutizeOptions` produced files)
@@ -367,8 +287,28 @@ export function asOptions(option) {
367
287
  */
368
288
  export function toolGate(option, strict, spec) {
369
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
+ };
370
310
  const off = { enabled: false, options, files: [] };
371
- if (enabled === false) return off;
311
+ if (enabled === false) return trace(off, 'disabled explicitly');
372
312
 
373
313
  const {
374
314
  tool,
@@ -399,25 +339,27 @@ export function toolGate(option, strict, spec) {
399
339
  };
400
340
 
401
341
  if (strict) {
402
- if (!(enabled ?? strictHas)) return off;
342
+ if (!(enabled ?? strictHas)) return trace(off, 'strict probe negative');
403
343
  if (requirePackage && !has) {
404
344
  throw new Error(
405
345
  `${prefix} is on under strict detection, but the \`${packageName}\` package is not ` +
406
346
  `resolvable at this scope - install it here or set \`${tool}: false\`.`,
407
347
  );
408
348
  }
409
- const files = usable(absolutizeOptions?.(options) ?? []);
349
+ absolutized = absolutizeOptions?.(options) ?? [];
350
+ const files = usable(absolutized);
410
351
  if (needs && files.length === 0) {
411
352
  throw new Error(
412
353
  `${prefix} is on under strict detection, which cannot scan for the ${needs.what} - ` +
413
354
  `pass ${needs.hint} or set \`${tool}: false\`.`,
414
355
  );
415
356
  }
416
- return { enabled: true, options, files };
357
+ return trace({ enabled: true, options, files }, enabled ? 'strict, forced on' : 'strict probe positive');
417
358
  }
418
359
 
419
- const optionFiles = absolutizeOptions?.(options) ?? [];
420
- const files = usable(optionFiles.length > 0 ? optionFiles : (scan?.() ?? []));
360
+ absolutized = absolutizeOptions?.(options) ?? [];
361
+ scanned = absolutized.length > 0 ? [] : (scan?.() ?? []);
362
+ const files = usable(absolutized.length > 0 ? absolutized : scanned);
421
363
 
422
364
  if (needs && files.length === 0) {
423
365
  // `enabled` is only defined when the consumer explicitly turned the tool on - fail loudly
@@ -428,22 +370,27 @@ export function toolGate(option, strict, spec) {
428
370
  `candidates. Pass ${needs.hint} explicitly.`,
429
371
  );
430
372
  }
431
- return off;
373
+ return trace(off, `no ${needs.what} found`);
432
374
  }
433
375
 
434
- if (!(enabled ?? (has || files.length > 0))) return off;
376
+ if (!(enabled ?? (has || files.length > 0))) return trace(off, 'not detected');
435
377
 
436
- const resolvable = !packageName || has || files.some((file) => ensurePackageResolvable(packageName, file, has));
437
- if (!resolvable) {
438
- if (enabled && requirePackage) {
439
- throw new Error(
440
- `${prefix} is enabled, but the \`${packageName}\` package is resolvable neither from the ` +
441
- `workspace root nor from the detected evidence locations - install \`${packageName}\` ` +
442
- `in the package that owns them or at the workspace root.`,
443
- );
444
- }
445
- if (!enabled) return off;
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
+ );
446
393
  }
447
394
 
448
- return { enabled: true, options, files };
395
+ return trace({ enabled: true, options, files }, enabled ? 'forced on' : 'detected');
449
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.1",
4
+ "version": "0.3.3",
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": "*"
@@ -67,6 +70,7 @@
67
70
  "prettier": "^3",
68
71
  "storybook": "^10.5.2",
69
72
  "tailwindcss": "*",
73
+ "typescript": "^6",
70
74
  "vite": "*",
71
75
  "vitest": "*"
72
76
  },
@@ -27,8 +27,9 @@ ALWAYS verify `turbo.json` or `nx.json` task definitions when modifying scripts
27
27
 
28
28
  # The `dependsOn: ["^wait"]` Pattern
29
29
 
30
- https://github.com/vercel/turborepo/issues/1497
31
- https://github.com/vercel/turborepo/discussions/1299
30
+ - https://github.com/vercel/turborepo/issues/1497
31
+ - https://github.com/vercel/turborepo/discussions/1299
32
+ - https://turborepo.dev/docs/guides/coordinating-runtime-dependencies
32
33
 
33
34
  Neither Turbo nor NX can run `persistent` or `continuous` dependent tasks in order. If package `A` depends on `B` and both have `start` command, in freshly checked out repo `A` will fail as `B` does not have anything built yet. Besides, two continuous tasks can't depend on each other as neither will ever exit. Options are:
34
35
 
@@ -54,3 +55,5 @@ The `start` task uses `"dependsOn": ["^wait"]` (upstream):
54
55
  3. `B` also runs `"start": "build --watch"` task (for example) which produces `dist/index.js`
55
56
  4. Once the file exists, `B`'s `wait-on` unblocks and exits, and `A`'s `start` can proceed
56
57
  5. If file existed before, `A` starts immediately, the only issue could be `A`'s double-build if `B`'s `start` will eventually modify the file, causing `A`'s watcher to rebuild
58
+
59
+ For Turbo sibling runtime services (`web` <> `api`, not a package dependency) see the `with` + `wait` pattern in turbo.md.
package/rules/mui.md CHANGED
@@ -8,3 +8,9 @@ paths:
8
8
  - To use MUI default classes always use following notation because it's the only one that works with minification:
9
9
  - Import: `import Input, { inputClasses } from '@mui/material/Input';`
10
10
  - Usage: `<Box sx={{ [``& .${inputClasses.root}``]: { /* styles */ } }}><Input /></Box>`
11
+
12
+ # Admin Pages & Login
13
+
14
+ - ALWAYS use MUI for admin interfaces (Tailwind is ONLY for user-facing sites, see tailwind.md)
15
+ - ALWAYS use [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens: `AppProvider`, `DashboardLayout`, `PageContainer`, `SignInPage`
16
+ - Use as less custom JSX as possible — prefer Toolpad built-ins (navigation, dialogs, notifications, CRUD) over hand-rolled components
package/rules/nextjs.md CHANGED
@@ -13,6 +13,12 @@ _EVERY_ Next.js page, layout, route handler or component must adhere to policy u
13
13
  - Use `iron-session` for authentication
14
14
  - `package.json` MUST ALWAYS have version of Next.js, NEVER `*`, otherwise Vercel will fall into legacy mode instead of serverless
15
15
 
16
+ # Admin Pages & Login
17
+
18
+ - ALWAYS use MUI + [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens, with the App Router integration (`NextAppProvider` from `@toolpad/core/nextjs`), see mui.md
19
+ - Use as less custom JSX as possible — prefer Toolpad built-ins (`DashboardLayout`, `PageContainer`, `SignInPage`) over hand-rolled components
20
+ - Tailwind is ONLY for user-facing sites, NEVER for admin (see tailwind.md)
21
+
16
22
  # Layouts
17
23
 
18
24
  Always use https://nextjs.org/docs/app/api-reference/file-conventions/layout#layout-props-helper:
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
@@ -3,6 +3,7 @@ type: always_apply
3
3
  description: Set of rules for projects which use Tailwind
4
4
  ---
5
5
 
6
+ - Use Tailwind ONLY for user-facing sites, NEVER for admin — admin interfaces ALWAYS use MUI + `@toolpad/core` (see mui.md)
6
7
  - Always use latest version of Tailwind
7
8
  - Default UI library for use with Tailwind is Hero UI v3+
8
9
  - Use the smallest possible configuration of Tailwind and Hero UI, adhere to their best practices (for Vite, Next.js integration, etc.)
@@ -10,7 +11,9 @@ description: Set of rules for projects which use Tailwind
10
11
  # ESLint (eslint-plugin-tailwindcss, bundled with @kirill.konshin/lint)
11
12
 
12
13
  - The plugin MUST be able to resolve the Tailwind entry CSS or it hard-crashes lint (ENOENT)
13
- - Zero-config happy path: when the workspace contains exactly ONE `*.css` with `@import "tailwindcss"` (scanned ≤5 dir levels, `.gitignore`-aware), rules auto-enable with that entry
14
+ - 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
15
+ - Rules auto-scope to the workspace package owning the entry CSS (block `basePath`); pass `tailwind: { scoped: false }` to lint the whole workspace
16
+ - `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
14
17
  - Several entry CSS candidates are ALWAYS a HARD ERROR (a silent skip is hard to notice)
15
18
  - pass `cssConfigPath` to pick one (if others are not useful) OR
16
19
  - create multiple leaf `eslint.config.ts` per app (if ALL need to be linted)
package/rules/turbo.md CHANGED
@@ -10,31 +10,30 @@ paths:
10
10
 
11
11
  ```jsonc
12
12
  {
13
- "$schema": "https://turbo.build/schema.json",
14
- "globalDependencies": ["tsconfig.json"],
15
- "tasks": {
16
-
17
- // define task defaults
13
+ "$schema": "https://turbo.build/schema.json",
14
+ "globalDependencies": ["tsconfig.json"],
15
+ "tasks": {
16
+ // define task defaults
18
17
 
19
- "build": {},
20
- "wait": {
21
- "cache": false
22
- },
23
- "test": {
24
- "outputs": ["coverage/**/*"]
25
- },
26
- "start": {
27
- "persistent": true,
28
- "cache": false
29
- "dependsOn": ["^wait"]
30
- },
18
+ "build": {},
19
+ "wait": {
20
+ "cache": false,
21
+ },
22
+ "test": {
23
+ "outputs": ["coverage/**/*"],
24
+ },
25
+ "start": {
26
+ "persistent": true,
27
+ "cache": false,
28
+ "dependsOn": ["^wait"],
29
+ },
31
30
 
32
- // root tasks
31
+ // root tasks
33
32
 
34
- "//#lint": {
35
- "cache": false
33
+ "//#lint": {
34
+ "cache": false,
35
+ },
36
36
  },
37
- }
38
37
  }
39
38
  ```
40
39
 
@@ -56,3 +55,30 @@ paths:
56
55
  },
57
56
  }
58
57
  ```
58
+
59
+ # Runtime Services: `with` + `wait` (e.g. `web` <> `api`)
60
+
61
+ https://turborepo.dev/docs/guides/coordinating-runtime-dependencies
62
+
63
+ When an app needs a sibling service running in dev (`web` needs `api`), combine:
64
+
65
+ - `"with": ["api#start"]` — launches the service alongside, so `turbo run start --filter=web` brings up both (convenience instead of whole-repo `start`)
66
+ - `"dependsOn": ["api#wait"]` — blocks `web#start` until the readiness probe exits
67
+ - Name the probe task `wait` (NOT `dev:ready` as in the Turbo guide) — same task the `^wait` pattern uses (see monorepo-turbo-nx.md)
68
+ - NEVER put persistent tasks in `dependsOn` — they never exit, so dependents never unblock; depend on the finite `wait` probe
69
+ - `wait` lives in the service package so it self-identifies readiness: `"wait": "wait-on http://localhost:3001/health"` (URL, TCP port, file, socket)
70
+ - Task overrides replace, they don't merge — keep `^wait` when overriding `start`
71
+ - Run with at least `--concurrency=3` (a slot per persistent task + the probe)
72
+
73
+ ```jsonc
74
+ // ./apps/web/turbo.json
75
+ {
76
+ "extends": ["//"],
77
+ "tasks": {
78
+ "start": {
79
+ "with": ["api#start"],
80
+ "dependsOn": ["^wait", "api#wait"],
81
+ },
82
+ },
83
+ }
84
+ ```
@@ -11,6 +11,7 @@ paths:
11
11
 
12
12
  - ALL projects must use TypeScript by default
13
13
  - JavaScript is acceptable for service scripts, but discouraged, use `ts-node`
14
+ - Do NOT upgrade to TypeScript 7 until `typescript-eslint` supports it
14
15
  - ALL configs should use TypeScript if possible via `defineConfig` or at least import TS type for configuration.
15
16
  - Prefer short-circuit evaluation and early exit
16
17
  - Use structured logging with context, consider adding function arguments to log:
package/rules/webstorm.md CHANGED
@@ -131,3 +131,49 @@ Applies if project is using Tailwind.
131
131
  </component>
132
132
  </project>
133
133
  ```
134
+
135
+ # Configure `.idea/jsonSchemas.xml`
136
+
137
+ ```xml
138
+ <?xml version="1.0" encoding="UTF-8"?>
139
+ <project version="4">
140
+ <component name="JsonSchemaMappingsProjectConfiguration">
141
+ <state>
142
+ <map>
143
+ <entry key="Gemini CLI settings">
144
+ <value>
145
+ <SchemaInfo>
146
+ <option name="name" value="Gemini CLI settings" />
147
+ <option name="relativePathToSchema" value="https://raw.githubusercontent.com/google-gemini/gemini-cli/refs/heads/main/schemas/settings.schema.json" />
148
+ <option name="applicationDefined" value="true" />
149
+ <option name="patterns">
150
+ <list>
151
+ <Item>
152
+ <option name="path" value=".gemini/settings.json" />
153
+ </Item>
154
+ </list>
155
+ </option>
156
+ </SchemaInfo>
157
+ </value>
158
+ </entry>
159
+ <entry key="Yarn Config (.yarnrc.yml)">
160
+ <value>
161
+ <SchemaInfo>
162
+ <option name="name" value="Yarn Config (.yarnrc.yml)" />
163
+ <option name="relativePathToSchema" value="https://yarnpkg.com/configuration/yarnrc.json" />
164
+ <option name="applicationDefined" value="true" />
165
+ <option name="patterns">
166
+ <list>
167
+ <Item>
168
+ <option name="path" value=".yarnrc.yml" />
169
+ </Item>
170
+ </list>
171
+ </option>
172
+ </SchemaInfo>
173
+ </value>
174
+ </entry>
175
+ </map>
176
+ </state>
177
+ </component>
178
+ </project>
179
+ ```