@kirill.konshin/lint 0.6.7 → 0.7.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.
Files changed (50) hide show
  1. package/README.md +253 -94
  2. package/dist/configs/imports.js +3 -30
  3. package/dist/configs/react.d.ts +0 -15
  4. package/dist/configs/react.js +2 -36
  5. package/dist/configs/tailwind.d.ts +10 -0
  6. package/dist/configs/tailwind.js +25 -9
  7. package/dist/configs/testing.js +2 -41
  8. package/dist/configs/unicorn.js +2 -10
  9. package/dist/conventions.d.ts +12 -0
  10. package/dist/conventions.js +53 -0
  11. package/dist/index.d.ts +4 -4
  12. package/dist/index.js +4 -4
  13. package/dist/lib.d.ts +18 -1
  14. package/dist/lib.js +36 -2
  15. package/dist/lintPrepare.d.ts +2 -1
  16. package/dist/lintPrepare.js +13 -1
  17. package/dist/oxlintPlugin.d.ts +10 -0
  18. package/dist/oxlintPlugin.js +13 -0
  19. package/dist/testColocation.d.ts +10 -0
  20. package/dist/testColocation.js +45 -0
  21. package/dist/vitePlus.d.ts +58 -0
  22. package/dist/vitePlus.js +434 -0
  23. package/package.json +32 -9
  24. package/rules/agent.md +3 -0
  25. package/rules/code-style.md +1 -1
  26. package/rules/github.md +4 -1
  27. package/rules/gitlab.md +3 -5
  28. package/rules/jest.md +1 -1
  29. package/rules/markdown.md +11 -0
  30. package/rules/monorepo-turbo-nx.md +9 -0
  31. package/rules/mui.md +0 -2
  32. package/rules/npm-yarn.md +10 -1
  33. package/rules/nx.md +3 -1
  34. package/rules/playwright.md +18 -0
  35. package/rules/react.md +1 -3
  36. package/rules/tailwind.md +1 -0
  37. package/rules/testing.md +5 -2
  38. package/rules/typescript.md +5 -4
  39. package/rules/vite.md +5 -1
  40. package/{rules/electron.md → skills/lint-electron/SKILL.md} +5 -3
  41. package/skills/lint-github/SKILL.md +244 -42
  42. package/skills/lint-gitlab/SKILL.md +46 -1
  43. package/skills/lint-migrate/SKILL.md +24 -0
  44. package/skills/lint-repo/SKILL.md +21 -5
  45. package/skills/lint-webstorm/SKILL.md +55 -3
  46. package/skills/spec-steward/SKILL.md +72 -15
  47. package/skills/spec-steward/references/contract.md +6 -6
  48. package/skills/spec-tools/SKILL.md +11 -11
  49. package/skills/spec-tools/references/rules/common.md +32 -7
  50. package/skills/spec-tools/scripts/cli.js +18 -12
