adamantite 0.45.0 → 0.47.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 +447 -127
- package/dist/index.js +628 -57
- package/dist/oxlint.js +1 -0
- package/dist/presets/analyze.js +1 -0
- package/dist/presets/lint/{react-doctor.d.ts → architecture.d.ts} +1 -1
- package/dist/presets/lint/architecture.js +8 -0
- package/dist/presets/lint/core.js +1 -2
- package/dist/presets/lint/effect.js +26 -1
- package/dist/presets/lint/plugin/glob.d.ts +7 -0
- package/dist/presets/lint/plugin/glob.js +48 -0
- package/dist/presets/lint/plugin/imports.d.ts +4 -0
- package/dist/presets/lint/plugin/imports.js +4 -1
- package/dist/presets/lint/plugin/index.d.ts +3 -0
- package/dist/presets/lint/plugin/index.js +14 -8
- package/dist/presets/lint/plugin/options.d.ts +5 -5
- package/dist/presets/lint/plugin/options.js +19 -7
- package/dist/presets/lint/plugin/resolver.d.ts +8 -0
- package/dist/presets/lint/plugin/resolver.js +79 -0
- package/dist/presets/lint/plugin/rules/import-owners.d.ts +67 -0
- package/dist/presets/lint/plugin/rules/import-owners.js +310 -0
- package/dist/presets/lint/plugin/rules/layers.d.ts +136 -0
- package/dist/presets/lint/plugin/rules/layers.js +479 -0
- package/dist/presets/lint/plugin/rules/no-query-data-in-state.js +1 -1
- package/dist/presets/lint/plugin/rules/no-react-state-hooks.d.ts +0 -5
- package/dist/presets/lint/plugin/rules/no-react-state-hooks.js +3 -47
- package/dist/presets/lint/plugin/rules/query-from-loader.js +2 -2
- package/dist/presets/lint/plugin/rules/require-suppression-reason.d.ts +5 -0
- package/dist/presets/lint/plugin/rules/require-suppression-reason.js +32 -0
- package/dist/presets/lint/react-strict.js +22 -2
- package/dist/presets/lint/strict.js +35 -2
- package/dist/presets/lint/{antislop.d.ts → tailwind.d.ts} +1 -1
- package/dist/presets/lint/{shadcn.js → tailwind.js} +1 -1
- package/dist/presets/lint/vendor/antislop/license.md +26 -1
- package/dist/presets/lint/vendor/antislop/plugin.d.mts +3 -0
- package/dist/presets/lint/vendor/antislop/plugin.mjs +959 -33
- package/dist/presets/lint/vendor/antislop-effect/license.md +27 -0
- package/dist/presets/lint/vendor/antislop-effect/plugin.d.mts +17 -0
- package/dist/presets/lint/vendor/antislop-effect/plugin.mjs +579 -0
- package/dist/presets/{lint → rules}/custom.d.ts +3 -20
- package/dist/presets/{lint → rules}/custom.js +50 -46
- package/dist/presets/rules/folder.d.ts +34 -0
- package/dist/presets/rules/folder.js +52 -0
- package/dist/presets/rules/index.d.ts +2 -9
- package/dist/presets/rules/index.js +1 -29
- package/dist/presets/rules/load.d.ts +8 -0
- package/dist/presets/rules/load.js +29 -0
- package/dist/presets/rules/plugin.d.ts +3 -0
- package/dist/presets/rules/plugin.js +1 -0
- package/dist/presets/rules/testing.d.ts +2 -0
- package/dist/presets/rules/testing.js +14 -0
- package/dist/presets/tsconfig.json +3 -0
- package/dist/presets/typescript/resets/array-includes.d.ts +15 -0
- package/dist/presets/typescript/resets/array-index-of.d.ts +23 -0
- package/dist/presets/typescript/resets/eval.d.ts +1 -0
- package/dist/presets/typescript/resets/fetch.d.ts +3 -0
- package/dist/presets/typescript/resets/filter-boolean.d.ts +24 -0
- package/dist/presets/typescript/resets/helpers.d.ts +15 -0
- package/dist/presets/typescript/resets/index.d.ts +20 -0
- package/dist/presets/typescript/resets/is-array.d.ts +3 -0
- package/dist/presets/typescript/resets/json-parse.d.ts +14 -0
- package/dist/presets/typescript/resets/license.md +12 -0
- package/dist/presets/typescript/resets/map-constructor.d.ts +3 -0
- package/dist/presets/typescript/resets/map-groupby.d.ts +3 -0
- package/dist/presets/typescript/resets/map-has.d.ts +9 -0
- package/dist/presets/typescript/resets/object-assign.d.ts +8 -0
- package/dist/presets/typescript/resets/object-get-prototype-of.d.ts +3 -0
- package/dist/presets/typescript/resets/object-groupby.d.ts +6 -0
- package/dist/presets/typescript/resets/object-values.d.ts +8 -0
- package/dist/presets/typescript/resets/reflect.d.ts +12 -0
- package/dist/presets/typescript/resets/set-has.d.ts +9 -0
- package/dist/presets/typescript/resets/storage.d.ts +3 -0
- package/dist/presets/typescript.json +13 -0
- package/dist/runtime-CVZPDpfE.js +11 -0
- package/package.json +81 -19
- package/skills/adamantite/SKILL.md +110 -207
- package/skills/adamantite/references/custom-rules.md +120 -0
- package/skills/adamantite/references/lint-rules.md +152 -0
- package/skills/adamantite/references/setup.md +70 -0
- package/dist/presets/lint/antislop.js +0 -28
- package/dist/presets/lint/react-doctor.js +0 -20
- package/dist/presets/lint/shadcn.d.ts +0 -5
package/README.md
CHANGED
|
@@ -34,11 +34,14 @@ and Sherif so humans and coding agents can use the same project workflow.
|
|
|
34
34
|
through an interactive or non-interactive initializer.
|
|
35
35
|
- **Setup maintenance**: Assess managed integrations with `doctor`, update managed
|
|
36
36
|
dependencies, and give humans or agents repair instructions.
|
|
37
|
-
- **Custom rules**: Write project-specific Oxlint rules in `.adamantite/
|
|
37
|
+
- **Custom rules**: Write project-specific Oxlint rules in `.adamantite/lint/`, one rule
|
|
38
38
|
for each file, and enable all of them with one line.
|
|
39
|
+
- **Hardening**: Have a coding agent turn the coding standards that your code already
|
|
40
|
+
follows into custom rules, and into instructions for the ones that no rule can check.
|
|
39
41
|
- **Workspace checks**: Find unused code with Knip and dependency inconsistencies with
|
|
40
42
|
Sherif.
|
|
41
|
-
- **Agent guidance**: Add a managed Adamantite section to `AGENTS.md
|
|
43
|
+
- **Agent guidance**: Add a managed Adamantite section to `AGENTS.md`, and add the
|
|
44
|
+
Adamantite skill for your coding agents.
|
|
42
45
|
|
|
43
46
|
## Quick start
|
|
44
47
|
|
|
@@ -49,7 +52,7 @@ npx adamantite init
|
|
|
49
52
|
```
|
|
50
53
|
|
|
51
54
|
The interactive setup lets you choose package scripts, presets, TypeScript, editors, CI,
|
|
52
|
-
and agent
|
|
55
|
+
and coding agent setup with the [Adamantite skill](#agent-skill). After setup, use the scripts written to `package.json`:
|
|
53
56
|
|
|
54
57
|
```sh
|
|
55
58
|
bun run check
|
|
@@ -69,7 +72,7 @@ adamantite analyze
|
|
|
69
72
|
## Non-interactive setup
|
|
70
73
|
|
|
71
74
|
Use `--non-interactive` to configure a project entirely from flags. Specify at least one
|
|
72
|
-
`--script`. Repeat `--script`, `--preset`, and `--editor` to select multiple values.
|
|
75
|
+
`--script` or `--typescript`. Repeat `--script`, `--preset`, and `--editor` to select multiple values.
|
|
73
76
|
|
|
74
77
|
```sh
|
|
75
78
|
npx adamantite init \
|
|
@@ -79,7 +82,7 @@ npx adamantite init \
|
|
|
79
82
|
--script analyze \
|
|
80
83
|
--preset react \
|
|
81
84
|
--editor vscode \
|
|
82
|
-
--typescript \
|
|
85
|
+
--typescript typescript \
|
|
83
86
|
--install-extensions \
|
|
84
87
|
--github-actions \
|
|
85
88
|
--agents
|
|
@@ -89,14 +92,24 @@ Available setup values:
|
|
|
89
92
|
|
|
90
93
|
- Scripts: `check`, `fix`, and `analyze`. In a detected monorepo, `analyze` also installs
|
|
91
94
|
Sherif.
|
|
92
|
-
- Presets: `react`, `react-strict`, `
|
|
93
|
-
`jest`, `vitest`, `node`, `
|
|
95
|
+
- Presets: `react`, `react-strict`, `tanstack`, `nextjs`, `vue`, `effect`,
|
|
96
|
+
`jest`, `vitest`, `node`, `architecture`, `strict`, and `tailwind`. `react-strict` requires `react`.
|
|
94
97
|
- Editors: `vscode` and `zed`.
|
|
98
|
+
- TypeScript presets: `typescript` and `tsconfig`. See [the TypeScript presets](#the-typescript-presets).
|
|
95
99
|
|
|
96
|
-
Presets
|
|
100
|
+
Presets require the `check` or `fix` script. Editor extension installation
|
|
97
101
|
requires an editor. GitHub Actions requires a compatible script and a supported package
|
|
98
102
|
manager. Omitted boolean flags are disabled.
|
|
99
103
|
|
|
104
|
+
The GitHub Actions workflow runs the `check` and `analyze` scripts that you select.
|
|
105
|
+
Its job sits between `# ADAMANTITE:START` and `# ADAMANTITE:END` comments. Adamantite owns
|
|
106
|
+
the jobs between these comments, and you own the rest of the workflow. You can rename the
|
|
107
|
+
file in `.github/workflows` and add your own jobs outside the comments. Doctor checks only the
|
|
108
|
+
jobs between the comments, and init updates them when you did not change them.
|
|
109
|
+
Agents verify custom rules with temporary cases while they work. CI runs the rules through
|
|
110
|
+
`check` by default. Users can add an explicit `adamantite rule test` step for optional saved tests.
|
|
111
|
+
Init preserves a workflow with an explicit rule-test command, including its setup and other settings.
|
|
112
|
+
|
|
100
113
|
Existing package scripts whose commands differ from Adamantite's are kept and reported
|
|
101
114
|
instead of being replaced. The interactive initializer asks before overwriting them; in
|
|
102
115
|
non-interactive mode, pass `--overwrite-scripts` to replace them. To keep custom flags,
|
|
@@ -105,8 +118,8 @@ forward them to the Adamantite command after `--`, e.g.
|
|
|
105
118
|
|
|
106
119
|
In a detected monorepo, TypeScript setup does not write a root `tsconfig.json`, because a
|
|
107
120
|
catch-all root config makes TypeScript treat all packages as one project. Adamantite
|
|
108
|
-
prints guidance instead: add `"extends": "adamantite/typescript"
|
|
109
|
-
`tsconfig.json` or to a shared base config.
|
|
121
|
+
prints guidance instead: add `"extends": "adamantite/typescript"`, or `"extends": "adamantite/tsconfig"`
|
|
122
|
+
in a library, to each package's `tsconfig.json` or to a shared base config.
|
|
110
123
|
|
|
111
124
|
## Commands
|
|
112
125
|
|
|
@@ -121,6 +134,11 @@ adamantite check
|
|
|
121
134
|
adamantite check src
|
|
122
135
|
```
|
|
123
136
|
|
|
137
|
+
`check` fails when Oxlint reports a warning, because a warning that passes is a pattern that
|
|
138
|
+
agents copy. Use `--allow-warnings` to pass with warnings. A forwarded `--max-warnings` or
|
|
139
|
+
`--deny-warnings`, such as `adamantite check -- --max-warnings 10`, replaces this default. To keep existing violations of a
|
|
140
|
+
rule while new code follows it, turn the rule off for those files in an Oxlint override.
|
|
141
|
+
|
|
124
142
|
Use `--only` to run one stage. Arguments after `--` go to that stage, and to Oxlint when
|
|
125
143
|
both run:
|
|
126
144
|
|
|
@@ -185,7 +203,9 @@ adamantite analyze --only monorepo --fix -- --select highest
|
|
|
185
203
|
### `adamantite doctor`
|
|
186
204
|
|
|
187
205
|
Assess every Adamantite-managed integration. Doctor is read-only. Each finding describes
|
|
188
|
-
the current state, the goal state, and how to verify the repair.
|
|
206
|
+
the current state, the goal state, and how to verify the repair. Doctor also checks that the
|
|
207
|
+
installed packages can run Oxlint: each declared package is installed, and `@effect/tsgo` has
|
|
208
|
+
a build for the installed Oxlint, tsrs, and platform. It starts no tool for this check.
|
|
189
209
|
|
|
190
210
|
```sh
|
|
191
211
|
adamantite doctor
|
|
@@ -206,44 +226,106 @@ directly. In a non-interactive run, Doctor prints the combined repair prompt and
|
|
|
206
226
|
when findings remain. If only assessment warnings remain, Doctor prints a Markdown
|
|
207
227
|
warning report and exits 0.
|
|
208
228
|
|
|
209
|
-
### `adamantite
|
|
229
|
+
### `adamantite harden`
|
|
210
230
|
|
|
211
|
-
|
|
231
|
+
Ask a coding agent to find the coding standards that the project already follows, and to put
|
|
232
|
+
each one at the highest level of enforcement that works: a custom rule when a rule can check
|
|
233
|
+
it, and a line in `CODING_STANDARDS.md` when no rule can.
|
|
212
234
|
|
|
213
235
|
```sh
|
|
214
|
-
adamantite
|
|
215
|
-
adamantite
|
|
236
|
+
adamantite harden
|
|
237
|
+
adamantite harden --path packages/web
|
|
238
|
+
adamantite harden --commits 500
|
|
216
239
|
```
|
|
217
240
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
241
|
+
The prompt lists the Oxlint config of the root and of each workspace package, the rules folders
|
|
242
|
+
that their `custom()` calls load, and the `AGENTS.md` of the root and of each package. Agents start
|
|
243
|
+
from `AGENTS.md`, so it must point to the other documentation. The prompt also lists each Markdown
|
|
244
|
+
file that `git ls-files` gives, except the changesets and the changelogs, and the agent reads each
|
|
245
|
+
one.
|
|
246
|
+
`--path` limits the session to one package or folder. The prompt then lists the configs of the
|
|
247
|
+
packages in that folder, or of the package that contains it, the rules folders that those configs
|
|
248
|
+
load, the `AGENTS.md` of the root and of those packages, and the Markdown files of those packages
|
|
249
|
+
and of the root. The prompt also lists the Markdown files that no chain of links or code-span paths
|
|
250
|
+
from an `AGENTS.md` reaches, and each link to a missing file. The agent also reads the fix commits of the last 200 commits, or of the number
|
|
251
|
+
that `--commits` gives, and a mistake that the fixes repeat becomes a candidate. With `--path`, it
|
|
252
|
+
reads only the commits that change that folder.
|
|
253
|
+
The agent shows the candidates and writes nothing until you approve them. When no human can
|
|
254
|
+
approve, the agent stops at the candidates.
|
|
255
|
+
|
|
256
|
+
In an interactive terminal, `harden` offers the same menu as Doctor: hand off to an installed
|
|
257
|
+
coding agent seeded with the prompt, copy the prompt, or do nothing. After a handoff, `harden`
|
|
258
|
+
runs `check`, then the Doctor assessment, and exits 1 when either fails.
|
|
259
|
+
During the session, the agent verifies each new or changed custom rule with temporary
|
|
260
|
+
RuleTester cases and removes the cases before handback.
|
|
261
|
+
Harden also exits 1 when the session added a link to a Markdown file that does not exist. A copy or "do nothing"
|
|
262
|
+
exits 0 without verification. Without a terminal, it prints the prompt and exits 0. `harden` never produces Doctor findings. See
|
|
263
|
+
[ADR 0012](docs/adr/0012-harden-instructs-agents-to-write-rules.md).
|
|
221
264
|
|
|
222
|
-
### `adamantite
|
|
265
|
+
### `adamantite update`
|
|
223
266
|
|
|
224
|
-
|
|
225
|
-
script in `package.json` runs it after each install:
|
|
267
|
+
Update Adamantite-managed dependencies, then report any setup findings:
|
|
226
268
|
|
|
227
|
-
```
|
|
228
|
-
|
|
269
|
+
```sh
|
|
270
|
+
adamantite update
|
|
271
|
+
adamantite doctor
|
|
229
272
|
```
|
|
230
273
|
|
|
231
|
-
|
|
232
|
-
|
|
274
|
+
`update` exits 0 when dependency updates succeed, even if doctor findings remain. Use
|
|
275
|
+
`adamantite doctor` as the CI gate. It also refreshes each copy of the
|
|
276
|
+
[Adamantite skill](#agent-skill) that differs from the skill of the installed Adamantite version.
|
|
233
277
|
|
|
234
278
|
### `adamantite rule`
|
|
235
279
|
|
|
236
|
-
Write and inspect [custom rules](#custom-rules):
|
|
280
|
+
Write, try, and inspect [custom rules](#custom-rules) and other Oxlint rules:
|
|
237
281
|
|
|
238
282
|
```sh
|
|
239
283
|
adamantite rule add no-process-env
|
|
240
284
|
adamantite rule add no-window --dir tooling/lint/rules
|
|
285
|
+
adamantite rule test add
|
|
286
|
+
adamantite rule test add no-process-env
|
|
287
|
+
adamantite rule test add no-process-env --path tests/no-process-env.test.ts
|
|
288
|
+
adamantite rule test
|
|
289
|
+
adamantite rule test --path tests/no-process-env.test.ts
|
|
290
|
+
adamantite rule try no-console --report src/debug.ts --accept src/index.ts
|
|
291
|
+
adamantite rule try no-restricted-imports --options '[{"paths":["node:fs"]}]' --report src/new.ts=draft.ts
|
|
292
|
+
adamantite rule try project/no-process-env --current --report src/env.ts
|
|
241
293
|
adamantite rule ast src/index.ts
|
|
242
294
|
```
|
|
243
295
|
|
|
244
|
-
`rule add` writes a rule stub to `.adamantite/
|
|
245
|
-
|
|
246
|
-
|
|
296
|
+
`rule add` writes only a rule stub to `.adamantite/lint/`, or to the folder that `--dir` names.
|
|
297
|
+
Agents verify it with temporary `RuleTester` cases by default. `rule test add` lists existing
|
|
298
|
+
rules for selection. Pass a rule name to skip the list; the command fails if the rule does not
|
|
299
|
+
exist. It writes an optional `<name>.test.ts` beside the rule, or at the file path that `--path`
|
|
300
|
+
names. `--dir` selects another rules folder. It preserves existing files. Adapt the generated
|
|
301
|
+
valid and invalid cases to the rule before running them.
|
|
302
|
+
|
|
303
|
+
`rule test` runs saved `.test.*` files beside the rules that `custom()` loads. Use
|
|
304
|
+
`rule test --path <file>` for a test saved elsewhere. CI and harden do not run saved tests
|
|
305
|
+
automatically. Agents remove their temporary verification cases before they finish.
|
|
306
|
+
During harden, agents can use `rule test add` to prepare those temporary cases and
|
|
307
|
+
`rule test --path <file>` to run them. They preserve user-owned saved tests.
|
|
308
|
+
|
|
309
|
+
`rule try` runs a trial. It lints cases with one rule and shows whether the rule reports or
|
|
310
|
+
accepts each case. Give the full rule name, such as `no-console`, `typescript/no-explicit-any`,
|
|
311
|
+
or `project/no-process-env`. Each `--report` adds a case that the rule must report, and each
|
|
312
|
+
`--accept` adds a case that the rule must accept. A trial needs at least one `--report` case.
|
|
313
|
+
Repeat either flag to add more cases.
|
|
314
|
+
|
|
315
|
+
Run `rule try` from the project root. A case is a file path relative to the project root. Use
|
|
316
|
+
`<path>=<file>` to lint the content of `<file>` as if it were at `<path>`. This form lets you try
|
|
317
|
+
code that is not in the project yet, and code in files that git ignores.
|
|
318
|
+
|
|
319
|
+
By default, the trial sets the rule to `error` with no options. `--options` gives the options
|
|
320
|
+
that come after the severity, as a JSON array. `--current` uses the rule setting from the
|
|
321
|
+
project config instead. You cannot use `--options` and `--current` together.
|
|
322
|
+
|
|
323
|
+
The trial lints a copy of the project in a temporary folder, so it does not change the project.
|
|
324
|
+
It exits 0 when every case gives the expected result, 1 when a case does not, and 2 when the
|
|
325
|
+
trial cannot check the cases, such as for a rule that does not exist.
|
|
326
|
+
|
|
327
|
+
`rule ast` prints the ESTree-shaped AST that Oxlint rules visit, so you can read node names off
|
|
328
|
+
real code.
|
|
247
329
|
|
|
248
330
|
### Pass arguments to underlying tools
|
|
249
331
|
|
|
@@ -251,7 +333,7 @@ Commands that invoke Knip, Oxlint, Oxfmt, or Sherif forward arguments after `--`
|
|
|
251
333
|
|
|
252
334
|
```sh
|
|
253
335
|
adamantite analyze --strict -- --directory packages/app
|
|
254
|
-
adamantite check src -- --
|
|
336
|
+
adamantite check src -- --format github
|
|
255
337
|
adamantite analyze --only monorepo -- --ignore-package package-a
|
|
256
338
|
```
|
|
257
339
|
|
|
@@ -262,34 +344,36 @@ bun run analyze -- -- --directory packages/app
|
|
|
262
344
|
npm run analyze -- -- --directory packages/app
|
|
263
345
|
```
|
|
264
346
|
|
|
265
|
-
`init`, `doctor`, and `update` do not forward arguments because they do not invoke one
|
|
347
|
+
`init`, `doctor`, `harden`, and `update` do not forward arguments because they do not invoke one
|
|
266
348
|
underlying CLI.
|
|
267
349
|
|
|
268
350
|
## Presets
|
|
269
351
|
|
|
270
|
-
Adamantite publishes configuration that can also be consumed directly
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
|
274
|
-
|
|
|
275
|
-
| `adamantite/lint
|
|
276
|
-
| `adamantite/lint/react
|
|
277
|
-
| `adamantite/lint/react-
|
|
278
|
-
| `adamantite/lint/tanstack` | Opinions for [TanStack Query](https://tanstack.com/query) with route loaders: queries defined once with `queryOptions()`, and no query data copied into state. See [the tanstack preset](#the-tanstack-preset).
|
|
279
|
-
| `adamantite/lint/nextjs` | Next.js rules.
|
|
280
|
-
| `adamantite/lint/vue` | Vue rules.
|
|
281
|
-
| `adamantite/lint/effect` | Curated [@effect/tsgo](https://github.com/Effect-TS/tsgo) rules for Effect misuse, such as effects that never run and unhandled errors. See [the effect preset](#the-effect-preset).
|
|
282
|
-
| `adamantite/lint/node` | Node.js rules.
|
|
283
|
-
| `adamantite/lint/jest` | Jest rules for test files. See [the jest and vitest presets](#the-jest-and-vitest-presets).
|
|
284
|
-
| `adamantite/lint/vitest` | Vitest rules for test files. See [the jest and vitest presets](#the-jest-and-vitest-presets).
|
|
285
|
-
| `adamantite/lint/
|
|
286
|
-
| `adamantite/lint/
|
|
287
|
-
| `adamantite/lint/
|
|
288
|
-
| `adamantite/
|
|
289
|
-
| `adamantite/rules`
|
|
290
|
-
| `adamantite/
|
|
291
|
-
| `adamantite/
|
|
292
|
-
| `adamantite/
|
|
352
|
+
Adamantite publishes configuration that can also be consumed directly. The package exports only
|
|
353
|
+
the imports in this table, and Node.js rejects any other path in the package:
|
|
354
|
+
|
|
355
|
+
| Export | Purpose |
|
|
356
|
+
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
357
|
+
| `adamantite/lint` | Core Oxlint rules. |
|
|
358
|
+
| `adamantite/lint/react` | React, JSX accessibility, and performance. |
|
|
359
|
+
| `adamantite/lint/react-strict` | React feature-code restrictions and curated [React Doctor](https://github.com/millionco/react-doctor) checks for state, effects, cleanup, and render lifetimes. See [the react-strict preset](#the-react-strict-preset). |
|
|
360
|
+
| `adamantite/lint/tanstack` | Opinions for [TanStack Query](https://tanstack.com/query) with route loaders: queries defined once with `queryOptions()`, and no query data copied into state. See [the tanstack preset](#the-tanstack-preset). |
|
|
361
|
+
| `adamantite/lint/nextjs` | Next.js rules. |
|
|
362
|
+
| `adamantite/lint/vue` | Vue rules. |
|
|
363
|
+
| `adamantite/lint/effect` | Curated [@effect/tsgo](https://github.com/Effect-TS/tsgo) rules for Effect misuse, such as effects that never run and unhandled errors, and vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules for tagged values. See [the effect preset](#the-effect-preset). |
|
|
364
|
+
| `adamantite/lint/node` | Node.js rules. |
|
|
365
|
+
| `adamantite/lint/jest` | Jest rules for test files. See [the jest and vitest presets](#the-jest-and-vitest-presets). |
|
|
366
|
+
| `adamantite/lint/vitest` | Vitest rules for test files. See [the jest and vitest presets](#the-jest-and-vitest-presets). |
|
|
367
|
+
| `adamantite/lint/architecture` | Load first-party rules for project-defined layer maps and import owners. No rules are enabled by default. |
|
|
368
|
+
| `adamantite/lint/strict` | Framework-neutral opinions: no type assertions outside tests, no `unknown` in signatures, no module mocks, no deep or wide destructuring, a reason on each suppression, no console calls, and no task comments. See [the strict preset](#the-strict-preset). |
|
|
369
|
+
| `adamantite/lint/tailwind` | [@shadcn/lint](https://github.com/shadcn-ui/lint) rules for Tailwind v4 design systems: no restyled components, raw colors, arbitrary values, inline styles, unknown classes, or unreadable class expressions. shadcn/ui is not required. See [the tailwind preset](#the-tailwind-preset). |
|
|
370
|
+
| `adamantite/rules` | A function, `custom()`, that loads the project's own rules from `.adamantite/lint/`. See [custom rules](#custom-rules). |
|
|
371
|
+
| `adamantite/rules/plugin` | `definePlugin`, `defineRule`, `eslintCompatPlugin`, and all Oxlint authoring types. |
|
|
372
|
+
| `adamantite/rules/testing` | `RuleTester` and its types for temporary agent verification and optional saved tests. |
|
|
373
|
+
| `adamantite/format` | Oxfmt configuration. |
|
|
374
|
+
| `adamantite/analyze` | Knip configuration. The `ignoreDependencies` named export groups suggested ignore lists; `init` sets `ignoreDependencies.monorepo` in a monorepo and `ignoreDependencies.effect` with the effect preset. |
|
|
375
|
+
| `adamantite/typescript` | Strict TypeScript configuration for TS 7+, with [ts-reset](https://github.com/total-typescript/ts-reset) types: `JSON.parse()` and `response.json()` return `unknown`. Allows only erasable syntax. Not for libraries. See [the TypeScript presets](#the-typescript-presets). |
|
|
376
|
+
| `adamantite/tsconfig` | The strict options of `adamantite/typescript` without the ts-reset types, for libraries. See [the TypeScript presets](#the-typescript-presets). |
|
|
293
377
|
|
|
294
378
|
When consuming the lint presets directly, hoist the core preset's ignore patterns onto the
|
|
295
379
|
root config. Oxlint does not merge `ignorePatterns` from extended configs, so without the
|
|
@@ -308,6 +392,44 @@ export default defineConfig({
|
|
|
308
392
|
|
|
309
393
|
Configs generated by `adamantite init` include this automatically.
|
|
310
394
|
|
|
395
|
+
### The TypeScript presets
|
|
396
|
+
|
|
397
|
+
`adamantite/tsconfig` sets strict compiler options for TypeScript 7 and later. It allows only
|
|
398
|
+
erasable syntax, so `enum`, a `namespace` with values, and parameter properties fail type checking.
|
|
399
|
+
|
|
400
|
+
`adamantite/typescript` adds type resets to the same options, so built-in APIs return safer
|
|
401
|
+
types. For example, `JSON.parse()`, `response.json()`, and property reads on `localStorage` return
|
|
402
|
+
`unknown` instead of `any`, and `includes()` on a literal array accepts a wider value. The project
|
|
403
|
+
needs no `reset.d.ts` file and no dependency, because the preset loads the resets from the
|
|
404
|
+
Adamantite package. The resets started from
|
|
405
|
+
[ts-reset](https://github.com/total-typescript/ts-reset) by Matt Pocock. See [credits](#credits).
|
|
406
|
+
|
|
407
|
+
The resets also cover built-in APIs that ts-reset leaves as `any`. `Object.values()` and
|
|
408
|
+
`Object.entries()` on a type without an index signature, `Object.assign()` with more than three
|
|
409
|
+
sources, `Object.getPrototypeOf()`, `Reflect.apply()`, `Reflect.construct()`, `eval()`, and the
|
|
410
|
+
values of a `JSON.parse()` reviver return or take `unknown`. TypeScript cannot change a property type or a
|
|
411
|
+
default type parameter by declaration merging, so `PromiseRejectedResult.reason` and
|
|
412
|
+
`MessageEvent` data stay `any`.
|
|
413
|
+
|
|
414
|
+
```json
|
|
415
|
+
{ "extends": "adamantite/typescript" }
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
Use `adamantite/tsconfig` in a library that publishes declaration files. A declaration file that
|
|
419
|
+
TypeScript emits with the type resets can name the global `AdamantiteTypeScript` helper types,
|
|
420
|
+
which a consumer without the resets does not have. Doctor reports a package whose
|
|
421
|
+
`tsconfig.json` loads the type resets, directly or through a base config, when the package is not
|
|
422
|
+
private and declares `exports` or `types`. Doctor asks the project's TypeScript with
|
|
423
|
+
`tsc --showConfig`.
|
|
424
|
+
|
|
425
|
+
The preset adds the type resets through `files`, and includes every file below your
|
|
426
|
+
`tsconfig.json` through `include`. List your files in `include`, which keeps the resets. A `files`
|
|
427
|
+
list in your `tsconfig.json` replaces the preset's list, so it drops the resets, and the config
|
|
428
|
+
still inherits the preset's `include`. A config that must check only its `files`, such as a
|
|
429
|
+
solution config with `"files": []` and `references`, sets `"include": []` too, or extends
|
|
430
|
+
`adamantite/tsconfig`. To use the strict options without the type resets, extend
|
|
431
|
+
`adamantite/tsconfig`.
|
|
432
|
+
|
|
311
433
|
### The jest and vitest presets
|
|
312
434
|
|
|
313
435
|
The `jest` and `vitest` presets apply their rules only to test files, so rules such as
|
|
@@ -356,8 +478,9 @@ ignores the `vitest/*` rules of an override that does not enable the `vitest` pl
|
|
|
356
478
|
### The react-strict preset
|
|
357
479
|
|
|
358
480
|
`adamantite/lint/react-strict` keeps state and side effects out of React feature code. Use
|
|
359
|
-
it together with `adamantite/lint/react`. It
|
|
360
|
-
|
|
481
|
+
it together with `adamantite/lint/react`. It loads Adamantite's first-party plugin and the
|
|
482
|
+
managed `oxlint-plugin-react-doctor` package. Init installs the pinned package when you
|
|
483
|
+
select `react-strict`. Doctor and update maintain its version.
|
|
361
484
|
|
|
362
485
|
`adamantite/no-react-state-hooks` reports calls to `useState`, `useReducer`, `useEffect`,
|
|
363
486
|
`useLayoutEffect`, `useSyncExternalStore`, `useMemo`, and `useCallback` imported from
|
|
@@ -391,23 +514,17 @@ export default defineConfig({
|
|
|
391
514
|
|
|
392
515
|
Each option replaces its default list.
|
|
393
516
|
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
`adamantite/lint/react-doctor` reports specific misuse of React state and effects. Use it
|
|
397
|
-
together with `adamantite/lint/react`. It needs the `oxlint-plugin-react-doctor` package.
|
|
398
|
-
`adamantite init` installs the pinned version when you select the preset, and
|
|
399
|
-
`adamantite doctor` and `adamantite update` keep it on that version. If you add the preset
|
|
400
|
-
by hand, install `oxlint-plugin-react-doctor` as a devDependency too.
|
|
401
|
-
|
|
402
|
-
The plugin exports more than 900 rules. The preset enables only rules that run on one file
|
|
517
|
+
The React Doctor package exports more than 900 rules. The preset enables only rules that run on one file
|
|
403
518
|
and that the native `react`, `react-hooks`, `jsx-a11y`, and `unicorn` rules do not already
|
|
404
519
|
report. Examples are an effect that does the work of an event handler (`no-effect-event-handler`), data fetched in an effect
|
|
405
|
-
(`no-fetch-in-effect`), and state changed in place (`no-direct-state-mutation`).
|
|
520
|
+
(`no-fetch-in-effect`), and state changed in place (`no-direct-state-mutation`). It also
|
|
521
|
+
checks cleanup, stale timer references, discarded effect cleanup callbacks, loading flags
|
|
522
|
+
that stay set after a failed request, and contexts or object URLs created during render. The
|
|
406
523
|
TanStack Query and TanStack Start rules are not in this preset. See
|
|
407
524
|
[ADR 0005](docs/adr/0005-curate-react-doctor-rules.md) for the criteria.
|
|
408
525
|
|
|
409
|
-
|
|
410
|
-
|
|
526
|
+
React Doctor checks also run in hook modules where state and effect hooks are allowed.
|
|
527
|
+
Some React Doctor rules
|
|
411
528
|
skip test files and fixtures by path, such as `__tests__/` and `*.test.tsx`.
|
|
412
529
|
|
|
413
530
|
`oxlint-plugin-react-doctor` has a modified MIT license. It needs written permission from
|
|
@@ -416,11 +533,15 @@ as a hosted product. Read the
|
|
|
416
533
|
[license](https://www.npmjs.com/package/oxlint-plugin-react-doctor?activeTab=code) before
|
|
417
534
|
you select the preset.
|
|
418
535
|
|
|
536
|
+
If you add `react-strict` by hand, install `oxlint-plugin-react-doctor` as a devDependency.
|
|
537
|
+
Run `adamantite doctor` for an existing `react-doctor` configuration. Its repair prompt
|
|
538
|
+
moves the preset to `react-strict` and preserves project settings and rule overrides.
|
|
539
|
+
|
|
419
540
|
### The tanstack preset
|
|
420
541
|
|
|
421
542
|
`adamantite/lint/tanstack` holds opinions for TanStack Query (`@tanstack/react-query`) in
|
|
422
543
|
apps that preload queries in route loaders, such as TanStack Router and TanStack Start apps.
|
|
423
|
-
|
|
544
|
+
It needs no extra package.
|
|
424
545
|
|
|
425
546
|
- `adamantite/query-from-loader` reports `useQuery`, `useSuspenseQuery`, `useInfiniteQuery`,
|
|
426
547
|
and `useSuspenseInfiniteQuery` calls in route files that take a plain options object or a `queryOptions()`
|
|
@@ -441,9 +562,8 @@ A route file is a file that calls a route factory from `@tanstack/react-router`,
|
|
|
441
562
|
the query, so components outside route files can define their queries inline.
|
|
442
563
|
`query-from-loader` checks one file at a time. It cannot prove that a loader preloads the
|
|
443
564
|
options, so it moves queries toward shared definitions but does not guarantee the preload.
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
[ADR 0008](docs/adr/0008-tanstack-query-options-from-loaders.md).
|
|
565
|
+
Query refetches from effects and mutation invalidation are not checked by these presets.
|
|
566
|
+
See [ADR 0008](docs/adr/0008-tanstack-query-options-from-loaders.md).
|
|
447
567
|
|
|
448
568
|
### The effect preset
|
|
449
569
|
|
|
@@ -454,43 +574,77 @@ simpler replacement (`catch-all-to-map-error`). The rules come from
|
|
|
454
574
|
[@effect/tsgo](https://github.com/Effect-TS/tsgo), the Effect Language Service for
|
|
455
575
|
TypeScript-Go, and need Oxlint's type-aware mode.
|
|
456
576
|
|
|
457
|
-
The
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
- `
|
|
464
|
-
`
|
|
465
|
-
- `
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
577
|
+
The preset also turns on the rules of the `anti-slop-effect` plugin from
|
|
578
|
+
[anti-slop](https://github.com/dmmulroy/anti-slop). Adamantite ships a build of it, so nothing
|
|
579
|
+
extra needs to be installed. The rules report tagged values that code handles by hand:
|
|
580
|
+
|
|
581
|
+
- `no-manual-tagged-construction` reports an object literal with a `_tag`. Use a tagged class,
|
|
582
|
+
such as `Data.TaggedClass` or `Data.TaggedError`, or the `make` of a tagged Schema.
|
|
583
|
+
- `no-manual-tag-comparison` reports a comparison or a `switch` on `_tag`. Use `Match.tag`,
|
|
584
|
+
`Predicate.isTagged`, or a helper such as `Option.isNone`.
|
|
585
|
+
- `no-manual-effect-error-tag` reports a broad `Effect.catch` handler that branches on `_tag`.
|
|
586
|
+
Use `Effect.catchTag` or `Effect.catchReason`.
|
|
587
|
+
- `prefer-effect-match` reports a chain of ternaries that compare one value with literals. Use
|
|
588
|
+
`Match` or a lookup table.
|
|
589
|
+
- `no-service-constructor-imports` reports a `make*` import from a project file outside tests.
|
|
590
|
+
Import the Layer of the service instead.
|
|
591
|
+
|
|
592
|
+
The preset turns off two core rules, `unicorn/no-array-callback-reference` and
|
|
593
|
+
`unicorn/no-array-method-this-argument`. They match an array method by its name only, so they
|
|
594
|
+
report Effect calls such as `Option.some(value)` and `Array.findLast(values, predicate)`.
|
|
595
|
+
|
|
596
|
+
The `@effect/tsgo` rules are not a JavaScript plugin. They exist only in the Effect builds of the Oxlint
|
|
597
|
+
binding and tsrs, which `@effect/tsgo` ships. When the project installs
|
|
598
|
+
`@effect/tsgo`, Adamantite runs Oxlint with those builds. Nothing changes in
|
|
599
|
+
installed package files, so linting needs no install script. These run Oxlint with the builds:
|
|
600
|
+
|
|
601
|
+
- `adamantite check`, `adamantite fix`, and `adamantite harden`.
|
|
602
|
+
- VS Code and Zed, through the settings that `adamantite init` writes. They start
|
|
603
|
+
`node_modules/adamantite/dist/oxlint.js` in place of `oxlint`.
|
|
604
|
+
|
|
605
|
+
A plain `oxlint` call, such as in a lint-staged config, stops with
|
|
606
|
+
`Unknown plugin: 'effecttsgo'`. Run `adamantite check --only lint` instead, which also takes
|
|
607
|
+
file arguments.
|
|
469
608
|
|
|
470
609
|
When you select the preset, `adamantite init` does these steps:
|
|
471
610
|
|
|
472
|
-
- Installs the pinned `@effect/tsgo
|
|
473
|
-
- Adds `"
|
|
474
|
-
`
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
`compilerOptions.plugins` in `tsconfig.json`. Editors that use the workspace TypeScript
|
|
479
|
-
get Effect quick fixes, refactors, and hovers. Oxlint reports the diagnostics, so the
|
|
480
|
-
language service does not report them a second time.
|
|
611
|
+
- Installs the pinned `@effect/tsgo`.
|
|
612
|
+
- Adds `{ "name": "@effect/language-service", "diagnostics": true }` to
|
|
613
|
+
`compilerOptions.plugins` in `tsconfig.json`. The rules read their options from this entry.
|
|
614
|
+
The Effect language server needs diagnostics enabled to offer semantic quick fixes.
|
|
615
|
+
- Configures the selected editors to use the installed Effect language server. Their Oxlint
|
|
616
|
+
settings hide duplicate Effect rule reports. CLI Oxlint keeps the effect preset.
|
|
481
617
|
- Sets `ignoreDependencies.effect` in `knip.config.ts`, because no package has the name
|
|
482
618
|
`@effect/language-service`.
|
|
483
619
|
|
|
484
620
|
`adamantite doctor` reports each missing part, and `adamantite update` keeps
|
|
485
|
-
`@effect/tsgo` on its pinned version. Each `@effect/tsgo` release
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
621
|
+
`@effect/tsgo` on its pinned version. Each `@effect/tsgo` release has Effect builds only for
|
|
622
|
+
some Oxlint and tsrs versions, so Adamantite moves the pins together. With an
|
|
623
|
+
Oxlint or tsrs version that the pinned `@effect/tsgo` has no build of, Oxlint
|
|
624
|
+
does not start, and the message names the versions that it supports. `@effect/tsgo` has no
|
|
625
|
+
builds for Linux with musl.
|
|
626
|
+
|
|
627
|
+
VS Code uses a copy of the Effect compiler and its standard libraries in
|
|
628
|
+
`node_modules/.cache/adamantite/effect/`. Init creates this cache without changing installed
|
|
629
|
+
package files. Zed starts the project's installed `effect-tsgo` CLI with `tsc --lsp --stdio`.
|
|
630
|
+
Both use a native TypeScript version that the installed `@effect/tsgo` supports.
|
|
631
|
+
|
|
632
|
+
To upgrade an existing editor setup, run:
|
|
489
633
|
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
634
|
+
```sh
|
|
635
|
+
adamantite update
|
|
636
|
+
adamantite init --non-interactive --script check --preset effect --editor vscode --editor zed --install-extensions
|
|
637
|
+
```
|
|
638
|
+
|
|
639
|
+
Init installs the TypeScript 7 extension for VS Code when `--install-extensions` is set.
|
|
640
|
+
In VS Code, run **TypeScript: Select TypeScript Version...**, then select **Use Workspace Version**
|
|
641
|
+
to use the Effect SDK. Install Zed's TypeScript language server extension (`zed://extension/tsgo`);
|
|
642
|
+
the managed server ID is `typescript-ls`.
|
|
643
|
+
|
|
644
|
+
After a fresh dependency install or an update, run
|
|
645
|
+
`adamantite init --non-interactive --script check --editor vscode` to prepare or refresh the SDK cache.
|
|
646
|
+
Doctor reports missing editor settings and a missing, incomplete, or stale SDK. It does not
|
|
647
|
+
write files. Install scripts can stay disabled.
|
|
494
648
|
|
|
495
649
|
The rules read their options from the tsconfig entry. For example, `unstable-api-usage`
|
|
496
650
|
reports each use of an API marked `@stability unstable`. To allow a module on purpose, list
|
|
@@ -502,7 +656,7 @@ it in `allowedUnstableApis`:
|
|
|
502
656
|
"plugins": [
|
|
503
657
|
{
|
|
504
658
|
"name": "@effect/language-service",
|
|
505
|
-
"diagnostics":
|
|
659
|
+
"diagnostics": true,
|
|
506
660
|
"allowedUnstableApis": ["effect/cli"],
|
|
507
661
|
},
|
|
508
662
|
],
|
|
@@ -521,10 +675,54 @@ as `Date.now()` or `process.env`, in code that is not Effect code. Inside Effect
|
|
|
521
675
|
reports them, because `Clock`, `Random`, and `Config` let tests control them. See
|
|
522
676
|
[ADR 0007](docs/adr/0007-effect-preset-patches-oxlint.md) for the criteria.
|
|
523
677
|
|
|
678
|
+
### The architecture preset
|
|
679
|
+
|
|
680
|
+
`adamantite/lint/architecture` loads the first-party plugin without enabling any rules.
|
|
681
|
+
Use it to configure `adamantite/layers` and `adamantite/import-owners` without the other
|
|
682
|
+
rules of `strict`. It needs no extra package. The `strict` preset still loads the same plugin.
|
|
683
|
+
|
|
684
|
+
```ts
|
|
685
|
+
import core from "adamantite/lint"
|
|
686
|
+
import architecture from "adamantite/lint/architecture"
|
|
687
|
+
import { defineConfig } from "oxlint"
|
|
688
|
+
|
|
689
|
+
export default defineConfig({
|
|
690
|
+
extends: [core, architecture],
|
|
691
|
+
ignorePatterns: core.ignorePatterns,
|
|
692
|
+
rules: {
|
|
693
|
+
"adamantite/layers": [
|
|
694
|
+
"error",
|
|
695
|
+
{
|
|
696
|
+
root: "src/lib",
|
|
697
|
+
layers: {
|
|
698
|
+
shared: { imports: [] },
|
|
699
|
+
services: { imports: ["shared"] },
|
|
700
|
+
},
|
|
701
|
+
},
|
|
702
|
+
],
|
|
703
|
+
"adamantite/import-owners": [
|
|
704
|
+
"error",
|
|
705
|
+
{ import: "giget", owners: ["src/lib/services/download.ts"] },
|
|
706
|
+
],
|
|
707
|
+
},
|
|
708
|
+
})
|
|
709
|
+
```
|
|
710
|
+
|
|
711
|
+
Each option after the severity is one layer map or one import and its owners. Set these
|
|
712
|
+
options for your project. The preset enables neither rule by default.
|
|
713
|
+
|
|
714
|
+
Each layer's `imports` list names siblings, and permissions are transitive. Put a child map
|
|
715
|
+
in that layer's `layers` property. Its root derives from the containing folder, and its
|
|
716
|
+
settings remain local. Every containing map checks the file independently.
|
|
717
|
+
|
|
718
|
+
You can also select it during setup with
|
|
719
|
+
`adamantite init --non-interactive --script check --preset architecture`.
|
|
720
|
+
|
|
524
721
|
### The strict preset
|
|
525
722
|
|
|
526
|
-
`adamantite/lint/strict` holds framework-neutral opinions. Use it with any other preset.
|
|
527
|
-
|
|
723
|
+
`adamantite/lint/strict` holds framework-neutral opinions. Use it with any other preset.
|
|
724
|
+
It needs no extra package. Most of its type rules come from
|
|
725
|
+
[anti-slop](https://github.com/dmmulroy/anti-slop), which Adamantite ships as a vendored build.
|
|
528
726
|
|
|
529
727
|
- `adamantite/no-overzealous-destructuring` reports destructuring patterns nested more than
|
|
530
728
|
`maxDepth` levels deep (default 2), such as `const { data: { user: { name } } } = query`,
|
|
@@ -532,6 +730,26 @@ reports them, because `Clock`, `Random`, and `Config` let tests control them. Se
|
|
|
532
730
|
element does not count. Keep the object and read its members, or split the pattern.
|
|
533
731
|
- `typescript/consistent-type-assertions` bans type assertions. `as const` stays allowed,
|
|
534
732
|
and test files (`*.test.*`, `*.spec.*`, and `__tests__/`) keep the core preset's setting.
|
|
733
|
+
- `no-console` reports a console call other than `console.info`.
|
|
734
|
+
- `adamantite/require-suppression-reason` reports an `oxlint-disable` or `eslint-disable`
|
|
735
|
+
comment, including the `-line` and `-next-line` forms, that gives no reason after `--`,
|
|
736
|
+
such as `// oxlint-disable-next-line no-console -- the CLI writes its report to stdout`. A
|
|
737
|
+
comment that names no rule is reported by the core preset's `unicorn/no-abusive-eslint-disable`.
|
|
738
|
+
- `no-warning-comments` reports a comment that starts with `TODO`, `FIXME`, `XXX`, or `HACK`.
|
|
739
|
+
Fix the code now, or track the work in your issue tracker. Do not only rename the marker.
|
|
740
|
+
- The anti-slop rules ask the code to decode input at its boundary into types that it owns.
|
|
741
|
+
They report `unknown` in function signatures and type aliases, loose dictionary types, a
|
|
742
|
+
`typeof` check outside a type predicate, `Reflect.get` and `Reflect.apply`, and Vitest or Jest
|
|
743
|
+
module mocks. They also report adjacent `filter` and `map` passes, a `reduce` that copies its
|
|
744
|
+
accumulator, `shape` in symbol names, and a missing blank line between statement groups.
|
|
745
|
+
- In test files, where type assertions are allowed, `anti-slop/require-safety-comment-for-type-assertion`
|
|
746
|
+
requires a `SAFETY:` comment on each assertion, and `anti-slop/no-chained-type-assertions` and
|
|
747
|
+
`anti-slop/no-widen-then-assert` report assertions that hide the source type. Outside tests,
|
|
748
|
+
`typescript/consistent-type-assertions` is the only rule that reports an assertion. To change
|
|
749
|
+
one of these three rules, set it in an `overrides` entry for the same test files, because the
|
|
750
|
+
preset's override takes priority over top-level `rules`.
|
|
751
|
+
- The preset turns off the core preset's `typescript/consistent-indexed-object-style` and
|
|
752
|
+
`unicorn/no-immediate-mutation`, which conflict with `anti-slop/no-known-value-widening`.
|
|
535
753
|
|
|
536
754
|
Set `maxDepth` and `maxProperties` to change the destructuring limits:
|
|
537
755
|
|
|
@@ -549,9 +767,11 @@ export default defineConfig({
|
|
|
549
767
|
})
|
|
550
768
|
```
|
|
551
769
|
|
|
552
|
-
### The
|
|
770
|
+
### The Tailwind preset
|
|
771
|
+
|
|
772
|
+
The preset uses upstream `shadcn/*` rule names and `settings.shadcn` keys.
|
|
553
773
|
|
|
554
|
-
`adamantite/lint/
|
|
774
|
+
`adamantite/lint/tailwind` needs Tailwind v4 and the `@shadcn/lint` package. `adamantite init`
|
|
555
775
|
installs the pinned version when you select the preset, and `adamantite doctor` and
|
|
556
776
|
`adamantite update` keep it on that version. If you add the preset by hand, install
|
|
557
777
|
`@shadcn/lint` as a devDependency too. The plugin finds your components and theme
|
|
@@ -561,11 +781,11 @@ components live elsewhere, set `settings.shadcn.ui`:
|
|
|
561
781
|
|
|
562
782
|
```ts
|
|
563
783
|
import core from "adamantite/lint"
|
|
564
|
-
import
|
|
784
|
+
import tailwind from "adamantite/lint/tailwind"
|
|
565
785
|
import { defineConfig } from "oxlint"
|
|
566
786
|
|
|
567
787
|
export default defineConfig({
|
|
568
|
-
extends: [core,
|
|
788
|
+
extends: [core, tailwind],
|
|
569
789
|
ignorePatterns: core.ignorePatterns,
|
|
570
790
|
settings: { shadcn: { ui: "@/ds" } },
|
|
571
791
|
})
|
|
@@ -580,21 +800,23 @@ contracts, and custom messages.
|
|
|
580
800
|
|
|
581
801
|
## Custom rules
|
|
582
802
|
|
|
583
|
-
Custom rules are Oxlint rules that your project writes and owns. Each file in
|
|
584
|
-
`.adamantite/
|
|
803
|
+
Custom rules are Oxlint rules that your project writes and owns. Each rule file in
|
|
804
|
+
`.adamantite/lint/` is one rule. `custom()` from `adamantite/rules` loads the folder
|
|
585
805
|
and enables each rule as `error` under the `project` plugin, so `no-process-env.ts` becomes
|
|
586
806
|
`project/no-process-env`. Add a file to add a rule, and delete the file to remove it. A file
|
|
587
|
-
that starts with `_`, such as `_helpers.ts`, is a helper
|
|
807
|
+
that starts with `_`, such as `_helpers.ts`, is a helper. Declaration files and optional
|
|
808
|
+
`.test.*` files are also excluded from plugin loading.
|
|
588
809
|
|
|
589
810
|
```text
|
|
590
|
-
.adamantite/
|
|
811
|
+
.adamantite/lint/
|
|
591
812
|
no-process-env.ts # enabled as project/no-process-env
|
|
813
|
+
no-process-env.test.ts # optional test, skipped by the plugin
|
|
592
814
|
_helpers.ts # skipped
|
|
593
815
|
```
|
|
594
816
|
|
|
595
817
|
```ts
|
|
596
|
-
// .adamantite/
|
|
597
|
-
import { defineRule } from "adamantite/rules"
|
|
818
|
+
// .adamantite/lint/no-process-env.ts
|
|
819
|
+
import { defineRule } from "adamantite/rules/plugin"
|
|
598
820
|
|
|
599
821
|
export default defineRule({
|
|
600
822
|
meta: {
|
|
@@ -616,7 +838,7 @@ export default defineRule({
|
|
|
616
838
|
```ts
|
|
617
839
|
// oxlint.config.ts
|
|
618
840
|
import core from "adamantite/lint"
|
|
619
|
-
import custom from "adamantite/
|
|
841
|
+
import custom from "adamantite/rules"
|
|
620
842
|
import { defineConfig } from "oxlint"
|
|
621
843
|
|
|
622
844
|
export default defineConfig({
|
|
@@ -629,20 +851,64 @@ export default defineConfig({
|
|
|
629
851
|
it to every generated config. It takes these options:
|
|
630
852
|
|
|
631
853
|
- `dir`: the rules folder. A relative path resolves from the file that calls `custom()`, not
|
|
632
|
-
from the working directory. Default: `.adamantite/
|
|
854
|
+
from the working directory. Default: `.adamantite/lint`.
|
|
633
855
|
- `name`: the plugin name that prefixes each rule. Default: `project`.
|
|
634
856
|
- `rules`: severity or options for a rule, by rule name without the prefix, such as
|
|
635
857
|
`{ "no-process-env": "warn" }`.
|
|
636
858
|
|
|
859
|
+
`adamantite/rules/plugin` re-exports the helpers and types from Adamantite's pinned
|
|
860
|
+
`@oxlint/plugins` dependency. Use `definePlugin` from that module if you write a plugin
|
|
861
|
+
that you register in `jsPlugins` yourself. You do not need to add `@oxlint/plugins` to your project.
|
|
862
|
+
|
|
863
|
+
Optional saved RuleTester tests use `node:test`. Exclude them from Vitest or Jest discovery
|
|
864
|
+
so those runners do not also try to run them. Keep the runner's default and existing
|
|
865
|
+
exclusions. For Vitest:
|
|
866
|
+
|
|
867
|
+
```ts
|
|
868
|
+
// vitest.config.ts
|
|
869
|
+
import { configDefaults, defineConfig } from "vitest/config"
|
|
870
|
+
|
|
871
|
+
export default defineConfig({
|
|
872
|
+
test: {
|
|
873
|
+
exclude: [...configDefaults.exclude, ".adamantite/lint/**/*.test.*"],
|
|
874
|
+
},
|
|
875
|
+
})
|
|
876
|
+
```
|
|
877
|
+
|
|
878
|
+
For Jest:
|
|
879
|
+
|
|
880
|
+
```js
|
|
881
|
+
// jest.config.mjs
|
|
882
|
+
export default {
|
|
883
|
+
testPathIgnorePatterns: ["/node_modules/", "<rootDir>/.adamantite/lint/"],
|
|
884
|
+
}
|
|
885
|
+
```
|
|
886
|
+
|
|
887
|
+
For another rules folder or a custom test `--path`, use its path in the exclusion. To
|
|
888
|
+
type-check tests that import `.ts` rule files, enable `compilerOptions.allowImportingTsExtensions`
|
|
889
|
+
in `tsconfig.json`. To check the hidden rules folder too, add `.adamantite/lint` to `include`.
|
|
890
|
+
|
|
891
|
+
To keep an existing `.adamantite/rules` folder, set `custom({ dir: ".adamantite/rules" })`
|
|
892
|
+
and use `rule add --dir .adamantite/rules`. You can instead move the folder to
|
|
893
|
+
`.adamantite/lint`. The previous `adamantite/lint/custom` import and named authoring imports
|
|
894
|
+
from `adamantite/rules` are removed. Import `custom` from `adamantite/rules` and the
|
|
895
|
+
authoring helpers and types from `adamantite/rules/plugin`. Run `adamantite doctor` for
|
|
896
|
+
migration instructions. Doctor reports the old imports and default folder without changing files.
|
|
897
|
+
|
|
637
898
|
Rule files run with Node.js type stripping, so use erasable TypeScript only: no `enum`,
|
|
638
899
|
`namespace` with values, or parameter properties. Rules get no type information. A rule
|
|
639
900
|
that throws prints an error for each file, and the lint run still exits 0. Adamantite owns
|
|
640
|
-
the wiring and the authoring guidance; your project owns the correctness
|
|
641
|
-
|
|
642
|
-
|
|
901
|
+
the wiring and the authoring guidance; your project owns the correctness of its rules.
|
|
902
|
+
Agents use `RuleTester` from `adamantite/rules/testing` to verify new and changed rules.
|
|
903
|
+
They run valid and invalid cases from stdin or a temporary file with Node.js, also in Bun
|
|
904
|
+
projects, and remove their temporary verification cases and fixtures before handback. The rules and their
|
|
905
|
+
runtime helpers stay in the target project. The "Custom rules" section of the
|
|
906
|
+
[Adamantite skill](#agent-skill) has the command and the full authoring guidance.
|
|
643
907
|
|
|
644
908
|
`adamantite doctor` reports a rule file that cannot load, with the reason, a rules folder
|
|
645
|
-
that no `custom()` call loads, and two rules folders that use the same plugin name.
|
|
909
|
+
that no `custom()` call loads, and two rules folders that use the same plugin name. It also
|
|
910
|
+
provides migration guidance for old API imports and the previous default rules folder.
|
|
911
|
+
User-owned saved tests and optional CI steps remain supported.
|
|
646
912
|
|
|
647
913
|
### Custom rules in a monorepo
|
|
648
914
|
|
|
@@ -652,7 +918,7 @@ root rules extends the root config:
|
|
|
652
918
|
|
|
653
919
|
```ts
|
|
654
920
|
// packages/web/oxlint.config.ts
|
|
655
|
-
import custom from "adamantite/
|
|
921
|
+
import custom from "adamantite/rules"
|
|
656
922
|
import { defineConfig } from "oxlint"
|
|
657
923
|
import root from "../../oxlint.config.ts"
|
|
658
924
|
|
|
@@ -665,14 +931,15 @@ extends it loads the same rules:
|
|
|
665
931
|
|
|
666
932
|
```ts
|
|
667
933
|
// tooling/lint/index.ts
|
|
668
|
-
import custom from "adamantite/
|
|
934
|
+
import custom from "adamantite/rules"
|
|
669
935
|
|
|
670
936
|
export default custom({ dir: "rules", name: "acme" })
|
|
671
937
|
```
|
|
672
938
|
|
|
673
939
|
Run `adamantite rule add <name> --dir tooling/lint/rules` to add a rule to that folder.
|
|
674
940
|
Doctor starts from the Oxlint config of the root and of each workspace package, and follows
|
|
675
|
-
relative imports and imports of workspace packages to find the `custom()` calls. It
|
|
941
|
+
relative imports, `#` imports, and imports of workspace packages to find the `custom()` calls. It
|
|
942
|
+
resolves them as Node.js does, so run it after you install the dependencies. It resolves
|
|
676
943
|
`dir` and `name` when they are string literals.
|
|
677
944
|
|
|
678
945
|
## Requirements and boundaries
|
|
@@ -692,16 +959,38 @@ relative imports and imports of workspace packages to find the `custom()` calls.
|
|
|
692
959
|
|
|
693
960
|
## Agent skill
|
|
694
961
|
|
|
695
|
-
|
|
696
|
-
|
|
962
|
+
The Adamantite skill teaches coding agents how to initialize, assess, repair, and update a
|
|
963
|
+
project, and how to write [custom rules](#custom-rules). The Adamantite package ships it.
|
|
964
|
+
|
|
965
|
+
`adamantite init` asks whether to set up coding agents. When you answer yes, or pass
|
|
966
|
+
`--agents` in non-interactive mode, init adds the Adamantite section to `AGENTS.md` and writes
|
|
967
|
+
the skill to these folders:
|
|
968
|
+
|
|
969
|
+
| Skill folder | Agents | When |
|
|
970
|
+
| ---------------- | --------------------------------------- | --------------------------- |
|
|
971
|
+
| `.agents/skills` | Codex, Cursor, Gemini CLI, and OpenCode | Always |
|
|
972
|
+
| `.claude/skills` | Claude Code | The project has `.claude/`. |
|
|
973
|
+
| `.grok/skills` | Grok Build | The project has `.grok/`. |
|
|
974
|
+
|
|
975
|
+
The Adamantite CLI bundles the skill, so the copy matches the Adamantite version that wrote
|
|
976
|
+
it. After you update Adamantite, `adamantite update` writes the skill again to each folder
|
|
977
|
+
whose copy changed. It also removes the `adamantite` entry from `skills-lock.json`, so the
|
|
978
|
+
`skills` CLI does not write the same folders. Commit the skill folders, so every clone has
|
|
979
|
+
the skill.
|
|
980
|
+
|
|
981
|
+
To install the skill from GitHub instead, with the
|
|
982
|
+
[`skills` CLI](https://github.com/vercel-labs/skills):
|
|
697
983
|
|
|
698
984
|
```sh
|
|
699
985
|
npx skills add adelrodriguez/adamantite --list
|
|
700
986
|
npx skills add adelrodriguez/adamantite --skill adamantite
|
|
701
987
|
```
|
|
702
988
|
|
|
703
|
-
|
|
704
|
-
|
|
989
|
+
`adamantite update` replaces a copy from GitHub with the skill of the installed Adamantite
|
|
990
|
+
version.
|
|
991
|
+
|
|
992
|
+
With pnpm 12.11 or later, `pnpm install` can also link the skill that the package ships
|
|
993
|
+
into the agent skill directories that exist in the project, such as `.claude/skills`,
|
|
705
994
|
after you approve it. pnpm creates the directory only when the agent that runs pnpm sets an
|
|
706
995
|
environment variable that identifies it, such as `CLAUDECODE` for `.claude/skills`.
|
|
707
996
|
Otherwise, if no skill directory exists, the install fails, so create one before you
|
|
@@ -720,6 +1009,37 @@ set `skills.dirs`.
|
|
|
720
1009
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository workflow. Contributors should
|
|
721
1010
|
also read the [domain glossary](GLOSSARY.md) and [architecture reference](docs/architecture.md).
|
|
722
1011
|
|
|
1012
|
+
## Credits
|
|
1013
|
+
|
|
1014
|
+
Adamantite builds on the work of these people and projects.
|
|
1015
|
+
|
|
1016
|
+
Adamantite ships code from these projects, each with its MIT license:
|
|
1017
|
+
|
|
1018
|
+
- [ts-reset](https://github.com/total-typescript/ts-reset) by
|
|
1019
|
+
[Matt Pocock](https://github.com/mattpocock) of
|
|
1020
|
+
[Total TypeScript](https://www.totaltypescript.com/ts-reset). The type resets of
|
|
1021
|
+
`adamantite/typescript` and their tests started from it.
|
|
1022
|
+
- [anti-slop](https://github.com/dmmulroy/anti-slop) by
|
|
1023
|
+
[Dillon Mulroy](https://github.com/dmmulroy), in `adamantite/lint/strict` and
|
|
1024
|
+
`adamantite/lint/effect`.
|
|
1025
|
+
|
|
1026
|
+
Adamantite configures and runs these tools:
|
|
1027
|
+
|
|
1028
|
+
- [Oxlint, Oxfmt, and tsrs](https://github.com/oxc-project) by
|
|
1029
|
+
[Boshen](https://github.com/Boshen) and the Oxc contributors.
|
|
1030
|
+
- [Knip](https://github.com/webpro-nl/knip) by [Lars Kappert](https://github.com/webpro).
|
|
1031
|
+
- [Sherif](https://github.com/QuiiBz/sherif) by [Tom Lienard](https://github.com/QuiiBz).
|
|
1032
|
+
- [@effect/tsgo](https://github.com/Effect-TS/tsgo) by
|
|
1033
|
+
[Mattia Manzati](https://github.com/mattiamanzati) and the
|
|
1034
|
+
[Effect](https://github.com/Effect-TS) team.
|
|
1035
|
+
- [React Doctor](https://github.com/millionco/react-doctor) by
|
|
1036
|
+
[Aiden Bai](https://github.com/aidenybai) of [Million](https://github.com/millionco).
|
|
1037
|
+
- [@shadcn/lint](https://github.com/shadcn-ui/lint) by [shadcn](https://github.com/shadcn).
|
|
1038
|
+
- [TypeScript](https://github.com/microsoft/TypeScript) by Microsoft.
|
|
1039
|
+
|
|
1040
|
+
The terminal interface uses [Clack](https://github.com/bombshell-dev/clack) by
|
|
1041
|
+
[Nate Moore](https://github.com/natemoo-re).
|
|
1042
|
+
|
|
723
1043
|
## License
|
|
724
1044
|
|
|
725
1045
|
Adamantite uses the [MIT License](LICENSE).
|