adamantite 0.44.0 → 0.46.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 +413 -122
- package/dist/index.js +638 -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 +0 -1
- package/dist/presets/lint/effect.js +26 -1
- package/dist/presets/lint/jest.d.ts +13 -0
- package/dist/presets/lint/jest.js +88 -68
- 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 +940 -31
- 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/vitest.d.ts +13 -0
- package/dist/presets/lint/vitest.js +111 -91
- 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/runtime-CVZPDpfE.js +11 -0
- package/package.json +79 -18
- package/skills/adamantite/SKILL.md +112 -200
- package/skills/adamantite/references/custom-rules.md +120 -0
- package/skills/adamantite/references/lint-rules.md +158 -0
- package/skills/adamantite/references/setup.md +64 -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
|
|
@@ -89,14 +92,19 @@ 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`.
|
|
95
98
|
|
|
96
99
|
Presets and TypeScript require the `check` or `fix` script. Editor extension installation
|
|
97
100
|
requires an editor. GitHub Actions requires a compatible script and a supported package
|
|
98
101
|
manager. Omitted boolean flags are disabled.
|
|
99
102
|
|
|
103
|
+
The GitHub Actions workflow runs the `check` and `analyze` scripts that you select.
|
|
104
|
+
Agents verify custom rules with temporary cases while they work. CI runs the rules through
|
|
105
|
+
`check` by default. Users can add an explicit `adamantite rule test` step for optional saved tests.
|
|
106
|
+
Init preserves a workflow with an explicit rule-test command, including its setup and other settings.
|
|
107
|
+
|
|
100
108
|
Existing package scripts whose commands differ from Adamantite's are kept and reported
|
|
101
109
|
instead of being replaced. The interactive initializer asks before overwriting them; in
|
|
102
110
|
non-interactive mode, pass `--overwrite-scripts` to replace them. To keep custom flags,
|
|
@@ -121,6 +129,11 @@ adamantite check
|
|
|
121
129
|
adamantite check src
|
|
122
130
|
```
|
|
123
131
|
|
|
132
|
+
`check` fails when Oxlint reports a warning, because a warning that passes is a pattern that
|
|
133
|
+
agents copy. Use `--allow-warnings` to pass with warnings. A forwarded `--max-warnings` or
|
|
134
|
+
`--deny-warnings`, such as `adamantite check -- --max-warnings 10`, replaces this default. To keep existing violations of a
|
|
135
|
+
rule while new code follows it, turn the rule off for those files in an Oxlint override.
|
|
136
|
+
|
|
124
137
|
Use `--only` to run one stage. Arguments after `--` go to that stage, and to Oxlint when
|
|
125
138
|
both run:
|
|
126
139
|
|
|
@@ -185,7 +198,9 @@ adamantite analyze --only monorepo --fix -- --select highest
|
|
|
185
198
|
### `adamantite doctor`
|
|
186
199
|
|
|
187
200
|
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.
|
|
201
|
+
the current state, the goal state, and how to verify the repair. Doctor also checks that the
|
|
202
|
+
installed packages can run Oxlint: each declared package is installed, and `@effect/tsgo` has
|
|
203
|
+
a build for the installed Oxlint, tsrs, and platform. It starts no tool for this check.
|
|
189
204
|
|
|
190
205
|
```sh
|
|
191
206
|
adamantite doctor
|
|
@@ -206,44 +221,106 @@ directly. In a non-interactive run, Doctor prints the combined repair prompt and
|
|
|
206
221
|
when findings remain. If only assessment warnings remain, Doctor prints a Markdown
|
|
207
222
|
warning report and exits 0.
|
|
208
223
|
|
|
209
|
-
### `adamantite
|
|
224
|
+
### `adamantite harden`
|
|
210
225
|
|
|
211
|
-
|
|
226
|
+
Ask a coding agent to find the coding standards that the project already follows, and to put
|
|
227
|
+
each one at the highest level of enforcement that works: a custom rule when a rule can check
|
|
228
|
+
it, and a line in `CODING_STANDARDS.md` when no rule can.
|
|
212
229
|
|
|
213
230
|
```sh
|
|
214
|
-
adamantite
|
|
215
|
-
adamantite
|
|
231
|
+
adamantite harden
|
|
232
|
+
adamantite harden --path packages/web
|
|
233
|
+
adamantite harden --commits 500
|
|
216
234
|
```
|
|
217
235
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
236
|
+
The prompt lists the Oxlint config of the root and of each workspace package, the rules folders
|
|
237
|
+
that their `custom()` calls load, and the `AGENTS.md` of the root and of each package. Agents start
|
|
238
|
+
from `AGENTS.md`, so it must point to the other documentation. The prompt also lists each Markdown
|
|
239
|
+
file that `git ls-files` gives, except the changesets and the changelogs, and the agent reads each
|
|
240
|
+
one.
|
|
241
|
+
`--path` limits the session to one package or folder. The prompt then lists the configs of the
|
|
242
|
+
packages in that folder, or of the package that contains it, the rules folders that those configs
|
|
243
|
+
load, the `AGENTS.md` of the root and of those packages, and the Markdown files of those packages
|
|
244
|
+
and of the root. The prompt also lists the Markdown files that no chain of links or code-span paths
|
|
245
|
+
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
|
|
246
|
+
that `--commits` gives, and a mistake that the fixes repeat becomes a candidate. With `--path`, it
|
|
247
|
+
reads only the commits that change that folder.
|
|
248
|
+
The agent shows the candidates and writes nothing until you approve them. When no human can
|
|
249
|
+
approve, the agent stops at the candidates.
|
|
250
|
+
|
|
251
|
+
In an interactive terminal, `harden` offers the same menu as Doctor: hand off to an installed
|
|
252
|
+
coding agent seeded with the prompt, copy the prompt, or do nothing. After a handoff, `harden`
|
|
253
|
+
runs `check`, then the Doctor assessment, and exits 1 when either fails.
|
|
254
|
+
During the session, the agent verifies each new or changed custom rule with temporary
|
|
255
|
+
RuleTester cases and removes the cases before handback.
|
|
256
|
+
Harden also exits 1 when the session added a link to a Markdown file that does not exist. A copy or "do nothing"
|
|
257
|
+
exits 0 without verification. Without a terminal, it prints the prompt and exits 0. `harden` never produces Doctor findings. See
|
|
258
|
+
[ADR 0012](docs/adr/0012-harden-instructs-agents-to-write-rules.md).
|
|
221
259
|
|
|
222
|
-
### `adamantite
|
|
260
|
+
### `adamantite update`
|
|
223
261
|
|
|
224
|
-
|
|
225
|
-
script in `package.json` runs it after each install:
|
|
262
|
+
Update Adamantite-managed dependencies, then report any setup findings:
|
|
226
263
|
|
|
227
|
-
```
|
|
228
|
-
|
|
264
|
+
```sh
|
|
265
|
+
adamantite update
|
|
266
|
+
adamantite doctor
|
|
229
267
|
```
|
|
230
268
|
|
|
231
|
-
|
|
232
|
-
|
|
269
|
+
`update` exits 0 when dependency updates succeed, even if doctor findings remain. Use
|
|
270
|
+
`adamantite doctor` as the CI gate. It also refreshes each copy of the
|
|
271
|
+
[Adamantite skill](#agent-skill) that differs from the skill of the installed Adamantite version.
|
|
233
272
|
|
|
234
273
|
### `adamantite rule`
|
|
235
274
|
|
|
236
|
-
Write and inspect [custom rules](#custom-rules):
|
|
275
|
+
Write, try, and inspect [custom rules](#custom-rules) and other Oxlint rules:
|
|
237
276
|
|
|
238
277
|
```sh
|
|
239
278
|
adamantite rule add no-process-env
|
|
240
279
|
adamantite rule add no-window --dir tooling/lint/rules
|
|
280
|
+
adamantite rule test add
|
|
281
|
+
adamantite rule test add no-process-env
|
|
282
|
+
adamantite rule test add no-process-env --path tests/no-process-env.test.ts
|
|
283
|
+
adamantite rule test
|
|
284
|
+
adamantite rule test --path tests/no-process-env.test.ts
|
|
285
|
+
adamantite rule try no-console --report src/debug.ts --accept src/index.ts
|
|
286
|
+
adamantite rule try no-restricted-imports --options '[{"paths":["node:fs"]}]' --report src/new.ts=draft.ts
|
|
287
|
+
adamantite rule try project/no-process-env --current --report src/env.ts
|
|
241
288
|
adamantite rule ast src/index.ts
|
|
242
289
|
```
|
|
243
290
|
|
|
244
|
-
`rule add` writes a rule stub to `.adamantite/
|
|
245
|
-
|
|
246
|
-
|
|
291
|
+
`rule add` writes only a rule stub to `.adamantite/lint/`, or to the folder that `--dir` names.
|
|
292
|
+
Agents verify it with temporary `RuleTester` cases by default. `rule test add` lists existing
|
|
293
|
+
rules for selection. Pass a rule name to skip the list; the command fails if the rule does not
|
|
294
|
+
exist. It writes an optional `<name>.test.ts` beside the rule, or at the file path that `--path`
|
|
295
|
+
names. `--dir` selects another rules folder. It preserves existing files. Adapt the generated
|
|
296
|
+
valid and invalid cases to the rule before running them.
|
|
297
|
+
|
|
298
|
+
`rule test` runs saved `.test.*` files beside the rules that `custom()` loads. Use
|
|
299
|
+
`rule test --path <file>` for a test saved elsewhere. CI and harden do not run saved tests
|
|
300
|
+
automatically. Agents remove their temporary verification cases before they finish.
|
|
301
|
+
During harden, agents can use `rule test add` to prepare those temporary cases and
|
|
302
|
+
`rule test --path <file>` to run them. They preserve user-owned saved tests.
|
|
303
|
+
|
|
304
|
+
`rule try` runs a trial. It lints cases with one rule and shows whether the rule reports or
|
|
305
|
+
accepts each case. Give the full rule name, such as `no-console`, `typescript/no-explicit-any`,
|
|
306
|
+
or `project/no-process-env`. Each `--report` adds a case that the rule must report, and each
|
|
307
|
+
`--accept` adds a case that the rule must accept. A trial needs at least one `--report` case.
|
|
308
|
+
Repeat either flag to add more cases.
|
|
309
|
+
|
|
310
|
+
Run `rule try` from the project root. A case is a file path relative to the project root. Use
|
|
311
|
+
`<path>=<file>` to lint the content of `<file>` as if it were at `<path>`. This form lets you try
|
|
312
|
+
code that is not in the project yet, and code in files that git ignores.
|
|
313
|
+
|
|
314
|
+
By default, the trial sets the rule to `error` with no options. `--options` gives the options
|
|
315
|
+
that come after the severity, as a JSON array. `--current` uses the rule setting from the
|
|
316
|
+
project config instead. You cannot use `--options` and `--current` together.
|
|
317
|
+
|
|
318
|
+
The trial lints a copy of the project in a temporary folder, so it does not change the project.
|
|
319
|
+
It exits 0 when every case gives the expected result, 1 when a case does not, and 2 when the
|
|
320
|
+
trial cannot check the cases, such as for a rule that does not exist.
|
|
321
|
+
|
|
322
|
+
`rule ast` prints the ESTree-shaped AST that Oxlint rules visit, so you can read node names off
|
|
323
|
+
real code.
|
|
247
324
|
|
|
248
325
|
### Pass arguments to underlying tools
|
|
249
326
|
|
|
@@ -251,7 +328,7 @@ Commands that invoke Knip, Oxlint, Oxfmt, or Sherif forward arguments after `--`
|
|
|
251
328
|
|
|
252
329
|
```sh
|
|
253
330
|
adamantite analyze --strict -- --directory packages/app
|
|
254
|
-
adamantite check src -- --
|
|
331
|
+
adamantite check src -- --format github
|
|
255
332
|
adamantite analyze --only monorepo -- --ignore-package package-a
|
|
256
333
|
```
|
|
257
334
|
|
|
@@ -262,34 +339,35 @@ bun run analyze -- -- --directory packages/app
|
|
|
262
339
|
npm run analyze -- -- --directory packages/app
|
|
263
340
|
```
|
|
264
341
|
|
|
265
|
-
`init`, `doctor`, and `update` do not forward arguments because they do not invoke one
|
|
342
|
+
`init`, `doctor`, `harden`, and `update` do not forward arguments because they do not invoke one
|
|
266
343
|
underlying CLI.
|
|
267
344
|
|
|
268
345
|
## Presets
|
|
269
346
|
|
|
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.
|
|
284
|
-
| `adamantite/lint/vitest` | Vitest rules.
|
|
285
|
-
| `adamantite/lint/
|
|
286
|
-
| `adamantite/lint/
|
|
287
|
-
| `adamantite/lint/
|
|
288
|
-
| `adamantite/
|
|
289
|
-
| `adamantite/rules`
|
|
290
|
-
| `adamantite/
|
|
291
|
-
| `adamantite/
|
|
292
|
-
| `adamantite/
|
|
347
|
+
Adamantite publishes configuration that can also be consumed directly. The package exports only
|
|
348
|
+
the imports in this table, and Node.js rejects any other path in the package:
|
|
349
|
+
|
|
350
|
+
| Export | Purpose |
|
|
351
|
+
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
352
|
+
| `adamantite/lint` | Core Oxlint rules. |
|
|
353
|
+
| `adamantite/lint/react` | React, JSX accessibility, and performance. |
|
|
354
|
+
| `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). |
|
|
355
|
+
| `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). |
|
|
356
|
+
| `adamantite/lint/nextjs` | Next.js rules. |
|
|
357
|
+
| `adamantite/lint/vue` | Vue rules. |
|
|
358
|
+
| `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). |
|
|
359
|
+
| `adamantite/lint/node` | Node.js rules. |
|
|
360
|
+
| `adamantite/lint/jest` | Jest rules for test files. See [the jest and vitest presets](#the-jest-and-vitest-presets). |
|
|
361
|
+
| `adamantite/lint/vitest` | Vitest rules for test files. See [the jest and vitest presets](#the-jest-and-vitest-presets). |
|
|
362
|
+
| `adamantite/lint/architecture` | Load first-party rules for project-defined layer maps and import owners. No rules are enabled by default. |
|
|
363
|
+
| `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). |
|
|
364
|
+
| `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). |
|
|
365
|
+
| `adamantite/rules` | A function, `custom()`, that loads the project's own rules from `.adamantite/lint/`. See [custom rules](#custom-rules). |
|
|
366
|
+
| `adamantite/rules/plugin` | `definePlugin`, `defineRule`, `eslintCompatPlugin`, and all Oxlint authoring types. |
|
|
367
|
+
| `adamantite/rules/testing` | `RuleTester` and its types for temporary agent verification and optional saved tests. |
|
|
368
|
+
| `adamantite/format` | Oxfmt configuration. |
|
|
369
|
+
| `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. |
|
|
370
|
+
| `adamantite/typescript` | Strict TypeScript configuration for TS 7+. Allows only erasable syntax, so `enum`, a `namespace` with values, and parameter properties fail type checking. |
|
|
293
371
|
|
|
294
372
|
When consuming the lint presets directly, hoist the core preset's ignore patterns onto the
|
|
295
373
|
root config. Oxlint does not merge `ignorePatterns` from extended configs, so without the
|
|
@@ -308,11 +386,57 @@ export default defineConfig({
|
|
|
308
386
|
|
|
309
387
|
Configs generated by `adamantite init` include this automatically.
|
|
310
388
|
|
|
389
|
+
### The jest and vitest presets
|
|
390
|
+
|
|
391
|
+
The `jest` and `vitest` presets apply their rules only to test files, so rules such as
|
|
392
|
+
`vitest/require-hook` do not report scripts and library code. Each preset exports `testFiles`, the
|
|
393
|
+
files that its test runner runs as tests by default. `vitest` `testFiles` match `*.test.*` and
|
|
394
|
+
`*.spec.*` files. `jest` `testFiles` also match files in `__tests__` folders.
|
|
395
|
+
|
|
396
|
+
Extend the preset to use these files:
|
|
397
|
+
|
|
398
|
+
```ts
|
|
399
|
+
import core from "adamantite/lint"
|
|
400
|
+
import vitest from "adamantite/lint/vitest"
|
|
401
|
+
import { defineConfig } from "oxlint"
|
|
402
|
+
|
|
403
|
+
export default defineConfig({
|
|
404
|
+
extends: [core, vitest],
|
|
405
|
+
ignorePatterns: core.ignorePatterns,
|
|
406
|
+
})
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
If your test runner finds tests in other files, use the preset in an override of your own
|
|
410
|
+
instead of `extends`. `vitest.plugins` and `vitest.rules` hold the preset's plugins and rules:
|
|
411
|
+
|
|
412
|
+
```ts
|
|
413
|
+
import core from "adamantite/lint"
|
|
414
|
+
import vitest, { testFiles } from "adamantite/lint/vitest"
|
|
415
|
+
import { defineConfig } from "oxlint"
|
|
416
|
+
|
|
417
|
+
export default defineConfig({
|
|
418
|
+
extends: [core],
|
|
419
|
+
ignorePatterns: core.ignorePatterns,
|
|
420
|
+
overrides: [
|
|
421
|
+
{
|
|
422
|
+
files: [...testFiles, "e2e/**/*.ts"],
|
|
423
|
+
plugins: vitest.plugins,
|
|
424
|
+
rules: { ...vitest.rules, "vitest/max-expects": "off" },
|
|
425
|
+
},
|
|
426
|
+
],
|
|
427
|
+
})
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
Change a test rule in an override, not in the top-level `rules`: the preset's rules for test files
|
|
431
|
+
replace top-level settings. Keep `plugins: vitest.plugins` in that override too, because Oxlint
|
|
432
|
+
ignores the `vitest/*` rules of an override that does not enable the `vitest` plugin.
|
|
433
|
+
|
|
311
434
|
### The react-strict preset
|
|
312
435
|
|
|
313
436
|
`adamantite/lint/react-strict` keeps state and side effects out of React feature code. Use
|
|
314
|
-
it together with `adamantite/lint/react`. It
|
|
315
|
-
|
|
437
|
+
it together with `adamantite/lint/react`. It loads Adamantite's first-party plugin and the
|
|
438
|
+
managed `oxlint-plugin-react-doctor` package. Init installs the pinned package when you
|
|
439
|
+
select `react-strict`. Doctor and update maintain its version.
|
|
316
440
|
|
|
317
441
|
`adamantite/no-react-state-hooks` reports calls to `useState`, `useReducer`, `useEffect`,
|
|
318
442
|
`useLayoutEffect`, `useSyncExternalStore`, `useMemo`, and `useCallback` imported from
|
|
@@ -346,23 +470,17 @@ export default defineConfig({
|
|
|
346
470
|
|
|
347
471
|
Each option replaces its default list.
|
|
348
472
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
`adamantite/lint/react-doctor` reports specific misuse of React state and effects. Use it
|
|
352
|
-
together with `adamantite/lint/react`. It needs the `oxlint-plugin-react-doctor` package.
|
|
353
|
-
`adamantite init` installs the pinned version when you select the preset, and
|
|
354
|
-
`adamantite doctor` and `adamantite update` keep it on that version. If you add the preset
|
|
355
|
-
by hand, install `oxlint-plugin-react-doctor` as a devDependency too.
|
|
356
|
-
|
|
357
|
-
The plugin exports more than 900 rules. The preset enables only rules that run on one file
|
|
473
|
+
The React Doctor package exports more than 900 rules. The preset enables only rules that run on one file
|
|
358
474
|
and that the native `react`, `react-hooks`, `jsx-a11y`, and `unicorn` rules do not already
|
|
359
475
|
report. Examples are an effect that does the work of an event handler (`no-effect-event-handler`), data fetched in an effect
|
|
360
|
-
(`no-fetch-in-effect`), and state changed in place (`no-direct-state-mutation`).
|
|
476
|
+
(`no-fetch-in-effect`), and state changed in place (`no-direct-state-mutation`). It also
|
|
477
|
+
checks cleanup, stale timer references, discarded effect cleanup callbacks, loading flags
|
|
478
|
+
that stay set after a failed request, and contexts or object URLs created during render. The
|
|
361
479
|
TanStack Query and TanStack Start rules are not in this preset. See
|
|
362
480
|
[ADR 0005](docs/adr/0005-curate-react-doctor-rules.md) for the criteria.
|
|
363
481
|
|
|
364
|
-
|
|
365
|
-
|
|
482
|
+
React Doctor checks also run in hook modules where state and effect hooks are allowed.
|
|
483
|
+
Some React Doctor rules
|
|
366
484
|
skip test files and fixtures by path, such as `__tests__/` and `*.test.tsx`.
|
|
367
485
|
|
|
368
486
|
`oxlint-plugin-react-doctor` has a modified MIT license. It needs written permission from
|
|
@@ -371,11 +489,15 @@ as a hosted product. Read the
|
|
|
371
489
|
[license](https://www.npmjs.com/package/oxlint-plugin-react-doctor?activeTab=code) before
|
|
372
490
|
you select the preset.
|
|
373
491
|
|
|
492
|
+
If you add `react-strict` by hand, install `oxlint-plugin-react-doctor` as a devDependency.
|
|
493
|
+
Run `adamantite doctor` for an existing `react-doctor` configuration. Its repair prompt
|
|
494
|
+
moves the preset to `react-strict` and preserves project settings and rule overrides.
|
|
495
|
+
|
|
374
496
|
### The tanstack preset
|
|
375
497
|
|
|
376
498
|
`adamantite/lint/tanstack` holds opinions for TanStack Query (`@tanstack/react-query`) in
|
|
377
499
|
apps that preload queries in route loaders, such as TanStack Router and TanStack Start apps.
|
|
378
|
-
|
|
500
|
+
It needs no extra package.
|
|
379
501
|
|
|
380
502
|
- `adamantite/query-from-loader` reports `useQuery`, `useSuspenseQuery`, `useInfiniteQuery`,
|
|
381
503
|
and `useSuspenseInfiniteQuery` calls in route files that take a plain options object or a `queryOptions()`
|
|
@@ -396,9 +518,8 @@ A route file is a file that calls a route factory from `@tanstack/react-router`,
|
|
|
396
518
|
the query, so components outside route files can define their queries inline.
|
|
397
519
|
`query-from-loader` checks one file at a time. It cannot prove that a loader preloads the
|
|
398
520
|
options, so it moves queries toward shared definitions but does not guarantee the preload.
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
[ADR 0008](docs/adr/0008-tanstack-query-options-from-loaders.md).
|
|
521
|
+
Query refetches from effects and mutation invalidation are not checked by these presets.
|
|
522
|
+
See [ADR 0008](docs/adr/0008-tanstack-query-options-from-loaders.md).
|
|
402
523
|
|
|
403
524
|
### The effect preset
|
|
404
525
|
|
|
@@ -409,43 +530,77 @@ simpler replacement (`catch-all-to-map-error`). The rules come from
|
|
|
409
530
|
[@effect/tsgo](https://github.com/Effect-TS/tsgo), the Effect Language Service for
|
|
410
531
|
TypeScript-Go, and need Oxlint's type-aware mode.
|
|
411
532
|
|
|
412
|
-
The
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
- `
|
|
419
|
-
`
|
|
420
|
-
- `
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
533
|
+
The preset also turns on the rules of the `anti-slop-effect` plugin from
|
|
534
|
+
[anti-slop](https://github.com/dmmulroy/anti-slop). Adamantite ships a build of it, so nothing
|
|
535
|
+
extra needs to be installed. The rules report tagged values that code handles by hand:
|
|
536
|
+
|
|
537
|
+
- `no-manual-tagged-construction` reports an object literal with a `_tag`. Use a tagged class,
|
|
538
|
+
such as `Data.TaggedClass` or `Data.TaggedError`, or the `make` of a tagged Schema.
|
|
539
|
+
- `no-manual-tag-comparison` reports a comparison or a `switch` on `_tag`. Use `Match.tag`,
|
|
540
|
+
`Predicate.isTagged`, or a helper such as `Option.isNone`.
|
|
541
|
+
- `no-manual-effect-error-tag` reports a broad `Effect.catch` handler that branches on `_tag`.
|
|
542
|
+
Use `Effect.catchTag` or `Effect.catchReason`.
|
|
543
|
+
- `prefer-effect-match` reports a chain of ternaries that compare one value with literals. Use
|
|
544
|
+
`Match` or a lookup table.
|
|
545
|
+
- `no-service-constructor-imports` reports a `make*` import from a project file outside tests.
|
|
546
|
+
Import the Layer of the service instead.
|
|
547
|
+
|
|
548
|
+
The preset turns off two core rules, `unicorn/no-array-callback-reference` and
|
|
549
|
+
`unicorn/no-array-method-this-argument`. They match an array method by its name only, so they
|
|
550
|
+
report Effect calls such as `Option.some(value)` and `Array.findLast(values, predicate)`.
|
|
551
|
+
|
|
552
|
+
The `@effect/tsgo` rules are not a JavaScript plugin. They exist only in the Effect builds of the Oxlint
|
|
553
|
+
binding and tsrs, which `@effect/tsgo` ships. When the project installs
|
|
554
|
+
`@effect/tsgo`, Adamantite runs Oxlint with those builds. Nothing changes in
|
|
555
|
+
installed package files, so linting needs no install script. These run Oxlint with the builds:
|
|
556
|
+
|
|
557
|
+
- `adamantite check`, `adamantite fix`, and `adamantite harden`.
|
|
558
|
+
- VS Code and Zed, through the settings that `adamantite init` writes. They start
|
|
559
|
+
`node_modules/adamantite/dist/oxlint.js` in place of `oxlint`.
|
|
560
|
+
|
|
561
|
+
A plain `oxlint` call, such as in a lint-staged config, stops with
|
|
562
|
+
`Unknown plugin: 'effecttsgo'`. Run `adamantite check --only lint` instead, which also takes
|
|
563
|
+
file arguments.
|
|
424
564
|
|
|
425
565
|
When you select the preset, `adamantite init` does these steps:
|
|
426
566
|
|
|
427
|
-
- Installs the pinned `@effect/tsgo
|
|
428
|
-
- Adds `"
|
|
429
|
-
`
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
`compilerOptions.plugins` in `tsconfig.json`. Editors that use the workspace TypeScript
|
|
434
|
-
get Effect quick fixes, refactors, and hovers. Oxlint reports the diagnostics, so the
|
|
435
|
-
language service does not report them a second time.
|
|
567
|
+
- Installs the pinned `@effect/tsgo`.
|
|
568
|
+
- Adds `{ "name": "@effect/language-service", "diagnostics": true }` to
|
|
569
|
+
`compilerOptions.plugins` in `tsconfig.json`. The rules read their options from this entry.
|
|
570
|
+
The Effect language server needs diagnostics enabled to offer semantic quick fixes.
|
|
571
|
+
- Configures the selected editors to use the installed Effect language server. Their Oxlint
|
|
572
|
+
settings hide duplicate Effect rule reports. CLI Oxlint keeps the effect preset.
|
|
436
573
|
- Sets `ignoreDependencies.effect` in `knip.config.ts`, because no package has the name
|
|
437
574
|
`@effect/language-service`.
|
|
438
575
|
|
|
439
576
|
`adamantite doctor` reports each missing part, and `adamantite update` keeps
|
|
440
|
-
`@effect/tsgo` on its pinned version. Each `@effect/tsgo` release
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
577
|
+
`@effect/tsgo` on its pinned version. Each `@effect/tsgo` release has Effect builds only for
|
|
578
|
+
some Oxlint and tsrs versions, so Adamantite moves the pins together. With an
|
|
579
|
+
Oxlint or tsrs version that the pinned `@effect/tsgo` has no build of, Oxlint
|
|
580
|
+
does not start, and the message names the versions that it supports. `@effect/tsgo` has no
|
|
581
|
+
builds for Linux with musl.
|
|
582
|
+
|
|
583
|
+
VS Code uses a copy of the Effect compiler and its standard libraries in
|
|
584
|
+
`node_modules/.cache/adamantite/effect/`. Init creates this cache without changing installed
|
|
585
|
+
package files. Zed starts the project's installed `effect-tsgo` CLI with `tsc --lsp --stdio`.
|
|
586
|
+
Both use a native TypeScript version that the installed `@effect/tsgo` supports.
|
|
444
587
|
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
588
|
+
To upgrade an existing editor setup, run:
|
|
589
|
+
|
|
590
|
+
```sh
|
|
591
|
+
adamantite update
|
|
592
|
+
adamantite init --non-interactive --script check --preset effect --editor vscode --editor zed --install-extensions
|
|
593
|
+
```
|
|
594
|
+
|
|
595
|
+
Init installs the TypeScript 7 extension for VS Code when `--install-extensions` is set.
|
|
596
|
+
In VS Code, run **TypeScript: Select TypeScript Version...**, then select **Use Workspace Version**
|
|
597
|
+
to use the Effect SDK. Install Zed's TypeScript language server extension (`zed://extension/tsgo`);
|
|
598
|
+
the managed server ID is `typescript-ls`.
|
|
599
|
+
|
|
600
|
+
After a fresh dependency install or an update, run
|
|
601
|
+
`adamantite init --non-interactive --script check --editor vscode` to prepare or refresh the SDK cache.
|
|
602
|
+
Doctor reports missing editor settings and a missing, incomplete, or stale SDK. It does not
|
|
603
|
+
write files. Install scripts can stay disabled.
|
|
449
604
|
|
|
450
605
|
The rules read their options from the tsconfig entry. For example, `unstable-api-usage`
|
|
451
606
|
reports each use of an API marked `@stability unstable`. To allow a module on purpose, list
|
|
@@ -457,7 +612,7 @@ it in `allowedUnstableApis`:
|
|
|
457
612
|
"plugins": [
|
|
458
613
|
{
|
|
459
614
|
"name": "@effect/language-service",
|
|
460
|
-
"diagnostics":
|
|
615
|
+
"diagnostics": true,
|
|
461
616
|
"allowedUnstableApis": ["effect/cli"],
|
|
462
617
|
},
|
|
463
618
|
],
|
|
@@ -476,10 +631,55 @@ as `Date.now()` or `process.env`, in code that is not Effect code. Inside Effect
|
|
|
476
631
|
reports them, because `Clock`, `Random`, and `Config` let tests control them. See
|
|
477
632
|
[ADR 0007](docs/adr/0007-effect-preset-patches-oxlint.md) for the criteria.
|
|
478
633
|
|
|
634
|
+
### The architecture preset
|
|
635
|
+
|
|
636
|
+
`adamantite/lint/architecture` loads the first-party plugin without enabling any rules.
|
|
637
|
+
Use it to configure `adamantite/layers` and `adamantite/import-owners` without the other
|
|
638
|
+
rules of `strict`. It needs no extra package. The `strict` preset still loads the same plugin.
|
|
639
|
+
|
|
640
|
+
```ts
|
|
641
|
+
import core from "adamantite/lint"
|
|
642
|
+
import architecture from "adamantite/lint/architecture"
|
|
643
|
+
import { defineConfig } from "oxlint"
|
|
644
|
+
|
|
645
|
+
export default defineConfig({
|
|
646
|
+
extends: [core, architecture],
|
|
647
|
+
ignorePatterns: core.ignorePatterns,
|
|
648
|
+
rules: {
|
|
649
|
+
"adamantite/layers": [
|
|
650
|
+
"error",
|
|
651
|
+
{
|
|
652
|
+
root: "src/lib",
|
|
653
|
+
layers: {
|
|
654
|
+
shared: { imports: [] },
|
|
655
|
+
services: { imports: ["shared"] },
|
|
656
|
+
},
|
|
657
|
+
},
|
|
658
|
+
],
|
|
659
|
+
"adamantite/import-owners": [
|
|
660
|
+
"error",
|
|
661
|
+
{ import: "giget", owners: ["src/lib/services/download.ts"] },
|
|
662
|
+
],
|
|
663
|
+
},
|
|
664
|
+
})
|
|
665
|
+
```
|
|
666
|
+
|
|
667
|
+
Each option after the severity is one layer map or one import and its owners. Set these
|
|
668
|
+
options for your project. The preset enables neither rule by default.
|
|
669
|
+
|
|
670
|
+
Each layer's `imports` list names siblings, and permissions are transitive. Put a child map
|
|
671
|
+
in that layer's `layers` property. Its root derives from the containing folder, and its
|
|
672
|
+
settings remain local. Every containing map checks the file independently. For the previous
|
|
673
|
+
array-valued declarations, run `adamantite doctor` and follow its migration instructions.
|
|
674
|
+
|
|
675
|
+
You can also select it during setup with
|
|
676
|
+
`adamantite init --non-interactive --script check --preset architecture`.
|
|
677
|
+
|
|
479
678
|
### The strict preset
|
|
480
679
|
|
|
481
|
-
`adamantite/lint/strict` holds framework-neutral opinions. Use it with any other preset.
|
|
482
|
-
|
|
680
|
+
`adamantite/lint/strict` holds framework-neutral opinions. Use it with any other preset.
|
|
681
|
+
It needs no extra package. Most of its type rules come from
|
|
682
|
+
[anti-slop](https://github.com/dmmulroy/anti-slop), which Adamantite ships as a vendored build.
|
|
483
683
|
|
|
484
684
|
- `adamantite/no-overzealous-destructuring` reports destructuring patterns nested more than
|
|
485
685
|
`maxDepth` levels deep (default 2), such as `const { data: { user: { name } } } = query`,
|
|
@@ -487,6 +687,26 @@ reports them, because `Clock`, `Random`, and `Config` let tests control them. Se
|
|
|
487
687
|
element does not count. Keep the object and read its members, or split the pattern.
|
|
488
688
|
- `typescript/consistent-type-assertions` bans type assertions. `as const` stays allowed,
|
|
489
689
|
and test files (`*.test.*`, `*.spec.*`, and `__tests__/`) keep the core preset's setting.
|
|
690
|
+
- `no-console` reports a console call other than `console.info`.
|
|
691
|
+
- `adamantite/require-suppression-reason` reports an `oxlint-disable` or `eslint-disable`
|
|
692
|
+
comment, including the `-line` and `-next-line` forms, that gives no reason after `--`,
|
|
693
|
+
such as `// oxlint-disable-next-line no-console -- the CLI writes its report to stdout`. A
|
|
694
|
+
comment that names no rule is reported by the core preset's `unicorn/no-abusive-eslint-disable`.
|
|
695
|
+
- `no-warning-comments` reports a comment that starts with `TODO`, `FIXME`, `XXX`, or `HACK`.
|
|
696
|
+
Fix the code now, or track the work in your issue tracker. Do not only rename the marker.
|
|
697
|
+
- The anti-slop rules ask the code to decode input at its boundary into types that it owns.
|
|
698
|
+
They report `unknown` in function signatures and type aliases, loose dictionary types, a
|
|
699
|
+
`typeof` check outside a type predicate, `Reflect.get` and `Reflect.apply`, and Vitest or Jest
|
|
700
|
+
module mocks. They also report adjacent `filter` and `map` passes, a `reduce` that copies its
|
|
701
|
+
accumulator, `shape` in symbol names, and a missing blank line between statement groups.
|
|
702
|
+
- In test files, where type assertions are allowed, `anti-slop/require-safety-comment-for-type-assertion`
|
|
703
|
+
requires a `SAFETY:` comment on each assertion, and `anti-slop/no-chained-type-assertions` and
|
|
704
|
+
`anti-slop/no-widen-then-assert` report assertions that hide the source type. Outside tests,
|
|
705
|
+
`typescript/consistent-type-assertions` is the only rule that reports an assertion. To change
|
|
706
|
+
one of these three rules, set it in an `overrides` entry for the same test files, because the
|
|
707
|
+
preset's override takes priority over top-level `rules`.
|
|
708
|
+
- The preset turns off the core preset's `typescript/consistent-indexed-object-style` and
|
|
709
|
+
`unicorn/no-immediate-mutation`, which conflict with `anti-slop/no-known-value-widening`.
|
|
490
710
|
|
|
491
711
|
Set `maxDepth` and `maxProperties` to change the destructuring limits:
|
|
492
712
|
|
|
@@ -504,9 +724,11 @@ export default defineConfig({
|
|
|
504
724
|
})
|
|
505
725
|
```
|
|
506
726
|
|
|
507
|
-
### The
|
|
727
|
+
### The Tailwind preset
|
|
508
728
|
|
|
509
|
-
`
|
|
729
|
+
The preset uses upstream `shadcn/*` rule names and `settings.shadcn` keys.
|
|
730
|
+
|
|
731
|
+
`adamantite/lint/tailwind` needs Tailwind v4 and the `@shadcn/lint` package. `adamantite init`
|
|
510
732
|
installs the pinned version when you select the preset, and `adamantite doctor` and
|
|
511
733
|
`adamantite update` keep it on that version. If you add the preset by hand, install
|
|
512
734
|
`@shadcn/lint` as a devDependency too. The plugin finds your components and theme
|
|
@@ -516,11 +738,11 @@ components live elsewhere, set `settings.shadcn.ui`:
|
|
|
516
738
|
|
|
517
739
|
```ts
|
|
518
740
|
import core from "adamantite/lint"
|
|
519
|
-
import
|
|
741
|
+
import tailwind from "adamantite/lint/tailwind"
|
|
520
742
|
import { defineConfig } from "oxlint"
|
|
521
743
|
|
|
522
744
|
export default defineConfig({
|
|
523
|
-
extends: [core,
|
|
745
|
+
extends: [core, tailwind],
|
|
524
746
|
ignorePatterns: core.ignorePatterns,
|
|
525
747
|
settings: { shadcn: { ui: "@/ds" } },
|
|
526
748
|
})
|
|
@@ -535,21 +757,23 @@ contracts, and custom messages.
|
|
|
535
757
|
|
|
536
758
|
## Custom rules
|
|
537
759
|
|
|
538
|
-
Custom rules are Oxlint rules that your project writes and owns. Each file in
|
|
539
|
-
`.adamantite/
|
|
760
|
+
Custom rules are Oxlint rules that your project writes and owns. Each rule file in
|
|
761
|
+
`.adamantite/lint/` is one rule. `custom()` from `adamantite/rules` loads the folder
|
|
540
762
|
and enables each rule as `error` under the `project` plugin, so `no-process-env.ts` becomes
|
|
541
763
|
`project/no-process-env`. Add a file to add a rule, and delete the file to remove it. A file
|
|
542
|
-
that starts with `_`, such as `_helpers.ts`, is a helper
|
|
764
|
+
that starts with `_`, such as `_helpers.ts`, is a helper. Declaration files and optional
|
|
765
|
+
`.test.*` files are also excluded from plugin loading.
|
|
543
766
|
|
|
544
767
|
```text
|
|
545
|
-
.adamantite/
|
|
768
|
+
.adamantite/lint/
|
|
546
769
|
no-process-env.ts # enabled as project/no-process-env
|
|
770
|
+
no-process-env.test.ts # optional test, skipped by the plugin
|
|
547
771
|
_helpers.ts # skipped
|
|
548
772
|
```
|
|
549
773
|
|
|
550
774
|
```ts
|
|
551
|
-
// .adamantite/
|
|
552
|
-
import { defineRule } from "adamantite/rules"
|
|
775
|
+
// .adamantite/lint/no-process-env.ts
|
|
776
|
+
import { defineRule } from "adamantite/rules/plugin"
|
|
553
777
|
|
|
554
778
|
export default defineRule({
|
|
555
779
|
meta: {
|
|
@@ -571,7 +795,7 @@ export default defineRule({
|
|
|
571
795
|
```ts
|
|
572
796
|
// oxlint.config.ts
|
|
573
797
|
import core from "adamantite/lint"
|
|
574
|
-
import custom from "adamantite/
|
|
798
|
+
import custom from "adamantite/rules"
|
|
575
799
|
import { defineConfig } from "oxlint"
|
|
576
800
|
|
|
577
801
|
export default defineConfig({
|
|
@@ -584,20 +808,64 @@ export default defineConfig({
|
|
|
584
808
|
it to every generated config. It takes these options:
|
|
585
809
|
|
|
586
810
|
- `dir`: the rules folder. A relative path resolves from the file that calls `custom()`, not
|
|
587
|
-
from the working directory. Default: `.adamantite/
|
|
811
|
+
from the working directory. Default: `.adamantite/lint`.
|
|
588
812
|
- `name`: the plugin name that prefixes each rule. Default: `project`.
|
|
589
813
|
- `rules`: severity or options for a rule, by rule name without the prefix, such as
|
|
590
814
|
`{ "no-process-env": "warn" }`.
|
|
591
815
|
|
|
816
|
+
`adamantite/rules/plugin` re-exports the helpers and types from Adamantite's pinned
|
|
817
|
+
`@oxlint/plugins` dependency. Use `definePlugin` from that module if you write a plugin
|
|
818
|
+
that you register in `jsPlugins` yourself. You do not need to add `@oxlint/plugins` to your project.
|
|
819
|
+
|
|
820
|
+
Optional saved RuleTester tests use `node:test`. Exclude them from Vitest or Jest discovery
|
|
821
|
+
so those runners do not also try to run them. Keep the runner's default and existing
|
|
822
|
+
exclusions. For Vitest:
|
|
823
|
+
|
|
824
|
+
```ts
|
|
825
|
+
// vitest.config.ts
|
|
826
|
+
import { configDefaults, defineConfig } from "vitest/config"
|
|
827
|
+
|
|
828
|
+
export default defineConfig({
|
|
829
|
+
test: {
|
|
830
|
+
exclude: [...configDefaults.exclude, ".adamantite/lint/**/*.test.*"],
|
|
831
|
+
},
|
|
832
|
+
})
|
|
833
|
+
```
|
|
834
|
+
|
|
835
|
+
For Jest:
|
|
836
|
+
|
|
837
|
+
```js
|
|
838
|
+
// jest.config.mjs
|
|
839
|
+
export default {
|
|
840
|
+
testPathIgnorePatterns: ["/node_modules/", "<rootDir>/.adamantite/lint/"],
|
|
841
|
+
}
|
|
842
|
+
```
|
|
843
|
+
|
|
844
|
+
For another rules folder or a custom test `--path`, use its path in the exclusion. To
|
|
845
|
+
type-check tests that import `.ts` rule files, enable `compilerOptions.allowImportingTsExtensions`
|
|
846
|
+
in `tsconfig.json`. To check the hidden rules folder too, add `.adamantite/lint` to `include`.
|
|
847
|
+
|
|
848
|
+
To keep an existing `.adamantite/rules` folder, set `custom({ dir: ".adamantite/rules" })`
|
|
849
|
+
and use `rule add --dir .adamantite/rules`. You can instead move the folder to
|
|
850
|
+
`.adamantite/lint`. The previous `adamantite/lint/custom` import and named authoring imports
|
|
851
|
+
from `adamantite/rules` are removed. Import `custom` from `adamantite/rules` and the
|
|
852
|
+
authoring helpers and types from `adamantite/rules/plugin`. Run `adamantite doctor` for
|
|
853
|
+
migration instructions. Doctor reports the old imports and default folder without changing files.
|
|
854
|
+
|
|
592
855
|
Rule files run with Node.js type stripping, so use erasable TypeScript only: no `enum`,
|
|
593
856
|
`namespace` with values, or parameter properties. Rules get no type information. A rule
|
|
594
857
|
that throws prints an error for each file, and the lint run still exits 0. Adamantite owns
|
|
595
|
-
the wiring and the authoring guidance; your project owns the correctness
|
|
596
|
-
|
|
597
|
-
|
|
858
|
+
the wiring and the authoring guidance; your project owns the correctness of its rules.
|
|
859
|
+
Agents use `RuleTester` from `adamantite/rules/testing` to verify new and changed rules.
|
|
860
|
+
They run valid and invalid cases from stdin or a temporary file with Node.js, also in Bun
|
|
861
|
+
projects, and remove their temporary verification cases and fixtures before handback. The rules and their
|
|
862
|
+
runtime helpers stay in the target project. The "Custom rules" section of the
|
|
863
|
+
[Adamantite skill](#agent-skill) has the command and the full authoring guidance.
|
|
598
864
|
|
|
599
865
|
`adamantite doctor` reports a rule file that cannot load, with the reason, a rules folder
|
|
600
|
-
that no `custom()` call loads, and two rules folders that use the same plugin name.
|
|
866
|
+
that no `custom()` call loads, and two rules folders that use the same plugin name. It also
|
|
867
|
+
provides migration guidance for old API imports and the previous default rules folder.
|
|
868
|
+
User-owned saved tests and optional CI steps remain supported.
|
|
601
869
|
|
|
602
870
|
### Custom rules in a monorepo
|
|
603
871
|
|
|
@@ -607,7 +875,7 @@ root rules extends the root config:
|
|
|
607
875
|
|
|
608
876
|
```ts
|
|
609
877
|
// packages/web/oxlint.config.ts
|
|
610
|
-
import custom from "adamantite/
|
|
878
|
+
import custom from "adamantite/rules"
|
|
611
879
|
import { defineConfig } from "oxlint"
|
|
612
880
|
import root from "../../oxlint.config.ts"
|
|
613
881
|
|
|
@@ -620,14 +888,15 @@ extends it loads the same rules:
|
|
|
620
888
|
|
|
621
889
|
```ts
|
|
622
890
|
// tooling/lint/index.ts
|
|
623
|
-
import custom from "adamantite/
|
|
891
|
+
import custom from "adamantite/rules"
|
|
624
892
|
|
|
625
893
|
export default custom({ dir: "rules", name: "acme" })
|
|
626
894
|
```
|
|
627
895
|
|
|
628
896
|
Run `adamantite rule add <name> --dir tooling/lint/rules` to add a rule to that folder.
|
|
629
897
|
Doctor starts from the Oxlint config of the root and of each workspace package, and follows
|
|
630
|
-
relative imports and imports of workspace packages to find the `custom()` calls. It
|
|
898
|
+
relative imports, `#` imports, and imports of workspace packages to find the `custom()` calls. It
|
|
899
|
+
resolves them as Node.js does, so run it after you install the dependencies. It resolves
|
|
631
900
|
`dir` and `name` when they are string literals.
|
|
632
901
|
|
|
633
902
|
## Requirements and boundaries
|
|
@@ -647,16 +916,38 @@ relative imports and imports of workspace packages to find the `custom()` calls.
|
|
|
647
916
|
|
|
648
917
|
## Agent skill
|
|
649
918
|
|
|
650
|
-
|
|
651
|
-
|
|
919
|
+
The Adamantite skill teaches coding agents how to initialize, assess, repair, and update a
|
|
920
|
+
project, and how to write [custom rules](#custom-rules). The Adamantite package ships it.
|
|
921
|
+
|
|
922
|
+
`adamantite init` asks whether to set up coding agents. When you answer yes, or pass
|
|
923
|
+
`--agents` in non-interactive mode, init adds the Adamantite section to `AGENTS.md` and writes
|
|
924
|
+
the skill to these folders:
|
|
925
|
+
|
|
926
|
+
| Skill folder | Agents | When |
|
|
927
|
+
| ---------------- | --------------------------------------- | --------------------------- |
|
|
928
|
+
| `.agents/skills` | Codex, Cursor, Gemini CLI, and OpenCode | Always |
|
|
929
|
+
| `.claude/skills` | Claude Code | The project has `.claude/`. |
|
|
930
|
+
| `.grok/skills` | Grok Build | The project has `.grok/`. |
|
|
931
|
+
|
|
932
|
+
The Adamantite CLI bundles the skill, so the copy matches the Adamantite version that wrote
|
|
933
|
+
it. After you update Adamantite, `adamantite update` writes the skill again to each folder
|
|
934
|
+
whose copy changed. It also removes the `adamantite` entry from `skills-lock.json`, so the
|
|
935
|
+
`skills` CLI does not write the same folders. Commit the skill folders, so every clone has
|
|
936
|
+
the skill.
|
|
937
|
+
|
|
938
|
+
To install the skill from GitHub instead, with the
|
|
939
|
+
[`skills` CLI](https://github.com/vercel-labs/skills):
|
|
652
940
|
|
|
653
941
|
```sh
|
|
654
942
|
npx skills add adelrodriguez/adamantite --list
|
|
655
943
|
npx skills add adelrodriguez/adamantite --skill adamantite
|
|
656
944
|
```
|
|
657
945
|
|
|
658
|
-
|
|
659
|
-
|
|
946
|
+
`adamantite update` replaces a copy from GitHub with the skill of the installed Adamantite
|
|
947
|
+
version.
|
|
948
|
+
|
|
949
|
+
With pnpm 12.11 or later, `pnpm install` can also link the skill that the package ships
|
|
950
|
+
into the agent skill directories that exist in the project, such as `.claude/skills`,
|
|
660
951
|
after you approve it. pnpm creates the directory only when the agent that runs pnpm sets an
|
|
661
952
|
environment variable that identifies it, such as `CLAUDECODE` for `.claude/skills`.
|
|
662
953
|
Otherwise, if no skill directory exists, the install fails, so create one before you
|