@kirill.konshin/lint 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -104,6 +104,29 @@ indent_style = tab
104
104
  }
105
105
  ```
106
106
 
107
+ ### Tailwind CSS rules
108
+
109
+ When `tailwindcss` (v4+) is installed, the config auto-enables [`eslint-plugin-tailwindcss`](https://github.com/francoismassart/eslint-plugin-tailwindcss) recommended rules. The plugin **must** be able to resolve the Tailwind entry CSS — it hard-crashes lint (ENOENT) otherwise — so the entry is auto-detected: the workspace is scanned for `*.css` files containing `@import "tailwindcss"` (up to three directory levels deep — covers `packages/<x>/src` — skipping dot dirs, `node_modules`, and everything in `.gitignore`).
110
+
111
+ - Exactly **one** entry found → rules enable automatically with it (added as a standalone config block, easy to override).
112
+ - **Zero or several** entries → nothing is added; enable manually with a **mandatory** `settings.tailwindcss.cssConfigPath` in `eslint.config.mjs`:
113
+
114
+ ```js
115
+ import customConfig, { tailwindPlugin } from '@kirill.konshin/lint';
116
+
117
+ export default defineConfig([
118
+ ...customConfig,
119
+ {
120
+ ...tailwindPlugin.configs.recommended,
121
+ settings: {
122
+ tailwindcss: {
123
+ cssConfigPath: './src/styles/tailwind.css', // relative to the package root
124
+ },
125
+ },
126
+ },
127
+ ]);
128
+ ```
129
+
107
130
  ### IDEA settings
108
131
 
109
132
  - Eslint: `**/*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}`
@@ -0,0 +1,46 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { resolve } from 'node:path';
3
+ import { includeIgnoreFile } from '@eslint/compat';
4
+ import { globSync } from 'glob';
5
+
6
+ /**
7
+ * Auto-find the Tailwind v4 entry CSS: scan `*.css` up to three directory levels deep (covers
8
+ * `packages/<x>/src`), skipping dot dirs, the given ignore patterns and everything in `.gitignore`,
9
+ * looking for the Tailwind v4 marker `@import "tailwindcss"`.
10
+ *
11
+ * eslint-plugin-tailwindcss v4 loads the entry (`settings.tailwindcss.cssConfigPath`) and
12
+ * HARD-CRASHES with ENOENT when it can't, so the caller must only enable the plugin when exactly
13
+ * one entry is found; with zero or several the consumer configures `cssConfigPath` manually
14
+ * (MANDATORY for the plugin) - see README "Tailwind CSS rules".
15
+ *
16
+ * @param {string[]} ignores glob patterns to skip, passed in (not imported) to avoid a circular dependency
17
+ * @returns {string | null} absolute path of the single entry, or null when zero or several were found
18
+ */
19
+ export function findTailwindEntry(ignores) {
20
+ let gitignored = [];
21
+ try {
22
+ // Reuse ESLint's gitignore->minimatch conversion; glob's `ignore` speaks the same language.
23
+ // Negations dropped: glob's ignore cannot un-ignore.
24
+ gitignored = includeIgnoreFile(resolve(process.cwd(), '.gitignore')).ignores.filter(
25
+ (pattern) => !pattern.startsWith('!'),
26
+ );
27
+ } catch {
28
+ // no .gitignore - the scan is just less filtered
29
+ }
30
+
31
+ // `<dir-pattern>/**` variants prune the CONTENTS of ignored directories, not just the dir itself
32
+ const ignore = [...ignores, ...gitignored].flatMap((pattern) => [
33
+ pattern,
34
+ pattern.endsWith('/') ? `${pattern}**` : `${pattern}/**`,
35
+ ]);
36
+
37
+ const entries = globSync('{*.css,*/*.css,*/*/*.css,*/*/*/*.css}', { ignore, absolute: true }).filter((file) => {
38
+ try {
39
+ return /@import\s+['"]tailwindcss['"]/.test(readFileSync(file, 'utf-8'));
40
+ } catch {
41
+ return false;
42
+ }
43
+ });
44
+
45
+ return entries.length === 1 ? entries[0] : null;
46
+ }
package/index.js CHANGED
@@ -17,7 +17,6 @@
17
17
  * normally has exactly one of these, and applying the other runner's correctness rules to it would
18
18
  * be conceptually wrong (even if mechanically harmless, since the rule namespaces don't collide).
19
19
  */
20
- import { existsSync } from 'node:fs';
21
20
  import { dirname, resolve } from 'node:path';
22
21
  import { fileURLToPath } from 'node:url';
23
22
  import { includeIgnoreFile as includeIgnoreFileCompat } from '@eslint/compat';
@@ -38,6 +37,8 @@ import unusedImportsPlugin from 'eslint-plugin-unused-imports';
38
37
  import globals from 'globals';
39
38
  import jsoncParser from 'jsonc-eslint-parser';
40
39
 
40
+ import { findTailwindEntry } from './findTailwindEntry.js';
41
+ import { GLOBAL_IGNORES, hasWorkspaceFile, isPackageResolvable } from './lib.js';
41
42
  import { testColocation } from './ruleTestColocation.js';
42
43
 
43
44
  export const tsExtsRaw = 'js,jsx,ts,tsx,cjs,cts,mjs,mts'; // TODO mdx, needs loader
@@ -48,21 +49,18 @@ export const tsExts = `{${tsExtsRaw}}`;
48
49
  export const eslintExts = `*.{${eslintExtsRaw}}`;
49
50
  export const prettierExts = `*.{${prettierExtsRaw}}`;
50
51
 
51
- function isPackageResolvable(specifier) {
52
- try {
53
- import.meta.resolve(specifier);
54
- return true;
55
- } catch {
56
- return false;
57
- }
58
- }
52
+ export const hasNext = isPackageResolvable('next/package.json');
53
+ export const hasStorybook = isPackageResolvable('storybook/package.json');
54
+ export const hasVite = isPackageResolvable('vite/package.json');
55
+ export const hasJest = isPackageResolvable('jest/package.json');
56
+ export const hasVitest = isPackageResolvable('vitest/package.json');
57
+ export const hasTurbo = isPackageResolvable('turbo/package.json');
58
+ export const hasNx = hasWorkspaceFile('nx.json');
59
+ export const hasTailwind = isPackageResolvable('tailwindcss/package.json');
59
60
 
60
- const hasNext = isPackageResolvable('next/package.json');
61
61
  const nextPlugin = hasNext ? (await import('@next/eslint-plugin-next')).default : null;
62
- const hasStorybook = isPackageResolvable('storybook/package.json');
63
- const hasVite = isPackageResolvable('vite/package.json');
64
- const hasJest = isPackageResolvable('jest/package.json');
65
- const hasVitest = isPackageResolvable('vitest/package.json');
62
+
63
+ export const tailwindEntry = hasTailwind ? findTailwindEntry(GLOBAL_IGNORES) : null;
66
64
 
67
65
  const ENABLE_TYPE_AWARE_RULES = false;
68
66
 
@@ -76,6 +74,7 @@ const ENABLE_TYPE_AWARE_RULES = false;
76
74
  */
77
75
  let storybookConfig = null;
78
76
  try {
77
+ //TODO Add hasStorybook?
79
78
  const storybook = await import('eslint-plugin-storybook');
80
79
  storybookConfig = storybook.default.configs['flat/recommended'];
81
80
  } catch {
@@ -114,39 +113,10 @@ const reactFallbackConfig = hasNext
114
113
  jsxA11yPlugin.flatConfigs.recommended,
115
114
  ];
116
115
 
117
- /*
118
- * Gate the Turbo rule set on the tool actually being installed, same as jest/vitest above. A bare cwd
119
- * config-file check would make lint results depend on the invocation directory (IDE integrations and
120
- * per-package runs launch eslint from subdirectories). Without the turbo gate,
121
- * `turbo/no-undeclared-env-vars` treats "no turbo.json" as "nothing declared" and flags every single
122
- * env var access - useless noise for consumers that use NX (or nothing) instead. `eslint-plugin-turbo`
123
- * is bundled but does not drag in `turbo` itself, so this resolvability check stays honest.
124
- */
125
- const hasTurbo = isPackageResolvable('turbo/package.json');
126
-
127
- /*
128
- * NX cannot use the same resolvability gate: `nx` core is always resolvable here as a transitive dep of
129
- * the bundled @nx/eslint-plugin (-> @nx/devkit -> nx), so `isPackageResolvable('nx')` reports true in
130
- * every consumer - including plain non-Nx projects, where it wrongly switches on @nx/dependency-checks,
131
- * which then fails with no project graph. Detect an actual Nx workspace by walking up from cwd to an
132
- * `nx.json` instead: unlike a bare cwd check this is stable across subdirectory / per-package / IDE runs
133
- * (they resolve to the same workspace root) and correctly stays off outside an Nx workspace.
134
- */
135
- function hasWorkspaceFile(fileName) {
136
- let dir = process.cwd();
137
- for (;;) {
138
- if (existsSync(resolve(dir, fileName))) return true;
139
- const parent = dirname(dir);
140
- if (parent === dir) return false;
141
- dir = parent;
142
- }
143
- }
144
-
145
- const hasNx = hasWorkspaceFile('nx.json');
146
-
147
116
  // lazy for the same reason as nextPlugin above
148
117
  const turboPlugin = hasTurbo ? (await import('eslint-plugin-turbo')).default : null;
149
118
  const nxPlugin = hasNx ? (await import('@nx/eslint-plugin')).default : null;
119
+ const tailwindPlugin = hasTailwind ? (await import('eslint-plugin-tailwindcss')).default : null;
150
120
 
151
121
  const index = [
152
122
  js.configs.recommended,
@@ -160,16 +130,7 @@ const index = [
160
130
  * which would corrupt them if autofixed into a `/* *\/` block).
161
131
  */
162
132
  {
163
- ignores: [
164
- //TODO coverage, dist, out, build?
165
- '**/next-env.d.ts',
166
- '**/viteEnv.d.ts',
167
- '**/node_modules',
168
- '**/.cache',
169
- '**/.nx',
170
- '**/.turbo',
171
- '**/.yarn',
172
- ],
133
+ ignores: GLOBAL_IGNORES,
173
134
  },
174
135
 
175
136
  ...nextConfig,
@@ -378,7 +339,8 @@ const index = [
378
339
  /^opengraph-image\.[jt]sx?$/,
379
340
  /^twitter-image\.[jt]sx?$/,
380
341
  /^apple-icon\.[jt]sx?$/,
381
- /^next-env\.d\.ts$/,
342
+ /^mdx-components\.[jt]sx?$/,
343
+ /\.d\.tsx?$/,
382
344
  /^electron-builder\..+$/,
383
345
  ],
384
346
  },
@@ -495,10 +457,25 @@ const index = [
495
457
  '**/.prettierrc*',
496
458
  `**/App.${tsExts}`,
497
459
  `**/index.${tsExts}`,
460
+ `**/main.${tsExts}`,
461
+ '**/*.d.ts',
462
+ `**/default.${tsExts}`,
463
+ `**/error.${tsExts}`,
464
+ `**/forbidden.${tsExts}`,
465
+ `**/global-error.${tsExts}`,
498
466
  `**/layout.${tsExts}`,
499
467
  `**/loading.${tsExts}`,
500
- `**/main.${tsExts}`,
468
+ `**/not-found.${tsExts}`,
501
469
  `**/page.${tsExts}`,
470
+ `**/template.${tsExts}`,
471
+ `**/unauthorized.${tsExts}`,
472
+ `**/apple-icon.${tsExts}`,
473
+ `**/icon.${tsExts}`,
474
+ `**/manifest.${tsExts}`,
475
+ `**/opengraph-image.${tsExts}`,
476
+ `**/robots.${tsExts}`,
477
+ `**/sitemap.${tsExts}`,
478
+ `**/twitter-image.${tsExts}`,
502
479
  ],
503
480
  rules: {
504
481
  /*
@@ -526,6 +503,25 @@ const index = [
526
503
  ]
527
504
  : []),
528
505
 
506
+ /*
507
+ * Recommended rules (warnings + `no-contradicting-classname` as error), re-scoped from the
508
+ * plugin's global js/jsx/ts/tsx default to only the detected Tailwind project dirs - see the
509
+ * two-gate comment above findTailwindProjectDirs().
510
+ */
511
+ /*
512
+ * Standalone block (simple to override wholesale), auto-added only when exactly one Tailwind v4
513
+ * entry CSS was found - see the auto-find comment above findTailwindEntry(). Recommended rules:
514
+ * warnings + `no-contradicting-classname` as error.
515
+ */
516
+ ...(tailwindEntry
517
+ ? [
518
+ {
519
+ ...tailwindPlugin.configs.recommended,
520
+ settings: { tailwindcss: { cssConfigPath: tailwindEntry } },
521
+ },
522
+ ]
523
+ : []),
524
+
529
525
  ...(hasNx
530
526
  ? [
531
527
  /*
@@ -611,7 +607,7 @@ const index = [
611
607
 
612
608
  export default index;
613
609
 
614
- export { nextPlugin, nxPlugin, turboPlugin, jestPlugin, vitestPlugin, storybookConfig };
610
+ export { nextPlugin, nxPlugin, turboPlugin, jestPlugin, vitestPlugin, findTailwindEntry };
615
611
 
616
612
  /**
617
613
  * @param {string} importMetaUrl
package/lib.js ADDED
@@ -0,0 +1,52 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { dirname, resolve } from 'node:path';
3
+
4
+ //TODO coverage, dist, out, build?
5
+ export const GLOBAL_IGNORES = [
6
+ '**/next-env.d.ts',
7
+ '**/viteEnv.d.ts',
8
+ '**/node_modules',
9
+ '**/.cache',
10
+ '**/.nx',
11
+ '**/.turbo',
12
+ '**/.yarn',
13
+ ];
14
+
15
+ /**
16
+ * Capability gate: is a package installed in the consumer's project?
17
+ *
18
+ * @param {string} specifier e.g. `'next/package.json'` - probe package.json, importing the real entry could have side effects
19
+ * @returns {boolean}
20
+ */
21
+ export function isPackageResolvable(specifier) {
22
+ try {
23
+ import.meta.resolve(specifier);
24
+ return true;
25
+ } catch {
26
+ return false;
27
+ }
28
+ }
29
+
30
+ /**
31
+ * Detect a workspace by walking up from cwd to a marker file (e.g. `nx.json`). Unlike a bare cwd
32
+ * check this is stable across subdirectory / per-package / IDE runs - they all resolve to the same
33
+ * workspace root - and correctly stays negative outside such a workspace.
34
+ *
35
+ * The walk is bounded by the git root: a workspace marker can't meaningfully live above `.git`, and
36
+ * stopping there prevents a stray marker file elsewhere on the disk (e.g. in the home directory)
37
+ * from switching the gate on. `.git` is a directory in a normal clone but a FILE in worktrees and
38
+ * submodules - existsSync covers both.
39
+ *
40
+ * @param {string} fileName marker file, e.g. `'nx.json'`
41
+ * @returns {boolean}
42
+ */
43
+ export function hasWorkspaceFile(fileName) {
44
+ let dir = process.cwd();
45
+ for (;;) {
46
+ if (existsSync(resolve(dir, fileName))) return true;
47
+ if (existsSync(resolve(dir, '.git'))) return false;
48
+ const parent = dirname(dir);
49
+ if (parent === dir) return false;
50
+ dir = parent;
51
+ }
52
+ }
package/lintPrepare.js CHANGED
@@ -20,7 +20,7 @@
20
20
 
21
21
  import fs from 'node:fs';
22
22
  import path from 'node:path';
23
- import { fileURLToPath, pathToFileURL } from 'node:url';
23
+ import { fileURLToPath } from 'node:url';
24
24
 
25
25
  const __filename = fileURLToPath(import.meta.url);
26
26
  const __dirname = path.dirname(__filename);
@@ -321,6 +321,6 @@ export function main() {
321
321
  }
322
322
 
323
323
  // Only run when executed directly (e.g. `lint-prepare init`), not when imported.
324
- if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
324
+ if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(__filename)) {
325
325
  main();
326
326
  }
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.1.0",
4
+ "version": "0.2.0",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
@@ -19,6 +19,8 @@
19
19
  },
20
20
  "files": [
21
21
  "index.js",
22
+ "findTailwindEntry.js",
23
+ "lib.js",
22
24
  "lintPrepare.js",
23
25
  "ruleTestColocation.js",
24
26
  "rules",
@@ -43,9 +45,11 @@
43
45
  "eslint-plugin-react-hooks": "^7.0.1",
44
46
  "eslint-plugin-simple-import-sort": "^14.0.0",
45
47
  "eslint-plugin-storybook": "^10.5.2",
48
+ "eslint-plugin-tailwindcss": "^4.2.0",
46
49
  "eslint-plugin-turbo": "^2.10.5",
47
50
  "eslint-plugin-unicorn": "^72.0.0",
48
51
  "eslint-plugin-unused-imports": "^4.4.1",
52
+ "glob": "^13.0.6",
49
53
  "globals": "^16.4.0",
50
54
  "jsonc-eslint-parser": "^2.4.2"
51
55
  },
@@ -56,6 +60,7 @@
56
60
  "lint-staged": "^16",
57
61
  "next": "^16",
58
62
  "storybook": "^10.5.2",
63
+ "tailwindcss": "*",
59
64
  "vite": "*",
60
65
  "vitest": "*"
61
66
  },
@@ -69,6 +74,9 @@
69
74
  "storybook": {
70
75
  "optional": true
71
76
  },
77
+ "tailwindcss": {
78
+ "optional": true
79
+ },
72
80
  "vite": {
73
81
  "optional": true
74
82
  },
package/rules/tailwind.md CHANGED
@@ -7,6 +7,28 @@ description: Set of rules for projects which use Tailwind
7
7
  - Default UI library for use with Tailwind is Hero UI v3+
8
8
  - Use the smallest possible configuration of Tailwind and Hero UI, adhere to their best practices (for Vite, Next.js integration, etc.)
9
9
 
10
+ # ESLint (eslint-plugin-tailwindcss, bundled with @kirill.konshin/lint)
11
+
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
+ - ONLY when auto-find finds nothing (or several entries) add the block manually with a MANDATORY `settings.tailwindcss.cssConfigPath` in `eslint.config.mjs`:
15
+
16
+ ```js
17
+ import customConfig, { tailwindPlugin } from '@kirill.konshin/lint';
18
+
19
+ export default defineConfig([
20
+ ...customConfig,
21
+ {
22
+ ...tailwindPlugin.configs.recommended,
23
+ settings: {
24
+ tailwindcss: {
25
+ cssConfigPath: './src/styles/tailwind.css', // MANDATORY, relative to the package root
26
+ },
27
+ },
28
+ },
29
+ ]);
30
+ ```
31
+
10
32
  # Hero UI
11
33
 
12
34
  - Always extract Compound Components as reusable UI kit library of project-specific Components if used more than once, never duplicate boilerplate, except highly custom ones, if in doubt ask confirmation from user