@@ -0,0 +1,434 @@
1
+ import { eslintExts, markupExtsRaw, prettierExtsRaw, tsExts, tsExtsRaw } from "./exts.js";
2
+ import { defaultExportFiles, filenameCaseIgnore } from "./conventions.js";
3
+ import { GLOBAL_IGNORES, asOptions, findNextRoots, findWorkspaceRoot, hasJest, hasNext, hasNx, hasStorybook, hasTurbo, scanWorkspace, toolGate } from "./lib.js";
4
+ import { tailwindGate } from "./configs/tailwind.js";
5
+ import { dirname, relative } from "node:path";
6
+ import { fileURLToPath } from "node:url";
7
+ //#region src/vitePlus.ts
8
+ const TS_FILES = `**/*.${tsExts}`;
9
+ const TEST_FILES = `**/*.{test,spec}.${tsExts}`;
10
+ /**
11
+ * Type-aware `correctness` rules of Oxlint 1.88 that stay off when `typeAware` is on. Tried on this monorepo they
12
+ * reported mostly noise (`act()` with sync callbacks, `for await` over sync iterables, unions with `any`); the
13
+ * other type-aware `correctness` rules stay on — `no-misused-spread`, `no-base-to-string` and `unbound-method` found
14
+ * real bugs (dropped headers, `"[object Object]"` URLs, lost `this`). Re-enable per project in `lint.rules`.
15
+ */
16
+ const TYPE_AWARE_CORRECTNESS_OFF = [
17
+ "typescript/await-thenable",
18
+ "typescript/no-floating-promises",
19
+ "typescript/no-redundant-type-constituents",
20
+ "typescript/no-useless-default-assignment",
21
+ "typescript/require-array-sort-compare",
22
+ "typescript/restrict-template-expressions"
23
+ ];
24
+ /** Resolved from this package, so a JS plugin loads even when the consumer does not hoist it. */
25
+ function pluginPath(specifier) {
26
+ return fileURLToPath(import.meta.resolve(specifier));
27
+ }
28
+ /** A workspace-root-relative glob for an absolute directory (Oxlint override globs resolve from the config file). */
29
+ function workspaceGlob(dir, glob) {
30
+ const rel = relative(findWorkspaceRoot(), dir).replaceAll("\\", "/");
31
+ return rel ? `${rel}/${glob}` : glob;
32
+ }
33
+ /**
34
+ * Oxlint config: the ESLint config's rules, by Oxlint's names. Each plugin's `recommended` set maps to Oxlint's
35
+ * `correctness` category; the deliberate overrides of the ESLint config are listed rule by rule. Plugins Oxlint has no
36
+ * native port of (Nx, Storybook, Tailwind, Turbo, the local `test-colocation` rule) run as JS plugins.
37
+ *
38
+ * Not carried over: `@nx/dependency-checks` (Oxlint does not lint JSON), `multiline-comment-style` (off anyway),
39
+ * `@typescript-eslint/naming-convention` (type-aware only, off by default), the resolution-dependent `import-x` rules
40
+ * (off anyway). Import sorting moves to Oxfmt (`sortImports`), unused-import removal to `no-unused-vars` with an
41
+ * import autofix.
42
+ */
43
+ function lintConfig(options = {}) {
44
+ const { enabled: defaultOn = true, strict = false } = asOptions(options.detection);
45
+ const flag = (option) => option === void 0 && !defaultOn ? false : option;
46
+ const next = toolGate(flag(options.next), strict, {
47
+ tool: "next",
48
+ has: hasNext,
49
+ requirePackage: false,
50
+ scan: () => findNextRoots(GLOBAL_IGNORES).map((dir) => `${dir}/package.json`)
51
+ });
52
+ const storybook = toolGate(flag(options.storybook), strict, {
53
+ tool: "storybook",
54
+ has: hasStorybook,
55
+ packageName: "storybook",
56
+ scan: () => scanWorkspace(".storybook/main.*", GLOBAL_IGNORES, { dot: true })
57
+ });
58
+ const turbo = toolGate(flag(options.turbo), false, {
59
+ tool: "turbo",
60
+ has: hasTurbo,
61
+ requirePackage: false
62
+ });
63
+ const nx = toolGate(flag(options.nx), strict, {
64
+ tool: "nx",
65
+ has: hasNx,
66
+ packageName: "eslint"
67
+ });
68
+ const jest = toolGate(flag(options.jest), strict, {
69
+ tool: "jest",
70
+ has: hasJest,
71
+ requirePackage: false,
72
+ scan: () => scanWorkspace("jest.config.*", GLOBAL_IGNORES)
73
+ });
74
+ const vitest = asOptions(flag(options.vitest)).enabled ?? true;
75
+ const tailwind = tailwindGate(flag(options.tailwind), strict);
76
+ const { enabled: typeAware = true } = asOptions(options.typeAware);
77
+ const jsPlugins = [{
78
+ name: "local",
79
+ specifier: pluginPath("@kirill.konshin/lint/oxlint-plugin")
80
+ }];
81
+ if (nx.enabled) jsPlugins.push({
82
+ name: "@nx",
83
+ specifier: pluginPath("@nx/eslint-plugin")
84
+ });
85
+ const overrides = [
86
+ {
87
+ files: ["**/*.d.ts"],
88
+ rules: { "typescript/consistent-type-imports": ["error", {
89
+ prefer: "type-imports",
90
+ fixStyle: "inline-type-imports",
91
+ disallowTypeAnnotations: false
92
+ }] }
93
+ },
94
+ {
95
+ files: defaultExportFiles,
96
+ rules: { "import/no-default-export": "off" }
97
+ },
98
+ {
99
+ files: [TEST_FILES],
100
+ plugins: [...vitest ? ["vitest"] : [], ...jest.enabled ? ["jest"] : []],
101
+ env: {
102
+ ...vitest ? { vitest: true } : {},
103
+ ...jest.enabled ? { jest: true } : {}
104
+ },
105
+ rules: {
106
+ "local/test-colocation": "error",
107
+ ...vitest ? {
108
+ "vitest/consistent-test-it": ["error", { fn: "test" }],
109
+ "vitest/no-disabled-tests": "warn",
110
+ "vitest/require-mock-type-parameters": "off",
111
+ "vitest/expect-expect": ["error", { assertFunctionNames: [
112
+ "expect",
113
+ "assert",
114
+ "expectTypeOf",
115
+ "assertType"
116
+ ] }]
117
+ } : {},
118
+ ...jest.enabled ? {
119
+ "jest/consistent-test-it": ["error", { fn: "test" }],
120
+ "jest/no-disabled-tests": "warn"
121
+ } : {}
122
+ }
123
+ }
124
+ ];
125
+ if (storybook.enabled) {
126
+ const specifier = pluginPath("eslint-plugin-storybook");
127
+ overrides.push({
128
+ files: [`**/*.{stories,story}.${tsExts}`],
129
+ jsPlugins: [{
130
+ name: "storybook",
131
+ specifier
132
+ }],
133
+ rules: {
134
+ "react/rules-of-hooks": "off",
135
+ "import/no-anonymous-default-export": "off",
136
+ "storybook/await-interactions": "error",
137
+ "storybook/context-in-play-function": "error",
138
+ "storybook/default-exports": "error",
139
+ "storybook/hierarchy-separator": "warn",
140
+ "storybook/no-redundant-story-name": "warn",
141
+ "storybook/no-renderer-packages": "error",
142
+ "storybook/prefer-pascal-case": "warn",
143
+ "storybook/story-exports": "error",
144
+ "storybook/use-storybook-expect": "error",
145
+ "storybook/use-storybook-testing-library": "error"
146
+ }
147
+ }, {
148
+ files: [`**/.storybook/main.${tsExts}`],
149
+ jsPlugins: [{
150
+ name: "storybook",
151
+ specifier
152
+ }],
153
+ rules: { "storybook/no-uninstalled-addons": "error" }
154
+ });
155
+ }
156
+ if (tailwind) overrides.push({
157
+ files: [tailwind.packageDir ? workspaceGlob(tailwind.packageDir, TS_FILES) : TS_FILES],
158
+ jsPlugins: [{
159
+ name: "tailwindcss",
160
+ specifier: pluginPath("eslint-plugin-tailwindcss")
161
+ }],
162
+ rules: {
163
+ "tailwindcss/classnames-order": "warn",
164
+ "tailwindcss/enforces-negative-arbitrary-values": "warn",
165
+ "tailwindcss/enforces-shorthand": "warn",
166
+ "tailwindcss/important-modifier-suffix": "warn",
167
+ "tailwindcss/no-custom-classname": "warn",
168
+ "tailwindcss/no-contradicting-classname": "error",
169
+ "tailwindcss/no-unnecessary-arbitrary-value": "warn"
170
+ }
171
+ });
172
+ if (turbo.enabled) overrides.push({
173
+ files: [TS_FILES],
174
+ jsPlugins: [{
175
+ name: "turbo",
176
+ specifier: pluginPath("eslint-plugin-turbo")
177
+ }],
178
+ rules: { "turbo/no-undeclared-env-vars": "warn" }
179
+ });
180
+ return {
181
+ plugins: [
182
+ "eslint",
183
+ "typescript",
184
+ "unicorn",
185
+ "oxc",
186
+ "import",
187
+ "promise",
188
+ "react",
189
+ "jsx-a11y",
190
+ ...next.enabled ? ["nextjs"] : []
191
+ ],
192
+ jsPlugins,
193
+ categories: { correctness: "error" },
194
+ env: {
195
+ builtin: true,
196
+ browser: true,
197
+ node: true
198
+ },
199
+ ignorePatterns: GLOBAL_IGNORES,
200
+ settings: {
201
+ react: { version: "19" },
202
+ ...next.enabled && next.files.length > 0 ? { next: { rootDir: next.files.map(dirname) } } : {},
203
+ ...tailwind ? { tailwindcss: { cssConfigPath: tailwind.absoluteCssConfigPath } } : {}
204
+ },
205
+ ...typeAware ? { options: {
206
+ typeAware: true,
207
+ typeCheck: true
208
+ } } : {},
209
+ rules: {
210
+ "no-restricted-imports": ["error", { paths: [{
211
+ name: "next/router",
212
+ message: "Please use next/navigation instead of next/router"
213
+ }] }],
214
+ "no-unused-vars": ["error", {
215
+ args: "none",
216
+ caughtErrors: "none",
217
+ ignoreRestSiblings: true,
218
+ varsIgnorePattern: "^_",
219
+ fix: {
220
+ imports: "safe-fix",
221
+ variables: "suggestion"
222
+ }
223
+ }],
224
+ "unicorn/prefer-string-starts-ends-with": "off",
225
+ "unicorn/no-useless-spread": "off",
226
+ "unicorn/no-thenable": "off",
227
+ "unicorn/no-empty-file": "off",
228
+ "jsx-a11y/prefer-tag-over-role": "off",
229
+ "typescript/no-useless-empty-export": "off",
230
+ "typescript/consistent-type-definitions": ["error", "type"],
231
+ "typescript/consistent-type-imports": ["error", {
232
+ prefer: "type-imports",
233
+ fixStyle: "inline-type-imports"
234
+ }],
235
+ "typescript/ban-ts-comment": ["error", {
236
+ "ts-expect-error": "allow-with-description",
237
+ "ts-ignore": true,
238
+ "ts-nocheck": true,
239
+ "ts-check": false,
240
+ minimumDescriptionLength: 3
241
+ }],
242
+ "typescript/prefer-as-const": "error",
243
+ "typescript/no-explicit-any": "off",
244
+ "typescript/no-empty-function": "off",
245
+ "typescript/no-require-imports": "off",
246
+ ...typeAware ? {
247
+ "typescript/prefer-optional-chain": "warn",
248
+ "typescript/prefer-nullish-coalescing": "warn",
249
+ ...Object.fromEntries(TYPE_AWARE_CORRECTNESS_OFF.map((rule) => [rule, "off"]))
250
+ } : {},
251
+ "react/rules-of-hooks": "error",
252
+ "react/exhaustive-deps": "warn",
253
+ "react/static-components": "error",
254
+ "react/use-memo": "error",
255
+ "react/void-use-memo": "error",
256
+ "react/preserve-manual-memoization": "error",
257
+ "react/incompatible-library": "warn",
258
+ "react/immutability": "error",
259
+ "react/globals": "error",
260
+ "react/refs": "error",
261
+ "react/set-state-in-effect": "error",
262
+ "react/error-boundaries": "error",
263
+ "react/purity": "error",
264
+ "react/set-state-in-render": "error",
265
+ "react/unsupported-syntax": "warn",
266
+ "react/react-in-jsx-scope": "off",
267
+ "jsx-a11y/alt-text": "off",
268
+ ...next.enabled ? {
269
+ "nextjs/no-html-link-for-pages": "off",
270
+ "nextjs/no-img-element": "off"
271
+ } : {},
272
+ "import/no-anonymous-default-export": "off",
273
+ "import/no-default-export": "warn",
274
+ "promise/prefer-await-to-then": "warn",
275
+ "promise/param-names": "off",
276
+ "promise/always-return": "off",
277
+ "promise/catch-or-return": "off",
278
+ "unicorn/filename-case": ["error", {
279
+ case: "camelCase",
280
+ ignore: filenameCaseIgnore.map((regex) => regex.source)
281
+ }],
282
+ "unicorn/prefer-node-protocol": "error"
283
+ },
284
+ overrides
285
+ };
286
+ }
287
+ /**
288
+ * Oxfmt config: the Prettier config (`./prettier`), plus the import order `simple-import-sort` enforced (see
289
+ * typescript.md). Oxfmt reads `.editorconfig`, which Prettier partly ignored, so the Prettier behaviors that differ
290
+ * from an `.editorconfig` are set explicitly (`insertFinalNewline`). `package.json` key order is left alone, as
291
+ * Prettier did. Oxfmt honours `.gitignore` and `.prettierignore`; the `.prettierignore` the README recommended is the
292
+ * default `ignorePatterns`. With `proseWrap: 'never'` a Markdown table is aligned only while it fits `printWidth`, so
293
+ * Markdown gets 200 columns; a wider table is HTML, or stays unaligned when it is mostly code (rules/markdown.md).
294
+ */
295
+ function fmtConfig() {
296
+ return {
297
+ printWidth: 120,
298
+ tabWidth: 2,
299
+ singleQuote: true,
300
+ proseWrap: "never",
301
+ insertFinalNewline: true,
302
+ sortPackageJson: false,
303
+ ignorePatterns: [
304
+ ".idea",
305
+ ".husky",
306
+ ".yarn",
307
+ "/AGENTS.md",
308
+ "**/next-env.d.ts",
309
+ ".agents/skills/openspec-*",
310
+ ".claude/skills/openspec-*",
311
+ ".claude/commands/opsx"
312
+ ],
313
+ sortImports: {
314
+ customGroups: [{
315
+ groupName: "polyfill",
316
+ selector: "side_effect",
317
+ elementNamePattern: [
318
+ "server-only",
319
+ "client-only",
320
+ "**polyfill**",
321
+ "core-js",
322
+ "core-js/**",
323
+ "regenerator-runtime",
324
+ "regenerator-runtime/**",
325
+ "whatwg-fetch",
326
+ "@vitest/web-worker"
327
+ ]
328
+ }, {
329
+ groupName: "react",
330
+ elementNamePattern: [
331
+ "react",
332
+ "react/**",
333
+ "react-dom",
334
+ "react-dom/**"
335
+ ]
336
+ }],
337
+ groups: [
338
+ "polyfill",
339
+ "react",
340
+ "builtin",
341
+ { newlinesBetween: false },
342
+ "external",
343
+ "internal",
344
+ { newlinesBetween: false },
345
+ [
346
+ "subpath",
347
+ "parent",
348
+ "sibling",
349
+ "index"
350
+ ],
351
+ ["side_effect_style", "side_effect"],
352
+ "unknown"
353
+ ]
354
+ },
355
+ overrides: [{
356
+ files: [`**/${eslintExts}`],
357
+ options: { tabWidth: 4 }
358
+ }, {
359
+ files: ["**/*.{md,mdx}"],
360
+ options: {
361
+ sortImports: false,
362
+ printWidth: 200
363
+ }
364
+ }]
365
+ };
366
+ }
367
+ /**
368
+ * Staged-file checks (`vp staged`): what lint-staged ran, as one `vp check --fix` - it formats every file and lints
369
+ * the code files, so no two tasks race on one file.
370
+ */
371
+ function stagedConfig() {
372
+ return { [`*.{${tsExtsRaw},${markupExtsRaw},${prettierExtsRaw}}`]: "vp check --fix" };
373
+ }
374
+ /**
375
+ * The shared Vite+ config: {@link lintConfig}, {@link fmtConfig} and {@link stagedConfig} merged with the consumer's
376
+ * own config. Lists add up (`plugins`, `jsPlugins`, `overrides`, `ignorePatterns`), maps merge key by key (`rules`,
377
+ * `settings`, `env`, ...), and a consumer's `staged` replaces the default. Wrap the result in `defineConfig`:
378
+ *
379
+ * ```ts
380
+ * import { vitePlusConfig } from '@kirill.konshin/lint/vite-plus';
381
+ * import { defineConfig } from 'vite-plus';
382
+ *
383
+ * export default defineConfig(vitePlusConfig({ lint: { rules: { ... } } }));
384
+ * ```
385
+ */
386
+ function vitePlusConfig(config = {}, options = {}) {
387
+ const { lint = {}, fmt = {}, staged, ...rest } = config;
388
+ const baseLint = lintConfig(options);
389
+ const baseFmt = fmtConfig();
390
+ return {
391
+ ...rest,
392
+ lint: {
393
+ ...baseLint,
394
+ ...lint,
395
+ plugins: [.../* @__PURE__ */ new Set([...baseLint.plugins ?? [], ...lint.plugins ?? []])],
396
+ jsPlugins: [...baseLint.jsPlugins ?? [], ...lint.jsPlugins ?? []],
397
+ categories: {
398
+ ...baseLint.categories,
399
+ ...lint.categories
400
+ },
401
+ env: {
402
+ ...baseLint.env,
403
+ ...lint.env
404
+ },
405
+ globals: {
406
+ ...baseLint.globals,
407
+ ...lint.globals
408
+ },
409
+ settings: {
410
+ ...baseLint.settings,
411
+ ...lint.settings
412
+ },
413
+ ...baseLint.options || lint.options ? { options: {
414
+ ...baseLint.options,
415
+ ...lint.options
416
+ } } : {},
417
+ ignorePatterns: [...baseLint.ignorePatterns ?? [], ...lint.ignorePatterns ?? []],
418
+ rules: {
419
+ ...baseLint.rules,
420
+ ...lint.rules
421
+ },
422
+ overrides: [...baseLint.overrides ?? [], ...lint.overrides ?? []]
423
+ },
424
+ fmt: {
425
+ ...baseFmt,
426
+ ...fmt,
427
+ ignorePatterns: [...baseFmt.ignorePatterns ?? [], ...fmt.ignorePatterns ?? []],
428
+ overrides: [...baseFmt.overrides ?? [], ...fmt.overrides ?? []]
429
+ },
430
+ staged: staged ?? stagedConfig()
431
+ };
432
+ }
433
+ //#endregion
434
+ export { fmtConfig, lintConfig, stagedConfig, tsExts, vitePlusConfig };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@kirill.konshin/lint",
3
- "description": "ESLint + Prettier + lint-staged config and AI agent rules/skills for monorepos",
4
- "version": "0.6.7",
3
+ "description": "Vite+ (Oxlint + Oxfmt), ESLint + Prettier + lint-staged configs and AI agent rules/skills for monorepos",
4
+ "version": "0.7.0",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
@@ -26,6 +26,16 @@
26
26
  "import": "./dist/prettier.js",
