@minimalstuff/tooling 0.5.0 → 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.
package/README.md CHANGED
@@ -1,158 +1,208 @@
1
+ # @minimalstuff/tooling
2
+
1
3
  ## Features
2
4
 
3
- - Shared presets for [OXC](https://oxc.rs/) tools (oxlint + oxfmt)
4
- - TypeScript configuration presets
5
+ - [OXC](https://oxc.rs/) presets: oxlint and oxfmt
6
+ - [Knip](https://knip.dev/) preset, with AdonisJS support
7
+ - EditorConfig preset
5
8
  - CLI for quick project setup
6
9
 
7
- ## Usage
10
+ ## Requirements
11
+
12
+ - Node >= 26
13
+ - `oxlint`, `oxfmt` and `oxlint-tsgolint` (optional peer dependencies, for the OXC presets)
14
+ - `knip` >= 6.42.1 (optional peer dependency, for the Knip preset)
8
15
 
9
16
  > [!IMPORTANT]
10
17
  > New/updated rules will not be considered as breaking changes. Only API changes will be considered as breaking changes.
11
18
 
12
- ### CLI installation
19
+ ## Setup
13
20
 
14
- Just run this command in your project root directory:
21
+ ### CLI
22
+
23
+ Run this command in your project root directory:
15
24
 
16
25
  ```bash
17
26
  pnpm dlx @minimalstuff/tooling@latest
18
27
  ```
19
28
 
29
+ The CLI lets you pick the tools to set up: EditorConfig, OXC, Knip and VSCode settings. For OXC and Knip, it lets you pick the presets (`react`, `adonisjs`, `vitest`) once, pre-selected from the dependencies it detects. Knip is pre-selected unless a knip config already exists. When `adonisjs` is kept, the generated `knip.ts` targets the root (`adonisjs: true`) or the workspaces (`apps/*`, `packages/*`) whose `package.json` has an `@adonisjs/*` dependency. It asks before overwriting an existing config file and only adds the `package.json` scripts that do not exist yet:
30
+
31
+ | Script | Command |
32
+ | -------------- | -------------------------------------------------- |
33
+ | `lint` | `oxlint` |
34
+ | `lint:fix` | `oxlint --fix` |
35
+ | `format` | `oxfmt && oxlint --fix` |
36
+ | `format:check` | `oxfmt --check` |
37
+ | `typecheck` | `tsc --noEmit` |
38
+ | `knip` | `knip` |
39
+ | `check` | `pnpm lint && pnpm format:check && pnpm typecheck` |
40
+
41
+ With Knip and OXC selected, `check` also runs `pnpm knip` at the end. Knip alone only adds the `knip` script.
42
+
20
43
  ### Manual install
21
44
 
22
45
  ```bash
23
- pnpm add -D oxlint oxfmt @minimalstuff/tooling
46
+ pnpm add -D oxlint oxfmt oxlint-tsgolint @minimalstuff/tooling
47
+ # optional, for the Knip preset
48
+ pnpm add -D knip
24
49
  ```
25
50
 
26
- ### OXC (oxlint + oxfmt)
27
-
28
- #### oxlint
51
+ ## oxlint
29
52
 
30
53
  ```ts
31
54
  // oxlint.config.ts
32
- import { defineConfig } from 'oxlint';
33
55
  import { minimalstuffPreset } from '@minimalstuff/tooling/oxc/lint';
34
56
 
35
- export default defineConfig({
36
- extends: [minimalstuffPreset()],
57
+ export default minimalstuffPreset({
58
+ react: true,
59
+ ignorePatterns: ['tmp/**'],
60
+ rules: {
61
+ 'no-console': 'warn',
62
+ },
37
63
  });
38
64
  ```
39
65
 
40
- Options:
66
+ `minimalstuffPreset` returns the root config. Any oxlint option (`rules`, `overrides`, `plugins`, `extends`, ...) can be passed next to the preset options:
41
67
 
42
- | Option | Type | Default | Description |
43
- | --------------- | --------- | ------- | --------------------------------------- |
44
- | `react` | `boolean` | `false` | Enable React-specific oxlint plugins |
45
- | `adonisjs` | `boolean` | `false` | Enable AdonisJS-specific rules |
46
- | `perfectionist` | `boolean` | `true` | Enable import sorting via perfectionist |
68
+ | Option | Type | Default | Enables |
69
+ | ---------- | --------- | ------- | --------------------------------------------------------------------------------------------------------- |
70
+ | `react` | `boolean` | `false` | `react` and `jsx-a11y` plugins, `react/rules-of-hooks` and `react/only-export-components` |
71
+ | `adonisjs` | `boolean` | `false` | `@adonisjs/eslint-plugin` lazy import rules, Lucid-aware `no-floating-promises`, AdonisJS ignore patterns |
72
+ | `vitest` | `boolean` | `false` | `vitest` plugin |
47
73
 
48
- ```ts
49
- import {
50
- ADONISJS_DEFAULT_IGNORE_PATTERNS,
51
- minimalstuffPreset,
52
- } from '@minimalstuff/tooling/oxc/lint';
74
+ With both `adonisjs` and `react`, the Inertia rules (`no-backend-import-in-frontend`, `prefer-adonisjs-inertia-link`, `prefer-adonisjs-inertia-form`) are enabled on `**/inertia/**/*.{ts,tsx}`.
53
75
 
54
- export default defineConfig({
55
- ignorePatterns: [...ADONISJS_DEFAULT_IGNORE_PATTERNS, 'tmp/**'],
56
- extends: [
57
- minimalstuffPreset({ react: true, adonisjs: true, perfectionist: true }),
58
- ],
59
- rules: {
60
- 'no-unused-vars': 'error',
61
- },
62
- });
63
- ```
76
+ The base preset enables the `typescript`, `unicorn` and `oxc` plugins, the `correctness` category as `error`, and type-aware linting with type checking (`typeAware`, `typeCheck`) with a set of strict `typescript/*` rules.
77
+
78
+ ### Merge semantics
79
+
80
+ - `rules`: yours override the preset's
81
+ - `overrides`: yours come after the preset's
82
+ - `plugins`, `jsPlugins`: yours are added to the preset's
83
+ - `extends`: yours come after the preset's
84
+ - `ignorePatterns`: the defaults are kept and yours are appended
85
+
86
+ ### Default ignore patterns
87
+
88
+ - Always: `**/node_modules/**`, `**/dist/**`, `**/build/**`, `**/routeTree.gen.ts`, `**/*.yml`, `**/*.yaml`
89
+ - With `adonisjs`: `**/.adonisjs/**`, `**/bin/*`, `**/database/schema.ts`
64
90
 
65
- #### oxfmt
91
+ ## oxfmt
66
92
 
67
93
  ```ts
68
94
  // oxfmt.config.ts
69
95
  import { minimalstuffPreset } from '@minimalstuff/tooling/oxc/fmt';
70
96
 
71
- export default minimalstuffPreset();
97
+ export default minimalstuffPreset({ printWidth: 100 });
72
98
  ```
73
99
 
74
- You can override any option:
100
+ Defaults: `printWidth: 80`, `tabWidth: 2`, `useTabs: true`, `semi: true`, `singleQuote: true`, `quoteProps: 'as-needed'`, `bracketSpacing: true`, `arrowParens: 'always'`, `trailingComma: 'es5'`, `htmlWhitespaceSensitivity: 'ignore'`.
101
+
102
+ Imports are sorted natively with `sortImports`, alphabetically, in three groups separated by a blank line: side effects, then `builtin` and `external`, then `@/` and `~/` internal imports and relative imports.
103
+
104
+ | Option | Type | Default | Description |
105
+ | ---------- | --------- | ------- | -------------------------------- |
106
+ | `adonisjs` | `boolean` | `false` | Add the AdonisJS ignore patterns |
107
+
108
+ Any other oxfmt option overrides the defaults. `ignorePatterns` are appended to the defaults (the oxlint ones plus `**/CHANGELOG.md`), never replaced.
109
+
110
+ ## knip
75
111
 
76
112
  ```ts
77
- export default minimalstuffPreset({ printWidth: 120, semi: true });
113
+ // knip.ts
114
+ import { minimalstuffPreset } from '@minimalstuff/tooling/knip';
115
+
116
+ export default minimalstuffPreset({ adonisjs: true });
78
117
  ```
79
118
 
80
- For Adonis projects, you can extend ignore patterns:
119
+ Monorepo, with the AdonisJS app(s) in workspaces:
81
120
 
82
121
  ```ts
83
- import {
84
- ADONISJS_DEFAULT_IGNORE_PATTERNS,
85
- minimalstuffPreset,
86
- OXFMT_DEFAULT_IGNORE_PATTERNS,
87
- } from '@minimalstuff/tooling/oxc/fmt';
88
-
89
- export default minimalstuffPreset({
90
- ignorePatterns: [
91
- ...OXFMT_DEFAULT_IGNORE_PATTERNS,
92
- ...ADONISJS_DEFAULT_IGNORE_PATTERNS,
93
- ],
94
- });
122
+ export default minimalstuffPreset({ adonisjs: ['apps/webapp'] });
95
123
  ```
96
124
 
97
- Defaults: `printWidth: 100`, `semi: false`, `singleQuote: true`, `trailingComma: 'all'`, `arrowParens: 'avoid'`.
125
+ `minimalstuffPreset` returns the root config. Any knip option (`entry`, `project`, `ignore`, `ignoreDependencies`, `workspaces`, ...) can be passed next to the preset option. Without `adonisjs`, it returns your config as is: knip's built-in plugins (vite, vitest, playwright, tsdown, oxlint, ...) already cover most setups.
98
126
 
99
- #### Scripts
127
+ | Option | Type | Default | Description |
128
+ | ---------- | ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
129
+ | `adonisjs` | `boolean \| readonly string[]` | `false` | `true` applies the AdonisJS config to the root workspace. A list of paths applies it to each of those workspaces (under `workspaces[path]`, monorepo case) |
100
130
 
101
- ```json
102
- {
103
- "scripts": {
104
- "lint": "oxlint",
105
- "lint:fix": "oxlint --fix",
106
- "format": "oxfmt --write ."
107
- }
108
- }
109
- ```
131
+ Knip has no AdonisJS or Japa plugin, so everything Adonis loads by convention would be reported as unused. The AdonisJS config declares:
132
+
133
+ - `entry`: `adonisrc.ts`, `ace.js`, `bin/*.ts`, `start/**`, `config/**`, `providers/**`, `commands/**`, `database/{migrations,seeders,factories}/**`, `tests/bootstrap.ts`, Japa specs (`tests/**/*.spec.{ts,js}`, `app/**/*.spec.{ts,js}`), and the Inertia files (`inertia/{app,ssr}.{ts,tsx}`, `inertia/app/{app,ssr}.{ts,tsx}`, `inertia/pages/**/*.{ts,tsx}`, pages are resolved by name at runtime)
134
+ - `project`: `**/*.{ts,tsx,js}`
135
+ - `ignore`: `.adonisjs/**` (generated), `database/schema.ts` (generated by Lucid)
136
+ - `ignoreDependencies`: `pg`, `mysql2`, `better-sqlite3`, `sqlite3` (database drivers only referenced by name in `config/database.ts`), `pino-pretty` (logger transport referenced by name), `hot-hook` (only referenced in `package.json`)
137
+
138
+ ### Merge semantics
110
139
 
111
- ### Tsconfig
140
+ For the targeted workspace(s):
112
141
 
113
- Node (ESM):
142
+ - arrays (`entry`, `project`, `ignore`, `ignoreDependencies`, ...): yours are appended to the preset's (a single string is accepted)
143
+ - other keys (booleans, objects such as plugin configs): yours win
114
144
 
115
- ```json
116
- {
117
- "extends": "@minimalstuff/tooling/tsconfigs/tsconfig.node",
118
- "compilerOptions": {
119
- "rootDir": "./",
120
- "outDir": "./build"
121
- }
122
- }
145
+ With `adonisjs: true`, the preset is merged into the root keys. If you define `workspaces['.']` yourself, knip ignores the root keys: use `adonisjs: ['.']` instead. With a list of paths, the root keys are left untouched and each listed workspace gets the preset merged with its own `workspaces[path]` entry.
146
+
147
+ ## Migrating from 0.6
148
+
149
+ In 0.x a minor bump is breaking, so `^0.6.0` never resolves to 0.7: upgrade explicitly.
150
+
151
+ ```bash
152
+ pnpm add -D @minimalstuff/tooling@^0.7.0 oxlint@latest oxfmt@latest oxlint-tsgolint@latest
123
153
  ```
124
154
 
125
- Node Next (ESM + `ts` extensions):
155
+ Requirements changed:
156
+
157
+ - Node >= 26.
158
+ - Peers: `oxlint >= 1.89.0`, `oxfmt >= 0.74.0`, `oxlint-tsgolint >= 7.0.2004`.
159
+
160
+ oxlint: the preset now returns the root config instead of being passed to `extends`.
161
+
162
+ ```ts
163
+ // before
164
+ export default defineConfig({
165
+ ignorePatterns: [...ADONISJS_DEFAULT_IGNORE_PATTERNS, 'tmp/**'],
166
+ extends: [minimalstuffPreset({ react: true, adonisjs: true })],
167
+ rules: { 'no-console': 'warn' },
168
+ });
126
169
 
127
- ```json
128
- {
129
- "extends": "@minimalstuff/tooling/tsconfigs/tsconfig.node-next",
130
- "compilerOptions": {
131
- "rootDir": "./",
132
- "outDir": "./build"
133
- }
134
- }
170
+ // after
171
+ export default minimalstuffPreset({
172
+ react: true,
173
+ adonisjs: true,
174
+ ignorePatterns: ['tmp/**'],
175
+ rules: { 'no-console': 'warn' },
176
+ });
135
177
  ```
136
178
 
137
- React (TSX, bundler resolution):
179
+ oxfmt: `OXFMT_DEFAULT_IGNORE_PATTERNS` and `ADONISJS_DEFAULT_IGNORE_PATTERNS` are no longer exported.
138
180
 
139
- ```json
140
- {
141
- "extends": "@minimalstuff/tooling/tsconfigs/tsconfig.react",
142
- "compilerOptions": {
143
- "rootDir": "./",
144
- "outDir": "./build"
145
- }
146
- }
181
+ ```ts
182
+ // before
183
+ export default minimalstuffPreset({
184
+ ignorePatterns: [
185
+ ...OXFMT_DEFAULT_IGNORE_PATTERNS,
186
+ ...ADONISJS_DEFAULT_IGNORE_PATTERNS,
187
+ ],
188
+ });
189
+
190
+ // after
191
+ export default minimalstuffPreset({ adonisjs: true });
147
192
  ```
148
193
 
149
- ### Prerequisites
194
+ Other changes:
195
+
196
+ - The `perfectionist` option is removed. Imports are now sorted alphabetically by oxfmt: run `pnpm format` once.
197
+ - Remove the ignore patterns that are now defaults from your configs.
198
+ - The `eslint-plugin-perfectionist` dependency is no longer needed.
199
+ - Correctness rules are now errors and new type-aware rules are enabled (see [oxlint](#oxlint)): `pnpm lint` may fail where it passed before.
200
+ - The CLI only adds missing scripts, so update existing ones by hand: drop `--fix-dangerously` from `lint:fix` and replace `format: "pnpm lint:fix; oxfmt ."` with `format: "oxfmt && oxlint --fix"` (see [CLI](#cli)).
201
+ - Optional: add Knip (see [knip](#knip)).
150
202
 
151
- 1. **NPM token**
152
- Create an automation token at [npmjs.com/access-tokens](https://www.npmjs.com/access-tokens) (scope: package publish for `@minimalstuff/ui`).
203
+ ## Publishing
153
204
 
154
- 2. **Repository secret**
155
- In the repo: **Settings → Secrets and variables → Actions**. Add a secret named `NPM_TOKEN` with the token value.
205
+ Publishing uses npm [trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC), no token needed. On npmjs.com, `@minimalstuff/tooling` > **Settings > Trusted publishing** must list GitHub Actions with organization `minimalstuff`, repository `tooling` and workflow `publish.yml`. Publishing a GitHub release triggers the workflow.
156
206
 
157
207
  ---
158
208
 
@@ -1,8 +1 @@
1
- //#region src/cli/index.d.ts
2
- type ConfigTool = 'editorconfig' | 'oxc';
3
- declare const DEFAULT_SELECTED_TOOLS: ConfigTool[];
4
- interface PromptResult {
5
- tools: ConfigTool[];
6
- }
7
- //#endregion
8
- export { ConfigTool, DEFAULT_SELECTED_TOOLS, PromptResult };
1
+ export {}