@kirill.konshin/lint 0.8.4 → 0.8.6
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
|
@@ -216,7 +216,7 @@ What maps where:
|
|
|
216
216
|
</tbody>
|
|
217
217
|
</table>
|
|
218
218
|
|
|
219
|
-
Not carried over: `@nx/dependency-checks` (Oxlint does not lint JSON), `@typescript-eslint/naming-convention` (type-aware only, off by default). `@nx/eslint-plugin`
|
|
219
|
+
Not carried over: `@nx/dependency-checks` (Oxlint does not lint JSON), `@typescript-eslint/naming-convention` (type-aware only, off by default). `@nx/eslint-plugin` and the Tailwind plugin need the `eslint` package installed (as a library; ESLint itself does not run; Tailwind: a known gap, see [Issues](#issues)). Oxlint type-aware linting and type checking (tsgolint, the TypeScript 7 engine) are on by default — `vp check` is the type check, `vp pack` does not type-check; `vitePlus: { typeAware: false }` turns them off. tsgolint rejects tsconfig options TypeScript 7 removed (`target: es5`, `moduleResolution: node`, `downlevelIteration`).
|
|
220
220
|
|
|
221
221
|
`package.json`:
|
|
222
222
|
|
|
@@ -675,7 +675,7 @@ Due to limitations package visibility between leaf and root this package has to
|
|
|
675
675
|
|
|
676
676
|
¹ 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.
|
|
677
677
|
|
|
678
|
-
`vitePlusConfig` runs the same gates (`src/gates.ts`, shared with the ESLint blocks), with three differences: Oxlint JS plugins load from this package, so only `storybook` (its plugin imports `storybook`) and `
|
|
678
|
+
`vitePlusConfig` runs the same gates (`src/gates.ts`, shared with the ESLint blocks), with three differences: Oxlint JS plugins load from this package, so only `storybook` (its plugin imports `storybook`), `nx` (needs `eslint`) and `tailwind` (needs `eslint`, a known gap, see [Issues](#issues), besides `tailwindcss`) demand a resolvable package; `vitest` is ON unless set to `false` (Vite+ bundles it); `next` needs no package (Oxlint's `nextjs` plugin is native). `typeAware` differs by backend: `eslint.typeAware` is OFF by default (slow), `vitePlus.typeAware` ON.
|
|
679
679
|
|
|
680
680
|
The machinery is controlled by the `detection` key of `lint.config.ts` (same toggle notation as the tools):
|
|
681
681
|
|
|
@@ -712,6 +712,8 @@ paths:
|
|
|
712
712
|
- [ ] pnpm — root detection via `@manypkg/find-root` (`pnpm-workspace.yaml`); `public-hoist-pattern` guidance unverified in a real pnpm workspace
|
|
713
713
|
- [ ] npm — env fast-path (`npm_config_local_prefix`) verified previously; `@manypkg/find-root` fallback unverified since the switch
|
|
714
714
|
- [x] Yarn [constraints](https://yarnpkg.com/features/constraints) helper enforces root overrides/resolutions or default dependency consistency
|
|
715
|
+
- Vite+
|
|
716
|
+
- [ ] `eslint-plugin-tailwindcss` as an Oxlint JS plugin needs the `eslint` package (a required peer, loaded through `@typescript-eslint/utils`): without it `vp check` stops before linting with `Cannot find module 'eslint'`. Workaround until fixed: `eslint` in the root `devDependencies`, as a library only (the `lint-tailwind` skill)
|
|
715
717
|
- ESLint 9
|
|
716
718
|
- [x] https://github.com/microsoft/rushstack/issues/4635 Failed to patch ESLint because the calling module was not recognized
|
|
717
719
|
- [x] https://github.com/microsoft/rushstack/issues/4965 Failed to patch ESLint because the calling module was not recognized
|
package/package.json
CHANGED
package/rules/typescript.md
CHANGED
|
@@ -92,6 +92,8 @@ paths:
|
|
|
92
92
|
- `exports` conditions must be FLAT and `types`-first (`{types, import, default}`) — a nested or `import`-only map matches NO condition outside `import`, so CJS resolvers get `ERR_PACKAGE_PATH_NOT_EXPORTED` (the entry is invisible, not merely interop-incompatible); `default` is the catch-all, not a CJS build, and Node >= 22.12 loads the ESM behind it through `require()`
|
|
93
93
|
- Next.js transpiles `next.config.ts` to CommonJS and `require()`s it, so config-only helpers MUST be reachable this way — keep them in their own subpath that imports nothing at runtime
|
|
94
94
|
- Every subpath export needs its OWN bundler entry — a pure re-export barrel that is merely reachable from the main entry gets inlined, and its `dist/<mod>/index.js` is never written
|
|
95
|
+
- Emit declarations with the tsdown `dts` option of `vp pack`; do not add `unplugin-dts` or `vite-plugin-dts` — tsdown already falls back to the TypeScript compiler (`dts.generator: 'tsc'`) when a package cannot use `isolatedDeclarations`
|
|
96
|
+
- Exception: `unplugin-dts` for a package that must build with `vite build` library mode and cannot move to `vp pack`
|
|
95
97
|
- NEVER import an OPTIONAL peerDependency at runtime, not even for a single constant — inline it (annotate with `typeof` of a type-only import as a drift guard); a barrel re-exporting such a module makes the WHOLE entry unresolvable when the peer is absent
|
|
96
98
|
|
|
97
99
|
# Type Annotation Patterns
|
|
@@ -34,7 +34,7 @@ All settings move into one `lint.config.ts` in the workspace root (README "`lint
|
|
|
34
34
|
- **Prerequisites**: Node `^22.18 || ^24.11 || >=26`, Vite 8+, Vitest 4.1+, `node-modules` linker
|
|
35
35
|
- **Set up** Vite+ by hand per the README "Vite+" section — not `vp migrate`: it copies every expanded ESLint rule, writes absolute paths and broken regexes, and rewrites dependencies; if it was run, replace its `lint` / `fmt` blocks with `vitePlusConfig`
|
|
36
36
|
- **Carry over**: rules from `eslint.config.*` → `lint.rules` / `lint.overrides` (`@typescript-eslint/x` → `typescript/x`, `react-hooks/x` → `react/x`, `import-x/x` → `import/x`, `@nx/*` unchanged); extra `.prettierignore` entries → `fmt.ignorePatterns`; root `vitest.config.*` → the `test` block
|
|
37
|
-
- **Remove**: `eslint.config.*`, `.prettierrc*`, `.prettierignore`, `.lintstagedrc*`, `vitest.config.*`, `tsdown.config.*` (→ `pack`), `.husky/` (→ `.vite-hooks/`; `git config --unset core.hooksPath`); dependencies `prettier`, `lint-staged`, `husky`, `vitest`, `tsdown`, `vite-plugin-dts`, `rollup-preserve-directives` — keep `eslint`
|
|
37
|
+
- **Remove**: `eslint.config.*`, `.prettierrc*`, `.prettierignore`, `.lintstagedrc*`, `vitest.config.*`, `tsdown.config.*` (→ `pack`), `.husky/` (→ `.vite-hooks/`; `git config --unset core.hooksPath`); dependencies `prettier`, `lint-staged`, `husky`, `vitest`, `tsdown`, `vite-plugin-dts`, `rollup-preserve-directives` — keep `eslint` for `@nx/eslint-plugin` and for Tailwind (a known gap, the `lint-tailwind` skill)
|
|
38
38
|
- **Rewrite**: `from 'vitest'` → `from 'vite-plus/test'` (keep `declare module 'vitest'`); `defineConfig` from `vite-plus`; library `vite build` with `preserveModules` → `pack` with `unbundle: true`, `dts: true`, `deps: { neverBundle: true }`; inline disables of file-name rules → `lint.overrides`
|
|
39
39
|
- **Expect**: a one-time Oxfmt reformat (commit as `style:` / `chore:`); type errors the old setup never reported (`typeAware` is on), TS 7-removed tsconfig options (`target: es5`, `moduleResolution: node`, `downlevelIteration`) and TS 6's empty default `types` (list `["node", "vite-plus/client"]`); new Oxlint findings are real — fix, or override with a reason; `@nx/dependency-checks` is gone (Oxlint lints no JSON)
|
|
40
40
|
- **Verify**: every package's build and tests; `dist` file lists and `package.json` `exports` unchanged
|
|
@@ -1,10 +1,24 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: lint-nextjs
|
|
3
|
-
description: Our Next.js App Router conventions on top of the vendor Next.js skills - typed `LayoutProps` / `PageProps`, auth-guarded layouts, `params` / `searchParams` in server and client pages, page and component file placement, where `next.config.ts` details are. Use when writing or reviewing Next.js pages, layouts, route handlers or `next.config.ts`.
|
|
3
|
+
description: Our Next.js App Router conventions on top of the vendor Next.js skills - `next typegen` in `postinstall`, typed `LayoutProps` / `PageProps`, auth-guarded layouts, `params` / `searchParams` in server and client pages, page and component file placement, where `next.config.ts` details are. Use when writing or reviewing Next.js pages, layouts, route handlers or `next.config.ts`.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
The binding rules are in [rules/nextjs.md](../../rules/nextjs.md). Next.js API knowledge: the docs that `next` bundles (`node_modules/next/dist/docs/`), the `next-*` skills and the `vercel-react-best-practices` skill; MUI setup: the `material-ui-nextjs` skill.
|
|
7
7
|
|
|
8
|
+
# Route types in `postinstall`
|
|
9
|
+
|
|
10
|
+
`LayoutProps`, `PageProps` and `RouteContext` are global types that Next.js generates into `.next/types`, referenced from `next-env.d.ts` (both gitignored). `next dev` and `next build` write them, so a fresh clone or a CI type check (`vp check`) fails without them. Every Next.js app runs `next typegen` in `postinstall`:
|
|
11
|
+
|
|
12
|
+
```jsonc
|
|
13
|
+
{
|
|
14
|
+
"scripts": {
|
|
15
|
+
"postinstall": "lint-prepare init && vp config && next typegen",
|
|
16
|
+
},
|
|
17
|
+
}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
- Monorepo: `next typegen` goes into the `postinstall` of each Next.js app package, not the root
|
|
21
|
+
|
|
8
22
|
# Layouts
|
|
9
23
|
|
|
10
24
|
Always use https://nextjs.org/docs/app/api-reference/file-conventions/layout#layout-props-helper:
|
|
@@ -24,7 +24,7 @@ Do not use Yarn PnP ([rules/npm-yarn.md](../../rules/npm-yarn.md)). IF the proje
|
|
|
24
24
|
|
|
25
25
|
Write the config by hand. `vp migrate` is only an optional first pass: it copies every expanded ESLint rule, absolute paths and broken regexes into `vite.config.ts`, so clean up after it as the `lint-migrate` skill describes.
|
|
26
26
|
|
|
27
|
-
1. **Install** — add `vite-plus`, `@kirill.konshin/lint` (+ `eslint`
|
|
27
|
+
1. **Install** — add `vite-plus`, `@kirill.konshin/lint` (+ `eslint` for Nx module-boundary rules and for Tailwind, a known gap: the `lint-tailwind` skill); pin `vite`/`vitest` at the root (README "Yarn constraints").
|
|
28
28
|
2. **Config** — `lint.config.ts` in the workspace root, always (README "`lint.config.ts`"; `"type": "module"` in the root `package.json`): tool toggles, `skills`, `rules`, and under `vitePlus` the `typeAware` setting and the project blocks — rule overrides in `lint.rules` / `lint.overrides`, ignores in `lint.ignorePatterns`, `test`, `fmt`. Root `vite.config.ts` is exactly `export default defineConfig(vitePlusConfig());`. Keep `.editorconfig`.
|
|
29
29
|
3. **Hooks** — `lint-prepare init && vp config` in `prepare`/`postinstall` — in this order: `vp config` fills the Vite+ section `lint-prepare` writes into `AGENTS.md` (same choice as below), `.vite-hooks/pre-commit` with `vp staged`; scripts `lint: vp check --fix`, `lint:staged: vp staged`; workspace-wide scripts move from `yarn workspaces foreach` to `vp run -r` ([rules/npm-yarn.md](../../rules/npm-yarn.md)).
|
|
30
30
|
4. **Tests/builds** — tests import from `vite-plus/test`; libraries `vp pack`, apps `vp build`.
|
|
@@ -32,6 +32,7 @@ The binding rules are in [rules/tailwind.md](../../rules/tailwind.md). This skil
|
|
|
32
32
|
# ESLint (eslint-plugin-tailwindcss, bundled with @kirill.konshin/lint)
|
|
33
33
|
|
|
34
34
|
- With Vite+ the same plugin runs as an Oxlint JS plugin with the same detection; both read `tailwind` from `lint.config.ts`
|
|
35
|
+
- Known gap: the plugin needs the `eslint` package (a required peer, loaded through `@typescript-eslint/utils`) also with Vite+, where ESLint does not run; without it `vp check` stops before linting with `Failed to load JS plugin … Cannot find module 'eslint'`. Temporary workaround: add `eslint` to the root `devDependencies`, as a library only (no `eslint.config.*`)
|
|
35
36
|
- The plugin MUST be able to resolve the Tailwind entry CSS or it hard-crashes lint (ENOENT)
|
|
36
37
|
- 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
|
|
37
38
|
- Rules auto-scope to the workspace package owning the entry CSS (block `basePath`); pass `tailwind: { scoped: false }` to lint the whole workspace
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: lint-vercel
|
|
3
|
-
description: Vercel project setup - the Vercel CLI as a dev dependency, the committed repository link (`.vercel/repo.json`) so every clone is linked without `vercel link`, what stays out of git in `.vercel
|
|
3
|
+
description: Vercel project setup - the Vercel CLI as a dev dependency, the committed repository link (`.vercel/repo.json`) so every clone is linked without `vercel link`, what stays out of git in `.vercel/`, the Yarn install command for projects whose root package is ESM. Use when adding Vercel to a project, running `vercel link`, editing `vercel.json`, editing the `.vercel` lines of `.gitignore`, or when a Vercel install fails with Yarn / Corepack.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Platform operations (deploy, env vars, domains, logs): the `vercel-cli` skill.
|
|
@@ -28,3 +28,18 @@ Everything else in `.vercel/` is local and stays out of git: env files of `verce
|
|
|
28
28
|
- `.vercel/*`, not `.vercel`: git cannot re-include a file inside an ignored directory
|
|
29
29
|
- `vercel link` appends a `.vercel` line to `.gitignore` when that exact line is missing, which silently drops the exception: after every `vercel link`, remove the appended `.vercel` line
|
|
30
30
|
- Check: `git check-ignore -q .vercel/repo.json` exits 1 (not ignored), `git status -uall` shows `.vercel/repo.json` and nothing else from `.vercel/`
|
|
31
|
+
|
|
32
|
+
# Install with Yarn
|
|
33
|
+
|
|
34
|
+
The root `package.json` has `"type": "module"` (`@kirill.konshin/lint` requires it). With `ENABLE_EXPERIMENTAL_COREPACK=1`, Vercel downloads Yarn into `.vercel/cache/corepack/`, inside the repository, so Node loads Yarn's CommonJS bundle as ESM and `yarn install` crashes with `Dynamic require of "util" is not supported`. Set the install command in `vercel.json` instead:
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"installCommand": "npm i -g corepack@latest && corepack enable && yarn install --immutable"
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
- Remove the `ENABLE_EXPERIMENTAL_COREPACK` env var from the Vercel project
|
|
43
|
+
- Yarn's files then live outside the repository, as on GitLab (the `lint-gitlab` skill), and `"type": "module"` stays
|
|
44
|
+
- Not tested on Vercel yet: global npm installs normally work there; confirm on the first deploy
|
|
45
|
+
- Do not remove `"type": "module"` from the root `package.json`, the workaround Vercel staff suggest: it works, but `@kirill.konshin/lint` requires the field and Node warns on every load of `lint.config.ts`
|