27
27
  "default": "./dist/prettier.js"
28
28
  },
29
+ "./vite-plus": {
30
+ "types": "./dist/vitePlus.d.ts",
31
+ "import": "./dist/vitePlus.js",
32
+ "default": "./dist/vitePlus.js"
33
+ },
34
+ "./oxlint-plugin": {
35
+ "types": "./dist/oxlintPlugin.d.ts",
36
+ "import": "./dist/oxlintPlugin.js",
37
+ "default": "./dist/oxlintPlugin.js"
38
+ },
29
39
  "./yarn": {
30
40
  "types": "./dist/yarn.d.cts",
31
41
  "require": "./dist/yarn.cjs"
@@ -34,11 +44,10 @@
34
44
  "scripts": {
35
45
  "----- BUILD -----": "",
36
46
  "clean": "rm -rf dist skills/spec-tools/scripts",
37
- "build": "tsdown",
38
- "start": "tsdown --watch",
47
+ "build": "vp pack",
48
+ "start": "vp pack --watch",
39
49
  "----- TEST -----": "",
40
- "typecheck": "tsc --noEmit",
41
- "test": "yarn build && yarn typecheck && vitest run"
50
+ "test": "yarn build && vp test run"
42
51
  },
43
52
  "files": [
44
53
  "dist",
@@ -83,15 +92,17 @@
83
92
  "@types/eslint-plugin-jsx-a11y": "^6.10.1",
84
93
  "@types/eslint-plugin-promise": "^7.3.0",
85
94
  "github-markdown-css": "^5.9.0",
95
+ "lint-staged": "^17.3.0",
86
96
  "marked": "^18.0.5",
87
- "tsdown": "^0.23.0",
88
- "vitest": "^4.1.10"
97
+ "prettier": "^3.9.6",
98
+ "typescript": "^6.0.3",
99
+ "vite-plus": "^1.3.0"
89
100
  },
90
101
  "peerDependencies": {
91
102
  "eslint": "^10",
92
103
  "husky": "^9",
93
104
  "jest": "^30",
94
- "lint-staged": "^16",
105
+ "lint-staged": "^16 || ^17",
95
106
  "next": "^16",
96
107
  "prettier": "^3",
97
108
  "storybook": "^10",
@@ -101,12 +112,24 @@
101
112
  "vitest": "^4"
102
113
  },
103
114
  "peerDependenciesMeta": {
115
+ "eslint": {
116
+ "optional": true
117
+ },
118
+ "husky": {
119
+ "optional": true
120
+ },
104
121
  "jest": {
105
122
  "optional": true
106
123
  },
124
+ "lint-staged": {
125
+ "optional": true
126
+ },
107
127
  "next": {
108
128
  "optional": true
109
129
  },
130
+ "prettier": {
131
+ "optional": true
132
+ },
110
133
  "storybook": {
111
134
  "optional": true
112
135
  },
package/rules/agent.md CHANGED
@@ -66,6 +66,9 @@ Do not use `.claude/commands` for anything. It's not portable (`.agent/commands`
66
66
  - Directory-specific rules & instructions should be in `AGENTS.md` of that folder
67
67
  - Lift rules & instructions up the tree to higher `AGENTS.md` if multiple dirs must adhere to them, don't copy-paste them
68
68
  - All `AGENTS.md` files should be accompanied by a symlink `CLAUDE.md`
69
+ - Tool-provided agent instructions: tools install and maintain their own — NEVER copy or hand-wire their content
70
+ - `lint-prepare` writes each tool's empty marker pair into the generated `AGENTS.md` (e.g. `<!--VITE PLUS START-->`); the tool runs AFTER it in the same install script and fills it (`lint-prepare init && vp config`); content between the markers is the tool's, do not edit it
71
+ - Do not run a tool's setup command just to get its agent files when it also rewrites the project (`vp migrate --agent`, `vp create`); the anchor is enough
69
72
 
70
73
  # `.agents/rules`
71
74
 
@@ -3,6 +3,6 @@ type: always_apply
3
3
  description: Set of general coding style rules
4
4
  ---
5
5
 
6
- - When generating code respect max length set in `.editorconfig` or `.prettierrc` (could be with extension)
6
+ - When generating code respect max length set in `.editorconfig`, the `fmt` block of `vite.config.ts` or `.prettierrc` (could be with extension)
7
7
  - Always wrap configurations in `defineConfig` if provided to ensure type safety (eslint, vite, vitest, jest, playwright, yarn, etc.)
8
8
  - Prefer TS-based configurations if possible (next.js, vite, vitest)
package/rules/github.md CHANGED
@@ -8,4 +8,7 @@ paths:
8
8
  ---
9
9
 
10
10
  - Agentic review MUST verify this effective CI order: checkout -> enable Corepack -> setup Node with Yarn cache -> restore build caches -> immutable install -> prepare -> verification (lint/test/build) -> publish; publishing MUST depend on successful verification.
11
- - In multi-job workflows, use job-specific build-cache keys with a same-run fallback so downstream jobs reuse upstream results without immutable-key collisions.
11
+ - Key build caches per commit when jobs run one after another: key `${{ runner.os }}-<tool>-${{ github.sha }}`, restore key `${{ runner.os }}-<tool>-`. A later job gets an exact hit and does not save again.
12
+ - Key build caches per job and commit when jobs run in parallel: key `${{ runner.os }}-<tool>-${{ github.job }}-${{ github.sha }}`, restore key `${{ runner.os }}-<tool>-${{ github.job }}-`. Only the first job that saves a key keeps its outputs. A downstream job restores the producing job's key and does not save.
13
+ - With Nx Cloud (`nxCloudId` in `nx.json`): no `.nx` cache steps; workflow-level `env: NX_CLOUD_ACCESS_TOKEN` — `${{ secrets.NX_CLOUD_ACCESS_TOKEN }}` (read-write) in workflows that run only on `main`, `${{ secrets.NX_CLOUD_ACCESS_TOKEN_READ_ONLY }}` in PR workflows, both repository secrets (fork PRs get no secrets and run without the cache); see `lint-github` skill.
14
+ - Without Nx Cloud, when caching Nx locally, cache its DB as `.nx/workspace-data/default-v*.db` next to `.nx/cache`: rename it to the runner's machine ID before install and back to `default-v*.db` before an explicit `actions/cache/save`, otherwise Nx ignores the restored `.nx/cache` (see `lint-github` skill).
package/rules/gitlab.md CHANGED
@@ -10,8 +10,6 @@ paths:
10
10
  - Always collect coverage from tests
11
11
  - Always publish important build stats as artifacts
12
12
  - Agentic review MUST verify this effective CI order: checkout and cache restore -> enable Corepack -> immutable install -> prepare -> verification (lint/test/build) -> publish; publishing MUST depend on successful verification.
13
- - Keep local build-cache keys job-specific in parallel pipelines; use a remote Nx or Turbo cache when results must be shared across jobs.
14
-
15
- # Example
16
-
17
- - Use Nx Cloud or Turbo Remote Cache when build results must be shared safely across parallel jobs.
13
+ - Keep local build-cache keys job-specific in parallel pipelines; a remote Nx or Turbo cache is needed only to share results between different jobs.
14
+ - With Nx Cloud (`nxCloudId` in `nx.json`): no `.nx` cache; `NX_CLOUD_ACCESS_TOKEN` is a masked **protected** CI/CD variable holding a read-write token (protected branches only), and merge-request pipelines map `NX_CLOUD_ACCESS_TOKEN: $NX_CLOUD_ACCESS_TOKEN_READ_ONLY` from a masked unprotected variable; see `lint-gitlab` skill.
15
+ - Without Nx Cloud, when caching Nx locally, cache its DB as `.nx/workspace-data/default-v*.db` next to `.nx/cache`: rename it to the runner's machine ID in `before_script` (before install) and back to `default-v*.db` in `after_script`, otherwise Nx ignores the restored `.nx/cache` (see `lint-gitlab` skill).
package/rules/jest.md CHANGED
@@ -7,4 +7,4 @@ paths:
7
7
 
8
8
  - Always prefer TS-based config. Choice of loader is dictated by other installed packages, https://jestjs.io/docs/configuration (first tip about loaders)
9
9
  - In monorepo define root jest project https://jestjs.io/docs/configuration#projects-arraystring--projectconfig
10
- - Prefer Vitest instead of Jest
10
+ - Prefer Vitest (with Vite+, `vp test`) instead of Jest
@@ -0,0 +1,11 @@
1
+ ---
2
+ type: always_apply
3
+ description: Markdown writing rules
4
+ paths:
5
+ - '**/*.md'
6
+ - '**/*.mdx'
7
+ ---
8
+
9
+ - A Markdown table may be up to 200 columns wide once aligned (Markdown is formatted at `printWidth` 200, so it stays aligned); a wider table is an HTML `<table>`
10
+ - Exception: a table whose cells are mostly code spans (paths, globs, commands, identifiers) stays Markdown however wide — the formatter leaves it unaligned (`| --- |`), which is acceptable there
11
+ - Inside an HTML table write inline formatting as HTML (`<code>`, `<strong>`, `<a href>`): Markdown is not parsed there
@@ -13,8 +13,17 @@ paths:
13
13
  - Public entrypoints for use in other tools (like `lint-staged`, CLI, Webstorm, CI) & useful presets
14
14
  - Tasks to launch inner tasks (main `build` that launches `build` in each sub-package)
15
15
  - Inner `package.json` MUST only define atomic orchestrator-agnostic tasks
16
+ - Repo-wide defaults (parallelism, worker counts, cache and tool settings) live in env files (`.env`) or tool configs (`nx.json`, `turbo.json`, `vite.config.ts`), NEVER in `package.json` scripts — scripts stay as simple as possible; CI-specific behavior is set on the CI command (flags or env) where it is needed
16
17
  - Prefer NX for new projects
17
18
 
19
+ # Test Ownership
20
+
21
+ - The orchestrator (Nx / Turbo) runs every task, tests included, with its cache: the full run (`nx run-many -t test`, `turbo run test`) on `main`/`master` — unchanged packages are cache hits — and the affected run on PRs (`nx affected -t test`, `turbo run test --affected`)
22
+ - The test tool at the root (Vitest `test.projects`, Jest `projects`) is the local / IDE full-speed run: one worker pool over every package, all cores, no cache
23
+ - Inside an orchestrator task a test runner takes half of the cores, as the orchestrator runs several tasks at once (Nx: detect with `NX_TASK_TARGET_PROJECT`)
24
+ - Type checking (`vp check`, `tsc`) resolves workspace packages through their built declarations: CI lint jobs run after the build job (`needs: build`) and build the packages first through the orchestrator (cache hits), and so does a fresh clone before `lint`
25
+ - Suites that need running apps (e2e, integration): the orchestrator starts them — the test target `dependsOn` the continuous `start` / `dev` / `serve` plus a `wait` probe, `cache: false` — or Docker Compose does; the test tool never starts them (Playwright `webServer`), see playwright.md and testing.md
26
+
18
27
  # Task Consistency
19
28
 
20
29
  ALWAYS verify `turbo.json` or `nx.json` task definitions when modifying scripts or package structure:
package/rules/mui.md CHANGED
@@ -1,8 +1,6 @@
1
1
  ---
2
2
  type: always_apply
3
3
  description: Set of rules for projects with MUI
4
- paths:
5
- - '**/*.tsx'
6
4
  ---
7
5
 
8
6
  - Always import components or icons this way: `import { Paper, Button } from '@mui/material';` and `import { Xxx } from '@mui/icons-material';`
package/rules/npm-yarn.md CHANGED
@@ -6,9 +6,15 @@ description: NPM & Yarn patterns
6
6
  - Prefer using Corepack for all new projects.
7
7
  - Prefer Yarn v4+ for all new projects.
8
8
 
9
+ # Vite+
10
+
11
+ - IF `vite-plus` is installed, use `vp` commands: `vp check` (format + lint + type checks), `vp lint`, `vp fmt`, `vp test`, `vp pack` (libraries), `vp build` (apps), `vp staged`, `vp config` (git hooks)
12
+ - IF `vite-plus` is not installed, use the old style: package scripts with ESLint, Prettier, lint-staged, Husky
13
+ - Vite+ requires the `node-modules` linker (no Yarn PnP) and pins `vite` to its core and `vitest` to its bundled version at the root (see the `@kirill.konshin/lint` README)
14
+
9
15
  # Lifecycle Scripts: `prepare` vs `postinstall`
10
16
 
11
- - ⚠️ ALWAYS put install-time setup (husky, codegen, cache warmup) in the install lifecycle — `prepare` by default, `postinstall` for a private root (tradeoff below)
17
+ - ⚠️ ALWAYS put install-time setup (git hooks: `vp config` or `husky`, codegen, cache warmup) in the install lifecycle — `prepare` by default, `postinstall` for a private root (tradeoff below)
12
18
  - ⚠️ Yarn 2+ (Berry) skips top-level `prepare` on install ([lifecycle scripts](https://yarnpkg.com/advanced/lifecycle-scripts)) — run `yarn prepare` yourself / in CI. For a **private** root, prefer `postinstall`: Yarn does run it on install, so hooks land automatically (incl. CI) with no manual step and no [pinst](https://github.com/typicode/pinst) guard. Keep `prepare` for **published** packages — an unguarded `postinstall` would run on consumers' installs.
13
19
 
14
20
  # Prefer Libraries with Long History
@@ -94,6 +100,9 @@ approvedGitRepositories:
94
100
 
95
101
  compressionLevel: mixed
96
102
 
103
+ # print install-time script output (postinstall / prepare, dependency builds) live instead of buffering it into a log
104
+ enableInlineBuilds: true
105
+
97
106
  enableScripts: true
98
107
 
99
108
  nodeLinker: node-modules
package/rules/nx.md CHANGED
@@ -10,9 +10,11 @@ paths:
10
10
  # NX
11
11
 
12
12
  - If NX is used root `package.json` must have `nx show projects > /dev/null` in the `prepare`/`postinstall` script, so the project graph cache exists for tools that read it outside `nx` — e.g. `@nx/eslint-plugin` rules in a bare `eslint` run silently skip without it. With `prepare`, Yarn 2+ skips it on install — run `yarn prepare` explicitly (after cloning + as a CI step); with `postinstall` (private root) Yarn runs it on install, so no extra step
13
+ - With Nx Cloud (`nxCloudId` in `nx.json`) the remote cache replaces CI caching of `.nx/cache` — do NOT cache `.nx` in CI. Set Workspace visibility → Organization members only in the Nx Cloud workspace settings (no anonymous access; fork PRs run without the cache); developers run `npx nx login` once (personal read-write token in the home folder, no env var); CI passes `NX_CLOUD_ACCESS_TOKEN` from repository secrets (environment secrets reach only jobs that declare the environment): a read-write CI access token only on protected branches (`main`, release), a read-only CI access token everywhere else
14
+ - Without Nx Cloud: Nx 20+ indexes `.nx/cache` in a SQLite DB in `.nx/workspace-data`, named after the machine ID. A CI cache must carry both, with the DB under the fixed name `default-v*.db`: rename it to the machine ID before install and back before saving (see `github.md` / `gitlab.md`). One cache entry holds one DB, so restoring several entries does not merge their outputs.
13
15
  - NX Release (v23+) with conventional commits silently demotes bumps for `0.x` packages (breaking → minor, `feat` → patch) while the log still claims `Applied semver relative bump "minor"`;
14
16
  - set `release.version.adjustSemverBumpsForZeroMajorVersion: false` in `nx.json` if `feat:` must bump minor before `1.0.0`
15
- - Root NX task-script convention: bare name = `nx run-many -t <target>` over all projects (`build`/`test`/`start`/`serve`), with concurrency flags set once here;
17
+ - Root NX task-script convention: bare name = `nx run-many -t <target>` over all projects (`build`/`test`/`start`/`serve`), with NO `--parallel` flags: parallelism lives in the root `.env` (`NX_PARALLEL=50%` — Nx loads it before every command and parses percentages; `nx.json` `parallel` takes only a number, a string there dispatches nothing); continuous tasks (`start`) always all run, each in its own slot; test runners limit their own workers (Vitest `maxWorkers: '50%'`);
16
18
  - Add a NX scripts to root `package.json`:
17
19
  - `<target>:packages` scopes to publishable libs (`yarn <target> --projects '@scope/*'`);
18
20
  - `<target>:affected` = `nx affected -t <target>` for CI (exclude demos, diff vs `origin/main`)